Skip to content

API.md

Latest commit

 

History

History
548 lines (437 loc) · 10.4 KB

API.md

File metadata and controls

548 lines (437 loc) · 10.4 KB

ACP API Reference

Version: 2.0.0 (Vectorize) Base URL (Production Worker): https://your-worker.workers.dev Base URL (Local Python): http://localhost:8000 (when running uvicorn main:app) Base URL (Local Worker Dev): http://localhost:8787 (when running wrangler dev)

Table of Contents

Authentication

Protected endpoints require an API key. Pass it via header:

x-api-key: your_api_key

Or using Bearer token:

Authorization: Bearer your_api_key

API Architecture

ACP provides two API implementations:

1. Worker API (Cloudflare) - Production

  • URL: https://your-worker.workers.dev
  • Purpose: Production-ready, edge-deployed API
  • Key Features:
    • Vectorize integration for axiom search
    • Semantic caching via KV
    • Rate limiting
    • Global edge distribution

Main Endpoints:

  • POST /consensus-iterative - Iterative consensus with φ-spiral
  • POST /consensus - Single-shot consensus (faster)
  • GET /axioms/search - Search axiom database
  • POST /cache/check - Check semantic cache
  • GET /health - Service health

2. Python FastAPI - Local Development

  • URL: http://localhost:8000 (when running uvicorn main:app)
  • Purpose: Local development, full Python engine access
  • Key Features:
    • Direct access to ConsensusEngine
    • Asynchronous and synchronous modes
    • Background task processing
    • Full Python ecosystem integration

Main Endpoints:

  • POST /consensus - Create async consensus task (returns task ID)
  • GET /consensus/{id} - Get task status/result
  • POST /consensus/sync - Synchronous consensus (waits for result)

Worker API Endpoints

All endpoints below are for the Worker API (production).

Endpoints

Health Check

GET /health

Check service status and Vectorize availability.

Response:

{
  "status": "healthy",
  "service": "ACP Consensus Worker",
  "version": "4.0.0",
  "vectorize": {
    "available": true,
    "ai_available": true,
    "axioms_seeded": true
  }
}

Consensus (Iterative)

POST /consensus-iterative

Run iterative consensus with φ-spiral convergence.

Headers:

  • x-api-key (required if configured)
  • x-openrouter-key (optional, use your own key)

Body:

{
  "query": "What is 2 + 2?",
  "models": ["anthropic/claude-3-haiku", "openai/gpt-4o-mini"],
  "skip_cache": false
}

Response:

{
  "consensus_reached": true,
  "final_answer": "4",
  "confidence": 0.95,
  "iterations": 2,
  "metrics": {
    "initial_D": 0.15,
    "final_D": 0.02,
    "H_total": 0.98
  },
  "cache_hit": false,
  "relevant_axioms": [...]
}

Axiom Search

GET /axioms/search?q=<query>&level=5,6,7&topK=5&minScore=0.7

Search axioms by semantic similarity.

Query Parameters:

Parameter Type Default Description
q string required Search query
topK int 5 Max results
level string all Comma-separated levels (1-7)
minScore float 0.7 Minimum relevance score

Response:

{
  "query": "machine learning",
  "axioms": [
    {
      "id": "axiom_L5_001",
      "axiom": "Neural networks implement gradient descent",
      "level": 5,
      "levelName": "architectural",
      "domain": "ML",
      "description": "...",
      "relevance": 0.89
    }
  ],
  "count": 1
}

Semantic Cache Check

POST /cache/check

Check if a similar query exists in cache.

Body:

{
  "query": "What is two plus two?"
}

Response (hit):

{
  "hit": true,
  "similarity": 0.95,
  "cached_query": "What is 2+2?",
  "result": {
    "final_answer": "4",
    "confidence": 0.95
  }
}

Response (miss):

{
  "hit": false
}

Cache Statistics

GET /cache/stats

Get cache performance statistics.

Response:

{
  "total_queries": 1234,
  "cache_hits": 567,
  "hit_rate": 0.46,
  "avg_similarity": 0.92
}

Find Similar Queries

GET /similar?q=<query>&topK=5&minScore=0.7

Find similar past queries.

Response:

{
  "query": "sum of 2 and 2",
  "similar": [
    {
      "query": "What is 2+2?",
      "similarity": 0.91,
      "result_id": "res_abc123",
      "created_at": 1703500000
    }
  ],
  "count": 1
}

Prometheus Metrics

GET /metrics

Prometheus-format metrics.

Response:

# HELP acp_requests_total Total requests
# TYPE acp_requests_total counter
acp_requests_total 12345

# HELP acp_consensus_duration_seconds Consensus duration
# TYPE acp_consensus_duration_seconds histogram
acp_consensus_duration_seconds_bucket{le="1"} 1000

Axiom Levels

Level Name Description Self-Referential
1 Mathematical a + b = b + a No
2 Physical F = ma No
3 Ontological H₂O = water No
4 Computable SHA-256 No
5 Architectural von Neumann Yes
6 Protocol TCP/IP Yes
7 Linguistic Python syntax Yes

Python FastAPI Endpoints (Local Development)

These endpoints are available when running the Python backend locally:

uvicorn main:app --reload --port 8000

POST /consensus

Create asynchronous consensus task (returns immediately).

Request Body:

{
  "query": "What is 2+2?",
  "models": [
    {
      "provider": "openrouter",
      "name": "gpt4",
      "model": "openai/gpt-4o-mini",
      "temperature": 0.7
    },
    {
      "provider": "openrouter",
      "name": "claude",
      "model": "anthropic/claude-3-haiku",
      "temperature": 0.7
    }
  ],
  "max_iterations": 7,
  "structure": "sonata"
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "progress": 0.0
}

GET /consensus/{consensus_id}

Get status and result of consensus task.

Response (running):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "progress": 0.4
}

Response (completed):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "progress": 1.0,
  "result": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "query": "What is 2+2?",
    "final_answer": "4",
    "consensus_reached": true,
    "iterations_used": 1,
    "final_D": 0.0,
    "final_H_total": 1.0,
    "iterations": [...]
  }
}

POST /consensus/sync

Synchronous consensus (waits for result, blocks until complete).

Request Body: Same as POST /consensus

Response: Returns ConsensusResponse directly (same as result in async endpoint).

Example:

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

Error Codes

Code Meaning
400 Bad request (missing parameters)
401 Unauthorized (invalid API key)
429 Rate limited (retry after header)
500 Internal server error

Rate Limits

  • 100 requests per minute per IP
  • 1000 requests per hour per API key
  • Burst: 10 requests per second

SDKs

Python

Option 1: Using Worker API Client

from src.core.vectorize_client import VectorizeClient
import asyncio

async def main():
    # Initialize client
    client = VectorizeClient(
        worker_url="https://your-worker.workers.dev",
        openrouter_key="your_openrouter_key"
    )

    # Check cache
    result = await client.check_cache("What is 2+2?")
    if result.get("hit"):
        print(f"Cached: {result['result']}")

    # Search axioms
    axioms = await client.search_axioms(
        "machine learning",
        top_k=5,
        level_filter=[5, 6, 7]
    )
    for axiom in axioms:
        print(f"[L{axiom['level']}] {axiom['statement']}")

    # Run consensus via Worker
    response = await client.request(
        "POST",
        "/consensus-iterative",
        json={
            "query": "What is the capital of France?",
            "models": ["openai/gpt-4o-mini", "anthropic/claude-3-haiku"]
        }
    )
    print(response["final_answer"])

asyncio.run(main())

Option 2: Using Python Engine Directly

from src.engine import ConsensusEngine, ConsensusConfig
from src.llm.openrouter_llm import OpenRouterLLM
import asyncio
import os

async def main():
    # Initialize engine
    engine = ConsensusEngine()
    api_key = os.getenv("OPENROUTER_API_KEY")

    # Add models
    engine.add_model(OpenRouterLLM(
        name="gpt4",
        model="openai/gpt-4o-mini",
        api_key=api_key
    ))
    engine.add_model(OpenRouterLLM(
        name="claude",
        model="anthropic/claude-3-haiku",
        api_key=api_key
    ))

    # Configure consensus
    config = ConsensusConfig(
        max_iterations=5,
        structure="sonata"  # 2-3 models
    )

    # Run consensus
    result = await engine.run(
        query="What is the capital of France?",
        config=config
    )

    print(f"Answer: {result.final_answer}")
    print(f"D-score: {result.final_D:.3f}")
    print(f"Consensus: {result.consensus_reached}")

asyncio.run(main())

Note: Run Python examples from project root:

cd /path/to/ACP-PROJECT
python your_script.py

JavaScript

const response = await fetch('https://your-worker.workers.dev/consensus-iterative', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your_key'
  },
  body: JSON.stringify({
    query: 'What is 2+2?'
  })
});

const data = await response.json();
console.log(data.final_answer);

cURL

curl -X POST https://your-worker.workers.dev/consensus-iterative \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_key" \
  -d '{"query": "What is 2+2?"}'