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

kader/agent/base.py

@@ -23,7 +23,9 @@ from kader.providers.base import (
     Message,
     ModelConfig,
     StreamChunk,
+    Usage,
 )
+from kader.providers.google import GoogleProvider
 from kader.providers.ollama import OllamaProvider
 from kader.tools import BaseTool, ToolRegistry
 
@@ -48,11 +50,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 +81,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
@@ -214,6 +224,8 @@ class BaseAgent:
             provider_type = "openai"
             if isinstance(self.provider, OllamaProvider):
                 provider_type = "ollama"
+            elif isinstance(self.provider, GoogleProvider):
+                provider_type = "google"
 
             base_config = ModelConfig(
                 temperature=base_config.temperature,
@@ -339,6 +351,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 +472,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 +531,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 +570,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,
         )
 
@@ -565,7 +628,12 @@ class BaseAgent:
                     )
 
                     # estimate the cost...
-                    estimated_cost = self.provider.estimate_cost(token_usage)
+                    usage_obj = Usage(
+                        prompt_tokens=token_usage["prompt_tokens"],
+                        completion_tokens=token_usage["completion_tokens"],
+                        total_tokens=token_usage["total_tokens"],
+                    )
+                    estimated_cost = self.provider.estimate_cost(usage_obj)
 
                     # Calculate and log cost
                     agent_logger.calculate_cost(
@@ -652,7 +720,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 +759,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,
         )
 
@@ -733,7 +805,12 @@ class BaseAgent:
                     )
 
                     # estimate the cost...
-                    estimated_cost = self.provider.estimate_cost(token_usage)
+                    usage_obj = Usage(
+                        prompt_tokens=token_usage["prompt_tokens"],
+                        completion_tokens=token_usage["completion_tokens"],
+                        total_tokens=token_usage["total_tokens"],
+                    )
+                    estimated_cost = self.provider.estimate_cost(usage_obj)
 
                     # Calculate and log cost
                     agent_logger.calculate_cost(
@@ -905,9 +982,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/config.py

@@ -69,13 +69,21 @@ def ensure_kader_directory():
 def ensure_env_file(kader_dir):
     """
     Ensure that the .env file exists in the .kader directory with the
-    required OLLAMA_API_KEY configuration.
+    required API key configurations.
     """
     env_file = kader_dir / ".env"
 
     # Create the .env file if it doesn't exist
     if not env_file.exists():
-        env_file.write_text("OLLAMA_API_KEY=''\n", encoding="utf-8")
+        default_env_content = """# Kader Configuration
+# Ollama API Key (for local Ollama models)
+OLLAMA_API_KEY=''
+
+# Google Gemini API Key (for Google Gemini models)
+# Get your API key from: https://aistudio.google.com/apikey
+GEMINI_API_KEY=''
+"""
+        env_file.write_text(default_env_content, encoding="utf-8")
 
         # Set appropriate permissions for the .env file on Unix-like systems
         if not sys.platform.startswith("win"):

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/__init__.py

@@ -1,9 +1,11 @@
 from .base import Message
+from .google import GoogleProvider
 from .mock import MockLLM
 from .ollama import OllamaProvider
 
 __all__ = [
     "Message",
     "OllamaProvider",
+    "GoogleProvider",
     "MockLLM",
 ]