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

kader/tools/todo.py

@@ -52,7 +52,10 @@ class TodoTool(BaseTool[str]):
                 "Manage todo lists for planning. "
                 "Supports creating, reading, updating, and deleting todo lists. "
                 "Each list is identified by a todo_id and contains items with status "
-                "(not-started, in-progress, completed)."
+                "(not-started, in-progress, completed). "
+                "IMPORTANT: When updating, you can ONLY change the status of existing items. "
+                "You cannot add, remove, or modify task descriptions. "
+                "If you need to change tasks, delete and recreate the list."
             ),
             category=ToolCategory.UTILITY,
             parameters=[
@@ -185,7 +188,10 @@ class TodoTool(BaseTool[str]):
     def _update_todo(
         self, session_id: str, todo_id: str, items: list[TodoItem] | None
     ) -> str:
-        """Update an existing todo list (overwrite)."""
+        """Update an existing todo list (status changes only).
+        This method enforces integrity by only allowing status updates.
+        The task descriptions must match the existing todo list exactly.
+        """
         path = self._get_todo_path(session_id, todo_id)
         if not path.exists():
             return f"Error: Todo list '{todo_id}' not found. Use 'create' to make a new list."
@@ -193,6 +199,26 @@ class TodoTool(BaseTool[str]):
         if items is None:
             return "Error: 'items' must be provided for update action."
 
+        # Read existing todo list
+        with open(path, "r", encoding="utf-8") as f:
+            try:
+                existing_data = json.load(f)
+            except json.JSONDecodeError:
+                return "Error: Failed to decode existing todo list JSON."
+
+        # Validate integrity: check that task descriptions match
+        existing_tasks = [item.get("task", "") for item in existing_data]
+        new_tasks = [item.task for item in items]
+
+        # Check if the number of items matches
+        if len(existing_tasks) != len(new_tasks):
+            return self._format_integrity_error(todo_id, existing_data)
+
+        # Check if all task descriptions match (order matters)
+        if existing_tasks != new_tasks:
+            return self._format_integrity_error(todo_id, existing_data)
+
+        # Validation passed - update with new statuses
         data = [item.model_dump() for item in items]
 
         with open(path, "w", encoding="utf-8") as f:
@@ -200,6 +226,21 @@ class TodoTool(BaseTool[str]):
 
         return f"Successfully updated todo list '{todo_id}'."
 
+    def _format_integrity_error(self, todo_id: str, existing_data: list[dict]) -> str:
+        """Format an integrity error message with the current todo list content."""
+        items_description = "\n".join(
+            f"  {i + 1}. [{item.get('status', 'not-started')}] {item.get('task', '')}"
+            for i, item in enumerate(existing_data)
+        )
+        return (
+            f"Error: Update rejected - todo list integrity violation.\n"
+            f"The provided items do not match the existing todo list '{todo_id}'.\n"
+            f"You can only update the STATUS of existing items, not add, remove, or modify task descriptions.\n\n"
+            f"Current todo list '{todo_id}' content:\n{items_description}\n\n"
+            f"Please update using the exact task descriptions from the list above, "
+            f"only changing the 'status' field as needed."
+        )
+
     def _delete_todo(self, session_id: str, todo_id: str) -> str:
         """Delete a todo list."""
         path = self._get_todo_path(session_id, todo_id)

kader/utils/__init__.py

@@ -0,0 +1,10 @@
+"""
+Utility modules for Kader.
+
+Provides shared utility functions and helper modules.
+"""
+
+from .checkpointer import Checkpointer
+from .context_aggregator import ContextAggregator
+
+__all__ = ["Checkpointer", "ContextAggregator"]

kader/utils/checkpointer.py

@@ -0,0 +1,371 @@
+"""
+Checkpointer module for generating step-by-step summaries of agent memory.
+
+Uses OllamaProvider to analyze conversation history and produce
+human-readable markdown summaries.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from kader.memory.types import (
+    aload_json,
+    aread_text,
+    awrite_text,
+    get_default_memory_dir,
+    load_json,
+)
+from kader.providers.base import Message
+from kader.providers.ollama import OllamaProvider
+
+CHECKPOINT_SYSTEM_PROMPT = """You are an assistant that summarizes agent conversation histories.
+Given a conversation between a user and an AI agent, create a structured summary in markdown format.
+
+Your summary MUST include the following sections:
+
+## Directory Structure
+List the directory structure of any files/folders created or modified during the conversation.
+Use a tree-like format:
+```
+project/
+├── src/
+│   └── main.py
+└── README.md
+```
+
+## Actions Performed
+Summarize the main accomplishments and significant actions taken by the agent.
+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.
+"""
+
+
+class Checkpointer:
+    """
+    Generates step-by-step markdown summaries of agent memory.
+
+    Uses OllamaProvider to analyze conversation history from memory files
+    and produce human-readable checkpoint summaries.
+
+    Example:
+        checkpointer = Checkpointer()
+        md_path = checkpointer.generate_checkpoint("session-id/conversation.json")
+        print(f"Checkpoint saved to: {md_path}")
+    """
+
+    def __init__(
+        self,
+        model: str = "gpt-oss:120b-cloud",
+        host: str | None = None,
+    ) -> None:
+        """
+        Initialize the Checkpointer.
+
+        Args:
+            model: Ollama model identifier (default: "gpt-oss:120b-cloud")
+            host: Optional Ollama server host
+        """
+        self._provider = OllamaProvider(model=model, host=host)
+
+    def _load_memory(self, memory_path: Path) -> dict[str, Any]:
+        """
+        Load memory JSON from the specified path.
+
+        Args:
+            memory_path: Absolute path to the memory JSON file
+
+        Returns:
+            Dictionary containing the memory data
+
+        Raises:
+            FileNotFoundError: If the memory file doesn't exist
+        """
+        if not memory_path.exists():
+            raise FileNotFoundError(f"Memory file not found: {memory_path}")
+
+        return load_json(memory_path)
+
+    def _extract_messages(self, memory_data: dict[str, Any]) -> list[dict[str, Any]]:
+        """
+        Extract messages from memory data.
+
+        Args:
+            memory_data: Dictionary containing memory data
+
+        Returns:
+            List of message dictionaries
+        """
+        # Handle different memory formats
+        if "messages" in memory_data:
+            # Standard conversation format
+            messages = memory_data["messages"]
+            # Extract inner message if wrapped in ConversationMessage format
+            return [
+                msg.get("message", msg) if isinstance(msg, dict) else msg
+                for msg in messages
+            ]
+        elif "conversation" in memory_data:
+            # Alternative format
+            return memory_data["conversation"]
+        else:
+            # Return empty if no known format
+            return []
+
+    def _format_conversation_for_prompt(self, messages: list[dict[str, Any]]) -> str:
+        """
+        Format messages into a readable string for the LLM prompt.
+
+        Args:
+            messages: List of message dictionaries
+
+        Returns:
+            Formatted string representation of the conversation
+        """
+        lines = []
+        for i, msg in enumerate(messages, 1):
+            role = msg.get("role", "unknown").upper()
+            content = msg.get("content", "")
+
+            # Handle tool calls
+            tool_calls = msg.get("tool_calls", [])
+            if tool_calls:
+                lines.append(f"[{i}] {role}: (calling tools)")
+                for tc in tool_calls:
+                    func = tc.get("function", {})
+                    name = func.get("name", "unknown")
+                    args = func.get("arguments", {})
+                    lines.append(f"     -> Tool: {name}")
+                    lines.append(f"        Args: {args}")
+            elif content:
+                # Truncate very long content
+                if len(content) > 1000:
+                    content = content[:1000] + "... [truncated]"
+                lines.append(f"[{i}] {role}: {content}")
+
+            # Handle tool call ID (tool results)
+            tool_call_id = msg.get("tool_call_id")
+            if tool_call_id:
+                lines.append(f"     (tool result for: {tool_call_id})")
+
+        return "\n".join(lines)
+
+    def _generate_summary(
+        self, conversation_text: str, existing_checkpoint: str | None = None
+    ) -> str:
+        """
+        Generate a step-by-step summary using the LLM (synchronous).
+
+        Args:
+            conversation_text: Formatted conversation text
+            existing_checkpoint: Existing checkpoint content to update, if any
+
+        Returns:
+            Markdown summary of the conversation
+        """
+        if existing_checkpoint:
+            user_prompt = f"""Here is the existing checkpoint from previous iterations:
+
+---
+{existing_checkpoint}
+---
+
+Here is the new conversation to incorporate:
+
+---
+{conversation_text}
+---
+
+Update the existing checkpoint by incorporating the new information. Merge new items into the existing sections.
+Keep all previously documented content and add new content from this iteration."""
+        else:
+            user_prompt = f"""Please analyze this agent conversation and create a checkpoint summary:
+
+---
+{conversation_text}
+---
+
+Create a structured summary following the format specified."""
+
+        messages = [
+            Message.system(CHECKPOINT_SYSTEM_PROMPT),
+            Message.user(user_prompt),
+        ]
+
+        response = self._provider.invoke(messages)
+        return response.content
+
+    async def _agenerate_summary(
+        self, conversation_text: str, existing_checkpoint: str | None = None
+    ) -> str:
+        """
+        Generate a step-by-step summary using the LLM (asynchronous).
+
+        Args:
+            conversation_text: Formatted conversation text
+            existing_checkpoint: Existing checkpoint content to update, if any
+
+        Returns:
+            Markdown summary of the conversation
+        """
+        if existing_checkpoint:
+            user_prompt = f"""Here is the existing checkpoint from previous iterations:
+
+---
+{existing_checkpoint}
+---
+
+Here is the new conversation to incorporate:
+
+---
+{conversation_text}
+---
+
+Update the existing checkpoint by incorporating the new information. Merge new items into the existing sections.
+Keep all previously documented content and add new content from this iteration."""
+        else:
+            user_prompt = f"""Please analyze this agent conversation and create a checkpoint summary:
+
+---
+{conversation_text}
+---
+
+Create a structured summary following the format specified."""
+
+        messages = [
+            Message.system(CHECKPOINT_SYSTEM_PROMPT),
+            Message.user(user_prompt),
+        ]
+
+        response = await self._provider.ainvoke(messages)
+        return response.content
+
+    def _load_existing_checkpoint(self, checkpoint_path: Path) -> str | None:
+        """
+        Load existing checkpoint content if it exists.
+
+        Args:
+            checkpoint_path: Path to the checkpoint file
+
+        Returns:
+            Checkpoint content if exists, None otherwise
+        """
+        if checkpoint_path.exists():
+            try:
+                return checkpoint_path.read_text(encoding="utf-8")
+            except Exception:
+                return None
+        return None
+
+    async def _aload_existing_checkpoint(self, checkpoint_path: Path) -> str | None:
+        """
+        Asynchronously load existing checkpoint content if it exists.
+
+        Args:
+            checkpoint_path: Path to the checkpoint file
+
+        Returns:
+            Checkpoint content if exists, None otherwise
+        """
+        if checkpoint_path.exists():
+            try:
+                return await aread_text(checkpoint_path)
+            except Exception:
+                return None
+        return None
+
+    def generate_checkpoint(self, memory_path: str) -> str:
+        """
+        Generate a checkpoint markdown file from an agent's memory (synchronous).
+
+        If a checkpoint already exists, it will be updated instead of overwritten.
+
+        Args:
+            memory_path: Relative path within ~/.kader/memory/sessions/
+                         (e.g., "session-id/conversation.json")
+                         Or absolute path to the memory JSON file.
+
+        Returns:
+            Absolute path to the generated markdown file
+
+        Raises:
+            FileNotFoundError: If the memory file doesn't exist
+            ValueError: If no messages found in memory
+        """
+        # Resolve path
+        path = Path(memory_path)
+        if not path.is_absolute():
+            base_dir = get_default_memory_dir() / "sessions"
+            path = base_dir / memory_path
+
+        # Load and parse memory
+        memory_data = self._load_memory(path)
+        messages = self._extract_messages(memory_data)
+
+        if not messages:
+            raise ValueError(f"No messages found in memory file: {path}")
+
+        # Check for existing checkpoint
+        checkpoint_path = path.parent / "checkpoint.md"
+        existing_checkpoint = self._load_existing_checkpoint(checkpoint_path)
+
+        # Format and generate summary
+        conversation_text = self._format_conversation_for_prompt(messages)
+        summary = self._generate_summary(conversation_text, existing_checkpoint)
+
+        # Save checkpoint markdown
+        checkpoint_path.write_text(summary, encoding="utf-8")
+
+        return str(checkpoint_path)
+
+    async def agenerate_checkpoint(self, memory_path: str) -> str:
+        """
+        Generate a checkpoint markdown file from an agent's memory (asynchronous).
+
+        If a checkpoint already exists, it will be updated instead of overwritten.
+
+        Args:
+            memory_path: Relative path within ~/.kader/memory/sessions/
+                         (e.g., "session-id/conversation.json")
+                         Or absolute path to the memory JSON file.
+
+        Returns:
+            Absolute path to the generated markdown file
+
+        Raises:
+            FileNotFoundError: If the memory file doesn't exist
+            ValueError: If no messages found in memory
+        """
+        # Resolve path
+        path = Path(memory_path)
+        if not path.is_absolute():
+            base_dir = get_default_memory_dir() / "sessions"
+            path = base_dir / memory_path
+
+        # Load and parse memory (async)
+        if not path.exists():
+            raise FileNotFoundError(f"Memory file not found: {path}")
+        memory_data = await aload_json(path)
+        messages = self._extract_messages(memory_data)
+
+        if not messages:
+            raise ValueError(f"No messages found in memory file: {path}")
+
+        # Check for existing checkpoint (async)
+        checkpoint_path = path.parent / "checkpoint.md"
+        existing_checkpoint = await self._aload_existing_checkpoint(checkpoint_path)
+
+        # Format and generate summary
+        conversation_text = self._format_conversation_for_prompt(messages)
+        summary = await self._agenerate_summary(conversation_text, existing_checkpoint)
+
+        # Save checkpoint markdown (async)
+        await awrite_text(checkpoint_path, summary)
+
+        return str(checkpoint_path)