Metadata-Version: 2.4
Name: ralphx
Version: 0.1.0
Summary: Generic agent loop orchestration system with web dashboard
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 <jack@example.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: 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

**Generic Agent Loop Orchestration System**

RalphX is a domain-agnostic framework for building and running autonomous AI agent loops with a modern web dashboard. Define your agent workflows in YAML, run them with any LLM backend, and monitor everything in real-time.

## Features

- **Declarative Loop Definitions** - Define agent workflows in YAML, not code
- **Real-time Dashboard** - Monitor loop progress, view logs, control execution
- **Multiple LLM Backends** - Claude CLI, Anthropic API, OpenAI, Ollama
- **Work Item Management** - Track generated/consumed items with categories and phases
- **Production Ready** - Error handling, timeouts, graceful shutdown, persistence

## Quick Start

```bash
# Install
pip install ralphx

# Create a loop configuration
cat > my_loop.yaml << 'EOF'
name: my_research
display_name: "My Research Loop"
type: generator

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

mode_selection:
  strategy: fixed
  fixed_mode: default

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

limits:
  max_iterations: 10
  max_consecutive_errors: 3
EOF

# Run the loop
ralphx run my_loop.yaml

# Or start the dashboard
ralphx serve
```

## Architecture

```
┌─────────────────────────────────────────────┐
│           RalphX Dashboard (React)          │
├─────────────────────────────────────────────┤
│  Loop Control │ Work Items │ Live Logs      │
└─────────────────────────────────────────────┘
                    │ SSE
                    ▼
┌─────────────────────────────────────────────┐
│            RalphX API (FastAPI)             │
├─────────────────────────────────────────────┤
│  /loops  │  /items  │  /stream  │  /config  │
└─────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│          RalphX Core (Python)               │
├─────────────────────────────────────────────┤
│  Loop Executor │ LLM Adapters │ Stores      │
└─────────────────────────────────────────────┘
```

## 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

## Example Use Cases

### PRD Research (Ralph-style)
Generate user stories from design documents and web research.

### Code Review Loop
Automatically review code changes for security and style issues.

### Documentation Generator
Generate API docs from source code.

### Content Pipeline
Research topics and generate content at scale.

## Inspired By

RalphX is inspired by the Ralph system used in the HANK RCM project - an autonomous agent that continuously researches and implements features. RalphX generalizes these patterns into a reusable framework.

## License

MIT
