API Reference¶

The amplifier-foundation API is fully documented via Python docstrings and type hints. This overview lists what's exported; for details, read the source files directly.

Why this approach? Documentation that duplicates code becomes context poisoning when it drifts. The code IS the authoritative reference.

Quick Import¶

from amplifier_foundation import Bundle, BundleRegistry, load_bundle

Core Classes¶

Export	Source	Purpose
`Bundle`	`bundle/__init__.py`	Composable unit with mount plan config
`SessionConfigurator`	`configurator.py`	Runtime session configuration
`BundleRegistry`	`registry.py`	Named bundle management and loading
`BundleValidator`	`validator.py`	Bundle structure validation
`ValidationResult`	`validator.py`	Validation result with errors/warnings
`BundleState`	`registry.py`	Tracked state for loaded bundles
`UpdateInfo`	`registry.py`	Available update information

Bundle Package¶

The amplifier_foundation.bundle sub-package exports additional classes used for bundle preparation and module resolution:

from amplifier_foundation.bundle import PreparedBundle, BundleModuleResolver, BundleModuleSource

Export	Source	Purpose
`Bundle`	`bundle/_dataclass.py`	Composable unit (also exported at top level)
`PreparedBundle`	`bundle/_prepared.py`	Compiled bundle ready for session use
`BundleModuleResolver`	`bundle/_prepared.py`	Resolves module paths within a bundle
`BundleModuleSource`	`bundle/_prepared.py`	Represents a module source within a bundle

Convenience Functions¶

Export	Source	Purpose
`load_bundle`	`registry.py`	Load bundle from URI
`validate_bundle`	`validator.py`	Validate bundle, return result
`validate_bundle_or_raise`	`validator.py`	Validate bundle, raise on error

Exceptions¶

Export	Source	Purpose
`BundleError`	`exceptions.py`	Base exception
`BundleNotFoundError`	`exceptions.py`	Bundle not found
`BundleLoadError`	`exceptions.py`	Bundle load/parse failed
`BundleValidationError`	`exceptions.py`	Validation failed
`BundleDependencyError`	`exceptions.py`	Dependency resolution failed

Protocols¶

Export	Source	Purpose
`MentionResolverProtocol`	`mentions/protocol.py`	@mention resolution contract
`SourceResolverProtocol`	`sources/protocol.py`	URI resolution contract
`SourceHandlerProtocol`	`sources/protocol.py`	Source type handler contract
`SourceHandlerWithStatusProtocol`	`sources/protocol.py`	Source handler with status support
`SourceStatus`	`sources/protocol.py`	Source status enum
`CacheProviderProtocol`	`cache/protocol.py`	Cache provider contract

Reference Implementations¶

Export	Source	Purpose
`BaseMentionResolver`	`mentions/resolver.py`	Default @mention resolver
`SimpleSourceResolver`	`sources/resolver.py`	Git/file source resolver
`SimpleCache`	`cache/simple.py`	In-memory cache
`DiskCache`	`cache/disk.py`	Persistent disk cache

Mentions¶

Export	Source	Purpose
`parse_mentions`	`mentions/parser.py`	Extract @mentions from text
`load_mentions`	`mentions/loader.py`	Load @mention content (async)
`ContentDeduplicator`	`mentions/deduplicator.py`	SHA-256 content deduplication
`ContextFile`	`mentions/models.py`	Loaded context file data
`MentionResult`	`mentions/models.py`	@mention resolution result

I/O Utilities¶

Export	Source	Purpose
`read_yaml`	`io/yaml.py`	Read YAML file (async)
`write_yaml`	`io/yaml.py`	Write YAML file (async)
`parse_frontmatter`	`io/frontmatter.py`	Parse YAML frontmatter
`read_with_retry`	`io/files.py`	Read with cloud sync retry (async)
`write_with_retry`	`io/files.py`	Write with cloud sync retry (async)
`write_with_backup`	`io/files.py`	Write with backup (async)

Dict Utilities¶

Export	Source	Purpose
`deep_merge`	`dicts/merge.py`	Deep merge dictionaries
`merge_module_lists`	`dicts/merge.py`	Merge module lists by ID
`get_nested`	`dicts/navigation.py`	Get nested dict value by path
`set_nested`	`dicts/navigation.py`	Set nested dict value by path

Path Utilities¶

Export	Source	Purpose
`parse_uri`	`paths/resolution.py`	Parse source URI
`ParsedURI`	`paths/resolution.py`	Parsed URI dataclass
`normalize_path`	`paths/resolution.py`	Normalize/resolve path
`construct_agent_path`	`paths/construction.py`	Build agent file path
`construct_context_path`	`paths/construction.py`	Build context file path
`find_files`	`paths/discovery.py`	Find files by pattern (async)
`find_bundle_root`	`paths/discovery.py`	Find bundle root upward (async)

Session Capabilities¶

Export	Source	Purpose
`get_working_dir`	`session/capabilities.py`	Get session working directory from coordinator
`set_working_dir`	`session/capabilities.py`	Update session working directory dynamically
`WORKING_DIR_CAPABILITY`	`session/capabilities.py`	Capability name constant (`"session.working_dir"`)

Spawn Utilities¶

Utilities for spawning sub-sessions with provider/model preferences.

Export	Source	Purpose
`ProviderPreference`	`spawn_utils.py`	Dataclass for provider/model preference (supports glob patterns)
`ModelResolutionResult`	`spawn_utils.py`	Result of model pattern resolution
`apply_provider_preferences`	`spawn_utils.py`	Apply ordered preferences to mount plan
`apply_provider_preferences_with_resolution`	`spawn_utils.py`	Apply preferences with resolution result
`resolve_model_pattern`	`spawn_utils.py`	Resolve glob patterns (e.g., `claude-haiku-*`) to concrete model names
`is_glob_pattern`	`spawn_utils.py`	Check if model string contains glob characters

Cost Bridge Utilities¶

Utilities for propagating child-session costs to parent coordinators in app-layer spawn wrappers. Import via from amplifier_foundation import ....

Export	Source	Purpose
`bridge_child_cost`	`bundle/_prepared.py`	Collect child session's `session.cost` contributions and register them as a single contributor on the parent coordinator. Never raises — errors are logged as warnings.
`sum_cost_usd`	`bundle/_prepared.py`	Sum a list of `collect_contributions()` results into a single `Decimal \\| None`. Returns `None` when no cost data is present. Tolerates both `Decimal` and `str` values.

Subprocess Runner¶

Export	Source	Purpose
`run_session_in_subprocess`	`subprocess_runner.py`	Run a session as an isolated subprocess

Serialization Utilities¶

Export	Source	Purpose
`sanitize_for_json`	`serialization.py`	Sanitize values for JSON serialization
`sanitize_message`	`serialization.py`	Sanitize message for logging

Tracing Utilities¶

Export	Source	Purpose
`generate_sub_session_id`	`tracing.py`	Generate sub-session ID from parent

Updates¶

Export	Source	Purpose
`BundleStatus`	`updates.py`	Bundle status dataclass
`check_bundle_status`	`updates.py`	Check for bundle updates
`update_bundle`	`updates.py`	Update bundle to latest version

Reading the Source¶

Each source file has comprehensive docstrings. To read them:

# In your editor
code amplifier_foundation/bundle/__init__.py

# Or via Python
python -c "from amplifier_foundation import Bundle; help(Bundle)"

# Or via pydoc
python -m pydoc amplifier_foundation.Bundle

Common Patterns¶

Load and Use a Bundle¶

from amplifier_foundation import load_bundle

bundle = await load_bundle("git+https://github.com/org/my-bundle@main")
mount_plan = bundle.to_mount_plan()

Compose Bundles¶

from amplifier_foundation import load_bundle

base = await load_bundle("foundation")
overlay = await load_bundle("./local-overlay.md")
composed = base.compose(overlay)

Registry Management¶

from amplifier_foundation import BundleRegistry

registry = BundleRegistry()
registry.register({"my-bundle": "git+https://github.com/org/bundle@main"})
bundle = await registry.load("my-bundle")

Load @Mentions¶

from amplifier_foundation import load_mentions, BaseMentionResolver

resolver = BaseMentionResolver(bundles={"foundation": foundation_bundle})
results = await load_mentions("See @foundation:context/guidelines.md", resolver)