operator-architecture 0.2.0__tar.gz

operator_architecture-0.2.0/.gitignore

@@ -0,0 +1,15 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# IDE
+.idea/
+.vscode/
+*.iml

operator_architecture-0.2.0/.python-version

@@ -0,0 +1 @@
+3.14

operator_architecture-0.2.0/MEMORY.md

@@ -0,0 +1,24 @@
+# Operator Architecture memory
+
+## What this is
+- **Pure orchestration SDK** (`operator-architecture` → `import operator_architecture`)
+- Owns state, OpenAI-shaped context, sub-agent registry, commission → stage → accept/instruct
+- Does **not** call LLMs, run tool loops, or ship coding tools / TUI / CLI
+
+## Public API
+- `StateMachine`, `Coordinator`, `AgentSpec`, `AgentRequest`, `AgentResult`, `AgentRunner`
+- `Messages` (OpenAI chat dicts), `callable_agent`, `orchestration_tools` / `tool_schemas`
+- `streaming_callback` for host observability (`StreamEvent` phases)
+
+## Host contract
+- Each `AgentSpec.runner` implements `async run(request, *, streaming_callback=None) -> AgentResult`
+- Adapters (Relay, LangChain, HTTP) live in the host — zero coupling to encode / axe / courier-os
+
+## Layout
+- `src/operator_architecture/` — SDK only
+- `examples/minimal_callable.py` — no-LLM smoke example
+- `ORIGINAL_CONCEPT.md` — archived coding-operator vision
+- `README.md` — current SDK docs
+
+## Non-goals (here)
+- AXE / agentloop, Courier OS inference, Scout FS tools, SQLite/ACP (future optional modules)

operator_architecture-0.2.0/ORIGINAL_CONCEPT.md

@@ -0,0 +1,74 @@
+> **Historical document.** This describes an earlier coding-operator concept (CLI, five pillars, Rust/SQLite SM). It is **not** the Operator Architecture SDK contract. See [README.md](README.md) for the current orchestration SDK.
+
+# Operator Architecture Technical Specification
+
+## Overview
+The Operator Architecture is designed to solve the problem of "context explosion" in large-scale LLM-driven development. Instead of a single behemoth implementation that loses accuracy as context windows fill, this architecture splits complex tasks into focused, purpose-built **Sub-Agents**. Each sub-agent operates with hyper-efficient context management, receiving only the specific information required to complete its current objective, while a centralized state machine maintains the global truth.
+
+## Core Components
+
+### 1. The Coordinator
+The primary agent persona for user interaction. The Coordinator acts as the orchestrator and reviewer, translating high-level user intent into actionable objectives and validating the outputs of sub-agents. It is the sole interface for the human user.
+
+### 2. The State Machine
+The backbone of the entire system. Implemented in **Rust**, this layer manages orchestration and persistence via **SQLite**.
+- **Session Management**: Tracks active agent sessions.
+- **Plan & State**: Maintains the current plan, step statuses, and objective progress.
+- **Audit Log**: Tracks all file edits (diff logs) for traceability and safety.
+
+### 3. Sub-Agents (The 5 Pillars)
+Each sub-agent is specialized in a specific domain to minimize token noise and maximize reasoning capabilities:
+- **Researcher**: A read-only toolkit specialized in codebase navigation, grep, and semantic comprehension.
+- **Implementer**: A read/write toolkit capable of performing complex code modifications and surgical edits.
+- **Bash/Tester**: A terminal-access agent designed to execute commands, run test suites, and verify environment state.
+- **Documenter**: A specialized toolkit for generating, updating, and maintaining Markdown-based documentation.
+- **Planner**: A strategic agent responsible for breaking down high-level objectives into granular, executable implementation steps.
+
+## The Workflow
+
+### Commissioning
+The Coordinator does not simply "talk" to agents; it commissions them using the State Machine. It passes structured properties to sub-agents:
+- **Objective**: The specific goal of the sub-agent.
+- **Checklist**: A list of requirements to be met.
+- **Agent Props**: Context-specific metadata needed for the task.
+
+### Plan Execution
+Plans are executed incrementally:
+1. The **Planner** creates a sequence of steps.
+2. **Implementation Loop**. Each step triggers an implementation agent with the context of the plan overview, all the steps overview, it's specific step implementation plan, and the agent summary from previously completed steps.
+3. **Verification Loop**: Implementation steps can trigger the **Bash/Tester** agent automatically to verify that the code change satisfies the requirement before the step is marked as complete.
+
+### Context Efficiency
+To prevent hallucinations and token waste, agents do not receive full conversation histories. They receive:
+- A high-level **Plan Overview**.
+- The current **Step Objective**.
+- **Summaries** of prior successful steps.
+This ensures the LLM's attention is focused entirely on the task at hand.
+
+## The CLI & Server Model
+
+### Lifecycle Management
+The `operator` CLI manages a persistent background server:
+- `operator server --start`: Starts the orchestration server.
+- `operator server --stop`: Gracefully shuts down the server.
+- `operator server --bind <session>`: Attaches the CLI to an existing session/project.
+- `operator server --drop <session>`: Detaches the live session from the project.
+
+### Intelligent Automation
+The CLI is designed for ease of use: if a command is issued while the server is offline, the CLI automatically handles the start/bind sequence.
+
+### Extensibility
+The system exposes an **OpenAPI surface on port 9200**, allowing web-based dashboards or third-party tools to orchestrate agents and monitor the State Machine in real-time.
+
+This allows developers to integrate into IDEs or create their own visual agent windows that utilize the Operator Architecture.
+
+## Technical Stack
+- Python
+- **Persistence**: [SQLite](https://www.sqlite.org/) (Lightweight, file-based, and ACID-compliant for session and diff tracking).
+- **API**: REST/OpenAPI (For seamless integration). Using **FastAPI**
+- **Configuration**: Managed via a `.operator` directory containing the database and system settings.
+
+## Future Work
+- **Parallel Step Execution**: Allowing multiple non-dependent sub-agents to work simultaneously.
+- **Courier Cloud**: Integration for remote authentication and automated configuration population.
+

operator_architecture-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,207 @@
+# 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/examples/minimal_callable.py

@@ -0,0 +1,60 @@
+"""Minimal OA example — host-provided callable agents, no LLM libraries."""
+
+from __future__ import annotations
+
+import asyncio
+
+from operator_architecture import (
+    AgentRequest,
+    AgentResult,
+    AgentSpec,
+    Coordinator,
+    StateMachine,
+    callable_agent,
+)
+
+
+async def research(request: AgentRequest) -> AgentResult:
+    lines = [
+        f"Skill: {request.skill[:60]}…",
+        f"Objective: {request.objective}",
+    ]
+    if request.checklist:
+        lines.append("Checklist: " + ", ".join(request.checklist))
+    return AgentResult(content="\n".join(lines))
+
+
+async def main() -> None:
+    sm = StateMachine(
+        coordinator=Coordinator(),
+        agents=[
+            AgentSpec(
+                name="researcher",
+                description="Read-only exploration",
+                skill="You are a researcher. Be concrete.",
+                runner=callable_agent(research),
+            ),
+        ],
+    )
+
+    events: list[str] = []
+
+    async def on_stream(event: dict) -> None:
+        events.append(f"{event.get('agent')}:{event.get('phase')}")
+
+    staged = await sm.commission(
+        "researcher",
+        "Map where vLLM is configured",
+        checklist=["find config", "note versions"],
+        streaming_callback=on_stream,
+    )
+    print("staged:", staged["status"], staged["index"])
+    print("message:\n", sm.agent("researcher")[1].agent_message)
+    print("accept:", sm.accept("researcher", 1)["status"])
+    print("stream phases:", events)
+    print("agents:", sm.list_agents())
+    print("objectives:", sm.list_objectives())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

operator_architecture-0.2.0/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "operator-architecture"
+version = "0.2.0"
+description = "Framework-agnostic multi-agent orchestration SDK (Operator Architecture)"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/operator_architecture"]

operator_architecture-0.2.0/src/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"