kader 0.1.5__py3-none-any.whl → 1.0.0__py3-none-any.whl

kader/utils/context_aggregator.py

@@ -0,0 +1,347 @@
+"""
+Context Aggregator module for aggregating sub-agent checkpoint contexts.
+
+Aggregates checkpoint.md files from sub-agents into a unified context file
+in the main session's executors directory.
+"""
+
+from pathlib import Path
+
+from kader.memory.types import aread_text, awrite_text, get_default_memory_dir
+from kader.providers.base import Message
+from kader.providers.ollama import OllamaProvider
+
+AGGREGATOR_SYSTEM_PROMPT = """You are an assistant that aggregates and merges checkpoint summaries from multiple sub-agents.
+Given checkpoint summaries from different sub-agents, create a unified summary that combines all information.
+
+Your merged summary MUST include the following sections:
+
+## Directory Structure
+Merge all directory structures from sub-agents into a unified tree.
+Use a tree-like format:
+```
+project/
+├── src/
+│   └── main.py
+└── README.md
+```
+
+## Actions Performed
+Summarize the main accomplishments and significant actions taken by all sub-agents.
+Focus on high-level outcomes, not individual steps. For example:
+- "Implemented user authentication module with login/logout functionality"
+- "Fixed database connection issues and added retry logic"
+- "Created REST API endpoints for user management"
+
+Do NOT list every single action (like reading files, running commands, etc.).
+Only mention the meaningful outcomes and key decisions.
+
+If a section has no relevant content, write "None" under that section.
+
+IMPORTANT: Remove duplicates and merge similar items. Keep the summary organized and clean.
+"""
+
+
+class ContextAggregator:
+    """
+    Aggregates checkpoint contexts from sub-agents.
+
+    Reads checkpoint.md files from sub-agent directories and merges them
+    into a unified checkpoint.md in the executors directory.
+
+    Example:
+        aggregator = ContextAggregator(session_id="main-session-id")
+        md_path = aggregator.aggregate("/path/to/subagent/checkpoint.md")
+        print(f"Aggregated checkpoint saved to: {md_path}")
+    """
+
+    def __init__(
+        self,
+        session_id: str,
+        model: str = "gpt-oss:120b-cloud",
+        host: str | None = None,
+    ) -> None:
+        """
+        Initialize the ContextAggregator.
+
+        Args:
+            session_id: The main session ID for the executors directory
+            model: Ollama model identifier (default: "gpt-oss:120b-cloud")
+            host: Optional Ollama server host
+        """
+        self._session_id = session_id
+        self._provider = OllamaProvider(model=model, host=host)
+
+    def _get_executors_dir(self) -> Path:
+        """
+        Get the executors directory path for the main session.
+
+        Returns:
+            Path to ~/.kader/memory/sessions/<session-id>/executors/
+        """
+        return get_default_memory_dir() / "sessions" / self._session_id / "executors"
+
+    def _get_aggregated_checkpoint_path(self) -> Path:
+        """
+        Get the path for the aggregated checkpoint file.
+
+        Returns:
+            Path to the aggregated checkpoint.md in executors directory
+        """
+        return self._get_executors_dir() / "checkpoint.md"
+
+    def _load_existing_aggregated(self) -> str | None:
+        """
+        Load existing aggregated checkpoint if it exists.
+
+        Returns:
+            Content of existing aggregated checkpoint, or None if not exists
+        """
+        checkpoint_path = self._get_aggregated_checkpoint_path()
+        if checkpoint_path.exists():
+            try:
+                return checkpoint_path.read_text(encoding="utf-8")
+            except Exception:
+                return None
+        return None
+
+    async def _aload_existing_aggregated(self) -> str | None:
+        """
+        Asynchronously load existing aggregated checkpoint if it exists.
+
+        Returns:
+            Content of existing aggregated checkpoint, or None if not exists
+        """
+        checkpoint_path = self._get_aggregated_checkpoint_path()
+        if checkpoint_path.exists():
+            try:
+                return await aread_text(checkpoint_path)
+            except Exception:
+                return None
+        return None
+
+    def _load_subagent_checkpoint(self, checkpoint_path: str | Path) -> str | None:
+        """
+        Load a sub-agent's checkpoint content.
+
+        Args:
+            checkpoint_path: Path to the sub-agent's checkpoint.md file
+
+        Returns:
+            Content of the checkpoint file, or None if not found
+        """
+        checkpoint_path = self._get_executors_dir() / checkpoint_path
+        path = Path(checkpoint_path)
+        if path.exists():
+            try:
+                return path.read_text(encoding="utf-8")
+            except Exception:
+                return None
+        return None
+
+    async def _aload_subagent_checkpoint(
+        self, checkpoint_path: str | Path
+    ) -> str | None:
+        """
+        Asynchronously load a sub-agent's checkpoint content.
+
+        Args:
+            checkpoint_path: Path to the sub-agent's checkpoint.md file
+
+        Returns:
+            Content of the checkpoint file, or None if not found
+        """
+        full_path = self._get_executors_dir() / checkpoint_path
+        path = Path(full_path)
+        if path.exists():
+            try:
+                return await aread_text(path)
+            except Exception:
+                return None
+        return None
+
+    def _merge_checkpoints(
+        self,
+        existing_aggregated: str | None,
+        new_checkpoint: str,
+        subagent_name: str | None = None,
+    ) -> str:
+        """
+        Merge a new sub-agent checkpoint into the existing aggregated checkpoint.
+
+        Args:
+            existing_aggregated: Content of existing aggregated checkpoint
+            new_checkpoint: Content of the new sub-agent checkpoint
+            subagent_name: Optional name of the sub-agent for labeling
+
+        Returns:
+            Merged checkpoint content
+        """
+        # If no existing aggregated checkpoint, use the new checkpoint directly
+        if not existing_aggregated:
+            return new_checkpoint
+
+        user_prompt = f"""Here is the existing aggregated checkpoint from previous sub-agents:
+
+---
+{existing_aggregated}
+---
+
+Here is the new checkpoint from sub-agent{f' "{subagent_name}"' if subagent_name else ""}:
+
+---
+{new_checkpoint}
+---
+
+Merge the new checkpoint into the existing aggregated checkpoint.
+Combine items into the appropriate sections, remove duplicates, and keep everything organized."""
+
+        messages = [
+            Message.system(AGGREGATOR_SYSTEM_PROMPT),
+            Message.user(user_prompt),
+        ]
+
+        response = self._provider.invoke(messages)
+        return response.content
+
+    async def _amerge_checkpoints(
+        self,
+        existing_aggregated: str | None,
+        new_checkpoint: str,
+        subagent_name: str | None = None,
+    ) -> str:
+        """
+        Merge a new sub-agent checkpoint into the existing aggregated checkpoint (async).
+
+        Args:
+            existing_aggregated: Content of existing aggregated checkpoint
+            new_checkpoint: Content of the new sub-agent checkpoint
+            subagent_name: Optional name of the sub-agent for labeling
+
+        Returns:
+            Merged checkpoint content
+        """
+        # If no existing aggregated checkpoint, use the new checkpoint directly
+        if not existing_aggregated:
+            return new_checkpoint
+
+        user_prompt = f"""Here is the existing aggregated checkpoint from previous sub-agents:
+
+---
+{existing_aggregated}
+---
+
+Here is the new checkpoint from sub-agent{f' "{subagent_name}"' if subagent_name else ""}:
+
+---
+{new_checkpoint}
+---
+
+Merge the new checkpoint into the existing aggregated checkpoint.
+Combine items into the appropriate sections, remove duplicates, and keep everything organized."""
+
+        messages = [
+            Message.system(AGGREGATOR_SYSTEM_PROMPT),
+            Message.user(user_prompt),
+        ]
+
+        response = await self._provider.ainvoke(messages)
+        return response.content
+
+    def aggregate(
+        self, subagent_checkpoint_path: str, subagent_name: str | None = None
+    ) -> str:
+        """
+        Aggregate a sub-agent's checkpoint into the main executors checkpoint.
+
+        If checkpoint.md exists in the executors directory, it will be updated
+        with the new sub-agent's checkpoint. Otherwise, a new aggregated file is created.
+
+        Args:
+            subagent_checkpoint_path: Path to the sub-agent's checkpoint.md file
+            subagent_name: Optional name of the sub-agent for labeling in the summary
+
+        Returns:
+            Absolute path to the aggregated checkpoint file
+
+        Raises:
+            FileNotFoundError: If the sub-agent checkpoint file doesn't exist
+            ValueError: If the sub-agent checkpoint is empty
+        """
+        # Load the sub-agent's checkpoint
+        new_checkpoint = self._load_subagent_checkpoint(subagent_checkpoint_path)
+        if not new_checkpoint:
+            raise FileNotFoundError(
+                f"Sub-agent checkpoint not found: {subagent_checkpoint_path}"
+            )
+
+        if not new_checkpoint.strip():
+            raise ValueError(
+                f"Sub-agent checkpoint is empty: {subagent_checkpoint_path}"
+            )
+
+        # Load existing aggregated checkpoint if it exists
+        existing_aggregated = self._load_existing_aggregated()
+
+        # Merge the checkpoints
+        merged_content = self._merge_checkpoints(
+            existing_aggregated, new_checkpoint, subagent_name
+        )
+
+        # Ensure executors directory exists
+        aggregated_path = self._get_aggregated_checkpoint_path()
+        aggregated_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Save the aggregated checkpoint
+        aggregated_path.write_text(merged_content, encoding="utf-8")
+
+        return str(aggregated_path)
+
+    async def aaggregate(
+        self, subagent_checkpoint_path: str, subagent_name: str | None = None
+    ) -> str:
+        """
+        Aggregate a sub-agent's checkpoint into the main executors checkpoint (async).
+
+        If checkpoint.md exists in the executors directory, it will be updated
+        with the new sub-agent's checkpoint. Otherwise, a new aggregated file is created.
+
+        Args:
+            subagent_checkpoint_path: Path to the sub-agent's checkpoint.md file
+            subagent_name: Optional name of the sub-agent for labeling in the summary
+
+        Returns:
+            Absolute path to the aggregated checkpoint file
+
+        Raises:
+            FileNotFoundError: If the sub-agent checkpoint file doesn't exist
+            ValueError: If the sub-agent checkpoint is empty
+        """
+        # Load the sub-agent's checkpoint (async)
+        new_checkpoint = await self._aload_subagent_checkpoint(subagent_checkpoint_path)
+        if not new_checkpoint:
+            raise FileNotFoundError(
+                f"Sub-agent checkpoint not found: {subagent_checkpoint_path}"
+            )
+
+        if not new_checkpoint.strip():
+            raise ValueError(
+                f"Sub-agent checkpoint is empty: {subagent_checkpoint_path}"
+            )
+
+        # Load existing aggregated checkpoint if it exists (async)
+        existing_aggregated = await self._aload_existing_aggregated()
+
+        # Merge the checkpoints
+        merged_content = await self._amerge_checkpoints(
+            existing_aggregated, new_checkpoint, subagent_name
+        )
+
+        # Ensure executors directory exists
+        aggregated_path = self._get_aggregated_checkpoint_path()
+        aggregated_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Save the aggregated checkpoint (async)
+        await awrite_text(aggregated_path, merged_content)
+
+        return str(aggregated_path)

kader/workflows/__init__.py

@@ -0,0 +1,13 @@
+"""
+Kader Workflows Module.
+
+Provides workflow implementations for orchestrating agents in complex task flows.
+"""
+
+from kader.workflows.base import BaseWorkflow
+from kader.workflows.planner_executor import PlannerExecutorWorkflow
+
+__all__ = [
+    "BaseWorkflow",
+    "PlannerExecutorWorkflow",
+]

kader/workflows/base.py

@@ -0,0 +1,71 @@
+"""
+Base Workflow Class.
+
+Abstract base class for all workflow implementations.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+from kader.providers.base import BaseLLMProvider
+
+
+class BaseWorkflow(ABC):
+    """
+    Abstract base class for workflow implementations.
+
+    Workflows orchestrate multiple agents or agent interactions to accomplish
+    complex tasks. They provide a structured way to compose agent behaviors
+    and manage the flow of information between agents.
+
+    Subclasses must implement:
+    - run: Synchronous workflow execution
+    - arun: Asynchronous workflow execution
+    """
+
+    def __init__(
+        self,
+        name: str,
+        provider: Optional[BaseLLMProvider] = None,
+        model_name: str = "qwen3-coder:480b-cloud",
+        interrupt_before_tool: bool = True,
+    ) -> None:
+        """
+        Initialize the base workflow.
+
+        Args:
+            name: Name of the workflow instance.
+            provider: LLM provider for agents in the workflow.
+            model_name: Model to use if no provider specified.
+            interrupt_before_tool: Whether to pause before tool execution.
+        """
+        self.name = name
+        self.provider = provider
+        self.model_name = model_name
+        self.interrupt_before_tool = interrupt_before_tool
+
+    @abstractmethod
+    def run(self, task: str) -> str:
+        """
+        Execute the workflow synchronously.
+
+        Args:
+            task: The task or goal to accomplish.
+
+        Returns:
+            A summary of the workflow execution and results.
+        """
+        ...
+
+    @abstractmethod
+    async def arun(self, task: str) -> str:
+        """
+        Execute the workflow asynchronously.
+
+        Args:
+            task: The task or goal to accomplish.
+
+        Returns:
+            A summary of the workflow execution and results.
+        """
+        ...

kader/workflows/planner_executor.py

@@ -0,0 +1,251 @@
+"""
+Planner Executor Workflow.
+
+Orchestrates a PlanningAgent with TodoTool and AgentTool to break down tasks
+and delegate sub-tasks to executor agents.
+"""
+
+import uuid
+from typing import Callable, Optional, Tuple
+
+from kader.agent.agents import PlanningAgent
+from kader.memory import SlidingWindowConversationManager
+from kader.memory.types import get_default_memory_dir
+from kader.prompts import KaderPlannerPrompt
+from kader.providers.base import BaseLLMProvider, Message
+from kader.tools import AgentTool, TodoTool, ToolRegistry
+from kader.utils import Checkpointer
+
+from .base import BaseWorkflow
+
+
+class PlannerExecutorWorkflow(BaseWorkflow):
+    """
+    Planner-Executor Workflow using PlanningAgent with sub-agent delegation.
+
+    This workflow:
+    1. Accepts a user task
+    2. PlanningAgent creates a plan using TodoTool
+    3. For each sub-task, PlanningAgent can delegate to AgentTool (executor)
+    4. Executor outputs are added to planner's memory as assistant messages
+    5. PlanningAgent updates TodoTool status and continues until complete
+
+    Example:
+        workflow = PlannerExecutorWorkflow(name="project_workflow")
+        result = workflow.run("Create a Python project with README and tests")
+    """
+
+    def __init__(
+        self,
+        name: str,
+        provider: Optional[BaseLLMProvider] = None,
+        model_name: str = "qwen3-coder:480b-cloud",
+        interrupt_before_tool: bool = True,
+        tool_confirmation_callback: Optional[
+            Callable[..., Tuple[bool, Optional[str]]]
+        ] = None,
+        direct_execution_callback: Optional[Callable[..., None]] = None,
+        tool_execution_result_callback: Optional[Callable[..., None]] = None,
+        use_persistence: bool = False,
+        session_id: Optional[str] = None,
+        executor_names: Optional[list[str]] = None,
+    ) -> None:
+        """
+        Initialize the Planner-Executor workflow.
+
+        Args:
+            name: Name of the workflow instance.
+            provider: LLM provider for agents.
+            model_name: Model to use if no provider specified.
+            interrupt_before_tool: Whether to pause before tool execution.
+            tool_confirmation_callback: Callback for tool confirmation UI.
+            use_persistence: Enable session persistence.
+            session_id: Optional session ID to resume.
+            executor_names: Names for executor sub-agents (default: ["executor"]).
+        """
+        super().__init__(
+            name=name,
+            provider=provider,
+            model_name=model_name,
+            interrupt_before_tool=interrupt_before_tool,
+        )
+        self.tool_confirmation_callback = tool_confirmation_callback
+        self.direct_execution_callback = direct_execution_callback
+        self.tool_execution_result_callback = tool_execution_result_callback
+        self.use_persistence = use_persistence
+        self.session_id = session_id if session_id else str(uuid.uuid4())
+        self.executor_names = executor_names or ["executor"]
+
+        # Build the planner agent with tools
+        self._planner = self._build_planner()
+
+    def _load_checkpoint_context(self) -> Optional[str]:
+        """
+        Load checkpoint context from the session directory if it exists.
+
+        Returns:
+            The checkpoint markdown content if file exists, None otherwise.
+        """
+        if not self.session_id:
+            return None
+
+        checkpoint_path = (
+            get_default_memory_dir() / "sessions" / self.session_id / "checkpoint.md"
+        )
+
+        if checkpoint_path.exists():
+            try:
+                return checkpoint_path.read_text(encoding="utf-8")
+            except Exception:
+                return None
+
+        return None
+
+    def _build_planner(self) -> PlanningAgent:
+        """Build the PlanningAgent with TodoTool and AgentTool(s)."""
+        registry = ToolRegistry()
+
+        # TodoTool is added implicitly by PlanningAgent, but we ensure it's there
+        registry.register(TodoTool())
+
+        # Add AgentTool(s) for sub-task delegation
+        for executor_name in self.executor_names:
+            agent_tool = AgentTool(
+                name=executor_name,
+                description=(
+                    f"Delegate a sub-task to the '{executor_name}' agent. "
+                    "Use this when a specific task needs to be executed by a "
+                    "specialized worker agent. Provide a clear task description."
+                ),
+                provider=self.provider,
+                model_name=self.model_name,
+                interrupt_before_tool=self.interrupt_before_tool,
+                tool_confirmation_callback=self.tool_confirmation_callback,
+                direct_execution_callback=self.direct_execution_callback,
+                tool_execution_result_callback=self.tool_execution_result_callback,
+            )
+            registry.register(agent_tool)
+
+        # Create memory for the planner
+        memory = SlidingWindowConversationManager(window_size=20)
+
+        # Load checkpoint context if it exists from previous iterations
+        checkpoint_context = self._load_checkpoint_context()
+
+        # Create the Kader system prompt with tool descriptions and context
+        system_prompt = KaderPlannerPrompt(
+            tools=registry.tools,
+            context=checkpoint_context,
+        )
+
+        # Build the PlanningAgent
+        # Note: The planner itself runs without interruption (TodoTool, AgentTool execute directly)
+        # Sub-agents inside AgentTool can still have their own interrupt settings
+        planner = PlanningAgent(
+            name=f"{self.name}_planner",
+            tools=registry,
+            system_prompt=system_prompt,
+            provider=self.provider,
+            memory=memory,
+            model_name=self.model_name,
+            session_id=self.session_id,
+            use_persistence=self.use_persistence,
+            interrupt_before_tool=False,  # Planner executes TodoTool/AgentTool directly
+            tool_confirmation_callback=self.tool_confirmation_callback,
+            direct_execution_callback=self.direct_execution_callback,
+            tool_execution_result_callback=self.tool_execution_result_callback,
+        )
+
+        return planner
+
+    def _add_executor_output_to_memory(self, executor_name: str, output: str) -> None:
+        """
+        Add executor agent output to planner's memory as assistant message.
+
+        Args:
+            executor_name: Name of the executor that produced the output.
+            output: The output/result from the executor.
+        """
+        # Format the executor output as an assistant message
+        formatted_output = f"[{executor_name} completed]: {output}"
+        self._planner.memory.add_message(Message.assistant(formatted_output))
+
+    def _create_checkpoint(self) -> Optional[str]:
+        """
+        Create a checkpoint of the current session using the Checkpointer.
+
+        Returns:
+            Path to the checkpoint file if created, None otherwise.
+        """
+        if not self.session_id or not self.use_persistence:
+            return None
+
+        try:
+            checkpointer = Checkpointer()
+            memory_path = f"{self.session_id}/conversation.json"
+            checkpoint_path = checkpointer.generate_checkpoint(memory_path)
+            return checkpoint_path
+        except Exception:
+            # Silently fail if checkpointing fails - don't interrupt workflow
+            return None
+
+    def run(self, task: str) -> str:
+        """
+        Execute the planner-executor workflow synchronously.
+
+        Args:
+            task: The main task to accomplish.
+
+        Returns:
+            Final response from the planner summarizing completed work.
+        """
+        # Invoke the planner with the task
+        # The PlanningAgent will:
+        # 1. Create a plan using TodoTool
+        # 2. Delegate sub-tasks using AgentTool when needed
+        # 3. Update todo status as tasks complete
+        # 4. Continue until all tasks are done
+
+        response = self._planner.invoke(task)
+
+        # Create checkpoint after execution completes
+        self._create_checkpoint()
+
+        # Extract content from response
+        if hasattr(response, "content"):
+            return str(response.content)
+        elif isinstance(response, dict):
+            return str(response.get("content", str(response)))
+        else:
+            return str(response)
+
+    async def arun(self, task: str) -> str:
+        """
+        Execute the planner-executor workflow asynchronously.
+
+        Args:
+            task: The main task to accomplish.
+
+        Returns:
+            Final response from the planner summarizing completed work.
+        """
+        response = await self._planner.ainvoke(task)
+
+        # Create checkpoint after execution completes
+        self._create_checkpoint()
+
+        if hasattr(response, "content"):
+            return str(response.content)
+        elif isinstance(response, dict):
+            return str(response.get("content", str(response)))
+        else:
+            return str(response)
+
+    @property
+    def planner(self) -> PlanningAgent:
+        """Get the underlying PlanningAgent instance."""
+        return self._planner
+
+    def reset(self) -> None:
+        """Reset the workflow by rebuilding the planner with fresh memory."""
+        self._planner = self._build_planner()