Nebula Protocol
Nebula Convergence Engine (NCE) — CRDT-based convergent state replication for heterogeneous multi-agent systems, extending Google's A2A protocol.
| Section | Description |
|---|---|
| Problem | Phantom commitments in multi-agent coordination |
| Solution | AS-CRDTs and observation proofs |
| Quick Start | Install, run, verify |
| Dashboard | Demo and Live modes |
| Architecture | NCE Core, ADRs, diagrams |
| API | REST + WebSocket reference |
| Reproducibility | Paper Table 5 reproduction |
| Benchmarks | Protocol comparison |
The Problem
AI agents operating on the same shared resource (e.g., inventory) can act on stale state and make conflicting decisions - a phantom commitment. Two agents simultaneously read stock: 1 and both commit a sale, resulting in stock: -1. This occurs in any multi-agent system without real-time consensus, and consensus protocols sacrifice availability during network partitions.
The Solution
NCE provides AS-CRDTs (Agent-State CRDTs) with cryptographic observation proofs as a native A2A protocol extension. Three CRDT types - TaskStatus, ObservedBeliefRegister, and CapabilitySet - guarantee eventual consistency without a central coordinator. Every state mutation is logged as an EU AI Act Article 12 compliance event.
Quick Start
pip install nebula-protocol
# Or from source:
pip install -e ".[dev]"
# Run the full test suite (124 tests, including Hypothesis property tests)
make ci
# Run the e-commerce simulation (NCE vs 3 baselines)
python -m simulation.run_simulation --all --transactions 1000
# Launch the dashboard
cd dashboard && npm install && npm run dev
Dashboard
The NCE Simulation Dashboard visualizes the multi-agent e-commerce simulation in real time.
| Mode | Use Case |
|---|---|
| Demo Mode | No server needed. Runs entirely in the browser. Ideal for presentations and paper review. |
| Live Mode | Connects to the FastAPI backend. Requires uvicorn api.main:app --port 8000 running. |
What you see: 4 KPI cards (Phantom Commits, Conv p99, Token Saved, Art.12), convergence histogram, token cost comparison, agent fleet table, throughput chart, compliance log, and protocol comparison table.
📖 Dashboard Guide - Technical implementation details (12 agents, API contract, components).
Demo
Run simulation in Demo Mode; KPIs, charts, and agent fleet update in real time.
Architecture
See docs/architecture.md for full architecture diagrams and ADRs.
High-level flow: Dashboard (React) ↔ FastAPI (REST + WebSocket) ↔ Simulation (12 agents, 4 baselines) ↔ NCE Core (CRDTs, delta sync, compliance).
5-line usage example:
from nce.sync.state_bus import StateBus
from nce.crdt.task_status import StatusLevel
bus = StateBus(agent_id="order-agent-1")
await bus.update_belief("inventory:SKU-001", 42)
await bus.update_task("order-99", StatusLevel.COMPLETED)
state = bus.query_state()
print(state.beliefs["inventory:SKU-001"].value) # 42
Architecture (NCE Core)
graph TD
A2A[A2A Agent Card\nwith NCE Extension] --> Interceptor[TaskInterceptor]
Interceptor --> Bus[StateBus]
Bus --> CRDT[CompositeState\nCRDT Product Lattice]
Bus --> Barrier[CausalBarrier]
Bus --> Gossip[GossipProtocol\nAnti-entropy sync]
CRDT --> TS[TaskStatus\nMonotone Lattice]
CRDT --> BR[ObservedBeliefRegister\nLWW + ObservationProof]
CRDT --> CS[CapabilitySet\nOR-Set add-wins]
Bus --> Recorder[FlightRecorder\nArticle 12 Compliance]
Full solution diagram (Dashboard → API → Simulation → NCE): docs/architecture.md
API
REST + WebSocket backend for the NCE dashboard. See docs/api.md for full reference.
| Endpoint | Description |
|---|---|
POST /control/* |
Start, stop, reset, chaos |
POST /simulate |
Run baseline (nce, no_sync, full_context, central_coordinator) |
WS /ws/simulation |
Stream simulation state updates to dashboard |
uvicorn api.main:app --port 8000
# OpenAPI: http://localhost:8000/docs
Reproducibility
Reproduce paper benchmark tables (5,000 transactions × 3 seeds, 12 agents, adversarial network):
pip install -e ".[dev]"
make bench-paper
Output: docs/paper/tables/summary.md and CSVs. Python 3.11+. Seeds: 42, 7, 137 (Hypothesis property tests use seed 42).
Related Work
NCE builds on established distributed systems research and differentiates from adjacent tools:
| System | CRDT Support | Agent-Aware | A2A Extension | Art.12 Coverage | Delta-sync |
|---|---|---|---|---|---|
| Automerge | ✓ (document CRDTs) | ✗ | ✗ | ✗ | ✓ |
| Yjs | ✓ (collaborative editing) | ✗ | ✗ | ✗ | ✓ |
| Riak | ✓ (database CRDTs) | ✗ | ✗ | ✗ | partial |
| Ray Actors | ✗ | ✓ | ✗ | ✗ | ✗ |
| LangGraph | ✗ | ✓ | ✗ | ✗ | ✗ |
| NCE | ✓ (AS-CRDTs) | ✓ | ✓ | ✓ | ✓ |
NCE's novel contribution is the combination of: (1) CRDT types purpose-designed for agent state semantics (monotone task lifecycle, LWW beliefs with cryptographic provenance, OR-Set capabilities), (2) native Google A2A protocol extension for agent discoverability, and (3) structural Article 12 field coverage as a first-class design constraint. See Shapiro et al. 2011 for foundational CRDT theory.
CRDT Properties
All three CRDT types are property-based validated to satisfy:
- Commutative:
merge(a, b) == merge(b, a) - Associative:
merge(merge(a, b), c) == merge(a, merge(b, c)) - Idempotent:
merge(a, a) == a
Validated by 15+ Hypothesis property-based tests with 100–200 randomly-generated examples each. Property-based testing provides strong empirical evidence but is not equivalent to a formal mathematical proof (e.g., Coq/TLA+).
Benchmarks
| Metric | No Sync | Full Context | Central | NCE |
|---|---|---|---|---|
| Phantom Commits | 271 (5.4%) | 0 | 0 | 7 (0.1%) ✓ |
| Conv. p99 (ms)¹ | N/A | 1,053ms | 250ms | 737ms ✓ |
| Tokens/sync | 0 | ~26,114 | ~2,128 | ~697 ✓ |
| Availability | 100% | 92% | 90% | 100% ✓ |
| Art.12 Field Coverage² | 0% | 50% | 70% | 100% ✓ |
Mean of 3 independent runs (seeds 42, 7, 137), 5,000 transactions each, 12 agents, 2% partition probability.
¹ Convergence latency is modeled, not measured in-process. The simulation uses synchronous in-process delta sync (which converges in 0 ms). The reported p99 reflects one gossip round at the default 500 ms sync_interval_ms + Gaussian jitter (σ=100 ms), representing expected latency in a deployed NCE cluster. Theoretical O(log n) convergence: for n=12 peers, expected 4 rounds = ~2 s worst-case; p99 ≈ 1.7 s with jitter.
² Article 12 field coverage measures the fraction of EU AI Act Article 12–required fields (reference_database, input_data_match, state_before_hash, state_after_hash, vector_clock, agent_id, timestamp) populated in each ComplianceEvent. This is a structural coverage metric, not a legal compliance certification. Persistence across restarts and conformity-body certification are deployment responsibilities.
Contributing
- Fork the repo and create a feature branch
- Run
make ci- all 124 tests must pass - Add property tests for any new CRDT operations
- Submit a PR with a description of the change
License
Apache 2.0
Metadata
Release files for nebula-protocol 1.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nebula_protocol-1.2.1.tar.gz | 68.8 kB | Without provenance | Details for nebula_protocol-1.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nebula_protocol-1.2.1-py3-none-any.whl | Python 3 | none | any | Details for nebula_protocol-1.2.1-py3-none-any.whl |
Total release size: 154.7 kB
Release files / nebula_protocol-1.2.1.tar.gz
| Download URL | nebula_protocol-1.2.1.tar.gz |
|---|---|
| Size | 68.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5ba35d6e9f56f29a0f08151ecf314f66e9d8d6e0609ae9858f2b336b51210e48
|
|
BLAKE2b-256 checksum How to use checksums |
77d973d6edd21a1c0f02584000ad2d839f9fd49cadf79244ffcca29fd5d8af55
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Release files / nebula_protocol-1.2.1-py3-none-any.whl
| Download URL | nebula_protocol-1.2.1-py3-none-any.whl |
|---|---|
| Size | 85.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f8f5610fe129c5e67b725f374a417cde971192401a752236418a3d3ea6b502a4
|
|
BLAKE2b-256 checksum How to use checksums |
04374b820bc1518546f6a9af362164d89171ae5db69c9cb7a31d9e811cc6fe6e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.5
|
Security for nebula-protocol 1.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.