kader 0.1.6__tar.gz → 1.0.0__tar.gz

{kader-0.1.6 → kader-1.0.0}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: kader
-Version: 0.1.6
+Version: 1.0.0
 Summary: kader coding agent
 Requires-Python: >=3.11
+Requires-Dist: aiofiles>=25.1.0
 Requires-Dist: faiss-cpu>=1.9.0
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: loguru>=0.7.3
@@ -32,6 +33,7 @@ Kader is an intelligent coding agent designed to assist with software developmen
 - 🔄 **ReAct Agent Framework** - Reasoning and Acting agent architecture
 - 🗂️ **File System Tools** - Read, write, search, and edit files
 - 🔍 **Planning Agent** - Task planning and execution capabilities
+- 🤝 **Agent-As-Tool** - Spawn sub-agents for specific tasks with isolated memory
 
 ## Installation
 
@@ -177,6 +179,40 @@ Kader provides several agent types:
 - **PlanningAgent**: Agent that plans multi-step tasks
 - **BaseAgent**: Base agent class for creating custom agents
 
+### Agent-As-Tool (AgentTool)
+
+The `AgentTool` allows you to wrap a `ReActAgent` as a callable tool, enabling agents to spawn sub-agents for specific tasks with isolated memory contexts.
+
+```python
+from kader.tools import AgentTool
+
+# Autonomous execution (runs without pausing for confirmation)
+autonomous_agent = AgentTool(
+    name="research_agent",
+    description="Research topics autonomously",
+    interrupt_before_tool=False,
+)
+result = autonomous_agent.execute(task="Find info about topic X")
+
+# Interactive execution (pauses for user confirmation before each tool)
+def my_callback(tool_call_dict, llm_content=None):
+    user_input = input("Execute? [y/n]: ")
+    return (user_input.lower() == 'y', None)
+
+interactive_agent = AgentTool(
+    name="interactive_agent",
+    interrupt_before_tool=True,
+    tool_confirmation_callback=my_callback,
+)
+result = interactive_agent.execute(task="Analyze data and generate report")
+```
+
+**Key Features:**
+- Each sub-agent has isolated memory (separate `SlidingWindowConversationManager`)
+- Default tools included: filesystem, web search, command executor
+- Optional `interrupt_before_tool` for user confirmation before tool execution
+- Task completes when the agent returns its final response
+
 ### Memory Management
 
 Kader's memory system includes:
@@ -194,6 +230,7 @@ Kader includes a rich set of tools:
 - **Command Executor**: Execute shell commands safely
 - **Web Tools**: Search and fetch web content
 - **RAG Tools**: Retrieval Augmented Generation capabilities
+- **AgentTool**: Spawn sub-agents for specific tasks
 
 ## Examples
 

{kader-0.1.6 → kader-1.0.0}/README.md

@@ -15,6 +15,7 @@ Kader is an intelligent coding agent designed to assist with software developmen
 - 🔄 **ReAct Agent Framework** - Reasoning and Acting agent architecture
 - 🗂️ **File System Tools** - Read, write, search, and edit files
 - 🔍 **Planning Agent** - Task planning and execution capabilities
+- 🤝 **Agent-As-Tool** - Spawn sub-agents for specific tasks with isolated memory
 
 ## Installation
 
@@ -160,6 +161,40 @@ Kader provides several agent types:
 - **PlanningAgent**: Agent that plans multi-step tasks
 - **BaseAgent**: Base agent class for creating custom agents
 
+### Agent-As-Tool (AgentTool)
+
+The `AgentTool` allows you to wrap a `ReActAgent` as a callable tool, enabling agents to spawn sub-agents for specific tasks with isolated memory contexts.
+
+```python
+from kader.tools import AgentTool
+
+# Autonomous execution (runs without pausing for confirmation)
+autonomous_agent = AgentTool(
+    name="research_agent",
+    description="Research topics autonomously",
+    interrupt_before_tool=False,
+)
+result = autonomous_agent.execute(task="Find info about topic X")
+
+# Interactive execution (pauses for user confirmation before each tool)
+def my_callback(tool_call_dict, llm_content=None):
+    user_input = input("Execute? [y/n]: ")
+    return (user_input.lower() == 'y', None)
+
+interactive_agent = AgentTool(
+    name="interactive_agent",
+    interrupt_before_tool=True,
+    tool_confirmation_callback=my_callback,
+)
+result = interactive_agent.execute(task="Analyze data and generate report")
+```
+
+**Key Features:**
+- Each sub-agent has isolated memory (separate `SlidingWindowConversationManager`)
+- Default tools included: filesystem, web search, command executor
+- Optional `interrupt_before_tool` for user confirmation before tool execution
+- Task completes when the agent returns its final response
+
 ### Memory Management
 
 Kader's memory system includes:
@@ -177,6 +212,7 @@ Kader includes a rich set of tools:
 - **Command Executor**: Execute shell commands safely
 - **Web Tools**: Search and fetch web content
 - **RAG Tools**: Retrieval Augmented Generation capabilities
+- **AgentTool**: Spawn sub-agents for specific tasks
 
 ## Examples
 

{kader-0.1.6 → kader-1.0.0}/cli/app.py

@@ -1,7 +1,9 @@
 """Kader CLI - Modern Vibe Coding CLI with Textual."""
 
 import asyncio
+import atexit
 import threading
+from concurrent.futures import ThreadPoolExecutor
 from importlib.metadata import version as get_version
 from pathlib import Path
 from typing import Optional
@@ -18,13 +20,11 @@ from textual.widgets import (
     Tree,
 )
 
-from kader.agent.agents import ReActAgent
 from kader.memory import (
     FileSessionManager,
     MemoryConfig,
-    SlidingWindowConversationManager,
 )
-from kader.tools import get_default_registry
+from kader.workflows import PlannerExecutorWorkflow
 
 from .utils import (
     DEFAULT_MODEL,
@@ -103,22 +103,79 @@ class KaderApp(App):
         self._model_selector: Optional[ModelSelector] = None
         self._update_info: Optional[str] = None  # Latest version if update available
 
-        self._agent = self._create_agent(self._current_model)
+        # Dedicated thread pool for agent invocation (isolated from default pool)
+        self._agent_executor = ThreadPoolExecutor(
+            max_workers=2, thread_name_prefix="kader_agent"
+        )
+        # Ensure executor is properly shut down on exit
+        atexit.register(self._agent_executor.shutdown, wait=False)
+
+        self._workflow = self._create_workflow(self._current_model)
 
-    def _create_agent(self, model_name: str) -> ReActAgent:
-        """Create a new ReActAgent with the specified model."""
-        registry = get_default_registry()
-        memory = SlidingWindowConversationManager(window_size=10)
-        return ReActAgent(
+    def _create_workflow(self, model_name: str) -> PlannerExecutorWorkflow:
+        """Create a new PlannerExecutorWorkflow with the specified model."""
+        return PlannerExecutorWorkflow(
             name="kader_cli",
-            tools=registry,
-            memory=memory,
             model_name=model_name,
-            use_persistence=True,
             interrupt_before_tool=True,
             tool_confirmation_callback=self._tool_confirmation_callback,
+            direct_execution_callback=self._direct_execution_callback,
+            tool_execution_result_callback=self._tool_execution_result_callback,
+            use_persistence=True,
+            executor_names=["executor"],
+        )
+
+    def _direct_execution_callback(self, message: str, tool_name: str) -> None:
+        """
+        Callback for direct execution tools - called from agent thread.
+
+        Shows a message in the conversation view without blocking for confirmation.
+        """
+        # Schedule message display on main thread
+        self.call_from_thread(self._show_direct_execution_message, message, tool_name)
+
+    def _show_direct_execution_message(self, message: str, tool_name: str) -> None:
+        """Show a direct execution message in the conversation view."""
+        try:
+            conversation = self.query_one("#conversation-view", ConversationView)
+            # User-friendly message showing the tool is executing
+            friendly_message = f"[>] Executing {tool_name}..."
+            conversation.add_message(friendly_message, "assistant")
+            conversation.scroll_end()
+        except Exception:
+            pass
+
+    def _tool_execution_result_callback(
+        self, tool_name: str, success: bool, result: str
+    ) -> None:
+        """
+        Callback for tool execution results - called from agent thread.
+
+        Updates the conversation view with the execution result.
+        """
+        # Schedule result display on main thread
+        self.call_from_thread(
+            self._show_tool_execution_result, tool_name, success, result
         )
 
+    def _show_tool_execution_result(
+        self, tool_name: str, success: bool, result: str
+    ) -> None:
+        """Show the tool execution result in the conversation view."""
+        try:
+            conversation = self.query_one("#conversation-view", ConversationView)
+            if success:
+                # User-friendly success message
+                friendly_message = f"(+) {tool_name} completed successfully"
+            else:
+                # User-friendly error message with truncated result
+                error_preview = result[:100] + "..." if len(result) > 100 else result
+                friendly_message = f"(-) {tool_name} failed: {error_preview}"
+            conversation.add_message(friendly_message, "assistant")
+            conversation.scroll_end()
+        except Exception:
+            pass
+
     def _tool_confirmation_callback(self, message: str) -> tuple[bool, Optional[str]]:
         """
         Callback for tool confirmation - called from agent thread.
@@ -135,7 +192,10 @@ class KaderApp(App):
 
         # Wait for user response (blocking in agent thread)
         # This is safe because we're in a background thread
-        self._confirmation_event.wait()
+        # Timeout after 5 minutes to prevent indefinite blocking
+        if not self._confirmation_event.wait(timeout=300):
+            # Timeout occurred - decline tool execution gracefully
+            return (False, "Tool confirmation timed out after 5 minutes")
 
         # Return the result
         return self._confirmation_result
@@ -183,7 +243,8 @@ class KaderApp(App):
         if event.confirmed:
             if tool_message:
                 conversation.add_message(tool_message, "assistant")
-            conversation.add_message("(+) Executing tool...", "assistant")
+            # Show executing message - will be updated by result callback
+            conversation.add_message("[>] Executing tool...", "assistant")
             # Restart spinner
             try:
                 spinner = self.query_one(LoadingSpinner)
@@ -249,7 +310,7 @@ class KaderApp(App):
         # Update model and recreate agent
         old_model = self._current_model
         self._current_model = event.model
-        self._agent = self._create_agent(self._current_model)
+        self._workflow = self._create_workflow(self._current_model)
 
         conversation.add_message(
             f"(+) Model changed from `{old_model}` to `{self._current_model}`",
@@ -431,8 +492,8 @@ Please resize your terminal."""
             await self._show_model_selector(conversation)
         elif cmd == "/clear":
             conversation.clear_messages()
-            self._agent.memory.clear()
-            self._agent.provider.reset_tracking()  # Reset usage/cost tracking
+            self._workflow.planner.memory.clear()
+            self._workflow.planner.provider.reset_tracking()  # Reset usage/cost tracking
             self._current_session_id = None
             self.notify("Conversation cleared!", severity="information")
         elif cmd == "/save":
@@ -462,7 +523,7 @@ Please resize your terminal."""
             )
 
     async def _handle_chat(self, message: str) -> None:
-        """Handle regular chat messages with ReActAgent."""
+        """Handle regular chat messages with PlannerExecutorWorkflow."""
         if self._is_processing:
             self.notify("Please wait for the current response...", severity="warning")
             return
@@ -490,16 +551,21 @@ Please resize your terminal."""
         spinner = self.query_one(LoadingSpinner)
 
         try:
-            # Run the agent invoke in a thread
+            # Run the workflow in a dedicated thread pool
             loop = asyncio.get_event_loop()
             response = await loop.run_in_executor(
-                None, lambda: self._agent.invoke(message)
+                self._agent_executor, lambda: self._workflow.run(message)
             )
 
             # Hide spinner and show response (this runs on main thread via await)
             spinner.stop()
-            if response and response.content:
-                conversation.add_message(response.content, "assistant")
+            if response:
+                conversation.add_message(
+                    response,
+                    "assistant",
+                    model_name=self._workflow.planner.provider.model,
+                    usage_cost=self._workflow.planner.provider.total_cost.total_cost,
+                )
 
         except Exception as e:
             spinner.stop()
@@ -516,7 +582,7 @@ Please resize your terminal."""
         """Clear the conversation (Ctrl+L)."""
         conversation = self.query_one("#conversation-view", ConversationView)
         conversation.clear_messages()
-        self._agent.memory.clear()
+        self._workflow.planner.memory.clear()
         self.notify("Conversation cleared!", severity="information")
 
     def action_save_session(self) -> None:
@@ -548,8 +614,10 @@ Please resize your terminal."""
                 session = self._session_manager.create_session("kader_cli")
                 self._current_session_id = session.session_id
 
-            # Get messages from agent memory and save
-            messages = [msg.message for msg in self._agent.memory.get_messages()]
+            # Get messages from planner memory and save
+            messages = [
+                msg.message for msg in self._workflow.planner.memory.get_messages()
+            ]
             self._session_manager.save_conversation(self._current_session_id, messages)
 
             conversation.add_message(
@@ -580,11 +648,11 @@ Please resize your terminal."""
 
             # Clear current state
             conversation.clear_messages()
-            self._agent.memory.clear()
+            self._workflow.planner.memory.clear()
 
             # Add loaded messages to memory and UI
             for msg in messages:
-                self._agent.memory.add_message(msg)
+                self._workflow.planner.memory.add_message(msg)
                 role = msg.get("role", "user")
                 content = msg.get("content", "")
                 if role in ["user", "assistant"] and content:
@@ -633,9 +701,9 @@ Please resize your terminal."""
         """Display LLM usage costs."""
         try:
             # Get cost and usage from the provider
-            cost = self._agent.provider.total_cost
-            usage = self._agent.provider.total_usage
-            model = self._agent.provider.model
+            cost = self._workflow.planner.provider.total_cost
+            usage = self._workflow.planner.provider.total_usage
+            model = self._workflow.planner.provider.model
 
             lines = [
                 "## Usage Costs ($)\n",

{kader-0.1.6 → kader-1.0.0}/cli/app.tcss

@@ -132,6 +132,26 @@ ConversationView {
     scrollbar-size: 1 1;
 }
 
+.message-footer {
+    height: auto;
+    margin-top: 0;
+    padding: 0 1;
+    border-top: none;
+}
+
+.footer-left {
+    color: $secondary;
+    text-style: italic;
+    width: 1fr;
+}
+
+.footer-right {
+    color: $success;
+    text-style: bold;
+    text-align: right;
+    width: auto;
+}
+
 /* ===== Welcome Message ===== */
 
 #welcome {

{kader-0.1.6 → kader-1.0.0}/cli/utils.py

@@ -3,7 +3,7 @@
 from kader.providers import OllamaProvider
 
 # Default model
-DEFAULT_MODEL = "qwen3-coder:480b-cloud"
+DEFAULT_MODEL = "kimi-k2.5:cloud"
 
 HELP_TEXT = """## Kader CLI Commands
 

kader-1.0.0/cli/widgets/conversation.py

@@ -0,0 +1,101 @@
+"""Conversation display widget for Kader CLI."""
+
+from textual.app import ComposeResult
+from textual.containers import Horizontal, VerticalScroll
+from textual.widgets import Markdown, Static
+
+
+class Message(Static):
+    """A single message in the conversation."""
+
+    def __init__(
+        self,
+        content: str,
+        role: str = "user",
+        model_name: str | None = None,
+        usage_cost: float | None = None,
+    ) -> None:
+        super().__init__()
+        self.content = content
+        self.role = role
+        self.model_name = model_name
+        self.usage_cost = usage_cost
+        self.add_class(f"message-{role}")
+
+    def compose(self) -> ComposeResult:
+        prefix = "(**) **You:**" if self.role == "user" else "(^^) **Kader:**"
+        yield Markdown(f"{prefix}\n\n{self.content}")
+
+        if self.role == "assistant" and (
+            self.model_name or self.usage_cost is not None
+        ):
+            with Horizontal(classes="message-footer"):
+                model_label = f"[*] {self.model_name}" if self.model_name else ""
+                yield Static(model_label, classes="footer-left")
+
+                usage_label = (
+                    f"($) {self.usage_cost:.6f}" if self.usage_cost is not None else ""
+                )
+                yield Static(usage_label, classes="footer-right")
+
+
+class ConversationView(VerticalScroll):
+    """Scrollable conversation history with markdown rendering."""
+
+    DEFAULT_CSS = """
+    ConversationView {
+        padding: 1 2;
+    }
+
+    ConversationView Message {
+        margin-bottom: 1;
+        padding: 1;
+    }
+
+    ConversationView .message-user {
+        background: $surface;
+        border-left: thick $primary;
+    }
+
+    ConversationView .message-assistant {
+        background: $surface-darken-1;
+        border-left: thick $success;
+    }
+
+    .message-footer {
+        height: auto;
+        margin-top: 0;
+        padding: 0 1;
+        border-top: none;
+    }
+
+    .footer-left {
+        color: $secondary;
+        text-style: italic;
+        width: 1fr;
+    }
+
+    .footer-right {
+        color: $success;
+        text-style: bold;
+        text-align: right;
+        width: auto;
+    }
+    """
+
+    def add_message(
+        self,
+        content: str,
+        role: str = "user",
+        model_name: str | None = None,
+        usage_cost: float | None = None,
+    ) -> None:
+        """Add a message to the conversation."""
+        message = Message(content, role, model_name, usage_cost)
+        self.mount(message)
+        self.scroll_end(animate=True)
+
+    def clear_messages(self) -> None:
+        """Clear all messages from the conversation."""
+        for child in self.query(Message):
+            child.remove()

kader-1.0.0/examples/planner_executor_example.py

@@ -0,0 +1,74 @@
+"""
+Planner-Executor Workflow Example.
+
+Demonstrates the PlannerExecutorWorkflow that uses a PlanningAgent with
+TodoTool for task management and AgentTool for sub-task delegation.
+"""
+
+import asyncio
+import os
+import sys
+
+# Add project root to path for direct execution
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
+
+from kader.workflows import PlannerExecutorWorkflow
+
+
+async def main():
+    print("=== Planner-Executor Workflow Demo ===")
+    print("This workflow uses a PlanningAgent to:")
+    print("  1. Create a plan using TodoTool")
+    print("  2. Delegate sub-tasks to executor agents")
+    print("  3. Track progress and update todo status")
+    print("\nType '/exit' or '/close' to quit.\n")
+
+    # Initialize the workflow
+    # Note: The planner (TodoTool, AgentTool) executes without interruption
+    # Sub-agents spawned by AgentTool will respect interrupt_before_tool setting
+    workflow = PlannerExecutorWorkflow(
+        name="demo_workflow",
+        model_name="qwen3-coder:480b-cloud",
+        interrupt_before_tool=True,  # Applies to sub-agents inside AgentTool
+        use_persistence=True,
+        executor_names=["code_executor", "research_executor"],
+    )
+
+    print(f"Workflow '{workflow.name}' initialized")
+    print(f"Planner session ID: {workflow.planner.session_id}")
+    print(f"Available tools: {list(workflow.planner.tools_map.keys())}\n")
+
+    # Interactive Loop
+    while True:
+        try:
+            user_input = input("\nYou: ").strip()
+
+            if not user_input:
+                continue
+
+            if user_input.lower() in ["/exit", "/close", "exit", "quit"]:
+                print("Goodbye!")
+                break
+
+            if user_input.lower() == "/reset":
+                workflow.reset()
+                print("Workflow reset. Fresh planner created.")
+                continue
+
+            # Run the workflow
+            print("\nPlanner is analyzing and creating a plan...")
+            try:
+                result = workflow.run(user_input)
+                print(f"\n[Workflow Result]:\n{result}\n")
+            except Exception as e:
+                print(f"\nError during workflow execution: {e}")
+
+        except KeyboardInterrupt:
+            print("\nGoodbye!")
+            break
+        except Exception as e:
+            print(f"\nAn error occurred: {e}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

{kader-0.1.6 → kader-1.0.0}/examples/tools_example.py

@@ -18,6 +18,8 @@ from pathlib import Path
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
 
 from kader.tools import (
+    # Agent Tool
+    AgentTool,
     # Command execution
     CommandExecutorTool,
     GrepTool,
@@ -371,6 +373,66 @@ def demo_tool_parameters():
     print(f"\nTool schema (first 200 chars): {str(schema)[:200]}...")
 
 
+def demo_agent_tool():
+    """Demonstrate the AgentTool that wraps a ReActAgent."""
+    print("\n=== Agent Tool Demo ===")
+
+    # Example 1: Autonomous execution (no tool interrupts)
+    print("\n--- Autonomous AgentTool ---")
+    autonomous_agent = AgentTool(
+        name="research_agent",
+        description="An agent that can research topics and perform tasks autonomously",
+        interrupt_before_tool=False,  # Default: runs without pausing
+    )
+
+    print(f"Tool created: {autonomous_agent.name}")
+    print(f"Description: {autonomous_agent.description}")
+    print(f"Category: {autonomous_agent.schema.category.value}")
+    print(f"Interrupt before tool: {autonomous_agent._interrupt_before_tool}")
+
+    # Show parameters
+    print("\nParameters:")
+    for param in autonomous_agent.schema.parameters:
+        print(
+            f"  - {param.name}: {param.description} (type: {param.type}, required: {param.required})"
+        )
+
+    # Test interruption message
+    task = "Find the current stock price of AAPL and summarize the market trends"
+    msg = autonomous_agent.get_interruption_message(task=task)
+    print(f"\nInterruption message: {msg}")
+
+    # Example 2: Interactive execution with tool confirmation
+    print("\n--- Interactive AgentTool ---")
+
+    # Define a custom confirmation callback
+    def example_callback(tool_call_dict, llm_content=None):
+        """Example callback that would normally prompt the user."""
+        # In a real scenario, this would prompt the user
+        # Return (should_execute, optional_user_feedback)
+        return (True, None)
+
+    interactive_agent = AgentTool(
+        name="interactive_agent",
+        description="An agent that confirms each tool execution with the user",
+        interrupt_before_tool=True,  # Pause before each tool
+        tool_confirmation_callback=example_callback,
+    )
+
+    print(f"Tool created: {interactive_agent.name}")
+    print(f"Interrupt before tool: {interactive_agent._interrupt_before_tool}")
+    print(
+        f"Callback provided: {interactive_agent._tool_confirmation_callback is not None}"
+    )
+
+    # Note: Actual execution would require LLM access
+    print("\n[Note] To actually run the agent, LLM access is required.")
+    print(
+        "When interrupt_before_tool=True, the agent pauses before each tool execution "
+        "for confirmation. The task completes only when the agent returns its final response."
+    )
+
+
 def main():
     """Run all tool demos."""
     print("Kader Tools Examples")
@@ -390,6 +452,7 @@ def main():
     demo_custom_tool()
     demo_async_operations()
     demo_tool_parameters()
+    demo_agent_tool()
 
     print("\n[OK] All tool demos completed!")
 

{kader-0.1.6 → kader-1.0.0}/kader/__init__.py

@@ -8,6 +8,7 @@ creating the .kader directory in the user's home directory.
 from .config import ENV_FILE_PATH, KADER_DIR, initialize_kader_config
 from .providers import *  # noqa: F401, F403
 from .tools import *  # noqa: F401, F403
+from .utils import Checkpointer
 
 # Initialize the configuration when the module is imported
 initialize_kader_config()
@@ -18,5 +19,6 @@ __all__ = [
     "KADER_DIR",
     "ENV_FILE_PATH",
     "initialize_kader_config",
+    "Checkpointer",
     # Export everything from providers and tools
 ]