tunacode-cli 0.0.55__py3-none-any.whl → 0.0.78.6__py3-none-any.whl

tunacode/tools/xml_helper.py

@@ -0,0 +1,83 @@
+"""Helper module for loading prompts and schemas from XML files."""
+
+import logging
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+import defusedxml.ElementTree as ET
+
+logger = logging.getLogger(__name__)
+
+
+@lru_cache(maxsize=32)
+def load_prompt_from_xml(tool_name: str) -> Optional[str]:
+    """Load and return the base prompt from XML file.
+
+    Args:
+        tool_name: Name of the tool (e.g., 'grep', 'glob')
+
+    Returns:
+        str: The loaded prompt from XML or None if not found
+    """
+    try:
+        prompt_file = Path(__file__).parent / "prompts" / f"{tool_name}_prompt.xml"
+        if prompt_file.exists():
+            tree = ET.parse(prompt_file)
+            root = tree.getroot()
+            description = root.find("description")
+            if description is not None:
+                return description.text.strip()
+    except Exception as e:
+        logger.warning(f"Failed to load XML prompt for {tool_name}: {e}")
+    return None
+
+
+@lru_cache(maxsize=32)
+def load_parameters_schema_from_xml(tool_name: str) -> Optional[Dict[str, Any]]:
+    """Load and return the parameters schema from XML file.
+
+    Args:
+        tool_name: Name of the tool (e.g., 'grep', 'glob')
+
+    Returns:
+        Dict containing the JSON schema for tool parameters or None if not found
+    """
+    try:
+        prompt_file = Path(__file__).parent / "prompts" / f"{tool_name}_prompt.xml"
+        if prompt_file.exists():
+            tree = ET.parse(prompt_file)
+            root = tree.getroot()
+            parameters = root.find("parameters")
+            if parameters is not None:
+                schema: Dict[str, Any] = {"type": "object", "properties": {}, "required": []}
+                required_fields: List[str] = []
+
+                for param in parameters.findall("parameter"):
+                    name = param.get("name")
+                    required = param.get("required", "false").lower() == "true"
+                    param_type = param.find("type")
+                    description = param.find("description")
+
+                    if name and param_type is not None:
+                        prop = {
+                            "type": param_type.text.strip(),
+                            "description": description.text.strip()
+                            if description is not None
+                            else "",
+                        }
+
+                        # Add enum values if present
+                        enums = param.findall("enum")
+                        if enums:
+                            prop["enum"] = [e.text.strip() for e in enums]
+
+                        schema["properties"][name] = prop
+                        if required:
+                            required_fields.append(name)
+
+                schema["required"] = required_fields
+                return schema
+    except Exception as e:
+        logger.warning(f"Failed to load parameters from XML for {tool_name}: {e}")
+    return None

tunacode/tutorial/__init__.py

@@ -0,0 +1,9 @@
+"""
+Module: tunacode.tutorial
+
+Tutorial system for TunaCode onboarding and user guidance.
+"""
+
+from .manager import TutorialManager
+
+__all__ = ["TutorialManager"]

tunacode/tutorial/content.py

@@ -0,0 +1,98 @@
+"""
+Module: tunacode.tutorial.content
+
+Tutorial content definitions and step configurations.
+"""
+
+from typing import Dict, List
+
+# Tutorial step content library
+TUTORIAL_CONTENT: Dict[str, Dict[str, str]] = {
+    "welcome": {
+        "title": "🎯 Welcome to TunaCode!",
+        "content": """TunaCode is your AI-powered development assistant.
+
+In this quick tutorial, you'll learn how to:
+• Chat with AI about your code
+• Use commands to control TunaCode
+• Work with files and projects
+• Get help when you need it
+
+This tutorial takes about 2-3 minutes. Ready to start?""",
+        "action": "Press Enter to continue...",
+    },
+    "basic_chat": {
+        "title": "💬 Basic AI Chat",
+        "content": """The core of TunaCode is natural conversation with AI.
+
+You can ask questions like:
+• "How do I implement a binary search in Python?"
+• "Review this function and suggest improvements"
+• "Help me debug this error message"
+• "Explain what this code does"
+
+Just type your question naturally - no special syntax needed!""",
+        "action": "Try asking: 'What can you help me with?'",
+    },
+    "file_operations": {
+        "title": "📁 Working with Files",
+        "content": """TunaCode can read, create, and modify files in your project.
+
+Useful commands:
+• Reference files with @filename.py
+• Use /read to explicitly read files
+• Ask to create or modify files
+• Get help with /help
+
+TunaCode understands your project structure and can work across multiple files.""",
+        "action": "Try: 'Read the current directory structure'",
+    },
+    "commands": {
+        "title": "⚙️ TunaCode Commands",
+        "content": """Commands start with / and give you control over TunaCode:
+
+Essential commands:
+• /help - Show all available commands
+• /model - Switch AI models
+• /clear - Clear conversation history
+• /exit - Exit TunaCode
+
+System commands:
+• !command - Run shell commands
+• /streaming - Toggle streaming responses""",
+        "action": "Try typing: /help",
+    },
+    "best_practices": {
+        "title": "✨ Best Practices",
+        "content": """To get the most out of TunaCode:
+
+🎯 Be specific: "Fix the bug in login.py line 42" vs "fix my code"
+📁 Use file references: "@app.py" to include files in context
+🔄 Break down large tasks: Ask for step-by-step guidance
+💬 Ask follow-up questions: TunaCode remembers your conversation
+🚀 Experiment: Try different prompts to see what works best
+
+Remember: TunaCode is here to help you code faster and better!""",
+        "action": "Press Enter to complete the tutorial...",
+    },
+    "completion": {
+        "title": "🎉 Tutorial Complete!",
+        "content": """Congratulations! You're ready to use TunaCode.
+
+Quick recap:
+✅ Chat naturally with AI about code
+✅ Use @ to reference files
+✅ Try /help for commands
+✅ Ask specific questions for better results
+
+🚀 Ready to start coding? Just ask TunaCode anything!
+
+Need help later? Use /quickstart to review this tutorial anytime.""",
+        "action": "Press Enter to start using TunaCode...",
+    },
+}
+
+
+def get_tutorial_steps() -> List[str]:
+    """Get the ordered list of tutorial step IDs."""
+    return ["welcome", "basic_chat", "file_operations", "commands", "best_practices", "completion"]

tunacode/tutorial/manager.py

@@ -0,0 +1,182 @@
+"""
+Module: tunacode.tutorial.manager
+
+Tutorial manager for orchestrating the TunaCode onboarding experience.
+"""
+
+import logging
+
+from ..types import StateManager
+from ..ui import console as ui
+from .steps import (
+    create_tutorial_steps,
+    is_first_time_user,
+    is_tutorial_completed,
+    is_tutorial_declined,
+    load_tutorial_progress,
+    mark_tutorial_completed,
+    mark_tutorial_declined,
+    save_tutorial_progress,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class TutorialManager:
+    """Manages the tutorial experience for TunaCode users."""
+
+    def __init__(self, state_manager: StateManager):
+        self.state_manager = state_manager
+        self.steps = [
+            "welcome",
+            "basic_chat",
+            "file_operations",
+            "commands",
+            "best_practices",
+            "completion",
+        ]
+
+    async def should_offer_tutorial(self) -> bool:
+        """Determine if we should offer the tutorial to the user."""
+        # Don't offer if already completed or declined
+        if is_tutorial_completed(self.state_manager):
+            return False
+
+        if is_tutorial_declined(self.state_manager):
+            return False
+
+        # Check if tutorial is enabled in settings
+        settings = self.state_manager.session.user_config.get("settings", {})
+        tutorial_enabled = settings.get("enable_tutorial", True)
+
+        if not tutorial_enabled:
+            return False
+
+        # Only offer to first-time users (installed within last 7 days)
+        if not is_first_time_user(self.state_manager):
+            return False
+
+        # Check if this is a fresh session (no significant interaction yet)
+        message_count = len(self.state_manager.session.messages)
+
+        # Offer tutorial if user has minimal interaction history
+        return message_count < 3
+
+    async def offer_tutorial(self) -> bool:
+        """Offer the tutorial to the user and return whether they accepted."""
+        await ui.panel(
+            "🎯 Welcome to TunaCode!",
+            "Would you like a quick 2-minute tutorial to get started?\n"
+            "This will help you learn the basics and start coding faster.",
+            border_style="cyan",
+        )
+
+        choice = await ui.input(
+            "tutorial_offer",
+            pretext="  → Start tutorial? [Y/n]: ",
+            state_manager=self.state_manager,
+        )
+
+        choice = choice.strip().lower()
+
+        if choice in ["n", "no", "false"]:
+            await ui.muted("Tutorial skipped. Use [green]/quickstart[/green] anytime to start it!")
+            # Mark as declined so we don't ask again
+            mark_tutorial_declined(self.state_manager)
+
+            # Save the configuration to persist the declined status
+            try:
+                from ..utils import user_configuration
+
+                user_configuration.save_config(self.state_manager)
+            except Exception as e:
+                logger.warning(f"Failed to save tutorial declined status: {e}")
+
+            return False
+
+        return True
+
+    async def run_tutorial(self, resume: bool = False) -> bool:
+        """
+        Run the complete tutorial experience.
+
+        Args:
+            resume: If True, resume from saved progress
+
+        Returns:
+            True if tutorial completed successfully, False if cancelled
+        """
+        try:
+            from .content import TUTORIAL_CONTENT
+
+            # Load progress or start from beginning
+            current_step = load_tutorial_progress(self.state_manager) if resume else 0
+            steps = create_tutorial_steps()
+
+            await ui.line()
+            await ui.info(f"🎯 Starting TunaCode Tutorial ({len(steps)} steps)")
+            await ui.line()
+
+            while current_step < len(steps):
+                step_id = steps[current_step]
+                step_content = TUTORIAL_CONTENT.get(step_id, {})
+
+                if not step_content:
+                    logger.warning(f"Missing content for tutorial step: {step_id}")
+                    current_step += 1
+                    continue
+
+                # Display step content
+                await ui.panel(
+                    f"Step {current_step + 1}/{len(steps)}: {step_content.get('title', step_id)}",
+                    step_content.get("content", ""),
+                    border_style="cyan",
+                )
+
+                # Get user input for progression
+                action_text = step_content.get("action", "Press Enter to continue...")
+                try:
+                    user_input = await ui.input(
+                        f"tutorial_step_{current_step}",
+                        pretext=f"  → {action_text} ",
+                        state_manager=self.state_manager,
+                    )
+
+                    # Allow users to exit tutorial early
+                    if user_input.lower() in ["quit", "exit", "skip"]:
+                        await ui.info(
+                            "Tutorial cancelled. Use [green]/quickstart[/green] to restart anytime!"
+                        )
+                        return False
+
+                except Exception as e:
+                    logger.warning(f"Tutorial interrupted: {e}")
+                    # Save progress before exiting
+                    save_tutorial_progress(self.state_manager, current_step)
+                    await ui.info("Tutorial paused. Use [green]/quickstart[/green] to resume!")
+                    return False
+
+                current_step += 1
+                save_tutorial_progress(self.state_manager, current_step)
+
+            # Tutorial completed successfully
+            mark_tutorial_completed(self.state_manager)
+
+            # Save the completion status
+            try:
+                from ..utils import user_configuration
+
+                user_configuration.save_config(self.state_manager)
+            except Exception as e:
+                logger.warning(f"Failed to save tutorial completion status: {e}")
+
+            await ui.line()
+            await ui.success("🎉 Tutorial completed! You're ready to use TunaCode.")
+            await ui.line()
+
+            return True
+
+        except Exception as e:
+            logger.error(f"Tutorial failed: {e}")
+            await ui.error(f"Tutorial encountered an error: {e}")
+            return False

tunacode/tutorial/steps.py

@@ -0,0 +1,124 @@
+"""
+Module: tunacode.tutorial.steps
+
+Tutorial step management and progress tracking functionality.
+"""
+
+import logging
+from dataclasses import dataclass
+from typing import List, Optional
+
+from ..types import StateManager
+from .content import get_tutorial_steps
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class TutorialStepResult:
+    """Result of executing a tutorial step."""
+
+    completed: bool
+    should_continue: bool
+    user_input: Optional[str] = None
+
+
+def create_tutorial_steps() -> List[str]:
+    """Create and return the list of tutorial steps."""
+    return get_tutorial_steps()
+
+
+def get_tutorial_completion_key() -> str:
+    """Get the config key for storing tutorial completion status."""
+    return "tutorial_completed"
+
+
+def get_tutorial_progress_key() -> str:
+    """Get the config key for storing tutorial progress."""
+    return "tutorial_progress"
+
+
+def mark_tutorial_completed(state_manager: StateManager) -> None:
+    """Mark the tutorial as completed in user config."""
+    if "settings" not in state_manager.session.user_config:
+        state_manager.session.user_config["settings"] = {}
+
+    state_manager.session.user_config["settings"][get_tutorial_completion_key()] = True
+
+    # Clear any existing progress since it's now completed
+    if get_tutorial_progress_key() in state_manager.session.user_config["settings"]:
+        del state_manager.session.user_config["settings"][get_tutorial_progress_key()]
+
+
+def save_tutorial_progress(state_manager: StateManager, current_step: int) -> None:
+    """Save tutorial progress to user config."""
+    if "settings" not in state_manager.session.user_config:
+        state_manager.session.user_config["settings"] = {}
+
+    state_manager.session.user_config["settings"][get_tutorial_progress_key()] = current_step
+
+
+def load_tutorial_progress(state_manager: StateManager) -> int:
+    """Load tutorial progress from user config."""
+    settings = state_manager.session.user_config.get("settings", {})
+    return settings.get(get_tutorial_progress_key(), 0)
+
+
+def clear_tutorial_progress(state_manager: StateManager) -> None:
+    """Clear tutorial progress from user config."""
+    if "settings" not in state_manager.session.user_config:
+        return
+
+    if get_tutorial_progress_key() in state_manager.session.user_config["settings"]:
+        del state_manager.session.user_config["settings"][get_tutorial_progress_key()]
+
+
+def is_tutorial_completed(state_manager: StateManager) -> bool:
+    """Check if the tutorial has been completed."""
+    settings = state_manager.session.user_config.get("settings", {})
+    return settings.get(get_tutorial_completion_key(), False)
+
+
+def get_tutorial_declined_key() -> str:
+    """Get the config key for storing tutorial declined status."""
+    return "tutorial_declined"
+
+
+def mark_tutorial_declined(state_manager: StateManager) -> None:
+    """Mark the tutorial as declined in user config."""
+    if "settings" not in state_manager.session.user_config:
+        state_manager.session.user_config["settings"] = {}
+
+    state_manager.session.user_config["settings"][get_tutorial_declined_key()] = True
+
+    # Clear any existing progress since it was declined
+    if get_tutorial_progress_key() in state_manager.session.user_config["settings"]:
+        del state_manager.session.user_config["settings"][get_tutorial_progress_key()]
+
+
+def is_tutorial_declined(state_manager: StateManager) -> bool:
+    """Check if the tutorial has been declined."""
+    settings = state_manager.session.user_config.get("settings", {})
+    return settings.get(get_tutorial_declined_key(), False)
+
+
+def is_first_time_user(state_manager: StateManager) -> bool:
+    """Check if this is a first-time user based on installation date."""
+    from datetime import datetime, timedelta
+
+    settings = state_manager.session.user_config.get("settings", {})
+    installation_date_str = settings.get("first_installation_date")
+
+    if not installation_date_str:
+        # No installation date means legacy user, treat as experienced
+        return False
+
+    try:
+        installation_date = datetime.fromisoformat(installation_date_str)
+        now = datetime.now()
+
+        # Consider first-time if installed within last 7 days
+        return (now - installation_date) <= timedelta(days=7)
+    except (ValueError, TypeError):
+        # Invalid date format, treat as experienced user
+        return False

tunacode/types.py

@@ -6,7 +6,9 @@ used throughout the TunaCode codebase.
 """
 
 from dataclasses import dataclass, field
-from datetime import datetime
+
+# Plan types will be defined below
+from enum import Enum
 from pathlib import Path
 from typing import (
     Any,
@@ -14,39 +16,20 @@ from typing import (
     Callable,
     Dict,
     List,
-    Literal,
     Optional,
     Protocol,
     Tuple,
     Union,
 )
 
-# Try to import pydantic-ai types if available
-try:
-    from pydantic_ai import Agent
-    from pydantic_ai.messages import ModelRequest, ToolReturnPart
-
-    PydanticAgent = Agent
-    MessagePart = Union[ToolReturnPart, Any]
-    ModelRequest = ModelRequest  # type: ignore[misc]
-    ModelResponse = Any
-except ImportError:
-    # Fallback if pydantic-ai is not available
-    PydanticAgent = Any
-    MessagePart = Any  # type: ignore[misc]
-    ModelRequest = Any
-    ModelResponse = Any  # type: ignore[misc]
+# Import pydantic-ai types (required dependency)
+from pydantic_ai import Agent
+from pydantic_ai.messages import ModelRequest, ToolReturnPart
 
-
-@dataclass
-class TodoItem:
-    id: str
-    content: str
-    status: Literal["pending", "in_progress", "completed"]
-    priority: Literal["high", "medium", "low"]
-    created_at: datetime
-    completed_at: Optional[datetime] = None
-    tags: list[str] = field(default_factory=list)
+PydanticAgent = Agent
+MessagePart = Union[ToolReturnPart, Any]
+ModelRequest = ModelRequest  # type: ignore[misc]
+ModelResponse = Any
 
 
 # =============================================================================
@@ -126,6 +109,7 @@ class ToolConfirmationResponse:
     approved: bool
     skip_future: bool = False
     abort: bool = False
+    instructions: str = ""
 
 
 # =============================================================================
@@ -192,6 +176,15 @@ class SimpleResult:
     output: str
 
 
+class AgentState(Enum):
+    """Agent loop states for enhanced completion detection."""
+
+    USER_INPUT = "user_input"  # Initial: user prompt received
+    ASSISTANT = "assistant"  # Reasoning/deciding phase
+    TOOL_EXECUTION = "tool_execution"  # Tool execution phase
+    RESPONSE = "response"  # Handling results, may complete or loop
+
+
 # =============================================================================
 # Session and State Types
 # =============================================================================