# AI-Orchestrator

A Python implementation of the [Symphony specification](https://github.com/openai/symphony/blob/main/SPEC.md) — a service that orchestrates coding agents to get project work done.

Symphony turns project work into isolated, autonomous implementation runs, allowing teams to manage work instead of supervising coding agents.

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    AI-Orchestrator                        │
├─────────────────────────────────────────────────────────┤
│  Policy Layer        │ WORKFLOW.md (repo-defined)        │
│  Configuration Layer │ Typed config from front matter    │
│  Coordination Layer  │ Orchestrator (poll/dispatch)      │
│  Execution Layer     │ Workspace + Agent subprocess      │
│  Integration Layer   │ Linear adapter                    │
│  Observability Layer │ Logs + HTTP status surface        │
└─────────────────────────────────────────────────────────┘
```

## Components

- **Workflow Loader** — Reads and parses `WORKFLOW.md` (YAML front matter + prompt template)
- **Config Layer** — Typed getters, defaults, env var resolution, validation
- **Issue Tracker Client** — Linear GraphQL adapter with pagination and normalization
- **Orchestrator** — Poll loop, dispatch, concurrency, retries, reconciliation
- **Workspace Manager** — Per-issue workspace lifecycle and hooks
- **Agent Runner** — Codex app-server subprocess integration
- **HTTP Server** — Optional REST API and dashboard for observability

## Quick Start

### Requirements

- Python 3.11+
- A Linear API key (set `LINEAR_API_KEY` env var)
- Codex CLI installed (`codex app-server`)

### Installation

```bash
cd AI-Orchestrator
pip install -e .
```

### Configuration

Create a `WORKFLOW.md` in your project root:

```markdown
---
tracker:
  kind: linear
  api_key: $LINEAR_API_KEY
  project_slug: your-project-slug
polling:
  interval_ms: 30000
workspace:
  root: ~/symphony_workspaces
agent:
  max_concurrent_agents: 5
  max_turns: 20
codex:
  command: codex app-server
  approval_policy: auto-edit
  turn_timeout_ms: 3600000
---

You are working on issue {{ issue.identifier }}: {{ issue.title }}

{{ issue.description }}

{% if attempt %}
This is retry attempt {{ attempt }}. Review previous work and continue.
{% endif %}
```

### Running

```bash
# Run with default WORKFLOW.md in current directory
ai-orchestrator

# Run with explicit workflow path
ai-orchestrator /path/to/WORKFLOW.md

# Run with HTTP server
ai-orchestrator --port 8080
```

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Type checking
mypy src/
```

## License

Apache License 2.0