Aragora

https://github.com/synaptent/aragora
Admin
Aragora is an auditable execution control plane for AI-assisted work that governs consequential...
Tokens:2,630,831
Snippets:29,659
Trust Score:3.1
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Quick Start Development Setup

Source: https://github.com/synaptent/aragora/blob/main/CONTRIBUTING.md

Commands to clone the repository, install dependencies, and verify the setup.

```bash
# Clone the repository
git clone https://github.com/aragora-ai/aragora.git
cd aragora

# Install development dependencies
make dev

# Run tests to verify setup
make test-fast

# Start the development server
make serve
```

--------------------------------

### Setup and Start Application

Source: https://github.com/synaptent/aragora/blob/main/examples/typescript-web/README.md

Commands to install dependencies, start the server, configure API keys, and launch the development environment.

```bash
# Install dependencies
npm install

# Start the Aragora server (in another terminal)
aragora serve --api-port 8080 --ws-port 8765

# Set API keys (on server side)
export ANTHROPIC_API_KEY="sk-..."
export OPENAI_API_KEY="sk-..."

# Start the web app
npm run dev
```

--------------------------------

### Install Dependencies and Start Development Server

Source: https://github.com/synaptent/aragora/blob/main/examples/remix/README.md

Commands to install project dependencies, set up environment variables by copying the example file, and start the development server.

```bash
npm install

cp .env.example .env
# Edit .env with your Aragora API URL and key

npm run dev
```

--------------------------------

### Manual Frontend Setup

Source: https://github.com/synaptent/aragora/blob/main/docs/getting-started/LOCAL_DEVELOPMENT.md

Installs frontend dependencies and starts the development server.

```bash
cd aragora/live
npm install

# Create local env from template
cp .env.local.example .env.local
# Defaults are correct for local dev:
#   NEXT_PUBLIC_API_URL=http://localhost:8080
#   NEXT_PUBLIC_WS_URL=ws://localhost:8765/ws

npm run dev
```

--------------------------------

### Quick Start: Set up Aragora

Source: https://github.com/synaptent/aragora/blob/main/docs-site/docs/getting-started/configuration.md

Copy the example configuration, set at least one AI provider API key, and start the server. Ensure you have the necessary dependencies installed.

```bash
cp .env.example .env

# Minimum required: at least one AI provider key
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

# Start the server
aragora serve --api-port 8080 --ws-port 8765
```

--------------------------------

### Quick Start Environment Setup

Source: https://github.com/synaptent/aragora/blob/main/docs/guides/FIRST_CONTRIBUTION.md

Commands to clone the repository, set up a virtual environment, install dependencies, configure API keys, and run the server.

```bash
# 1. Clone the repo
git clone https://github.com/synaptent/aragora.git
cd aragora

# 2. Set up environment
python -m venv .venv
source .venv/bin/activate  # or `.venv\Scripts\activate` on Windows
pip install -e ".[dev]"

# 3. Set up API keys (at least one)
export ANTHROPIC_API_KEY="your-key"
# or
export OPENAI_API_KEY="your-key"

# 4. Run tests to verify setup
pytest tests/debate/test_orchestrator.py -v

# 5. Start the server
aragora serve --api-port 8080 --ws-port 8765
```

--------------------------------

### Local Development Setup

Source: https://github.com/synaptent/aragora/blob/main/docs/DEPLOYMENT.md

Install the package and start the server in either offline or production-ready mode.

```bash
pip install aragora

# Offline mode — SQLite, no external services, no API keys needed
aragora serve --offline

# With API keys — full functionality
export ANTHROPIC_API_KEY=your-key
aragora serve
```

--------------------------------

### Initial Aragora Setup

Source: https://github.com/synaptent/aragora/blob/main/docs/reference/CONFIGURATION.md

Copy the example environment file, set a minimum required AI provider key, and start the Aragora server.

```bash
cp .env.example .env

echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env

aragora serve --api-port 8080 --ws-port 8765
```

--------------------------------

### Manual Backend Setup

Source: https://github.com/synaptent/aragora/blob/main/docs/getting-started/LOCAL_DEVELOPMENT.md

Installs dependencies and starts the backend server manually without Docker.

```bash
# From repository root
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Set at least one API key
export ANTHROPIC_API_KEY="sk-ant-..."

# Start the server
aragora serve --api-port 8080
```

--------------------------------

### Install Dependencies and Start Development Server

Source: https://github.com/synaptent/aragora/blob/main/docs/debate/FRONTEND_DEVELOPMENT.md

Navigate to the project directory, install dependencies using npm, and start the development server.

```bash
cd aragora/live

# Install dependencies
npm install

# Start development server
npm run dev
```

--------------------------------

### Install Dependencies and Start Server

Source: https://github.com/synaptent/aragora/blob/main/examples/nextjs-app-router/README.md

Use these bash commands to install project dependencies and start the development server.

```bash
npm install

# Set up environment variables
cp .env.example .env.local
# Edit .env.local with your Aragora API URL and key

# Start development server
npm run dev
```

--------------------------------

### Aragora Setup Wizard Example Session

Source: https://github.com/synaptent/aragora/blob/main/docs/guides/CLI_SETUP_GUIDE.md

An example of the interactive Aragora setup wizard, showing prompts for API keys, server ports, database selection, integrations, and security.

```text
============================================================
  Aragora Setup Wizard
============================================================

This wizard will help you configure Aragora.
Press Ctrl+C at any time to cancel.

[1/5] API Keys Configuration
----------------------------------------
Aragora requires at least one AI provider API key.

  Anthropic API Key (recommended): ********
  OpenAI API Key: ********

  Configure OpenRouter for fallback? (recommended) [Y/n]: y
  OpenRouter API Key: ********

[2/5] Testing API Keys
----------------------------------------
  Testing Anthropic key... OK (Valid)
  Testing OpenAI key... OK (Valid)
  Testing OpenRouter key... OK (Valid)

[3/5] Server Configuration
----------------------------------------
  HTTP Port [8080]:
  WebSocket Port [8765]:

  Database options:
    1. SQLite (simple, no setup required)
    2. PostgreSQL (production-ready, requires setup)
  Select database [1/2]: 1

[4/5] Integrations (Optional)
----------------------------------------
  Configure integrations to connect Aragora with external services.

  Configure Slack integration? [y/N]: n
  Configure GitHub integration? [y/N]: n
  Configure Telegram integration? [y/N]: n

[5/5] Security Configuration
----------------------------------------
  Generate encryption key for secrets? [Y/n]: y
    Generated key: a1b2c3d4e5f6g7h8...

============================================================
  Generating Configuration
============================================================
  Created: /path/to/project/.env

============================================================
  Setup Complete!
============================================================

Configuration summary:
  - Anthropic API: Configured
  - OpenAI API: Configured
  - OpenRouter: Configured
  - Database: SQLITE
  - HTTP Port: 8080

Next steps:
  1. Review .env file and adjust settings if needed
  2. Start the server: aragora serve
  3. Run a debate: aragora ask 'Your question here'

For more help, run: aragora --help

```

--------------------------------

### Quick Start Example

Source: https://github.com/synaptent/aragora/blob/main/docs/debate/EVIDENCE.md

A quick start example demonstrating how to use the ArXivConnector to search for evidence.

```APIDOC
## Quick Start with ArXivConnector

This example shows how to initialize the ArXivConnector and search for evidence related to 'large language model safety'.

### Method
```python
connector.search(query, max_results)
```

### Request Example
```python
from aragora.connectors import ArXivConnector, Evidence

# Create connector
connector = ArXivConnector()

# Search for evidence
results = connector.search("large language model safety", max_results=5)

for evidence in results:
    print(f"Title: {evidence.title}")
    print(f"Score: {evidence.reliability_score:.2f}")
    print(f"URL: {evidence.url}")
    print("---")
```

### Response Example
```
Title: Large Language Model Safety
Score: 0.85
URL: https://arxiv.org/abs/2301.00001
---
Title: Safety in LLMs
Score: 0.78
URL: https://arxiv.org/abs/2302.00002
---
```
```

--------------------------------

### Install as a service

Source: https://github.com/synaptent/aragora/blob/main/docs/ops/SELF_HOSTED_RUNNERS.md

Install and start the runner as a system service.

```bash
sudo ./svc.sh install
sudo ./svc.sh start
sudo ./svc.sh status
```

--------------------------------

### Install and Quick Start Aragora

Source: https://github.com/synaptent/aragora/blob/main/docs/guides/BETA_REVIEW_GUIDE.md

Install the package, configure API keys, and run a demo or local diff review.

```bash
# Install
pip install aragora

# Set at least one API key
export ANTHROPIC_API_KEY=sk-ant-...

# Try the demo (no API key needed)
aragora review --demo

# Review your code
git diff main | aragora review
```

--------------------------------

### Common Quickstart Flags

Source: https://github.com/synaptent/aragora/blob/main/docs/QUICKSTART_CLI.md

Examples of common command-line flags for customizing the quickstart execution.

```bash
aragora quickstart --question "Should we adopt microservices?"
aragora quickstart --demo
aragora quickstart --format md --no-browser
aragora quickstart --output ./my-first-receipt.html
aragora quickstart --rounds 3
```

--------------------------------

### Run TypeScript Quickstart

Source: https://github.com/synaptent/aragora/blob/main/docs/plans/2026-03-04-three-initiatives-plan.md

Example usage of the Aragora SDK in TypeScript.

```typescript
import { AragoraClient } from "@aragora/sdk";

const client = new AragoraClient({ baseUrl: "http://localhost:8080" });
const result = await client.debates.create({
  task: "Should we use microservices or a monolith?",
  agents: ["claude", "openai"],
  rounds: 3,
});
console.log(result.summary);
```

--------------------------------

### Install Dependencies and Setup Environment

Source: https://github.com/synaptent/aragora/blob/main/examples/nodejs-slack-bot/README.md

Install project dependencies and copy the environment template file. Ensure to edit the .env file with your specific tokens and configurations.

```bash
npm install

cp .env.example .env
```

--------------------------------

### Initialize and Use KnowledgeMound

Source: https://github.com/synaptent/aragora/blob/main/aragora/knowledge/README.md

Quick start example demonstrating initialization, storing knowledge, and semantic querying with KnowledgeMound. Requires setup of MoundConfig and KnowledgeMound instance.

```python
from aragora.knowledge.mound import KnowledgeMound, MoundConfig, IngestionRequest

# Initialize
config = MoundConfig(backend=MoundBackend.SQLITE)
mound = KnowledgeMound(config, workspace_id="team_a")
await mound.initialize()

# Store knowledge
result = await mound.store(IngestionRequest(
    content="Contracts require 90-day notice for termination",
    source_type=KnowledgeSource.DEBATE,
    debate_id="debate_123",
    confidence=0.95,
))

# Query semantically
results = await mound.query("contract notice requirements", limit=10)
for item in results.items:
    print(f"{item.content[:80]}... (confidence: {item.confidence})")

await mound.close()
```

--------------------------------

### Setup Aragora with pip

Source: https://github.com/synaptent/aragora/blob/main/docs/getting-started/SME_QUICKSTART.md

Install Aragora via pip and start the service in demo mode.

```bash
pip install aragora && cp .env.example .env   # set ANTHROPIC_API_KEY in .env
aragora serve --demo                          # API :8080, WebSocket :8765
```

--------------------------------

### Python SDK Setup

Source: https://github.com/synaptent/aragora/blob/main/docs/api/API_EXAMPLES.md

Basic setup for Python examples, including importing necessary libraries and defining base configuration for API calls.

```python
import httpx
import asyncio
from typing import Any

# Base configuration
BASE_URL = "http://localhost:8080"
API_TOKEN = "your-api-token"  # Set via ARAGORA_API_TOKEN env var

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json",
}
```

--------------------------------

### Run Interactive Setup Wizard

Source: https://github.com/synaptent/aragora/blob/main/docs/guides/GETTING_STARTED.md

Use the interactive setup wizard for an easy configuration of Aragora. It guides through API key setup, server port, database selection, and optional integrations.

```bash
aragora setup
```

--------------------------------

### Frontend Development: Install Dependencies and Run Server

Source: https://github.com/synaptent/aragora/blob/main/DEVELOPMENT.md

Navigate to the frontend directory and install dependencies using npm. Start the development server to see changes live.

```bash
cd aragora/live

# Install dependencies
npm install

# Development server
npm run dev
```

--------------------------------

### Run Aragora Quickstart

Source: https://github.com/synaptent/aragora/blob/main/docs-site/docs/api/cli.md

Initiates a fast onboarding process for new users. Use the --demo flag for a guided experience.

```bash
aragora quickstart --demo
```

--------------------------------

### Get and Install Skill from Marketplace

Source: https://github.com/synaptent/aragora/blob/main/docs/integrations/PLUGIN_DEVELOPMENT.md

Demonstrates how to retrieve skill details and install a skill using the marketplace API.

```python
listing = await marketplace.get_skill("weather-skill")
print(f"Rating: {listing.average_rating}/5")
print(f"Installs: {listing.install_count}")
```

```python
result = await marketplace.install(
    skill_id="weather-skill",
    tenant_id="my-tenant",
)
```

--------------------------------

### Quick Start: Standalone SDK (aragora-sdk)

Source: https://github.com/synaptent/aragora/blob/main/docs/SDK_GUIDE.md

A quick start example demonstrating how to use the standalone Aragora SDK to run a debate asynchronously.

```python
import asyncio
from aragora_sdk import AragoraClient

async def main():
    client = AragoraClient("http://localhost:8080")
    debate = await client.debates.run(
        task="Should we use microservices?",
        agents=["anthropic-api", "openai-api"],
    )
    print(f"Consensus: {debate.consensus.conclusion}")

asyncio.run(main())
```

--------------------------------

### Quick Start

Source: https://github.com/synaptent/aragora/blob/main/sdk/typescript/README.md

A quick guide to setting up the client and performing basic operations like creating and retrieving debates.

```APIDOC
## Quick Start

```typescript
import { createClient } from '@aragora/sdk';

const client = createClient({
  baseUrl: 'https://api.aragora.ai',
  apiKey: 'your-api-key'
});

// Create a debate
const result = await client.createDebate({
  task: 'What is the best programming language for web development?',
  agents: ['claude', 'gpt-4', 'gemini'],
  rounds: 3,
  consensus: 'majority'
});

console.log('Debate created:', result.debate_id);

// Get debate result
const debate = await client.getDebate(result.debate_id);
console.log('Final answer:', debate.final_answer);
```
```

--------------------------------

### Initialize Environment Variables

Source: https://github.com/synaptent/aragora/blob/main/docs/deployment/DOCKER_COMPOSE_GUIDE.md

Copy the example environment file to create a local configuration file before starting the services.

```bash
cp .env.example .env
# Edit .env with your API keys (at minimum: ANTHROPIC_API_KEY or OPENAI_API_KEY)
```

--------------------------------

### Initialize StripeConnector

Source: https://github.com/synaptent/aragora/blob/main/docs/connectors/STRIPE_GUIDE.md

Quick start example showing how to initialize the StripeConnector with credentials and create a customer.

```python
from aragora.connectors.payments.stripe import (
    StripeConnector,
    StripeCredentials,
)

credentials = StripeCredentials(
    secret_key="sk_test_...",
    webhook_secret="whsec_...",  # Optional, for webhooks
)

async with StripeConnector(credentials) as stripe:
    # Create a customer
    customer = await stripe.create_customer(
        email="customer@example.com",
        name="John Doe",
    )
    print(f"Created customer: {customer.id}")
```

--------------------------------

### Install and Start Aragora with Jupyter

Source: https://github.com/synaptent/aragora/blob/main/tutorials/README.md

Install Aragora in development mode and start the Jupyter notebook server to access interactive tutorials.

```bash
pip install -e .
cd tutorials
jupyter notebook
```

--------------------------------

### Install Aragora from Source

Source: https://github.com/synaptent/aragora/blob/main/docs-site/docs/getting-started/installation.md

Steps to clone the Aragora repository, install Python and Node.js dependencies, and start the server.

```bash
# Clone the repository
git clone https://github.com/aragora/aragora.git
cd aragora

# Install Python dependencies
pip install -e .

# Install Node dependencies (for frontend)
cd aragora/live
npm install

# Start the server
aragora serve --api-port 8080 --ws-port 8765
```

--------------------------------

### Aragora Workspace Quick Start

Source: https://github.com/synaptent/aragora/blob/main/docs/guides/WORKSPACE_GUIDE.md

A quick start guide to setting up a WorkspaceManager, creating a rig, defining a convoy with bead specifications, and starting its execution. Monitor progress using get_convoy_status.

```python
from aragora.workspace import WorkspaceManager, RigConfig

# Create workspace manager
ws = WorkspaceManager(workspace_root="/path/to/projects")

# Create a rig (per-repo container)
rig = await ws.create_rig(
    name="my-project",
    config=RigConfig(repo_url="https://github.com/org/repo"),
)

# Create a convoy with work items
convoy = await ws.create_convoy(
    rig_id=rig.rig_id,
    name="Feature Implementation",
    bead_specs=[
        {"title": "Write tests", "description": "Add unit tests"},
        {"title": "Implement feature", "depends_on": ["bead-1"]},
        {"title": "Update docs"},
    ],
)

# Start execution
await ws.start_convoy(convoy.convoy_id)

# Check status
status = await ws.get_convoy_status(convoy.convoy_id)
print(f"Progress: {status['progress_percent']}")
```

--------------------------------

### Install and Run Aragora CLI

Source: https://github.com/synaptent/aragora/blob/main/docs/SDK_QUICKSTART.md

Commands for installing the full platform, starting the local server, running debates, and accessing the REPL.

```bash
pip install aragora[all]

# Start the server (SQLite, no external dependencies)
aragora serve --offline

# Run a debate from the CLI
aragora decide "Should we migrate to Kubernetes?" --rounds 3

# Interactive REPL
aragora repl
```

--------------------------------

### Setup Aragora SDK

Source: https://github.com/synaptent/aragora/blob/main/examples/python-debate/README.md

Install the necessary dependencies and configure the environment for the Aragora server.

```bash
# Install Aragora SDK
pip install aragora-sdk python-dotenv

# Start the server (in another terminal)
aragora serve --api-port 8080 --ws-port 8765

# Set API keys (for debate functionality)
export ANTHROPIC_API_KEY="sk-..."
export OPENAI_API_KEY="sk-..."
```

--------------------------------

### Quickstart Compliance Workflow

Source: https://github.com/synaptent/aragora/blob/main/docs/compliance/EU_AI_ACT_GUIDE.md

Commands to install Aragora, classify an AI use case, and export a compliance bundle using demo data.

```bash
# Install (if not already)
pip install -e .

# Step 1: Classify your AI use case by risk tier
aragora compliance classify \
  "AI-powered CV screening for automated hiring decisions"

# Step 2: Export a compliance bundle (demo mode -- no real debate required)
aragora compliance export \
  --demo \
  --output-dir ./my-compliance-pack

# Step 3: Review what was generated
ls -la ./my-compliance-pack/
cat ./my-compliance-pack/README.md
```

--------------------------------

### Run quickstart onboarding

Source: https://github.com/synaptent/aragora/blob/main/docs/CLI_REFERENCE.md

Initialize a debate session using demo mode, specific questions, or live provider credentials.

```bash
aragora quickstart --demo --no-browser
aragora quickstart --question "Should we rewrite in Go?" --output ./receipt.html
aragora quickstart --provider openai --api-key sk-... --save-key --no-browser
```

--------------------------------

### Telegram Command Usage Examples

Source: https://github.com/synaptent/aragora/blob/main/docs/integrations/BOT_INTEGRATIONS.md

Interact with Aragora in Telegram using commands for starting debates, checking status, or getting help.

```bash
/start - Welcome message and introduction
/help - Show available commands
/debate Should we use microservices? - Start a debate
/ask Is Python better than JavaScript? - Alias for /debate
/status - Check Aragora status
```

--------------------------------

### Quick Start: Full SDK (aragora) - Asynchronous Usage

Source: https://github.com/synaptent/aragora/blob/main/docs/SDK_GUIDE.md

Example of using the full Aragora SDK asynchronously to create and wait for a debate to complete.

```python
import asyncio
from aragora.client import AragoraClient

async def main():
    async with AragoraClient(base_url="http://localhost:8080") as client:
        # Create and wait for debate completion
        debate = await client.debates.run(
            task="Design a distributed cache",
            timeout=600,  # 10 minutes
        )
        print(f"Status: {debate['status']}")

asyncio.run(main())
```

--------------------------------

### Quick Start with Docker

Source: https://github.com/synaptent/aragora/blob/main/docs/getting-started/LOCAL_DEVELOPMENT.md

Initializes the project using mock agents and SQLite without requiring API keys.

```bash
git clone https://github.com/aragora-ai/aragora.git && cd aragora
docker compose -f docker-compose.quickstart.yml up
```

--------------------------------

### Basic Debate in TypeScript

Source: https://github.com/synaptent/aragora/blob/main/docs-site/docs/guides/sdk-quickstart.md

Demonstrates a basic debate using the Aragora TypeScript SDK. This example is part of the quickstart guides and works offline.

```typescript
import { Debate } from "aragora-ts";

async function main() {
  const debate = new Debate({
    topic: "Is TypeScript better than JavaScript?",
    consensus: "majority",
    rounds: 3,
  });

  const receipt = await debate.run();
  console.log(receipt);
}

main();
```

--------------------------------

### Initialize Arena with Debate Protocol

Source: https://github.com/synaptent/aragora/blob/main/aragora/debate/README.md

Quick start example for setting up the debate environment, protocol, and arena. Requires an initialized environment and agent list.

```python
from aragora.debate import Arena, DebateProtocol
from aragora import Environment

env = Environment(task="Design a rate limiter for our API")
protocol = DebateProtocol(rounds=9, consensus="hybrid")
arena = Arena(environment=env, agents=agents, protocol=protocol)
result = await arena.run()
```

--------------------------------

### Post-Setup Verification Commands

Source: https://github.com/synaptent/aragora/blob/main/docs/guides/CLI_SETUP_GUIDE.md

Commands to verify Aragora's installation and configuration after setup. Includes checking system health, starting the server, and testing with a debate.

```bash
aragora doctor
```

```bash
aragora serve
```

```bash
aragora ask "What is 2+2?"
```

--------------------------------

### Connect and Setup Instance

Source: https://github.com/synaptent/aragora/blob/main/deploy/DEPLOYMENT_PLAN_ARCHIVED.md

Retrieves the instance IP address, establishes an SSH connection, and executes the remote setup script.

```bash
# Get the IP
LIGHTSAIL_IP=$(aws lightsail get-instance --instance-name aragora-api \
  --query 'instance.publicIpAddress' --output text)

# SSH into instance
ssh -i ~/.ssh/lightsail-aragora.pem ubuntu@$LIGHTSAIL_IP

# On the instance, run:
curl -sL https://raw.githubusercontent.com/an0mium/aragora/main/deploy/lightsail-setup.sh | bash
```

--------------------------------

### Gauntlet API: Run, Get Receipt, Run and Wait

Source: https://github.com/synaptent/aragora/blob/main/docs/SDK_GUIDE.md

Examples of using the Gauntlet API for adversarial validation, including starting a gauntlet, retrieving a receipt, and running until completion.

```python
# Start a gauntlet adversarial validation
response = client.gauntlet.run(
    task="Should we deploy this architecture to production?",
    attack_rounds=3,
    proposer_agent="anthropic-api",
    attacker_agents=["openai-api", "mistral-api"],
)

# Get decision receipt
receipt = client.gauntlet.get_receipt(response["gauntlet_id"])
print(f"Verdict: {receipt['verdict']}")

for finding in receipt.get("findings", []):
    print(f"- [{finding['severity']}] {finding['title']}")

# Run and wait for completion
result = client.gauntlet.run_and_wait(
    task="Validate our privacy policy compliance",
    attack_rounds=5,
    timeout=900,
)
```

--------------------------------

### Quick Start: Full SDK (aragora) - Synchronous Usage

Source: https://github.com/synaptent/aragora/blob/main/docs/SDK_GUIDE.md

Example of using the full Aragora SDK synchronously to create and retrieve a debate.

```python
from aragora.client import AragoraClient

# Create client
client = AragoraClient(base_url="http://localhost:8080")

# Create a debate
response = client.debates.create(task="Should we use microservices?")
print(f"Debate started: {response.debate_id}")

# Get debate result
debate = client.debates.get(response.debate_id)
print(f"Status: {debate.status}")
```

--------------------------------

### Install Dependencies

Source: https://github.com/synaptent/aragora/blob/main/examples/document-analysis/README.md

Installs the required Python packages for the document analysis example.

```bash
pip install -r examples/document-analysis/requirements.txt
```

--------------------------------

### Install Workflow Dependencies

Source: https://github.com/synaptent/aragora/blob/main/examples/workflow-automation/README.md

Install the necessary Python packages for the workflow automation example.

```bash
pip install -r examples/workflow-automation/requirements.txt
```

--------------------------------

### Quick Start: Initialize and Run LocalGateway

Source: https://github.com/synaptent/aragora/blob/main/docs/guides/GATEWAY_GUIDE.md

Use this snippet to quickly set up and start the LocalGateway with basic configuration. Ensure you have the necessary imports.

```python
from aragora.gateway import LocalGateway, GatewayConfig

# Create gateway with configuration
config = GatewayConfig(
    host="127.0.0.1",
    port=8090,
    api_key="your-secret-key",
    enable_auth=True,
)

gateway = LocalGateway(config=config)

# Start HTTP server
runner = await gateway.start_http()

# Gateway is now accepting requests at http://localhost:8090
print(f"Gateway running: {gateway.is_running}")

# Stop when done
await gateway.stop_http()
```

--------------------------------

### Common Event Payloads Examples

Source: https://github.com/synaptent/aragora/blob/main/docs/streaming/WEBSOCKET_EVENTS.md

A collection of JSON examples for various common stream event payloads, including debate start, round start, agent messages, critiques, errors, votes, and consensus.

```json
{ "type": "debate_start", "data": { "task": "...", "agents": ["a", "b"] } }
```

```json
{ "type": "round_start", "data": { "round": 1 } }
```

```json
{ "type": "agent_message", "data": { "content": "...", "role": "proposal" } }
```

```json
{ "type": "critique", "data": { "target": "...", "issues": ["..."], "severity": 0.4, "content": "..." } }
```

```json
{ "type": "agent_error", "data": { "error_type": "timeout", "message": "...", "recoverable": true, "phase": "proposal" } }
```

```json
{ "type": "vote", "data": { "vote": "...", "confidence": 0.72 } }
```

```json
{ "type": "consensus", "data": { "reached": true, "confidence": 0.85, "answer": "...", "status": "consensus_reached", "agent_failures": {} } }
```

```json
{ "type": "debate_end", "data": { "duration": 42.2, "rounds": 3 } }
```

--------------------------------

### Verify Server Startup

Source: https://github.com/synaptent/aragora/blob/main/docs/deployment/TROUBLESHOOTING.md

Check dependencies, importability, port availability, and start the server with debug logging.

```bash
# Verify Python dependencies
pip check

# Verify aragora is importable
python3 -c "import aragora; print(aragora.__version__)"

# Check for port conflicts
lsof -i :8080
lsof -i :8765

# Start with verbose logging
ARAGORA_LOG_LEVEL=DEBUG aragora serve --api-port 8080 --ws-port 8765
```

--------------------------------

### Local Development

Source: https://github.com/synaptent/aragora/blob/main/docs-site/DEPLOY.md

Start the local development server for previewing documentation.

```bash
cd docs-site
npm install
npm start
```

--------------------------------

### Setup Aragora with Docker

Source: https://github.com/synaptent/aragora/blob/main/docs/getting-started/SME_QUICKSTART.md

Initialize the Aragora environment using Docker Compose for a quickstart setup or production stack.

```bash
git clone https://github.com/aragora-ai/aragora.git && cd aragora
docker compose -f docker-compose.quickstart.yml up -d
```

```bash
cp .env.example .env
echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env   # at minimum
docker compose -f docker-compose.quickstart.yml up -d --force-recreate
```

```bash
cp .env.example .env   # set ANTHROPIC_API_KEY, optionally OPENAI_API_KEY
docker compose -f docker-compose.sme.yml up -d
# API at :8080, Grafana at :3001 (admin/admin)
```

--------------------------------

### PostgreSQL Connection String Examples

Source: https://github.com/synaptent/aragora/blob/main/docs/reference/CONFIGURATION.md

Examples of PostgreSQL connection strings for Supabase, AWS RDS, and local setups.

```bash
DATABASE_URL=postgresql://postgres.[ref]:[pass]@aws-0-us-west-1.pooler.supabase.com:6543/postgres
```

```bash
DATABASE_URL=postgresql://admin:password@mydb.xxxx.us-west-2.rds.amazonaws.com:5432/aragora
```

```bash
DATABASE_URL=postgresql://user:pass@localhost:5432/aragora
```

--------------------------------

### Get Subscription Response Example

Source: https://github.com/synaptent/aragora/blob/main/docs/api/ADMIN_API_REFERENCE.md

Example JSON response detailing subscription plan, status, and billing period.

```json
{
  "subscription_id": "sub-123",
  "plan": {
    "id": "plan-enterprise",
    "name": "Enterprise",
    "features": ["unlimited_debates", "priority_support", "sla_guarantee"]
  },
  "status": "active",
  "current_period_start": "2024-01-01T00:00:00Z",
  "current_period_end": "2024-02-01T00:00:00Z",
  "cancel_at_period_end": false
}
```

--------------------------------

### Run Aragora SDK Examples

Source: https://github.com/synaptent/aragora/blob/main/sdk/python/examples/README.md

Demonstrates how to run Aragora SDK examples, including dry runs, actual API calls, and using a custom API URL.

```bash
# Run any example (dry run - shows patterns without API calls)
python examples/basic_debate.py

# Run with actual API calls
RUN_EXAMPLES=true python examples/knowledge_integration.py

# Run with a custom API URL
ARAGORA_API_URL=http://localhost:8080 python examples/basic_debate.py
```

--------------------------------

### GET /api/podcast/episodes Response Example

Source: https://github.com/synaptent/aragora/blob/main/docs/integrations/BROADCAST.md

Example JSON response for the /api/podcast/episodes endpoint, listing available podcast episodes with metadata.

```json
{
  "episodes": [
    {
      "debate_id": "abc123",
      "task": "Rate Limiting Strategy",
      "agents": ["claude-visionary", "gemini-visionary"],
      "audio_url": "https://api.aragora.ai/audio/abc123.mp3",
      "duration_seconds": 180,
      "file_size_bytes": 2880000,
      "generated_at": "2026-01-09T10:00:00Z"
    }
  ],
  "count": 1,
  "feed_url": "/api/podcast/feed.xml"
}
```

--------------------------------

### Install Certbot for Manual Certificate Setup

Source: https://github.com/synaptent/aragora/blob/main/docs/deployment/TLS.md

Installs Certbot, a tool for obtaining and renewing Let's Encrypt certificates. Choose the installation method appropriate for your system (apt or pip).

```bash
# Ubuntu/Debian
apt-get install certbot

# Or via pip
pip install certbot
```

--------------------------------

### Production Build and Start

Source: https://github.com/synaptent/aragora/blob/main/docs/debate/FRONTEND_DEVELOPMENT.md

Commands to build the project for production and start the production server.

```bash
# Build for production
npm run build

# Start production server
npm start
```

--------------------------------

### Execute Live Founder-Loop Proof

Source: https://github.com/synaptent/aragora/blob/main/docs/plans/2026-03-26-pmf-14-day-execution-plan.md

Runs the Aragora CLI quickstart command with a specific user ID to verify the dogfood pipeline.

```bash
ARAGORA_USER_ID=an0mium \
python3 -m aragora.cli.main quickstart \
  --question "Should Aragora use its own dogfood pipeline to close the remaining PMF gaps?" \
  --no-browser
```

--------------------------------

### Run Startup Sequence

Source: https://github.com/synaptent/aragora/blob/main/aragora/server/README.md

Initializes the server with options for graceful degradation or strict Kubernetes-compatible mode.

```python
from aragora.server.startup import run_startup_sequence

# Graceful degradation mode
await run_startup_sequence(graceful_degradation=True)

# Strict mode (Kubernetes)
await run_startup_sequence(graceful_degradation=False)
```

--------------------------------

### Get Genome Lineage API Response

Source: https://github.com/synaptent/aragora/blob/main/docs-site/docs/advanced/genesis.md

Example JSON response for the GET /api/genesis/lineage/{genome_id} endpoint, showing the evolutionary ancestry of a genome.

```json
{
  "genome_id": "claude-systems-v3",
  "lineage": [
    {
      "genome_id": "claude-systems-v3",
      "generation": 3,
      "fitness_score": 0.92,
      "parent_ids": ["claude-systems-v2"],
      "event_type": "mutation",
      "created_at": "2026-01-10T10:00:00Z"
    },
    {
      "genome_id": "claude-systems-v2",
      "generation": 2,
      "fitness_score": 0.85,
      "parent_ids": ["claude-systems-v1", "grok-perf-v1"],
      "event_type": "crossover",
      "created_at": "2026-01-09T15:30:00Z"
    },
    {
      "genome_id": "claude-systems-v1",
      "generation": 1,
      "fitness_score": 0.78,
      "parent_ids": ["claude-base-v1"],
      "event_type": "mutation",
      "created_at": "2026-01-08T09:00:00Z"
    },
    {
      "genome_id": "claude-base-v1",
      "generation": 0,
      "fitness_score": 0.65,
      "parent_ids": [],
      "event_type": "spawn",
      "created_at": "2026-01-07T12:00:00Z"
    }
  ],
  "generations": 4
}
```

--------------------------------

### Run Aragora CLI Setup

Source: https://github.com/synaptent/aragora/blob/main/docs/guides/CLI_SETUP_GUIDE.md

Initiates the Aragora setup process. Use `--minimal` for essential settings or `--yes` for non-interactive setup with defaults.

```bash
aragora setup
```

```bash
aragora setup --minimal
```

```bash
aragora setup --yes
```

--------------------------------

### Development Environment Setup

Source: https://github.com/synaptent/aragora/blob/main/docs/DEPLOYMENT.md

Prepare the local environment file for development.

```bash
cp .env.template .env  # fill in API keys
```

--------------------------------

### Manual Configuration with .env

Source: https://github.com/synaptent/aragora/blob/main/docs-site/docs/getting-started/overview.md

Copy the starter .env file and edit it to include at least one AI provider API key. Optionally, set a data directory.

```bash
cp .env.starter .env
```

```dotenv
# Required: At least one of these
ANTHROPIC_API_KEY=sk-ant-xxx     # Claude (recommended)
OPENAI_API_KEY=sk-xxx            # GPT-4
GEMINI_API_KEY=AIzaSy...         # Gemini
XAI_API_KEY=xai-xxx              # Grok
MISTRAL_API_KEY=xxx              # Mistral (optional)
OPENROUTER_API_KEY=sk-or-xxx     # OpenRouter (optional)
```

```bash
ARAGORA_DATA_DIR=.nomic
```

--------------------------------

### Start MCP Server using Python

Source: https://github.com/synaptent/aragora/blob/main/docs-site/docs/guides/mcp-advanced.md

Use this command to start the MCP server. Ensure Python is installed and the aragora package is available in your environment.

```bash
# Start MCP server
python -m aragora.mcp.server
```

--------------------------------

### Setup Aragora Server on EC2

Source: https://github.com/synaptent/aragora/blob/main/deploy/QUICK_SETUP.md

SSH into the EC2 instance, run the same setup script as Lightsail, configure environment variables, and start the Aragora service.

```bash
# SSH into server
ssh -i your-key.pem ubuntu@<EC2_IP>

# Run setup (same as Lightsail)
git clone https://github.com/an0mium/aragora.git
cd aragora
chmod +x deploy/lightsail-setup.sh
sudo ./deploy/lightsail-setup.sh

# Configure and start
sudo nano /etc/aragora/env
sudo systemctl start aragora
```

--------------------------------

### Enable Metrics and Start Service

Source: https://github.com/synaptent/aragora/blob/main/docs/enterprise/ENTERPRISE_FEATURES.md

Configure metrics port and enable monitoring before starting the server.

```bash
# Start with metrics enabled
export METRICS_ENABLED=true
export METRICS_PORT=9090
aragora serve
```

--------------------------------

### Start Dashboard

Source: https://github.com/synaptent/aragora/blob/main/docs/guides/GETTING_STARTED.md

Launch the local dashboard server.

```bash
aragora serve
# Open http://localhost:8080
```

--------------------------------

### Get Usage Response Example

Source: https://github.com/synaptent/aragora/blob/main/docs/api/ADMIN_API_REFERENCE.md

Example JSON response for organization or user usage metrics, including detailed usage breakdown and cost information.

```json
{
  "org_id": "org-456",
  "period": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "usage": {
    "debates": 150,
    "tokens_in": 2500000,
    "tokens_out": 1200000,
    "api_calls": 5000,
    "storage_bytes": 104857600
  },
  "costs": {
    "total_usd": 125.50,
    "by_provider": {
      "anthropic": 75.00,
      "openai": 45.00,
      "google": 5.50
    }
  }
}
```

--------------------------------

### Manage Frontend Build and Server

Source: https://github.com/synaptent/aragora/blob/main/docs-site/docs/operations/troubleshooting.md

Commands to build the frontend and start the development server.

```bash
cd aragora/live
npm run build
```

```bash
npm run dev
```

--------------------------------

### Get Genome Descendants API Response

Source: https://github.com/synaptent/aragora/blob/main/docs-site/docs/advanced/genesis.md

Example JSON response for the GET /api/genesis/descendants/{genome_id} endpoint, illustrating the forward-looking family tree of a genome.

```json
{
  "genome_id": "claude-base-v1",
  "descendants": [
    {
      "genome_id": "claude-systems-v1",
      "name": "Systems Specialist",
      "generation": 1,
      "fitness_score": 0.78,
      "parent_ids": ["claude-base-v1"],
      "depth": 1
    },
    {
      "genome_id": "claude-systems-v2",
      "name": "Systems Specialist v2",
      "generation": 2,
      "fitness_score": 0.85,
      "parent_ids": ["claude-systems-v1", "grok-perf-v1"],
      "depth": 2
    },
    {
      "genome_id": "claude-systems-v3",
      "name": "Systems Specialist v3",
      "generation": 3,
      "fitness_score": 0.92,
      "parent_ids": ["claude-systems-v2"],
      "depth": 3
    }
  ],
  "total_descendants": 3,
  "max_depth_reached": 3
}
```

--------------------------------

### Run Billing and Usage Example

Source: https://github.com/synaptent/aragora/blob/main/sdk/typescript/examples/README.md

Execute the billing and usage tracking example script.

```bash
npx ts-node examples/billing-usage.ts
```

--------------------------------

### Manage Onboarding

Source: https://github.com/synaptent/aragora/blob/main/examples/python-debate/README.md

Start, continue, or complete onboarding steps using templates.

```bash
# Start or continue onboarding
python main.py onboarding

# Complete the current step
python main.py onboarding --complete

# Use a specific template
python main.py onboarding --template developer
```

--------------------------------

### QuickBooks Integration

Source: https://github.com/synaptent/aragora/blob/main/docs/reference/ACCOUNTING.md

Guides and code examples for integrating with QuickBooks Online.

```APIDOC
## QuickBooks Integration Setup

1. Create a QuickBooks Developer account.
2. Create an app and obtain credentials.
3. Set the following environment variables:

```bash
export QBO_CLIENT_ID="your-client-id"
export QBO_CLIENT_SECRET="your-client-secret"
export QBO_REDIRECT_URI="https://yourapp.com/callback"
export QBO_ENVIRONMENT="sandbox"  # or "production"
```
```

```APIDOC
## QuickBooks OAuth Flow

```python
from aragora.connectors.accounting.qbo import QuickBooksConnector

qbo = QuickBooksConnector()

# Get authorization URL
auth_url = qbo.get_auth_url()
# Redirect user to auth_url...

# Exchange code for tokens (after callback)
credentials = await qbo.exchange_code(auth_code, realm_id)

# Use connector
customers = await qbo.list_customers()
```
```

```APIDOC
## QuickBooks Sync Operations

```python
# Create expense in QBO
qbo_expense = await qbo.create_expense(
    vendor_id="123",
    account_id="456",
    amount=100.00,
    description="Office supplies",
)

# Create bill (AP)
qbo_bill = await qbo.create_bill(
    vendor_id="123",
    account_id="789",
    amount=500.00,
    due_date=datetime.now() + timedelta(days=30),
)

# Create invoice (AR)
qbo_invoice = await qbo.create_invoice(
    customer_id="456",
    line_items=[...],
)
```
```

--------------------------------

### Start and Get Gauntlet Analysis

Source: https://github.com/synaptent/aragora/blob/main/docs/guides/SDK_TYPESCRIPT.md

Initiate gauntlet analysis for stress-testing specifications and architectures. This involves starting an analysis and retrieving the results using a receipt ID.

```typescript
// Start gauntlet analysis
const receipt = await client.gauntlet.run({
  input_type: 'specification',
  input_text: 'The system shall handle 10k requests/second...', 
});

// Get gauntlet result
const result = await client.gauntlet.get(receipt.receipt_id);

// List previous runs
const runs = await client.gauntlet.list({ limit: 10 });
```

--------------------------------

### Quick Start: Create and Use an API Agent

Source: https://github.com/synaptent/aragora/blob/main/aragora/agents/api_agents/README.md

Demonstrates how to create an API agent with automatic fallback and generate/stream responses. Ensure necessary API keys are set as environment variables.

```python
from aragora.agents.api_agents import (
    AnthropicAPIAgent,
    OpenAIAPIAgent,
    GeminiAgent,
    GrokAgent,
    OpenRouterAgent,
    DeepSeekAgent,
)

# Create an agent with automatic fallback
agent = AnthropicAPIAgent(name="claude-debate", model="claude-opus-4-5-20251101")

# Generate a response
response = await agent.generate("Analyze the trade-offs of microservices vs monoliths")

# Stream tokens as they arrive
async for chunk in agent.generate_stream("Explain quantum computing"):
    print(chunk, end="", flush=True)
```

--------------------------------

### Clone and setup Aragora platform

Source: https://github.com/synaptent/aragora/blob/main/docs/START_HERE.md

Clone the repository and prepare the environment for self-hosting.

```bash
git clone https://github.com/synaptent/aragora.git
cd aragora
cp .env.example .env
```

--------------------------------

### Install Aragora and Run in Offline Mode

Source: https://github.com/synaptent/aragora/blob/main/docs/ZERO_CONFIG.md

Install Aragora using pip and start the server in offline mode for immediate use without any external dependencies.

```bash
pip install -e .
python -m aragora.server --offline
# API ready at http://localhost:8080/api/v1/health
```

--------------------------------

### Setup Aragora Server on Lightsail

Source: https://github.com/synaptent/aragora/blob/main/deploy/QUICK_SETUP.md

SSH into the Lightsail instance, clone the Aragora repository, run the setup script, configure environment variables, and start the service.

```bash
# SSH into server
ssh -i your-key.pem ubuntu@<LIGHTSAIL_IP>

# Run setup script
git clone https://github.com/an0mium/aragora.git
cd aragora
chmod +x deploy/lightsail-setup.sh
sudo ./deploy/lightsail-setup.sh

# Set environment variables
sudo nano /etc/aragora/env
# Add: ANTHROPIC_API_KEY=sk-ant-...
# Add: OPENAI_API_KEY=sk-...

# Start service
sudo systemctl start aragora
```

--------------------------------

### Full ML Integration Example

Source: https://github.com/synaptent/aragora/blob/main/docs/guides/ML_INTEGRATION_GUIDE.md

Demonstrates setting up ML components, configuring the arena with ML delegation, and running a debate with quality gates. Exports data for training.

```python
from aragora.debate import Arena, Environment, DebateProtocol
from aragora.debate.ml_integration import (
    MLDelegationStrategy,
    QualityGate,
    ConsensusEstimator,
    get_training_exporter,
)

# Setup ML components
ml_delegation = MLDelegationStrategy()
quality_gate = QualityGate(threshold=0.6)
consensus_estimator = ConsensusEstimator()
exporter = get_training_exporter()

# Configure arena with ML delegation
config = ArenaConfig(
    delegation_strategy=ml_delegation,
)

env = Environment(task="Design a distributed cache")
arena = Arena(env, agents, protocol, config=config)

# Run debate with quality gates
result = await arena.run()

# Export for training
training_data = exporter.export_debate(
    task=env.task,
    consensus_response=result.consensus.content,
    rejected_responses=[m.content for m in result.messages if m != result.consensus],
)
training_data.to_jsonl("debate_training.jsonl")
```

--------------------------------

### Start Background Workers in Python

Source: https://github.com/synaptent/aragora/blob/main/docs/status/NEW_FEATURES.md

Code examples for manually starting the Batch Explainability Worker and Webhook Delivery Worker. These workers process jobs asynchronously.

```python
from aragora.queue.batch_worker import BatchExplainabilityWorker
from aragora.queue.webhook_worker import WebhookDeliveryWorker

# Start batch worker
batch_worker = BatchExplainabilityWorker(
    queue=job_queue,
    worker_id="batch-1",
    max_concurrent_debates=10,
)
await batch_worker.start()

# Start webhook worker
webhook_worker = WebhookDeliveryWorker(
    queue=job_queue,
    worker_id="webhook-1",
    max_concurrent=50,
)
await webhook_worker.start()
```

--------------------------------

### Run Simple Debate Example

Source: https://github.com/synaptent/aragora/blob/main/examples/quickstart/README.md

Execute the first example to see three mock agents debating a monolith-to-microservices migration.

```bash
python examples/quickstart/01_simple_debate.py
```

--------------------------------

### Get Stripe Customer

Source: https://github.com/synaptent/aragora/blob/main/docs/connectors/STRIPE_GUIDE.md

Example of retrieving an existing Stripe customer by their ID.

```python
customer = await stripe.get_customer("cus_xxx")
```

--------------------------------

### Gusto Payroll Integration

Source: https://github.com/synaptent/aragora/blob/main/docs/reference/ACCOUNTING.md

Guides and code examples for integrating with Gusto Payroll.

```APIDOC
## Gusto Payroll Integration Setup

1. Create a Gusto Developer account and OAuth app.
2. Configure redirect URIs in the Gusto developer console.
3. Set the following environment variables:

```bash
GUSTO_CLIENT_ID="your-client-id"
GUSTO_CLIENT_SECRET="your-client-secret"
GUSTO_REDIRECT_URI="https://yourapp.com/api/accounting/gusto/callback"
```
```

```APIDOC
## Gusto OAuth Flow

```python
from aragora.connectors.accounting.gusto import GustoConnector

gusto = GustoConnector()
auth_url = gusto.get_auth_url()
# Redirect user to auth_url...
```
```

```APIDOC
## Gusto Payroll Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/accounting/gusto/status` | Connection status |
| GET | `/api/accounting/gusto/employees` | List employees |
| GET | `/api/accounting/gusto/payrolls` | List payroll runs |
| GET | `/api/accounting/gusto/payrolls/{payroll_id}` | Payroll run details |
| POST | `/api/accounting/gusto/payrolls/{payroll_id}/journal-entry` | Generate journal entry |
```

--------------------------------

### Initialize Database

Source: https://github.com/synaptent/aragora/blob/main/docs/reference/DATABASE.md

SQL commands to create the production database, user, and grant necessary privileges.

```sql
-- Create database
CREATE DATABASE aragora_prod;
CREATE USER aragora WITH ENCRYPTED PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE aragora_prod TO aragora;
```

--------------------------------

### Run Agent Selection Example

Source: https://github.com/synaptent/aragora/blob/main/sdk/typescript/examples/README.md

Execute the agent selection example script.

```bash
npx ts-node examples/agent-selection.ts
```

--------------------------------

### Start Debate via Aragora REST API

Source: https://github.com/synaptent/aragora/blob/main/docs/guides/SME_GA_GUIDE.md

Initiate a debate using the Aragora REST API. This example shows how to start a 'sme_hiring_decision' debate with candidate details.

```bash
# Start a debate
curl -X POST https://api.aragora.com/api/debates \
  -H "Authorization: Bearer $ARAGORA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "sme_hiring_decision",
    "inputs": {
      "candidate_name": "Jane Smith",
      "role": "Product Manager"
    }
  }'
```

--------------------------------

### Run Enterprise Authentication Example

Source: https://github.com/synaptent/aragora/blob/main/sdk/typescript/examples/README.md

Execute the enterprise authentication example script.

```bash
npx ts-node examples/auth-enterprise.ts
```
Tokens:
Raw