operator-architecture 0.2.0__py3-none-any.whl

operator_architecture/__init__.py

@@ -0,0 +1,40 @@
+"""Operator Architecture — framework-agnostic multi-agent orchestration SDK."""
+
+from __future__ import annotations
+
+from operator_architecture.agent import (
+    AgentHandle,
+    AgentRequest,
+    AgentResult,
+    AgentRunner,
+    AgentSpec,
+    ObjectiveSlot,
+    callable_agent,
+)
+from operator_architecture.coordinator import DEFAULT_COORDINATOR_SKILL, Coordinator
+from operator_architecture.machine import StateMachine
+from operator_architecture.messages import Message, Messages
+from operator_architecture.orchestration import openai_tool_schema, tool_schemas
+from operator_architecture.streaming import StreamEvent, StreamingCallback, emit_stream
+
+__all__ = [
+    "AgentHandle",
+    "AgentRequest",
+    "AgentResult",
+    "AgentRunner",
+    "AgentSpec",
+    "Coordinator",
+    "DEFAULT_COORDINATOR_SKILL",
+    "Message",
+    "Messages",
+    "ObjectiveSlot",
+    "StateMachine",
+    "StreamEvent",
+    "StreamingCallback",
+    "callable_agent",
+    "emit_stream",
+    "openai_tool_schema",
+    "tool_schemas",
+]
+
+__version__ = "0.2.0"

operator_architecture/agent.py

@@ -0,0 +1,157 @@
+"""Agent registration and runner protocol."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from operator_architecture.streaming import StreamingCallback
+
+
+@dataclass
+class AgentRequest:
+    """Input handed to a host ``AgentRunner`` when an objective is run."""
+
+    agent: str
+    objective: str
+    skill: str
+    messages: list[dict[str, Any]]
+    checklist: list[str] | None = None
+    agent_props: dict[str, Any] | None = None
+    model: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class AgentResult:
+    """Output from a host agent — staged onto the objective slot."""
+
+    content: str
+    messages: list[dict[str, Any]] | None = None
+    usage: dict[str, Any] | None = None
+    raw: Any = None
+
+
+@runtime_checkable
+class AgentRunner(Protocol):
+    """Host-provided agent runtime (Relay, LangChain, HTTP, callable, …)."""
+
+    async def run(
+        self,
+        request: AgentRequest,
+        *,
+        streaming_callback: StreamingCallback = None,
+    ) -> AgentResult: ...
+
+
+@dataclass
+class AgentSpec:
+    """Register a named sub-agent with the state machine."""
+
+    name: str
+    description: str
+    skill: str
+    runner: AgentRunner
+    model: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class ObjectiveSlot:
+    """One commissioned objective for a sub-agent."""
+
+    index: int
+    agent: str
+    objective: str
+    checklist: list[str] = field(default_factory=list)
+    agent_props: dict[str, Any] = field(default_factory=dict)
+    messages: list[dict[str, Any]] = field(default_factory=list)
+    agent_message: str | None = None
+    result: dict[str, Any] | None = None
+    status: str = "pending"  # pending | running | staged | accepted | failed
+    model: str | None = None
+    duration_ms: float | None = None
+    commission_id: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.commission_id:
+            self.commission_id = f"{self.agent}-{self.index}"
+
+
+@dataclass
+class AgentHandle:
+    """Runtime handle for one registered agent + its objective slots."""
+
+    spec: AgentSpec
+    slots: list[ObjectiveSlot] = field(default_factory=list)
+
+    @property
+    def name(self) -> str:
+        return self.spec.name
+
+    @property
+    def runner(self) -> AgentRunner:
+        return self.spec.runner
+
+    def __len__(self) -> int:
+        return len(self.slots)
+
+    def __getitem__(self, index: int) -> ObjectiveSlot:
+        if index < 1 or index > len(self.slots):
+            raise IndexError(
+                f"{self.name} has {len(self.slots)} objectives; "
+                f"requested index {index} (1-based)"
+            )
+        return self.slots[index - 1]
+
+    def next_index(self) -> int:
+        return len(self.slots) + 1
+
+    def create_objective(
+        self,
+        objective: str,
+        *,
+        checklist: list[str] | None = None,
+        agent_props: dict[str, Any] | None = None,
+    ) -> ObjectiveSlot:
+        idx = self.next_index()
+        slot = ObjectiveSlot(
+            index=idx,
+            agent=self.name,
+            objective=objective,
+            checklist=list(checklist or []),
+            agent_props=dict(agent_props or {}),
+            model=self.spec.model,
+            messages=[
+                {"role": "system", "content": self.spec.skill},
+            ],
+        )
+        self.slots.append(slot)
+        return slot
+
+    def objectives(self) -> list[ObjectiveSlot]:
+        return list(self.slots)
+
+
+def callable_agent(
+    fn: Callable[[AgentRequest], Awaitable[AgentResult] | AgentResult],
+) -> AgentRunner:
+    """Wrap an async/sync callable as an ``AgentRunner``."""
+
+    class _CallableRunner:
+        async def run(
+            self,
+            request: AgentRequest,
+            *,
+            streaming_callback: StreamingCallback = None,
+        ) -> AgentResult:
+            _ = streaming_callback
+            result = fn(request)
+            if hasattr(result, "__await__"):
+                result = await result  # type: ignore[misc]
+            if isinstance(result, AgentResult):
+                return result
+            return AgentResult(content=str(result))
+
+    return _CallableRunner()

operator_architecture/coordinator.py

@@ -0,0 +1,42 @@
+"""Coordinator configuration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from operator_architecture.agent import AgentRunner
+
+DEFAULT_COORDINATOR_SKILL = """\
+You are the **Operator coordinator**. You are the sole interface to the user.
+
+You do NOT perform domain work yourself. Commission specialized agents, then \
+review their staged messages before accepting results into the core conversation.
+
+## Orchestration tools
+- `list_agents()` — discover registered agents
+- `commission(agent, objective, checklist=None, agent_props=None)` — run a junior
+- `get_agent_message(agent, index)` — peek staged junior prose
+- `accept_agent_result(agent, index)` — attach compact result to the core thread
+- `instruct_agent(agent, index, message)` — continue a junior objective
+- `list_objectives(agent=None)` — status board
+
+## Rules
+- Prefer listing agents before commissioning when unsure what exists.
+- After each commission, review the staged message: accept or instruct.
+- Summarize accepted results clearly for the user.
+"""
+
+
+@dataclass
+class Coordinator:
+    """Coordinator persona — context owned by the StateMachine.
+
+    If ``runner`` is set, ``StateMachine.run`` will invoke it with orchestration
+    tools. If unset, the host drives orchestration via SM methods only.
+    """
+
+    skill: str = DEFAULT_COORDINATOR_SKILL
+    runner: AgentRunner | None = None
+    model: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)

operator_architecture/machine.py

@@ -0,0 +1,507 @@
+"""StateMachine — orchestration engine for the Operator Architecture."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Sequence
+from typing import Any
+
+from operator_architecture.agent import (
+    AgentHandle,
+    AgentRequest,
+    AgentResult,
+    AgentSpec,
+    ObjectiveSlot,
+)
+from operator_architecture.coordinator import Coordinator
+from operator_architecture.messages import Messages
+from operator_architecture.orchestration import attach_schema, openai_tool_schema, tool_schemas
+from operator_architecture.streaming import StreamingCallback, emit_stream
+
+
+class StateMachine:
+    """Framework-agnostic multi-agent orchestration engine.
+
+    Owns coordinator context, sub-agent registry, and the commission → stage →
+    accept/instruct lifecycle. Does **not** call LLMs — hosts supply
+    ``AgentRunner`` implementations.
+    """
+
+    def __init__(
+        self,
+        coordinator: Coordinator | None = None,
+        agents: Sequence[AgentSpec] | None = None,
+    ) -> None:
+        self.coordinator = coordinator or Coordinator()
+        self.coordinator_messages = Messages().system(self.coordinator.skill)
+        self.active_agent: str | None = None
+        self._streaming_callback: StreamingCallback = None
+        self._agents: dict[str, AgentHandle] = {}
+        for spec in agents or []:
+            self.add_agent(spec)
+
+    # ── registry ──────────────────────────────────────────────────────
+
+    def add_agent(self, spec: AgentSpec) -> AgentHandle:
+        if not spec.name or spec.name == "coordinator":
+            raise ValueError("agent name required and must not be 'coordinator'")
+        if spec.name in self._agents:
+            raise ValueError(f"agent already registered: {spec.name}")
+        handle = AgentHandle(spec=spec)
+        self._agents[spec.name] = handle
+        return handle
+
+    def agent(self, name: str) -> AgentHandle:
+        if name not in self._agents:
+            raise KeyError(f"Unknown agent: {name}")
+        return self._agents[name]
+
+    def agents(self) -> list[AgentHandle]:
+        return list(self._agents.values())
+
+    def set_streaming_callback(self, callback: StreamingCallback) -> None:
+        self._streaming_callback = callback
+
+    # ── discovery / status ────────────────────────────────────────────
+
+    def list_agents(self) -> list[dict[str, Any]]:
+        """Return registered agents (name, description, model, metadata keys)."""
+        out: list[dict[str, Any]] = []
+        for handle in self._agents.values():
+            spec = handle.spec
+            entry: dict[str, Any] = {
+                "name": spec.name,
+                "description": spec.description,
+                "model": spec.model,
+            }
+            meta_tools = spec.metadata.get("tools")
+            if meta_tools is not None:
+                entry["tools"] = meta_tools
+            out.append(entry)
+        return out
+
+    def list_objectives(self, agent: str | None = None) -> list[dict[str, Any]]:
+        """Return objective status board for one agent or all."""
+        handles = [self.agent(agent)] if agent else self.agents()
+        rows: list[dict[str, Any]] = []
+        for handle in handles:
+            for slot in handle.objectives():
+                rows.append(
+                    {
+                        "agent": slot.agent,
+                        "index": slot.index,
+                        "commission_id": slot.commission_id,
+                        "objective": slot.objective,
+                        "status": slot.status,
+                        "model": slot.model,
+                        "duration_ms": slot.duration_ms,
+                    }
+                )
+        return rows
+
+    def get_agent_message(self, agent: str, index: int) -> dict[str, Any]:
+        """Peek staged junior prose without accepting it."""
+        slot = self.agent(agent)[index]
+        return {
+            "agent": agent,
+            "index": index,
+            "status": slot.status,
+            "agent_message": slot.agent_message,
+            "objective": slot.objective,
+        }
+
+    # ── commission / instruct / accept ────────────────────────────────
+
+    async def commission(
+        self,
+        agent: str,
+        objective: str,
+        checklist: list[str] | None = None,
+        agent_props: dict[str, Any] | None = None,
+        *,
+        streaming_callback: StreamingCallback = None,
+    ) -> dict[str, Any]:
+        """Create an objective slot, run the host agent, stage the result."""
+        goal = (objective or "").strip()
+        if not goal:
+            return {"error": "missing_objective", "detail": "objective is required."}
+
+        handle = self.agent(agent)
+        slot = handle.create_objective(
+            goal, checklist=checklist, agent_props=agent_props
+        )
+        slot.status = "running"
+        self.active_agent = agent
+        cb = streaming_callback or self._streaming_callback
+
+        await emit_stream(
+            cb,
+            {
+                "agent": agent,
+                "phase": "commissioned",
+                "detail": goal,
+                "model": slot.model or "",
+                "objective": goal,
+                "commission_id": slot.commission_id,
+                "index": slot.index,
+            },
+        )
+
+        brief = self._build_brief(goal, checklist, agent_props)
+        slot.messages.append({"role": "user", "content": brief})
+
+        return await self._run_slot(handle, slot, streaming_callback=cb)
+
+    async def instruct(
+        self,
+        agent: str,
+        index: int,
+        message: str,
+        *,
+        streaming_callback: StreamingCallback = None,
+    ) -> dict[str, Any]:
+        """Append instruction to a slot and re-run the host agent."""
+        text = (message or "").strip()
+        if not text:
+            return {"error": "empty_message"}
+        handle = self.agent(agent)
+        try:
+            slot = handle[index]
+        except IndexError as exc:
+            return {"error": "bad_index", "detail": str(exc)}
+
+        slot.messages.append({"role": "user", "content": text})
+        slot.status = "running"
+        self.active_agent = agent
+        cb = streaming_callback or self._streaming_callback
+        return await self._run_slot(handle, slot, streaming_callback=cb)
+
+    def accept(self, agent: str, index: int) -> dict[str, Any]:
+        """Accept staged result into the coordinator core thread (compact)."""
+        return self.accept_agent_result(agent, index)
+
+    def accept_agent_result(self, agent: str, index: int) -> dict[str, Any]:
+        """Attach compact slot.result onto coordinator messages context."""
+        if agent not in self._agents:
+            return {"error": "unknown_agent", "agent": agent}
+        try:
+            slot = self.agent(agent)[index]
+        except IndexError as exc:
+            return {"error": "bad_index", "detail": str(exc)}
+
+        if slot.agent_message is None and slot.result is None:
+            return {"error": "nothing_staged", "agent": agent, "index": index}
+
+        compact = slot.result or {
+            "status": "accepted",
+            "agent": agent,
+            "index": index,
+            "report": (slot.agent_message or "")[:2000],
+            "objective": slot.objective,
+            "model": slot.model,
+            "duration_ms": slot.duration_ms,
+        }
+        compact = {**compact, "status": "accepted"}
+        slot.result = compact
+        slot.status = "accepted"
+
+        # Hosts attach this return value to the coordinator thread (tool result
+        # or manual append). OA does not invent a second copy here.
+        return {
+            "status": "accepted",
+            "agent": agent,
+            "index": index,
+            "result": compact,
+        }
+
+    # aliases matching tool names
+    async def instruct_agent(
+        self,
+        agent: str,
+        index: int,
+        message: str,
+        *,
+        streaming_callback: StreamingCallback = None,
+    ) -> dict[str, Any]:
+        return await self.instruct(
+            agent, index, message, streaming_callback=streaming_callback
+        )
+
+    # ── coordinator turn ──────────────────────────────────────────────
+
+    async def run(
+        self,
+        user_text: str,
+        *,
+        streaming_callback: StreamingCallback = None,
+        orchestration_tools: bool = True,
+    ) -> str:
+        """Append user text and invoke the coordinator runner (if configured).
+
+        OA does not execute a tool loop. The host ``Coordinator.runner`` owns
+        inference/tool-calling and may call back into orchestration tools.
+        """
+        text = (user_text or "").strip()
+        if not text:
+            return ""
+        if self.coordinator.runner is None:
+            raise RuntimeError(
+                "Coordinator.runner is not set. "
+                "Provide a runner for sm.run(), or call sm.commission/accept directly."
+            )
+
+        self.coordinator_messages.user(text)
+        self.active_agent = "coordinator"
+        cb = streaming_callback or self._streaming_callback
+        self._streaming_callback = cb
+
+        await emit_stream(
+            cb,
+            {
+                "agent": "coordinator",
+                "phase": "start",
+                "detail": "starting",
+                "model": self.coordinator.model or "",
+            },
+        )
+
+        tools = self.orchestration_tools() if orchestration_tools else []
+        request = AgentRequest(
+            agent="coordinator",
+            objective=text,
+            skill=self.coordinator.skill,
+            messages=self.coordinator_messages.to_list(),
+            model=self.coordinator.model,
+            metadata={
+                "tools": tools,
+                "tool_schemas": tool_schemas(tools),
+                **self.coordinator.metadata,
+            },
+        )
+
+        try:
+            result = await self.coordinator.runner.run(
+                request, streaming_callback=cb
+            )
+            if result.messages is not None:
+                self.coordinator_messages.replace(result.messages)
+            elif result.content:
+                self.coordinator_messages.assistant(result.content)
+            reply = (result.content or "").strip() or "(no response)"
+            await emit_stream(
+                cb,
+                {
+                    "agent": "coordinator",
+                    "phase": "done",
+                    "detail": reply[:500],
+                    "model": self.coordinator.model or "",
+                    "status": "done",
+                },
+            )
+            return reply
+        except Exception as exc:  # noqa: BLE001
+            err = f"Coordinator error: {type(exc).__name__}: {exc}"
+            await emit_stream(
+                cb,
+                {
+                    "agent": "coordinator",
+                    "phase": "fail",
+                    "detail": err,
+                    "status": "failed",
+                },
+            )
+            raise
+        finally:
+            self.active_agent = None
+            if streaming_callback is not None:
+                # only clear if we temporarily owned the callback for this call
+                pass
+
+    def orchestration_tools(self) -> list:
+        """Return plain callables + OpenAI schemas for host coordinator runners."""
+        sm = self
+
+        async def list_agents() -> list[dict[str, Any]]:
+            """List registered sub-agents with descriptions."""
+            return sm.list_agents()
+
+        async def commission(
+            agent: str,
+            objective: str,
+            checklist: list[str] | None = None,
+            agent_props: dict[str, Any] | None = None,
+        ) -> dict[str, Any]:
+            """Commission a sub-agent. Result is staged until accept_agent_result."""
+            return await sm.commission(
+                agent, objective, checklist=checklist, agent_props=agent_props
+            )
+
+        async def get_agent_message(agent: str, index: int) -> dict[str, Any]:
+            """Peek a staged sub-agent message without accepting it."""
+            return sm.get_agent_message(agent, index)
+
+        async def accept_agent_result(agent: str, index: int) -> dict[str, Any]:
+            """Accept a staged result into the coordinator core thread."""
+            return sm.accept_agent_result(agent, index)
+
+        async def instruct_agent(
+            agent: str, index: int, message: str
+        ) -> dict[str, Any]:
+            """Send further instruction to a sub-agent objective and re-run it."""
+            return await sm.instruct(agent, index, message)
+
+        async def list_objectives(agent: str | None = None) -> list[dict[str, Any]]:
+            """List objective slots and their statuses."""
+            return sm.list_objectives(agent)
+
+        tools = [
+            list_agents,
+            commission,
+            get_agent_message,
+            accept_agent_result,
+            instruct_agent,
+            list_objectives,
+        ]
+        for fn in tools:
+            attach_schema(fn, openai_tool_schema(fn))
+        return tools
+
+    # ── internals ─────────────────────────────────────────────────────
+
+    def _build_brief(
+        self,
+        objective: str,
+        checklist: list[str] | None,
+        agent_props: dict[str, Any] | None,
+    ) -> str:
+        parts = [f"Objective:\n{objective.strip()}"]
+        if checklist:
+            parts.append(
+                "Checklist:\n"
+                + "\n".join(f"- {item}" for item in checklist if str(item).strip())
+            )
+        if agent_props:
+            props_lines = [f"- {k}: {v}" for k, v in agent_props.items()]
+            parts.append("Agent props:\n" + "\n".join(props_lines))
+        return "\n\n".join(parts)
+
+    async def _run_slot(
+        self,
+        handle: AgentHandle,
+        slot: ObjectiveSlot,
+        *,
+        streaming_callback: StreamingCallback = None,
+    ) -> dict[str, Any]:
+        await emit_stream(
+            streaming_callback,
+            {
+                "agent": handle.name,
+                "phase": "start",
+                "detail": "starting",
+                "model": slot.model or "",
+                "commission_id": slot.commission_id,
+                "index": slot.index,
+                "objective": slot.objective,
+            },
+        )
+
+        started = time.perf_counter()
+        request = AgentRequest(
+            agent=handle.name,
+            objective=slot.objective,
+            skill=handle.spec.skill,
+            messages=list(slot.messages),
+            checklist=list(slot.checklist) or None,
+            agent_props=dict(slot.agent_props) or None,
+            model=slot.model,
+            metadata=dict(handle.spec.metadata),
+        )
+
+        try:
+            result: AgentResult = await handle.runner.run(
+                request, streaming_callback=streaming_callback
+            )
+            duration_ms = (time.perf_counter() - started) * 1000
+            report = (result.content or "").strip() or "(empty report)"
+            if result.messages is not None:
+                slot.messages = list(result.messages)
+            else:
+                slot.messages.append({"role": "assistant", "content": report})
+
+            slot.agent_message = report
+            slot.duration_ms = duration_ms
+            slot.status = "staged"
+            slot.result = {
+                "status": "staged",
+                "agent": handle.name,
+                "index": slot.index,
+                "report": report[:2000],
+                "duration_ms": duration_ms,
+                "model": slot.model,
+                "objective": slot.objective,
+            }
+            await emit_stream(
+                streaming_callback,
+                {
+                    "agent": handle.name,
+                    "phase": "done",
+                    "detail": report[:500],
+                    "model": slot.model or "",
+                    "commission_id": slot.commission_id,
+                    "status": "staged",
+                    "duration_ms": duration_ms,
+                    "objective": slot.objective,
+                    "index": slot.index,
+                },
+            )
+            self.active_agent = None
+            return {
+                "status": "staged",
+                "agent": handle.name,
+                "index": slot.index,
+                "commission_id": slot.commission_id,
+                "hint": (
+                    f"Junior reply staged at sm.agent('{handle.name}')[{slot.index}].agent_message. "
+                    f"Call accept_agent_result('{handle.name}', {slot.index}) to attach "
+                    f"the compact result to the core thread, or instruct_agent(...) to continue."
+                ),
+                "preview": report[:400],
+                "duration_ms": duration_ms,
+                "model": slot.model,
+            }
+        except Exception as exc:  # noqa: BLE001
+            duration_ms = (time.perf_counter() - started) * 1000
+            slot.status = "failed"
+            slot.duration_ms = duration_ms
+            slot.agent_message = f"{type(exc).__name__}: {exc}"
+            slot.result = {
+                "status": "failed",
+                "agent": handle.name,
+                "index": slot.index,
+                "report": slot.agent_message,
+                "duration_ms": duration_ms,
+                "model": slot.model,
+                "objective": slot.objective,
+            }
+            await emit_stream(
+                streaming_callback,
+                {
+                    "agent": handle.name,
+                    "phase": "fail",
+                    "detail": slot.agent_message,
+                    "model": slot.model or "",
+                    "commission_id": slot.commission_id,
+                    "status": "failed",
+                    "duration_ms": duration_ms,
+                    "index": slot.index,
+                },
+            )
+            self.active_agent = None
+            return {
+                "status": "failed",
+                "agent": handle.name,
+                "index": slot.index,
+                "report": slot.agent_message,
+                "duration_ms": duration_ms,
+                "model": slot.model,
+            }

operator_architecture/messages.py

@@ -0,0 +1,65 @@
+"""OpenAI chat-completions compatible message helpers."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+
+Message = dict[str, Any]
+
+
+class Messages:
+    """Mutable list of OpenAI-shaped chat messages.
+
+    Compatible with chat.completions payloads: roles ``system``, ``user``,
+    ``assistant``, ``tool`` plus optional ``tool_calls`` / ``tool_call_id``.
+    """
+
+    def __init__(self, messages: list[Message] | None = None) -> None:
+        self._messages: list[Message] = list(messages or [])
+
+    def __iter__(self):
+        return iter(self._messages)
+
+    def __len__(self) -> int:
+        return len(self._messages)
+
+    def __getitem__(self, index: int) -> Message:
+        return self._messages[index]
+
+    def to_list(self) -> list[Message]:
+        return deepcopy(self._messages)
+
+    def clear(self) -> None:
+        self._messages.clear()
+
+    def append(self, message: Message) -> Messages:
+        self._messages.append(dict(message))
+        return self
+
+    def system(self, content: str) -> Messages:
+        return self.append({"role": "system", "content": content})
+
+    def user(self, content: str) -> Messages:
+        return self.append({"role": "user", "content": content})
+
+    def assistant(self, content: str, *, tool_calls: list[dict] | None = None) -> Messages:
+        msg: Message = {"role": "assistant", "content": content}
+        if tool_calls is not None:
+            msg["tool_calls"] = tool_calls
+        return self.append(msg)
+
+    def tool(self, content: str, *, tool_call_id: str) -> Messages:
+        return self.append(
+            {"role": "tool", "content": content, "tool_call_id": tool_call_id}
+        )
+
+    def extend(self, messages: list[Message]) -> Messages:
+        for m in messages:
+            self.append(m)
+        return self
+
+    def replace(self, messages: list[Message]) -> Messages:
+        self._messages = [dict(m) for m in messages]
+        return self

operator_architecture/orchestration.py

@@ -0,0 +1,88 @@
+"""OpenAI tool schemas + callables for coordinator orchestration."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+
+def openai_tool_schema(
+    fn: Callable[..., Any],
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> dict[str, Any]:
+    """Build a chat.completions tools[] entry from a callable's signature/doc."""
+    tool_name = name or fn.__name__
+    doc = (description or inspect.getdoc(fn) or "").strip()
+    sig = inspect.signature(fn)
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+
+    hints = {}
+    try:
+        hints = fn.__annotations__
+    except Exception:
+        hints = {}
+
+    for pname, param in sig.parameters.items():
+        if pname in {"self", "cls"}:
+            continue
+        prop: dict[str, Any] = {"type": _json_type(hints.get(pname, str))}
+        properties[pname] = prop
+        if param.default is inspect.Parameter.empty:
+            required.append(pname)
+
+    return {
+        "type": "function",
+        "function": {
+            "name": tool_name,
+            "description": doc.split("\n\n")[0] if doc else tool_name,
+            "parameters": {
+                "type": "object",
+                "properties": properties,
+                "required": required,
+            },
+        },
+    }
+
+
+def _json_type(annotation: Any) -> str:
+    origin = getattr(annotation, "__origin__", None)
+    if origin is list:
+        return "array"
+    if origin is dict:
+        return "object"
+    name = getattr(annotation, "__name__", "") or str(annotation)
+    mapping = {
+        "str": "string",
+        "int": "integer",
+        "float": "number",
+        "bool": "boolean",
+        "list": "array",
+        "dict": "object",
+    }
+    # Optional[X] / X | None
+    if "None" in str(annotation) or "Optional" in str(annotation):
+        args = getattr(annotation, "__args__", ())
+        for a in args:
+            if a is not type(None):
+                return _json_type(a)
+    return mapping.get(name, "string")
+
+
+def attach_schema(fn: Callable[..., Any], schema: dict[str, Any]) -> Callable[..., Any]:
+    """Attach OpenAI tool schema on the callable for host runners."""
+    setattr(fn, "__oa_tool_schema__", schema)
+    return fn
+
+
+def tool_schemas(tools: list[Callable[..., Any]]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for fn in tools:
+        schema = getattr(fn, "__oa_tool_schema__", None)
+        if schema is None:
+            schema = openai_tool_schema(fn)
+        out.append(schema)
+    return out

operator_architecture/streaming.py

@@ -0,0 +1,38 @@
+"""Streaming / observability types for Operator Architecture."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any, TypedDict
+
+
+class StreamEvent(TypedDict, total=False):
+    """Structured event forwarded from host agents or emitted by the SM."""
+
+    agent: str
+    phase: str  # start | token | tool_start | tool_result | tool_error | commissioned | done | fail
+    detail: str
+    model: str
+    objective: str
+    commission_id: str
+    status: str
+    duration_ms: float
+    index: int
+
+
+StreamingCallback = (
+    Callable[[StreamEvent], None]
+    | Callable[[StreamEvent], Awaitable[None]]
+    | None
+)
+
+
+async def emit_stream(
+    callback: StreamingCallback,
+    event: StreamEvent | dict[str, Any],
+) -> None:
+    if callback is None:
+        return
+    result = callback(event)  # type: ignore[arg-type]
+    if hasattr(result, "__await__"):
+        await result  # type: ignore[misc]

operator_architecture-0.2.0.dist-info/METADATA

@@ -0,0 +1,216 @@
+Metadata-Version: 2.5
+Name: operator-architecture
+Version: 0.2.0
+Summary: Framework-agnostic multi-agent orchestration SDK (Operator Architecture)
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Operator Architecture
+
+**Framework-agnostic multi-agent orchestration SDK.**
+
+Operator Architecture (OA) manages **state**, **context**, **sub-agents**, and **orchestration**. It does **not** call LLMs, run tool loops, or ship coding tools. You plug in any agent runtime — Relay, LangChain, OpenAI Agents, HTTP services, or a plain async function.
+
+For the earlier coding-CLI / five-pillars vision, see [ORIGINAL_CONCEPT.md](ORIGINAL_CONCEPT.md).
+
+## Install
+
+```bash
+pip install -e .
+# or
+uv pip install -e .
+```
+
+Runtime dependencies: **none** (stdlib only).
+
+```python
+from operator_architecture import (
+    StateMachine,
+    Coordinator,
+    AgentSpec,
+    AgentRequest,
+    AgentResult,
+    callable_agent,
+)
+```
+
+## What OA owns vs what you own
+
+| Operator Architecture | Your host |
+|-----------------------|-----------|
+| `StateMachine`, `Coordinator`, `AgentSpec` | Agent implementations (`AgentRunner`) |
+| OpenAI-compatible message threads | Relay / LangChain / custom loops |
+| `commission` → stage → `accept` / `instruct` | Models, API keys, tools, MCP, FS |
+| Optional `streaming_callback` fan-in | Emitting stream events from runners |
+
+## Core objects
+
+### `AgentSpec` + `AgentRunner`
+
+Register any number of sub-agents. Each needs a **runner** OA will call:
+
+```python
+async def research(request: AgentRequest) -> AgentResult:
+    # call Relay, LangChain, HTTP, … — OA does not care
+    return AgentResult(content=f"Findings for: {request.objective}")
+
+researcher = AgentSpec(
+    name="researcher",
+    description="Read-only exploration",
+    skill="You are a careful researcher. Answer with concrete findings.",
+    runner=callable_agent(research),
+    model="my-model",  # metadata only
+)
+```
+
+Protocol:
+
+```python
+class AgentRunner(Protocol):
+    async def run(
+        self,
+        request: AgentRequest,
+        *,
+        streaming_callback: StreamingCallback = None,
+    ) -> AgentResult: ...
+```
+
+`AgentRequest` carries OpenAI-shaped `messages`, `objective`, `skill`, optional `checklist` / `agent_props`.  
+`AgentResult.content` is staged as `agent_message`.
+
+### `Coordinator`
+
+Owns the user-facing skill string and optional runner for `sm.run()`:
+
+```python
+coordinator = Coordinator(
+    skill="You operate the state machine…",  # default skill provided
+    runner=my_coordinator_runner,            # optional
+    model="coord-model",
+)
+```
+
+### `StateMachine`
+
+```python
+sm = StateMachine(coordinator=coordinator, agents=[researcher])
+```
+
+No process-global singleton — hold the instance yourself (`sm = StateMachine(...)`).
+
+## Lifecycle
+
+```text
+user → (optional) sm.run / host
+     → commission(agent, objective)
+         → AgentRunner.run(AgentRequest)
+         → stage agent_message  (status=staged)
+     → accept_agent_result(agent, index)   # compact result for core thread
+        or instruct_agent(agent, index, message)  # continue junior
+```
+
+### Direct API (always available)
+
+```python
+staged = await sm.commission("researcher", "Find all uses of vLLM")
+msg = sm.get_agent_message("researcher", 1)
+accepted = sm.accept("researcher", 1)          # or accept_agent_result
+# or:
+await sm.instruct("researcher", 1, "Also check Dockerfiles")
+
+sm.list_agents()
+sm.list_objectives()
+```
+
+Indexed access: `sm.agent("researcher")[1].agent_message`.
+
+### `sm.run` (optional)
+
+If `Coordinator.runner` is set, `await sm.run(user_text, streaming_callback=...)` appends the user message and invokes that runner with:
+
+- `metadata["tools"]` — orchestration callables
+- `metadata["tool_schemas"]` — OpenAI `tools[]` schemas
+
+**OA does not execute a tool loop.** Your runner (Relay, LangChain, …) must invoke those callables when the model requests them.
+
+```python
+tools = sm.orchestration_tools()
+# list_agents, commission, get_agent_message,
+# accept_agent_result, instruct_agent, list_objectives
+```
+
+## OpenAI-compatible context
+
+Coordinator and junior threads are lists of chat.completions-style dicts:
+
+```python
+{"role": "system"|"user"|"assistant"|"tool", "content": "...", ...}
+```
+
+Helpers: `Messages` (`.system()`, `.user()`, `.assistant()`, `.to_list()`).
+
+## `streaming_callback`
+
+Optional observability hook (UI, logs, websockets). Sync or async:
+
+```python
+async def on_stream(event: dict) -> None:
+    print(event["phase"], event.get("detail", "")[:80])
+
+await sm.commission("researcher", "…", streaming_callback=on_stream)
+# or
+await sm.run("…", streaming_callback=on_stream)
+```
+
+Phases: `start`, `token`, `tool_start`, `tool_result`, `tool_error`, `commissioned`, `done`, `fail`.  
+Runners may emit events; OA forwards them and also emits lifecycle events around commission.
+
+## Writing adapters
+
+| Adapter idea | Wraps |
+|--------------|--------|
+| `callable_agent(fn)` | Plain async/sync function (shipped) |
+| Relay agent | `encode.relay_async` / `courier_os.relay` inside `run()` |
+| LangChain agent | AgentExecutor / LangGraph; map messages ↔ LC messages |
+| HTTP agent | POST OpenAI-compatible or custom JSON API |
+
+OA never imports those libraries. Keep adapters in your host.
+
+### Minimal Relay sketch (host code)
+
+```python
+class RelayRunner:
+    def __init__(self, model, api_key, base_url, tools):
+        self.model, self.api_key, self.base_url, self.tools = model, api_key, base_url, tools
+
+    async def run(self, request, *, streaming_callback=None):
+        import encode
+        messages = encode.Messages()
+        for m in request.messages:
+            # map dicts into encode.Messages as needed
+            ...
+        out = await encode.relay_async(
+            model=self.model,
+            api_key=self.api_key,
+            base_url=self.base_url,
+            messages=messages,
+            tools=self.tools or request.metadata.get("tools"),
+        )
+        return AgentResult(content=out.content or "", raw=out)
+```
+
+## Example
+
+See [`examples/minimal_callable.py`](examples/minimal_callable.py).
+
+## Design boundaries
+
+- **Not** a coding CLI or competitor to Cursor/Claude Code
+- **Not** an inference or tool-loop SDK (use Courier OS, encode, agentloop, LangChain, …)
+- **Not** coupled to AXE or Courier OS — hosts may wrap them as runners
+
+## License / status
+
+Early SDK (`0.2.0`). API may evolve; the orchestration contract (commission / stage / accept) is the stable idea.

operator_architecture-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+operator_architecture/__init__.py,sha256=_GxNq2tUVCxbRAErCEvZIbAyjk6wH8j44doi2Us3Jrg,1043
+operator_architecture/agent.py,sha256=P7wtgWfSCg0OAMHdfbm1ftNTGx7T88cYnUeRGsHpGaY,4333
+operator_architecture/coordinator.py,sha256=G0MzTibtKL0SBMAwXi55lbZrfSE1HagUqa33ijR2Xnc,1526
+operator_architecture/machine.py,sha256=6Dx0jtJ5JUh4Y5MljarHyVQEltbj6SfETkqRLY4Gs-E,18763
+operator_architecture/messages.py,sha256=3K365AQKjmhYG7zbkJuTm2BBTI5IL0qkNBuEa5BkvIc,1960
+operator_architecture/orchestration.py,sha256=yKbbXSdZyE7lGxcm5CV-sibFOhEdHy4wlrAmxEIrOug,2585
+operator_architecture/streaming.py,sha256=-96FMN80nncSOR9aJxreIWywFXcnVmzvm2kRe0FpNFg,952
+operator_architecture-0.2.0.dist-info/METADATA,sha256=uj2VfxdYjNJ1c4gTIr0YysgaqMzCQwsiqxFUePtNQZM,6570
+operator_architecture-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+operator_architecture-0.2.0.dist-info/RECORD,,

operator_architecture-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any