ACP-PROJECT
ACP-PROJECT is the execution layer of the ACP ecosystem. It contains everything needed to run consensus: the web frontend for user interaction, the Cloudflare Worker API for production edge deployment, and the Python consensus engine for the core algorithmic logic.
Role in the Ecosystem
ACP-PROJECT is the central repository that ties the ecosystem together. It imports system prompts from ACP-PROMPTS to define model behavior and queries axioms from ACP-DATASETS via Vectorize for grounding. All user interaction, API handling, consensus orchestration, and result delivery happens here.
Dependencies
ACP-PROJECT depends on both ACP-PROMPTS (for system prompt loading) and ACP-DATASETS (for axiom retrieval via Vectorize). Both can be updated independently without redeploying ACP-PROJECT.
Component Architecture
The repository contains three major components, each responsible for a distinct layer of the execution pipeline.
+----------------------------------------------------------+ | ACP-PROJECT | | | | +----------------+ +-----------------+ | | | FRONTEND | | WORKER API | | | | (Next.js) |-->| (Cloudflare) | | | | | | | | | | - Playground | | - /consensus- | | | | - Dashboard | | iterative | | | | - History | | - /axioms/search| | | | - Settings | | - /cache/check | | | | - Docs site | | - /embeddings | | | +----------------+ +--------+--------+ | | | | | +-------v--------+ | | | PYTHON ENGINE | | | | (FastAPI) | | | | | | | | - Consensus | | | | - phi-spiral | | | | - Validators | | | | - Oracles | | | | - Metrics | | | +---------------+ | +----------------------------------------------------------+
Frontend (Next.js)
The frontend is a Next.js 14 application using the App Router. It provides the primary user interface for interacting with the consensus engine, including the interactive Playground where users can submit queries, select models, choose musical structures, and observe real-time convergence.
| Feature | Description |
|---|---|
| Playground | Interactive consensus UI with real-time D-score graphs, model response cards, and convergence visualization |
| Dashboard | Overview of recent consensus runs, aggregate metrics, and system status |
| History | Searchable log of past consensus sessions with full replay capability |
| Settings | API key management, model selection, threshold configuration |
| Documentation | The docs site you are reading now, built as part of the frontend |
Technologies: Next.js 14, React 18, TypeScript, Tailwind CSS, Framer Motion, shadcn/ui.
Deployment: Vercel, accessible at axiomprotocol.org.
Worker API (Cloudflare Workers)
The Worker API is the production edge gateway. It runs on Cloudflare Workers for global low-latency access and orchestrates the full consensus pipeline: prompt loading, axiom retrieval via Vectorize, LLM calls via OpenRouter, D-score calculation, and result caching.
| Endpoint | Method | Purpose |
|---|---|---|
/consensus-iterative | POST | Run iterative consensus with phi-spiral |
/axioms/search | GET | Semantic search over axioms via Vectorize |
/cache/check | POST | Check semantic cache for a previous result |
/cache/stats | GET | Cache performance statistics |
/embeddings | POST | Generate text embeddings via Cloudflare AI |
/health | GET | Health check with Vectorize status |
/seed-axioms | POST | Seed axioms from ACP-DATASETS into Vectorize |
Technologies: Cloudflare Workers, Vectorize (768-dim embeddings, bge-base-en-v1.5), KV Namespaces, Cloudflare AI.
Local development: Run wrangler dev to start the Worker locally at http://localhost:8787.
Python Engine (FastAPI)
The Python engine is the reference implementation of the ACP v4.0 consensus algorithm. It provides the core logic for φ-convergence, musical structures (Fugue, Sonata, Concert), D-score calculation, oracle verification, and axiom-grounded reasoning.
| Module | Path | Responsibility |
|---|---|---|
| Core Metrics | src/core/ | D-score, H-total, C_ij calculations, validators, oracles |
| Consensus Engine | src/engine/ | ConsensusEngine with phi-spiral, musical structures |
| LLM Adapters | src/llm/ | OpenAI, Anthropic, OpenRouter, Mock adapters |
| API Routes | src/api/ | FastAPI routes for consensus, health, WebSocket |
| Axiom Registry | src/registry/ | Axiom CRUD, database models, service layer |
| Prompt Loader | src/core/prompts.py | Load and parse prompts from ACP-PROMPTS |
| Vectorize Client | src/core/vectorize_client.py | Search axioms via Worker Vectorize endpoint |
Technologies: Python 3.11+, FastAPI, SQLAlchemy, PostgreSQL, Redis.
Local development: Run uvicorn main:app --reload to start the API at http://localhost:8000.
File Structure
The repository is organized into clearly separated directories for each major subsystem.
ACP-PROJECT/
├── src/ # Python backend (reference implementation)
│ ├── core/ # Metrics (D-score, H-total, C_ij), validators, oracles
│ ├── engine/ # ConsensusEngine + musical structures (Fugue/Sonata/Concert)
│ ├── llm/ # LLM adapters (OpenAI, Anthropic, OpenRouter, Mock)
│ ├── api/ # FastAPI routes (consensus, health, websocket)
│ ├── registry/ # Axiom registry (CRUD, DB models, service)
│ └── consensus/ # Consensus state management
├── workers/cloudflare-worker/ # Edge consensus API (Cloudflare Workers + Vectorize)
├── data/axioms/ # 7 axiom level JSON files
├── scripts/ # Utility scripts (seeding, testing)
├── tests/ # Python test suite
├── docs/ # Documentation source files
├── legal/ # BSL 1.1 license, CLA, trademark policy
└── archive/ # Historical development files (read-only)Tech Stack
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | Next.js 14, React 18, TypeScript, Tailwind CSS | Web UI and documentation site |
| Edge API | Cloudflare Workers, Wrangler | Global serverless edge deployment |
| Search | Cloudflare Vectorize (768-dim, bge-base-en-v1.5) | Semantic axiom retrieval |
| Cache | Cloudflare KV | Semantic result caching and rate limiting |
| Backend | Python 3.11+, FastAPI | Consensus engine reference implementation |
| Database | PostgreSQL, SQLAlchemy | Metrics persistence and axiom registry |
| Queue | Redis | Task queue and session state |
| LLM APIs | OpenAI, Anthropic, OpenRouter | Multi-model AI inference |
| Linting | Ruff, Black, mypy | Code quality enforcement |
| Testing | pytest | Unit and integration tests |
Development Commands
pip install -r requirements.txt
uvicorn main:app --reloadcd workers/cloudflare-worker
npm install
wrangler dev# Linting
ruff check src/ tests/
black src/ tests/
mypy src/ --ignore-missing-imports
# Tests
pytest tests/License
ACP-PROJECT is licensed under BSL 1.1 (Business Source License). Non-production use is permitted. The license transitions to Apache 2.0 on 2030-04-09. See the legal/ directory for full terms.