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

modules/caas/examples/demos/demo_time_decay.py

@@ -0,0 +1,247 @@
+"""
+Demonstration of the Time-Based Decay Function
+
+"The Half-Life of Truth" - Mathematical gravity that pulls old data down.
+
+This demo shows how the decay function prioritizes recent documents over old ones,
+even when the old documents have higher similarity scores.
+"""
+
+import uuid
+from datetime import datetime, timedelta
+from caas.models import Document, ContentFormat, DocumentType, Section
+from caas.storage import DocumentStore, ContextExtractor
+from caas.decay import calculate_decay_factor
+
+
+def demo_decay_principle():
+    """Demonstrate the core decay principle."""
+    print("\n" + "="*70)
+    print("THE HALF-LIFE OF TRUTH - Time-Based Decay Demonstration")
+    print("="*70)
+    
+    print("\n📅 Core Principle:")
+    print("   'Recency is Relevance' - We don't cut off old data, we apply gravity.")
+    print("   Formula: Score = Similarity × (1 / (1 + time_elapsed))")
+    
+    print("\n🎯 The Challenge:")
+    print("   In a living system like software documentation, the truth moves:")
+    print("   - 'How to reset the server' in 2021 ≠ 2025")
+    print("   - If AI retrieves the 2021 answer (better word match), it fails")
+    print("   - We need to prioritize 'What happened latest' over 'What matched best'")
+    
+    print("\n" + "-"*70)
+    print("EXAMPLE: Yesterday's 80% Match vs Last Year's 95% Match")
+    print("-"*70)
+    
+    # Calculate decay factors
+    ref_time = datetime.utcnow()
+    
+    # Recent document (yesterday)
+    recent_time = (ref_time - timedelta(days=1)).isoformat()
+    recent_decay = calculate_decay_factor(recent_time, ref_time, decay_rate=1.0)
+    recent_similarity = 0.80
+    recent_score = recent_similarity * recent_decay
+    
+    # Old document (last year)
+    old_time = (ref_time - timedelta(days=365)).isoformat()
+    old_decay = calculate_decay_factor(old_time, ref_time, decay_rate=1.0)
+    old_similarity = 0.95
+    old_score = old_similarity * old_decay
+    
+    print(f"\n📄 Recent Document (Yesterday):")
+    print(f"   Base Similarity:  {recent_similarity:.1%}")
+    print(f"   Decay Factor:     {recent_decay:.3f}")
+    print(f"   Final Score:      {recent_score:.3f}")
+    
+    print(f"\n📄 Old Document (Last Year):")
+    print(f"   Base Similarity:  {old_similarity:.1%}")
+    print(f"   Decay Factor:     {old_decay:.3f}")
+    print(f"   Final Score:      {old_score:.3f}")
+    
+    print(f"\n{'='*70}")
+    if recent_score > old_score:
+        print("✅ WINNER: Recent Document!")
+        print(f"   {recent_score:.3f} > {old_score:.3f}")
+        print("   Even with lower similarity, the recent document wins!")
+    else:
+        print("❌ Old Document won (this shouldn't happen)")
+    
+    print("="*70)
+
+
+def demo_search_with_decay():
+    """Demonstrate search with time-based decay."""
+    print("\n" + "="*70)
+    print("SEARCH DEMONSTRATION - Time Decay in Action")
+    print("="*70)
+    
+    store = DocumentStore()
+    current_time = datetime.utcnow()
+    
+    # Create documents about "server reset" from different time periods
+    documents = [
+        {
+            "title": "Server Reset Guide 2026 (Latest)",
+            "content": "Modern server reset using cloud-native tools. Reset the server with kubectl.",
+            "age_days": 1,
+            "description": "Yesterday"
+        },
+        {
+            "title": "Server Reset Guide 2024",
+            "content": "Server reset procedures updated for Docker. How to reset the server container.",
+            "age_days": 365,
+            "description": "1 year ago"
+        },
+        {
+            "title": "Server Reset Guide 2021 (Legacy)",
+            "content": "Legacy server reset using manual processes. Server reset steps. Old reset method.",
+            "age_days": 365 * 3,
+            "description": "3 years ago"
+        }
+    ]
+    
+    print("\n📚 Document Corpus:")
+    for doc_info in documents:
+        doc = Document(
+            id=str(uuid.uuid4()),
+            title=doc_info["title"],
+            content=doc_info["content"],
+            format=ContentFormat.TEXT,
+            detected_type=DocumentType.TECHNICAL_DOCUMENTATION,
+            sections=[
+                Section(
+                    title="Introduction",
+                    content=doc_info["content"],
+                    weight=1.0
+                )
+            ],
+            ingestion_timestamp=(current_time - timedelta(days=doc_info["age_days"])).isoformat()
+        )
+        store.add(doc)
+        print(f"   • {doc_info['title']} ({doc_info['description']})")
+    
+    # Search without decay
+    print("\n" + "-"*70)
+    print("🔍 Search Results: 'server reset' (WITHOUT time decay)")
+    print("-"*70)
+    results_no_decay = store.search("server reset", enable_time_decay=False)
+    for i, doc in enumerate(results_no_decay, 1):
+        score = doc.metadata.get('_search_score', 0)
+        print(f"{i}. {doc.title}")
+        print(f"   Score: {score:.3f}")
+    
+    # Search with decay
+    print("\n" + "-"*70)
+    print("🔍 Search Results: 'server reset' (WITH time decay)")
+    print("-"*70)
+    results_with_decay = store.search("server reset", enable_time_decay=True)
+    for i, doc in enumerate(results_with_decay, 1):
+        score = doc.metadata.get('_search_score', 0)
+        decay = doc.metadata.get('_decay_factor', 1.0)
+        age_days = (current_time - datetime.fromisoformat(doc.ingestion_timestamp)).days
+        print(f"{i}. {doc.title}")
+        print(f"   Score: {score:.3f} | Decay: {decay:.3f} | Age: {age_days} days")
+    
+    print("\n✅ Notice: With time decay enabled, the most recent document ranks first,")
+    print("   even though older documents may have more keyword matches!")
+
+
+def demo_context_extraction():
+    """Demonstrate context extraction with time decay."""
+    print("\n" + "="*70)
+    print("CONTEXT EXTRACTION - Time-Weighted Relevance")
+    print("="*70)
+    
+    store = DocumentStore()
+    current_time = datetime.utcnow()
+    
+    # Create a semi-recent document
+    doc = Document(
+        id=str(uuid.uuid4()),
+        title="Authentication API Guide",
+        content="Complete guide to authentication endpoints.",
+        format=ContentFormat.HTML,
+        detected_type=DocumentType.API_DOCUMENTATION,
+        sections=[
+            Section(
+                title="JWT Authentication",
+                content="Use JWT tokens for secure authentication. Token expires in 24 hours.",
+                weight=2.0,
+                importance_score=0.9
+            ),
+            Section(
+                title="OAuth2 Flow",
+                content="OAuth2 authorization flow with PKCE. Recommended for web apps.",
+                weight=1.8,
+                importance_score=0.8
+            ),
+            Section(
+                title="API Keys",
+                content="Legacy API keys for backward compatibility. Not recommended for new apps.",
+                weight=1.0,
+                importance_score=0.4
+            )
+        ],
+        ingestion_timestamp=(current_time - timedelta(days=7)).isoformat()
+    )
+    
+    store.add(doc)
+    
+    print(f"\n📄 Document: {doc.title}")
+    print(f"   Age: 7 days old")
+    print(f"   Sections: {len(doc.sections)}")
+    
+    # Extract without decay
+    print("\n" + "-"*70)
+    print("📝 Context Extraction WITHOUT time decay:")
+    print("-"*70)
+    extractor_no_decay = ContextExtractor(store, enable_time_decay=False)
+    _, metadata_no_decay = extractor_no_decay.extract_context(doc.id, "authentication")
+    
+    print(f"Decay Factor: {metadata_no_decay['decay_factor']:.3f}")
+    print("Section Weights:")
+    for section, weight in metadata_no_decay['weights_applied'].items():
+        print(f"   • {section}: {weight:.3f}")
+    
+    # Extract with decay
+    print("\n" + "-"*70)
+    print("📝 Context Extraction WITH time decay:")
+    print("-"*70)
+    extractor_with_decay = ContextExtractor(store, enable_time_decay=True)
+    _, metadata_with_decay = extractor_with_decay.extract_context(doc.id, "authentication")
+    
+    print(f"Decay Factor: {metadata_with_decay['decay_factor']:.3f}")
+    print("Section Weights (after decay):")
+    for section, weight in metadata_with_decay['weights_applied'].items():
+        print(f"   • {section}: {weight:.3f}")
+    
+    print("\n✅ Notice: Weights are reduced based on document age, ensuring")
+    print("   that fresher documents get prioritized in multi-document scenarios!")
+
+
+def main():
+    """Run all demonstrations."""
+    print("\n" + "╔" + "="*68 + "╗")
+    print("║" + " "*20 + "TIME-BASED DECAY DEMO" + " "*27 + "║")
+    print("║" + " "*15 + "'The Half-Life of Truth'" + " "*29 + "║")
+    print("╚" + "="*68 + "╝")
+    
+    demo_decay_principle()
+    demo_search_with_decay()
+    demo_context_extraction()
+    
+    print("\n" + "="*70)
+    print("🎉 DEMONSTRATION COMPLETE")
+    print("="*70)
+    print("\n💡 Key Takeaways:")
+    print("   1. Time decay applies 'mathematical gravity' to old data")
+    print("   2. Recent content beats old content, even with lower similarity")
+    print("   3. We don't delete history - it's still searchable, just deprioritized")
+    print("   4. In living systems: Recency IS Relevance")
+    print("\n   Formula: Score = Similarity × (1 / (1 + days_elapsed))")
+    print("="*70 + "\n")
+
+
+if __name__ == "__main__":
+    main()

modules/caas/examples/demos/demo_trust_gateway.py

@@ -0,0 +1,383 @@
+"""
+Demo: Trust Gateway - Enterprise-Grade Private Cloud Router
+
+This demo showcases the Trust Gateway addressing the "Middleware Gap" problem:
+
+The Problem:
+No Enterprise CISO will send proprietary data to a random middleware startup
+just to save 30% on tokens. The risk of data leakage is too high.
+
+The Solution:
+Trust Gateway - Deploy within your own infrastructure for zero data leakage.
+"""
+
+from caas.gateway import (
+    TrustGateway,
+    SecurityPolicy,
+    DeploymentMode,
+    SecurityLevel,
+    DataRetentionPolicy
+)
+
+
+def demo_basic_gateway():
+    """Demo: Basic Trust Gateway usage."""
+    print("\n" + "=" * 70)
+    print("DEMO 1: Basic Trust Gateway")
+    print("=" * 70)
+    
+    # Create a basic Trust Gateway
+    gateway = TrustGateway()
+    
+    print("\n📦 Trust Gateway deployed!")
+    print("\nDeployment Info:")
+    info = gateway.get_deployment_info()
+    print(f"  • Deployment Mode: {info['deployment_mode']}")
+    print(f"  • Security Level: {info['security_level']}")
+    print(f"  • Audit Enabled: {info['audit_enabled']}")
+    
+    print("\n✅ Trust Guarantees:")
+    for guarantee in info['trust_guarantees']:
+        print(f"  • {guarantee}")
+
+
+def demo_enterprise_deployment():
+    """Demo: Enterprise deployment with maximum security."""
+    print("\n" + "=" * 70)
+    print("DEMO 2: Enterprise Deployment (Maximum Security)")
+    print("=" * 70)
+    
+    print("\n🏢 Scenario: Financial institution deploying Trust Gateway")
+    print("   Requirements: Air-gapped, maximum security, SOC2 compliance")
+    
+    # Configure maximum security
+    retention = DataRetentionPolicy(
+        retain_requests=False,  # No retention for air-gapped
+        retention_days=0,
+        auto_delete=True,
+        encrypt_at_rest=True,
+        pii_scrubbing=True
+    )
+    
+    policy = SecurityPolicy(
+        deployment_mode=DeploymentMode.AIR_GAPPED,
+        security_level="maximum",
+        data_retention=retention,
+        require_authentication=True,
+        allowed_users=["ciso@bank.com", "admin@bank.com"],
+        data_classification_required=True,
+        encrypt_in_transit=True,
+        encrypt_at_rest=True,
+        audit_all_requests=True,
+        compliance_mode="SOC2",
+        allow_external_calls=False
+    )
+    
+    gateway = TrustGateway(security_policy=policy, audit_enabled=True)
+    
+    print("\n✅ Gateway Configured:")
+    print("  • Deployment: Air-gapped (no internet connectivity)")
+    print("  • Security: Maximum")
+    print("  • Compliance: SOC2")
+    print("  • Authentication: Required")
+    print("  • Allowed Users: ciso@bank.com, admin@bank.com")
+    print("  • Data Classification: Required")
+    print("  • Encryption: In transit & at rest")
+    print("  • External Calls: Blocked")
+    print("  • Data Retention: 0 days (immediate deletion)")
+    
+    # Test request
+    print("\n📝 Test Request:")
+    print("  Query: 'Analyze Q4 financial results'")
+    print("  User: ciso@bank.com")
+    print("  Classification: confidential")
+    
+    result = gateway.route_request(
+        query="Analyze Q4 financial results",
+        user_id="ciso@bank.com",
+        data_classification="confidential"
+    )
+    
+    print("\n✅ Request Approved:")
+    print(f"  • Status: {result['status']}")
+    print(f"  • Request ID: {result['request_id']}")
+    print(f"  • Model Tier: {result['routing_decision']['model_tier']}")
+    print(f"  • Suggested Model: {result['routing_decision']['suggested_model']}")
+    
+    print("\n🔒 Security Context:")
+    sc = result['security_context']
+    print(f"  • Deployment: {sc['deployment_mode']}")
+    print(f"  • Security Level: {sc['security_level']}")
+    print(f"  • Classification: {sc['data_classification']}")
+    print(f"  • Encrypted: {sc['encrypted']}")
+    print(f"  • Audited: {sc['audited']}")
+
+
+def demo_security_validation():
+    """Demo: Security policy validation."""
+    print("\n" + "=" * 70)
+    print("DEMO 3: Security Policy Validation")
+    print("=" * 70)
+    
+    print("\n🔐 Scenario: Strict authentication and data classification")
+    
+    policy = SecurityPolicy(
+        require_authentication=True,
+        allowed_users=["admin@company.com", "user@company.com"],
+        data_classification_required=True,
+        allowed_classifications=["public", "internal", "confidential"]
+    )
+    
+    gateway = TrustGateway(security_policy=policy)
+    
+    # Test 1: Valid request
+    print("\n✅ Test 1: Valid Request")
+    print("  User: admin@company.com (in allowed list)")
+    print("  Classification: confidential (valid)")
+    
+    validation = gateway.validate_request(
+        request_data={"query": "Test query"},
+        user_id="admin@company.com",
+        data_classification="confidential"
+    )
+    
+    print(f"  Result: {'✅ PASSED' if validation['valid'] else '❌ FAILED'}")
+    
+    # Test 2: Unauthorized user
+    print("\n❌ Test 2: Unauthorized User")
+    print("  User: hacker@external.com (not in allowed list)")
+    print("  Classification: confidential")
+    
+    validation = gateway.validate_request(
+        request_data={"query": "Test query"},
+        user_id="hacker@external.com",
+        data_classification="confidential"
+    )
+    
+    print(f"  Result: {'✅ PASSED' if validation['valid'] else '❌ BLOCKED'}")
+    if not validation['valid']:
+        print(f"  Violations: {', '.join(validation['violations'])}")
+    
+    # Test 3: Invalid classification
+    print("\n❌ Test 3: Invalid Data Classification")
+    print("  User: admin@company.com")
+    print("  Classification: top-secret (not in allowed list)")
+    
+    validation = gateway.validate_request(
+        request_data={"query": "Test query"},
+        user_id="admin@company.com",
+        data_classification="top-secret"
+    )
+    
+    print(f"  Result: {'✅ PASSED' if validation['valid'] else '❌ BLOCKED'}")
+    if not validation['valid']:
+        print(f"  Violations: {', '.join(validation['violations'])}")
+
+
+def demo_routing_decisions():
+    """Demo: Heuristic routing through Trust Gateway."""
+    print("\n" + "=" * 70)
+    print("DEMO 4: Heuristic Routing Through Trust Gateway")
+    print("=" * 70)
+    
+    print("\n⚡ Philosophy: Speed > Smarts")
+    print("   Use deterministic heuristics for 0ms routing decisions")
+    print("   No external AI calls = No data leakage")
+    
+    gateway = TrustGateway()
+    
+    test_queries = [
+        ("Hi", "Greeting → Canned response (zero cost)"),
+        ("What is Python?", "Short query → Fast model (low cost)"),
+        ("Summarize this 50-page document and compare key findings", "Complex task → Smart model (high cost)")
+    ]
+    
+    for query, description in test_queries:
+        print(f"\n📝 Query: '{query}'")
+        print(f"   Description: {description}")
+        
+        result = gateway.route_request(
+            query=query,
+            user_id="developer@company.com"
+        )
+        
+        decision = result['routing_decision']
+        print(f"   ✅ Routed to: {decision['model_tier']} tier")
+        print(f"   Model: {decision['suggested_model']}")
+        print(f"   Cost: {decision['estimated_cost']}")
+        print(f"   Reason: {decision['reason']}")
+
+
+def demo_audit_trail():
+    """Demo: Audit trail for compliance."""
+    print("\n" + "=" * 70)
+    print("DEMO 5: Audit Trail for Compliance")
+    print("=" * 70)
+    
+    print("\n📊 Scenario: GDPR compliance audit")
+    
+    policy = SecurityPolicy(compliance_mode="GDPR")
+    gateway = TrustGateway(security_policy=policy, audit_enabled=True)
+    
+    # Make several requests
+    print("\n📝 Simulating user activity...")
+    
+    requests = [
+        ("user1@company.com", "What is GDPR?", "public"),
+        ("user2@company.com", "Analyze customer data", "confidential"),
+        ("admin@company.com", "Generate compliance report", "internal")
+    ]
+    
+    for user, query, classification in requests:
+        gateway.route_request(
+            query=query,
+            user_id=user,
+            data_classification=classification
+        )
+        print(f"  • Request from {user}: '{query}'")
+    
+    # Retrieve audit logs
+    print("\n📋 Retrieving Audit Logs:")
+    logs = gateway.get_audit_logs()
+    
+    print(f"\n  Total Logs: {len(logs)}")
+    
+    # Show sample logs
+    print("\n  Sample Log Entries:")
+    for log in logs[:3]:
+        print(f"    • {log['timestamp'][:19]}: {log['event_type']}")
+        print(f"      User: {log.get('user_id', 'N/A')}")
+        print(f"      Action: {log['action']}")
+        if log.get('data_classification'):
+            print(f"      Classification: {log['data_classification']}")
+        print()
+    
+    # Filter by event type
+    routing_logs = gateway.get_audit_logs(event_type="request_routed")
+    print(f"  Routing Logs: {len(routing_logs)}")
+    
+    # Filter by user
+    user_logs = gateway.get_audit_logs(user_id="admin@company.com")
+    print(f"  Admin Activity: {len(user_logs)} events")
+    
+    print("\n✅ Complete audit trail available for compliance reporting")
+
+
+def demo_comparison():
+    """Demo: SaaS Router vs Trust Gateway comparison."""
+    print("\n" + "=" * 70)
+    print("DEMO 6: SaaS Router vs Trust Gateway")
+    print("=" * 70)
+    
+    print("\n🏢 CISO Decision Matrix:")
+    print("\n" + "-" * 70)
+    print("| Feature              | SaaS Router        | Trust Gateway      |")
+    print("-" * 70)
+    print("| Data Location        | ❌ Third-party     | ✅ Your servers    |")
+    print("| Data Security        | ⚠️  Trust required | ✅ Full control    |")
+    print("| CISO Approval        | ❌ Difficult       | ✅ Easy            |")
+    print("| Compliance           | ⚠️  Provider-based | ✅ Your controls   |")
+    print("| Audit Trail          | ⚠️  Limited        | ✅ Full visibility |")
+    print("| Cost Savings         | 30% token savings  | 30% token savings  |")
+    print("| Latency              | +500ms (external)  | 0ms (local)        |")
+    print("| Data Leakage Risk    | ⚠️  High           | ✅ Zero            |")
+    print("-" * 70)
+    
+    print("\n💡 The Trust Gateway Advantage:")
+    print("   'The winner won't be the one with the smartest routing algorithm;")
+    print("    it will be the one the Enterprise trusts with the keys to the kingdom.'")
+    
+    print("\n📊 Annual Cost Comparison:")
+    print("\n  SaaS Router (External Service):")
+    print("    • External routing service: $500/month")
+    print("    • Data egress fees: $200/month")
+    print("    • Third-party security audit: $1,000/month")
+    print("    • Risk of data breach: Priceless")
+    print("    Total: $1,700/month + breach risk")
+    
+    print("\n  Trust Gateway (Self-Hosted):")
+    print("    • Server resources: $100/month (marginal)")
+    print("    • No external service fees: $0")
+    print("    • No data egress: $0")
+    print("    • No third-party risk: $0")
+    print("    • Peace of mind: Priceless")
+    print("    Total: $100/month + full control")
+    
+    print("\n  💰 Annual Savings: $19,200 + eliminated security risk")
+
+
+def demo_deployment_options():
+    """Demo: Different deployment options."""
+    print("\n" + "=" * 70)
+    print("DEMO 7: Deployment Options")
+    print("=" * 70)
+    
+    deployments = [
+        (DeploymentMode.ON_PREM, "Financial Institution", 
+         "Maximum control, data center deployment"),
+        (DeploymentMode.PRIVATE_CLOUD, "Tech Company",
+         "Cloud-native with isolated VPC"),
+        (DeploymentMode.HYBRID, "Healthcare Provider",
+         "Local processing with cloud backup"),
+        (DeploymentMode.AIR_GAPPED, "Defense Contractor",
+         "Complete isolation, no external connectivity")
+    ]
+    
+    for mode, org_type, description in deployments:
+        print(f"\n🏢 {org_type}")
+        print(f"   Mode: {mode}")
+        print(f"   Description: {description}")
+        
+        policy = SecurityPolicy(deployment_mode=mode)
+        gateway = TrustGateway(security_policy=policy)
+        info = gateway.get_deployment_info()
+        
+        print(f"   ✅ Deployment Status: Operational")
+        print(f"   Security Level: {info['security_level']}")
+
+
+def run_all_demos():
+    """Run all Trust Gateway demos."""
+    print("\n" + "=" * 70)
+    print("TRUST GATEWAY DEMONSTRATION")
+    print("Enterprise-Grade Private Cloud Router")
+    print("=" * 70)
+    print("\nThe Middleware Gap Solution:")
+    print("'Build an On-Prem / Private Cloud Router that enterprises")
+    print(" can deploy within their own infrastructure.'")
+    
+    demos = [
+        demo_basic_gateway,
+        demo_enterprise_deployment,
+        demo_security_validation,
+        demo_routing_decisions,
+        demo_audit_trail,
+        demo_comparison,
+        demo_deployment_options
+    ]
+    
+    for demo in demos:
+        try:
+            demo()
+        except Exception as e:
+            print(f"\n❌ Demo failed: {str(e)}")
+    
+    print("\n" + "=" * 70)
+    print("DEMONSTRATION COMPLETE")
+    print("=" * 70)
+    print("\n🎉 Trust Gateway is ready for enterprise deployment!")
+    print("\nKey Takeaways:")
+    print("  1. ✅ Data never leaves your infrastructure")
+    print("  2. ✅ Zero third-party data sharing")
+    print("  3. ✅ Full audit trail for compliance")
+    print("  4. ✅ Enterprise-grade security controls")
+    print("  5. ✅ 0ms routing decisions (no external calls)")
+    print("  6. ✅ Flexible deployment (on-prem, cloud, hybrid, air-gapped)")
+    print("\n💡 Remember:")
+    print("   'The winner won't be the one with the smartest routing;")
+    print("    it will be the one the Enterprise trusts with the keys to the kingdom.'")
+    print()
+
+
+if __name__ == "__main__":
+    run_all_demos()