agent-assembly 0.0.1a4__tar.gz

agent_assembly-0.0.1a4/LICENSE

@@ -0,0 +1,22 @@
+
+MIT License
+
+Copyright (c) 2025 Bryant Liu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_assembly-0.0.1a4/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: agent-assembly
+Version: 0.0.1a4
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: pydantic>=2.0.0,<3.0.0
+Requires-Dist: httpx>=0.27.0,<1.0.0
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: grpcio>=1.66,<2
+Requires-Dist: protobuf>=5,<8
+Requires-Dist: agent-assembly[runtime] ; extra == 'all'
+Provides-Extra: all
+Provides-Extra: runtime
+License-File: LICENSE
+Summary: Python SDK for AI Agent Assembly - A governance-native runtime for AI agents
+Keywords: ai-agent,governance,mcp,assembly,runtime,policy
+Author-email: Agent Assembly Team <team@agent-assembly.dev>
+Requires-Python: >=3.12, <4.0
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/agent-assembly/python-sdk
+Project-URL: Repository, https://github.com/agent-assembly/python-sdk
+
+# Agent Assembly Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/agent-assembly.svg)](https://pypi.org/project/agent-assembly/)
+[![Python versions](https://img.shields.io/pypi/pyversions/agent-assembly.svg)](https://pypi.org/project/agent-assembly/)
+[![CI](https://github.com/AI-agent-assembly/python-sdk/actions/workflows/ci.yaml/badge.svg?branch=master)](https://github.com/AI-agent-assembly/python-sdk/actions/workflows/ci.yaml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+Python SDK for **AI Agent Assembly** — a governance-native runtime for AI agents. One `init_assembly()` call wires your agent into the policy gateway, applies pre-execution allow/deny on tool calls, and emits audit events without changing how the agent itself is written.
+
+## Why use it
+
+- **Framework adapters** for LangChain, LangGraph, CrewAI, OpenAI Agents, Pydantic AI, and MCP servers — drop in, no SDK rewrites required.
+- **Pre-execution policy enforcement** via the `FrameworkAdapter` ABC — block disallowed tool calls before they hit the LLM.
+- **Audit trail** — every tool call, prompt, and policy decision is emitted to the gateway with full agent lineage (parent / root / team).
+- **Native PyO3 fast path** (optional) — drop into a Rust runtime client when you need sub-millisecond policy checks.
+- **Typed throughout** — Pydantic models for every gateway payload, mypy strict on adapter base and registry.
+
+## Requirements
+
+- **Python** `>=3.12,<4.0` (3.12, 3.13, 3.14 are tested in CI)
+- **Rust toolchain** (stable channel) — only required for building the optional native extension via `maturin develop`. Pure-Python users do not need Rust.
+- **uv** ≥ 0.4 — recommended for managing the dev environment. (`pip` works for plain installs.)
+
+## Installation
+
+### Use the SDK in your project
+
+```bash
+pip install agent-assembly
+```
+
+(Once published to PyPI. Until then, install directly from GitHub:)
+
+```bash
+pip install git+https://github.com/AI-agent-assembly/python-sdk.git
+```
+
+### Develop on the SDK
+
+Clone the repo and sync the dev environment with `uv`:
+
+```bash
+git clone https://github.com/AI-agent-assembly/python-sdk.git
+cd python-sdk
+uv sync
+```
+
+To build the optional PyO3 extension locally (requires Rust):
+
+```bash
+uv tool run maturin develop --manifest-path rust/aa-ffi-python/Cargo.toml --release
+```
+
+The pure-Python SDK works without the native extension — `maturin develop` is only needed if you want the sub-millisecond `RuntimeClient` fast path.
+
+## Quick Start
+
+A governed LangChain ReAct agent that runs offline against a mock LLM. The example imports LangChain in addition to the SDK, so install both:
+
+```bash
+pip install agent-assembly langchain langchain-community
+```
+
+```python
+from langchain.agents import AgentExecutor, create_react_agent
+from langchain.tools import Tool
+from langchain_community.llms import FakeListLLM
+from langchain_core.prompts import PromptTemplate
+
+from agent_assembly import init_assembly
+
+with init_assembly(
+    gateway_url="http://localhost:8080",
+    api_key="dev-key",
+    agent_id="quickstart-agent",
+    mode="sdk-only",
+):
+    llm = FakeListLLM(responses=[
+        "Thought: I should look up the user.\nAction: whoami\nAction Input: alice\n",
+        "Thought: I have the answer.\nFinal Answer: alice is in engineering\n",
+    ])
+    tools = [Tool(name="whoami", func=lambda name: f"{name} is in engineering", description="who")]
+    prompt = PromptTemplate.from_template(
+        "Use the tools.\n{tools}\nTool names: {tool_names}\nQ: {input}\n{agent_scratchpad}"
+    )
+    executor = AgentExecutor(agent=create_react_agent(llm, tools, prompt), tools=tools, max_iterations=2)
+    print(executor.invoke({"input": "Which team is alice on?"})["output"])
+```
+
+What this does:
+
+1. `init_assembly()` registers the agent with the gateway and auto-loads the LangChain adapter — every tool call from now on goes through the policy gate.
+2. The `FakeListLLM` replays canned responses so the example runs **offline** with no real LLM.
+3. The `with` block tears down the gateway connection and unwinds adapter hooks on exit.
+
+## Public API
+
+- `init_assembly(gateway_url, api_key, agent_id=None, mode="auto") -> AssemblyContext`
+- `GatewayClient.register_agent() -> dict`
+- `GatewayClient.check_policy_compliance(action: str) -> dict`
+- Exceptions: `AssemblyError`, `AgentError`, `PolicyError`, `GatewayError`, `ConfigurationError`
+- Data models: `AgentConfig`, `AgentState`, `PolicyEvaluation`
+
+## Error Handling
+
+```python
+from agent_assembly import init_assembly
+from agent_assembly.exceptions import ConfigurationError
+
+try:
+    context = init_assembly(gateway_url="", api_key="my-api-key", agent_id="my-agent-001")
+except ConfigurationError as exc:
+    print(f"Invalid configuration: {exc}")
+```
+
+## Development
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+Run integration tests:
+
+```bash
+uv run pytest -m integration
+```
+
+Lint and type-check:
+
+```bash
+uv run ruff check .
+uv run mypy agent_assembly
+```
+
+## Native Core Extension (AAASM-55)
+
+Build and install the PyO3 extension locally:
+
+```bash
+uv tool run maturin develop --manifest-path rust/aa-ffi-python/Cargo.toml --release
+```
+
+Validate native module import:
+
+```python
+from agent_assembly._core import RuntimeClient, GovernanceEvent, PolicyResult
+```
+
+Run opt-in native integration tests:
+
+```bash
+AAASM_RUN_NATIVE_CORE_TESTS=1 uv run pytest test/integration/test_native_core_runtime.py
+AAASM_RUN_MATURIN_TESTS=1 uv run pytest test/integration/test_native_core_maturin.py
+```
+
+## Documentation
+
+- **Project docs (rendered)** — https://ai-agent-assembly.github.io/python-sdk/ *(versioned via `mike`; pick `latest` or `stable` from the version selector)*
+- **Architecture** — [rendered](https://ai-agent-assembly.github.io/python-sdk/latest/architecture/) / [source](./docs/architecture/index.md) — adapter pattern, PyO3 FFI, `init_assembly()` lifecycle, with a Mermaid flow diagram.
+- **API reference** — [rendered](https://ai-agent-assembly.github.io/python-sdk/latest/api-reference/) / [source](./docs/api-reference/index.md) — auto-generated from package docstrings via `mkdocstrings`. Per-module pages: [Client](./docs/api-reference/client.md), [Exceptions](./docs/api-reference/exceptions.md), [Models](./docs/api-reference/models.md).
+- **ADRs** — [`docs/development/adr/`](./docs/development/adr/) (architecture decision records)
+
+## Contributing
+
+Please read [**CONTRIBUTING.md**](./CONTRIBUTING.md) before opening a PR — it covers dev environment setup, framework adapter authoring, the test/lint command list, branch naming, and the PR checklist.
+
+## License
+
+[MIT License](./LICENSE)
+

agent_assembly-0.0.1a4/README.md

@@ -0,0 +1,171 @@
+# Agent Assembly Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/agent-assembly.svg)](https://pypi.org/project/agent-assembly/)
+[![Python versions](https://img.shields.io/pypi/pyversions/agent-assembly.svg)](https://pypi.org/project/agent-assembly/)
+[![CI](https://github.com/AI-agent-assembly/python-sdk/actions/workflows/ci.yaml/badge.svg?branch=master)](https://github.com/AI-agent-assembly/python-sdk/actions/workflows/ci.yaml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+Python SDK for **AI Agent Assembly** — a governance-native runtime for AI agents. One `init_assembly()` call wires your agent into the policy gateway, applies pre-execution allow/deny on tool calls, and emits audit events without changing how the agent itself is written.
+
+## Why use it
+
+- **Framework adapters** for LangChain, LangGraph, CrewAI, OpenAI Agents, Pydantic AI, and MCP servers — drop in, no SDK rewrites required.
+- **Pre-execution policy enforcement** via the `FrameworkAdapter` ABC — block disallowed tool calls before they hit the LLM.
+- **Audit trail** — every tool call, prompt, and policy decision is emitted to the gateway with full agent lineage (parent / root / team).
+- **Native PyO3 fast path** (optional) — drop into a Rust runtime client when you need sub-millisecond policy checks.
+- **Typed throughout** — Pydantic models for every gateway payload, mypy strict on adapter base and registry.
+
+## Requirements
+
+- **Python** `>=3.12,<4.0` (3.12, 3.13, 3.14 are tested in CI)
+- **Rust toolchain** (stable channel) — only required for building the optional native extension via `maturin develop`. Pure-Python users do not need Rust.
+- **uv** ≥ 0.4 — recommended for managing the dev environment. (`pip` works for plain installs.)
+
+## Installation
+
+### Use the SDK in your project
+
+```bash
+pip install agent-assembly
+```
+
+(Once published to PyPI. Until then, install directly from GitHub:)
+
+```bash
+pip install git+https://github.com/AI-agent-assembly/python-sdk.git
+```
+
+### Develop on the SDK
+
+Clone the repo and sync the dev environment with `uv`:
+
+```bash
+git clone https://github.com/AI-agent-assembly/python-sdk.git
+cd python-sdk
+uv sync
+```
+
+To build the optional PyO3 extension locally (requires Rust):
+
+```bash
+uv tool run maturin develop --manifest-path rust/aa-ffi-python/Cargo.toml --release
+```
+
+The pure-Python SDK works without the native extension — `maturin develop` is only needed if you want the sub-millisecond `RuntimeClient` fast path.
+
+## Quick Start
+
+A governed LangChain ReAct agent that runs offline against a mock LLM. The example imports LangChain in addition to the SDK, so install both:
+
+```bash
+pip install agent-assembly langchain langchain-community
+```
+
+```python
+from langchain.agents import AgentExecutor, create_react_agent
+from langchain.tools import Tool
+from langchain_community.llms import FakeListLLM
+from langchain_core.prompts import PromptTemplate
+
+from agent_assembly import init_assembly
+
+with init_assembly(
+    gateway_url="http://localhost:8080",
+    api_key="dev-key",
+    agent_id="quickstart-agent",
+    mode="sdk-only",
+):
+    llm = FakeListLLM(responses=[
+        "Thought: I should look up the user.\nAction: whoami\nAction Input: alice\n",
+        "Thought: I have the answer.\nFinal Answer: alice is in engineering\n",
+    ])
+    tools = [Tool(name="whoami", func=lambda name: f"{name} is in engineering", description="who")]
+    prompt = PromptTemplate.from_template(
+        "Use the tools.\n{tools}\nTool names: {tool_names}\nQ: {input}\n{agent_scratchpad}"
+    )
+    executor = AgentExecutor(agent=create_react_agent(llm, tools, prompt), tools=tools, max_iterations=2)
+    print(executor.invoke({"input": "Which team is alice on?"})["output"])
+```
+
+What this does:
+
+1. `init_assembly()` registers the agent with the gateway and auto-loads the LangChain adapter — every tool call from now on goes through the policy gate.
+2. The `FakeListLLM` replays canned responses so the example runs **offline** with no real LLM.
+3. The `with` block tears down the gateway connection and unwinds adapter hooks on exit.
+
+## Public API
+
+- `init_assembly(gateway_url, api_key, agent_id=None, mode="auto") -> AssemblyContext`
+- `GatewayClient.register_agent() -> dict`
+- `GatewayClient.check_policy_compliance(action: str) -> dict`
+- Exceptions: `AssemblyError`, `AgentError`, `PolicyError`, `GatewayError`, `ConfigurationError`
+- Data models: `AgentConfig`, `AgentState`, `PolicyEvaluation`
+
+## Error Handling
+
+```python
+from agent_assembly import init_assembly
+from agent_assembly.exceptions import ConfigurationError
+
+try:
+    context = init_assembly(gateway_url="", api_key="my-api-key", agent_id="my-agent-001")
+except ConfigurationError as exc:
+    print(f"Invalid configuration: {exc}")
+```
+
+## Development
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+Run integration tests:
+
+```bash
+uv run pytest -m integration
+```
+
+Lint and type-check:
+
+```bash
+uv run ruff check .
+uv run mypy agent_assembly
+```
+
+## Native Core Extension (AAASM-55)
+
+Build and install the PyO3 extension locally:
+
+```bash
+uv tool run maturin develop --manifest-path rust/aa-ffi-python/Cargo.toml --release
+```
+
+Validate native module import:
+
+```python
+from agent_assembly._core import RuntimeClient, GovernanceEvent, PolicyResult
+```
+
+Run opt-in native integration tests:
+
+```bash
+AAASM_RUN_NATIVE_CORE_TESTS=1 uv run pytest test/integration/test_native_core_runtime.py
+AAASM_RUN_MATURIN_TESTS=1 uv run pytest test/integration/test_native_core_maturin.py
+```
+
+## Documentation
+
+- **Project docs (rendered)** — https://ai-agent-assembly.github.io/python-sdk/ *(versioned via `mike`; pick `latest` or `stable` from the version selector)*
+- **Architecture** — [rendered](https://ai-agent-assembly.github.io/python-sdk/latest/architecture/) / [source](./docs/architecture/index.md) — adapter pattern, PyO3 FFI, `init_assembly()` lifecycle, with a Mermaid flow diagram.
+- **API reference** — [rendered](https://ai-agent-assembly.github.io/python-sdk/latest/api-reference/) / [source](./docs/api-reference/index.md) — auto-generated from package docstrings via `mkdocstrings`. Per-module pages: [Client](./docs/api-reference/client.md), [Exceptions](./docs/api-reference/exceptions.md), [Models](./docs/api-reference/models.md).
+- **ADRs** — [`docs/development/adr/`](./docs/development/adr/) (architecture decision records)
+
+## Contributing
+
+Please read [**CONTRIBUTING.md**](./CONTRIBUTING.md) before opening a PR — it covers dev environment setup, framework adapter authoring, the test/lint command list, branch naming, and the PR checklist.
+
+## License
+
+[MIT License](./LICENSE)

agent_assembly-0.0.1a4/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.1a4"
+
+# 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-0.0.1a4/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-0.0.1a4/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"]