Metadata-Version: 2.4
Name: ralph-workflow
Version: 0.8.0b7
Summary: Vendor-neutral AI coding workflow orchestration with unattended execution, recovery, and verification.
Project-URL: Homepage, https://codeberg.org/RalphWorkflow/Ralph-Workflow
Project-URL: Documentation, https://codeberg.org/RalphWorkflow/Ralph-Workflow/src/branch/main/ralph-workflow/README.md
Project-URL: Repository, https://codeberg.org/RalphWorkflow/Ralph-Workflow
Project-URL: Issues, https://codeberg.org/RalphWorkflow/Ralph-Workflow/issues
Author: Mistlight
License: AGPL-3.0-or-later
License-File: LICENSE
Keywords: agent,ai,multi-agent,orchestration,pipeline
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.12
Requires-Dist: ddgs>=9.14.0
Requires-Dist: gitpython>=3.1
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: loguru>=0.7
Requires-Dist: mcp>=1.27.0
Requires-Dist: psutil>=5.9
Requires-Dist: pydantic>=2.7
Requires-Dist: rich-click>=1.8
Requires-Dist: rich>=13.0
Requires-Dist: tqdm>=4.66
Requires-Dist: typer>=0.12
Requires-Dist: watchdog>=4.0
Provides-Extra: bundle
Requires-Dist: pyinstaller>=6.0; extra == 'bundle'
Provides-Extra: dev
Requires-Dist: hatch; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pydantic>=2.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: readability-lxml>=0.8.1; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: selectolax>=0.3.21; extra == 'dev'
Requires-Dist: types-psutil>=5.9; extra == 'dev'
Requires-Dist: vulture>=2.16; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo>=2024.8.6; extra == 'docs'
Requires-Dist: linkify-it-py>=2; extra == 'docs'
Requires-Dist: myst-parser; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5; extra == 'docs'
Requires-Dist: sphinx-design>=0.5; extra == 'docs'
Requires-Dist: sphinx>=7; extra == 'docs'
Provides-Extra: web-search
Requires-Dist: brave-search-python-client>=0.4.27; extra == 'web-search'
Requires-Dist: exa-py>=2.12.0; extra == 'web-search'
Requires-Dist: tavily-python>=0.7.23; extra == 'web-search'
Provides-Extra: web-visit
Requires-Dist: readability-lxml>=0.8.1; extra == 'web-visit'
Requires-Dist: selectolax>=0.3.21; extra == 'web-visit'
Description-Content-Type: text/markdown

# Ralph Workflow (Python)

> Vendor-neutral AI coding workflow orchestration — unattended, auditable, and configured in your repo.

Ralph Workflow is a Python 3.12+ CLI package and framework for **policy-defined orchestration** of AI coding workflows. You decide which agent runs which phase, keep the workflow configuration in repo-local TOML, and let Ralph Workflow plan, implement, review, fix, and commit work for you. The runtime is a generic policy interpreter: all workflow behavior — phase routing, retry rules, analysis loops, commit semantics, verification gates, recovery routing, and parallel execution constraints — is declared in TOML policy files and enforced by the runtime without hardcoded phase knowledge.

The package exposes two entry points:

- `ralph` — the main CLI
- `ralph-mcp` — the standalone MCP server runtime

## What Ralph Workflow is

Ralph Workflow sits across AI coding vendors rather than locking you into one tool.
It can route work across Claude Code, Codex, OpenCode, and any OpenCode-wrapped model,
so you can use frontier models where reasoning matters and cheaper models where they are enough.

Key differentiators:

- **Vendor-neutral orchestration** — choose different agents for planning, development, review, fix, and commit
- **Cost arbitrage** — route frontier models to planning/review and cheaper models to development/fix
- **Unattended execution** — walk away and come back to a reviewed diff instead of babysitting an agent
- **Workflow config in repo** — phase graph, agent chains, retry budgets, and recovery rules live in versioned config
- **Recovery and verification discipline** — checkpoint/resume, failure classification, and evidence-based phase completion

## Policy-Driven Orchestration

Ralph Workflow's pipeline behavior is defined entirely by three TOML policy files:

| File | What it declares |
|------|------------------|
| `.agent/pipeline.toml` | Phase graph, roles, transitions, retry rules, analysis loops, commit semantics, recovery routing, parallel execution |
| `.agent/ralph-workflow.toml` | Agent chains and drain-to-chain bindings |
| `.agent/artifacts.toml` | Artifact contracts and decision vocabularies per drain |

The runtime validates that policy is semantically complete at startup and rejects incomplete configurations with actionable errors — it does not silently fall back to hidden built-in semantics.

**Policy surfaces that are configurable:**

- Phase roles (`execution`, `analysis`, `review`, `commit`, `verification`, `terminal`, `fanout_join`)
- Transition graph (`on_success`, `on_failure`, `on_loopback`)
- Analysis loop bounds and iteration counters
- Decision vocabulary and per-decision routing
- Budget counters and the commit counter that each commit phase increments
- Post-commit budget-guarded routing (`remaining`, `exhausted`, `no_review`)
- Retry and fallback strategy per phase
- Recovery cycle cap and terminal routing
- Parallel execution constraints
- Artifact requirements per drain

**To understand why Ralph Workflow routed a certain way**, read the active `.agent/pipeline.toml` — all routing decisions trace back to declared policy, not code branches.

**To add or change workflow behavior**, update `pipeline.toml`. Incomplete policy is rejected at startup with a `PolicyValidationError` listing the missing fields.

**To override a budget counter cap at runtime** without editing `pipeline.toml`, use the `--counter` flag:

```bash
ralph --counter iteration=2         # limit developer cycles to 2
ralph --counter reviewer_pass=1     # limit review passes to 1
```

Counter names must match `[budget_counters.<name>]` entries declared in `pipeline.toml`. Use `--check-policy` to confirm effective caps after overrides.

## Inspecting the active policy

Run `ralph --explain-policy` to print a visual representation of the active pipeline policy:

```bash
ralph --explain-policy
```

To inspect a project-local policy directory explicitly:

```bash
ralph --explain-policy --explain-policy-dir /path/to/.agent
```

Example output (abbreviated):

```
=ENTRY=>
+------------------+
|    planning      |
| role=execution   |
+------------------+
    |
    v
[fanout: max_workers=8, max_units=50]
+------------------+
|   development    |
| role=execution   |
+------------------+
    | loop back to development
    +---^  (returns to 'development' phase)
    |
    v
...
+------------------+
|    complete      |
| role=terminal    |
+------------------+
==SUCCESS==>
```

The diagram shows phases and their roles, the happy-path spine, loopback arrows with their return targets clearly marked, decision branches, fanout annotations for parallel phases, and terminal outcome markers. See [docs/migration/policy-v2.md](../docs/migration/policy-v2.md) for the policy model reference and migration guide.

## Install

### PyPI

```bash
pip install ralph-workflow
ralph --help
```

Requires Python 3.12+.

### pipx

```bash
python -m pip install pipx
python -m pipx ensurepath
pipx install ralph-workflow
ralph --help
```

### From source

```bash
git clone https://codeberg.org/RalphWorkflow/Ralph-Workflow.git
cd Ralph-Workflow/ralph-workflow
pip install -e .
ralph --version
```

## Quick start

```bash
cd /path/to/your/project
ralph --init
# edit PROMPT.md
ralph
```

`ralph --init` is the canonical form. Compatibility labels such as `default` are deprecated,
ignored, and no longer recommended in docs or scripts.

## First-run configuration

On first run, Ralph Workflow creates the standard project and user config files from bundled templates.

**User-global (created once, reused across projects):**
- `~/.config/ralph-workflow.toml` — main Ralph Workflow configuration
- `~/.config/ralph-workflow-mcp.toml` — MCP servers, web search, and web visit configuration

**Project-local (created by `ralph --init`, lives in your project directory):**
- `.agent/ralph-workflow.toml` — project-local main config override, including agent chains and drain bindings
- `.agent/mcp.toml` — project-local MCP override
- `.agent/pipeline.toml` — phase graph and orchestration settings
- `.agent/artifacts.toml` — MCP artifact contracts per drain

**Override precedence (highest to lowest):**
CLI flags → project-local (`.agent/`) → user-global (`~/.config/`) → bundled defaults

To reset configs from the bundled defaults (existing files are backed up to `<name>.bak`), run:

```bash
ralph --regenerate-config
```

Before your first real run, it is a good idea to validate your environment:

```bash
ralph --diagnose
```

## How a run works

When you run `ralph`, the workflow moves through a structured sequence of phases:

1. **Planning** — a planning agent reads `PROMPT.md` and produces a structured plan
2. **Development** — a developer agent implements the work
3. **Development analysis** — the workflow decides whether to iterate or continue
4. **Development commit** — changes are committed
5. **Review** — a reviewer agent inspects the result and produces issues if needed
6. **Review analysis** — the workflow decides whether to loop to fix or continue
7. **Fix** — a fix agent resolves issues found during review
8. **Review commit** — final changes are committed
9. **Complete** — the workflow ends successfully

If review finds significant problems, the review → fix cycle repeats up to the configured limit.

## Compatible agents

Ralph Workflow supports three built-in transport families and several naming forms on top of them.

| Identifier form | What it means | Example |
|---|---|---|
| `claude` | Claude Code using your currently selected Claude Code model/profile | `planning = ["claude"]` |
| `claude/<family>` | Force a Claude model family for that chain entry | `planning = ["claude/opus"]` |
| `codex` | OpenAI Codex CLI transport | `review = ["codex"]` |
| `opencode` | Base OpenCode transport | `development = ["opencode"]` |
| `opencode/<provider>/<model>` | OpenCode with an explicit provider/model target | `development = ["opencode/minimax/MiniMax-M2.7-highspeed"]` |
| `ccs/<alias>` | Claude Code Switch alias resolved dynamically | `planning = ["ccs/work"]` |
| custom `[agents.*]` name | Your own named agent definition in `ralph-workflow.toml` | `review = ["my-reviewer"]` |

Built-in transports:

| Transport | Strong at | Setup |
|---|---|---|
| Claude Code | Planning, complex reasoning, large context | `npm install -g @anthropic/claude-code` |
| Codex CLI | Structured review, cost-effective analysis | `npm install -g @openai/codex` |
| OpenCode | Multi-provider execution across OpenCode-supported models | [opencode.ai](https://opencode.ai) |
| CCS | Profile-based Claude Code switching and aliasing | Use `ccs/<alias>` directly |

## When Ralph Workflow fits

- Multi-step coding tasks that do not fit in one prompt
- Refactors, test suites, docs, or features that take longer unattended runs
- Work where you want to walk away and come back to reviewed commits
- Teams that need cost-controlled, auditable, or workflow-configured agent execution
- Anyone tired of paying frontier-model rates for grunt work cheaper models handle fine

## When it does not fit

- One-shot prompts you can answer interactively
- Pair-programming sessions where you want to steer in real time
- Tasks that finish manually before setup overhead pays off
- Workflows that need unpredictable mid-run human input

## Standalone MCP runtime

The package also ships `ralph-mcp`, a standalone MCP HTTP server runtime:

```bash
ralph-mcp --help
```

Use it when you want Ralph Workflow's MCP tool surface without running the full `ralph` pipeline.

## Verification

```bash
make verify
```

That runs:

- `ruff check ralph/ tests/`
- `uv run python -m mypy ralph/`
- `uv run --extra docs sphinx-build -b html docs/sphinx docs/sphinx/_build/html -W --keep-going`
- `uv run python -m ralph.verify_timeout --suite-timeout 30 -- pytest tests/ -q -n 8 --cov=ralph --cov-report=term-missing --cov-report=html --cov-fail-under 80`

For narrower local runs, use:

- `make docs` — build Sphinx HTML into `docs/sphinx/_build/html` with warnings treated as errors
- `make test` — full pytest suite without coverage
- `make test-unit` — everything under `tests/` except `tests/integration/`
- `make test-integration` — `tests/integration/` only

For the dead-code policy tooling, run the separate Vulture audit:

```bash
make dead-code
```

It is intentionally separate from `make verify` while the current dead-code backlog still exists; today the command proves the scanner wiring by failing on the code that still needs cleanup.

## Package map

- `ralph/cli/` — Typer CLI entry points and command plumbing
- `ralph/config/` — layered config loading and Pydantic models
- `ralph/pipeline/` — state, events, reducer, orchestrator, effects
- `ralph/phases/` — phase handlers and dispatch
- `ralph/agents/` — agent registry, chains, and invocation
- `ralph/mcp/` — MCP bridge, artifact handling, standalone server runtime
- `ralph/git/` — GitPython-backed repository helpers and rebase support
- `ralph/workspace/` — production and in-memory filesystem abstractions
- `ralph/recovery/` — failure classification, budgets, connectivity monitoring, and recovery controller

## Pydoc-first API reference

The public package docstrings are intended to stand on their own. Useful entry points:

```bash
python -m pydoc ralph
python -m pydoc ralph.cli
python -m pydoc ralph.pipeline
python -m pydoc ralph.mcp
python -m pydoc ralph.git
python -m pydoc ralph.workspace
python -m pydoc ralph.recovery
```

Use package/module docstrings for API understanding and this README for workflow-level guidance.

## Phase-output hardening

Ralph Workflow now treats several agent-driven phases as producing explicit evidence, not just a zero exit code.

- `review` must leave behind a fresh `.agent/artifacts/issues.json`.
- In same-workspace parallel mode, `development` and `fix` workers are judged by per-worker artifact evidence only: a worker succeeds when it submits an artifact under `.agent/workers/<unit_id>/artifacts/`. Repo-wide `git status` is never used to determine worker success in parallel mode. Exit code is retained as diagnostic information only.
- Planning keeps `.agent/artifacts/plan.json` as the canonical machine-readable artifact and mirrors it to `.agent/PLAN.md` as the human/agent handoff.
- The runner still removes per-phase artifacts before each invocation so interrupted runs cannot leak stale summaries or review findings into later phases.

Artifact contract:
- Use `.json` artifacts for Ralph Workflow's validation, routing, checkpointing, and other orchestrator-only logic.
- Use `.md` handoff files when a user or downstream AI agent needs to read the result of an earlier phase.
- Current mirrored handoffs are:
  - `.agent/PLAN.md`
  - `.agent/DEVELOPMENT_RESULT.md`
  - `.agent/ISSUES.md`
  - `.agent/FIX_RESULT.md`
  - `.agent/DEVELOPMENT_ANALYSIS_DECISION.md`
  - `.agent/REVIEW_ANALYSIS_DECISION.md`

This hardening is intentionally selective. Review and planning rely on explicit artifacts where Ralph Workflow needs structured evidence. In same-workspace parallel mode, `development` and `fix` workers are judged by per-worker artifact evidence under `.agent/workers/<unit_id>/artifacts/`; repo-wide workspace changes are not used as a success signal in parallel mode.

## Built-in web tools

### Web search (`web_search`)

Enabled by default. Uses a multi-backend fallback chain (ddgs, Tavily, Brave, Exa, SearXNG).
Configure via `[web_search]` in `mcp.toml`.

### URL fetching (`visit_url`)

A built-in `visit_url` tool fetches a single HTTP/HTTPS page and returns readable extracted text.
Requires the optional extras:

```bash
pip install "ralph-workflow[web-visit]"
```

Configure via `[web_visit]` in `mcp.toml`.
See [`docs/mcp/web-visit.md`](docs/mcp/web-visit.md) for the full reference.

For multi-page or JavaScript-rendered crawling, wire in [Crawl4AI](https://docs.crawl4ai.com/)
as an upstream MCP server — see [`docs/mcp/mcp-servers.md`](docs/mcp/mcp-servers.md).

## Multimodal MCP support (opt-in)

Ralph Workflow supports image-reading MCP tools via `read_image`. This feature is disabled by default.

Enable it in `.agent/mcp.toml`:

```toml
[media]
enabled = true
max_inline_bytes = 5242880  # 5 MiB default
```

When enabled:
- supported formats are PNG, JPEG, GIF, and WebP
- `read_image` only appears for clients that declare multimodal/image/media capability
- text-only clients keep the pre-multimodal tool set unchanged
- image payloads are returned as MCP image content blocks with base64-encoded data
- `max_inline_bytes` enforces the inline size guard (5 MiB by default)

### Compatibility contract

The multimodal support is designed with strict backward compatibility:

1. **Text-only clients unchanged** — Existing tools (`read_file`, `write_file`, etc.) continue to return text content blocks with the same shape.
2. **Client capability filtering** — `read_image` only appears in `tools/list` for clients that declare multimodal/image/media capability in the MCP `initialize` handshake.
3. **Upstream multimodal rejection** — If an upstream MCP server returns a non-text content block, Ralph Workflow rejects it with a clear error rather than silently passing it through.

### What text-only clients see

When a client connects without declaring multimodal support, `read_image` is **not visible** in `tools/list`, even if `media.enabled = true`. The text-only tool set is byte-equivalent to pre-multimodal behavior.

### What multimodal clients see

Clients that declare `capabilities.image`, `capabilities.media`, or `capabilities.multimodal` in the `initialize` request will see `read_image` in `tools/list` when `media.enabled = true`.

## Claude/CCS MCP safety note

Claude-compatible transports such as `claude` and `ccs` run through a stricter MCP path. Ralph Workflow still uses `--mcp-config` plus `--strict-mcp-config`, but it only emits `--tools ""` / `--allowedTools ...` when live MCP tool discovery succeeds with a non-empty allowlist. That avoids a brittle edge case in non-interactive Claude/CCS runs where empty-tool configurations and MCP bootstrapping can produce misleadingly successful no-op executions.

Ralph Workflow's Claude parser accepts both bare (`claude: ...`) and model-qualified (`claude/<model>: ...`) transcript prefixes emitted by the Claude CLI. Lifecycle-only markers (`message_delta`, `user`, `system (status=...)`, `thinking` without a payload) are automatically suppressed so they never appear as noise in the activity log. Free-form text and tool lines after the prefix are parsed normally.

## Parallel mode

When the planning phase produces two or more work units, Ralph Workflow runs them as parallel workers in the **same git checkout** (same-workspace mode v1). Each worker is restricted to its declared `allowed_directories` and writes its artifacts under `.agent/workers/<unit_id>/`. Workers share the checkout and write to it directly, without separate git branches; coordination uses edit-area fencing and artifact namespaces only. For the full guide including configuration, work unit structure, and success criteria, see [`docs/sphinx/parallel-mode.md`](docs/sphinx/parallel-mode.md).

Quick configuration (in `.agent/pipeline.toml`):

```toml
[phases.development.parallelization]
mode = "same_workspace"
max_parallel_workers = 4
max_work_units = 50
```

See [`docs/sphinx/parallel-mode.md`](docs/sphinx/parallel-mode.md) for the full guide.

## Recovery

Ralph Workflow treats failure recovery as a first-class concern. It supports checkpoint/resume,
failure classification, retry budgets, and connectivity-aware pause/resume behavior.

See [`docs/sphinx/recovery.md`](docs/sphinx/recovery.md) for the full guide.

## Long-content display

When agent output gets large, Ralph Workflow keeps the terminal readable by summarizing oversized content.
The deterministic headline summary layer is **enabled by default** and activates once content exceeds **4000** display cells.
That summary appears before the condensed output and gives you a stable, deterministic headline instead of making you scroll through a giant block.

If no clean headline can be extracted, Ralph Workflow shows the placeholder **`(no headline available)`**.
Inline summary lines are capped at **200** characters, and streaming end-line summaries are capped at **120** characters.

To disable the deterministic headline layer, use any of these values for `RALPH_LONG_CONTENT_SUMMARY`:
`0`, `false`, `no`, or `off`.
It is already on by default, so you do not need an "enable" value for it.

Ralph Workflow also supports an optional AI-generated summary layer labelled **`↳ ai-summary:`**.
That layer is controlled separately through the `RALPH_LONG_CONTENT_AI_SUMMARY` opt-in environment variable.

## Terminal display

All rendering goes through a single `DisplayContext` object that owns the console, colour
policy, terminal width, and adaptive layout limits. No renderer constructs its own console.

**Modes**

| Mode | Trigger | Headline cap | Condenser soft limit |
|------|---------|--------------|---------------------|
| `wide` | width ≥ 60 (default) | 120 chars | 400 cells |
| `compact` | width < 60, or `RALPH_FORCE_NARROW=1` | 80 chars | 240 cells |

**Environment knobs**

| Variable | Effect |
|----------|--------|
| `RALPH_FORCE_NARROW=1` | Force compact mode regardless of width |
| `NO_COLOR=1` | Disable colour output (standard, wins over `FORCE_COLOR`) |
| `FORCE_COLOR=1` | Force colour output even in non-TTY environments |
| `COLUMNS=<n>` | Override terminal width used for mode detection |

Colours come from the Okabe-Ito palette defined in `ralph/display/theme.py` and are
applied through semantic theme keys (`theme.banner.title`, `theme.text.muted`, etc.).
This makes it straightforward to adapt the palette without touching renderer code.

## Documentation

The full documentation lives in `docs/sphinx/` and is published under `/docs` at <https://ralphworkflow.com>.
Useful pages:

- [`docs/sphinx/getting-started.md`](docs/sphinx/getting-started.md) — step-by-step first-run walkthrough
- [`docs/sphinx/quickstart.md`](docs/sphinx/quickstart.md) — install, init, and run in five minutes
- [`docs/sphinx/concepts.md`](docs/sphinx/concepts.md) — phases, drains, agents, MCP artifacts, checkpoints
- [`docs/sphinx/cli.md`](docs/sphinx/cli.md) — all CLI flags and sub-commands
- [`docs/sphinx/configuration.md`](docs/sphinx/configuration.md) — config files, precedence, and FAQ
- [`docs/sphinx/reference.md`](docs/sphinx/reference.md) — operator-facing reference index
- [`docs/sphinx/recovery.md`](docs/sphinx/recovery.md) — failure classification, retry budgets, and recovery behavior
- [`docs/sphinx/parallel-mode.md`](docs/sphinx/parallel-mode.md) — same-checkout parallel execution for multi-work-unit plans
- [`docs/sphinx/troubleshooting.md`](docs/sphinx/troubleshooting.md) — common issues and FAQ

## License

[AGPL-3.0-or-later](LICENSE).

The framework is copyleft. The code Ralph Workflow generates belongs to you — no license encumbrance on outputs.
Use it commercially. Use it privately. Use it however you want.
