Metadata-Version: 2.4
Name: ralphx
Version: 0.1.5
Summary: Autonomous AI loop orchestration for Claude Code - define workflows in YAML, run autonomously, monitor in real-time
Project-URL: Homepage, https://github.com/jackneil/ralphx
Project-URL: Repository, https://github.com/jackneil/ralphx
Project-URL: Documentation, https://github.com/jackneil/ralphx#readme
Author-email: Jack Neil <jack@jackmd.com>
License-Expression: MIT
Keywords: agent,ai,automation,claude,llm,orchestration,workflow
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: aiofiles>=23.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: fastapi>=0.100
Requires-Dist: httpx>=0.24
Requires-Dist: pydantic>=2.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: sse-starlette>=1.0
Requires-Dist: typer>=0.9
Requires-Dist: uvicorn[standard]>=0.20
Requires-Dist: watchfiles>=0.20
Provides-Extra: dev
Requires-Dist: httpx>=0.24; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=0.1; extra == 'mcp'
Description-Content-Type: text/markdown

# RalphX

**Autonomous AI Loop Orchestration for Claude Code**

[![PyPI version](https://badge.fury.io/py/ralphx.svg)](https://badge.fury.io/py/ralphx)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

RalphX lets you define autonomous AI workflows in YAML and run them with Claude Code. Instead of manually prompting your AI assistant over and over, define a loop once and let it execute autonomously while you monitor progress in a real-time dashboard.

---

## Why RalphX?

**The Problem:** Running Claude Code manually for repetitive tasks is tedious. You find yourself copy-pasting prompts, tracking progress in your head, and losing context between sessions.

**The Solution:** RalphX provides:

- **Declarative Loops** - Define workflows in YAML, not code
- **Autonomous Execution** - Let loops run while you focus on other work
- **Real-time Monitoring** - Watch progress in a web dashboard with live logs
- **Work Item Tracking** - Manage generated/consumed items with categories and phases
- **Multiple Interfaces** - Web UI for visual users, MCP for Claude Code integration, CLI for automation

### Use Cases

- **Planning Loops** - Generate user stories from design docs
- **Implementation Loops** - Build features phase by phase
- **Research Loops** - Gather and synthesize information
- **Review Loops** - Automated code review and feedback
- **Content Pipelines** - Generate documentation or content at scale

---

## Quick Start

RalphX is designed to work with Claude Code. Just ask Claude to set it up for you.

### Ask Claude Code (Recommended)

Copy this prompt into Claude Code:

> "Install RalphX using conda and register this project. Then show me how to create my first workflow."

Claude will handle environment setup, installation, and project registration.

### Manual Installation

If you prefer to install manually:

```bash
# Create conda environment (we use conda, not venv)
conda create -n ralphx python=3.11 -y
conda activate ralphx

# Install RalphX
pip install ralphx

# Register your project and start the dashboard
ralphx add /path/to/your/project
ralphx serve
# Open http://localhost:8765
```

### MCP Integration (Optional)

Let Claude Code manage your loops through natural language:

```bash
# Add RalphX as an MCP server
claude mcp add ralphx -- ralphx mcp

# Now ask Claude: "List my RalphX projects" or "Start the planning loop"
```

---

## Core Concepts

| Concept | Description |
|---------|-------------|
| **Project** | A directory registered with RalphX, containing loops and work items |
| **Loop** | A YAML config defining an autonomous workflow (prompts, modes, limits) |
| **Work Item** | Generated/consumed data (stories, tasks, research notes, etc.) |
| **Mode** | An execution strategy within a loop (e.g., research mode, implementation mode) |
| **Iteration** | A single execution cycle of a loop |

---

## Creating Your First Loop

Create a file called `my_loop.yaml` in your project:

```yaml
name: research_loop
display_name: "Research Loop"
type: generator

modes:
  default:
    timeout: 300
    model: sonnet
    tools: [WebSearch, Read, Write]
    prompt_template: prompts/research.md

mode_selection:
  strategy: fixed
  fixed_mode: default

output:
  format: jsonl
  path: data/research_items.jsonl
  schema:
    required: [id, content, status]

limits:
  max_iterations: 10
  max_consecutive_errors: 3
```

### Key Fields

- **name** - Unique identifier for the loop
- **type** - `generator` (creates items) or `consumer` (processes items)
- **modes** - Different execution strategies with their own prompts and settings
- **mode_selection** - How to pick which mode runs (fixed, rotating, or conditional)
- **output** - Where generated items are stored
- **limits** - Safety limits to prevent runaway execution

Run it:

```bash
ralphx run my_loop.yaml --project my-project
```

---

## Web Dashboard

Start the dashboard with `ralphx serve` and open http://localhost:8765.

```
+----------------------------------------------------------+
|  RalphX Dashboard                              [Settings] |
+----------------------------------------------------------+
|                                                          |
|  Projects          Loops              Work Items         |
|  +--------------+  +----------------+ +----------------+ |
|  | my-project   |  | research_loop  | | 12 items       | |
|  | another-proj |  | planning_loop  | | Status: active | |
|  +--------------+  +----------------+ +----------------+ |
|                                                          |
|  Live Session Logs                                       |
|  +-----------------------------------------------------+ |
|  | [14:23:01] Starting iteration 5...                  | |
|  | [14:23:15] Generated item: user-story-042           | |
|  | [14:23:18] Iteration complete. Items: 42            | |
|  +-----------------------------------------------------+ |
|                                                          |
+----------------------------------------------------------+
```

**Features:**
- Real-time loop monitoring with SSE streaming
- Work item management (view, filter, edit)
- Session logs with timestamps
- Start/stop/pause loop controls
- Configuration editing

---

## MCP Integration (Claude Code)

[MCP (Model Context Protocol)](https://modelcontextprotocol.io/) lets Claude Code use external tools. RalphX exposes its functionality through MCP, allowing Claude to manage your loops conversationally.

### Setup

```bash
# Add RalphX as an MCP server
claude mcp add ralphx -- ralphx mcp
```

### Available Tools

Once connected, Claude Code has access to:

| Tool | Description |
|------|-------------|
| `ralphx_list_projects` | List all registered projects |
| `ralphx_get_project` | Get details about a specific project |
| `ralphx_list_loops` | List loops in a project |
| `ralphx_get_loop_status` | Check if a loop is running |
| `ralphx_start_loop` | Start a loop execution |
| `ralphx_stop_loop` | Stop a running loop |
| `ralphx_list_items` | List work items |
| `ralphx_add_item` | Add a new work item |
| `ralphx_update_item` | Update an existing item |

### Example Conversation

```
You: "What RalphX projects do I have?"
Claude: "You have 2 projects registered: 'my-app' and 'docs-site'"

You: "Start the planning loop on my-app"
Claude: "Started the planning loop. It will generate user stories from your
        design docs. I'll monitor progress - currently on iteration 1."

You: "How many items has it generated?"
Claude: "The loop has generated 8 user stories so far. Would you like me
        to show you the latest ones?"
```

---

## CLI Reference

| Command | Description |
|---------|-------------|
| `ralphx add <path>` | Register a project directory |
| `ralphx remove <name>` | Unregister a project |
| `ralphx list` | List all registered projects |
| `ralphx show <name>` | Show project details |
| `ralphx sync` | Sync loops from project directories |
| `ralphx loops` | List all loops across projects |
| `ralphx validate <loop>` | Validate a loop configuration |
| `ralphx run <loop>` | Run a loop |
| `ralphx serve` | Start the web dashboard |
| `ralphx mcp` | Start the MCP server |
| `ralphx doctor` | Check system health |
| `ralphx diagnose <loop>` | Debug a loop configuration |
| `ralphx why <loop>` | Explain why a loop stopped |
| `ralphx permissions` | Manage loop permissions |

Use `ralphx <command> --help` for detailed options.

---

## Loop Examples

### Planning Loop

Generate user stories from a design document:

```yaml
name: planning
display_name: "Story Generator"
type: generator

modes:
  generate:
    timeout: 600
    model: sonnet
    prompt_template: prompts/generate_stories.md

mode_selection:
  strategy: fixed
  fixed_mode: generate

output:
  format: jsonl
  path: data/user_stories.jsonl
  schema:
    required: [id, title, description, acceptance_criteria]

limits:
  max_iterations: 20
```

### Implementation Loop

Build features with phase awareness:

```yaml
name: implementation
display_name: "Feature Builder"
type: consumer

input:
  path: data/user_stories.jsonl
  filter:
    status: ready

modes:
  implement:
    timeout: 900
    model: sonnet
    tools: [Read, Write, Bash]
    prompt_template: prompts/implement.md

mode_selection:
  strategy: fixed
  fixed_mode: implement

limits:
  max_iterations: 50
  max_consecutive_errors: 5
```

---

## Architecture

```
+-----------------------------------------------+
|         RalphX Dashboard (React)              |
|  Loop Control | Work Items | Live Logs        |
+-----------------------------------------------+
                    | SSE
                    v
+-----------------------------------------------+
|           RalphX API (FastAPI)                |
|  /loops  |  /items  |  /stream  |  /config    |
+-----------------------------------------------+
                    |
                    v
+-----------------------------------------------+
|           RalphX Core (Python)                |
|  Loop Executor | LLM Adapters | Item Stores   |
+-----------------------------------------------+
                    |
                    v
+-----------------------------------------------+
|              Claude Code CLI                  |
|         (or other LLM backends)               |
+-----------------------------------------------+
```

**Components:**

- **Dashboard** - React SPA with real-time updates via SSE
- **API** - FastAPI server handling REST endpoints and streaming
- **Core** - Python library with loop execution, adapters, and storage
- **Adapters** - Pluggable LLM backends (Claude CLI, Anthropic API, etc.)

---

## Documentation

- [Design Overview](design/DESIGN.md) - Full system design and architecture
- [Loop Schema](design/LOOP_SCHEMA.md) - Complete YAML configuration reference
- [API Specification](design/API_SPEC.md) - REST API documentation

---

## License

MIT
