Skip to content

luxinlabs/CHRONOS

BranchesTags

Repository files navigation

CHRONOS Project Overview

Project Description

CHRONOS is an open-source multi-agent collaboration platform that enables AI agents to discover each other by skills, share structured context safely, propose actions, debate decisions, and resolve conflicts through enforceable AI Court rulings. The platform emphasizes true collaboration among peer agents rather than hierarchical orchestration.

🎯 Core Concept

CHRONOS is NOT:

  • A workflow engine
  • A task scheduler
  • A chat UI
  • A single "super agent"

CHRONOS IS:

  • A collaboration runtime
  • Where agents share context via MongoDB
  • Propose structured actions
  • Submit support/block/modify positions
  • Resolve disagreements via enforceable AI Court decisions

Agents never call tools directly. They must collaborate to reach a decision.

🏗️ Architecture

Components

  1. Agent Registry & Capability Discovery

    • Agents register with specific capabilities
    • Peer discovery by skills

  2. Shared Context Engine (MongoDB)

    • Agents write findings to shared memory
    • Trust-labeled evidence (trusted/untrusted/quarantined)
    • Prompt injection detection

  3. Structured Debate System

    • Agents propose actions
    • Submit positions (support/block/modify)
    • Reference evidence from shared memory
    • Automatic conflict detection

  4. Governance & Policy Evaluation

    • Scope authorization checks
    • Constitution rule validation
    • Risk assessment

  5. AI Court (Conflict Resolution)

    • Analyzes agent debate
    • Reviews trusted evidence
    • Issues binding rulings
    • Creates precedent case law

🚀 Quick Start

Prerequisites

  • Docker and Docker Compose
  • Node.js (for frontend development)
  • Python 3.8+ (for backend development)
  • Optional: Fireworks AI API key for Court decisions

1. Start the System

For Local Development:

cd CHRONOS
docker-compose up --build

For MongoDB Atlas (Required for Finalists):

  1. Create a free MongoDB Atlas cluster
  2. Get your connection string: mongodb+srv://username:password@cluster.mongodb.net/chronos
  3. Set environment variable: export MONGODB_URI="your-atlas-connection-string"
  4. Run: docker-compose up --build (without local MongoDB service)

This starts:

  • MongoDB on port 27017
  • Backend API on port 8000
  • Frontend UI on port 3000

2. Access the Application

Open your browser to: http://localhost:3000

3. Seed Demo Data

Click the "Seed Demo" button to populate the system with a complete collaboration scenario.

📊 Demo Scenario: SaaS Launch Pricing

After seeding, observe the complete multi-agent collaboration flow:

1. Agent Discovery

  • 4 specialized agents register with capabilities:
    • Orchestrator: planning, coordination
    • Research: market intelligence, analysis
    • Finance: budgeting, pricing
    • Legal: compliance, risk assessment

2. Shared Context

  • Research agent shares market analysis
  • Finance agent shares cost models
  • Legal agent shares compliance review
  • All evidence trust-labeled and stored in MongoDB

3. Action Proposal

  • Finance agent proposes: "Set SaaS pricing at $179/month"
  • Includes detailed payload with pricing tiers

4. Structured Debate

  • Research agent SUPPORTS with market evidence
  • Legal agent BLOCKS due to risk concerns
  • Orchestrator suggests MODIFICATION for compromise
  • Each position references specific evidence

5. Conflict Detection

  • System detects disagreement (1 support, 1 block, 1 modify)
  • Automatically creates conflict record
  • Action status changes to "CONFLICT"

6. AI Court Arbitration

  • Click "Arbitrate" to send to AI Court
  • Court analyzes:
    • All agent positions
    • Trusted evidence
    • Constitution rules
    • Relevant precedents
  • Issues binding ruling (allow/deny/modify/require_human)

7. Enforceable Outcome

  • Decision is binding
  • Agents cannot override
  • Precedent case created
  • Full audit trail logged

🔑 Key Features

Multi-Agent Collaboration

  • Agent registration and capability discovery
  • Shared context with trust labeling
  • Structured debate with evidence-backed positions
  • Automatic conflict detection and resolution

Security & Governance

  • Zero-trust shared memory model
  • Prompt injection detection
  • Capability-based authorization
  • Comprehensive audit trails
  • Security alert monitoring

AI Court System

  • Analyzes agent positions and evidence
  • Issues binding rulings (allow/deny/modify/require_human)
  • Creates precedent case law
  • Integrates with external AI services (Fireworks AI)

Observability

  • Conflict tracking
  • Court case precedents
  • Audit event logging
  • Security incident monitoring

📡 API Endpoints

Core Entities

  • Tenants: /v1/tenants - Multi-tenant organization management
  • Agents: /v1/agents - Agent registration and discovery
  • Goals: /v1/goals - Shared objectives with constitution rules
  • Actions: /v1/actions - Proposed operations and decision tracking

Collaboration

  • Shared Memory: /v1/memory - Context sharing with trust labels
  • Positions: /v1/actions/{id}/position - Support/block/modify submissions
  • Policy Evaluation: /v1/actions/{id}/evaluate - Governance checks
  • AI Court: /v1/actions/{id}/arbitrate - Conflict resolution

Observability

  • Conflicts: /v1/conflicts - Detected disagreements
  • Cases: /v1/cases - Court precedents
  • Audit: /v1/audit/{entity_id} - Event history
  • Security: /v1/security/alerts - Incident monitoring

🗄️ MongoDB Collections

All collections include tenant_id for multi-tenancy:

  • tenants - Organization data
  • agents - Agent profiles and capabilities
  • goals - Shared objectives
  • shared_memory - Facts and evidence
  • actions - Proposed operations
  • positions - Agent arguments
  • policy_evaluations - Governance results
  • conflicts - Detected disagreements
  • cases - Court precedents
  • rulings - AI Court decisions
  • audit_events - Immutable event log
  • security_alerts - Security incidents

🔐 Security Features

Zero-Trust Shared Memory

  • All memory labeled: trusted, untrusted, or quarantined
  • Heuristic prompt injection detection
  • Suspicious content automatically quarantined
  • Quarantined memory excluded from Court input

Capability-Based Authorization

  • Agents authenticate via API key
  • Actions require specific scopes
  • Missing scopes = automatic denial

Abnormal Behavior Detection

  • Repeated denied actions
  • Rate anomalies
  • Security alerts generated
  • Agent quarantine capability

🔧 Tech Stack

Backend

  • Language: Python
  • Framework: FastAPI (async)
  • Database: MongoDB with Motor (async driver)
  • Validation: Pydantic
  • Key Dependencies: fastapi, motor, pydantic

Frontend

  • Framework: Next.js 14 with App Router
  • Language: TypeScript
  • Styling: TailwindCSS
  • UI Components: Radix UI primitives
  • Key Dependencies: next, react, tailwindcss, @radix-ui/*, lucide-react

Infrastructure

  • Containerization: Docker & Docker Compose
  • Database: MongoDB (local via Docker or MongoDB Atlas)

🛠️ Development

Prerequisites

  • Docker and Docker Compose
  • Node.js (for frontend development)
  • Python 3.8+ (for backend development)
  • Optional: Fireworks AI API key for Court decisions

Quick Start

# Start all services
docker-compose up --build

# Access frontend at http://localhost:3002
# Access backend API at http://localhost:8002

Development Mode

# Backend
cd backend
pip install -r requirements.txt
uvicorn main:app --reload

# Frontend
cd frontend
npm install
npm run dev

MongoDB Access

docker exec -it chronos-mongodb mongosh -u admin -p password

use chronos
db.agents.find()
db.actions.find()
db.positions.find()

📝 Environment Variables

Backend

  • MONGODB_URI - MongoDB connection string
  • FIREWORKS_API_KEY - AI Court integration
  • CORS_ORIGINS - Allowed frontend origins

Frontend

  • NEXT_PUBLIC_API_URL - Backend API endpoint

🎓 Hackathon Context

Built for MongoDB CHRONOS Hackathon demonstrating:

  • True multi-agent collaboration through structured debate
  • MongoDB-backed shared context with security features
  • AI-powered conflict resolution with binding decisions
  • Complete open-source implementation under MIT License

📄 License

MIT License - See LICENSE file for details

🤝 Contributing

This is a hackathon MVP. Contributions welcome!

Built for MongoDB CHRONOS Hackathon - Demonstrating true multi-agent collaboration through structured debate and AI-powered conflict resolution.

About

CHRONOS solves the hardest unsolved problem in agent systems: how to run reliably over time, through failure and change, without restarting.

chronos-eosin-ten.vercel.app

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages