agent-assembly 0.0.2__py3-none-any.whl

agent_assembly/__init__.py

@@ -0,0 +1,122 @@
+"""Agent Assembly Python SDK."""
+
+from __future__ import annotations
+
+import contextlib
+import importlib
+import importlib.util
+import sys
+from typing import TYPE_CHECKING, Any
+
+__version__ = "0.0.1a2"
+
+# AAASM-1696: top-level exports are resolved lazily so that lightweight
+# submodules (e.g. `agent_assembly.runtime`, which is stdlib-only) can be
+# imported without dragging in the SDK's third-party dependency surface
+# (`httpx`, `pydantic`, …). See PEP 562.
+_LAZY_EXPORTS: dict[str, str] = {
+    "init_assembly": "agent_assembly.core",
+    "AssemblyContext": "agent_assembly.core",
+    "GovernanceInterceptor": "agent_assembly.adapters",
+    "FrameworkAdapter": "agent_assembly.adapters",
+    "AssemblyError": "agent_assembly.exceptions",
+    "AgentError": "agent_assembly.exceptions",
+    "PolicyError": "agent_assembly.exceptions",
+    "GatewayError": "agent_assembly.exceptions",
+    "ConfigurationError": "agent_assembly.exceptions",
+    "AdapterValidationError": "agent_assembly.exceptions",
+    "ToolExecutionBlockedError": "agent_assembly.exceptions",
+    "MCPToolBlockedError": "agent_assembly.exceptions",
+    "AuditEvent": "agent_assembly.types",
+    "CallStackNode": "agent_assembly.types",
+    "CallStackNodeKind": "agent_assembly.types",
+    "GovernanceEvent": "agent_assembly._core",
+    "PolicyResult": "agent_assembly._core",
+    "PolicyTimeoutError": "agent_assembly._core",
+    "RuntimeClient": "agent_assembly._core",
+}
+
+_ALWAYS_EXPORTED: list[str] = [
+    "__version__",
+    "init_assembly",
+    "AssemblyContext",
+    "GovernanceInterceptor",
+    "FrameworkAdapter",
+    "AssemblyError",
+    "AgentError",
+    "PolicyError",
+    "GatewayError",
+    "ConfigurationError",
+    "AdapterValidationError",
+    "ToolExecutionBlockedError",
+    "MCPToolBlockedError",
+    "AuditEvent",
+    "CallStackNode",
+    "CallStackNodeKind",
+]
+
+_OPTIONAL_CORE: list[str] = [
+    "RuntimeClient",
+    "GovernanceEvent",
+    "PolicyResult",
+    "PolicyTimeoutError",
+]
+
+
+def _core_available() -> bool:
+    if "agent_assembly._core" in sys.modules:
+        return True
+    try:
+        return importlib.util.find_spec("agent_assembly._core") is not None
+    except (ModuleNotFoundError, ValueError):
+        return False
+
+
+__all__: list[str] = list(_ALWAYS_EXPORTED)
+if _core_available():
+    __all__.extend(_OPTIONAL_CORE)
+
+
+def __getattr__(name: str) -> Any:
+    module_name = _LAZY_EXPORTS.get(name)
+    if module_name is None:
+        raise AttributeError(f"module 'agent_assembly' has no attribute {name!r}")
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError:
+        if module_name == "agent_assembly._core":
+            raise AttributeError(
+                f"module 'agent_assembly' has no attribute {name!r}: the native '_core' extension is not built"
+            ) from None
+        raise
+    value = getattr(module, name)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(set(__all__) | set(globals()))
+
+
+if TYPE_CHECKING:
+    from agent_assembly.adapters import FrameworkAdapter, GovernanceInterceptor
+    from agent_assembly.core import AssemblyContext, init_assembly
+    from agent_assembly.exceptions import (
+        AdapterValidationError,
+        AgentError,
+        AssemblyError,
+        ConfigurationError,
+        GatewayError,
+        MCPToolBlockedError,
+        PolicyError,
+        ToolExecutionBlockedError,
+    )
+    from agent_assembly.types import AuditEvent, CallStackNode, CallStackNodeKind
+
+    with contextlib.suppress(ImportError):
+        from agent_assembly._core import (
+            GovernanceEvent,
+            PolicyResult,
+            PolicyTimeoutError,
+            RuntimeClient,
+        )

agent_assembly/_install.py

@@ -0,0 +1,56 @@
+"""Install-time runtime binary resolution for the agent-assembly Python SDK.
+
+This module is the lean, blocking presence check for the ``aasm`` sidecar
+binary. It is intentionally separate from :mod:`agent_assembly.runtime`,
+which manages the full lifecycle (port probe + subprocess spawn). The
+intended use is at import time or at the start of long-running scripts:
+fail fast with a clear install hint when the binary is unavailable, before
+the user discovers it via a subtle subprocess failure deep in the SDK call.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+__all__ = [
+    "BINARY_NAME",
+    "INSTALL_HINT",
+    "WHEEL_BUNDLED_BIN",
+    "ensure_runtime",
+]
+
+BINARY_NAME = "aasm"
+
+# Path where the platform-wheel ([runtime] extra) bundles the sidecar binary.
+# Mirrors the location runtime.py's find_aasm_binary() also searches, so
+# both modules observe the same wheel artifact without coordination.
+WHEEL_BUNDLED_BIN = Path(__file__).resolve().parent / "bin" / BINARY_NAME
+
+INSTALL_HINT = (
+    "agent-assembly runtime binary `aasm` was not found.\n"
+    "  Install the platform wheel: pip install agent-assembly[runtime]\n"
+    "  Or install manually:        brew install agent-assembly/tap/aasm\n"
+    "                              curl -fsSL https://get.agent-assembly.io | sh"
+)
+
+
+def ensure_runtime() -> Path:
+    """Return the resolved path to the ``aasm`` sidecar binary.
+
+    Search order, fast to slow:
+
+    1. ``$PATH`` (Homebrew tap, ``cargo install``, ``curl`` installer default).
+    2. ``agent_assembly/bin/aasm`` bundled by the ``[runtime]`` platform wheel.
+
+    Raises:
+        RuntimeError: when no binary is found on either path. The message
+            carries :data:`INSTALL_HINT` with copy-paste install commands.
+    """
+    path_hit = shutil.which(BINARY_NAME)
+    if path_hit:
+        return Path(path_hit)
+    if WHEEL_BUNDLED_BIN.is_file() and os.access(WHEEL_BUNDLED_BIN, os.X_OK):
+        return WHEEL_BUNDLED_BIN
+    raise RuntimeError(INSTALL_HINT)

agent_assembly/adapters/__init__.py

@@ -0,0 +1,4 @@
+from agent_assembly.adapters.base import FrameworkAdapter, GovernanceInterceptor
+from agent_assembly.adapters.registry import AdapterInfo, AdapterRegistry
+
+__all__ = ["GovernanceInterceptor", "FrameworkAdapter", "AdapterInfo", "AdapterRegistry"]

agent_assembly/adapters/base.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import importlib
+from abc import ABC, abstractmethod
+from typing import Protocol
+
+from agent_assembly.exceptions import AdapterValidationError
+
+
+class GovernanceInterceptor(Protocol):
+    """Protocol implemented by governance interceptors used by adapters."""
+
+
+class FrameworkAdapter(ABC):
+    """Abstract contract implemented by every framework adapter.
+
+    This is the **public adapter API** — the interface that SDK users and
+    third-party plugin authors interact with.  Each concrete adapter represents
+    one AI framework (e.g. LangChain, CrewAI) and knows how to install
+    governance hooks for that framework.
+
+    The two key lifecycle methods are:
+
+    - ``register_hooks(interceptor)`` — install framework-specific
+      monkey-patches that route intercepted calls through the governance
+      interceptor.  Internally, each adapter delegates to one or more
+      ``RuntimePatch`` instances whose ``apply()`` method performs the
+      actual monkey-patching.
+
+    - ``unregister_hooks()`` — tear down all patches installed by this
+      adapter, delegating to each patch's ``revert()`` method.
+
+    Adapters are discovered and activated by ``AdapterRegistry.auto_detect()``
+    which is the single detection path used by ``init_assembly()``.
+
+    Adapters should be registered through ``register()`` so contract
+    validation errors are raised before framework hooks are attached.
+
+    See Also:
+        ``RuntimePatch`` in ``core/assembly.py`` — the internal
+        monkey-patch protocol with ``apply()`` / ``revert()`` methods.
+        ADR-0001 (``docs/adr/0001-hook-architecture.md``) for the full
+        architecture rationale.
+    """
+
+    @abstractmethod
+    def get_framework_name(self) -> str:
+        """Return the canonical importable framework package name.
+
+        Error conditions:
+        - Empty or whitespace-only names trigger `AdapterValidationError`
+          during `register()`.
+        """
+
+        ...
+
+    @abstractmethod
+    def get_supported_versions(self) -> list[str]:
+        """Return supported semantic version ranges for the framework.
+
+        Error conditions:
+        - Empty lists or empty range strings trigger `AdapterValidationError`
+          during `register()`.
+        """
+
+        ...
+
+    @abstractmethod
+    def register_hooks(self, interceptor: GovernanceInterceptor) -> None:
+        """Attach framework hooks to a governance interceptor instance.
+
+        Error conditions:
+        - Framework-specific hook wiring failures should raise adapter-specific
+          exceptions for the caller to handle.
+        """
+
+        ...
+
+    @abstractmethod
+    def unregister_hooks(self) -> None:
+        """Detach all framework hooks in an idempotent way.
+
+        Error conditions:
+        - This method should avoid raising when no hooks are currently active.
+        """
+
+        ...
+
+    def validate_registration(self) -> None:
+        """Validate adapter contract values before hook registration.
+
+        Raises:
+            AdapterValidationError: If the framework name or version ranges
+                violate the base adapter contract.
+        """
+        framework_name = self.get_framework_name()
+        if not framework_name.strip():
+            raise AdapterValidationError("Adapter contract invalid: framework name must be non-empty.")
+
+        supported_versions = self.get_supported_versions()
+        if not supported_versions:
+            raise AdapterValidationError("Adapter contract invalid: supported versions must not be empty.")
+
+        for version_range in supported_versions:
+            if not version_range.strip():
+                raise AdapterValidationError("Adapter contract invalid: version ranges must be non-empty strings.")
+
+    def register(self, interceptor: GovernanceInterceptor) -> None:
+        """Validate contract values and then attach framework hooks.
+
+        Raises:
+            AdapterValidationError: If `validate_registration()` fails.
+        """
+        self.validate_registration()
+        self.register_hooks(interceptor)
+
+    def is_available(self) -> bool:
+        """Return True when the framework package can be imported.
+
+        Error conditions:
+        - Import failures are handled internally and return `False`.
+        """
+
+        try:
+            importlib.import_module(self.get_framework_name())
+        except ImportError:
+            return False
+
+        return True
+
+    def set_process_agent_id(self, agent_id: str | None) -> None:
+        """Set the process-level agent ID for governance event attribution.
+
+        Adapters that need an agent ID (e.g. LangChain, OpenAI Agents, MCP)
+        override ``process_agent_id`` as a property.  This base method is
+        a no-op for adapters that do not use an agent ID.
+        """
+        if hasattr(self, "process_agent_id"):
+            self.process_agent_id = agent_id
+
+    def get_active_version(self) -> str | None:
+        """Return framework `__version__` when present, otherwise `None`.
+
+        Error conditions:
+        - Import failures and missing/non-string `__version__` values return
+          `None`.
+        """
+
+        try:
+            module = importlib.import_module(self.get_framework_name())
+        except ImportError:
+            return None
+
+        version = getattr(module, "__version__", None)
+        if isinstance(version, str):
+            return version
+
+        return None

agent_assembly/adapters/crewai/__init__.py

@@ -0,0 +1,6 @@
+"""CrewAI adapter package."""
+
+from agent_assembly.adapters.crewai.adapter import CrewAIAdapter
+from agent_assembly.adapters.crewai.patch import CrewAIPatch
+
+__all__ = ["CrewAIAdapter", "CrewAIPatch"]

agent_assembly/adapters/crewai/adapter.py

@@ -0,0 +1,28 @@
+"""CrewAI framework adapter."""
+
+from __future__ import annotations
+
+from agent_assembly.adapters.base import FrameworkAdapter, GovernanceInterceptor
+from agent_assembly.adapters.crewai.patch import CrewAIPatch
+
+
+class CrewAIAdapter(FrameworkAdapter):
+    """Adapter for CrewAI framework governance hook installation."""
+
+    def __init__(self) -> None:
+        self._patch: CrewAIPatch | None = None
+
+    def get_framework_name(self) -> str:
+        return "crewai"
+
+    def get_supported_versions(self) -> list[str]:
+        return [">=0.1.0"]
+
+    def register_hooks(self, interceptor: GovernanceInterceptor) -> None:
+        self._patch = CrewAIPatch(interceptor)
+        self._patch.apply()
+
+    def unregister_hooks(self) -> None:
+        if self._patch is not None:
+            self._patch.revert()
+            self._patch = None