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

kader/prompts/templates/executor_agent.j2

@@ -0,0 +1,70 @@
+You are Kader, an Executor Agent specialized in deep and complex tasks.
+
+You excel at:
+- Writing high-quality code and implementing features
+- Deep research and comprehensive analysis
+- Complex problem-solving and debugging
+- Thorough documentation and testing
+
+You have access to the following tools:
+
+{% for tool in tools %}
+{{ tool.name }}: {{ tool.description }}
+{% endfor %}
+
+## Your Objective
+
+Complete the assigned task safely and thoroughly. Think carefully before each action.
+
+## Execution Process
+
+1. **Analyze the Task**: Before taking any action, carefully think about:
+   - What exactly needs to be done
+   - What could go wrong and how to prevent it
+   - The safest approach to complete the task
+
+2. **Plan Your Steps**: Create a mental action plan before executing
+
+3. **Execute Safely**: For each action:
+   - Think about potential side effects
+   - Verify inputs before executing
+   - Handle errors gracefully
+
+4. **Track Your Work**: Keep track of:
+   - Files created or modified
+   - Commands executed
+   - Any issues encountered
+
+## Response Format
+
+Use the following format for reasoning:
+
+Thought: Analyze what needs to be done and plan the approach
+Action: the action to take, should be one of [{{ tool_names }}]
+Action Input: the input to the action
+Observation: the result of the action
+... (this Thought/Action/Action Input/Observation can repeat N times)
+Thought: I have completed the task
+Final Answer: [Your detailed execution report]
+
+## CRITICAL: Final Answer Requirements
+
+Your Final Answer MUST include a structured execution report with:
+
+### What Has Been Done
+- List each action completed with details
+
+### Files Created/Modified
+- Full path and purpose of each file
+- If no files: state "No files were created or modified"
+
+### Execution Summary
+- Brief summary of the overall execution
+- Whether the task was completed successfully
+
+### Issues/Notes
+- Any errors encountered and how they were resolved
+- Any warnings or important notes for the caller
+- If no issues: state "No issues encountered"
+
+Begin!

kader/prompts/templates/kader_planner.j2

@@ -0,0 +1,71 @@
+You are Kader, an intelligent planning agent. You have access to the following tools:
+
+{% for tool in tools %}
+{{ tool.name }}: {{ tool.description }}
+{% endfor %}
+
+{% if context %}
+## Previous Context (What Has Been Done)
+
+The following summarizes what has been accomplished in previous rounds. Consider this context when planning your next steps to avoid repeating completed work:
+
+{{ context }}
+
+{% endif %}
+Your goal is to complete the user's request by creating a plan and executing it step-by-step.
+
+## Core Instructions
+
+1. Break down the user request into logical steps.
+2. For each step, determine if a tool is needed.
+3. Execute necessary tools.
+4. CRITICAL: Always create a TODO using the TODO Tool for the plan.
+5. CRITICAL: Follow the instructions of the TODO list strictly. The current item in the TODO list is your PRIMARY instruction.
+6. CRITICAL: After completing a step (e.g., creating a file, running a test), you MUST immediately use the TODO Tool to update the status of that item to 'completed'. Do not proceed to the next item without updating the TODO list.
+7. If you have enough information, provide the final answer.
+
+## Using Agent as a Tool
+
+When delegating tasks to sub-agents using the Agent Tool, follow these guidelines:
+
+### Task Parameter
+- **Primary Instruction**: This MUST come directly from the current item in your TODO list (e.g., "Implement unit tests", "Create database schema").
+- **Secondary Instructions (Objectives)**: These are the supporting details or objectives for the sub-agent (e.g., "View the code to understand the context", "Ensure 100% coverage").
+- **Structure**:
+  - Start with the Primary Instruction.
+  - Follow with "Objectives:" listing the Secondary Instructions.
+- **Example**:
+  - If the TODO item is "Implement feature X", and you need the agent to also read the docs:
+    - Task: "Implement feature X. Objectives: 1. Read documentation at doc/feature.md. 2. Verify implementation with tests."
+- **REQUIRED**: Include instruction that the agent MUST return:
+  - What has been done (actions completed)
+  - What files have been written or modified (if any)
+  - A summary of the execution
+  - Any issues or errors that occurred during execution
+
+### Context Parameter (REQUIRED)
+The context parameter MUST include:
+1. **Brief about latest actions**: Summarize what has been done so far and the current state
+2. **Completed actions to avoid repetition**: List actions that were successfully completed so the sub-agent does NOT repeat them
+
+Example Agent Tool usage:
+```
+task: "Create unit tests for the user authentication module"
+context: "We are building a user management system. So far, the User model and AuthService have been implemented in src/auth/. Completed actions: 1) Created User model with email/password fields, 2) Implemented AuthService with login/register methods, 3) Set up pytest configuration. Do NOT recreate these files."
+```
+
+## Example Planning Flow
+
+Task: Implement a ML Inference Endpoint
+
+Plan:
+1. Analyze the requirements and design the system architecture
+2. Implement the endpoint using a web framework
+3. Test the endpoint to ensure it works as expected
+4. Deploy the endpoint to a production environment
+
+When executing this plan:
+- Create the TODO list first
+- For each step, consider if delegation to an Agent Tool is appropriate
+- Update TODO status after completing each step
+- Provide context to sub-agents about completed work

kader/providers/ollama.py

@@ -433,11 +433,11 @@ class OllamaProvider(BaseLLMProvider):
             models_config = {}
             for model in models:
                 models_config[model] = client.show(model)
+            accepted_capabilities = ["completion", "tools"]
             return [
                 model
                 for model, config in models_config.items()
-                if config.capabilities
-                in [["completion", "tools", "thinking"], ["completion", "tools"]]
+                if set(accepted_capabilities).issubset(set(config.capabilities))
             ]
         except Exception:
             return []

kader/tools/__init__.py

@@ -9,6 +9,7 @@ from kader.tools.exec_commands import (
     CommandExecutorTool,
 )
 
+from .agent import AgentTool
 from .base import (
     # Core classes
     BaseTool,
@@ -84,6 +85,28 @@ def get_default_registry() -> ToolRegistry:
     return registry
 
 
+# Module-level cached registry singleton
+_cached_default_registry: ToolRegistry | None = None
+
+
+def get_cached_default_registry() -> ToolRegistry:
+    """
+    Get a cached registry populated with all standard tools.
+
+    This is more efficient than get_default_registry() when called multiple times,
+    as it avoids repeated tool instantiation and registration.
+
+    The cached registry is created once and reused for all subsequent calls.
+
+    Returns:
+        Cached ToolRegistry with all standard tools registered.
+    """
+    global _cached_default_registry
+    if _cached_default_registry is None:
+        _cached_default_registry = get_default_registry()
+    return _cached_default_registry
+
+
 __all__ = [
     # Core classes
     "BaseTool",
@@ -125,6 +148,9 @@ __all__ = [
     "CommandExecutorTool",
     # Todo Tool
     "TodoTool",
+    # Agent Tool
+    "AgentTool",
     # Helpers
     "get_default_registry",
+    "get_cached_default_registry",
 ]

kader/tools/agent.py

@@ -0,0 +1,452 @@
+"""
+Agent Tool - Use a ReActAgent as a callable tool.
+
+Allows spawning sub-agents to execute specific tasks with isolated memory contexts.
+"""
+
+import uuid
+from pathlib import Path
+from typing import Any, Callable, Optional, Tuple
+
+from kader.memory import SlidingWindowConversationManager
+from kader.memory.types import aread_text, save_json
+from kader.prompts import ExecutorAgentPrompt
+from kader.providers.base import BaseLLMProvider, Message
+from kader.utils import Checkpointer, ContextAggregator
+
+from .base import BaseTool, ParameterSchema, ToolCategory
+
+
+class PersistentSlidingWindowConversationManager(SlidingWindowConversationManager):
+    """
+    SlidingWindowConversationManager with JSON persistence.
+
+    Saves the entire message history (dict format) to a JSON file
+    after every add_message(s) call.
+    """
+
+    def __init__(self, file_path: Path, window_size: int = 20) -> None:
+        """
+        Initialize with a file path for persistence.
+        """
+        super().__init__(window_size=window_size)
+        self.file_path = file_path
+
+    def _save(self) -> None:
+        """Save entire history to JSON."""
+        try:
+            # We want to save plain dicts
+            messages_dicts = [msg.message for msg in self._messages]
+            data = {"messages": messages_dicts}
+            # Ensure parent temp-directory exists is done by caller usually,
+            # but best effort here:
+            self.file_path.parent.mkdir(parents=True, exist_ok=True)
+            save_json(self.file_path, data)
+        except Exception:
+            # Best effort save
+            pass
+
+    def add_message(self, message: Any) -> Any:
+        # Call super
+        result = super().add_message(message)
+        # Save
+        self._save()
+        return result
+
+    def add_messages(self, messages: list[Any]) -> list[Any]:
+        # Call super
+        result = super().add_messages(messages)
+        # Save
+        self._save()
+        return result
+
+
+class AgentTool(BaseTool[str]):
+    """
+    Tool that spawns a ReActAgent to execute a specific task.
+
+    Creates an agent with its own memory context and default tools
+    (filesystem, web, command executor) to complete the given task.
+
+    When `interrupt_before_tool=True`, the agent will pause before each tool
+    execution and use the `tool_confirmation_callback` to get user confirmation.
+
+    Example:
+        # Autonomous execution (no interrupts)
+        tool = AgentTool(name="research_agent", interrupt_before_tool=False)
+        result = tool.execute(task="Find the current stock price of AAPL")
+
+        # Interactive execution with tool confirmation
+        def my_callback(tool_info: str) -> Tuple[bool, Optional[str]]:
+            user_input = input(f"Execute {tool_info}? [y/n]: ")
+            return (user_input.lower() == 'y', None)
+
+        tool = AgentTool(
+            name="research_agent",
+            interrupt_before_tool=True,
+            tool_confirmation_callback=my_callback
+        )
+        result = tool.execute(task="Find info about topic X")
+    """
+
+    def __init__(
+        self,
+        name: str,
+        description: str = "Execute a specific task using an AI agent",
+        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,
+    ) -> None:
+        """
+        Initialize the AgentTool.
+
+        Args:
+            name: Name of the agent tool (used as identifier).
+            description: Description of what this agent does.
+            provider: Optional LLM provider (uses OllamaProvider by default).
+            model_name: Model to use for the agent.
+            interrupt_before_tool: If True, pause before tool execution for user
+                confirmation. The task will only complete when the agent returns
+                its final response.
+            tool_confirmation_callback: Callback function for tool confirmation.
+                Should return (should_execute: bool, additional_context: Optional[str]).
+                If not provided and interrupt_before_tool=True, uses stdin prompts.
+        """
+        super().__init__(
+            name=name,
+            description=description,
+            parameters=[
+                ParameterSchema(
+                    name="task",
+                    type="string",
+                    description="The specific task for the agent to execute",
+                    required=True,
+                ),
+                ParameterSchema(
+                    name="context",
+                    type="string",
+                    description="Context to provide to the agent before executing the task",
+                    required=True,
+                ),
+            ],
+            category=ToolCategory.UTILITY,
+        )
+        self._provider = provider
+        self._model_name = model_name
+        self._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
+
+    def _load_aggregated_context(self, main_session_id: str) -> str | None:
+        """
+        Load the aggregated checkpoint from executors directory if it exists.
+
+        Args:
+            main_session_id: The main session ID
+
+        Returns:
+            Content of the aggregated checkpoint, or None if not found
+        """
+        if main_session_id == "standalone":
+            return None
+
+        home = Path.home()
+        aggregated_path = (
+            home
+            / ".kader"
+            / "memory"
+            / "sessions"
+            / main_session_id
+            / "executors"
+            / "checkpoint.md"
+        )
+
+        if aggregated_path.exists():
+            try:
+                return aggregated_path.read_text(encoding="utf-8")
+            except Exception:
+                return None
+        return None
+
+    async def _aload_aggregated_context(self, main_session_id: str) -> str | None:
+        """
+        Asynchronously load the aggregated checkpoint from executors directory.
+
+        Args:
+            main_session_id: The main session ID
+
+        Returns:
+            Content of the aggregated checkpoint, or None if not found
+        """
+        if main_session_id == "standalone":
+            return None
+
+        home = Path.home()
+        aggregated_path = (
+            home
+            / ".kader"
+            / "memory"
+            / "sessions"
+            / main_session_id
+            / "executors"
+            / "checkpoint.md"
+        )
+
+        if aggregated_path.exists():
+            try:
+                return await aread_text(aggregated_path)
+            except Exception:
+                return None
+        return None
+
+    def execute(self, task: str, context: str) -> str:
+        """
+        Execute a task using a ReActAgent with isolated memory.
+
+        When interrupt_before_tool is True, the agent will pause before each tool
+        execution for user confirmation. The task only ends when the agent returns
+        its final response.
+
+        Args:
+            task: The task to execute.
+            context: Context to add to memory before the task.
+
+        Returns:
+            A summary of what the agent accomplished.
+        """
+        # Import here to avoid circular imports
+        from kader.agent.agents import ReActAgent
+
+        # Create a fresh memory manager for isolated context
+        # Persistence: ~/.kader/memory/sessions/<main-session-id>/executors/<agent-name>-<id>.json
+        execution_id = str(uuid.uuid4())
+        # Use propagated session ID or 'standalone' if not set
+        main_session_id = self._session_id if self._session_id else "standalone"
+
+        home = Path.home()
+        memory_dir = (
+            home
+            / ".kader"
+            / "memory"
+            / "sessions"
+            / main_session_id
+            / "executors"
+            / f"{self.name}-{execution_id}"
+        )
+        memory_file = memory_dir / "conversation.json"
+
+        memory = PersistentSlidingWindowConversationManager(
+            file_path=memory_file, window_size=20
+        )
+
+        # Load aggregated context from previous executors
+        aggregated_context = self._load_aggregated_context(main_session_id)
+        if aggregated_context:
+            full_context = f"## Previous Executor Context\n{aggregated_context}\n\n## Current Task Context\n{context}"
+        else:
+            full_context = context
+
+        # Add context to memory as user message
+        memory.add_message(Message.user(full_context))
+
+        # Get default tools (filesystem, web, command executor) - use cached version
+        from kader.tools import get_cached_default_registry
+
+        tools = get_cached_default_registry()
+
+        # Create ExecutorAgentPrompt with tool descriptions
+        system_prompt = ExecutorAgentPrompt(tools=tools.tools)
+
+        # Create the ReActAgent with separate memory and executor prompt
+        agent = ReActAgent(
+            name=f"{self.name}_worker",
+            tools=tools,
+            system_prompt=system_prompt,
+            provider=self._provider,
+            memory=memory,
+            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,
+        )
+
+        try:
+            # Invoke the agent with the task
+            # The agent will handle tool interruptions internally
+            response = agent.invoke(task)
+
+            # Generate checkpoint and aggregate it
+            try:
+                checkpointer = Checkpointer()
+                checkpoint_path = checkpointer.generate_checkpoint(str(memory_file))
+                checkpoint_content = Path(checkpoint_path).read_text(encoding="utf-8")
+
+                # Aggregate the checkpoint into the main executors checkpoint
+                if main_session_id != "standalone":
+                    aggregator = ContextAggregator(session_id=main_session_id)
+                    # Use relative path from executors directory
+                    relative_path = f"{self.name}-{execution_id}/checkpoint.md"
+                    aggregator.aggregate(relative_path, subagent_name=self.name)
+
+                # Append the agent's response to the checkpoint content if it exists
+                response_content = None
+                if hasattr(response, "content"):
+                    response_content = str(response.content)
+                elif isinstance(response, dict):
+                    response_content = str(response.get("content", str(response)))
+                else:
+                    response_content = str(response)
+
+                if response_content and response_content != "None":
+                    checkpoint_content += f"\n\nResponse:\n{response_content}"
+
+                return checkpoint_content
+            except Exception:
+                # Fallback to raw response if checkpointing fails
+                if hasattr(response, "content"):
+                    return str(response.content)
+                elif isinstance(response, dict):
+                    return str(response.get("content", str(response)))
+                else:
+                    return str(response)
+
+        except Exception as e:
+            return f"Agent execution failed: {str(e)}"
+
+    async def aexecute(self, task: str, context: str) -> str:
+        """
+        Asynchronously execute a task using a ReActAgent.
+
+        When interrupt_before_tool is True, the agent will pause before each tool
+        execution for user confirmation. The task only ends when the agent returns
+        its final response.
+
+        Args:
+            task: The task to execute.
+            context: Context to add to memory before the task.
+
+        Returns:
+            A summary of what the agent accomplished.
+        """
+        # Import here to avoid circular imports
+        from kader.agent.agents import ReActAgent
+
+        # Create a fresh memory manager for isolated context
+        # Persistence: ~/.kader/memory/sessions/<main-session-id>/executors/<agent-name>-<id>.json
+        execution_id = str(uuid.uuid4())
+        # Use propagated session ID or 'standalone' if not set
+        main_session_id = self._session_id if self._session_id else "standalone"
+
+        home = Path.home()
+        memory_dir = (
+            home
+            / ".kader"
+            / "memory"
+            / "sessions"
+            / main_session_id
+            / "executors"
+            / f"{self.name}-{execution_id}"
+        )
+        memory_file = memory_dir / "conversation.json"
+
+        memory = PersistentSlidingWindowConversationManager(
+            file_path=memory_file, window_size=20
+        )
+
+        # Load aggregated context from previous executors (async)
+        aggregated_context = await self._aload_aggregated_context(main_session_id)
+        if aggregated_context:
+            full_context = f"## Previous Executor Context\n{aggregated_context}\n\n## Current Task Context\n{context}"
+        else:
+            full_context = context
+
+        # Add context to memory as user message
+        memory.add_message(Message.user(full_context))
+
+        # Get default tools (filesystem, web, command executor) - use cached version
+        from kader.tools import get_cached_default_registry
+
+        tools = get_cached_default_registry()
+
+        # Create ExecutorAgentPrompt with tool descriptions
+        system_prompt = ExecutorAgentPrompt(tools=tools.tools)
+
+        # Create the ReActAgent with separate memory and executor prompt
+        agent = ReActAgent(
+            name=f"{self.name}_worker",
+            tools=tools,
+            system_prompt=system_prompt,
+            provider=self._provider,
+            memory=memory,
+            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,
+        )
+
+        try:
+            # Invoke the agent asynchronously
+            # The agent will handle tool interruptions internally
+            response = await agent.ainvoke(task)
+
+            # Generate checkpoint and aggregate it
+            try:
+                checkpointer = Checkpointer()
+                checkpoint_path = await checkpointer.agenerate_checkpoint(
+                    str(memory_file)
+                )
+                checkpoint_content = await aread_text(Path(checkpoint_path))
+
+                # Aggregate the checkpoint into the main executors checkpoint
+                if main_session_id != "standalone":
+                    aggregator = ContextAggregator(session_id=main_session_id)
+                    # Use relative path from executors directory
+                    relative_path = f"{self.name}-{execution_id}/checkpoint.md"
+                    await aggregator.aaggregate(relative_path, subagent_name=self.name)
+
+                # Append the agent's response to the checkpoint content if it exists
+                response_content = None
+                if hasattr(response, "content"):
+                    response_content = str(response.content)
+                elif isinstance(response, dict):
+                    response_content = str(response.get("content", str(response)))
+                else:
+                    response_content = str(response)
+
+                if response_content and response_content != "None":
+                    checkpoint_content += f"\n\nResponse:\n{response_content}"
+
+                return checkpoint_content
+            except Exception:
+                # Fallback to raw response if checkpointing fails
+                if hasattr(response, "content"):
+                    return str(response.content)
+                elif isinstance(response, dict):
+                    return str(response.get("content", str(response)))
+                else:
+                    return str(response)
+
+        except Exception as e:
+            return f"Agent execution failed: {str(e)}"
+
+    def get_interruption_message(self, task: str, **kwargs: Any) -> str:
+        """
+        Get a message describing the agent action for user confirmation.
+
+        Args:
+            task: The task the agent will execute.
+
+        Returns:
+            A formatted string describing the action.
+        """
+        # Truncate long tasks for readability
+        task_preview = task[:100] + "..." if len(task) > 100 else task
+        return f"execute {self.name}: {task_preview}"

kader/tools/filesys.py

@@ -646,5 +646,5 @@ def get_filesystem_tools(
         EditFileTool(bp, virtual_mode),
         GrepTool(bp, virtual_mode),
         GlobTool(bp, virtual_mode),
-        SearchInDirectoryTool(bp),
+        # SearchInDirectoryTool(bp), #TODO: remove search in directory from file system tools
     ]