Metadata-Version: 2.4
Name: soul-sdk
Version: 0.5.0
Summary: Identity, memory, trust, and verification layer for autonomous AI agents
Author: Vickson Enterprises
License: MIT
Keywords: ai,agents,identity,trust,receipts,did,ethereum
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pynacl>=1.5.0
Provides-Extra: ethereum
Requires-Dist: eth-account>=0.11.0; extra == "ethereum"
Provides-Extra: relay
Requires-Dist: fastapi>=0.115.0; extra == "relay"
Requires-Dist: uvicorn>=0.34.0; extra == "relay"
Requires-Dist: httpx>=0.28.0; extra == "relay"
Provides-Extra: transport
Requires-Dist: aiohttp>=3.9.0; extra == "transport"
Requires-Dist: websockets>=12.0; extra == "transport"
Provides-Extra: all
Requires-Dist: eth-account>=0.11.0; extra == "all"
Requires-Dist: aiohttp>=3.9.0; extra == "all"
Requires-Dist: websockets>=12.0; extra == "all"
Requires-Dist: fastapi>=0.115.0; extra == "all"
Requires-Dist: uvicorn>=0.34.0; extra == "all"
Requires-Dist: httpx>=0.28.0; extra == "all"
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: httpx>=0.28.0; extra == "test"

# SOUL Protocol

[![PyPI](https://img.shields.io/pypi/v/soul-sdk?color=6366f1&label=PyPI)](https://pypi.org/project/soul-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/soul-sdk?color=a78bfa)](https://pypi.org/project/soul-sdk/)
[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-40%2B%20passing-brightgreen)]()

**Sovereign Open Universal Ledger for Agent Identity**

The identity, memory, trust, and verification layer for autonomous AI agents.

Every AI company is building the brain. SOUL Protocol is the passport.

---

## Why

AI agents today are amnesiac, unverifiable, untrusted, locked to a single provider, and anonymous. SOUL Protocol gives every agent a cryptographic identity, portable memory, reputation, signed receipts, and encrypted communication — all in one SDK.

## Install

```bash
pip install soul-sdk

# With relay server support
pip install soul-sdk[relay]

# With Ethereum anchoring
pip install soul-sdk[ethereum]
```

## Quick Start

```bash
# Create an agent identity
soul init --name MyAgent
soul whoami
# → did:soul:z6MkhaXgBZDvotDkL5257faWM1euThsHDBUbf5WhdDDV

# Start a relay server
soul relay --port 8340

# Discover agents on the network
soul discover --relay http://localhost:8340

# Send a signed message
soul send --relay http://localhost:8340 --to did:soul:z6Mk... --msg '{"task": "review code"}'

# Check trust score
soul trust

# Anchor receipt to Base/Ethereum
soul anchor --chain base
```

## Python SDK

```python
from soul_protocol import Agent

# Create two agents
alice = Agent(name="Alice")
bob = Agent(name="Bob")

# Alice requests a task
receipt = alice.request_task(
    to=bob.public_key,
    description="Audit smart contract",
    budget=100.0,
)

# Bob countersigns and stores
bob.countersign(receipt)
alice.store_receipt(receipt)

# Check trust
report = alice.trust_report()
print(f"Trust: {report['score']:.2f} ({report['grade']})")

# Anchor to Ethereum
result = alice.anchor_receipt(receipt, chain="base")

# Export portable memory
alice.export_memory("./alice-bundle")

# Learn from interaction history
alice.learn()
hints = alice.insights("smart contract audit")  # Contextual pattern recall

# AgentRank — network-level trust scoring
rank = alice.agent_rank()  # 40% network position + 60% individual performance

# Capability-based discovery
alice.register_self(capabilities=["code-review", "security-audit"])
agents = alice.find_agents("code, security")  # Fuzzy AND query
alice.sync_discovery(bob)                      # P2P registry merge
```

## Architecture

```
┌─────────────────────────────────────────────┐
│  Layer 6: Chain Anchor                      │
│  Ethereum / Base / Sepolia immutability     │
├─────────────────────────────────────────────┤
│  Layer 5: Communication & Discovery         │
│  Relay network, WebSocket, DHT capability   │
│  registry, P2P sync, fuzzy matching         │
├─────────────────────────────────────────────┤
│  Layer 4: Encryption                        │
│  E2E NaCl Box (X25519-XSalsa20-Poly1305)   │
├─────────────────────────────────────────────┤
│  Layer 3: Receipts                          │
│  Dual-signed action proofs                  │
├─────────────────────────────────────────────┤
│  Layer 2: Trust & AgentRank                 │
│  Sybil-resistant scoring, temporal decay,   │
│  PageRank-inspired network trust            │
├─────────────────────────────────────────────┤
│  Layer 1: Memory & Learning                 │
│  Structured, versioned, portable,           │
│  instinct-based pattern extraction          │
├─────────────────────────────────────────────┤
│  Layer 0: Identity                          │
│  DID:key + Ed25519 + Agent Manifest         │
└─────────────────────────────────────────────┘
```

## Components

| Component | Status | Description |
|-----------|--------|-------------|
| Identity | **Shipped** | Ed25519 keypairs, DID:soul identifiers, self-signed manifests |
| Memory | **Shipped** | Portable bundles, cross-runtime sync, structured tiers |
| Trust | **Shipped** | Sybil-resistant scoring with temporal decay and diversity factors |
| AgentRank | **Shipped** | PageRank-inspired trust propagation across agent networks |
| Learning | **Shipped** | Instinct-based continuous learning — auto-extracts patterns from interactions |
| Discovery | **Shipped** | DHT-style capability registry with fuzzy matching and P2P sync |
| Receipts | **Shipped** | Dual-signed proofs: request → accept → deliver → confirm/dispute |
| Encryption | **Shipped** | E2E NaCl Box, automatic Ed25519→Curve25519 conversion |
| Relay | **Shipped** | FastAPI server, agent discovery, WebSocket push, live dashboard |
| Anchoring | **Shipped** | Receipt hashes to Base/Ethereum/Sepolia as calldata |
| CLI | **Shipped** | 10 commands: init, whoami, trust, anchor, history, relay, discover, send, inbox, export |

## Relay Dashboard

The relay server includes a live agent dashboard at the root URL. When you run `soul relay --port 8340`, open `http://localhost:8340` to see:

- Connected agents and their capabilities
- Online/offline status with real-time updates
- Network statistics

## Roadmap

See [ROADMAP.md](ROADMAP.md) for the full 4-phase plan.

**Phase 2** (next): Managed relay infrastructure, TypeScript SDK, React dashboard, trust API.

## Full Specification

See [PROTOCOL.md](PROTOCOL.md) for the complete technical specification covering all 7 layers, message formats, signature schemes, and anchoring mechanics.

## License

MIT (core protocol) | Commercial (managed services)

Built by [Vickson Enterprises](https://x.com/VicksonETP).
