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

modules/control-plane/examples/observability_demo.py

@@ -0,0 +1,370 @@
+"""
+Observability and Monitoring Examples
+
+This demonstrates production observability with Prometheus metrics,
+alerting, distributed tracing, and dashboards.
+"""
+
+from agent_control_plane import (
+    PrometheusExporter,
+    AlertManager,
+    TraceCollector,
+    ObservabilityDashboard,
+    MetricType,
+    AlertSeverity,
+    create_observability_suite
+)
+import time
+
+
+def example_prometheus_metrics():
+    """Example: Exporting Prometheus metrics"""
+    print("=== Prometheus Metrics Example ===\n")
+    
+    exporter = PrometheusExporter()
+    
+    # Record various metrics
+    exporter.increment_counter(
+        "agent_requests_total",
+        value=1,
+        labels={"agent_id": "agent1", "status": "success"},
+        help_text="Total number of agent requests"
+    )
+    
+    exporter.increment_counter(
+        "agent_requests_total",
+        value=1,
+        labels={"agent_id": "agent1", "status": "blocked"}
+    )
+    
+    exporter.set_gauge(
+        "agent_active_sessions",
+        value=5,
+        labels={"agent_id": "agent1"},
+        help_text="Number of active agent sessions"
+    )
+    
+    exporter.observe_histogram(
+        "agent_request_duration_seconds",
+        value=0.245,
+        labels={"agent_id": "agent1"},
+        help_text="Agent request duration"
+    )
+    
+    # Export in Prometheus format
+    print("Prometheus Metrics Export:")
+    print("-" * 50)
+    print(exporter.export())
+    print("-" * 50)
+    print()
+
+
+def example_alerting():
+    """Example: Rule-based alerting"""
+    print("=== Alerting Example ===\n")
+    
+    alert_mgr = AlertManager()
+    
+    # Define alert rules
+    alert_mgr.add_rule(
+        name="high_error_rate",
+        condition=lambda m: m.get("error_rate", 0) > 0.05,
+        severity=AlertSeverity.ERROR,
+        message="Error rate exceeds 5%",
+        labels={"team": "platform"}
+    )
+    
+    alert_mgr.add_rule(
+        name="high_latency",
+        condition=lambda m: m.get("avg_latency_ms", 0) > 1000,
+        severity=AlertSeverity.WARNING,
+        message="Average latency exceeds 1000ms"
+    )
+    
+    alert_mgr.add_rule(
+        name="system_overload",
+        condition=lambda m: m.get("cpu_usage", 0) > 0.9,
+        severity=AlertSeverity.CRITICAL,
+        message="CPU usage above 90%"
+    )
+    
+    # Simulate metrics
+    test_scenarios = [
+        {"name": "Normal", "error_rate": 0.02, "avg_latency_ms": 500, "cpu_usage": 0.6},
+        {"name": "High Errors", "error_rate": 0.10, "avg_latency_ms": 600, "cpu_usage": 0.65},
+        {"name": "Critical", "error_rate": 0.15, "avg_latency_ms": 1500, "cpu_usage": 0.95}
+    ]
+    
+    for scenario in test_scenarios:
+        print(f"Scenario: {scenario['name']}")
+        print(f"  Metrics: error_rate={scenario['error_rate']:.2f}, "
+              f"latency={scenario['avg_latency_ms']}ms, cpu={scenario['cpu_usage']:.2f}")
+        
+        alerts = alert_mgr.evaluate(scenario)
+        
+        if alerts:
+            print(f"  🚨 {len(alerts)} alert(s) firing:")
+            for alert in alerts:
+                severity_icon = {
+                    AlertSeverity.INFO: "ℹ️",
+                    AlertSeverity.WARNING: "⚠️",
+                    AlertSeverity.ERROR: "❌",
+                    AlertSeverity.CRITICAL: "🔥"
+                }
+                print(f"     {severity_icon[alert.severity]} [{alert.severity.value}] {alert.message}")
+        else:
+            print(f"  ✅ No alerts")
+        print()
+
+
+def example_distributed_tracing():
+    """Example: Distributed tracing"""
+    print("=== Distributed Tracing Example ===\n")
+    
+    collector = TraceCollector()
+    
+    # Start a trace for a request
+    trace_id = collector.start_trace(
+        "agent_request",
+        metadata={"user_id": "user123", "request_type": "tool_execution"}
+    )
+    
+    print(f"Started trace: {trace_id}")
+    
+    # Simulate nested operations
+    policy_span = collector.start_span(
+        trace_id=trace_id,
+        operation_name="policy_check",
+        tags={"policy": "rate_limit"}
+    )
+    time.sleep(0.01)
+    collector.end_span(trace_id, policy_span, tags={"result": "allowed"})
+    
+    execution_span = collector.start_span(
+        trace_id=trace_id,
+        operation_name="tool_execution",
+        tags={"tool": "read_file"}
+    )
+    
+    # Nested span
+    validation_span = collector.start_span(
+        trace_id=trace_id,
+        operation_name="validate_input",
+        parent_span_id=execution_span,
+        tags={"validation_type": "schema"}
+    )
+    time.sleep(0.005)
+    collector.end_span(trace_id, validation_span)
+    
+    time.sleep(0.015)
+    collector.end_span(trace_id, execution_span, tags={"status": "success"})
+    
+    # End trace
+    collector.end_trace(trace_id)
+    
+    # Get trace details
+    trace = collector.get_trace(trace_id)
+    print(f"\nTrace Details:")
+    print(f"  Duration: {trace.duration_ms:.2f}ms")
+    print(f"  Spans: {len(trace.spans)}")
+    for span in trace.spans:
+        indent = "    " if span.parent_span_id else "  "
+        print(f"{indent}- {span.operation_name}: {span.duration_ms:.2f}ms")
+    print()
+    
+    # Get visualization data
+    viz = collector.get_trace_visualization(trace_id)
+    print("Trace Visualization Data:")
+    print(f"  Span tree depth: {len(viz['span_tree'])}")
+    print()
+
+
+def example_observability_dashboard():
+    """Example: Observability dashboard"""
+    print("=== Observability Dashboard Example ===\n")
+    
+    # Create components
+    prometheus = PrometheusExporter()
+    alert_mgr = AlertManager()
+    trace_collector = TraceCollector()
+    dashboard = ObservabilityDashboard(prometheus, alert_mgr, trace_collector)
+    
+    # Add some data
+    prometheus.increment_counter("requests", value=100)
+    prometheus.set_gauge("active_users", value=42)
+    
+    alert_mgr.add_rule(
+        "test_alert",
+        lambda m: False,
+        AlertSeverity.INFO,
+        "Test"
+    )
+    
+    trace_collector.start_trace("sample_operation")
+    
+    # Get dashboard data
+    data = dashboard.get_dashboard_data()
+    
+    print("Dashboard Overview:")
+    print(f"  Timestamp: {data['timestamp']}")
+    print(f"  Metrics: {len(data['metrics'])} metric types")
+    print(f"  Active Alerts: {data['alerts']['active_count']}")
+    print(f"  Recent Traces: {data['traces']['recent_count']}")
+    print()
+    
+    # Get health status
+    health = dashboard.get_health_status()
+    
+    status_icon = {
+        "healthy": "🟢",
+        "warning": "🟡",
+        "degraded": "🟠",
+        "critical": "🔴"
+    }
+    
+    print(f"System Health: {status_icon.get(health['status'], '⚪')} {health['status']}")
+    print(f"  Active Alerts: {health['active_alerts']}")
+    print(f"  Critical: {health['critical_alerts']}")
+    print(f"  Errors: {health['error_alerts']}")
+    print()
+
+
+def example_monitoring_workflow():
+    """Example: Complete monitoring workflow"""
+    print("=== Complete Monitoring Workflow ===\n")
+    
+    suite = create_observability_suite()
+    
+    prometheus = suite["prometheus"]
+    alerts = suite["alerts"]
+    traces = suite["traces"]
+    dashboard = suite["dashboard"]
+    
+    print("Simulating agent request workflow...\n")
+    
+    # Start trace
+    trace_id = traces.start_trace("agent_request")
+    
+    # Increment request counter
+    prometheus.increment_counter(
+        "agent_requests_total",
+        labels={"status": "processing"}
+    )
+    
+    # Update active sessions
+    prometheus.set_gauge("agent_active_sessions", value=3)
+    
+    # Simulate processing
+    span1 = traces.start_span(trace_id, "authentication")
+    time.sleep(0.005)
+    traces.end_span(trace_id, span1)
+    
+    span2 = traces.start_span(trace_id, "policy_check")
+    time.sleep(0.008)
+    traces.end_span(trace_id, span2)
+    
+    span3 = traces.start_span(trace_id, "execution")
+    time.sleep(0.012)
+    traces.end_span(trace_id, span3)
+    
+    # End trace
+    traces.end_trace(trace_id)
+    
+    # Record duration
+    trace = traces.get_trace(trace_id)
+    prometheus.observe_histogram(
+        "agent_request_duration_ms",
+        value=trace.duration_ms
+    )
+    
+    # Update counter
+    prometheus.increment_counter(
+        "agent_requests_total",
+        labels={"status": "success"}
+    )
+    
+    # Check alerts
+    current_metrics = {
+        "error_rate": 0.01,
+        "avg_latency_ms": trace.duration_ms
+    }
+    
+    alerts.add_rule(
+        "high_latency",
+        lambda m: m.get("avg_latency_ms", 0) > 50,
+        AlertSeverity.WARNING,
+        "High latency detected"
+    )
+    
+    firing_alerts = alerts.evaluate(current_metrics)
+    
+    # Display results
+    print("Workflow Results:")
+    print(f"  ✅ Request processed")
+    print(f"  ⏱️  Duration: {trace.duration_ms:.2f}ms")
+    print(f"  📊 Metrics recorded: 3")
+    print(f"  🔍 Spans traced: {len(trace.spans)}")
+    print(f"  🚨 Alerts: {len(firing_alerts)}")
+    
+    if firing_alerts:
+        for alert in firing_alerts:
+            print(f"     - {alert.message}")
+    
+    print()
+    
+    # Get dashboard summary
+    health = dashboard.get_health_status()
+    print(f"System Health: {health['status']}")
+    print()
+
+
+def example_metrics_export_endpoint():
+    """Example: Metrics export endpoint (for Prometheus scraping)"""
+    print("=== Metrics Export Endpoint ===\n")
+    
+    exporter = PrometheusExporter()
+    
+    # Simulate real metrics
+    exporter.increment_counter("http_requests_total", value=1250, 
+                              labels={"method": "POST", "endpoint": "/api/agent"})
+    exporter.increment_counter("http_requests_total", value=3200,
+                              labels={"method": "GET", "endpoint": "/api/agent"})
+    
+    exporter.set_gauge("http_requests_in_flight", value=12)
+    exporter.observe_histogram("http_request_duration_seconds", value=0.123)
+    
+    print("Metrics endpoint output (for Prometheus scraping):")
+    print("=" * 60)
+    export = exporter.export()
+    print(export)
+    print("=" * 60)
+    print()
+    print("Configuration for Prometheus:")
+    print("  scrape_configs:")
+    print("    - job_name: 'agent-control-plane'")
+    print("      static_configs:")
+    print("        - targets: ['localhost:9090']")
+    print()
+
+
+if __name__ == "__main__":
+    print("Agent Control Plane - Observability & Monitoring Examples")
+    print("=" * 70)
+    print()
+    
+    example_prometheus_metrics()
+    print("\n" + "=" * 70 + "\n")
+    
+    example_alerting()
+    print("\n" + "=" * 70 + "\n")
+    
+    example_distributed_tracing()
+    print("\n" + "=" * 70 + "\n")
+    
+    example_observability_dashboard()
+    print("\n" + "=" * 70 + "\n")
+    
+    example_monitoring_workflow()
+    print("\n" + "=" * 70 + "\n")
+    
+    example_metrics_export_endpoint()

modules/control-plane/examples/use_cases.py

@@ -0,0 +1,336 @@
+"""
+Real-World Use Cases for Agent Control Plane
+
+This example demonstrates practical, production-ready scenarios.
+"""
+
+from datetime import time, datetime
+from agent_control_plane import AgentControlPlane, create_standard_agent
+from agent_control_plane.agent_kernel import ActionType, PermissionLevel
+from agent_control_plane.policy_engine import ResourceQuota
+from agent_control_plane.shadow_mode import ShadowModeConfig
+from agent_control_plane.constraint_graphs import (
+    DataGraph, TemporalGraph, GraphNode, GraphNodeType
+)
+
+
+def use_case_1_data_analysis_pipeline():
+    """
+    Use Case 1: Data Analysis Pipeline
+    
+    An AI agent that analyzes customer data but must:
+    - Only read from approved data sources
+    - Never write to production databases
+    - Respect PII restrictions
+    - Stay within rate limits
+    """
+    print("=" * 70)
+    print("USE CASE 1: Data Analysis Pipeline")
+    print("=" * 70)
+    print()
+    
+    control_plane = AgentControlPlane()
+    
+    # Create a data analyst agent with restricted permissions
+    permissions = {
+        ActionType.FILE_READ: PermissionLevel.READ_ONLY,
+        ActionType.DATABASE_QUERY: PermissionLevel.READ_ONLY,
+        ActionType.API_CALL: PermissionLevel.READ_ONLY,
+    }
+    
+    agent = control_plane.create_agent("data-analyst", permissions)
+    
+    # Set conservative rate limits
+    quota = ResourceQuota(
+        agent_id="data-analyst",
+        max_requests_per_minute=30,
+        max_requests_per_hour=500
+    )
+    control_plane.policy_engine.set_quota("data-analyst", quota)
+    
+    # Set up data graph for allowed data sources
+    data_graph = DataGraph()
+    data_graph.add_node(GraphNode(
+        id="customer_analytics",
+        node_type=GraphNodeType.TABLE,
+        metadata={"database": "analytics", "table": "customer_summary"}
+    ))
+    data_graph.add_node(GraphNode(
+        id="sales_reports",
+        node_type=GraphNodeType.FILE,
+        metadata={"path": "/data/reports/sales/"}
+    ))
+    
+    control_plane.set_data_graph("data-analyst", data_graph)
+    
+    print("✓ Data analyst agent configured")
+    print("  - Read-only access to approved data sources")
+    print("  - Rate limited to 30 req/min")
+    print("  - Cannot modify any data")
+    print()
+    
+    # Simulate analysis workflow
+    print("Executing analysis workflow...")
+    
+    # Step 1: Read customer data
+    result1 = control_plane.execute_action(
+        agent,
+        ActionType.DATABASE_QUERY,
+        {"query": "SELECT customer_segment, AVG(purchase_value) FROM customer_summary GROUP BY customer_segment"}
+    )
+    print(f"  1. Query customer segments: {result1['success']}")
+    
+    # Step 2: Read sales report
+    result2 = control_plane.execute_action(
+        agent,
+        ActionType.FILE_READ,
+        {"path": "/data/reports/sales/monthly.csv"}
+    )
+    print(f"  2. Read sales report: {result2['success']}")
+    
+    # Step 3: Try to write (should be denied)
+    result3 = control_plane.execute_action(
+        agent,
+        ActionType.FILE_WRITE,
+        {"path": "/data/reports/output.csv", "content": "analysis results"}
+    )
+    print(f"  3. Attempt to write output: {result3['success']} (correctly denied)")
+    
+    print()
+    print("✓ Analysis pipeline completed safely")
+    print()
+
+
+def use_case_2_content_moderation():
+    """
+    Use Case 2: Content Moderation Agent
+    
+    An AI agent that moderates user-generated content:
+    - Can read content submissions
+    - Can flag content for review
+    - Cannot delete content directly
+    - Must operate within business hours
+    """
+    print("=" * 70)
+    print("USE CASE 2: Content Moderation Agent")
+    print("=" * 70)
+    print()
+    
+    control_plane = AgentControlPlane()
+    
+    # Create moderation agent
+    permissions = {
+        ActionType.FILE_READ: PermissionLevel.READ_ONLY,
+        ActionType.DATABASE_QUERY: PermissionLevel.READ_ONLY,
+        ActionType.API_CALL: PermissionLevel.READ_WRITE,  # Can call moderation API
+    }
+    
+    agent = control_plane.create_agent("content-moderator", permissions)
+    
+    # Set temporal constraints - only operate during business hours
+    temporal_graph = TemporalGraph()
+    temporal_graph.set_business_hours(
+        time(9, 0),   # 9 AM
+        time(17, 0)   # 5 PM
+    )
+    
+    control_plane.set_temporal_graph("content-moderator", temporal_graph)
+    
+    print("✓ Content moderation agent configured")
+    print("  - Can read and analyze content")
+    print("  - Can flag for human review")
+    print("  - Cannot delete content")
+    print("  - Only operates 9 AM - 5 PM")
+    print()
+    
+    print("Moderating content submissions...")
+    
+    # Analyze content
+    result1 = control_plane.execute_action(
+        agent,
+        ActionType.FILE_READ,
+        {"path": "/content/submissions/post_12345.json"}
+    )
+    print(f"  1. Read submission: {result1['success']}")
+    
+    # Flag for review via API
+    result2 = control_plane.execute_action(
+        agent,
+        ActionType.API_CALL,
+        {
+            "url": "https://api.example.com/content/flag",
+            "method": "POST",
+            "data": {"post_id": "12345", "reason": "possible_violation"}
+        }
+    )
+    print(f"  2. Flag for review: {result2['success']}")
+    
+    print()
+    print("✓ Content moderation completed")
+    print()
+
+
+def use_case_3_testing_in_shadow_mode():
+    """
+    Use Case 3: Testing New Agent in Shadow Mode
+    
+    Test a new autonomous agent in shadow mode before production:
+    - Agent thinks it's executing real actions
+    - Control plane intercepts everything
+    - Validate behavior without side effects
+    - Analyze decision patterns
+    """
+    print("=" * 70)
+    print("USE CASE 3: Testing in Shadow Mode")
+    print("=" * 70)
+    print()
+    
+    control_plane = AgentControlPlane()
+    
+    # Create experimental agent
+    agent = create_standard_agent(control_plane, "experimental-agent")
+    
+    # Enable shadow mode for safe testing
+    shadow_config = ShadowModeConfig(
+        enabled=True,
+        log_reasoning=True
+    )
+    control_plane.enable_shadow_mode("experimental-agent", shadow_config)
+    
+    print("✓ Experimental agent in shadow mode")
+    print("  - All actions are simulated")
+    print("  - No real side effects")
+    print("  - Full reasoning telemetry")
+    print()
+    
+    print("Testing agent behavior in shadow mode...")
+    
+    # Execute various actions (all simulated)
+    actions = [
+        (ActionType.FILE_READ, {"path": "/data/config.json"}),
+        (ActionType.API_CALL, {"url": "https://api.example.com/data"}),
+        (ActionType.DATABASE_QUERY, {"query": "SELECT * FROM users LIMIT 10"}),
+        (ActionType.FILE_WRITE, {"path": "/tmp/output.txt", "content": "test"}),
+    ]
+    
+    for i, (action_type, params) in enumerate(actions, 1):
+        result = control_plane.execute_action(agent, action_type, params)
+        print(f"  {i}. {action_type.value}: Simulated (would have {'succeeded' if result['success'] else 'failed'})")
+    
+    print()
+    
+    # Get shadow mode statistics
+    shadow_logs = control_plane.get_shadow_mode_log("experimental-agent")
+    print(f"✓ Shadow mode test complete")
+    print(f"  - {len(shadow_logs)} actions simulated")
+    print(f"  - No real side effects occurred")
+    print(f"  - Ready to analyze agent behavior")
+    print()
+
+
+def use_case_4_multi_tenant_saas():
+    """
+    Use Case 4: Multi-Tenant SaaS Application
+    
+    Multiple customer tenants, each with their own agent:
+    - Isolated permissions per tenant
+    - Individual rate limits
+    - Tenant-specific data access
+    - Cost tracking per tenant
+    """
+    print("=" * 70)
+    print("USE CASE 4: Multi-Tenant SaaS Application")
+    print("=" * 70)
+    print()
+    
+    control_plane = AgentControlPlane()
+    
+    # Create agents for different tenants
+    tenants = ["acme-corp", "globex-inc", "initech-llc"]
+    
+    for tenant in tenants:
+        # Each tenant gets their own agent
+        agent = create_standard_agent(control_plane, f"{tenant}-agent")
+        
+        # Tenant-specific quotas (different tiers)
+        if tenant == "acme-corp":
+            # Premium tier
+            quota = ResourceQuota(
+                agent_id=f"{tenant}-agent",
+                max_requests_per_minute=100,
+                max_requests_per_hour=5000
+            )
+        else:
+            # Standard tier
+            quota = ResourceQuota(
+                agent_id=f"{tenant}-agent",
+                max_requests_per_minute=30,
+                max_requests_per_hour=1000
+            )
+        
+        control_plane.policy_engine.set_quota(f"{tenant}-agent", quota)
+        
+        # Tenant-specific data isolation
+        data_graph = DataGraph()
+        data_graph.add_node(GraphNode(
+            id=f"{tenant}_data",
+            node_type=GraphNodeType.DIRECTORY,
+            metadata={"path": f"/data/tenants/{tenant}/"}
+        ))
+        control_plane.set_data_graph(f"{tenant}-agent", data_graph)
+    
+    print("✓ Multi-tenant environment configured")
+    print(f"  - {len(tenants)} tenant agents created")
+    print("  - Each with isolated data access")
+    print("  - Individual rate limits per tier")
+    print()
+    
+    # Simulate tenant activity
+    for tenant in tenants:
+        agent = control_plane.kernel.get_agent_context(f"{tenant}-agent")
+        if agent:
+            result = control_plane.execute_action(
+                agent,
+                ActionType.FILE_READ,
+                {"path": f"/data/tenants/{tenant}/config.json"}
+            )
+            quota_status = control_plane.policy_engine.get_quota_status(f"{tenant}-agent")
+            print(f"  {tenant}: Action {'succeeded' if result['success'] else 'failed'}, "
+                  f"{quota_status['requests_this_minute']}/{quota_status['max_requests_per_minute']} requests")
+    
+    print()
+    print("✓ Multi-tenant operations completed")
+    print()
+
+
+def main():
+    """Run all use case examples"""
+    print()
+    print("=" * 70)
+    print("AGENT CONTROL PLANE - REAL-WORLD USE CASES")
+    print("=" * 70)
+    print()
+    
+    use_case_1_data_analysis_pipeline()
+    input("Press Enter for next use case...")
+    print()
+    
+    use_case_2_content_moderation()
+    input("Press Enter for next use case...")
+    print()
+    
+    use_case_3_testing_in_shadow_mode()
+    input("Press Enter for next use case...")
+    print()
+    
+    use_case_4_multi_tenant_saas()
+    
+    print()
+    print("=" * 70)
+    print("ALL USE CASES COMPLETED")
+    print("=" * 70)
+    print()
+
+
+if __name__ == "__main__":
+    main()