Metadata-Version: 2.4
Name: open-agent-compiler
Version: 1.16.5
Summary: Python-first agent framework: define composable agent trees once, compile them to multiple agent runtimes (opencode, Claude Code, Pi, Codex), auto-optimize them per harness and model with test-driven autoloops, and evolve repo-tailored coding harnesses.
Project-URL: Homepage, https://github.com/DehydratedWater/OpenAgentCompiler
Project-URL: Repository, https://github.com/DehydratedWater/OpenAgentCompiler
Project-URL: Documentation, https://dehydratedwater.github.io/OpenAgentCompiler/
Project-URL: Changelog, https://github.com/DehydratedWater/OpenAgentCompiler/releases
Author: Ignacy Daszkiewicz
License: MIT License
        
        Copyright (c) 2026 Ignacy Daszkiewicz
        
        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.
License-File: LICENSE
Keywords: agent,ai,claude-code,codex,coding-harness,compiler,framework,llm,opencode,pi-agent,prompt-optimization
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: loguru>=0.7.3
Requires-Dist: pydantic>=2.13.3
Requires-Dist: pyyaml>=6.0
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Requires-Dist: langchain-openai>=0.2; extra == 'langchain'
Provides-Extra: pydantic-ai
Requires-Dist: pydantic-ai-slim[openai]>=0.4; extra == 'pydantic-ai'
Description-Content-Type: text/markdown

# open-agent-compiler

Composable agent-tree compiler for [OpenCode](https://opencode.ai),
[Claude Code](https://claude.com/claude-code),
[Pi](https://pi.dev) (via [@tintinweb/pi-subagents](https://pi.dev/packages/@tintinweb/pi-subagents)),
and the [OpenAI Codex CLI](https://developers.openai.com/codex/subagents).
Define agents once as typed Python, compile them to any supported
runtime, test them with mocks, and improve them with closed-loop
optimization.

- **PyPI**: [`open-agent-compiler`](https://pypi.org/project/open-agent-compiler/)
- **Docs**: <https://dehydratedwater.github.io/OpenAgentCompiler/>

## What it does

Define an agent once in Python:

```python
from open_agent_compiler import (
    AgentDefinition, AgentHeader, AgentRegistry,
    CompilationConfig, ModelParameters,
    TemplateSlot, TemplateTree,
)

def registry() -> AgentRegistry:
    reg = AgentRegistry()
    agent = AgentDefinition(
        header=AgentHeader(agent_id="hello", name="hello",
                           description="Friendly greeter."),
        usage_explanation_long="A minimal greeting agent.",
        usage_explanation_short="greets",
        system_prompt="You are a friendly greeter. Reply in one sentence.",
    )
    aid = reg.register_agent("hello", agent,
        ModelParameters(model_name="zai-coding-plan/glm-4.5-air", temperature=0.7))
    reg.register_template(TemplateTree(name="t",
        slots=[TemplateSlot(name="primary", default_agent_id=aid)]))
    reg.create_compilation_config(CompilationConfig(name="prod", template_name="t"))
    return reg
```

Compile it into an opencode-loadable tree:

```bash
uv run oac compile myproj.agents:registry --config prod --target build
```

Run with OpenCode:

```bash
cd build && opencode run --agent primary "Hi"
> primary · glm-4.5-air
Hello there! Nice to meet you.
```

Or compile for Pi (requires the `@tintinweb/pi-subagents` extension for
subagent spawning plus `pi-permission-system` for permission enforcement):

```bash
uv run oac compile myproj.agents:registry --config prod --target build --dialect pi
cd build && pi -p --approve "Use the Agent tool to spawn the primary agent: Hi"
```

## Key features

- **Pydantic-modeled** agent/tool/skill/workflow definitions — no YAML
  hand-editing, types catch errors at registration time.
- **Multi-variant compilation** — same agent compiled side-by-side
  against different providers/models via `VariantSpec`. `SplitProfile`
  picks per-agent presets by declared `model_class`.
- **Dual tool format** — bash command allowlist or OpenCode-style
  JSON-schema custom_tool, per-agent or per-tool.
- **Built-in test framework** — `CapabilityTest` (introspection),
  `ToolTest` (mocked or real handler), `AgentTest` (end-to-end). 9
  evaluator kinds. JSONL artifacts. Incremental skip via composite hash.
- **Bundled infrastructure scripts** — `subagent_todo.py`,
  `workspace_io.py`, `opencode_manager.py` auto-included when the
  compiled tree references them.
- **Iterative improvement loop** — `oac improve` mutates prompts/tools/
  resources, evaluates candidates against your `OptimisationCriterion`,
  promotes winners.
- **Per-target adaptation** — `run_per_target_loops` tunes the same
  agent per (harness × model) cell — opencode/pi/codex *and* the
  in-process interactive tier — with per-target promotion slots
  (`oac promote --target pi+fast`), pluggable `HarnessRunner`s, and
  LLM-as-judge scoring. History lives in a SQLite run store; browse,
  load, unload, and roll back versions with `oac versions`.
- **Native tool calling** — `--native-tools` emits each harness's
  native tool form for json-contract tools: `.opencode/tool/*.ts`
  shims (opencode) or a generated MCP tools server (Claude Code /
  Codex), all bridging deterministically to the same Python scripts.
- **Evolve a coding harness** — `oac evolve <repo>` builds a
  repo-tailored harness (planner/implementer/reviewer + /plan,
  /implement, /review-pr skills mined from the repo's docs, commands,
  and change history) in a fully isolated clone, then evolves it
  against the repo's own commits (replay similarity) and a
  stronger-model teacher (gap-driven prompt AND workflow-structure
  mutation), shipping the result as a zip.
- **Project scaffolder** — `oac init` generates a Docker-compose'd
  project with FastAPI + cron + optional Postgres / Redis / Qdrant /
  Ollama / Langfuse. Cron POSTs JSON events to the FastAPI server which
  invokes the compiled agents.
- **Multi-dialect** — OpenCode (default) + Claude Code + Pi (via
  [@tintinweb/pi-subagents](https://pi.dev/packages/@tintinweb/pi-subagents)
  and [pi-permission-system](https://github.com/MasuRii/pi-permission-system))
  + Codex (`.codex/agents/*.toml` custom agents for the OpenAI Codex
  CLI), with a plug-in `Dialect` protocol for future runtimes.
- **Developer skill bundles** — `oac sync-skills` deploys opinionated
  markdown skill files into a project's `.opencode/skills/` and
  `.claude/skills/` so coding agents working in the repo know how to
  use the framework.

## Install

```bash
pip install open-agent-compiler
# or
uv add open-agent-compiler
```

For development on the framework itself:

```bash
git clone https://github.com/DehydratedWater/OpenAgentCompiler
cd OpenAgentCompiler
uv sync
uv run oac --help
```

## CLI

```
oac init <dir> --template web --llm anthropic …      # scaffold a new project
oac compile <factory> --config prod --target build   # compile agents
oac test <factory> --config prod                     # run embedded tests
oac improve <factory> --target X --criteria c.yaml   # iterative improvement
oac promote improved/X/LATEST.json                   # re-introduce a winner
oac sync-skills <project> --skills opencode,claude   # deploy dev skills
oac info <factory>                                   # introspect registry
```

## Examples gallery

| Example | Demonstrates |
|---|---|
| `examples/00_hello/` | minimum working agent end-to-end with z.ai glm-4.5-air |
| `examples/10_multi_provider/` | one agent compiled three ways: z.ai glm-4.5-air + glm-5.1 + local vLLM Qwen3.5-27B |
| `examples/20_optimization_run/` | weak agent improved via `oac improve` with glm-5.1 as the optimiser |
| `examples/80_pi_agents/` | orchestrator + subagents compiled for Pi runtime with pi-subagents |
| `examples/85_matrix_live_chat/` | capstone: one tree → 2 harnesses × 2 models, per-target autoloops (incl. interactive tier), live chat dispatching any variant |

All examples are tested end-to-end against real LLMs (see
`examples/README.md`).

## Documentation

**Start with the [Developer Guide](docs/dev-guide.md)** — the complete
walkthrough: setup, core concepts, all three dialects, the worker vs
interactive tier split, tools, workflows, variants, testing, the
improvement loop, CLI reference, and a full examples index. Dialect
deep-dive: [pi-agent-dialect.md](docs/dialects/pi.md).

## Documentation: developer skills

The framework ships 14 skill bundles you can deploy into any project
with `oac sync-skills` (highlights below; `oac sync-skills --help` for
the full set):

- `getting-started` — three commands you'll use most, agent shape
- `authoring-agents` — workflow vs system_prompt, modes, todo_mode
- `authoring-tools` — ScriptTool, MockableTool, AccessProfile
- `writing-tests` — CapabilityTest / ToolTest / AgentTest + evaluators
- `providers-and-models` — ModelPreset, per-agent model assignment
- `variants-and-profiles` — VariantSpec / SplitProfile / CompilationContext
- `docker-and-compose` — the scaffolded Docker setup + failure modes
- `improvement-loop` — `oac improve` + `oac promote`

```bash
uv run oac sync-skills ./myproject --skills opencode,claude
```

After this, coding agents (OpenCode or Claude Code) working in your
project read the skill files and know how to add agents, write tests,
debug Docker, configure providers, etc.

## Project layout

```
open_agent_compiler/
  __init__.py                # Public API re-exports
  cli/                       # `oac` CLI subcommands
  compiler/                  # The compile pipeline + dialect registry
    dialects/{opencode,claude_code,pi_agent}/
  improvement/               # Phase 6 iterative loop
    mutators/                # Mutator implementations
  model/                     # Pydantic models (agents/tools/skills/tests/…)
  runtime.py                 # ScriptTool base class
  scaffold/                  # `oac init` template engine
    files/                   # File generators (Dockerfile, compose, app, …)
  scripts/                   # Bundled handler scripts (auto-copied)
  skills/                    # Developer skill bundles
  testing/                   # Test runner + evaluators + artifacts
tests/                       # pytest tree (mirrors open_agent_compiler/)
examples/                    # Working end-to-end examples
```

## Status

Through Phase 36 (~36 numbered phases shipped). Headline features:

- **Composable agent trees** with `register_with_improvements`
  auto-merging promoted snapshots (Phase 10).
- **Multi-turn `AgentTest`** + sequenced / stateful `MockResponse`
  for streaming/monitoring scenarios (Phase 11).
- **Per-agent MCP allowlists** + bundled MCP-server scaffold via
  `--with-mcp-server` (Phases 12 + 24).
- **Tool-targeted mutators** (description, rules, bash-vs-json
  format) + `tool_failure_rate` criterion (Phase 13).
- **`ScriptTool.execute(input, resources)`** + `ResourceHandle`
  for clean DB / API bindings (Phase 15).
- **Composable context blocks** + `PromptAssembler` with
  volatility-aware ordering (Phase 19).
- **`TaskHandle`** + `SpawnAgentTool` for long-running and
  agent-spawned-from-tool patterns (Phases 20 + 21).
- **FastAPI dispatcher** with sync / async / fire-and-forget modes,
  variant routing, composable `RetryPolicy` (Phase 23).
- **`oac init --interactive`** + auto `uv sync` (Phase 25).
- **Dual-compile (`also_compile_as_primary`)**: every subagent slot
  can also emit a primary twin reachable directly via
  `opencode run --agent <name>-primary` or via opencode_manager
  dispatch (Phase 31).
- **`OpencodeRunner`** — the recommended sync eval runner with
  auto-retry on empty output + 0-1 score clamping (Phase 36).

19 numbered examples under `examples/`. 11 skills under
`open_agent_compiler/skills/content/` totalling 20+ documented patterns from real
project pain.

## Benchmark / verification

The framework's reproducibility benchmark is a complete spec for
building a real multi-agent media-tracking service (7 agents, 5
tools, Postgres, MCP, FastAPI dispatch) with the framework. Use it
to verify that a fresh agentic-coding instance can one-shot a real
project on top of `open_agent_compiler`. The reference
implementation is verified end-to-end (live search API, live z.ai
agent runs, live autoresearch producing a positive baseline delta).

## License

MIT.
