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

kader/agent/base.py

@@ -48,11 +48,15 @@ class BaseAgent:
         provider: Optional[BaseLLMProvider] = None,
         memory: Optional[ConversationManager] = None,
         retry_attempts: int = 3,
+        retry_wait_min: int = 1,
+        retry_wait_max: int = 5,
         model_name: str = "qwen3-coder:480b-cloud",
         session_id: Optional[str] = None,
         use_persistence: bool = False,
         interrupt_before_tool: bool = True,
         tool_confirmation_callback: Optional[callable] = None,
+        direct_execution_callback: Optional[callable] = None,
+        tool_execution_result_callback: Optional[callable] = None,
     ) -> None:
         """
         Initialize the Base Agent.
@@ -75,8 +79,12 @@ class BaseAgent:
         self.name = name
         self.system_prompt = system_prompt
         self.retry_attempts = retry_attempts
+        self.retry_wait_min = retry_wait_min
+        self.retry_wait_max = retry_wait_max
         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
 
         # Persistence Configuration
         self.session_id = session_id
@@ -339,6 +347,31 @@ class BaseAgent:
         if llm_content and len(llm_content) > 0:
             display_str = f"{llm_content}\n\n{display_str}"
 
+        # Extract tool name for direct execution check
+        fn_info = tool_call_dict.get("function", {})
+        if not fn_info and "name" in tool_call_dict:
+            fn_info = tool_call_dict
+        tool_name = fn_info.get("name", "")
+
+        # List of tools to execute directly (show message but don't ask for confirmation)
+        direct_execution_tools = {
+            "read_file",
+            "glob",
+            "grep",
+            "read_directory",
+            "read_dir",
+        }
+
+        # Direct execution for specific tools - applies regardless of callback
+        if tool_name in direct_execution_tools:
+            # Notify via direct_execution_callback if available (for CLI/TUI display)
+            if self.direct_execution_callback:
+                self.direct_execution_callback(display_str, tool_name)
+            else:
+                # Fallback: print to console
+                print(display_str)
+            return True, None
+
         # Use callback if provided (e.g., for GUI/TUI)
         if self.tool_confirmation_callback:
             return self.tool_confirmation_callback(display_str)
@@ -435,6 +468,18 @@ class BaseAgent:
                 # Execute tool
                 tool_result = self._tool_registry.run(tool_call)
 
+                # Notify about tool execution result if callback available
+                if self.tool_execution_result_callback:
+                    # Handle both enum and string status
+                    status = tool_result.status
+                    status_value = (
+                        status.value if hasattr(status, "value") else str(status)
+                    )
+                    success = status_value == "success"
+                    self.tool_execution_result_callback(
+                        tool_call.name, success, tool_result.content
+                    )
+
                 # add result to memory
                 # But here we just return messages, caller handles memory add
                 tool_msg = Message.tool(
@@ -482,6 +527,18 @@ class BaseAgent:
                 # Execute tool async
                 tool_result = await self._tool_registry.arun(tool_call)
 
+                # Notify about tool execution result if callback available
+                if self.tool_execution_result_callback:
+                    # Handle both enum and string status
+                    status = tool_result.status
+                    status_value = (
+                        status.value if hasattr(status, "value") else str(status)
+                    )
+                    success = status_value == "success"
+                    self.tool_execution_result_callback(
+                        tool_call.name, success, tool_result.content
+                    )
+
                 tool_msg = Message.tool(
                     tool_call_id=tool_result.tool_call_id, content=tool_result.content
                 )
@@ -509,7 +566,9 @@ class BaseAgent:
 
         runner = Retrying(
             stop=stop_after_attempt(self.retry_attempts),
-            wait=wait_exponential(multiplier=1, min=4, max=10),
+            wait=wait_exponential(
+                multiplier=1, min=self.retry_wait_min, max=self.retry_wait_max
+            ),
             reraise=True,
         )
 
@@ -652,7 +711,9 @@ class BaseAgent:
 
         runner = Retrying(
             stop=stop_after_attempt(self.retry_attempts),
-            wait=wait_exponential(multiplier=1, min=4, max=10),
+            wait=wait_exponential(
+                multiplier=1, min=self.retry_wait_min, max=self.retry_wait_max
+            ),
             reraise=True,
         )
 
@@ -689,7 +750,9 @@ class BaseAgent:
 
         runner = AsyncRetrying(
             stop=stop_after_attempt(self.retry_attempts),
-            wait=wait_exponential(multiplier=1, min=4, max=10),
+            wait=wait_exponential(
+                multiplier=1, min=self.retry_wait_min, max=self.retry_wait_max
+            ),
             reraise=True,
         )
 
@@ -905,9 +968,9 @@ class BaseAgent:
         if registry is None:
             # Lazy import to avoid circular dependencies if any
             try:
-                from kader.tools import get_default_registry
+                from kader.tools import get_cached_default_registry
 
-                registry = get_default_registry()
+                registry = get_cached_default_registry()
             except ImportError:
                 pass
 

kader/memory/types.py

@@ -114,3 +114,63 @@ def load_json(path: Path) -> dict[str, Any]:
         return {}
     with open(path, "r", encoding="utf-8") as f:
         return decode_bytes_values(json.load(f))
+
+
+# --- Async File I/O Utilities ---
+
+
+async def aread_text(path: Path, encoding: str = "utf-8") -> str:
+    """Asynchronously read text from a file.
+
+    Args:
+        path: Path to the file
+        encoding: File encoding (default: utf-8)
+
+    Returns:
+        File contents as string
+    """
+    import aiofiles
+
+    async with aiofiles.open(path, "r", encoding=encoding) as f:
+        return await f.read()
+
+
+async def awrite_text(path: Path, content: str, encoding: str = "utf-8") -> None:
+    """Asynchronously write text to a file.
+
+    Args:
+        path: Path to the file
+        content: Text content to write
+        encoding: File encoding (default: utf-8)
+    """
+    import aiofiles
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    async with aiofiles.open(path, "w", encoding=encoding) as f:
+        await f.write(content)
+
+
+async def asave_json(path: Path, data: dict[str, Any]) -> None:
+    """Asynchronously save data to a JSON file.
+
+    Args:
+        path: Path to the JSON file
+        data: Data to save
+    """
+    content = json.dumps(encode_bytes_values(data), indent=2, ensure_ascii=False)
+    await awrite_text(path, content)
+
+
+async def aload_json(path: Path) -> dict[str, Any]:
+    """Asynchronously load data from a JSON file.
+
+    Args:
+        path: Path to the JSON file
+
+    Returns:
+        Loaded data, or empty dict if file doesn't exist
+    """
+    if not path.exists():
+        return {}
+    content = await aread_text(path)
+    return decode_bytes_values(json.loads(content))

kader/prompts/__init__.py

@@ -1,4 +1,10 @@
-from .agent_prompts import BasicAssistancePrompt, PlanningAgentPrompt, ReActAgentPrompt
+from .agent_prompts import (
+    BasicAssistancePrompt,
+    ExecutorAgentPrompt,
+    KaderPlannerPrompt,
+    PlanningAgentPrompt,
+    ReActAgentPrompt,
+)
 from .base import PromptBase
 
 __all__ = [
@@ -6,4 +12,6 @@ __all__ = [
     "BasicAssistancePrompt",
     "ReActAgentPrompt",
     "PlanningAgentPrompt",
+    "KaderPlannerPrompt",
+    "ExecutorAgentPrompt",
 ]

kader/prompts/agent_prompts.py

@@ -25,3 +25,31 @@ class PlanningAgentPrompt(PromptBase):
 
     def __init__(self, **kwargs: Any) -> None:
         super().__init__(template_path="planning_agent.j2", **kwargs)
+
+
+class KaderPlannerPrompt(PromptBase):
+    """
+    Prompt for Kader Planner Agent.
+
+    Enhanced planning prompt with specific instructions for:
+    - Using Agent as a Tool with proper task/context parameters
+    - Tracking completed actions to avoid repetition
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(template_path="kader_planner.j2", **kwargs)
+
+
+class ExecutorAgentPrompt(PromptBase):
+    """
+    Prompt for Executor Agent (sub-agents in PlannerExecutorWorkflow).
+
+    Emphasizes:
+    - Careful thinking before each action
+    - Safe execution with error handling
+    - Detailed step-by-step reporting of what was done
+    - Structured final answer with files created, summary, and issues
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        super().__init__(template_path="executor_agent.j2", **kwargs)

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",
 ]