ROMA-DSPy Quick Start

Get up and running with ROMA-DSPy in under 10 minutes!

What is ROMA-DSPy?

ROMA-DSPy is a framework for building production-ready AI agents using DSPy. It provides:

Hierarchical Task Decomposition - Break complex tasks into manageable subtasks
Modular Agent Architecture - Atomizer, Planner, Executor, Aggregator, Verifier
Extensive Toolkit System - File ops, code execution, web search, crypto data, and more
MCP Integration - Connect to any Model Context Protocol server
Production Features - REST API, PostgreSQL persistence, MLflow observability, Docker deployment

Prerequisites

Python 3.12+
Docker & Docker Compose (recommended for full features)
Just command runner (optional but recommended)

Install Just (Optional)

# macOS
brew install just

# Linux
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin

Quick Start (3 paths)

Choose your preferred setup method:

Path A: Docker (Recommended - Full Features)

Best for: Production-like environment with PostgreSQL, MLflow, and all features

Clone and Configure

git clone https://github.com/your-org/ROMA-DSPy.git
cd ROMA-DSPy

# Copy environment template
cp .env.example .env

Configure Environment Edit .env and add your API keys:

# Required
OPENROUTER_API_KEY=your_key_here

# Optional (for specific features)
E2B_API_KEY=your_key_here
EXA_API_KEY=your_key_here

Start Services

# Build and start all services
just docker-up

# Or with MLflow observability
just docker-up-full

# Check health
curl http://localhost:8000/health

Run Your First Task

# Via Docker CLI
just solve "What is the capital of France?"

# Or via REST API
curl -X POST http://localhost:8000/api/v1/executions \
  -H "Content-Type: application/json" \
  -d '{"goal": "What is the capital of France?"}'

Services Running:

API: http://localhost:8000
PostgreSQL: localhost:5432
MinIO: http://localhost:9001
MLflow: http://localhost:5000 (with --profile observability)

Path B: Local Python (Quick Testing)

Best for: Quick experimentation without Docker

Install

git clone https://github.com/your-org/ROMA-DSPy.git
cd ROMA-DSPy

# Install package
pip install -e .

Set API Keys
```
export OPENROUTER_API_KEY=your_key_here
```

Run

from roma_dspy.core.engine.solve import solve

result = solve("What is 25 * 47?")
print(result.answer)

Note: Local mode has limited features (no persistence, no API, no MLflow).

Path C: Crypto Agent (Domain-Specific Example)

Best for: Cryptocurrency analysis use case

Quick Setup
```
just docker-up
```

Run Crypto Analysis

# Get Bitcoin price
just solve "What is the current price of Bitcoin?" crypto_agent

# Complex analysis
just solve "Compare Bitcoin and Ethereum prices, analyze 7-day trends" crypto_agent

# DeFi analysis
just solve "Show top 10 DeFi protocols by TVL" crypto_agent

Crypto Agent Includes:

CoinGecko (15,000+ cryptocurrencies)
Binance (spot/futures markets)
DefiLlama (DeFi protocol data)
Arkham (blockchain analytics)
Exa (web search)

Just Commands Cheat Sheet

Basic Usage

just                      # List all commands
just solve "task"         # Solve task with Docker
just viz <execution_id>   # Visualize execution DAG

Docker Management

just docker-up            # Start services
just docker-up-full       # Start with MLflow
just docker-down          # Stop services
just docker-logs          # View logs
just docker-ps            # Check status
just docker-shell         # Open shell in container

Development

just install              # Install dependencies
just test                 # Run tests
just lint                 # Check code quality
just format               # Format code
just clean                # Clean cache

List Available Profiles

just list-profiles
# Output:
#   - crypto_agent
#   - general

Verify Installation

1. Check Health

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy",
  "version": "1.0.0",
  "storage_connected": true,
  "active_executions": 0,
  "uptime_seconds": 123.45
}

2. Test via CLI

# Simple calculation
just solve "Calculate 15% of 2500"

# Get execution ID from output, then visualize
just viz <execution_id>

3. Test via API

# Create execution (max_depth=1 or 2 recommended)
curl -X POST http://localhost:8000/api/v1/executions \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "What are the prime numbers between 1 and 20?",
    "max_depth": 2
  }' | jq

# Poll status (use execution_id from response)
curl http://localhost:8000/api/v1/executions/<execution_id>/status | jq

Configuration Profiles

ROMA-DSPy uses profiles to pre-configure agents for different use cases.

Available Profiles

Profile	Purpose	Models	Toolkits
general	General-purpose tasks	Gemini Flash + Claude Sonnet	E2B, FileToolkit, CalculatorToolkit, Exa MCP
crypto_agent	Cryptocurrency analysis	Multiple (task-aware)	CoinGecko, Binance, DefiLlama, Arkham, E2B

Using a Profile

# Via CLI (defaults to 'general' if not specified)
just solve "your task"
just solve "crypto task" crypto_agent

# Via API
curl -X POST http://localhost:8000/api/v1/executions \
  -H "Content-Type: application/json" \
  -d '{
    "goal": "Your task",
    "config_profile": "general"
  }'

Custom Profile

Create config/profiles/my_profile.yaml:

agents:
  executor:
    llm:
      model: openai/gpt-4o
      temperature: 0.3
    prediction_strategy: react
    toolkits:
      - class_name: FileToolkit
        enabled: true
      - class_name: CalculatorToolkit
        enabled: true

runtime:
  max_depth: 2  # 1-2 recommended for most tasks

Use it:

just solve "task" my_profile

See CONFIGURATION.md for complete guide.

Environment Variables

Required

# LLM Provider (choose one or use OpenRouter for all)
OPENROUTER_API_KEY=xxx        # Recommended (single key for all models)
# OR individual providers:
OPENAI_API_KEY=xxx
ANTHROPIC_API_KEY=xxx
GOOGLE_API_KEY=xxx

Optional Features

# Code Execution (E2B)
E2B_API_KEY=xxx

# Web Search (Exa MCP)
EXA_API_KEY=xxx

# Web Search (Serper Toolkit)
SERPER_API_KEY=xxx

# Crypto APIs (all public, no keys needed)
# CoinGecko, Binance, DefiLlama, Arkham work without keys

Storage & Database

# PostgreSQL (auto-configured in Docker)
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/roma_dspy
POSTGRES_ENABLED=true

# S3 Storage (optional)
STORAGE_BASE_PATH=/opt/sentient
ROMA_S3_BUCKET=your-bucket
AWS_ACCESS_KEY_ID=xxx
AWS_SECRET_ACCESS_KEY=xxx

Common Tasks

1. Solve a Task

# Simple (uses 'general' profile by default)
just solve "What is 2+2?"

# With specific profile
just solve "Analyze Bitcoin" crypto_agent

# With all options
just solve "Complex task" crypto_agent 5 true json
# Parameters: <task> [profile] [max_depth] [verbose] [output_format]

2. Check Execution

# List all executions
curl http://localhost:8000/api/v1/executions | jq

# Get specific execution
curl http://localhost:8000/api/v1/executions/<id> | jq

# Get execution status
curl http://localhost:8000/api/v1/executions/<id>/status | jq

3. View Logs

# All services
just docker-logs

# Specific service
just docker-logs-service roma-api
just docker-logs-service postgres
just docker-logs-service mlflow

4. Interactive Visualization

# After solving a task, get execution_id
just solve "Complex task"

# Visualize execution tree
just viz <execution_id>

Examples

Example 1: Simple Calculation

just solve "Calculate compound interest on $10,000 at 5% annual rate for 10 years"

Example 2: Web Research

just solve "Research the latest developments in quantum computing and summarize in 3 bullet points"

Example 3: Code Execution

just solve "Generate a Python script that creates a fibonacci sequence up to 100, execute it, and show results"

Example 4: Crypto Analysis

just solve "Compare Bitcoin and Ethereum market caps, 24h volumes, and price changes" crypto_agent

Example 5: File Operations

just solve "Create a JSON file with data about the top 5 programming languages and their use cases"

Troubleshooting

Docker not starting

# Check Docker is running
docker ps

# Rebuild images
just docker-down
just docker-build-clean
just docker-up

# Check logs
just docker-logs

API not responding

# Check health
curl http://localhost:8000/health

# Check container status
just docker-ps

# View logs
just docker-logs-service roma-api

Database connection errors

# Check postgres is running
docker ps | grep postgres

# Check connection
docker exec -it roma-dspy-postgres psql -U postgres -d roma_dspy -c "SELECT 1"

# Verify DATABASE_URL in .env matches docker-compose.yaml

Missing API keys

# Verify keys are set
docker exec -it roma-dspy-api env | grep API_KEY

# Restart after changing .env
just docker-restart

E2B not working

# Check E2B key is set
echo $E2B_API_KEY

# Test E2B connection
just e2b-test

# Build custom template (if using S3 mount)
just e2b-build

Next Steps

Learn More

Configuration Guide - Profiles, agents, settings
Toolkits Reference - All available toolkits
MCP Integration - Using MCP servers
API Reference - REST API endpoints
Deployment Guide - Production deployment
Observability - MLflow tracking

Explore Examples

# See all example configurations
ls config/examples/*/

# Try different examples
just solve "task" -c config/examples/basic/minimal.yaml

Customize

Create custom profiles in config/profiles/
Add custom toolkits (see TOOLKITS.md)
Configure agents per task type (see CONFIGURATION.md)

Deploy

# Production deployment
just deploy-full

# Check deployment
just health-check

REST API

ROMA-DSPy includes a production-ready REST API for programmatic access.

Quick Start

# Start API server (via Docker)
just docker-up

# Verify server is running
curl http://localhost:8000/health

API Documentation

FastAPI provides interactive API documentation:

Swagger UI (interactive testing): http://localhost:8000/docs
ReDoc (clean reference): http://localhost:8000/redoc
OpenAPI JSON: http://localhost:8000/openapi.json

Example Usage

# Start execution
curl -X POST http://localhost:8000/api/v1/executions \
  -H "Content-Type: application/json" \
  -d '{"goal": "What is 2+2?", "max_depth": 1}' | jq

# Get status (use execution_id from response)
curl http://localhost:8000/api/v1/executions/<execution_id>/status | jq

# Get metrics
curl http://localhost:8000/api/v1/executions/<execution_id>/metrics | jq

See http://localhost:8000/docs for complete API reference with all endpoints, schemas, and interactive testing.

Getting Help

Documentation: docs/ directory
Examples: config/examples/
Issues: GitHub Issues
Just Commands: Run just to see all available commands

You're all set! Start building with ROMA-DSPy 🚀

FilesExpand file tree

QUICKSTART.md

Latest commit

History