RouteKitAI 0.1.0__py3-none-any.whl

routekitai/core/message.py

@@ -0,0 +1,132 @@
+"""Message primitive for RouteKit."""
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class MessageRole(str, Enum):
+    """Message role types."""
+
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+
+
+class Message(BaseModel):
+    """Canonical message schema for RouteKit."""
+
+    role: MessageRole = Field(..., description="Message role")
+    content: str = Field(..., description="Message content")
+    tool_calls: list[dict[str, Any]] | None = Field(
+        default=None, description="Tool calls made by the assistant"
+    )
+    tool_result: dict[str, Any] | None = Field(
+        default=None, description="Result from a tool call (for tool role messages)"
+    )
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+    @classmethod
+    def system(cls, content: str, **metadata: Any) -> "Message":
+        """Create a system message.
+
+        Args:
+            content: Message content
+            **metadata: Additional metadata
+
+        Returns:
+            System message
+        """
+        return cls(role=MessageRole.SYSTEM, content=content, metadata=metadata)
+
+    @classmethod
+    def user(cls, content: str, **metadata: Any) -> "Message":
+        """Create a user message.
+
+        Args:
+            content: Message content
+            **metadata: Additional metadata
+
+        Returns:
+            User message
+        """
+        return cls(role=MessageRole.USER, content=content, metadata=metadata)
+
+    @classmethod
+    def assistant(
+        cls,
+        content: str,
+        tool_calls: list[dict[str, Any]] | None = None,
+        **metadata: Any,
+    ) -> "Message":
+        """Create an assistant message.
+
+        Args:
+            content: Message content
+            tool_calls: Optional tool calls
+            **metadata: Additional metadata
+
+        Returns:
+            Assistant message
+        """
+        return cls(
+            role=MessageRole.ASSISTANT, content=content, tool_calls=tool_calls, metadata=metadata
+        )
+
+    @classmethod
+    def tool(cls, content: str, tool_result: dict[str, Any], **metadata: Any) -> "Message":
+        """Create a tool message.
+
+        Args:
+            content: Message content
+            tool_result: Tool execution result
+            **metadata: Additional metadata
+
+        Returns:
+            Tool message
+        """
+        return cls(
+            role=MessageRole.TOOL, content=content, tool_result=tool_result, metadata=metadata
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialize message to dictionary.
+
+        Returns:
+            Dictionary representation
+        """
+        return self.model_dump()
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Message":
+        """Deserialize message from dictionary.
+
+        Args:
+            data: Dictionary representation
+
+        Returns:
+            Message instance
+        """
+        return cls(**data)
+
+    def to_json(self) -> str:
+        """Serialize message to JSON string.
+
+        Returns:
+            JSON string representation
+        """
+        return self.model_dump_json()
+
+    @classmethod
+    def from_json(cls, json_str: str) -> "Message":
+        """Deserialize message from JSON string.
+
+        Args:
+            json_str: JSON string representation
+
+        Returns:
+            Message instance
+        """
+        return cls.model_validate_json(json_str)

routekitai/core/model.py

@@ -0,0 +1,91 @@
+"""Model primitive for RouteKit."""
+
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from routekitai.core.message import Message
+from routekitai.core.tool import Tool
+
+
+class Usage(BaseModel):
+    """Token usage and cost information."""
+
+    prompt_tokens: int = Field(default=0, description="Number of prompt tokens")
+    completion_tokens: int = Field(default=0, description="Number of completion tokens")
+    total_tokens: int = Field(default=0, description="Total number of tokens")
+    cost: float | None = Field(default=None, description="Estimated cost in USD")
+
+
+class ToolCall(BaseModel):
+    """Represents a tool call from the model."""
+
+    id: str = Field(..., description="Tool call ID")
+    name: str = Field(..., description="Tool name")
+    arguments: dict[str, Any] = Field(..., description="Tool arguments as dictionary")
+
+
+class ModelResponse(BaseModel):
+    """Standard response from a model."""
+
+    content: str = Field(..., description="Response content")
+    tool_calls: list[ToolCall] | None = Field(
+        default=None, description="Tool calls requested by the model"
+    )
+    usage: Usage | None = Field(default=None, description="Token usage information")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+
+class StreamEvent(BaseModel):
+    """Event emitted during streaming."""
+
+    type: str = Field(..., description="Event type")
+    content: str | None = Field(default=None, description="Content chunk")
+    tool_calls: list[ToolCall] | None = Field(default=None, description="Tool calls")
+    usage: Usage | None = Field(default=None, description="Usage information")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+
+class Model(ABC):
+    """Abstract base class for provider-agnostic model interface."""
+
+    @property
+    def name(self) -> str:
+        """Return the model name.
+
+        Returns:
+            Model name, defaults to class name if not set
+        """
+        # Check for _name attribute first (set by subclasses like FakeModel)
+        if hasattr(self, "_name"):
+            name_attr = self._name
+            if isinstance(name_attr, str):
+                return name_attr
+        # Fallback to class name
+        return str(self.__class__.__name__)
+
+    @abstractmethod
+    async def chat(
+        self,
+        messages: list[Message],
+        tools: list[Tool] | None = None,
+        stream: bool = False,
+        **kwargs: Any,
+    ) -> ModelResponse | AsyncIterator[StreamEvent]:
+        """Chat with the model.
+
+        Args:
+            messages: List of messages in the conversation
+            tools: Optional list of tools available to the model
+            stream: Whether to stream the response
+            **kwargs: Additional model-specific parameters
+
+        Returns:
+            ModelResponse if stream=False, AsyncIterator[StreamEvent] if stream=True
+
+        Raises:
+            ModelError: If the model operation fails
+        """
+        raise NotImplementedError("Subclasses must implement chat")

routekitai/core/policies.py

@@ -0,0 +1,373 @@
+"""Concrete policy implementations for RouteKit."""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from routekitai.core.agent import Agent
+from routekitai.core.message import Message, MessageRole
+from routekitai.core.model import ModelResponse
+from routekitai.core.policy import (
+    Action,
+    Final,
+    ModelAction,
+    Parallel,
+    Policy,
+    ToolAction,
+)
+from routekitai.core.runtime import Runtime
+from routekitai.graphs.graph import Graph
+
+
+class ReActPolicy(Policy):
+    """ReAct (Reasoning + Acting) policy.
+
+    Simple loop: model -> decide tool -> tool -> model -> final
+    """
+
+    max_iterations: int = 10
+
+    async def plan(self, state: dict[str, Any]) -> list[Action]:
+        """Plan next action in ReAct loop.
+
+        Args:
+            state: Current state with agent, messages, etc.
+
+        Returns:
+            List of actions (single action per step)
+        """
+        messages: list[Message] = state.get("messages", [])
+        iteration: int = state.get("iteration", 0)
+
+        if iteration >= self.max_iterations:
+            # Finalize with last message
+            if messages and messages[-1].role == MessageRole.ASSISTANT:
+                return [Final(output=messages[-1])]
+            return [Final(output=Message.assistant("Max iterations reached"))]
+
+        # If no messages or last message is not assistant, call model
+        if not messages or messages[-1].role != MessageRole.ASSISTANT:
+            return [ModelAction(messages=messages)]
+
+        # Check for tool calls in last message
+        last_message = messages[-1]
+        if last_message.tool_calls:
+            # Execute tool calls (can be parallel)
+            tool_actions: list[Action] = [
+                ToolAction(
+                    tool_name=tc["name"],
+                    tool_input=tc.get("arguments", {}),
+                )
+                for tc in last_message.tool_calls
+            ]
+            if len(tool_actions) > 1:
+                return [Parallel(actions=tool_actions)]
+            return tool_actions
+
+        # If assistant message with no tool calls, we're done
+        return [Final(output=last_message)]
+
+
+class FunctionCallingPolicy(Policy):
+    """Strict function calling policy.
+
+    Only allows tool calls that match available tool schemas.
+    No free-form tool names.
+    """
+
+    max_iterations: int = 10
+
+    async def plan(self, state: dict[str, Any]) -> list[Action]:
+        """Plan next action with strict function calling.
+
+        Args:
+            state: Current state
+
+        Returns:
+            List of actions
+        """
+        agent: Agent = state["agent"]
+        messages: list[Message] = state.get("messages", [])
+        iteration: int = state.get("iteration", 0)
+
+        if iteration >= self.max_iterations:
+            if messages and messages[-1].role == MessageRole.ASSISTANT:
+                return [Final(output=messages[-1])]
+            return [Final(output=Message.assistant("Max iterations reached"))]
+
+        # If no messages, start with model call
+        if not messages:
+            return [
+                ModelAction(messages=[], prompt="You are a helpful assistant with access to tools.")
+            ]
+
+        # If last message is not assistant, call model
+        if messages[-1].role != MessageRole.ASSISTANT:
+            return [ModelAction(messages=messages)]
+
+        # Check for tool calls
+        last_message = messages[-1]
+        if last_message.tool_calls:
+            # Validate tool calls against available tools
+            tool_names = {t.name for t in agent.tools}
+            valid_actions: list[Action] = []
+            for tc in last_message.tool_calls:
+                tool_name = tc["name"]
+                if tool_name not in tool_names:
+                    # Invalid tool name - skip
+                    continue
+                valid_actions.append(
+                    ToolAction(
+                        tool_name=tool_name,
+                        tool_input=tc.get("arguments", {}),
+                    )
+                )
+
+            if not valid_actions:
+                # No valid tools, finalize
+                return [Final(output=Message.assistant("No valid tools available"))]
+
+            if len(valid_actions) > 1:
+                return [Parallel(actions=valid_actions)]
+            return valid_actions
+
+        # Done
+        return [Final(output=last_message)]
+
+
+class GraphPolicy(Policy, BaseModel):
+    """Graph-based policy that delegates to graphs module execution."""
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    graph: Graph = Field(..., description="Graph to execute")
+    runtime: Runtime | None = Field(default=None, description="Runtime for graph execution")
+
+    async def plan(self, state: dict[str, Any]) -> list[Action]:
+        """Plan using graph execution.
+
+        Args:
+            state: Current state
+
+        Returns:
+            List of actions
+        """
+        from routekitai.graphs.executors import GraphExecutor
+
+        # Get runtime from state or use instance runtime
+        runtime = state.get("runtime") or self.runtime
+        if not runtime:
+            raise ValueError("GraphPolicy requires a Runtime instance")
+
+        # Create executor
+        executor = GraphExecutor(runtime=runtime, graph=self.graph)
+
+        # Extract input from state (prompt or messages)
+        messages = state.get("messages", [])
+        if messages:
+            # Get prompt from last user message
+            prompt = None
+            for msg in reversed(messages):
+                if hasattr(msg, "role") and msg.role.value == "user":
+                    prompt = msg.content if hasattr(msg, "content") else str(msg)
+                    break
+            input_data = {"prompt": prompt or ""}
+        else:
+            input_data = state.get("input_data", {})
+
+        # Execute graph
+        graph_result = await executor.execute(input_data=input_data)
+
+        # Return final output as result
+        final_output = graph_result.get("state", {}).get("output") or graph_result.get(
+            "state", {}
+        ).get("final_output", "Graph execution completed")
+        return [Final(output=Message.assistant(str(final_output)))]
+
+
+class PlanExecutePolicy(Policy):
+    """Plan-Execute policy: plan steps, then execute them."""
+
+    max_plan_steps: int = 10
+    max_iterations: int = 20
+
+    async def plan(self, state: dict[str, Any]) -> list[Action]:
+        """Plan execution steps.
+
+        Args:
+            state: Current state
+
+        Returns:
+            List of actions
+        """
+        messages: list[Message] = state.get("messages", [])
+        phase: str = state.get("phase", "planning")
+        iteration: int = state.get("iteration", 0)
+
+        if iteration >= self.max_iterations:
+            return [Final(output=Message.assistant("Max iterations reached"))]
+
+        if phase == "planning":
+            # Planning phase: ask model to create a plan
+            planning_prompt = (
+                "Create a step-by-step plan to solve this task. List the steps clearly."
+            )
+            if messages:
+                planning_prompt = f"{messages[0].content}\n\n{planning_prompt}"
+
+            return [ModelAction(messages=[Message.user(planning_prompt)])]
+
+        elif phase == "executing":
+            # Execution phase: execute planned steps
+            plan: list[str] = state.get("plan", [])
+            current_step: int = state.get("current_step", 0)
+
+            if current_step >= len(plan):
+                # All steps executed
+                return [Final(output=Message.assistant("Plan execution completed"))]
+
+            # Execute current step
+            step = plan[current_step]
+            return [ModelAction(messages=[Message.user(f"Execute step: {step}")])]
+
+        # Default: start planning
+        return [ModelAction(messages=messages)]
+
+    async def reflect(self, state: dict[str, Any], observation: dict[str, Any]) -> dict[str, Any]:
+        """Reflect and update state based on observation.
+
+        Args:
+            state: Current state
+            observation: Observation from last action
+
+        Returns:
+            Updated state
+        """
+        state = state.copy()
+        state.setdefault("observations", []).append(observation)
+        state["iteration"] = state.get("iteration", 0) + 1
+
+        # Extract plan from model response if in planning phase
+        if state.get("phase") == "planning" and "result" in observation:
+            result = observation["result"]
+            if isinstance(result, ModelResponse):
+                # Simple plan extraction (split by lines)
+                plan_lines = [
+                    line.strip()
+                    for line in result.content.split("\n")
+                    if line.strip() and line.strip()[0].isdigit()
+                ]
+                if plan_lines:
+                    state["plan"] = plan_lines
+                    state["phase"] = "executing"
+                    state["current_step"] = 0
+
+        # Update current step in execution phase
+        if state.get("phase") == "executing":
+            state["current_step"] = state.get("current_step", 0) + 1
+
+        return state
+
+
+class SupervisorPolicy(Policy, BaseModel):
+    """Supervisor policy for multi-agent coordination.
+
+    Supervisor delegates tasks to sub-agents with constrained toolsets and merges results.
+    """
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    sub_agents: dict[str, Agent] = Field(
+        default_factory=dict, description="Sub-agents available for delegation"
+    )
+    runtime: Any = Field(default=None, description="Runtime for executing sub-agents")
+    max_iterations: int = Field(default=20, description="Maximum iterations")
+    delegation_keywords: dict[str, list[str]] = Field(
+        default_factory=dict, description="Keywords to identify which agent to delegate to"
+    )
+
+    async def plan(self, state: dict[str, Any]) -> list[Action]:
+        """Plan using supervisor delegation.
+
+        Args:
+            state: Current state (should not be mutated directly)
+
+        Returns:
+            List of actions
+        """
+        messages: list[Message] = state.get("messages", [])
+        iteration: int = state.get("iteration", 0)
+        runtime: Runtime | None = state.get("runtime") or self.runtime
+
+        if iteration >= self.max_iterations:
+            return [Final(output=Message.assistant("Max iterations reached"))]
+
+        # Check if we're waiting for a sub-agent result
+        if state.get("waiting_for_subagent"):
+            # Sub-agent has completed, merge result
+            subagent_result = state.get("subagent_result")
+            if subagent_result:
+                # Create message with sub-agent result
+                result_message = Message.assistant(
+                    f"Sub-agent completed: {subagent_result.get('output', 'Task completed') if isinstance(subagent_result, dict) else str(subagent_result)}"
+                )
+                # Note: State mutations should be done via reflect(), not here
+                # But we need to signal completion, so we'll let the runtime handle it
+                # Supervisor processes the result
+                return [ModelAction(messages=[*messages, result_message])]
+
+        # If no messages, supervisor decides which agent to use
+        if not messages:
+            # Supervisor prompt to choose agent
+            agent_list = ", ".join(self.sub_agents.keys())
+            prompt = (
+                f"You are a supervisor coordinating multiple agents. "
+                f"Available agents: {agent_list}. "
+                f"Analyze the task and delegate to the appropriate agent. "
+                f"Respond with the agent name you want to delegate to."
+            )
+            return [ModelAction(messages=[Message.user(prompt)])]
+
+        # Check if supervisor has delegated
+        last_message = messages[-1]
+        if last_message.role == MessageRole.ASSISTANT and not state.get("delegated_agent"):
+            # Supervisor responded - check if it's a delegation
+            content = last_message.content.lower()
+            delegated_agent = None
+
+            # Check for explicit agent mentions
+            for agent_name, keywords in self.delegation_keywords.items():
+                if any(keyword.lower() in content for keyword in keywords):
+                    delegated_agent = agent_name
+                    break
+
+            # Fallback: check if agent name appears in content
+            if not delegated_agent:
+                for agent_name in self.sub_agents.keys():
+                    if agent_name.lower() in content:
+                        delegated_agent = agent_name
+                        break
+
+            if delegated_agent and delegated_agent in self.sub_agents:
+                # Delegate to sub-agent
+                state["delegated_agent"] = delegated_agent
+                state["waiting_for_subagent"] = True
+
+                # Extract task from original prompt
+                original_prompt = messages[0].content if messages else "Complete the task"
+
+                # Return a special action that will trigger sub-agent execution
+                # This is handled by the runtime adapter
+                return [
+                    ModelAction(
+                        messages=[Message.user(f"DELEGATE:{delegated_agent}:{original_prompt}")]
+                    )
+                ]
+
+        # Check if we need to execute sub-agent (handled by adapter)
+        if state.get("delegated_agent") and state.get("waiting_for_subagent") and runtime:
+            # This will be handled by the adapter
+            pass
+
+        # Default: continue with supervisor
+        return [ModelAction(messages=messages)]

routekitai/core/policy.py

@@ -0,0 +1,85 @@
+"""Policy system for routkitai agent execution."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from routekitai.core.message import Message
+
+
+class Action(BaseModel):
+    """Base class for execution actions."""
+
+    action_type: str = Field(..., description="Action type")
+
+
+class ModelAction(Action):
+    """Action to call the model."""
+
+    action_type: str = Field(default="model", description="Action type")
+    messages: list[Message] = Field(..., description="Messages to send to model")
+    prompt: str | None = Field(default=None, description="Optional prompt string")
+
+
+class ToolAction(Action):
+    """Action to execute a tool."""
+
+    action_type: str = Field(default="tool", description="Action type")
+    tool_name: str = Field(..., description="Tool name to execute")
+    tool_input: dict[str, Any] = Field(..., description="Tool input arguments")
+
+
+class Parallel(Action):
+    """Action to execute multiple tool actions in parallel."""
+
+    action_type: str = Field(default="parallel", description="Action type")
+    actions: list[Action] = Field(
+        ..., description="Actions to execute in parallel (typically ToolActions)"
+    )
+
+
+class Final(Action):
+    """Action to finalize execution with output."""
+
+    action_type: str = Field(default="final", description="Action type")
+    output: Message = Field(..., description="Final output message")
+
+
+class Policy(ABC):
+    """Policy interface for agent execution.
+
+    A policy determines what actions to take based on the current state.
+    """
+
+    @abstractmethod
+    async def plan(self, state: dict[str, Any]) -> list[Action]:
+        """Plan next actions based on current state.
+
+        Args:
+            state: Current execution state containing:
+                - agent: Agent instance
+                - messages: List of conversation messages
+                - tools: Available tools
+                - memory: Memory instance (if available)
+                - metadata: Additional state metadata
+
+        Returns:
+            List of actions to execute
+        """
+        raise NotImplementedError("Subclasses must implement plan")
+
+    async def reflect(self, state: dict[str, Any], observation: dict[str, Any]) -> dict[str, Any]:
+        """Reflect on observation and update state.
+
+        Args:
+            state: Current state
+            observation: Observation from last action (result, error, etc.)
+
+        Returns:
+            Updated state
+        """
+        # Default implementation: just merge observation into state
+        state = state.copy()
+        state.setdefault("observations", []).append(observation)
+        return state