maof 1.0.0__py3-none-any.whl

maof/__init__.py

@@ -0,0 +1,73 @@
+"""MAOF — Multi-Agent Orchestration Framework.
+
+The reusable orchestration + governance layer of a hierarchical (L1 -> L2)
+multi-agent system. Ships zero domain content: adopters inject their own L1
+orchestrator, L2 agents, skills, task schemas, and policy rulesets.
+"""
+
+from __future__ import annotations
+
+from maof.config import Settings
+from maof.errors import (
+    ApprovalRequired,
+    BudgetExceeded,
+    ConfigError,
+    IdempotencyError,
+    MAOFError,
+    PolicyDenied,
+    RegistryTrustError,
+    SchemaValidationError,
+    SignatureError,
+    TenancyError,
+    TransportError,
+)
+from maof.types import (
+    ContextEnvelope,
+    CoordinationMode,
+    DataPointer,
+    EffortBudget,
+    Envelope,
+    Intent,
+    OrchestrationMode,
+    Plan,
+    Stage,
+    StageContext,
+    Task,
+    TaskResult,
+    TenantContext,
+    ToolRef,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    "Settings",
+    # errors
+    "MAOFError",
+    "ConfigError",
+    "SignatureError",
+    "SchemaValidationError",
+    "PolicyDenied",
+    "ApprovalRequired",
+    "IdempotencyError",
+    "TransportError",
+    "RegistryTrustError",
+    "BudgetExceeded",
+    "TenancyError",
+    # core types
+    "Stage",
+    "CoordinationMode",
+    "OrchestrationMode",
+    "TenantContext",
+    "Envelope",
+    "ContextEnvelope",
+    "Task",
+    "TaskResult",
+    "Intent",
+    "Plan",
+    "ToolRef",
+    "DataPointer",
+    "EffortBudget",
+    "StageContext",
+]

maof/agents/base.py

@@ -0,0 +1,74 @@
+"""Agent contracts.
+
+First-party agents implement these Protocols and register via decorators /
+entry points; the MCP adapter wraps remote MCP servers to satisfy the
+same L2Agent contract. ``BaseL2Agent`` defaults
+``context_delegation = []`` so a simple agent that side-loads nothing need not
+declare anything.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from maof.registry.models import ContextDeclaration
+    from maof.types import L2Context, OrchestrationResult, TaskResult, TenantContext
+
+
+@runtime_checkable
+class Skill(Protocol):
+    name: str
+    version: str
+
+    async def run(self, payload: dict[str, Any], ctx: L2Context) -> dict[str, Any]: ...
+
+
+@runtime_checkable
+class L2Agent(Protocol):
+    name: str
+    accepted_task_types: list[str]
+    skills: list[Skill]
+    context_delegation: list[ContextDeclaration]  # declares any side-loaded context
+
+    async def handle(self, task: dict[str, Any], ctx: L2Context) -> TaskResult: ...
+
+
+@runtime_checkable
+class L1Orchestrator(Protocol):
+    async def run(self, goal: str, tenant: TenantContext) -> OrchestrationResult: ...
+
+
+class BaseSkill:
+    """Convenience base for a skill (an L2 agent's internal chain step)."""
+
+    name: str = "skill"
+    version: str = "v1"
+
+    async def run(self, payload: dict[str, Any], ctx: L2Context) -> dict[str, Any]:
+        raise NotImplementedError
+
+
+class BaseL2Agent:
+    """Convenience base for an L2 agent. Defaults ``context_delegation = []`` so a
+    simple agent that side-loads nothing need not declare anything."""
+
+    name: str = "base_l2_agent"
+    accepted_task_types: list[str] = []
+
+    def __init__(
+        self,
+        *,
+        skills: list[Skill] | None = None,
+        context_delegation: list[ContextDeclaration] | None = None,
+    ) -> None:
+        self.skills: list[Skill] = list(skills) if skills else []
+        self.context_delegation: list[ContextDeclaration] = (
+            list(context_delegation) if context_delegation else []
+        )
+
+    async def handle(self, task: dict[str, Any], ctx: L2Context) -> TaskResult:
+        raise NotImplementedError
+
+
+__all__ = ["Skill", "L2Agent", "L1Orchestrator", "BaseSkill", "BaseL2Agent"]

maof/agents/client.py

@@ -0,0 +1,199 @@
+"""Hosting machinery for source-of-truth agents.
+
+- :class:`AgentClientFactory` — registry-resolved, RBAC-scoped MCP clients for
+  agent→agent consultation (``ctx.agents``); every consultation is audited.
+- :func:`attach_registry_context_sources` — approved ``context_source`` entries
+  auto-attach to the ContextBuilder (``required`` fails closed; contributions
+  cache per ``ContextDeclaration.mutable``).
+- :func:`attach_registry_resolvers` — manifest ``resolver_schemes`` register as
+  JIT reference loaders (adopter-defined schemes, e.g. ``catalog://``, ``datastore://``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from maof.errors import MAOFError, RegistryTrustError
+from maof.observability.events import AuditEvent
+from maof.registry.loader import _scopes_granted
+
+if TYPE_CHECKING:
+    from maof.context.builder import ContextBuilder
+    from maof.context.jit import DefaultReferenceResolver
+    from maof.observability.events import EventSink
+    from maof.registry.loader import RegistryLoader
+    from maof.registry.models import AgentManifest
+    from maof.types import ContextEnvelope, StageContext, TenantContext
+
+#: Builds a connected client (MCP stdio/HTTP) for an approved manifest. Injected so
+#: deployments choose their MCP client library; tests inject fakes.
+ClientBuilder = Callable[["AgentManifest"], Any]
+
+
+class AgentClientFactory:
+    """Resolve an approved+signed registry agent into an RBAC-scoped client."""
+
+    def __init__(
+        self,
+        loader: RegistryLoader,
+        *,
+        tenant: TenantContext,
+        client_builder: ClientBuilder,
+        event_sink: EventSink | None = None,
+    ) -> None:
+        self._loader = loader
+        self._tenant = tenant
+        self._client_builder = client_builder
+        self._event_sink = event_sink
+        self._cache: dict[str, Any] = {}
+
+    async def client(self, agent_id: str) -> Any:
+        if agent_id in self._cache:
+            await self._emit(agent_id)
+            return self._cache[agent_id]
+        manifest = next((m for m in await self._loader.manifests() if m.id == agent_id), None)
+        if manifest is None:
+            raise RegistryTrustError(f"no approved registry agent {agent_id!r}")
+        if not _scopes_granted(manifest, self._tenant):
+            raise RegistryTrustError(
+                f"tenant {self._tenant.tenant_id!r} lacks scopes for {agent_id!r}"
+            )
+        client = self._client_builder(manifest)
+        self._cache[agent_id] = client
+        await self._emit(agent_id)
+        return client
+
+    async def _emit(self, agent_id: str) -> None:
+        if self._event_sink is None:
+            return
+        await self._event_sink.emit(
+            AuditEvent(
+                tenant_id=self._tenant.tenant_id,
+                intent_id=None,
+                event_type="agent_consulted",
+                envelope={"agent": agent_id},
+                details={},
+            )
+        )
+
+
+class ContextSourceCache:
+    """Caches context-source contributions keyed (entry_id, tenant, version)."""
+
+    def __init__(self) -> None:
+        self._cache: dict[tuple[str, str, str], Any] = {}
+
+    def get(self, manifest: AgentManifest, tenant_id: str) -> Any | None:
+        return self._cache.get((manifest.id, tenant_id, manifest.version))
+
+    def set(self, manifest: AgentManifest, tenant_id: str, value: Any) -> None:
+        self._cache[(manifest.id, tenant_id, manifest.version)] = value
+
+
+class RegistryContextSource:
+    """Wraps an approved ``context_source`` entry as a ContextBuilder source."""
+
+    def __init__(
+        self,
+        manifest: AgentManifest,
+        client: Any,
+        *,
+        cache: ContextSourceCache | None = None,
+        event_sink: EventSink | None = None,
+    ) -> None:
+        # The stable registry id is the lookup key — display names are not contracts.
+        self.name = manifest.id
+        self._manifest = manifest
+        self._client = client
+        self._cache = cache
+        self._event_sink = event_sink
+        # mutable declarations force re-fetch every build (ContextDeclaration.mutable)
+        self._cacheable = not any(d.mutable for d in manifest.side_loaded_context)
+
+    async def contribute(self, sc: StageContext, env: ContextEnvelope) -> ContextEnvelope:
+        data: Any | None = None
+        if self._cache is not None and self._cacheable:
+            data = self._cache.get(self._manifest, sc.tenant.tenant_id)
+        if data is None:
+            try:
+                data = await self._client.read_resource(self._manifest.id)
+            except Exception as exc:
+                if self._manifest.required:
+                    raise MAOFError(
+                        f"required context source {self._manifest.id!r} unavailable "
+                        f"(fail closed): {exc}"
+                    ) from exc
+                return env  # optional source: skip, keep planning
+            if self._cache is not None and self._cacheable:
+                self._cache.set(self._manifest, sc.tenant.tenant_id, data)
+        env.semantic_model[self.name] = data
+        env.extras.setdefault("registry_context_sources", []).append(self._manifest.id)
+        if self._event_sink is not None:
+            await self._event_sink.emit(
+                AuditEvent(
+                    tenant_id=sc.tenant.tenant_id,
+                    intent_id=env.intent_id,
+                    event_type="context_delegated",
+                    envelope={"agent": self._manifest.id, "kind": "registry_context_source"},
+                    details={"version": self._manifest.version},
+                )
+            )
+        return env
+
+
+async def attach_registry_context_sources(
+    builder: ContextBuilder,
+    loader: RegistryLoader,
+    *,
+    tenant: TenantContext,
+    client_builder: ClientBuilder,
+    cache: ContextSourceCache | None = None,
+    event_sink: EventSink | None = None,
+) -> list[AgentManifest]:
+    """Attach every approved + RBAC-granted ``context_source`` to the builder."""
+    attached: list[AgentManifest] = []
+    for manifest in await loader.context_sources(tenant=tenant):
+        builder.add_source(
+            RegistryContextSource(
+                manifest, client_builder(manifest), cache=cache, event_sink=event_sink
+            )
+        )
+        attached.append(manifest)
+    return attached
+
+
+async def attach_registry_resolvers(
+    resolver: DefaultReferenceResolver,
+    loader: RegistryLoader,
+    *,
+    client_builder: ClientBuilder,
+    tenant: TenantContext | None = None,
+) -> list[str]:
+    """Register every approved manifest's ``resolver_schemes`` as JIT loaders, so
+    ``<scheme>://<ref>`` references resolve through the owning agent."""
+    registered: list[str] = []
+    manifests = await loader.manifests()
+    for manifest in manifests:
+        if tenant is not None and not _scopes_granted(manifest, tenant):
+            continue
+        for scheme in manifest.resolver_schemes:
+            client = client_builder(manifest)
+
+            async def _load(rest: str, _client: Any = client) -> str:
+                data = await _client.read_resource(rest)
+                return data if isinstance(data, str) else repr(data)
+
+            resolver.register_loader(scheme, _load)
+            registered.append(scheme)
+    return registered
+
+
+__all__ = [
+    "ClientBuilder",
+    "AgentClientFactory",
+    "ContextSourceCache",
+    "RegistryContextSource",
+    "attach_registry_context_sources",
+    "attach_registry_resolvers",
+]

maof/agents/mcp_adapter.py

@@ -0,0 +1,138 @@
+"""MCP adapter.
+
+Wraps a remote MCP server so it satisfies the L2Agent contract (and, separately,
+the ContextSource contract). The MCP client is injected so this module imports
+without the ``mcp`` extra; adopters pass a connected client (stdio or HTTP) —
+either anything satisfying the duck-typed surface (``call_tool``/``read_resource``)
+or :class:`MCPSDKClient`, which adapts an official ``mcp`` SDK session to it.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any
+
+from maof.errors import ConfigError, MAOFError
+from maof.types import TaskResult
+
+if TYPE_CHECKING:
+    from maof.registry.models import AgentManifest, ContextDeclaration
+    from maof.types import ContextEnvelope, L2Context, StageContext
+
+
+class MCPAgentAdapter:
+    """Presents an MCP server as an L2 agent: each task maps to an MCP tool call."""
+
+    def __init__(self, manifest: AgentManifest, client: Any) -> None:
+        self.name = manifest.name
+        self.accepted_task_types = list(manifest.accepted_task_types)
+        self.skills: list[Any] = []
+        self.context_delegation: list[ContextDeclaration] = list(manifest.side_loaded_context)
+        self._client = client
+        self._manifest = manifest
+
+    async def handle(self, task: dict[str, Any], ctx: L2Context) -> TaskResult:
+        tool = task.get("tool") or task.get("task_type", "")
+        result = await self._client.call_tool(tool, task)
+        return TaskResult(
+            status="ok",
+            task_id=str(task.get("task_id", "")),
+            output={"mcp_tool": tool, "result": result},
+        )
+
+
+class MCPContextSource:
+    """Uses an MCP server purely as a context provider (a read-only slice)."""
+
+    def __init__(
+        self, manifest: AgentManifest, client: Any, *, resource: str | None = None
+    ) -> None:
+        self.name = manifest.name
+        self._client = client
+        self._resource = resource or manifest.id
+
+    async def contribute(self, sc: StageContext, env: ContextEnvelope) -> ContextEnvelope:
+        data = await self._client.read_resource(self._resource)
+        env.semantic_model[self.name] = data
+        return env
+
+
+def _parse_payload(text: str) -> Any:
+    """Tool/resource payloads are JSON when the server sends JSON, else raw text."""
+    try:
+        return json.loads(text)
+    except (json.JSONDecodeError, ValueError):
+        return text
+
+
+class MCPSDKClient:
+    """Adapts an official ``mcp`` SDK ``ClientSession`` to the duck-typed surface
+    the adapters above expect (``call_tool(name, args)`` / ``read_resource(ref)``).
+
+    Importing this module never requires the ``mcp`` extra; connecting does (see
+    :func:`mcp_stdio_client`). Fake clients keep satisfying the same surface.
+    """
+
+    def __init__(self, session: Any, *, default_resource_scheme: str = "resource") -> None:
+        self._session = session
+        self._scheme = default_resource_scheme
+
+    async def call_tool(self, name: str, args: dict[str, Any]) -> Any:
+        result = await self._session.call_tool(name, arguments=args)
+        structured = getattr(result, "structuredContent", None)
+        if structured:
+            return structured
+        parts: list[str] = []
+        for block in getattr(result, "content", None) or []:
+            text = getattr(block, "text", None)
+            if text is not None:
+                parts.append(str(text))
+        text_out = "\n".join(parts)
+        if getattr(result, "isError", False):
+            raise MAOFError(f"MCP tool {name!r} returned an error: {text_out or 'no detail'}")
+        return _parse_payload(text_out)
+
+    async def read_resource(self, ref: str) -> Any:
+        uri = ref if "://" in ref else f"{self._scheme}://{ref}"
+        result = await self._session.read_resource(uri)
+        for content in getattr(result, "contents", None) or []:
+            text = getattr(content, "text", None)
+            if text is not None:
+                return _parse_payload(str(text))
+            blob = getattr(content, "blob", None)
+            if blob is not None:
+                return blob
+        return None
+
+
+@contextlib.asynccontextmanager
+async def mcp_stdio_client(
+    command: str,
+    args: list[str] | None = None,
+    *,
+    env: dict[str, str] | None = None,
+    default_resource_scheme: str = "resource",
+) -> AsyncIterator[MCPSDKClient]:
+    """Spawn an MCP server over stdio and yield a connected :class:`MCPSDKClient`.
+
+    The official SDK is imported lazily so the module works without the extra.
+    """
+    try:
+        from mcp import ClientSession, StdioServerParameters
+        from mcp.client.stdio import stdio_client
+    except ImportError as exc:  # pragma: no cover - depends on installed extras
+        raise ConfigError(
+            "mcp_stdio_client requires the 'mcp' extra (pip install maof[mcp])"
+        ) from exc
+    params = StdioServerParameters(command=command, args=list(args or []), env=env)
+    async with (
+        stdio_client(params) as (read_stream, write_stream),
+        ClientSession(read_stream, write_stream) as session,
+    ):
+        await session.initialize()
+        yield MCPSDKClient(session, default_resource_scheme=default_resource_scheme)
+
+
+__all__ = ["MCPAgentAdapter", "MCPContextSource", "MCPSDKClient", "mcp_stdio_client"]

maof/agents/registry_runtime.py

@@ -0,0 +1,92 @@
+"""Runtime agent/skill registry.
+
+In-process map of locally injected L2 agents and skills (compile/deploy-time
+trust), populated via decorators and/or ``importlib.metadata`` entry points
+(groups ``maof.l2_agents`` / ``maof.skills``). Distinct from the persisted,
+admin-gated discovery registry in ``maof.registry``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from importlib import metadata
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+    from maof.agents.base import L2Agent, Skill
+
+A = TypeVar("A", bound="L2Agent")
+S = TypeVar("S", bound="Skill")
+
+
+class AgentRegistry:
+    def __init__(self) -> None:
+        self._agents: dict[str, L2Agent] = {}
+        self._by_task_type: dict[str, L2Agent] = {}
+        self._skills: dict[str, Skill] = {}
+
+    def register_agent(self, agent: L2Agent) -> None:
+        self._agents[agent.name] = agent
+        for task_type in agent.accepted_task_types:
+            self._by_task_type[task_type] = agent
+
+    def register_skill(self, skill: Skill) -> None:
+        self._skills[skill.name] = skill
+
+    def agent(self, name: str) -> L2Agent | None:
+        return self._agents.get(name)
+
+    def agent_for_task_type(self, task_type: str) -> L2Agent | None:
+        return self._by_task_type.get(task_type)
+
+    def skill(self, name: str) -> Skill | None:
+        return self._skills.get(name)
+
+    def agents(self) -> list[L2Agent]:
+        return list(self._agents.values())
+
+    def load_entry_points(self) -> None:
+        """Discover adopter agents/skills declared via packaging metadata."""
+        for ep in metadata.entry_points(group="maof.l2_agents"):
+            factory = ep.load()
+            self.register_agent(factory() if callable(factory) else factory)
+        for ep in metadata.entry_points(group="maof.skills"):
+            factory = ep.load()
+            self.register_skill(factory() if callable(factory) else factory)
+
+
+#: A process-global default registry that the decorators target.
+default_registry = AgentRegistry()
+
+
+def register_l2_agent(
+    registry: AgentRegistry | None = None,
+) -> Callable[[type[A]], type[A]]:
+    """Class decorator: instantiate and register an L2 agent on import."""
+    target = registry or default_registry
+
+    def decorator(cls: type[A]) -> type[A]:
+        target.register_agent(cls())
+        return cls
+
+    return decorator
+
+
+def register_skill(
+    registry: AgentRegistry | None = None,
+) -> Callable[[type[S]], type[S]]:
+    target = registry or default_registry
+
+    def decorator(cls: type[S]) -> type[S]:
+        target.register_skill(cls())
+        return cls
+
+    return decorator
+
+
+__all__ = [
+    "AgentRegistry",
+    "default_registry",
+    "register_l2_agent",
+    "register_skill",
+]