todo-agent 0.1.0__py3-none-any.whl

todo_agent/__init__.py

@@ -0,0 +1,14 @@
+"""
+Todo Agent - A natural language interface for todo.sh task management.
+"""
+
+try:
+    from ._version import version as __version__
+except ImportError:
+    __version__ = "unknown"
+
+__author__ = "codeprimate"
+
+from .main import main
+
+__all__ = ["main"]

todo_agent/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

todo_agent/core/__init__.py

@@ -0,0 +1,16 @@
+"""
+Core domain layer for todo.sh LLM agent.
+
+This module contains the business logic and domain entities
+for managing todo.sh operations.
+"""
+
+from .exceptions import InvalidTaskFormatError, TaskNotFoundError, TodoError
+from .todo_manager import TodoManager
+
+__all__ = [
+    "TodoManager",
+    "TodoError",
+    "TaskNotFoundError",
+    "InvalidTaskFormatError",
+]

todo_agent/core/conversation_manager.py

@@ -0,0 +1,310 @@
+"""
+Conversation management for todo.sh LLM agent.
+"""
+
+import time
+from typing import List, Dict, Optional
+from dataclasses import dataclass
+from enum import Enum
+
+try:
+    from todo_agent.infrastructure.token_counter import get_token_counter
+except ImportError:
+    from infrastructure.token_counter import get_token_counter
+
+
+class MessageRole(Enum):
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+    SYSTEM = "system"
+
+
+@dataclass
+class ConversationMessage:
+    role: MessageRole
+    content: str
+    tool_call_id: Optional[str] = None
+    timestamp: Optional[float] = None
+    tool_calls: Optional[List[Dict]] = None
+    thinking_time: Optional[float] = None
+    token_count: Optional[int] = None  # Cache token count for efficiency
+
+
+class ConversationManager:
+    """Manages conversation state and memory for LLM interactions."""
+
+    def __init__(
+        self, max_tokens: int = 4000, max_messages: int = 50, model: str = "gpt-4"
+    ):
+        self.history: List[ConversationMessage] = []
+        self.max_tokens = max_tokens
+        self.max_messages = max_messages
+        self.system_prompt: Optional[str] = None
+        self.token_counter = get_token_counter(model)
+        self._total_tokens = 0  # Running total of tokens in conversation
+
+    def add_message(
+        self,
+        role: MessageRole,
+        content: str,
+        tool_call_id: Optional[str] = None,
+        thinking_time: Optional[float] = None,
+    ) -> None:
+        """
+        Add a message to conversation history.
+
+        Args:
+            role: Message role (user, assistant, tool, system)
+            content: Message content
+            tool_call_id: Optional tool call identifier for tool messages
+            thinking_time: Optional thinking time in seconds for assistant messages
+        """
+        # Calculate token count for this message
+        token_count = self._estimate_tokens(content)
+
+        message = ConversationMessage(
+            role=role,
+            content=content,
+            tool_call_id=tool_call_id,
+            timestamp=time.time(),
+            thinking_time=thinking_time,
+            token_count=token_count,
+        )
+
+        self.history.append(message)
+        self._total_tokens += token_count
+        self._trim_if_needed()
+
+    def get_messages(self, include_tool_calls: bool = True) -> List[Dict[str, str]]:
+        """
+        Get conversation messages in OpenRouter API format.
+
+        Args:
+            include_tool_calls: Whether to include tool call messages
+
+        Returns:
+            List of message dictionaries for API consumption
+        """
+        messages = []
+
+        # Add conversation messages (system prompt is already in history)
+        for msg in self.history:
+            if msg.role == MessageRole.TOOL and not include_tool_calls:
+                continue
+
+            message_dict = {"role": msg.role.value, "content": msg.content}
+
+            # Handle tool calls in assistant messages
+            if msg.role == MessageRole.ASSISTANT and msg.tool_calls:
+                message_dict["tool_calls"] = msg.tool_calls
+
+            # Handle tool call IDs
+            if msg.tool_call_id:
+                message_dict["tool_call_id"] = msg.tool_call_id
+
+            messages.append(message_dict)
+
+        return messages
+
+    def _estimate_tokens(self, text: str) -> int:
+        """
+        Count tokens in text using accurate tokenization.
+
+        Args:
+            text: Text to count tokens for
+
+        Returns:
+            Number of tokens
+        """
+        return self.token_counter.count_tokens(text)
+
+    def _get_conversation_tokens(self) -> int:
+        """Get total tokens in conversation using cached count."""
+        return self._total_tokens
+
+    def _remove_message_at_index(self, index: int) -> None:
+        """
+        Remove a message at the specified index and update token count.
+
+        Args:
+            index: Index of message to remove
+        """
+        if 0 <= index < len(self.history):
+            message = self.history[index]
+            # Decrement total token count by this message's token count
+            if message.token_count is not None:
+                self._total_tokens -= message.token_count
+            self.history.pop(index)
+
+    def _trim_if_needed(self) -> None:
+        """
+        Trim conversation history if it exceeds token or message limits.
+        Preserves most recent messages and system prompt.
+        """
+        # Check message count limit
+        if len(self.history) > self.max_messages:
+            # Keep system prompt and most recent messages
+            system_messages = [
+                msg for msg in self.history if msg.role == MessageRole.SYSTEM
+            ]
+            recent_messages = self.history[-self.max_messages:]
+            self.history = system_messages + recent_messages[-self.max_messages + len(system_messages):]
+
+            # Recalculate total tokens after message count trimming
+            self._recalculate_total_tokens()
+
+        # Check token limit - remove oldest non-system messages until under limit
+        while self._total_tokens > self.max_tokens and len(self.history) > 2:
+            # Find oldest non-system message to remove
+            for i, msg in enumerate(self.history):
+                if msg.role != MessageRole.SYSTEM:
+                    self._remove_message_at_index(i)
+                    break
+            else:
+                # No non-system messages found, break to avoid infinite loop
+                break
+
+    def _recalculate_total_tokens(self) -> None:
+        """Recalculate total token count from scratch (used after major restructuring)."""
+        self._total_tokens = 0
+        for msg in self.history:
+            if msg.token_count is not None:
+                self._total_tokens += msg.token_count
+            else:
+                # Recalculate token count if not cached
+                token_count = self._estimate_tokens(msg.content)
+                msg.token_count = token_count
+                self._total_tokens += token_count
+
+    def clear_conversation(self, keep_system: bool = True) -> None:
+        """
+        Clear conversation history.
+
+        Args:
+            keep_system: Whether to preserve system prompt
+        """
+        if keep_system:
+            system_messages = [
+                msg for msg in self.history if msg.role == MessageRole.SYSTEM
+            ]
+            self.history = system_messages
+            # Recalculate total tokens for remaining system messages
+            self._recalculate_total_tokens()
+        else:
+            self.history = []
+            self._total_tokens = 0
+
+    def set_system_prompt(self, prompt: str) -> None:
+        """Set or update the system prompt."""
+        # Set the system prompt attribute
+        self.system_prompt = prompt
+
+        # Remove existing system messages and update token count
+        for i in range(len(self.history) - 1, -1, -1):
+            if self.history[i].role == MessageRole.SYSTEM:
+                self._remove_message_at_index(i)
+
+        # Add new system prompt at beginning
+        token_count = self._estimate_tokens(prompt)
+        system_message = ConversationMessage(
+            role=MessageRole.SYSTEM, content=prompt, token_count=token_count
+        )
+        self.history.insert(0, system_message)
+        self._total_tokens += token_count
+
+    def get_conversation_summary(self) -> Dict[str, any]:
+        """
+        Get conversation statistics and summary.
+
+        Returns:
+            Dictionary with conversation metrics
+        """
+        # Filter out messages with None timestamps for min/max calculations
+        messages_with_timestamps = [
+            msg for msg in self.history if msg.timestamp is not None
+        ]
+
+        # Calculate thinking time statistics
+        assistant_messages_with_time = [
+            msg
+            for msg in self.history
+            if msg.role == MessageRole.ASSISTANT and msg.thinking_time is not None
+        ]
+        thinking_times = [msg.thinking_time for msg in assistant_messages_with_time]
+
+        thinking_stats = {}
+        if thinking_times:
+            thinking_stats = {
+                "total_thinking_time": sum(thinking_times),
+                "average_thinking_time": sum(thinking_times) / len(thinking_times),
+                "min_thinking_time": min(thinking_times),
+                "max_thinking_time": max(thinking_times),
+                "thinking_time_count": len(thinking_times),
+            }
+
+        return {
+            "total_messages": len(self.history),
+            "estimated_tokens": self._total_tokens,
+            "user_messages": len(
+                [msg for msg in self.history if msg.role == MessageRole.USER]
+            ),
+            "assistant_messages": len(
+                [msg for msg in self.history if msg.role == MessageRole.ASSISTANT]
+            ),
+            "tool_messages": len(
+                [msg for msg in self.history if msg.role == MessageRole.TOOL]
+            ),
+            "oldest_message": (
+                min([msg.timestamp for msg in messages_with_timestamps])
+                if messages_with_timestamps
+                else None
+            ),
+            "newest_message": (
+                max([msg.timestamp for msg in messages_with_timestamps])
+                if messages_with_timestamps
+                else None
+            ),
+            **thinking_stats,
+        }
+
+    def add_tool_call_sequence(
+        self, tool_calls: List[Dict], tool_results: List[Dict]
+    ) -> None:
+        """
+        Add a complete tool call sequence to conversation history.
+
+        Args:
+            tool_calls: List of tool call requests from LLM
+            tool_results: List of tool execution results
+        """
+        # Add tool calls as assistant message with tool_calls field
+        if tool_calls:
+            # Create a single assistant message with all tool calls
+            self.add_message(
+                role=MessageRole.ASSISTANT,
+                content="",  # Tool calls don't have content
+                tool_call_id=None,  # This will be handled specially in get_messages
+            )
+            # Store tool calls for this assistant message
+            self.history[-1].tool_calls = tool_calls
+
+        # Add tool results
+        for result in tool_results:
+            self.add_message(
+                role=MessageRole.TOOL,
+                content=result.get("output", ""),
+                tool_call_id=result.get("tool_call_id"),
+            )
+
+    def get_recent_context(self, num_messages: int = 5) -> List[ConversationMessage]:
+        """
+        Get recent conversation context for analysis.
+
+        Args:
+            num_messages: Number of recent messages to return
+
+        Returns:
+            List of recent conversation messages
+        """
+        return self.history[-num_messages:] if self.history else []

todo_agent/core/exceptions.py

@@ -0,0 +1,27 @@
+"""
+Domain-specific exceptions for todo.sh operations.
+"""
+
+
+class TodoError(Exception):
+    """Base exception for todo operations."""
+
+    pass
+
+
+class TaskNotFoundError(TodoError):
+    """Task not found in todo file."""
+
+    pass
+
+
+class InvalidTaskFormatError(TodoError):
+    """Invalid task format."""
+
+    pass
+
+
+class TodoShellError(TodoError):
+    """Subprocess execution error."""
+
+    pass

todo_agent/core/todo_manager.py

@@ -0,0 +1,194 @@
+"""
+Todo.sh operations orchestration and business logic.
+"""
+
+from typing import Optional
+from datetime import datetime
+
+
+class TodoManager:
+    """Orchestrates todo.sh operations with business logic."""
+
+    def __init__(self, todo_shell):
+        self.todo_shell = todo_shell
+
+    def add_task(
+        self,
+        description: str,
+        priority: Optional[str] = None,
+        project: Optional[str] = None,
+        context: Optional[str] = None,
+        due: Optional[str] = None,
+    ) -> str:
+        """Add new task with explicit project/context parameters."""
+        # Build the full task description with priority, project, and context
+        full_description = description
+        
+        if priority:
+            full_description = f"({priority}) {full_description}"
+        
+        if project:
+            full_description = f"{full_description} +{project}"
+        
+        if context:
+            full_description = f"{full_description} @{context}"
+        
+        if due:
+            full_description = f"{full_description} due:{due}"
+        
+        result = self.todo_shell.add(full_description)
+        return f"Added task: {full_description}"
+
+    def list_tasks(self, filter: Optional[str] = None) -> str:
+        """List tasks with optional filtering."""
+        result = self.todo_shell.list_tasks(filter)
+        if not result.strip():
+            return "No tasks found."
+        
+        # Return the raw todo.txt format for the LLM to format conversationally
+        # The LLM will convert this into natural language in its response
+        return result
+
+    def complete_task(self, task_number: int) -> str:
+        """Mark task complete by line number."""
+        result = self.todo_shell.complete(task_number)
+        return f"Completed task {task_number}: {result}"
+
+    def get_overview(self, **kwargs) -> str:
+        """Show current task statistics."""
+        tasks = self.todo_shell.list_tasks()
+        completed = self.todo_shell.list_completed()
+        
+        task_count = len([line for line in tasks.split('\n') if line.strip()]) if tasks.strip() else 0
+        completed_count = len([line for line in completed.split('\n') if line.strip()]) if completed.strip() else 0
+        
+        return f"Task Overview:\n- Active tasks: {task_count}\n- Completed tasks: {completed_count}"
+
+    def replace_task(self, task_number: int, new_description: str) -> str:
+        """Replace entire task content."""
+        result = self.todo_shell.replace(task_number, new_description)
+        return f"Replaced task {task_number}: {result}"
+
+    def append_to_task(self, task_number: int, text: str) -> str:
+        """Add text to end of existing task."""
+        result = self.todo_shell.append(task_number, text)
+        return f"Appended to task {task_number}: {result}"
+
+    def prepend_to_task(self, task_number: int, text: str) -> str:
+        """Add text to beginning of existing task."""
+        result = self.todo_shell.prepend(task_number, text)
+        return f"Prepended to task {task_number}: {result}"
+
+    def delete_task(self, task_number: int, term: Optional[str] = None) -> str:
+        """Delete entire task or specific term from task."""
+        result = self.todo_shell.delete(task_number, term)
+        if term:
+            return f"Removed '{term}' from task {task_number}: {result}"
+        else:
+            return f"Deleted task {task_number}: {result}"
+
+    def set_priority(self, task_number: int, priority: str) -> str:
+        """Set or change task priority (A-Z)."""
+        result = self.todo_shell.set_priority(task_number, priority)
+        return f"Set priority {priority} for task {task_number}: {result}"
+
+    def remove_priority(self, task_number: int) -> str:
+        """Remove priority from task."""
+        result = self.todo_shell.remove_priority(task_number)
+        return f"Removed priority from task {task_number}: {result}"
+
+    def list_projects(self, **kwargs) -> str:
+        """List all available projects in todo.txt."""
+        result = self.todo_shell.list_projects()
+        if not result.strip():
+            return "No projects found."
+        return result
+
+    def list_contexts(self, **kwargs) -> str:
+        """List all available contexts in todo.txt."""
+        result = self.todo_shell.list_contexts()
+        if not result.strip():
+            return "No contexts found."
+        return result
+
+    def list_completed_tasks(
+        self, 
+        filter: Optional[str] = None,
+        project: Optional[str] = None,
+        context: Optional[str] = None,
+        text_search: Optional[str] = None,
+        date_from: Optional[str] = None,
+        date_to: Optional[str] = None,
+        **kwargs
+    ) -> str:
+        """List completed tasks with optional filtering.
+        
+        Args:
+            filter: Raw filter string (e.g., '+work', '@office')
+            project: Filter by project (without + symbol)
+            context: Filter by context (without @ symbol)
+            text_search: Search for text in task descriptions
+            date_from: Filter tasks completed from this date (YYYY-MM-DD)
+            date_to: Filter tasks completed until this date (YYYY-MM-DD)
+        """
+        # Build filter string from individual parameters
+        filter_parts = []
+        
+        if filter:
+            filter_parts.append(filter)
+        
+        if project:
+            filter_parts.append(f"+{project}")
+            
+        if context:
+            filter_parts.append(f"@{context}")
+            
+        if text_search:
+            filter_parts.append(text_search)
+            
+        # Handle date filtering - todo.sh supports direct date pattern matching
+        # LIMITATIONS: Due to todo.sh constraints, complex date ranges are not supported.
+        # The filtering behavior is:
+        # - date_from + date_to: Uses year-month pattern (YYYY-MM) from date_from for month-based filtering
+        # - date_from only: Uses exact date pattern (YYYY-MM-DD) for precise date matching
+        # - date_to only: Uses year-month pattern (YYYY-MM) from date_to for month-based filtering
+        # - Complex ranges spanning multiple months are not supported by todo.sh
+        if date_from and date_to:
+            # For a date range, we'll use the year-month pattern from date_from
+            # This will match all tasks in that month
+            filter_parts.append(date_from[:7])  # YYYY-MM format
+        elif date_from:
+            # For single date, use the full date pattern
+            filter_parts.append(date_from)
+        elif date_to:
+            # For end date only, we'll use the year-month pattern
+            # This will match all tasks in that month
+            filter_parts.append(date_to[:7])  # YYYY-MM format
+        
+        # Combine all filters
+        combined_filter = " ".join(filter_parts) if filter_parts else None
+        
+        result = self.todo_shell.list_completed(combined_filter)
+        if not result.strip():
+            return "No completed tasks found matching the criteria."
+        return result
+
+    def move_task(self, task_number: int, destination: str, source: Optional[str] = None) -> str:
+        """Move task from source to destination file."""
+        result = self.todo_shell.move(task_number, destination, source)
+        return f"Moved task {task_number} to {destination}: {result}"
+
+    def archive_tasks(self, **kwargs) -> str:
+        """Archive completed tasks."""
+        result = self.todo_shell.archive()
+        return f"Archived tasks: {result}"
+
+    def deduplicate_tasks(self, **kwargs) -> str:
+        """Remove duplicate tasks."""
+        result = self.todo_shell.deduplicate()
+        return f"Deduplicated tasks: {result}"
+
+    def get_current_datetime(self, **kwargs) -> str:
+        """Get the current date and time."""
+        now = datetime.now()
+        return f"Current date and time: {now.strftime('%Y-%m-%d %H:%M:%S')} ({now.strftime('%A, %B %d, %Y at %I:%M %p')})"

todo_agent/infrastructure/__init__.py

@@ -0,0 +1,11 @@
+"""
+Infrastructure layer for todo.sh LLM agent.
+
+This module contains external integrations and system operations.
+"""
+
+from .config import Config
+from .openrouter_client import OpenRouterClient
+from .todo_shell import TodoShell
+
+__all__ = ["OpenRouterClient", "TodoShell", "Config"]

todo_agent/infrastructure/config.py

@@ -0,0 +1,59 @@
+"""
+Configuration management for todo.sh LLM agent.
+"""
+
+import os
+
+
+class Config:
+    """Environment and configuration management."""
+
+    DEFAULT_MODEL = "openai/gpt-4o-mini"
+    # DEFAULT_MODEL = "mistralai/mistral-small-3.1-24b-instruct"
+
+    def __init__(self):
+        # Provider selection
+        self.provider = os.getenv("LLM_PROVIDER", "openrouter")
+        
+        # OpenRouter configuration
+        self.openrouter_api_key = os.getenv("OPENROUTER_API_KEY")
+        self.openrouter_model = os.getenv("OPENROUTER_MODEL", self.DEFAULT_MODEL)
+        
+        # Ollama configuration
+        self.ollama_base_url = os.getenv("OLLAMA_BASE_URL", "http://localhost:11434")
+        self.ollama_model = os.getenv("OLLAMA_MODEL", "mistral-small3.1")
+        
+        # Common configuration
+        self.model = self._get_model_for_provider()
+        self.log_level = os.getenv("LOG_LEVEL", "INFO")
+        self.todo_file_path = os.getenv("TODO_FILE", "todo.txt")
+
+    def _get_model_for_provider(self) -> str:
+        """Get model name for current provider."""
+        if self.provider == "openrouter":
+            return self.openrouter_model
+        elif self.provider == "ollama":
+            return self.ollama_model
+        return self.openrouter_model  # fallback
+
+    def validate(self) -> bool:
+        """Validate required configuration."""
+        if self.provider == "openrouter":
+            if not self.openrouter_api_key:
+                raise ValueError("OPENROUTER_API_KEY environment variable is required for OpenRouter provider")
+        elif self.provider == "ollama":
+            # Ollama doesn't require API key, but we could validate the base URL is reachable
+            pass
+        else:
+            raise ValueError(f"Unsupported LLM provider: {self.provider}")
+        return True
+
+    @property
+    def todo_dir(self) -> str:
+        """Get todo.sh directory path."""
+        return os.path.dirname(self.todo_file_path)
+
+    @property
+    def done_file_path(self) -> str:
+        """Get done.txt file path."""
+        return os.path.join(self.todo_dir, "done.txt")