Metadata-Version: 2.4
Name: hyperloop
Version: 0.27.0
Summary: Orchestrator that walks tasks through composable process pipelines using AI agents
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: claude-agent-sdk>=0.1.60
Requires-Dist: httpx>=0.27
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: rich>=15.0.0
Requires-Dist: structlog>=24.0
Requires-Dist: typer>=0.24.1
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.115; extra == 'dashboard'
Requires-Dist: uvicorn>=0.30; extra == 'dashboard'
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pre-commit>=4.0; extra == 'dev'
Requires-Dist: pyright>=1.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.20; extra == 'otel'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.20; extra == 'otel'
Description-Content-Type: text/markdown

# hyperloop

A reconciler that keeps code in sync with specs using AI agents. Specs are desired state. Code is actual state. Hyperloop continuously closes the gap.

```
Spec (desired) <-> Code (actual) = Gap
Gap -> Work -> PR -> Gate -> Merge -> Gap closed
```

You don't manage tasks -- you manage specs. Tasks are an internal implementation detail, like Kubernetes pods. Want to add a feature? Update the spec. Want to cancel it? Remove it from the spec.

## Prerequisites

- Python 3.12+
- [kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize/) on PATH
- `git`
- `gh` CLI (for GitHub PR operations)
- An Anthropic API key, or Vertex AI / Bedrock credentials

## Install

```bash
pip install hyperloop
```

## Quickstart

```bash
mkdir my-project && cd my-project && git init && git commit --allow-empty -m init

# Write a spec
cat > specs/auth.md << 'EOF'
# User Authentication
Implement JWT-based auth. POST /auth/login, POST /auth/register, GET /auth/me.
Passwords hashed with bcrypt. JWTs expire after 24h.
EOF

# Initialize hyperloop structure
hyperloop init

# Run the orchestrator
export ANTHROPIC_API_KEY=your-key  # or CLAUDE_CODE_USE_VERTEX=1
hyperloop run

# With GitHub PR support
hyperloop run --repo owner/repo
```

## Reconciliation Cycle

Each cycle has four phases:

1. **COLLECT** -- reap finished workers, run cycle hooks (e.g. process-improver)
2. **INTAKE** -- detect spec gaps and failed tasks, invoke PM agent to propose new work
3. **ADVANCE** -- advance existing tasks through pipeline steps (gates, actions)
4. **SPAWN** -- decide which tasks need workers, compose prompts, spawn agents

The orchestrator halts when no gaps remain. Use `hyperloop watch` for continuous operation.

## Pipeline Primitives

Work moves through a pipeline defined in `process.yaml`. Four primitives:

| Primitive | What it does |
|---|---|
| `agent: X` | Spawn a worker agent with X's prompt template |
| `gate: X` | Block until an external signal (e.g. PR label, CI status) |
| `action: X` | Execute an operation (e.g. merge PR) |
| `loop:` | Wrap steps -- on fail restart from top, on pass continue |

Example pipeline:

```yaml
pipeline:
  - loop:
      - agent: implementer
      - agent: verifier
  - gate: pr-require-label
  - action: merge-pr
```

## Project Structure

After `hyperloop init`:

```
my-project/
├── .hyperloop.yaml                     # orchestrator config
├── .hyperloop/
│   ├── agents/
│   │   ├── kustomization.yaml          # composition point (base + process component)
│   │   └── process/
│   │       ├── kustomization.yaml      # process-improver writes here
│   │       └── process.yaml            # pipeline + gate/action/hook config
│   ├── state/
│   │   ├── tasks/                      # task metadata (YAML frontmatter)
│   │   └── reviews/                    # per-round review files
│   └── checks/                         # executable check scripts
└── specs/
    └── *.md                            # product specs (your domain)
```

`specs/` is yours -- product specs only. `.hyperloop/` is orchestrator-managed.

## Prompt Composition

Three layers, resolved via `kustomize build`:

| Layer | Source | What it provides |
|---|---|---|
| Base | hyperloop repo `base/` | Core agent prompts |
| Project overlay | gitops repo or in-repo patches | Project-specific `guidelines` |
| Process overlay | `.hyperloop/agents/process/` | Learned rules from process-improver |

At compose time the orchestrator injects: `prompt + guidelines + spec content + findings from prior rounds`.

## Configuration

```yaml
# .hyperloop.yaml

overlay: .hyperloop/agents/
base_branch: main
runtime: local                          # local | ambient

max_workers: 6
poll_interval: 30
max_task_rounds: 50
max_action_attempts: 3

notifications:
  type: github-comment                  # github-comment | null (default: null)
```

## Custom Processes

Override the default pipeline in `.hyperloop/agents/process/process.yaml`:

```yaml
pipeline:
  - loop:
      - agent: implementer
      - agent: verifier
  - gate: pr-require-label
  - action: merge-pr

gates:
  pr-require-label:
    type: label                         # label (configurable, default: lgtm)
  # pr-require-approval:               # alternative gate type
  #   type: pr-approval                 # checks GitHub PR review approvals

actions:
  merge-pr:
    type: pr-merge

hooks:
  after_reap:
    - type: process-improver
```

## Architecture

Hexagonal (ports and adapters). The domain is pure logic with no I/O. Ports define interfaces, adapters implement them. Seven concerns are separated:

| Port | Purpose |
|---|---|
| `SpecSource` | Where to read desired state |
| `StateStore` | Where task/worker state lives |
| `Runtime` | Where agent sessions execute |
| `GatePort` | How gates are evaluated |
| `ActionPort` | How pipeline actions execute |
| `NotificationPort` | How humans are told to act |
| `OrchestratorProbe` | Domain observability |

The default adapter set is git-native (git state store, git spec source, local worktrees for agent isolation), but the architecture is adapter-agnostic.

See `specs/spec.md` for the full specification.

## Development

```bash
uv sync --all-extras
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run pyright
```
