kite-agent 0.1.0__py3-none-any.whl

kite/pipeline/reactive_pipeline.py

@@ -0,0 +1,171 @@
+"""
+Reactive Pipeline Pattern
+Level 2 Autonomy: Event-driven, concurrent processing with workers.
+
+Flow: Producer -> Stage 1 (N workers) -> Stage 2 (M workers) -> ... -> Result
+"""
+
+import asyncio
+import logging
+import inspect
+from typing import Dict, List, Optional, Any, Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+from .deterministic_pipeline import PipelineStatus, PipelineState
+
+@dataclass
+class ReactiveStage:
+    name: str
+    func: Callable
+    workers: int
+    input_queue: asyncio.Queue = field(default_factory=asyncio.Queue)
+    output_queue: Optional[asyncio.Queue] = None
+    tasks: List[asyncio.Task] = field(default_factory=list)
+
+class ReactivePipeline:
+    """
+    A reactive, streaming data pipeline with parallel workers.
+    
+    Each stage runs N workers in parallel, reading from an input queue
+    and passing results to the next stage's queue.
+    """
+    
+    def __init__(self, name: str = "reactive_pipeline", event_bus = None):
+        self.name = name
+        self.event_bus = event_bus
+        self.stages: List[ReactiveStage] = []
+        self.logger = logging.getLogger(f"Pipeline:{name}")
+        self.history: List[PipelineState] = []
+        self._running_tasks = []
+        
+        if self.event_bus:
+            self.event_bus.emit("pipeline:init", {"pipeline": self.name, "type": "reactive"})
+
+    def add_stage(self, name: str, func: Callable, workers: int = 1):
+        """Add a processing stage with a specific number of workers."""
+        stage = ReactiveStage(name=name, func=func, workers=workers)
+        
+        # Connect output of previous stage to input of this stage
+        if self.stages:
+            self.stages[-1].output_queue = stage.input_queue
+            
+        self.stages.append(stage)
+        self.logger.info(f"  [OK] Added stage: {name} (Workers: {workers})")
+
+    async def execute(self, initial_data: Any, task_id: Optional[str] = None):
+        """
+        Start the pipeline and feed it initial data.
+        Note: initial_data can be a single item or a list of items.
+        """
+        t_id = task_id or f"RTASK-{datetime.now().strftime('%H%M%S')}"
+        
+        if self.event_bus:
+            self.event_bus.emit("pipeline:start", {
+                "pipeline": self.name, 
+                "task_id": t_id, 
+                "mode": "reactive",
+                "stages": [s.name for s in self.stages]
+            })
+            # Emit structure for dashboard
+            self.event_bus.emit("pipeline:structure", {
+                "pipeline": self.name,
+                "task_id": t_id,
+                "steps": [s.name for s in self.stages]
+            })
+
+        # Start all workers for all stages
+        for i, stage in enumerate(self.stages):
+            for w_idx in range(stage.workers):
+                task = asyncio.create_task(
+                    self._worker_loop(stage, t_id),
+                    name=f"Worker-{stage.name}-{w_idx}"
+                )
+                stage.tasks.append(task)
+                self._running_tasks.append(task)
+
+        # Feed the first stage
+        if isinstance(initial_data, list):
+            for item in initial_data:
+                await self.stages[0].input_queue.put(item)
+        else:
+            await self.stages[0].input_queue.put(initial_data)
+
+        self.logger.info(f"Pipeline {self.name} is running...")
+        return t_id
+
+    async def _worker_loop(self, stage: ReactiveStage, task_id: str):
+        """Internal loop for a single worker in a stage."""
+        while True:
+            item = await stage.input_queue.get()
+            if item is None: # Shutdown signal
+                stage.input_queue.task_done()
+                break
+            
+            try:
+                if self.event_bus:
+                    self.event_bus.emit("pipeline:step_start", {
+                        "pipeline": self.name,
+                        "task_id": task_id,
+                        "step": stage.name,
+                        "data": str(item)[:100]
+                    })
+
+                # Execute function
+                if inspect.isasyncgenfunction(stage.func):
+                    # Handle async generator for streaming
+                    async for result in stage.func(item):
+                        if stage.output_queue and result is not None:
+                            if isinstance(result, list):
+                                for sub_item in result:
+                                    await stage.output_queue.put(sub_item)
+                            else:
+                                await stage.output_queue.put(result)
+                elif inspect.iscoroutinefunction(stage.func):
+                    result = await stage.func(item)
+                    if stage.output_queue and result is not None:
+                        if isinstance(result, list):
+                            for sub_item in result:
+                                await stage.output_queue.put(sub_item)
+                        else:
+                            await stage.output_queue.put(result)
+                else:
+                    result = stage.func(item)
+                    if stage.output_queue and result is not None:
+                        if isinstance(result, list):
+                            for sub_item in result:
+                                await stage.output_queue.put(sub_item)
+                        else:
+                            await stage.output_queue.put(result)
+
+            except Exception as e:
+                self.logger.error(f"Error in stage {stage.name}: {e}")
+                if self.event_bus:
+                    self.event_bus.emit("pipeline:error", {
+                        "pipeline": self.name,
+                        "task_id": task_id,
+                        "step": stage.name,
+                        "error": str(e)
+                    })
+            finally:
+                stage.input_queue.task_done()
+
+    async def wait_until_complete(self):
+        """Wait for all items to flow through all queues and workers to exit."""
+        for stage in self.stages:
+            # 1. Wait for all items in the current queue to be PROCESSED
+            await stage.input_queue.join()
+            
+            # 2. Tell all workers in this stage to SHUT DOWN
+            for _ in range(stage.workers):
+                await stage.input_queue.put(None)
+            
+            # 3. Wait for these specific workers to finish
+            if stage.tasks:
+                await asyncio.gather(*stage.tasks)
+                
+        self.logger.info(f"Pipeline {self.name} completed successfully.")
+        
+    def stop(self):
+        """Force stop all workers."""
+        for task in self._running_tasks:
+            task.cancel()

kite/pipeline_manager.py

@@ -0,0 +1,15 @@
+"""Pipeline Manager"""
+
+class PipelineManager:
+    def __init__(self, pipeline_class, logger):
+        self.pipeline_class = pipeline_class
+        self.logger = logger
+        self.pipelines = {}
+    
+    def create(self, name: str, event_bus = None):
+        pipeline = self.pipeline_class(name, event_bus=event_bus)
+        self.pipelines[name] = pipeline
+        return pipeline
+    
+    def get(self, name: str):
+        return self.pipelines.get(name)

kite/routing/__init__.py

@@ -0,0 +1,6 @@
+"""Routing systems module."""
+from .semantic_router import SemanticRouter
+from .aggregator_router import AggregatorRouter
+from .llm_router import LLMRouter
+
+__all__ = ['SemanticRouter', 'AggregatorRouter', 'LLMRouter']

kite/routing/aggregator_router.py

@@ -0,0 +1,325 @@
+from kite.agent import Agent
+from kite.llm_providers import LLMFactory
+import os
+import asyncio
+from typing import Dict, List, Optional, Callable, Any
+from dataclasses import dataclass, field
+from concurrent.futures import ThreadPoolExecutor
+from dotenv import load_dotenv
+import json
+
+load_dotenv()
+
+
+# ============================================================================
+# AGENT RESPONSE
+# ============================================================================
+
+@dataclass
+class AgentResponse:
+    """Response from a specialist agent."""
+    agent_name: str
+    subtask: str
+    response: str
+    success: bool
+    metadata: Dict = field(default_factory=dict)
+
+
+class SpecialistAgent(Agent):
+    """Base class for specialist agents using LLM logic."""
+    
+    def __init__(self, name: str, specialty: str, instructions: str, llm = None):
+        super().__init__(
+            name=name, 
+            system_prompt=f"Specialty: {specialty}\nInstructions: {instructions}", 
+            llm=llm or LLMFactory.auto_detect(),
+            tools=[],
+            framework=None
+        )
+        self.specialty = specialty
+        self.instructions = instructions
+    
+    async def handle(self, task: str) -> AgentResponse:
+        """Handle a specific task using LLM."""
+        print(f"    [{self.name}] Processing: {task}")
+        
+        prompt = f"""You are the {self.name} specialist. 
+Your specialty: {self.specialty}
+Instructions: {self.instructions}
+
+Task to perform: {task}
+
+Provide a detailed and helpful response."""
+        
+        try:
+            # Use the Agent's run method
+            response = await self.run(prompt) 
+            return AgentResponse(
+                agent_name=self.name,
+                subtask=task,
+                response=response,
+                success=True
+            )
+        except Exception as e:
+            return AgentResponse(
+                agent_name=self.name,
+                subtask=task,
+                response=f"Error processing task: {str(e)}",
+                success=False
+            )
+
+
+# ============================================================================
+# TASK DECOMPOSITION
+# ============================================================================
+
+@dataclass
+class Subtask:
+    """A decomposed subtask."""
+    description: str
+    assigned_agent: str
+    priority: int = 1  # 1 = highest
+
+
+class TaskDecomposer:
+    """
+    Decomposes complex queries into subtasks.
+    
+    Uses LLM to analyze intent and split into actionable subtasks.
+    """
+    
+    def __init__(self, llm = None):
+        self.llm = llm
+        self.agents_info = {}
+    
+    def decompose(self, query: str) -> List[Subtask]:
+        """
+        Decompose query into subtasks.
+        
+        Args:
+            query: User's complex query
+            
+        Returns:
+            List of subtasks with assigned agents
+        """
+        if not self.agents_info:
+            return [Subtask(description=query, assigned_agent="DefaultAgent", priority=1)]
+
+        print(f"\n  Decomposing query: {query}")
+        
+        # Create prompt for LLM
+        agents_desc = "\n".join([
+            f"- {name}: {desc}"
+            for name, desc in self.agents_info.items()
+        ])
+        
+        prompt = f"""You are a task decomposition expert. Analyze this user query and break it into subtasks.
+
+Available agents:
+{agents_desc}
+
+User query: "{query}"
+
+Decompose this into 1-3 specific subtasks. For each subtask:
+1. Write a clear, actionable description
+2. Assign to the most appropriate agent
+3. Set priority (1=highest, 3=lowest)
+
+Respond ONLY with valid JSON array:
+[
+  {{"description": "...", "agent": "SelectedAgentName", "priority": 1}},
+  {{"description": "...", "agent": "AnotherAgentName", "priority": 2}}
+]"""
+        
+        if self.llm:
+            response = self.llm.complete(prompt, temperature=0.3)
+            content = response.strip()
+        else:
+            # Fallback if no LLM provided (should not happen in production)
+            return [Subtask(description=query, assigned_agent=list(self.agents_info.keys())[0], priority=1)]
+        
+        # Robust JSON extraction
+        try:
+            # Find the first '[' and last ']'
+            start_idx = content.find('[')
+            end_idx = content.rfind(']')
+            if start_idx != -1 and end_idx != -1:
+                content = content[start_idx:end_idx + 1]
+            
+            tasks_data = json.loads(content)
+            subtasks = [
+                Subtask(
+                    description=task["description"],
+                    assigned_agent=task["agent"],
+                    priority=task.get("priority", 1)
+                )
+                for task in tasks_data
+            ]
+            
+            print(f"  [OK] Decomposed into {len(subtasks)} subtasks:")
+            for i, task in enumerate(subtasks, 1):
+                print(f"    {i}. [{task.assigned_agent}] {task.description}")
+            
+            return subtasks
+            
+        except json.JSONDecodeError as e:
+            print(f"    Failed to parse LLM response: {e}")
+            # Fallback
+            return [Subtask(
+                description=query,
+                assigned_agent=list(self.agents_info.keys())[0],
+                priority=1
+            )]
+
+
+# ============================================================================
+# AGGREGATOR ROUTER
+# ============================================================================
+
+class AggregatorRouter:
+    """
+    The Router (Aggregator Agent) that orchestrates specialist agents.
+    
+    Responsibilities:
+    1. Analyze user intent
+    2. Decompose into subtasks
+    3. Route to specialist agents
+    4. Execute in parallel
+    5. Merge results
+    6. Present unified response
+    """
+    
+    def __init__(self, llm = None):
+        self.llm = llm or LLMFactory.auto_detect()
+        self.agents: Dict[str, Any] = {}
+        self.decomposer = TaskDecomposer(llm=self.llm)
+        self.conversation_history: List[Dict] = []
+        
+        print("[OK] Aggregator Router initialized")
+    
+    def register_agent(self, name: str, agent: Any, description: Optional[str] = None):
+        """Register a new specialist agent."""
+        self.agents[name] = agent
+        
+        # Update decomposer's info
+        if description:
+            self.decomposer.agents_info[name] = description
+        elif hasattr(agent, 'specialty'):
+            self.decomposer.agents_info[name] = agent.specialty
+        elif hasattr(agent, 'metadata'):
+            self.decomposer.agents_info[name] = agent.metadata.get('specialty', 'Specialist agent')
+        else:
+            self.decomposer.agents_info[name] = "Specialist agent"
+        
+        print(f"  [OK] Registered agent: {name}")
+
+    async def _execute_subtask(self, subtask: Subtask) -> AgentResponse:
+        """Execute a single subtask with assigned agent."""
+        agent = self.agents.get(subtask.assigned_agent)
+        
+        if not agent:
+            return AgentResponse(
+                agent_name="Router",
+                subtask=subtask.description,
+                response=f"Error: Agent {subtask.assigned_agent} not available",
+                success=False
+            )
+        
+        # Support both SpecialistAgent (has handle method) and generic Agent (has run method)
+        if hasattr(agent, 'handle'):
+            return await agent.handle(subtask.description)
+        elif hasattr(agent, 'run'):
+            resp = await agent.run(subtask.description)
+            return AgentResponse(
+                agent_name=subtask.assigned_agent,
+                subtask=subtask.description,
+                response=resp,
+                success=True
+            )
+        else:
+            return AgentResponse(
+                agent_name=subtask.assigned_agent,
+                subtask=subtask.description,
+                response=f"Error: Agent {subtask.assigned_agent} is not compatible",
+                success=False
+            )
+    
+    async def _execute_parallel(self, subtasks: List[Subtask]) -> List[AgentResponse]:
+        """Execute multiple subtasks in parallel."""
+        print(f"\n  Executing {len(subtasks)} subtasks in parallel...")
+        
+        tasks = [self._execute_subtask(task) for task in subtasks]
+        responses = await asyncio.gather(*tasks)
+        
+        print(f"  [OK] All {len(responses)} agents completed")
+        return responses
+    
+    def _merge_responses(self, responses: List[AgentResponse], query: str) -> str:
+        """Merge multiple agent responses into unified answer."""
+        print(f"\n  Merging {len(responses)} responses using LLM...")
+        
+        successful = [r for r in responses if r.success]
+        if not successful:
+            return "I apologize, but I encountered errors processing your request."
+        
+        context = "\n\n".join([f"Agent: {r.agent_name}\nResponse: {r.response}" for r in successful])
+        
+        prompt = f"""You are the Multi-Agent Aggregator. Your goal is to combine specialist responses into a single, cohesive answer for the user.
+
+User original query: "{query}"
+
+Specialist Responses:
+{context}
+
+Respond as a single helpful assistant. Maintain the specific details provided by each specialist."""
+
+        return self.llm.complete(prompt)
+    
+    async def route(self, query: str) -> Dict[str, Any]:
+        """Main routing method."""
+        print(f"\n{'='*70}")
+        print(f"ROUTING REQUEST")
+        print('='*70)
+        
+        # Step 1: Decompose
+        subtasks = self.decomposer.decompose(query)
+        
+        # Step 2: Execute in parallel
+        responses = await self._execute_parallel(subtasks)
+        
+        # Step 3: Merge
+        final_response = self._merge_responses(responses, query)
+        
+        # Add to conversation history
+        self.conversation_history.append({
+            "query": query,
+            "subtasks": [{"desc": t.description, "agent": t.assigned_agent} for t in subtasks],
+            "responses": [{"agent": r.agent_name, "success": r.success} for r in responses]
+        })
+        
+        return {
+            "query": query,
+            "route": subtasks[0].assigned_agent if len(subtasks) == 1 else "multi",
+            "subtasks_count": len(subtasks),
+            "agents_used": list(set(r.agent_name for r in responses)),
+            "workers": list(set(r.agent_name for r in responses)),
+            "parallel": True,
+            "response": final_response,
+            "answer": final_response,
+            "metadata": {
+                "successful_tasks": sum(1 for r in responses if r.success),
+                "failed_tasks": sum(1 for r in responses if not r.success),
+                "total_tasks": len(responses)
+            }
+        }
+    
+    def get_stats(self) -> Dict:
+        """Get router statistics."""
+        return {
+            "total_requests": len(self.conversation_history),
+            "registered_agents": len(self.agents),
+            "average_subtasks": (
+                sum(len(h["subtasks"]) for h in self.conversation_history) / len(self.conversation_history)
+                if self.conversation_history else 0
+            )
+        }

kite/routing/llm_router.py

@@ -0,0 +1,149 @@
+"""
+LLM-based Router Implementation
+Uses LLM/SLM to classify user intent with reasoning.
+More accurate than embeddings but slower and more expensive.
+"""
+
+import json
+import asyncio
+from typing import Dict, List, Optional, Callable
+from dataclasses import dataclass, field
+
+@dataclass
+class LLMRoute:
+    name: str
+    description: str
+    handler: Callable
+
+class LLMRouter:
+    """
+    Routes user queries using LLM classification.
+    """
+    
+    def __init__(self, llm=None):
+        self.routes: Dict[str, LLMRoute] = {}
+        self.llm = llm
+        
+    def add_route(self, name: str, examples: List[str] | str = None, samples: List[str] | str = None, description: str = "", handler: Callable = None):
+        """Add a new route. Examples serve as context. 'samples' is an alias for 'examples'."""
+        final_examples = examples or samples
+        self.routes[name] = LLMRoute(
+            name=name,
+            description=description or f"Handle queries related to {name}",
+            handler=handler
+        )
+        print(f"[OK] Added LLM route: {name}")
+
+    async def route(self, query: str, context: Optional[Dict] = None) -> Dict:
+        """Route query to appropriate specialist agent using LLM."""
+        if not self.routes:
+            raise RuntimeError("No routes configured in LLMRouter")
+
+        # Prepare prompt
+        routes_desc = ""
+        for route in self.routes.values():
+            routes_desc += f"- {route.name}: {route.description}\n"
+
+        prompt = f"""Classify the user query into one of the following categories.
+Available Categories:
+{routes_desc}
+- none: Use this if the query doesn't fit any of the above.
+
+User Query: "{query}"
+
+Respond ONLY with a JSON object:
+{{"category": "category_name", "confidence": 0.0-1.0, "reasoning": "why?"}}"""
+
+        try:
+            # Use LLM for classification
+            response = await asyncio.to_thread(self.llm.complete, prompt, temperature=0.1)
+            
+            # Clean and parse JSON
+            content = response.strip()
+            if "```json" in content:
+                content = content.split("```json")[-1].split("```")[0].strip()
+            elif "```" in content:
+                content = content.split("```")[-1].split("```")[0].strip()
+            
+            # Robust JSON parsing with fallback
+            try:
+                # Try to find JSON in text
+                import re
+                json_match = re.search(r'\{[^}]+\}', content, re.DOTALL)
+                if json_match:
+                    content = json_match.group(0)
+                
+                data = json.loads(content)
+                category = data.get("category", "none")
+                confidence = data.get("confidence", 0.0)
+                reasoning = data.get("reasoning", "No reasoning")
+                
+            except (json.JSONDecodeError, AttributeError) as e:
+                # Fallback: keyword matching
+                print(f"[WARN] Router JSON parse failed creating fallback")
+                content_lower = response.lower()
+                category = "none"
+                confidence = 0.5
+                reasoning = "Fallback text classification"
+                
+                # Check for route keywords
+                for route_name in self.routes.keys():
+                    if route_name.replace("_", " ") in content_lower:
+                        category = route_name
+                        break
+            print(f"\n  LLM Intent Classification:")
+            print(f"   Query: {query}")
+            print(f"   Category: {category} (confidence: {confidence:.0%})")
+            print(f"   Reasoning: {reasoning}")
+
+            if category == "none" or category not in self.routes:
+                return {
+                    "route": "none",
+                    "confidence": confidence,
+                    "response": "I'm not sure how to help with that. Could you be more specific?",
+                    "needs_clarification": True
+                }
+
+            # Execute handler
+            route = self.routes[category]
+            print(f"[OK] Routing to {route.name}")
+            
+            # Use context if provided
+            try:
+                resp = route.handler(query, context)
+            except TypeError:
+                 # Fallback for handlers that don't accept context
+                resp = route.handler(query)
+
+            if asyncio.iscoroutine(resp):
+                resp = await resp
+            
+            # Extract response text
+            if isinstance(resp, dict) and 'response' in resp:
+                response_text = resp['response']
+            else:
+                response_text = str(resp)
+
+            return {
+                "route": route.name,
+                "confidence": confidence,
+                "response": response_text,
+                "needs_clarification": False
+            }
+
+        except Exception as e:
+            print(f"[ERROR] LLM Routing failed: {e}")
+            return {
+                "route": "error",
+                "confidence": 0,
+                "response": f"Routing error: {str(e)}",
+                "needs_clarification": False
+            }
+
+    def get_stats(self) -> Dict:
+        return {
+            "total_routes": len(self.routes),
+            "confidence_threshold": 0.0,
+            "cache_hit_rate": 0.0,
+            "type": "LLM"
+        }