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

modules/scak/examples/langchain_integration_example.py

@@ -0,0 +1,339 @@
+"""
+Example: LangChain Integration with Self-Correcting Agent Kernel (SCAK).
+
+This example demonstrates how to integrate SCAK with a LangChain agent to enable:
+1. Automatic laziness detection
+2. Dynamic memory management with 3-Tier hierarchy
+3. Runtime failure handling and self-correction
+
+Requirements:
+    pip install langchain langchain-core langchain-openai scak
+"""
+
+import os
+from typing import List
+
+# LangChain imports
+try:
+    from langchain.agents import AgentExecutor, create_openai_tools_agent
+    from langchain_openai import ChatOpenAI
+    from langchain.tools import Tool
+    from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
+    LANGCHAIN_AVAILABLE = True
+except ImportError:
+    print("LangChain not available. Install with: pip install langchain langchain-core langchain-openai")
+    LANGCHAIN_AVAILABLE = False
+
+# SCAK imports
+from src.integrations.langchain_integration import (
+    SCAKMemory,
+    SCAKCallbackHandler,
+    SelfCorrectingRunnable,
+    create_scak_agent
+)
+
+
+# ============================================================================
+# Example 1: Basic Integration - Add SCAK to existing LangChain agent
+# ============================================================================
+
+def example_basic_integration():
+    """
+    Basic example: Add SCAK monitoring to an existing LangChain agent.
+    
+    This adds laziness detection without changing the agent logic.
+    """
+    if not LANGCHAIN_AVAILABLE:
+        print("Skipping example - LangChain not available")
+        return
+    
+    print("=" * 80)
+    print("EXAMPLE 1: Basic SCAK Integration")
+    print("=" * 80)
+    
+    # 1. Create standard LangChain components
+    llm = ChatOpenAI(model="gpt-4o", temperature=0)
+    
+    # Define some tools
+    def search_logs(query: str) -> str:
+        """Search application logs."""
+        # Simulate tool that sometimes returns empty
+        if "error_500" in query.lower():
+            return ""  # Empty result - might trigger laziness
+        return f"Found 5 log entries for: {query}"
+    
+    tools = [
+        Tool(
+            name="search_logs",
+            func=search_logs,
+            description="Search application logs for a query"
+        )
+    ]
+    
+    # 2. Initialize SCAK Callback Handler
+    scak_handler = SCAKCallbackHandler(agent_id="example_agent")
+    
+    # 3. Create agent with standard prompt
+    prompt = ChatPromptTemplate.from_messages([
+        ("system", "You are a helpful assistant that searches logs."),
+        ("user", "{input}"),
+        MessagesPlaceholder(variable_name="agent_scratchpad"),
+    ])
+    
+    agent = create_openai_tools_agent(llm, tools, prompt)
+    
+    # 4. Create executor with SCAK callback
+    agent_executor = AgentExecutor(
+        agent=agent,
+        tools=tools,
+        callbacks=[scak_handler],  # Add SCAK monitoring
+        verbose=True
+    )
+    
+    # 5. Run agent
+    print("\n>>> Running agent with SCAK monitoring...")
+    
+    try:
+        result = agent_executor.invoke({
+            "input": "Find logs for error_500"
+        })
+        print(f"\nResult: {result['output']}")
+    except Exception as e:
+        print(f"\nError: {e}")
+    
+    # 6. Check statistics
+    print(f"\n📊 SCAK Statistics:")
+    print(f"   Total executions: {scak_handler.total_executions}")
+    print(f"   Give-up signals detected: {scak_handler.give_up_count}")
+    print(f"   Audits triggered: {scak_handler.audit_count}")
+
+
+# ============================================================================
+# Example 2: Full Integration - SCAK Memory + Callbacks + Self-Correction
+# ============================================================================
+
+def example_full_integration():
+    """
+    Full example: Use all SCAK components for maximum reliability.
+    
+    This includes:
+    - SCAKMemory for dynamic context injection
+    - SCAKCallbackHandler for laziness detection
+    - SelfCorrectingRunnable for runtime error handling
+    """
+    if not LANGCHAIN_AVAILABLE:
+        print("Skipping example - LangChain not available")
+        return
+    
+    print("\n" + "=" * 80)
+    print("EXAMPLE 2: Full SCAK Integration")
+    print("=" * 80)
+    
+    # 1. Initialize SCAK Components
+    scak_memory = SCAKMemory()
+    scak_handler = SCAKCallbackHandler(agent_id="full_example_agent")
+    
+    # 2. Create LangChain agent with SCAK memory
+    llm = ChatOpenAI(model="gpt-4o", temperature=0)
+    
+    # Define tools
+    def search_database(query: str) -> str:
+        """Search database."""
+        if "user_123" in query:
+            return "User found: John Doe"
+        return ""  # Empty result
+    
+    def execute_query(sql: str) -> str:
+        """Execute SQL query."""
+        # Simulate occasional failure
+        if "DROP" in sql.upper():
+            raise PermissionError("DROP TABLE is not allowed")
+        return f"Query executed: {sql}"
+    
+    tools = [
+        Tool(name="search_database", func=search_database, 
+             description="Search database for records"),
+        Tool(name="execute_query", func=execute_query,
+             description="Execute SQL query")
+    ]
+    
+    # 3. Create prompt with SCAK memory placeholder
+    prompt = ChatPromptTemplate.from_messages([
+        ("system", "{system_patch}\n\nYou are a database assistant."),
+        MessagesPlaceholder(variable_name="history"),
+        ("user", "{input}"),
+        MessagesPlaceholder(variable_name="agent_scratchpad"),
+    ])
+    
+    agent = create_openai_tools_agent(llm, tools, prompt)
+    
+    # 4. Create executor
+    agent_executor = AgentExecutor(
+        agent=agent,
+        tools=tools,
+        memory=scak_memory,  # Use SCAK memory
+        callbacks=[scak_handler],  # Add SCAK monitoring
+        verbose=True
+    )
+    
+    # 5. Wrap with self-correction
+    correcting_agent = SelfCorrectingRunnable(
+        agent=agent_executor,
+        agent_id="full_example_agent"
+    )
+    
+    # 6. Test scenarios
+    test_cases = [
+        "Find user_123 in the database",
+        "Search for user_999",  # Will likely give up
+        "Execute: SELECT * FROM users",  # Should work
+        # "Execute: DROP TABLE users",  # Would trigger correction
+    ]
+    
+    print("\n>>> Running test scenarios with full SCAK integration...")
+    
+    for i, test_input in enumerate(test_cases, 1):
+        print(f"\n--- Test {i}: {test_input} ---")
+        try:
+            # Load memory variables manually for demo
+            memory_vars = scak_memory.load_memory_variables({
+                "input": test_input,
+                "tools": tools
+            })
+            
+            # Prepare input with memory
+            full_input = {
+                "input": test_input,
+                "system_patch": memory_vars["system_patch"],
+                "history": memory_vars["history"]
+            }
+            
+            result = correcting_agent.invoke(full_input)
+            print(f"✓ Result: {result.get('output', result)[:100]}")
+            
+            # Save context
+            scak_memory.save_context(
+                {"input": test_input},
+                {"output": str(result)}
+            )
+            
+        except Exception as e:
+            print(f"✗ Error: {type(e).__name__}: {e}")
+    
+    # 7. Print statistics
+    print(f"\n📊 Final Statistics:")
+    print(f"   Agent executions: {correcting_agent.execution_count}")
+    print(f"   Failures detected: {correcting_agent.failure_count}")
+    print(f"   Auto-corrections: {correcting_agent.correction_count}")
+    print(f"   Give-up signals: {scak_handler.give_up_count}")
+    print(f"   Shadow audits: {scak_handler.audit_count}")
+    print(f"   Chat history length: {len(scak_memory.chat_history)}")
+
+
+# ============================================================================
+# Example 3: Convenience Function - Quick Setup
+# ============================================================================
+
+def example_convenience_function():
+    """
+    Convenience example: Use create_scak_agent for quick setup.
+    
+    This is the easiest way to add SCAK to an existing agent.
+    """
+    if not LANGCHAIN_AVAILABLE:
+        print("Skipping example - LangChain not available")
+        return
+    
+    print("\n" + "=" * 80)
+    print("EXAMPLE 3: Quick Setup with create_scak_agent()")
+    print("=" * 80)
+    
+    # 1. Create base agent (standard LangChain)
+    llm = ChatOpenAI(model="gpt-4o", temperature=0)
+    
+    def analyze_logs(query: str) -> str:
+        """Analyze logs."""
+        return f"Analysis: {query}"
+    
+    tools = [Tool(name="analyze_logs", func=analyze_logs,
+                  description="Analyze application logs")]
+    
+    prompt = ChatPromptTemplate.from_messages([
+        ("system", "You are a log analysis assistant."),
+        ("user", "{input}"),
+        MessagesPlaceholder(variable_name="agent_scratchpad"),
+    ])
+    
+    agent = create_openai_tools_agent(llm, tools, prompt)
+    base_agent = AgentExecutor(agent=agent, tools=tools, verbose=True)
+    
+    # 2. Wrap with SCAK in one line!
+    scak_agent = create_scak_agent(
+        base_agent,
+        callback_handler=SCAKCallbackHandler(),
+        enable_correction=True,
+        agent_id="convenience_agent"
+    )
+    
+    # 3. Use normally
+    print("\n>>> Running SCAK-enabled agent...")
+    
+    try:
+        result = scak_agent.invoke({
+            "input": "Analyze recent error logs"
+        })
+        print(f"\n✓ Result: {result.get('output', result)[:100]}")
+    except Exception as e:
+        print(f"\n✗ Error: {e}")
+    
+    print("\n✨ SCAK integration complete with just one function call!")
+
+
+# ============================================================================
+# Main
+# ============================================================================
+
+def main():
+    """Run all examples."""
+    print("""
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║   LangChain Integration Examples for Self-Correcting Agent Kernel (SCAK)    ║
+║                                                                              ║
+║   These examples demonstrate three integration patterns:                    ║
+║   1. Basic: Add laziness monitoring to existing agents                      ║
+║   2. Full: Use all SCAK components for maximum reliability                  ║
+║   3. Convenience: Quick setup with create_scak_agent()                      ║
+║                                                                              ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+    """)
+    
+    if not LANGCHAIN_AVAILABLE:
+        print("⚠️  LangChain is not installed.")
+        print("   Install with: pip install langchain langchain-core langchain-openai")
+        print("   Then set OPENAI_API_KEY environment variable.")
+        return
+    
+    # Check for API key
+    if not os.getenv("OPENAI_API_KEY"):
+        print("⚠️  OPENAI_API_KEY environment variable not set.")
+        print("   Set it with: export OPENAI_API_KEY='your-key'")
+        print("\n   Running examples in mock mode...")
+    
+    # Run examples
+    try:
+        example_basic_integration()
+        example_full_integration()
+        example_convenience_function()
+    except Exception as e:
+        print(f"\n❌ Example failed: {e}")
+        import traceback
+        traceback.print_exc()
+    
+    print("\n" + "=" * 80)
+    print("✅ All examples completed!")
+    print("=" * 80)
+
+
+if __name__ == "__main__":
+    main()

modules/scak/examples/layer4_demo.py

@@ -0,0 +1,243 @@
+"""
+Layer 4 Example: SCAK as Control Plane Extension.
+
+This example demonstrates:
+1. SCAK as a generic plugin (no application-specific logic)
+2. Integration with Control Plane (using mocks)
+3. CMVK verification for laziness detection
+4. Self-correction loop with patch lifecycle
+
+Architecture:
+    Layer 4: SCAK (This extension)
+    Layer 3: Control Plane (agent-control-plane)
+    Verification: CMVK (cmvk)
+
+Installation:
+    pip install scak[full]  # Gets control-plane + cmvk
+
+Usage:
+    python examples/layer4_demo.py
+"""
+
+import asyncio
+import logging
+import sys
+import os
+
+# Add project root to path
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+# Configure logging to see SCAK telemetry
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+
+# SCAK imports
+from src.kernel.core import SelfCorrectingKernel, create_kernel
+from src.integrations.cmvk_adapter import MockCMVKVerifier
+from src.integrations.control_plane_adapter import SCAKExtension, MockControlPlane
+
+
+async def demo_laziness_detection():
+    """
+    Demonstrate laziness detection and self-correction.
+    
+    SCAK detects when an agent gives up prematurely and generates
+    a competence patch to prevent future laziness.
+    """
+    print("\n" + "=" * 80)
+    print("DEMO: Laziness Detection with CMVK Verification")
+    print("=" * 80)
+    
+    # Create kernel with mocks (in production, use real packages)
+    # Note: Mock CMVK returns 0.65 confidence for give-up signals
+    kernel = create_kernel(config={
+        "model_version": "gpt-4o",
+        "auto_patch": True,
+        "verification_threshold": 0.6,  # Lower than mock's 0.65 confidence
+    })
+    
+    print(f"\n✓ Kernel created: {kernel._agent_id}")
+    print(f"  - Model: {kernel._current_model_version}")
+    print(f"  - Verifier: {type(kernel._verifier).__name__}")
+    print(f"  - Control Plane: {type(kernel._control_plane).__name__}")
+    
+    # Test 1: Normal response (no laziness)
+    print("\n--- Test 1: Normal Response ---")
+    result1 = await kernel.handle_outcome(
+        agent_id="customer-support-agent",
+        user_prompt="What is our return policy?",
+        agent_response="Our return policy allows returns within 30 days of purchase. "
+                      "Items must be in original condition with receipt.",
+        context={"department": "support"}
+    )
+    print(f"  Laziness detected: {result1.laziness_detected}")
+    print(f"  Patch generated: {result1.patch is not None}")
+    print(f"  Message: {result1.message}")
+    
+    # Test 2: Lazy response (give-up signal)
+    print("\n--- Test 2: Lazy Response (Give-Up Signal) ---")
+    result2 = await kernel.handle_outcome(
+        agent_id="data-analyst-agent",
+        user_prompt="Find the sales logs for Q4 2024 showing errors above 500",
+        agent_response="I couldn't find any logs matching your criteria. "
+                      "No data found in the system.",
+        context={"data_source": "sales_db"}
+    )
+    print(f"  Laziness detected: {result2.laziness_detected}")
+    print(f"  Patch generated: {result2.patch is not None}")
+    if result2.patch:
+        print(f"  Patch ID: {result2.patch.patch_id}")
+        print(f"  Patch Type: {result2.patch.patch_type}")
+        print(f"  Instruction: {result2.patch.instruction[:100]}...")
+    print(f"  CMVK Confidence: {result2.verification_confidence:.2f}")
+    
+    # Test 3: Another lazy response
+    print("\n--- Test 3: Another Lazy Response ---")
+    result3 = await kernel.handle_outcome(
+        agent_id="project-manager-agent",
+        user_prompt="Check the status of Project Alpha",
+        agent_response="I'm unable to locate Project Alpha in the system. "
+                      "The project may not exist.",
+        context={"workspace": "engineering"}
+    )
+    print(f"  Laziness detected: {result3.laziness_detected}")
+    print(f"  Patch generated: {result3.patch is not None}")
+    
+    # Final statistics
+    print("\n--- Final Statistics ---")
+    stats = kernel.get_statistics()
+    print(f"  Outcomes processed: {stats['outcomes_processed']}")
+    print(f"  Corrections applied: {stats['corrections_applied']}")
+    print(f"  Laziness count: {stats['laziness_count']}")
+    print(f"  Laziness rate: {stats['laziness_rate']:.1%}")
+    
+    return kernel
+
+
+async def demo_model_upgrade():
+    """
+    Demonstrate semantic purge on model upgrade.
+    
+    Type A patches (syntax/capability) are purged when upgrading models.
+    Type B patches (business/context) are retained.
+    """
+    print("\n" + "=" * 80)
+    print("DEMO: Model Upgrade and Semantic Purge")
+    print("=" * 80)
+    
+    kernel = create_kernel(config={"model_version": "gpt-4o"})
+    
+    # Generate some patches via lazy responses
+    await kernel.handle_outcome(
+        agent_id="agent-1",
+        user_prompt="Find user records",
+        agent_response="No data found"
+    )
+    await kernel.handle_outcome(
+        agent_id="agent-2", 
+        user_prompt="Check customer logs",
+        agent_response="I couldn't find the logs"
+    )
+    
+    print(f"\nBefore upgrade (model: {kernel._current_model_version}):")
+    print(f"  Patches generated: {kernel._corrections_applied}")
+    
+    # Upgrade model - triggers semantic purge
+    print("\n--- Upgrading to gpt-5 ---")
+    result = kernel.upgrade_model("gpt-5")
+    
+    print(f"\nAfter upgrade (model: {kernel._current_model_version}):")
+    print(f"  Purge triggered: {result['purge_triggered']}")
+    print(f"  Old version: {result['old_version']}")
+    print(f"  New version: {result['new_version']}")
+    print("\n  Note: Type A patches (capability) would be purged")
+    print("        Type B patches (business) would be retained")
+
+
+async def demo_control_plane_integration():
+    """
+    Demonstrate SCAK as a Control Plane extension.
+    
+    In production:
+        from agent_control_plane import ControlPlane
+        cp = ControlPlane()
+        scak = SCAKExtension()
+        cp.register_extension(scak)
+    """
+    print("\n" + "=" * 80)
+    print("DEMO: Control Plane Integration")
+    print("=" * 80)
+    
+    # Create mock control plane
+    control_plane = MockControlPlane()
+    
+    # Create SCAK extension
+    verifier = MockCMVKVerifier()
+    scak_extension = SCAKExtension(verifier=verifier)
+    
+    # Register with control plane
+    control_plane.register_extension(scak_extension)
+    print(f"\n✓ SCAK Extension registered: {scak_extension.extension_id}")
+    print(f"  Subscribed events: {scak_extension.subscribed_events}")
+    
+    # Simulate agent outcome through control plane
+    from src.integrations.control_plane_adapter import AgentOutcome
+    
+    outcome = AgentOutcome(
+        agent_id="orchestrated-agent",
+        prompt="Retrieve archived project data",
+        response="I don't have access to find the project data.",
+        success=True,
+        execution_time_ms=150,
+        context={"source": "control_plane"}
+    )
+    
+    print("\n--- Processing outcome through Control Plane ---")
+    await control_plane.handle_outcome(outcome)
+    
+    # Check patches
+    patches = control_plane.get_patches("orchestrated-agent")
+    print(f"\n  Patches applied to agent: {len(patches)}")
+    for patch in patches:
+        print(f"    - {patch.patch_id}: {patch.instruction[:50]}...")
+    
+    # Extension stats
+    ext_stats = scak_extension.get_statistics()
+    print(f"\n  Extension stats:")
+    print(f"    Outcomes processed: {ext_stats['outcomes_processed']}")
+    print(f"    Patches generated: {ext_stats['patches_generated']}")
+    print(f"    Laziness detected: {ext_stats['laziness_detected']}")
+
+
+async def main():
+    """Run all Layer 4 demos."""
+    print("\n" + "#" * 80)
+    print("# SCAK Layer 4 Demo: Self-Correcting Agent Kernel as Control Plane Extension")
+    print("#" * 80)
+    print("\nSCAK is a specialized 'brain' that fits into the Control Plane.")
+    print("It implements Laziness Detection and Self-Correction using CMVK verification.")
+    print("\nKey Dependencies:")
+    print("  - agent-control-plane: For Control Plane integration")
+    print("  - cmvk: For claim-based verification")
+    print("\nNote: This demo uses mocks. In production, install:")
+    print("  pip install scak[full]")
+    
+    await demo_laziness_detection()
+    await demo_model_upgrade()
+    await demo_control_plane_integration()
+    
+    print("\n" + "#" * 80)
+    print("# Demo Complete!")
+    print("#" * 80)
+    print("\nSCAK provides:")
+    print("  ✓ Laziness detection via CMVK verification")
+    print("  ✓ Self-correction with patch lifecycle management")
+    print("  ✓ Generic extension for ANY agent (no app-specific logic)")
+    print("  ✓ Semantic purge on model upgrades")
+    print("\nFor production usage, see: pip install scak[full]")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())