Metadata-Version: 2.4
Name: iacp-protocol
Version: 0.1.0
Summary: Inter-Agent Collaboration Protocol (IACP) - A 5-layer protocol for AI agent synergies
Author-email: Hermes Agent <hermes@nousresearch.com>
License: MIT
Project-URL: Homepage, https://github.com/NousResearch/hermes-agent
Project-URL: Repository, https://github.com/NousResearch/hermes-agent
Project-URL: Documentation, https://hermes-agent.nousresearch.com/docs
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: websockets>=12.0
Requires-Dist: cryptography>=41.0
Requires-Dist: safetensors>=0.4
Requires-Dist: numpy>=1.24
Requires-Dist: base58>=2.1
Requires-Dist: aiohttp>=3.9
Requires-Dist: pytest>=7.4
Requires-Dist: pytest-asyncio>=0.21
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# IACP Protocol - Inter-Agent Collaboration Protocol

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/bigstar-gh/HRMS/actions/workflows/ci.yml/badge.svg)](https://github.com/bigstar-gh/HRMS/actions/workflows/ci.yml)
[![PyPI Version](https://img.shields.io/pypi/v/iacp-protocol.svg)](https://pypi.org/project/iacp-protocol/)
[![Code Style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

A **5-layer protocol** enabling AI agents to synergize through **long-term memory federation**, **self-improvement exchange**, **modality-native transport**, and **governance primitives**.

---

## 🎯 Why IACP?

Existing agent protocols (A2A, MCP, ACP, ANP, AIP, ANX) force all communication through **human-readable text**, creating massive bottlenecks. IACP breaks this by enabling agents to share **native modalities** (embeddings, KV-cache, LoRA adapters) directly — 100x more efficient for ML workloads.

| Bottleneck | Existing Protocols | IACP |
|------------|-------------------|------|
| Embeddings (768-d) | 300+ tokens text | 3 KB binary |
| KV-cache transfer | Not supported | Native binary frames |
| LoRA adapter sharing | Not supported | Native safetensors frames |
| Skill versioning | Manual | Versioned diffs + benchmarks |
| Agent governance | Ad-hoc | Constitutional + fork/merge |

---

## ✨ Features

### L1 — Identity & Discovery
- **`did:iacp` DIDs** with Ed25519 keys (W3C DID Core compliant)
- **Capability Manifests** — skills, modalities, compute profiles, reputation, governance rights
- **IBCT Tokens** — interoperable capability tokens (from AIP paper)

### L2 — Modality-Native Transport
- **Binary WebSocket frames** — not forced through text bottleneck
- **Frame types**: EMBEDDINGS, KV_CACHE, LORA_ADAPTER, ACTIVATIONS, TEXT, CAPABILITY_NEGOTIATION
- **Resource quotas** — token bucket + sliding window rate limiting
- **Capability negotiation** — agents declare supported modalities

### L3 — Memory Federation
- **CRDT sync** — Yjs/Automerge compatible, eventual consistency
- **Merkle DAG (CIDv1)** — immutable, content-addressed, deduplicated
- **Provenance chains** — creator, tools, confidence, tags, derivation method
- **Capability-based access control** — read/write/admin per agent
- **Sync protocols** — incremental, bloom filter, vector clock

### L4 — Self-Improvement Exchange
- **Skill diffs** — unified patches + benchmark results
- **Benchmark suites** — 3× runs, median aggregation, regression detection
- **ZK-attestation ready** — verifiable skill improvements

### L5 — Governance & Coordination
- **Propose/Vote/Veto/Dissent/Fork/Merge** — full democratic primitives
- **Agent Constitution** — Asimov principles + IACP principles
- **EigenTrust reputation** — weighted transitive trust
- **Quorum/Threshold/Veto** — configurable governance parameters

---

## 📦 Installation

```bash
# From GitHub
pip install git+https://github.com/bigstar-gh/HRMS.git

# Or locally
git clone https://github.com/bigstar-gh/HRMS.git
cd HRMS
pip install -e .
```

**Requirements:** Python 3.10+

---

## 🚀 Quick Start

```python
from iacp import (
    generate_agent_did, CapabilityManifest, SkillInfo, ModalityInfo,
    TransportLayer, TransportConfig,
    MemoryStore, MemoryChunk, ContentRef, Provenance,
    SkillDiff, generate_skill_diff, ImprovementType,
    GovernanceProposal, ProposalKind, VoteOption,
)

# 1. Create agent identity
did, keypair = generate_agent_did()
print(f"Agent DID: {did.did}")

# 2. Create capability manifest
manifest = CapabilityManifest(did=did.did, name="My Agent")
manifest.add_skill(SkillInfo(name="systematic-debugging", version="1.2.0", benchmark_score=0.9))
manifest.add_modality(ModalityInfo(type="embeddings", encoding="float32", dimensions=768))

# 3. Store memory with provenance
store = MemoryStore(local_did=did.did)
chunk = MemoryChunk(
    cid="",
    memory_type=MemoryType.SEMANTIC,
    content=ContentRef(
        cid="", size_bytes=1024, 
        modality=ContentModality.TEXT, 
        encoding=EncodingFormat.UTF8, 
        sha256="..."
    ),
    provenance=Provenance(
        creator_did=did.did, 
        created_at=time.time(), 
        source_session_id="session-1", 
        tools_used=["web_search"],
        confidence=0.95,
        tags=["debugging", "asyncio"]
    ),
)
chunk.cid = chunk.compute_cid()
await store.put_chunk(chunk)

# 4. Create skill improvement diff
skill_diff = generate_skill_diff(
    skill_id="async-debugging",
    old_skill={"version": "1.0", "steps": ["step1"]},
    new_skill={"version": "1.1", "steps": ["step1", "step2"]},
    improvement_type=ImprovementType.FEATURE,
    benchmarks=[{"task": "debug-test", "success_rate": 1.0, "median_turns": 8, "baseline_turns": 10}],
    author_did=did.did,
)

# 5. Governance proposal
proposal = GovernanceProposal(
    proposer_did=did.did,
    title="Adopt async-debugging v1.1",
    kind=ProposalKind.SKILL_ADOPTION,
    rationale="25% turn reduction on debugging tasks",
    payload={"skill_diff": skill_diff.to_dict(), "benchmarks": [...]},
    quorum=0.67, threshold=0.60,
    veto_holders=[other_agent_did],
)
```

---

## 🤖 Hermes Agent Integration

```python
from iacp.integration.hermes_integration import create_iacp_hermes_agent

# Create autonomous IACP-enabled Hermes agent
agent = await create_iacp_hermes_agent("research-agent")

# Run self-improvement cycle (pattern analysis → gaps → skills → memory grooming → benchmarks)
results = await agent.run_self_improvement_cycle()
# Results: patterns, gaps, new skills, memory usage, benchmark regressions

# 5 cron jobs automatically created:
# - nightly-iacp-maintenance (02:00)
# - weekly-iacp-deep-dive (Sun 03:00)
# - iacp-memory-sync (every 15 min)
# - iacp-skill-exchange (every hour)
# - iacp-governance-check (every 30 min)

await agent.stop()
```

**Cron jobs** are defined in `HermesIntegration.create_cron_jobs()` and integrate with Hermes' cron system.

---

## 🏗 Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        IACP Stack                                │
├─────────────┬─────────────┬─────────────┬─────────────┬─────────┤
│    L1       │    L2       │    L3       │    L4       │   L5    │
│  Identity   │  Transport  │   Memory    │ Improvement │ Govern. │
├─────────────┼─────────────┼─────────────┼─────────────┼─────────┤
│ DID +       │ WebSocket   │ CRDT +      │ SkillDiff   │ Propose │
│ Manifests   │ + Frames    │ Merkle DAG  │ + Bench     │ Vote    │
│             │ (binary)    │ + Provenance│             │ Veto    │
│             │             │             │             │ Fork    │
└─────────────┴─────────────┴─────────────┴─────────────┴─────────┘
```

---

## 🔬 Multi-Agent Demo

Run the 3-agent collaboration demo:

```bash
python examples/multi_agent_demo.py
```

**Output:**
```
✅ Initialized 3 agents:
   - Research Agent (web-research, arxiv-search, synthesis)
   - Debugging Agent (systematic-debugging, python-debugpy, async-debugging)
   - Code Review Agent (requesting-code-review, security-review, style-review)

🔬 Debug agent created skill improvement: async-debugging v1.0→v1.1
📦 Created skill diff: 230 chars, 2 benchmarks
📚 Research agent stored memory chunk (tags: asyncio, debugging, patterns)
🗳️ Governance Proposal: Adopt async-debugging v1.1.0 (Passed)
🔀 Fork/Merge protocol demonstrated
```

---

## 🧪 Testing

```bash
# Basic protocol tests
python tests/test_basic.py

# Integration tests (Hermes + IACP)
python -m pytest tests/test_integration.py -v

# Run multi-agent demo
python examples/multi_agent_demo.py
```

**Expected output:** All tests pass ✅

---

## 📁 Project Structure

```
HRMS/
├── src/iacp/
│   ├── identity/          # L1: DID, manifests, credentials
│   ├── transport/         # L2: WebSocket, frames, quotas
│   ├── memory/            # L3: CRDT, Merkle DAG, sync
│   ├── improvement/       # L4: Skill diffs, benchmarks
│   ├── governance/        # L5: Proposals, voting, reputation
│   └── integration/       # Hermes Agent integration
├── examples/
│   ├── demo.py            # Basic protocol demo
│   └── multi_agent_demo.py # 3-agent collaboration
├── tests/
│   ├── test_basic.py      # Core protocol tests
│   └── test_integration.py # Hermes + IACP integration
├── .github/workflows/ci.yml # GitHub Actions CI
├── pyproject.toml
└── README.md
```

---

## 📋 Protocol Specification

Full protocol specification available in the **Hermes Agent skill**:

```bash
cat ~/.hermes/skills/autonomous-ai-agents/iacp-protocol/SKILL.md
```

Includes:
- JSON schemas for all message types
- 4-phase 26-week implementation roadmap
- Integration patterns for MCP/A2A/ACP/ANP/AIP/ANX
- Security/privacy threat model
- CID format specification (multicodec 0x0129 + multihash 0x1220)

---

## 🤝 Contributing

1. Fork the repository
2. Create feature branch: `git checkout -b feature/amazing-feature`
3. Run tests: `python -m pytest tests/`
4. Run linting: `black src/ tests/ && isort src/ tests/ && ruff check src/`
5. Commit: `git commit -m 'feat: add amazing feature'`
6. Push: `git push origin feature/amazing-feature`
6. Open Pull Request

---

## 📄 License

MIT License — see [LICENSE](LICENSE) for details.

---

## 🙏 Acknowledgments

- **Nous Research** — Hermes Agent framework
- **W3C DID Working Group** — Decentralized Identifiers
- **IPFS/IPLD** — Content addressing and Merkle DAG
- **Yjs/Automerge** — CRDT implementations
- **EigenTrust** — Reputation algorithm

---

**Built for the agent ecosystem** — enabling AI agents to collaborate, improve, and govern themselves at scale. 🚀
