Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
260 lines (195 loc) · 6.13 KB

GETTING_STARTED.md

File metadata and controls

260 lines (195 loc) · 6.13 KB
Raw

Getting Started with ACP

Welcome to the Axiom Consensus Protocol (ACP). This guide gets you from zero to a working consensus call in under 30 minutes.

The public interactive Playground at axiomprotocol.org is maintained in a separate repository. This guide covers the protocol itself — the Worker API and the Python engine.

⚡ 10-Minute API Quickstart

Use ACP as an HTTP API in your applications.

Step 1: Get an OpenRouter Key

# OpenRouter provides unified access to multiple LLMs
# Sign up at: https://openrouter.ai/keys
export OPENROUTER_API_KEY="your_key_here"

Step 2: Make Your First Request

curl -X POST https://your-worker.workers.dev/consensus-iterative \
  -H "Content-Type: application/json" \
  -H "x-openrouter-key: $OPENROUTER_API_KEY" \
  -d '{
    "query": "What is 2+2?",
    "models": ["openai/gpt-4", "anthropic/claude-3.5-sonnet"],
    "max_iterations": 7
  }'

Step 3: Understand the Response

{
  "query": "What is 2+2?",
  "final_answer": "4",
  "final_D": 0.0,
  "consensus_reached": true,
  "iterations_used": 1,
  "iteration_history": [
    {
      "iteration": 1,
      "D": 0.0,
      "responses": [
        { "model": "gpt-4", "content": "2+2 equals 4" },
        { "model": "claude-3.5-sonnet", "content": "The sum of 2 and 2 is 4" }
      ]
    }
  ]
}

Key fields:

  • final_D — Divergence score (0 = perfect consensus, 1 = total disagreement)
  • consensus_reached — true if D-score < 0.1
  • final_answer — The consensus answer from all models
  • axioms_used — Which fundamental axioms were referenced

Example Use Cases

Fact-checking:

curl -X POST https://your-worker.workers.dev/consensus-iterative \
  -H "Content-Type: application/json" \
  -H "x-openrouter-key: $OPENROUTER_API_KEY" \
  -d '{
    "query": "What is the speed of light in vacuum?",
    "models": ["openai/gpt-4", "anthropic/claude-3.5-sonnet", "google/gemini-1.5-pro"]
  }'

Code review:

curl -X POST https://your-worker.workers.dev/consensus-iterative \
  -H "Content-Type: application/json" \
  -H "x-openrouter-key: $OPENROUTER_API_KEY" \
  -d '{
    "query": "Is this Python code correct?\ndef factorial(n):\n    if n == 0: return 1\n    return n * factorial(n-1)",
    "models": ["openai/gpt-4", "anthropic/claude-3.5-sonnet"]
  }'

🏗️ 30-Minute Local Setup

Run ACP locally with the Python engine for full control.

Prerequisites

  • Python 3.11+
  • Node.js 18.18+ (only if you want to deploy the Worker)
  • Git

Step 1: Clone the Repository

git clone https://github.com/Axiom-consensus-protocol/ACP-PROJECT.git
cd ACP-PROJECT

Step 2: Set Up Environment Variables

# Copy example env file
cp .env.example .env

# Edit .env with your API keys:
# - OPENROUTER_API_KEY (required)
# - WORKER_URL       (optional — only if you run the Cloudflare Worker)

Minimum .env:

OPENROUTER_API_KEY=your_key_here
WORKER_URL=https://your-worker.workers.dev

Step 3: Install Python Dependencies

python -m venv .venv
source .venv/bin/activate   # macOS / Linux
# .venv\Scripts\activate    # Windows

pip install -r requirements.txt

Step 4: Run the Python API

uvicorn main:app --reload --port 8000

Visit http://localhost:8000/docs to see the interactive FastAPI OpenAPI UI.

Step 5: Verify Installation

Health check:

curl http://localhost:8000/health
# Should return: {"status":"ok"}

Test consensus:

curl -X POST http://localhost:8000/consensus \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is 2+2?",
    "models": ["openai/gpt-4o-mini", "anthropic/claude-3-haiku"]
  }'

Step 6: (Optional) Deploy the Worker

cd workers/cloudflare-worker
npm install
npx wrangler deploy

See scripts/deploy/README.md for detailed deployment options.

Step 7: Explore the Ecosystem

ACP consists of three repositories working together:

┌─────────────────────┐
│   ACP-PROJECT       │  ← You are here (execution)
│   - Worker API      │
│   - Python Engine   │
└─────────────────────┘
           │
           ├──→ ACP-DATASETS (1,059 verified axioms)
           │
           └──→ ACP-PROMPTS (system prompts)

Clone the companion repos into the same parent directory to use:

  • Axioms from ACP-DATASETS for grounding
  • Prompts from ACP-PROMPTS for consensus logic

See docs/ECOSYSTEM.md for the full architecture.

🎯 What's Next?

For Users

For Developers

  • Examples: See the /examples directory for working code
  • Contribute Axioms: Fork ACP-DATASETS, add JSON axiom files, submit a PR

For Researchers

🐛 Troubleshooting

"Vectorize not available"

Problem: Health endpoint shows axioms_seeded: false

Solution: Seed the vector database:

cd workers/cloudflare-worker
CLOUDFLARE_API_TOKEN=your_token node ../../scripts/vectorize/seed-all-axioms.js

"API key invalid"

Problem: Getting authentication errors

Solution: Check your OpenRouter key:

curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"
# Should return a list of available models

"Worker timeout"

Problem: Consensus requests timing out

Solution: Reduce max_iterations or use faster models:

{
  "max_iterations": 3,
  "models": ["openai/gpt-3.5-turbo", "anthropic/claude-3-haiku"]
}

For more issues, see TROUBLESHOOTING.md.

Additional Resources

Last updated: 2026-04-11