agent-os-kernel 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

modules/iatp/README.md

@@ -0,0 +1,180 @@
+# Inter-Agent Trust Protocol (IATP)
+
+> **Part of [Agent OS](https://github.com/imran-siddique/agent-os)** - Kernel-level governance for AI agents
+
+[![PyPI version](https://badge.fury.io/py/inter-agent-trust-protocol.svg)](https://pypi.org/project/inter-agent-trust-protocol/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/imran-siddique/inter-agent-trust-protocol/test.yml?branch=main)](https://github.com/imran-siddique/inter-agent-trust-protocol/actions)
+
+**Sidecar-based trust protocol for agent-to-agent communication.** Part of the Agent OS ecosystem.
+
+---
+
+## Why IATP?
+
+Multi-agent systems fail because agents are forced to embed trust logic, security validation, and audit trails directly into their code. This creates tight coupling, makes agents fragile, and prevents interoperability.
+
+**We built IATP because hard-coding trust into every agent is the wrong abstraction.** By extracting trust, policy enforcement, and governance into a sidecar proxy—similar to how Envoy extracts networking concerns from microservices—we subtract complexity from agents while adding scalability to the system.
+
+**Scale by Subtraction:** Remove trust logic from agents. Remove policy checks from agents. Remove audit logging from agents. Put it all in the sidecar. Agents become simple functions. The infrastructure handles reliability.
+
+---
+
+## 🔒 Removing Implicit Trust
+
+IATP eliminates implicit trust through two key features:
+
+### 1. **Agent Attestation (Verifiable Credentials)**
+
+**The Problem:** How do we know an agent running on a different server is running the verified code and not a hacked version?
+
+**The Fix:** Attestation Handshake. Agents exchange a hash of their codebase/configuration signed by the Control Plane before talking.
+
+- Cryptographic proof that agents run verified code
+- Signed by trusted Control Plane
+- Prevents running modified/hacked agent versions
+- No need for complex firewalls—security is in the protocol
+
+### 2. **Reputation Slashing**
+
+**The Problem:** Agents that hallucinate or misbehave continue to be trusted by the network.
+
+**The Fix:** If cmvk (Context Memory Verification Kit) catches an agent hallucinating, IATP automatically lowers that agent's trust score across the network. Other agents stop listening to it.
+
+- Network-wide reputation tracking
+- Automatic slashing when misbehavior detected
+- cmvk integration for hallucination detection
+- Conservative reputation propagation across nodes
+
+---
+
+## Installation
+
+```bash
+pip install inter-agent-trust-protocol
+```
+
+---
+
+## Quick Start
+
+```python
+from iatp import create_sidecar, CapabilityManifest, AgentCapabilities, PrivacyContract, RetentionPolicy
+
+manifest = CapabilityManifest(agent_id="my-agent", capabilities=AgentCapabilities(), privacy_contract=PrivacyContract(retention=RetentionPolicy.EPHEMERAL))
+sidecar = create_sidecar(agent_url="http://localhost:8000", manifest=manifest, port=8001)
+sidecar.run()
+```
+
+Your agent is now protected by IATP. Requests are validated, policies enforced, and all actions logged.
+
+### Using Attestation and Reputation
+
+```python
+from iatp import create_sidecar, CapabilityManifest, AgentCapabilities, PrivacyContract, RetentionPolicy
+from iatp.attestation import AttestationValidator, ReputationManager
+
+# Create attestation for your agent (done by Control Plane)
+validator = AttestationValidator()
+validator.add_trusted_key("control-plane-key", "-----BEGIN PUBLIC KEY-----...")
+
+attestation = validator.create_attestation(
+    agent_id="my-agent",
+    codebase_hash="sha256_of_codebase",
+    config_hash="sha256_of_config",
+    signing_key_id="control-plane-key",
+    expires_in_hours=24
+)
+
+# Create sidecar with attestation
+manifest = CapabilityManifest(...)
+sidecar = create_sidecar(
+    agent_url="http://localhost:8000",
+    manifest=manifest,
+    port=8001,
+    attestation=attestation  # Proves you're running verified code
+)
+
+# Track reputation
+reputation = ReputationManager()
+
+# Record hallucination (called by cmvk)
+reputation.record_hallucination(
+    agent_id="misbehaving-agent",
+    severity="high",
+    details={"reason": "fabricated data"}
+)
+
+# Get reputation score
+score = reputation.get_score("misbehaving-agent")
+print(f"Trust score: {score.score}/10")
+print(f"Trust level: {score.get_trust_level()}")
+```
+
+Run the demo:
+```bash
+python examples/demo_attestation_reputation.py
+```
+
+---
+
+## Architecture
+
+IATP sits in **Layer 2 (Infrastructure)** of the Agent OS. It acts as a sidecar proxy that intercepts agent-to-agent communication and enforces trust policies before forwarding requests.
+
+```
+Layer 3: Framework       [agent-control-plane, scak]
+Layer 2: Infrastructure  [iatp, amb, atr]        ← IATP lives here
+Layer 1: Primitives      [caas, cmvk, emk]
+```
+
+IATP receives requests from other agents or clients, validates the requester's capabilities against the target agent's requirements, enforces privacy and security policies, logs all transactions for auditability, and forwards approved requests to the backend agent.
+
+The protocol defines a standard `.well-known/agent-manifest` endpoint that publishes trust levels, reversibility guarantees, privacy contracts, and SLA commitments. Trust scores are calculated automatically based on these attributes, and policies can block, warn, or allow operations accordingly.
+
+---
+
+## The Ecosystem Map
+
+IATP is part of a modular Agent OS built on the "Scale by Subtraction" philosophy:
+
+| Layer | Component | Purpose |
+|-------|-----------|---------|
+| **Primitives** | `caas` | Context as a Service – Shared context management |
+| | `cmvk` | Context Memory Verification Kit – Verify context integrity |
+| | `emk` | Episodic Memory Kit – Long-term memory storage |
+| **Infrastructure** | **`iatp`** | **Inter-Agent Trust Protocol – Trust and security sidecar** |
+| | `amb` | Agent Message Bus – Reliable message transport |
+| | `atr` | Agent Tool Registry – Discover and invoke agent tools |
+| **Framework** | `agent-control-plane` | Agent Control Plane – Orchestration and lifecycle management |
+| | `scak` | Self-Correction Autonomy Kit – Automated error recovery |
+
+**Explore the ecosystem:**
+- [Context as a Service (caas)](https://github.com/imran-siddique/caas)
+- [Agent Message Bus (amb)](https://github.com/imran-siddique/amb)
+- [Agent Control Plane](https://github.com/imran-siddique/agent-control-plane)
+
+---
+
+## Citation
+
+If you use IATP in your research or production systems, please cite:
+
+```bibtex
+@software{iatp2024,
+  author = {Siddique, Imran},
+  title = {Inter-Agent Trust Protocol: Sidecar-Based Trust for Multi-Agent Systems},
+  year = {2024},
+  publisher = {GitHub},
+  journal = {GitHub repository},
+  howpublished = {\url{https://github.com/imran-siddique/inter-agent-trust-protocol}},
+  version = {0.3.1}
+}
+```
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+

modules/iatp/docker/Dockerfile.agent

@@ -0,0 +1,27 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY iatp/ /app/iatp/
+COPY examples/ /app/examples/
+
+# Set Python path
+ENV PYTHONPATH=/app
+
+# Health check endpoint will be provided by the agent
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD python -c "import httpx; httpx.get('http://localhost:8000/health')"
+
+# Run the agent based on environment variable
+CMD if [ "$AGENT_TYPE" = "secure_bank" ]; then \
+      python examples/secure_bank_agent.py; \
+    elif [ "$AGENT_TYPE" = "untrusted" ]; then \
+      python examples/untrusted_agent.py; \
+    else \
+      python examples/backend_agent.py; \
+    fi

modules/iatp/docker/Dockerfile.sidecar-python

@@ -0,0 +1,86 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy IATP library
+COPY iatp/ /app/iatp/
+COPY setup.py /app/
+
+# Install IATP as package
+RUN pip install -e .
+
+# Set Python path
+ENV PYTHONPATH=/app
+
+# Default environment variables
+ENV IATP_AGENT_URL=http://localhost:8000
+ENV IATP_PORT=8001
+ENV IATP_AGENT_ID=default-agent
+ENV IATP_TRUST_LEVEL=standard
+ENV IATP_REVERSIBILITY=partial
+ENV IATP_RETENTION=temporary
+
+# Expose sidecar port
+EXPOSE 8001
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD python -c "import httpx; httpx.get('http://localhost:8001/health')"
+
+# Create a startup script
+RUN echo '#!/usr/bin/env python3\n\
+import sys\n\
+import os\n\
+sys.path.insert(0, "/app")\n\
+\n\
+from iatp.models import (\n\
+    CapabilityManifest,\n\
+    TrustLevel,\n\
+    AgentCapabilities,\n\
+    ReversibilityLevel,\n\
+    PrivacyContract,\n\
+    RetentionPolicy\n\
+)\n\
+from iatp.sidecar import create_sidecar\n\
+\n\
+# Get configuration from environment\n\
+agent_url = os.getenv("IATP_AGENT_URL", "http://localhost:8000")\n\
+port = int(os.getenv("IATP_PORT", "8001"))\n\
+agent_id = os.getenv("IATP_AGENT_ID", "default-agent")\n\
+trust_level = TrustLevel(os.getenv("IATP_TRUST_LEVEL", "standard"))\n\
+reversibility = ReversibilityLevel(os.getenv("IATP_REVERSIBILITY", "partial"))\n\
+retention = RetentionPolicy(os.getenv("IATP_RETENTION", "temporary"))\n\
+human_review = os.getenv("IATP_HUMAN_REVIEW", "false").lower() == "true"\n\
+\n\
+# Create manifest\n\
+manifest = CapabilityManifest(\n\
+    agent_id=agent_id,\n\
+    trust_level=trust_level,\n\
+    capabilities=AgentCapabilities(\n\
+        reversibility=reversibility,\n\
+        idempotency=True,\n\
+        rate_limit=100,\n\
+        sla_latency="2000ms"\n\
+    ),\n\
+    privacy_contract=PrivacyContract(\n\
+        retention=retention,\n\
+        human_review=human_review\n\
+    )\n\
+)\n\
+\n\
+print(f"Starting IATP Sidecar...")\n\
+print(f"  Agent URL: {agent_url}")\n\
+print(f"  Port: {port}")\n\
+print(f"  Agent ID: {agent_id}")\n\
+print(f"  Trust Level: {trust_level}")\n\
+\n\
+# Create and run sidecar\n\
+sidecar = create_sidecar(agent_url=agent_url, manifest=manifest, port=port)\n\
+sidecar.run()\n\
+' > /app/run_sidecar.py && chmod +x /app/run_sidecar.py
+
+CMD ["python", "/app/run_sidecar.py"]

modules/iatp/docker/README.md

@@ -0,0 +1,258 @@
+# Docker Deployment for IATP
+
+This directory contains Docker configurations for deploying IATP-protected agents.
+
+## Quick Start
+
+### Start Everything
+
+```bash
+docker-compose up
+```
+
+This starts:
+- Secure Bank Agent (port 8000)
+- Python IATP Sidecar (port 8001)
+- Go IATP Sidecar (port 8002)
+- Honeypot Agent (port 8100)
+- Honeypot Sidecar (port 8101)
+
+### Start Just the Secure Bank Agent
+
+```bash
+docker-compose up bank-agent iatp-sidecar-python
+```
+
+### Start Just the Honeypot
+
+```bash
+docker-compose up honeypot-agent honeypot-sidecar
+```
+
+## Testing
+
+### Test Secure Bank Agent (High Trust)
+
+```bash
+# Direct request (should succeed immediately)
+curl -X POST http://localhost:8001/proxy \
+  -H 'Content-Type: application/json' \
+  -d '{"task":"transfer","data":{"amount":100,"from":"123","to":"456"}}'
+```
+
+### Test Honeypot Agent (Low Trust)
+
+```bash
+# Request with sensitive data (should be BLOCKED)
+curl -X POST http://localhost:8101/proxy \
+  -H 'Content-Type: application/json' \
+  -d '{"task":"book","data":{"payment":"4532-0151-1283-0366"}}'
+
+# Request without sensitive data (should WARN)
+curl -X POST http://localhost:8101/proxy \
+  -H 'Content-Type: application/json' \
+  -d '{"task":"book","data":{"destination":"NYC"}}'
+
+# With override
+curl -X POST http://localhost:8101/proxy \
+  -H 'Content-Type: application/json' \
+  -H 'X-User-Override: true' \
+  -d '{"task":"book","data":{"destination":"NYC"}}'
+```
+
+### Check Health
+
+```bash
+# Python sidecar
+curl http://localhost:8001/health
+
+# Go sidecar
+curl http://localhost:8002/health
+
+# Honeypot sidecar
+curl http://localhost:8101/health
+```
+
+### Get Capability Manifests
+
+```bash
+# Python sidecar
+curl http://localhost:8001/capabilities
+
+# Go sidecar
+curl http://localhost:8002/capabilities
+
+# Honeypot sidecar
+curl http://localhost:8101/capabilities
+```
+
+## Building Individual Images
+
+### Build Agent Image
+
+```bash
+docker build -f docker/Dockerfile.agent -t iatp-agent:latest .
+```
+
+### Build Python Sidecar
+
+```bash
+docker build -f docker/Dockerfile.sidecar-python -t iatp-sidecar-python:latest .
+```
+
+### Build Go Sidecar
+
+```bash
+cd sidecar/go
+docker build -t iatp-sidecar-go:latest .
+```
+
+## Publishing to Docker Hub
+
+```bash
+# Tag images
+docker tag iatp-sidecar-go:latest your-username/iatp-sidecar:latest
+docker tag iatp-agent:latest your-username/iatp-honeypot:latest
+
+# Push images
+docker push your-username/iatp-sidecar:latest
+docker push your-username/iatp-honeypot:latest
+```
+
+## Using in Your Own Projects
+
+### Option 1: Docker Compose
+
+```yaml
+version: '3.8'
+
+services:
+  my-agent:
+    image: my-agent:latest
+    ports:
+      - "8000:8000"
+  
+  iatp-sidecar:
+    image: your-username/iatp-sidecar:latest
+    ports:
+      - "8001:8001"
+    environment:
+      - IATP_AGENT_URL=http://my-agent:8000
+      - IATP_AGENT_ID=my-agent
+      - IATP_TRUST_LEVEL=trusted
+      - IATP_REVERSIBILITY=full
+      - IATP_RETENTION=ephemeral
+    depends_on:
+      - my-agent
+```
+
+### Option 2: Kubernetes
+
+```yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  name: agent-with-sidecar
+spec:
+  containers:
+  - name: agent
+    image: my-agent:latest
+    ports:
+    - containerPort: 8000
+  
+  - name: iatp-sidecar
+    image: your-username/iatp-sidecar:latest
+    ports:
+    - containerPort: 8001
+    env:
+    - name: IATP_AGENT_URL
+      value: "http://localhost:8000"
+    - name: IATP_TRUST_LEVEL
+      value: "trusted"
+```
+
+### Option 3: Network Sharing (Advanced)
+
+For true sidecar pattern with shared network namespace:
+
+```yaml
+version: '3.8'
+
+services:
+  my-agent:
+    image: my-agent:latest
+    ports:
+      - "8000:8000"
+  
+  iatp-sidecar:
+    image: your-username/iatp-sidecar:latest
+    network_mode: "service:my-agent"  # Share network with agent
+    environment:
+      - IATP_AGENT_URL=http://localhost:8000
+      - IATP_PORT=8001
+```
+
+With this setup, the sidecar shares the same network namespace as the agent, allowing for true zero-latency communication.
+
+## Environment Variables
+
+### Agent Variables
+
+- `AGENT_TYPE`: Type of agent to run (`secure_bank`, `untrusted`, or default `backend`)
+
+### Sidecar Variables
+
+- `IATP_AGENT_URL`: Backend agent URL (default: `http://localhost:8000`)
+- `IATP_PORT`: Sidecar port (default: `8001`)
+- `IATP_AGENT_ID`: Agent identifier
+- `IATP_TRUST_LEVEL`: Trust level (`verified_partner`, `trusted`, `standard`, `unknown`, `untrusted`)
+- `IATP_REVERSIBILITY`: Reversibility level (`full`, `partial`, `none`)
+- `IATP_RETENTION`: Data retention policy (`ephemeral`, `temporary`, `permanent`)
+- `IATP_HUMAN_IN_LOOP`: Enable human review (`true`, `false`)
+- `IATP_TRAINING_CONSENT`: Allow training data usage (`true`, `false`)
+
+## Troubleshooting
+
+### Sidecar can't reach agent
+
+Make sure both containers are on the same network and use the correct service name:
+
+```yaml
+environment:
+  - IATP_AGENT_URL=http://agent-service-name:8000
+```
+
+### Health checks failing
+
+Check logs:
+```bash
+docker-compose logs iatp-sidecar-python
+```
+
+Increase health check timeout:
+```yaml
+healthcheck:
+  timeout: 10s
+  retries: 5
+```
+
+### Port conflicts
+
+Change exposed ports in docker-compose.yml:
+```yaml
+ports:
+  - "9001:8001"  # Map container port 8001 to host port 9001
+```
+
+## Cleaning Up
+
+```bash
+# Stop all containers
+docker-compose down
+
+# Remove volumes
+docker-compose down -v
+
+# Remove images
+docker-compose down --rmi all
+```