Update README for current alpha state
This commit is contained in:
anthonyrawlins
111
README.md
111
README.md
@@ -1,99 +1,54 @@
|
||||
# CHORUS - Container-First P2P Task Coordination System
|
||||
# CHORUS – Container-First Context Platform (Alpha)
|
||||
|
||||
CHORUS is a next-generation P2P task coordination and collaborative AI system designed from the ground up for containerized deployments. It takes the best lessons learned from CHORUS and reimagines them for Docker Swarm, Kubernetes, and modern container orchestration platforms.
|
||||
CHORUS is the runtime that ties the CHORUS ecosystem together: libp2p mesh, DHT-backed storage, council/task coordination, and (eventually) SLURP contextual intelligence. The repository you are looking at is the in-progress container-first refactor. Several core systems boot today, but higher-level services (SLURP, SHHH, full HMMM routing) are still landing.
|
||||
|
||||
## Vision
|
||||
## Current Status
|
||||
|
||||
CHORUS enables distributed AI agents to coordinate, collaborate, and execute tasks across container clusters, supporting deployments from single containers to hundreds of instances in enterprise environments.
|
||||
| Area | Status | Notes |
|
||||
| --- | --- | --- |
|
||||
| libp2p node + PubSub | ✅ Running | `internal/runtime/shared.go` spins up the mesh, hypercore logging, availability broadcasts. |
|
||||
| DHT + DecisionPublisher | ✅ Running | Encrypted storage wired through `pkg/dht`; decisions written via `ucxl.DecisionPublisher`. |
|
||||
| Election manager | ✅ Running | Admin election integrated with Backbeat; metrics exposed under `pkg/metrics`. |
|
||||
| SLURP (context intelligence) | 🚧 Stubbed | `pkg/slurp/slurp.go` contains TODOs for resolver, temporal graphs, intelligence. Leader integration scaffolding exists but uses placeholder IDs/request forwarding. |
|
||||
| SHHH (secrets sentinel) | ❌ Not implemented | No `pkg/shhh` module yet; redaction hooks are pending. |
|
||||
| HMMM routing | 🚧 Partial | PubSub topics join, but capability/role announcements and HMMM router wiring are placeholders (`internal/runtime/agent_support.go`). |
|
||||
|
||||
## Key Design Principles
|
||||
See `docs/progress/CHORUS-WHOOSH-development-plan.md` for the detailed build plan and `docs/progress/CHORUS-WHOOSH-roadmap.md` for sequencing.
|
||||
|
||||
- **Container-First**: Designed specifically for Docker/Kubernetes deployments
|
||||
- **License-Controlled**: Simple environment variable-based licensing
|
||||
- **Cloud-Native Logging**: Structured logging to stdout/stderr for container runtime collection
|
||||
- **Swarm-Ready P2P**: P2P protocols optimized for container networking
|
||||
- **Scalable Agent IDs**: Agent identification system that works across distributed deployments
|
||||
- **Zero-Config**: Minimal configuration requirements via environment variables
|
||||
## Quick Start (Alpha)
|
||||
|
||||
## Architecture
|
||||
The container-first workflows are still evolving; expect frequent changes.
|
||||
|
||||
CHORUS follows a microservices architecture where each container runs a single agent instance:
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ CHORUS Agent │ │ CHORUS Agent │ │ CHORUS Agent │
|
||||
│ Container 1 │◄─┤ Container 2 │─►│ Container N │
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
│ │ │
|
||||
└──────────────────────┼──────────────────────┘
|
||||
│
|
||||
┌─────────────────┐
|
||||
│ Container │
|
||||
│ Network │
|
||||
│ (P2P Mesh) │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Docker & Docker Compose
|
||||
- Valid CHORUS license key
|
||||
- Access to Ollama endpoints for AI functionality
|
||||
|
||||
### Basic Deployment
|
||||
|
||||
1. Clone and configure:
|
||||
```bash
|
||||
git clone https://gitea.chorus.services/tony/CHORUS.git
|
||||
cd CHORUS
|
||||
cp docker/chorus.env.example docker/chorus.env
|
||||
# Edit docker/chorus.env with your license key and configuration
|
||||
# adjust env vars (KACHING license, bootstrap peers, etc.)
|
||||
docker compose -f docker/docker-compose.yml up --build
|
||||
```
|
||||
|
||||
2. Deploy:
|
||||
```bash
|
||||
docker-compose -f docker/docker-compose.yml up -d
|
||||
```
|
||||
You’ll get a single agent container with:
|
||||
- libp2p networking (mDNS + configured bootstrap peers)
|
||||
- election heartbeat
|
||||
- DHT storage (AGE-encrypted)
|
||||
- HTTP API + health endpoints
|
||||
|
||||
3. Scale (Docker Swarm):
|
||||
```bash
|
||||
docker service scale chorus_agent=10
|
||||
```
|
||||
**Missing today:** SLURP context resolution, SHHH redaction, HMMM per-issue routing. Expect log warnings/TODOs for those paths.
|
||||
|
||||
## Licensing
|
||||
## Roadmap Highlights
|
||||
|
||||
CHORUS requires a valid license key to operate. Set your license key in the environment:
|
||||
1. **Security substrate** – land SHHH sentinel, finish SLURP leader-only operations, validate COOEE enrolment (see roadmap Phase 1).
|
||||
2. **Autonomous teams** – coordinate with WHOOSH for deployment telemetry + SLURP context export.
|
||||
3. **UCXL + KACHING** – hook runtime telemetry into KACHING and enforce UCXL validator.
|
||||
|
||||
```env
|
||||
CHORUS_LICENSE_KEY=your-license-key-here
|
||||
CHORUS_LICENSE_EMAIL=your-email@example.com
|
||||
```
|
||||
Track progress via the shared roadmap and weekly burndown dashboards.
|
||||
|
||||
**No license = No operation.** CHORUS will not start without valid licensing.
|
||||
|
||||
## Differences from CHORUS
|
||||
|
||||
| Aspect | CHORUS | CHORUS |
|
||||
|--------|------|--------|
|
||||
| Deployment | systemd service (1 per host) | Container (N per cluster) |
|
||||
| Configuration | Web UI setup | Environment variables |
|
||||
| Logging | Journal/files | stdout/stderr (structured) |
|
||||
| Licensing | Setup-time validation | Runtime environment variable |
|
||||
| Agent IDs | Host-based | Container/cluster-based |
|
||||
| P2P Discovery | mDNS local network | Container network + service discovery |
|
||||
|
||||
## Development Status
|
||||
|
||||
🚧 **Early Development** - CHORUS is being designed and built. Not yet ready for production use.
|
||||
|
||||
Current Phase: Architecture design and core foundation development.
|
||||
|
||||
## License
|
||||
|
||||
CHORUS is a commercial product. Contact chorus.services for licensing information.
|
||||
## Related Projects
|
||||
- [WHOOSH](https://gitea.chorus.services/tony/WHOOSH) – council/team orchestration
|
||||
- [KACHING](https://gitea.chorus.services/tony/KACHING) – telemetry/licensing
|
||||
- [SLURP](https://gitea.chorus.services/tony/SLURP) – contextual intelligence prototypes
|
||||
- [HMMM](https://gitea.chorus.services/tony/hmmm) – meta-discussion layer
|
||||
|
||||
## Contributing
|
||||
|
||||
CHORUS is developed by the chorus.services team. For contributions or feedback, please use the issue tracker on our GITEA instance.
|
||||
This repo is still alpha. Please coordinate via the roadmap tickets before landing changes. Major security/runtime decisions should include a Decision Record with a UCXL address so SLURP/BUBBLE can ingest it later.
|
||||
|
||||
Reference in New Issue
Block a user