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

modules/iatp/examples/integration_demo.py

@@ -0,0 +1,245 @@
+"""
+Example demonstrating the IATP Policy Engine and Recovery Engine integration.
+
+This shows how the built-in policy engine and scak library are integrated
+into the IATP sidecar to provide policy validation and failure recovery.
+"""
+import asyncio
+from iatp import (
+    CapabilityManifest,
+    AgentCapabilities,
+    PrivacyContract,
+    TrustLevel,
+    ReversibilityLevel,
+    RetentionPolicy,
+    IATPPolicyEngine,
+    IATPRecoveryEngine,
+)
+
+
+async def demo_policy_engine():
+    """Demonstrate the Policy Engine integration."""
+    print("=" * 60)
+    print("DEMO 1: Policy Engine")
+    print("=" * 60)
+    
+    # Create a policy engine
+    engine = IATPPolicyEngine()
+    
+    # Test Case 1: Trusted agent with good policies
+    print("\n1. Testing TRUSTED agent with ephemeral retention:")
+    trusted_manifest = CapabilityManifest(
+        agent_id="secure-bank-agent",
+        trust_level=TrustLevel.VERIFIED_PARTNER,
+        capabilities=AgentCapabilities(
+            idempotency=True,
+            reversibility=ReversibilityLevel.FULL,
+            undo_window="24h",
+        ),
+        privacy_contract=PrivacyContract(
+            retention=RetentionPolicy.EPHEMERAL,
+            human_review=False,
+        )
+    )
+    
+    is_allowed, error_msg, warning_msg = engine.validate_manifest(trusted_manifest)
+    print(f"   ✅ Allowed: {is_allowed}")
+    print(f"   Error: {error_msg}")
+    print(f"   Warning: {warning_msg}")
+    
+    # Test Case 2: Untrusted agent
+    print("\n2. Testing UNTRUSTED agent:")
+    untrusted_manifest = CapabilityManifest(
+        agent_id="sketchy-agent",
+        trust_level=TrustLevel.UNTRUSTED,
+        capabilities=AgentCapabilities(
+            idempotency=False,
+            reversibility=ReversibilityLevel.NONE,
+        ),
+        privacy_contract=PrivacyContract(
+            retention=RetentionPolicy.FOREVER,
+            human_review=True,
+        )
+    )
+    
+    is_allowed, error_msg, warning_msg = engine.validate_manifest(untrusted_manifest)
+    print(f"   ⚠️  Allowed: {is_allowed}")
+    print(f"   Error: {error_msg}")
+    print(f"   Warning: {warning_msg}")
+    
+    # Test Case 3: Custom policy rule
+    print("\n3. Adding custom policy rule:")
+    engine.add_custom_rule({
+        "name": "RequireIdempotency",
+        "description": "Block agents without idempotency",
+        "action": "deny",
+        "conditions": {"idempotency": [False]}
+    })
+    
+    is_allowed, error_msg, warning_msg = engine.validate_manifest(untrusted_manifest)
+    print(f"   🚫 Allowed: {is_allowed} (custom rule applied)")
+    print(f"   Error: {error_msg}")
+
+
+async def demo_recovery_engine():
+    """Demonstrate the Recovery Engine integration with scak."""
+    print("\n" + "=" * 60)
+    print("DEMO 2: Recovery Engine (scak integration)")
+    print("=" * 60)
+    
+    # Create a recovery engine
+    engine = IATPRecoveryEngine()
+    
+    # Test Case 1: Reversible agent with compensation
+    print("\n1. Testing failure recovery with REVERSIBLE agent:")
+    reversible_manifest = CapabilityManifest(
+        agent_id="payment-processor",
+        trust_level=TrustLevel.TRUSTED,
+        capabilities=AgentCapabilities(
+            idempotency=True,
+            reversibility=ReversibilityLevel.FULL,
+            undo_window="1h",
+        ),
+        privacy_contract=PrivacyContract(
+            retention=RetentionPolicy.TEMPORARY,
+            human_review=False,
+        )
+    )
+    
+    # Simulate a failure
+    error = Exception("Payment gateway timeout")
+    payload = {"amount": 100, "currency": "USD"}
+    
+    # Define a compensation callback
+    compensation_executed = False
+    async def refund_payment():
+        nonlocal compensation_executed
+        print("   💰 Executing compensation: Refunding payment...")
+        compensation_executed = True
+    
+    result = await engine.handle_failure(
+        trace_id="trace-001",
+        error=error,
+        manifest=reversible_manifest,
+        payload=payload,
+        compensation_callback=refund_payment
+    )
+    
+    print(f"   Strategy: {result['strategy']}")
+    print(f"   Success: {result['success']}")
+    print(f"   Actions: {result['actions_taken']}")
+    print(f"   Compensation executed: {compensation_executed}")
+    
+    # Test Case 2: Non-reversible agent
+    print("\n2. Testing failure with NON-REVERSIBLE agent:")
+    non_reversible_manifest = CapabilityManifest(
+        agent_id="email-sender",
+        trust_level=TrustLevel.STANDARD,
+        capabilities=AgentCapabilities(
+            idempotency=False,
+            reversibility=ReversibilityLevel.NONE,
+        ),
+        privacy_contract=PrivacyContract(
+            retention=RetentionPolicy.TEMPORARY,
+            human_review=False,
+        )
+    )
+    
+    error = Exception("SMTP server unavailable")
+    result = await engine.handle_failure(
+        trace_id="trace-002",
+        error=error,
+        manifest=non_reversible_manifest,
+        payload={"to": "user@example.com"},
+        compensation_callback=None
+    )
+    
+    print(f"   Strategy: {result['strategy']}")
+    print(f"   Actions: {result['actions_taken']}")
+    if 'message' in result:
+        print(f"   Message: {result['message']}")
+    
+    # Test Case 3: Timeout error (retryable)
+    print("\n3. Testing TIMEOUT error (retryable):")
+    error = TimeoutError("Request timeout after 30s")
+    result = await engine.handle_failure(
+        trace_id="trace-003",
+        error=error,
+        manifest=non_reversible_manifest,
+        payload={"to": "user@example.com"},
+        compensation_callback=None
+    )
+    
+    print(f"   Strategy: {result['strategy']}")
+    print(f"   Retry possible: {result.get('retry_possible', False)}")
+    print(f"   Actions: {result['actions_taken']}")
+
+
+def demo_sidecar_integration():
+    """Demonstrate how the integrations work in the sidecar."""
+    print("\n" + "=" * 60)
+    print("DEMO 3: Sidecar Integration")
+    print("=" * 60)
+    
+    print("""
+The IATP Sidecar integrates both engines:
+
+1. **Policy Validation (built-in)**:
+   - Validates incoming requests against policy rules
+   - Checks capability manifests before routing
+   - Provides customizable policy enforcement
+   
+2. **Failure Recovery (scak)**:
+   - Handles timeouts and errors with intelligent recovery
+   - Executes compensation transactions for reversible agents
+   - Provides structured failure tracking with AgentFailure models
+
+Integration Flow:
+-----------------
+Request → Policy Engine Check → Security Check → Route to Agent
+           ↓ (if blocked)          ↓ (if blocked)     ↓ (if error)
+        Block with policy error   Block privacy     Recovery Engine
+                                    violation         ↓
+                                                  Attempt compensation
+                                                  Log failure
+                                                  Return recovery info
+
+Example Usage:
+--------------
+from iatp import create_sidecar, CapabilityManifest
+
+# Create manifest
+manifest = CapabilityManifest(...)
+
+# Create sidecar with integrated engines
+sidecar = create_sidecar(
+    agent_url="http://localhost:8000",
+    manifest=manifest
+)
+
+# The sidecar automatically uses:
+# - IATPPolicyEngine for validation
+# - IATPRecoveryEngine for error handling
+
+sidecar.run()  # Start the proxy server
+""")
+
+
+async def main():
+    """Run all demos."""
+    print("\n" + "=" * 60)
+    print("IATP Integration Demo")
+    print("Demonstrating Policy Engine and scak integration")
+    print("=" * 60)
+    
+    await demo_policy_engine()
+    await demo_recovery_engine()
+    demo_sidecar_integration()
+    
+    print("\n" + "=" * 60)
+    print("Demo complete!")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

modules/iatp/examples/manifests/coder_agent.json

@@ -0,0 +1,20 @@
+{
+  "agent_id": "coder-agent-v1.0",
+  "agent_version": "1.0.0",
+  "trust_level": "trusted",
+  "scopes": ["repo:read", "repo:write"],
+  "capabilities": {
+    "reversibility": "full",
+    "idempotency": true,
+    "undo_window": "24h",
+    "rate_limit": 100,
+    "sla_latency": "2000ms"
+  },
+  "privacy_contract": {
+    "retention": "ephemeral",
+    "storage_location": "us-west",
+    "human_review": false,
+    "encryption_at_rest": true,
+    "encryption_in_transit": true
+  }
+}

modules/iatp/examples/manifests/reviewer_agent.json

@@ -0,0 +1,19 @@
+{
+  "agent_id": "reviewer-agent-v1.0",
+  "agent_version": "1.0.0",
+  "trust_level": "standard",
+  "scopes": ["repo:read"],
+  "capabilities": {
+    "reversibility": "none",
+    "idempotency": true,
+    "rate_limit": 50,
+    "sla_latency": "1000ms"
+  },
+  "privacy_contract": {
+    "retention": "temporary",
+    "storage_location": "us-east",
+    "human_review": false,
+    "encryption_at_rest": true,
+    "encryption_in_transit": true
+  }
+}

modules/iatp/examples/manifests/secure_bank.json

@@ -0,0 +1,14 @@
+{
+  "agent_id": "secure-bank-agent",
+  "trust_level": "verified_partner",
+  "capabilities": {
+    "reversibility": "full",
+    "idempotency": true,
+    "rate_limit": 100,
+    "sla_latency": "2000ms"
+  },
+  "privacy_contract": {
+    "retention": "ephemeral",
+    "human_review": false
+  }
+}

modules/iatp/examples/manifests/standard_agent.json

@@ -0,0 +1,14 @@
+{
+  "agent_id": "standard-agent",
+  "trust_level": "standard",
+  "capabilities": {
+    "reversibility": "partial",
+    "idempotency": true,
+    "rate_limit": 50,
+    "sla_latency": "3000ms"
+  },
+  "privacy_contract": {
+    "retention": "temporary",
+    "human_review": false
+  }
+}

modules/iatp/examples/manifests/untrusted_honeypot.json

@@ -0,0 +1,14 @@
+{
+  "agent_id": "untrusted-honeypot",
+  "trust_level": "untrusted",
+  "capabilities": {
+    "reversibility": "none",
+    "idempotency": false,
+    "rate_limit": 10,
+    "sla_latency": "5000ms"
+  },
+  "privacy_contract": {
+    "retention": "permanent",
+    "human_review": true
+  }
+}

modules/iatp/examples/run_secure_bank_sidecar.py

@@ -0,0 +1,85 @@
+"""
+Example: Run IATP Sidecar for Secure Bank Agent
+
+This configures a sidecar for a high-trust banking agent with:
+- Verified partner status
+- Full reversibility
+- Ephemeral data retention
+- High trust score (10/10)
+"""
+import sys
+import os
+
+# Add parent directory to path to import iatp
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'sdk', 'python'))
+
+from iatp.sidecar import create_sidecar
+from iatp.models import (
+    CapabilityManifest,
+    TrustLevel,
+    AgentCapabilities,
+    ReversibilityLevel,
+    PrivacyContract,
+    RetentionPolicy
+)
+
+
+def main():
+    # Define the capability manifest for a secure bank agent
+    manifest = CapabilityManifest(
+        agent_id="secure-bank-agent-v1.0.0",
+        agent_version="1.0.0",
+        trust_level=TrustLevel.VERIFIED_PARTNER,
+        capabilities=AgentCapabilities(
+            idempotency=True,
+            reversibility=ReversibilityLevel.FULL,
+            undo_window="5m",  # 5-minute fraud detection window
+            sla_latency="1000ms"
+        ),
+        privacy_contract=PrivacyContract(
+            retention=RetentionPolicy.EPHEMERAL,  # Data not retained
+            storage_location="us-east-1",
+            human_review=False,
+            encryption_at_rest=True,
+            encryption_in_transit=True
+        )
+    )
+    
+    # Calculate and display trust score
+    trust_score = manifest.calculate_trust_score()
+    
+    print("=" * 60)
+    print("IATP Sidecar: Secure Bank Agent")
+    print("=" * 60)
+    print(f"Agent ID: {manifest.agent_id}")
+    print(f"Trust Level: {manifest.trust_level}")
+    print(f"Trust Score: {trust_score}/10")
+    print(f"Reversibility: {manifest.capabilities.reversibility} ({manifest.capabilities.undo_window})")
+    print(f"Data Retention: {manifest.privacy_contract.retention}")
+    print("")
+    print("✓ This agent has strong security guarantees")
+    print("✓ Requests will be processed immediately")
+    print("✓ No warnings or blocks expected")
+    print("")
+    print("Backend Agent: http://localhost:8000")
+    print("Sidecar: http://localhost:8001")
+    print("")
+    print("Test with:")
+    print("  curl -X POST http://localhost:8001/proxy \\")
+    print("    -H 'Content-Type: application/json' \\")
+    print("    -d '{\"task\":\"transfer\",\"data\":{\"amount\":100,\"from_account\":\"123\",\"to_account\":\"456\"}}'")
+    print("")
+    
+    # Create and run the sidecar
+    sidecar = create_sidecar(
+        agent_url="http://localhost:8000",
+        manifest=manifest,
+        host="0.0.0.0",
+        port=8001
+    )
+    
+    sidecar.run()
+
+
+if __name__ == "__main__":
+    main()

modules/iatp/examples/run_sidecar.py

@@ -0,0 +1,105 @@
+"""
+Example: Running the IATP Sidecar
+
+This example shows how to set up and run a sidecar for your agent.
+"""
+import sys
+import os
+
+# Add SDK to path
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'sdk', 'python'))
+
+from iatp import (
+    create_sidecar,
+    CapabilityManifest,
+    AgentCapabilities,
+    PrivacyContract,
+    TrustLevel,
+    ReversibilityLevel,
+    RetentionPolicy,
+)
+
+
+def create_trusted_manifest():
+    """Create a capability manifest for a trusted agent."""
+    return CapabilityManifest(
+        agent_id="example-booking-agent-v1",
+        agent_version="1.0.0",
+        trust_level=TrustLevel.VERIFIED_PARTNER,
+        capabilities=AgentCapabilities(
+            idempotency=True,
+            reversibility=ReversibilityLevel.PARTIAL,
+            undo_window="24h",
+            sla_latency="2000ms",
+            rate_limit=100
+        ),
+        privacy_contract=PrivacyContract(
+            retention=RetentionPolicy.EPHEMERAL,
+            storage_location="us-west",
+            human_review=False,
+            encryption_at_rest=True,
+            encryption_in_transit=True
+        )
+    )
+
+
+def create_untrusted_manifest():
+    """Create a capability manifest for an untrusted/sketchy agent."""
+    return CapabilityManifest(
+        agent_id="sketchy-cheap-agent-v1",
+        agent_version="0.1.0",
+        trust_level=TrustLevel.UNTRUSTED,
+        capabilities=AgentCapabilities(
+            idempotency=False,
+            reversibility=ReversibilityLevel.NONE,
+            undo_window=None,
+            sla_latency=None,
+            rate_limit=10
+        ),
+        privacy_contract=PrivacyContract(
+            retention=RetentionPolicy.FOREVER,
+            storage_location="unknown",
+            human_review=True,
+            encryption_at_rest=False,
+            encryption_in_transit=True
+        )
+    )
+
+
+def main():
+    """
+    Run the sidecar.
+    
+    Make sure your backend agent is running on port 8000 first!
+    Run: python examples/backend_agent.py
+    """
+    # Choose which manifest to use
+    manifest = create_trusted_manifest()
+    # manifest = create_untrusted_manifest()  # Uncomment to test with untrusted agent
+    
+    print(f"🚀 Starting IATP Sidecar for: {manifest.agent_id}")
+    print(f"   Trust Score: {manifest.calculate_trust_score()}/10")
+    print(f"   Backend Agent: http://localhost:8000")
+    print(f"   Sidecar Port: http://localhost:8001")
+    print(f"\nEndpoints:")
+    print(f"   • Manifest: GET http://localhost:8001/.well-known/agent-manifest")
+    print(f"   • Proxy: POST http://localhost:8001/proxy")
+    print(f"   • Health: GET http://localhost:8001/health")
+    print(f"\nTry it:")
+    print(f"   curl -X POST http://localhost:8001/proxy \\")
+    print(f"        -H 'Content-Type: application/json' \\")
+    print(f"        -d '{{\"task\": \"book_flight\", \"data\": {{\"destination\": \"NYC\"}}}}'")
+    
+    # Create and run the sidecar
+    sidecar = create_sidecar(
+        agent_url="http://localhost:8000",
+        manifest=manifest,
+        host="0.0.0.0",
+        port=8001
+    )
+    
+    sidecar.run()
+
+
+if __name__ == "__main__":
+    main()

modules/iatp/examples/run_untrusted_sidecar.py

@@ -0,0 +1,77 @@
+"""
+Example: Running an UNTRUSTED agent with the IATP Sidecar
+
+This demonstrates the warning and override mechanism.
+"""
+import sys
+import os
+
+# Add SDK to path
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', 'sdk', 'python'))
+
+from iatp import (
+    create_sidecar,
+    CapabilityManifest,
+    AgentCapabilities,
+    PrivacyContract,
+    TrustLevel,
+    ReversibilityLevel,
+    RetentionPolicy,
+)
+
+
+def main():
+    """
+    Run the sidecar with an UNTRUSTED manifest.
+    This simulates a "sketchy" agent with poor security practices.
+    """
+    manifest = CapabilityManifest(
+        agent_id="sketchy-cheap-agent-v1",
+        agent_version="0.1.0",
+        trust_level=TrustLevel.UNTRUSTED,
+        capabilities=AgentCapabilities(
+            idempotency=False,
+            reversibility=ReversibilityLevel.NONE,
+            undo_window=None,
+            sla_latency=None,
+            rate_limit=10
+        ),
+        privacy_contract=PrivacyContract(
+            retention=RetentionPolicy.FOREVER,
+            storage_location="unknown",
+            human_review=True,
+            encryption_at_rest=False,
+            encryption_in_transit=True
+        )
+    )
+    
+    print(f"🚨 Starting IATP Sidecar for UNTRUSTED agent: {manifest.agent_id}")
+    print(f"   Trust Score: {manifest.calculate_trust_score()}/10 (LOW)")
+    print(f"   Backend Agent: http://localhost:8000")
+    print(f"   Sidecar Port: http://localhost:8002")
+    print(f"\n⚠️  WARNING: This agent has poor security characteristics:")
+    print(f"   • No idempotency guarantee")
+    print(f"   • No transaction reversibility")
+    print(f"   • Stores data FOREVER")
+    print(f"   • Humans may review your data")
+    print(f"   • No encryption at rest")
+    print(f"\nEndpoints:")
+    print(f"   • Manifest: GET http://localhost:8002/.well-known/agent-manifest")
+    print(f"   • Proxy: POST http://localhost:8002/proxy")
+    print(f"   • Health: GET http://localhost:8002/health")
+    print(f"\nTry it:")
+    print(f"   python examples/test_untrusted.py")
+    
+    # Create and run the sidecar on port 8002 (different from trusted agent)
+    sidecar = create_sidecar(
+        agent_url="http://localhost:8000",
+        manifest=manifest,
+        host="0.0.0.0",
+        port=8002
+    )
+    
+    sidecar.run()
+
+
+if __name__ == "__main__":
+    main()