Metadata-Version: 2.4
Name: nebula-protocol
Version: 1.1.1
Summary: CRDT-based convergent state replication for heterogeneous multi-agent systems. Prevents phantom commitments via AS-CRDTs and A2A protocol extension.
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Jarvis2021/nebula-protocol
Project-URL: Repository, https://github.com/Jarvis2021/nebula-protocol
Project-URL: Source, https://github.com/Jarvis2021/nebula-protocol
Project-URL: Documentation, https://github.com/Jarvis2021/nebula-protocol#readme
Keywords: crdt,multi-agent,a2a,distributed-systems,eventual-consistency
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.27
Requires-Dist: cryptography>=42.0
Requires-Dist: uvicorn>=0.30
Requires-Dist: fastapi>=0.115
Requires-Dist: websockets>=13.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: hypothesis>=6.100; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.11; extra == "dev"
Provides-Extra: sim
Requires-Dist: openai>=1.50; extra == "sim"
Requires-Dist: anthropic>=0.37; extra == "sim"
Requires-Dist: google-generativeai>=0.8; extra == "sim"
Requires-Dist: numpy>=1.26; extra == "sim"
Requires-Dist: pandas>=2.2; extra == "sim"
Requires-Dist: matplotlib>=3.9; extra == "sim"
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.115; extra == "dashboard"
Requires-Dist: uvicorn>=0.30; extra == "dashboard"
Requires-Dist: websockets>=13.0; extra == "dashboard"
Dynamic: license-file

# Nebula Protocol

[![CI](https://github.com/Jarvis2021/nebula-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/Jarvis2021/nebula-protocol/actions)
[![PyPI](https://img.shields.io/badge/pypi-v1.1.1-blue.svg)](https://pypi.org/project/nebula-protocol/1.1.1/)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
[![Node 18+](https://img.shields.io/badge/node-18+-green.svg)](https://nodejs.org/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-green.svg)](LICENSE)

**Nebula Convergence Engine (NCE)** — CRDT-based convergent state replication for heterogeneous multi-agent systems, extending Google's [A2A protocol](https://github.com/google/A2A).

| Section | Description |
|---------|--------------|
| [Problem](#the-problem) | Phantom commitments in multi-agent coordination |
| [Solution](#the-solution) | AS-CRDTs and observation proofs |
| [Quick Start](#quick-start) | Install, run, verify |
| [Dashboard](#dashboard) | Demo and Live modes |
| [Architecture](#architecture) | NCE Core, ADRs, diagrams |
| [API](#api) | REST + WebSocket reference |
| [Reproducibility](#reproducibility) | Paper Table 5 reproduction |
| [Benchmarks](#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

```bash
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](docs/dashboard-guide.md)** - Technical implementation details (12 agents, API contract, components).

## Demo

![NCE Dashboard - 12 agents, 3 providers, real-time simulation](docs/demo.gif)

*Run simulation in Demo Mode; KPIs, charts, and agent fleet update in real time.*

## Architecture

See **[docs/architecture.md](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:**

```python
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)

```mermaid
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](docs/architecture.md)**

## API

REST + WebSocket backend for the NCE dashboard. See **[docs/api.md](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 |

```bash
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):

```bash
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).

## 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 Coverage | 0% | 50% | 70% | **100% ✓** |

*Mean of 3 independent runs (seeds 42, 7, 137), 5,000 transactions each.*

## CRDT Properties

All three CRDT types are mathematically verified to be:
- **Commutative**: `merge(a, b) == merge(b, a)`
- **Associative**: `merge(merge(a, b), c) == merge(a, merge(b, c))`
- **Idempotent**: `merge(a, a) == a`

Verified by 15+ Hypothesis property-based tests with 100–200 random examples each.

## Contributing

1. Fork the repo and create a feature branch
2. Run `make ci` - all 124 tests must pass
3. Add property tests for any new CRDT operations
4. Submit a PR with a description of the change

## License

Apache 2.0
