[AAASM-193] ♻️ adapters: Reconcile hook architecture into single canonical path#16
Merged
Chisanan232 merged 23 commits intoMay 1, 2026
Merged
Conversation
Documents the canonical hook architecture: Python owns monkey-patching and hook installation, Rust owns IPC transport. Architecture B (Rust-side hook dispatch) was superseded by AAASM-162. Refs AAASM-193 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
… adapter contract Explains the two-level naming: register_hooks()/unregister_hooks() is the public API, apply()/revert() is the internal RuntimePatch mechanism. References ADR-0001. Refs AAASM-193 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…mechanism role Explains that RuntimePatch with apply()/revert() is the internal monkey-patch mechanism, distinct from the public FrameworkAdapter API. References ADR-0001. Refs AAASM-193 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Wraps existing LangChainPatch with the public FrameworkAdapter API. register_hooks() creates and applies the patch, unregister_hooks() reverts it. Exposes get_callback_handler() for downstream adapters. Refs AAASM-193 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Wraps existing LangGraphPatch with the public FrameworkAdapter API. Refs AAASM-193 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Wraps existing CrewAIPatch with the public FrameworkAdapter API. Refs AAASM-193 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Wraps existing PydanticAIPatch with the public FrameworkAdapter API. Refs AAASM-193 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Wraps existing OpenAIAgentsPatch with the public FrameworkAdapter API. Overrides is_available() to check for openai.agents module specifically. Refs AAASM-193 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Wraps existing MCPClientPatch with the public FrameworkAdapter API. Refs AAASM-193 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…lasses Swap placeholder stubs for LangChainAdapter, LangGraphAdapter, CrewAIAdapter, and PydanticAIAdapter in AdapterRegistry.__init__(). Refs AAASM-193 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…adapters Previously missing from registry — now all 6 framework adapters are registered as builtins. Refs AAASM-193 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…s_by_priority LangChain must be first (callback handler threading), MCP must be last (fallback). New method returns available adapters in priority order without calling register_hooks() — init_assembly() handles that. Refs AAASM-193 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Allows init_assembly() to propagate the agent ID to adapters that need it without knowing which adapters require it. No-op for adapters without a process_agent_id property. Refs AAASM-193 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…tection path Replace _build_patch_plan() with AdapterRegistry.get_available_adapters_by_priority(). AssemblyContext now holds adapters instead of patches. Shutdown calls adapter.unregister_hooks() instead of patch.revert(). Remove dead code: _build_patch_plan, _is_installed, _has_agents_sdk, _apply_runtime_patches, _revert_patches, _replace_callback_targets. Refs AAASM-193 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…ter classes All six adapter packages now export their FrameworkAdapter subclass alongside the existing patch class. Refs AAASM-193 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace all references to removed functions (_apply_runtime_patches, _revert_patches, _build_patch_plan) with new adapter-based equivalents. Change context.patches to context.adapters throughout. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
find_spec("openai.agents") raises ModuleNotFoundError when the
openai package is not installed at all. Catch the exception so
is_available() returns False gracefully.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Rename test to reflect that builtin registry keys now match get_framework_name() directly, since real adapter classes replaced placeholder stubs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace monkeypatched _is_installed with _register_adapters to match the new adapter-based init_assembly flow. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Document the end-to-end integration status for all six framework adapters, confirming each is fully wired through the canonical FrameworkAdapter → RuntimePatch → interceptor path. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Auto-formatted by pre-commit hooks: import reordering and style adjustments across adapters, tests, and examples. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The import is used as a monkeypatch target by tests — add noqa to prevent ruff from removing it again. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Remove unused type: ignore comment in base.py, add type annotations to test_runtime.py monkeypatch parameters, apply remaining linter formatting. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Codecov Report❌ Patch coverage is 📢 Thoughts on this report? Let us know! |
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Reconciles the Python SDK's hook architecture by creating real
FrameworkAdaptersubclasses for all six frameworks and routinginit_assembly()throughAdapterRegistryas the single detection path. Documents the canonical architecture in ADR-0001.What changed
LangChainAdapter,LangGraphAdapter,CrewAIAdapter,PydanticAIAdapter,OpenAIAgentsAdapter, andMCPAdapter— each wrapping its correspondingRuntimePatchclass._BuiltinPlaceholderAdapterstubs with real adapter classes. Added priority ordering (get_available_adapters_by_priority()) with LangChain first (callback handler threading) and MCP last (fallback)._register_adapters()which goes throughAdapterRegistry— eliminating the parallel detection path (_build_patch_plan,_is_installed,_has_agents_sdk).AssemblyContext.patchesrenamed toAssemblyContext.adapters.test_assembly.py,test_registry.py, andtest_runtime.pyto match the new adapter-based architecture.Why
AAASM-193 (Epic AAASM-5) identified a naming inconsistency between the public adapter API (
register_hooks/unregister_hooks) and the internal patch mechanism (apply/revert), plus a dual detection path whereinit_assembly()bypassedAdapterRegistry. This PR resolves both by making the registry the single canonical detection path and adding docstrings that clarify the two-level naming convention.Type of Change
Breaking Changes
AssemblyContext.patchesrenamed toAssemblyContext.adapters(internal API, not public)_build_patch_plan,_is_installed,_has_agents_sdk,_apply_runtime_patches,_revert_patchesRelated Issues
Closes AAASM-193 (Epic: AAASM-5)
Testing
Checklist