kite-agent 0.1.0__py3-none-any.whl

kite/routing/semantic_router.py

@@ -0,0 +1,228 @@
+"""
+Semantic Router Implementation
+Based on Chapter 6: The Semantic Router
+
+A router that classifies user intent and routes to specialists.
+Uses embeddings for fast, cached classification.
+"""
+
+import os
+import hashlib
+from typing import Dict, List, Optional, Callable
+from dataclasses import dataclass
+from functools import lru_cache
+import numpy as np
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+# ============================================================================
+# ROUTING CONFIGURATION
+# ============================================================================
+
+@dataclass
+class Route:
+    """Define a route with examples and handler."""
+    name: str
+    description: str
+    examples: List[str]
+    handler: Callable
+    embedding: Optional[np.ndarray] = None
+
+
+# ============================================================================
+# SEMANTIC ROUTER
+# ============================================================================
+
+class SemanticRouter:
+    """
+    Routes user queries to specialist agents based on semantic similarity.
+    
+    Features:
+    - Embedding-based classification (fast, cheap)
+    - LRU caching for repeated queries
+    - Confidence thresholds
+    - Ambiguity handling
+    
+    Example:
+        router = SemanticRouter(embedding_provider=my_embedder)
+        router.add_route("technical", tech_agent.handle, [
+            "my internet is down",
+            "can't connect to wifi",
+            "server not responding"
+        ])
+        
+        response = router.route("my connection keeps dropping")
+    """
+    
+    def __init__(self, 
+                 confidence_threshold: float = 0.75,
+                 embedding_provider = None):
+        self.routes: List[Route] = []
+        self.confidence_threshold = confidence_threshold
+        self.embedding_provider = embedding_provider
+        
+        # Precompute route embeddings if routes exist (none initially)
+        self._compute_route_embeddings()
+    
+    @lru_cache(maxsize=10000)
+    def _get_embedding(self, text: str) -> np.ndarray:
+        """Get embedding for text with LRU caching."""
+        if self.embedding_provider:
+            return np.array(self.embedding_provider.embed(text))
+            
+        raise RuntimeError("No embedding provider configured for SemanticRouter")
+    
+    def _compute_route_embeddings(self):
+        """Precompute embeddings for all route examples."""
+        if not self.routes:
+            return
+
+        print("[CHART] Computing route embeddings...")
+        for route in self.routes:
+            if route.embedding is None:
+                # Combine all examples into one text for the route
+                combined_text = " | ".join(route.examples)
+                route.embedding = self._get_embedding(combined_text)
+    
+    def _cosine_similarity(self, a: np.ndarray, b: np.ndarray) -> float:
+        """Calculate cosine similarity between two vectors."""
+        return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))
+    
+    def classify_intent(self, query: str) -> tuple[Route, float]:
+        """
+        Classify query intent using semantic similarity.
+        
+        Args:
+            query: User query
+            
+        Returns:
+            (best_route, confidence_score)
+        """
+        if not self.routes:
+            raise RuntimeError("No routes configured in SemanticRouter")
+
+        # Get query embedding (cached if seen before)
+        query_embedding = self._get_embedding(query)
+        
+        # Calculate similarity to each route
+        scores = []
+        for route in self.routes:
+            similarity = self._cosine_similarity(query_embedding, route.embedding)
+            scores.append((route, similarity))
+        
+        # Sort by similarity
+        scores.sort(key=lambda x: x[1], reverse=True)
+        
+        best_route, best_score = scores[0]
+        
+        print(f"\n  Intent Classification:")
+        print(f"   Query: {query}")
+        print(f"   Best Match: {best_route.name} (confidence: {best_score:.2%})")
+        
+        return best_route, best_score
+    
+    async def route(self, query: str, context: Optional[Dict] = None) -> Dict:
+        """
+        Route query to appropriate specialist agent.
+        
+        Args:
+            query: User query
+            context: Optional context to pass to handler
+            
+        Returns:
+            Response dictionary with routing info
+        """
+        # Classify intent
+        route, confidence = self.classify_intent(query)
+        
+        # Handle low confidence (ambiguity)
+        if confidence < self.confidence_threshold:
+            print(f"[WARN]  Low confidence ({confidence:.2%} < {self.confidence_threshold:.2%})")
+            
+            return {
+                "route": "none",
+                "confidence": confidence,
+                "response": "I'm not sure how to help with that. Could you be more specific?",
+                "needs_clarification": True,
+                "suggested_routes": [r.name for r, _ in self._get_top_routes(query, n=3)]
+            }
+        
+        # Route to specialist
+        print(f"[OK] Routing to {route.name}")
+        if context:
+            response = route.handler(query, context)
+        else:
+            try:
+                response = route.handler(query)
+            except TypeError:
+                # Fallback if handler expects context but none provided
+                response = route.handler(query, {})
+        
+        # Support both sync and async handlers
+        import asyncio
+        if asyncio.iscoroutine(response):
+            response = await response
+            
+        # If response is a dict (from Agent.run), extract the 'response' text if available
+        if isinstance(response, dict) and 'response' in response:
+            response_text = response['response']
+        else:
+            response_text = str(response)
+        
+        return {
+            "route": route.name,
+            "confidence": confidence,
+            "response": response_text,
+            "needs_clarification": False
+        }
+    
+    def _get_top_routes(self, query: str, n: int = 3) -> List[tuple[Route, float]]:
+        """Get top N routes by similarity."""
+        query_embedding = self._get_embedding(query)
+        
+        scores = [
+            (route, self._cosine_similarity(query_embedding, route.embedding))
+            for route in self.routes
+        ]
+        
+        scores.sort(key=lambda x: x[1], reverse=True)
+        return scores[:n]
+    
+    def add_route(self, name: str, examples: List[str] | str, description: str = "", handler: Callable = None):
+        """Add a new route dynamically."""
+        if isinstance(examples, str):
+            examples = [examples]
+            
+        route = Route(
+            name=name,
+            description=description,
+            examples=examples,
+            handler=handler or (lambda x: f"Default response for {name}")
+        )
+        
+        # Compute embedding if provider exists
+        if self.embedding_provider:
+            combined_text = " | ".join(examples)
+            route.embedding = self._get_embedding(combined_text)
+        
+        self.routes.append(route)
+        print(f"[OK] Added route: {name}")
+    
+    def get_stats(self) -> Dict:
+        """Get router statistics."""
+        cache_info = self._get_embedding.cache_info()
+        
+        return {
+            "total_routes": len(self.routes),
+            "confidence_threshold": self.confidence_threshold,
+            "cache_size": cache_info.currsize,
+            "cache_hits": cache_info.hits,
+            "cache_misses": cache_info.misses,
+            "cache_hit_rate": (
+                cache_info.hits / (cache_info.hits + cache_info.misses)
+                if (cache_info.hits + cache_info.misses) > 0
+                else 0
+            )
+        }

kite/safety/__init__.py

@@ -0,0 +1,6 @@
+"""Safety patterns module."""
+from .circuit_breaker import CircuitBreaker, CircuitBreakerConfig, CircuitState
+from .idempotency_manager import IdempotencyManager, IdempotencyConfig
+from .kill_switch import KillSwitch
+
+__all__ = ['CircuitBreaker', 'CircuitBreakerConfig', 'CircuitState', 'IdempotencyManager', 'IdempotencyConfig', 'KillSwitch']

kite/safety/circuit_breaker.py

@@ -0,0 +1,360 @@
+"""
+Circuit Breaker Pattern for AI Agent Operations
+
+Prevents cascading failures when an agent repeatedly attempts failed operations.
+This is critical for write-access AI systems where retries can cause real damage.
+
+Author: [Your Name]
+License: MIT
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from enum import Enum
+from typing import Dict, Optional, Callable, Any
+import logging
+from functools import wraps
+
+logger = logging.getLogger(__name__)
+
+
+class CircuitState(Enum):
+    """States of the circuit breaker."""
+    CLOSED = "closed"      # Normal operation
+    OPEN = "open"          # Blocking requests
+    HALF_OPEN = "half_open"  # Testing if service recovered
+
+
+@dataclass
+class CircuitBreakerConfig:
+    """Configuration for circuit breaker behavior."""
+    failure_threshold: int = 3          # Failures before opening
+    success_threshold: int = 2          # Successes to close from half-open
+    timeout_seconds: int = 60           # Time before attempting recovery
+    half_open_max_calls: int = 1        # Max concurrent calls in half-open
+
+
+@dataclass
+class CircuitStats:
+    """Statistics for monitoring circuit breaker health."""
+    total_calls: int = 0
+    successful_calls: int = 0
+    failed_calls: int = 0
+    rejected_calls: int = 0
+    last_failure_time: Optional[datetime] = None
+    last_success_time: Optional[datetime] = None
+    state_changes: int = 0
+
+
+class CircuitBreaker:
+    """
+    Circuit breaker for AI agent operations.
+    
+    Use this to wrap any operation that:
+    - Makes external API calls
+    - Modifies state
+    - Costs money
+    - Could fail repeatedly
+    
+    Example:
+        circuit_breaker = CircuitBreaker(
+            name="stripe_refunds",
+            config=CircuitBreakerConfig(failure_threshold=3)
+        )
+        
+        @circuit_breaker.protected
+        def process_refund(order_id: str, amount: float):
+            return stripe.Refund.create(...)
+    """
+    
+    def __init__(
+        self,
+        name: str,
+        config: CircuitBreakerConfig = None,
+        on_open: Optional[Callable] = None,
+        on_close: Optional[Callable] = None
+    ):
+        self.name = name
+        self.config = config or CircuitBreakerConfig()
+        self.state = CircuitState.CLOSED
+        self.stats = CircuitStats()
+        
+        # Callbacks for state changes
+        self.on_open = on_open
+        self.on_close = on_close
+        
+        # Failure tracking
+        self.consecutive_failures = 0
+        self.consecutive_successes = 0
+        self.open_until: Optional[datetime] = None
+        self.half_open_calls = 0
+        
+        logger.info(f"Circuit breaker '{name}' initialized: {config}")
+    
+    def _change_state(self, new_state: CircuitState, reason: str):
+        """Change circuit state and trigger callbacks."""
+        if new_state == self.state:
+            return
+            
+        old_state = self.state
+        self.state = new_state
+        self.stats.state_changes += 1
+        
+        logger.warning(
+            f"Circuit '{self.name}': {old_state.value}   {new_state.value} "
+            f"(Reason: {reason})"
+        )
+        
+        if new_state == CircuitState.OPEN and self.on_open:
+            self.on_open(self.name, self.stats)
+        elif new_state == CircuitState.CLOSED and self.on_close:
+            self.on_close(self.name, self.stats)
+    
+    def _should_attempt_reset(self) -> bool:
+        """Check if enough time has passed to attempt recovery."""
+        if self.state != CircuitState.OPEN:
+            return False
+            
+        if self.open_until and datetime.now() >= self.open_until:
+            return True
+        
+        return False
+    
+    def call(self, func: Callable, *args, **kwargs) -> Any:
+        """
+        Execute a function with circuit breaker protection.
+        
+        Args:
+            func: Function to call
+            *args, **kwargs: Arguments to pass to function
+            
+        Returns:
+            Result from function
+            
+        Raises:
+            CircuitBreakerError: If circuit is open
+            Original exception: If function fails
+        """
+        self.stats.total_calls += 1
+        
+        # Check if circuit should transition from OPEN to HALF_OPEN
+        if self._should_attempt_reset():
+            self._change_state(CircuitState.HALF_OPEN, "Timeout expired")
+            self.half_open_calls = 0
+        
+        # Block calls if circuit is OPEN
+        if self.state == CircuitState.OPEN:
+            self.stats.rejected_calls += 1
+            raise CircuitBreakerError(
+                f"Circuit '{self.name}' is OPEN. "
+                f"Reset at {self.open_until}"
+            )
+        
+        # Limit concurrent calls in HALF_OPEN state
+        if self.state == CircuitState.HALF_OPEN:
+            if self.half_open_calls >= self.config.half_open_max_calls:
+                self.stats.rejected_calls += 1
+                raise CircuitBreakerError(
+                    f"Circuit '{self.name}' is HALF_OPEN and at capacity"
+                )
+            self.half_open_calls += 1
+        
+        # Attempt the call
+        try:
+            result = func(*args, **kwargs)
+            self._on_success()
+            return result
+            
+        except Exception as e:
+            self._on_failure()
+            raise
+        
+        finally:
+            if self.state == CircuitState.HALF_OPEN:
+                self.half_open_calls -= 1
+    
+    def _on_success(self):
+        """Handle successful function call."""
+        self.stats.successful_calls += 1
+        self.stats.last_success_time = datetime.now()
+        self.consecutive_failures = 0
+        
+        if self.state == CircuitState.HALF_OPEN:
+            self.consecutive_successes += 1
+            
+            if self.consecutive_successes >= self.config.success_threshold:
+                self._change_state(
+                    CircuitState.CLOSED,
+                    f"{self.consecutive_successes} consecutive successes"
+                )
+                self.consecutive_successes = 0
+        
+        logger.debug(f"Circuit '{self.name}': Call succeeded")
+    
+    def _on_failure(self):
+        """Handle failed function call."""
+        self.stats.failed_calls += 1
+        self.stats.last_failure_time = datetime.now()
+        self.consecutive_successes = 0
+        self.consecutive_failures += 1
+        
+        logger.warning(
+            f"Circuit '{self.name}': Call failed "
+            f"({self.consecutive_failures}/{self.config.failure_threshold})"
+        )
+        
+        # Open circuit if threshold exceeded
+        if self.consecutive_failures >= self.config.failure_threshold:
+            self.open_until = (
+                datetime.now() + 
+                timedelta(seconds=self.config.timeout_seconds)
+            )
+            self._change_state(
+                CircuitState.OPEN,
+                f"{self.consecutive_failures} consecutive failures"
+            )
+    
+    def protected(self, func: Callable) -> Callable:
+        """
+        Decorator to protect a function with circuit breaker.
+        
+        Example:
+            @circuit_breaker.protected
+            def risky_operation():
+                return external_api.call()
+        """
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            return self.call(func, *args, **kwargs)
+        return wrapper
+    
+    def reset(self):
+        """Manually reset circuit to closed state."""
+        self._change_state(CircuitState.CLOSED, "Manual reset")
+        self.consecutive_failures = 0
+        self.consecutive_successes = 0
+        self.open_until = None
+    
+    def get_stats(self) -> Dict[str, Any]:
+        """Get current statistics."""
+        return {
+            "name": self.name,
+            "state": self.state.value,
+            "total_calls": self.stats.total_calls,
+            "successful_calls": self.stats.successful_calls,
+            "failed_calls": self.stats.failed_calls,
+            "rejected_calls": self.stats.rejected_calls,
+            "success_rate": (
+                self.stats.successful_calls / self.stats.total_calls
+                if self.stats.total_calls > 0 else 0
+            ),
+            "consecutive_failures": self.consecutive_failures,
+            "open_until": self.open_until.isoformat() if self.open_until else None,
+            "last_failure": (
+                self.stats.last_failure_time.isoformat() 
+                if self.stats.last_failure_time else None
+            )
+        }
+
+
+class CircuitBreakerError(Exception):
+    """Raised when circuit breaker blocks an operation."""
+    pass
+
+
+class CircuitBreakerRegistry:
+    """
+    Global registry for managing multiple circuit breakers.
+    
+    Use this when you have multiple operations that need separate circuits.
+    """
+    
+    def __init__(self):
+        self._breakers: Dict[str, CircuitBreaker] = {}
+    
+    def get_or_create(
+        self,
+        name: str,
+        config: Optional[CircuitBreakerConfig] = None
+    ) -> CircuitBreaker:
+        """Get existing circuit breaker or create new one."""
+        if name not in self._breakers:
+            self._breakers[name] = CircuitBreaker(name, config)
+        return self._breakers[name]
+    
+    def get_all_stats(self) -> Dict[str, Dict[str, Any]]:
+        """Get statistics for all circuit breakers."""
+        return {
+            name: breaker.get_stats()
+            for name, breaker in self._breakers.items()
+        }
+    
+    def reset_all(self):
+        """Reset all circuit breakers."""
+        for breaker in self._breakers.values():
+            breaker.reset()
+
+
+# Global registry instance
+registry = CircuitBreakerRegistry()
+
+
+# Convenience function
+def circuit_breaker(
+    name: str,
+    config: Optional[CircuitBreakerConfig] = None
+) -> CircuitBreaker:
+    """Get or create a circuit breaker from global registry."""
+    return registry.get_or_create(name, config)
+
+
+if __name__ == "__main__":
+    # Example usage
+    import time
+    
+    # Configure logging
+    logging.basicConfig(
+        level=logging.INFO,
+        format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+    )
+    
+    # Create circuit breaker
+    breaker = CircuitBreaker(
+        name="example_api",
+        config=CircuitBreakerConfig(
+            failure_threshold=3,
+            timeout_seconds=5
+        )
+    )
+    
+    # Simulate API calls
+    call_count = 0
+    
+    def flaky_api_call():
+        """Simulates an API that fails sometimes."""
+        global call_count
+        call_count += 1
+        
+        # Fail first 5 calls, then succeed
+        if call_count <= 5:
+            raise Exception("API Error")
+        return {"status": "success", "data": "..."}
+    
+    # Test circuit breaker
+    print("\n=== Testing Circuit Breaker ===\n")
+    
+    for i in range(10):
+        print(f"\nAttempt {i+1}:")
+        try:
+            result = breaker.call(flaky_api_call)
+            print(f"[OK] Success: {result}")
+        except CircuitBreakerError as e:
+            print(f"  Circuit Open: {e}")
+        except Exception as e:
+            print(f"  API Error: {e}")
+        
+        time.sleep(1)
+    
+    # Show final stats
+    print("\n=== Final Statistics ===")
+    print(breaker.get_stats())

kite/safety/guardrails.py

@@ -0,0 +1,82 @@
+"""
+Guardrails / Safety Patterns (Chapter 18)
+Provides mechanisms to ensure agent inputs and outputs adhere to safety and structure guidelines.
+"""
+
+from typing import Type, Optional, Any, Dict
+from pydantic import BaseModel, ValidationError, Field
+import re
+import logging
+
+logger = logging.getLogger("Guardrails")
+
+class OutputGuardrail:
+    """
+    Enforces structured output from an LLM using Pydantic models.
+    Chapter 18: Output Filtering / Post-processing.
+    """
+    def __init__(self, model: Type[BaseModel], fix_on_failure: bool = True):
+        self.model = model
+        self.fix_on_failure = fix_on_failure
+
+    def validate(self, output: str) -> Optional[BaseModel]:
+        """
+        Validates and parses the LLM output. Uses regex to find the first JSON object.
+        """
+        try:
+            # Attempt to find a JSON-like block { ... }
+            # distinct from code blocks, just looking for the brace structure
+            json_match = re.search(r"\{.*\}", output, re.DOTALL)
+            
+            if json_match:
+                clean_output = json_match.group(0)
+            else:
+                # Fallback to original cleanup if regex fails
+                clean_output = output.strip()
+                if clean_output.startswith("```json"):
+                    clean_output = clean_output[7:]
+                if clean_output.startswith("```"):
+                    clean_output = clean_output[3:]
+                if clean_output.endswith("```"):
+                    clean_output = clean_output[:-3]
+            
+            clean_output = clean_output.strip()
+            
+            # Parse
+            parsed = self.model.model_validate_json(clean_output)
+            logger.info(f"Guardrail passed: {type(parsed).__name__}")
+            return parsed
+            
+        except ValidationError as e:
+            logger.warning(f"Guardrail validation failed: {e}")
+            if self.fix_on_failure:
+                return None # Signal need for retry/fix
+            raise e
+        except Exception as e:
+            logger.error(f"Guardrail parsing error: {e}")
+            return None
+
+class StandardEvaluation(BaseModel):
+    """Standard schema for Agent critique/review."""
+    score: int = Field(description="Score from 1-10")
+    feedback: str = Field(description="Specific feedback for improvement")
+    approved: bool = Field(description="Whether the output is acceptable")
+
+class InputGuardrail:
+    """
+    Filters unsafe or irrelevant user inputs before they reach the agent.
+    Chapter 18: Input Validation / Sanitization.
+    """
+    def __init__(self, forbidden_terms: list = None):
+        self.forbidden_terms = forbidden_terms or ["ignore all instructions", "system prompt"]
+
+    def check(self, user_input: str) -> bool:
+        """
+        Returns True if safe, False if unsafe.
+        """
+        content = user_input.lower()
+        for term in self.forbidden_terms:
+            if term in content:
+                logger.warning(f"Guardrail blocked input containing: '{term}'")
+                return False
+        return True