ROMA (Recursive Open Meta-Agents)

ROMA is built on several key concepts for hierarchical task execution and agentic reasoning:

Core Concepts

• DSPy: The underlying declarative framework for prompting and tool integration.
• Prediction Strategy: The specific DSPy class or function used for reasoning (e.g., CoT, ReAct).
• SubTask: A Pydantic model representing a unit of work, containing a goal, task_type, and dependencies.
• NodeType: Indicates if the Atomizer chose to PLAN or EXECUTE.
• TaskType: A MECE classification for subtasks, including RETRIEVE, WRITE, THINK, CODE_INTERPRET, and IMAGE_GENERATION.
• Context Defaults: Keyword arguments passed to dspy.context(...) during calls.

Configuration & Storage

• FileStorage: Provides isolated directories per task execution using an Execution ID.
• DataStorage: An automatic Parquet storage system for large toolkit responses based on a size threshold.
• Base Path: The root directory for storage (supports local paths or S3 buckets).
• Profile: A named configuration preset (e.g., general, crypto_agent).
• Configuration Override: Runtime values that supersede profile or default settings.

Toolkits

• BaseToolkit: The abstract base class for all toolkits, handling storage integration and tool registration.
• REQUIRES_FILE_STORAGE: A metadata flag for toolkits that depend on FileStorage (e.g., FileToolkit).
• Tool Selection: Mechanisms to include or exclude specific tools from a toolkit.
• Storage Threshold: The size limit (in KB) that triggers Parquet format storage for responses.

ROMA processes tasks through a recursive loop involving four main stages:

1. Atomizer: Determines if a request is atomic (directly executable) or requires planning.
2. Planner: If planning is required, the task is decomposed into smaller subtasks. These subtasks are fed back into the Atomizer, creating a recursive process.
3. Executors: Handle atomic tasks. Executors can be LLMs, APIs, or other agents, provided they implement an agent.execute() interface.
4. Aggregator: Collects and integrates results from subtasks to produce the final answer to the original parent task.

Information Flow:

• Top-down: Tasks are decomposed into subtasks recursively.
• Bottom-up: Subtask results are aggregated upwards into solutions for parent tasks.
• Left-to-right: Subtasks that depend on previous outputs wait for those tasks to complete before execution.

def solve(task):
    if is_atomic(task):                 # Step 1: Atomizer
        return execute(task)            # Step 2: Executor
    else:
        subtasks = plan(task)           # Step 2: Planner
        results = []
        for subtask in subtasks:
            results.append(solve(subtask))  # Recursive call
        return aggregate(results)       # Step 3: Aggregator

# Entry point:
answer = solve(initial_request)

Set up persistent storage for execution data and tool results. You can use the local filesystem, S3 (via goofys), or PostgreSQL.

PostgreSQL Setup: Enable via POSTGRES_ENABLED and provide a DATABASE_URL. You can start PostgreSQL automatically using the just docker-up command.

Tool Result Storage: To reduce context size and handle large datasets, configure toolkits (like MCPToolkit) to store results larger than a specific threshold in Parquet format.

storage:
  base_path: ${oc.env:STORAGE_BASE_PATH,/opt/sentient}
  max_file_size: 104857600  # 100MB

  # PostgreSQL (execution tracking)
  postgres:
    enabled: ${oc.env:POSTGRES_ENABLED,true}
    connection_url: ${oc.env:DATABASE_URL,postgresql+asyncpg://localhost/roma_dspy}
    pool_size: 10
    max_overflow: 20

toolkits:
  - class_name: MCPToolkit
    toolkit_config:
      use_storage: true
      storage_threshold_kb: 10  # Store results > 10KB

For production environments requiring persistence (PostgreSQL), observability (MLflow), and an API server (FastAPI), use the Docker-based setup. This requires Docker, Docker Compose, and optionally the just command runner.

Setup Commands

Use just to automate the build and service startup:

# Interactive setup (prompts for E2B, S3, etc.)
just setup

# Or with a specific profile
just setup crypto_agent

# Manual Docker start options
just docker-up       # Basic (PostgreSQL + MinIO + API)
just docker-up-full  # With MLflow observability

Available Services

• REST API: http://localhost:8000/docs (FastAPI with interactive docs)
• PostgreSQL: Automatic persistence for execution history and checkpoints
• MinIO: S3-compatible storage at http://localhost:9001
• MLflow: Experiment tracking at http://localhost:5000 (requires docker-up-full)

# One-command setup (builds Docker, starts services)
just setup

# Or with specific profile
just setup crypto_agent

# Verify services running
curl http://localhost:8000/health

# Solve tasks via API
just solve "What is the capital of France?"