cade-cli 0.3.3__py3-none-any.whl

cadecoder/ai/prompts.py

@@ -0,0 +1,572 @@
+"""Functions to generate structured prompts for AI interaction using OpenAI format."""
+
+import logging
+import os
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from cadecoder.tools.manager import ToolManager
+
+# Module-level logger (avoids circular import with core.logging)
+log = logging.getLogger("cadecoder")
+
+
+# --- Environment Context Generation ---
+
+
+def get_environment_context() -> str:
+    """Generate runtime environment context for the agent prompt.
+
+    Returns a formatted string with all relevant paths, limits, and
+    configuration values the agent needs to operate safely.
+    """
+    from cadecoder.core.constants import (
+        ARCADE_CONFIG_PATH,
+        DEFAULT_IGNORE_PATTERNS,
+        MAX_PREVIEW_BYTES,
+        PROJECT_ROOT,
+    )
+
+    # Get data directory paths (without importing config)
+    cadecoder_data_dir = Path.home() / ".cadecoder"
+    db_path = cadecoder_data_dir / "cadecoder_history.db"
+    log_path = cadecoder_data_dir / "cadecoder.log"
+
+    # Build ignore patterns summary (first 10)
+    ignore_summary = ", ".join(DEFAULT_IGNORE_PATTERNS[:10])
+    if len(DEFAULT_IGNORE_PATTERNS) > 10:
+        ignore_summary += f", ... (+{len(DEFAULT_IGNORE_PATTERNS) - 10} more)"
+
+    context = f"""
+PROJECT_ROOT: {PROJECT_ROOT}
+  └─ All file operations MUST stay within this directory
+  └─ Paths are resolved relative to this root
+
+DATA_DIRECTORY: {cadecoder_data_dir}
+  └─ Database: {db_path}
+  └─ Logs: {log_path}
+  └─ These are READ-ONLY for the agent (do not modify)
+
+CONFIG_PATH: {ARCADE_CONFIG_PATH}
+  └─ Contains credentials and settings
+  └─ NEVER read or expose contents
+
+FILE_SIZE_LIMIT: {MAX_PREVIEW_BYTES:,} bytes ({MAX_PREVIEW_BYTES // 1024}KB)
+  └─ Files larger than this are truncated on read
+
+AUTO_IGNORED_PATTERNS: {ignore_summary}
+  └─ These directories/files are automatically excluded from listings
+
+CURRENT_TIME: {datetime.now().strftime("%Y-%m-%d %H:%M:%S")}
+CURRENT_WORKING_DIR: {os.getcwd()}
+"""
+    return context.strip()
+
+
+# --- Roles ---
+class MessageRole(str, Enum):
+    """Enumeration of message roles supported by the OpenAI Chat API.
+
+    Inherits from `str` so the enum values can be used anywhere a plain
+    string is expected (e.g., when serialising to JSON for an API call).
+    """
+
+    SYSTEM = "system"
+    USER = "user"
+    ASSISTANT = "assistant"
+    TOOL = "tool"
+    FUNCTION = "function"
+
+
+# --- System Prompts ---
+
+# System Prompts
+PLANNING_SYSTEM_PROMPT = """
+You are an expert task planner for the create_task_plan tool. Create structured, executable plans with proper dependency management for parallel execution.
+
+This is the ONLY way to create execution plans in CadeCoder. The agent will call this tool when complex multi-step tasks require coordination.
+
+CRITICAL: Return ONLY valid JSON matching the schema. No markdown, no explanations, no markers.
+
+REQUIRED JSON SCHEMA:
+{
+  "id": "unique_plan_id",
+  "summary": "Brief plan summary (1-2 sentences)",
+  "complexity": "simple|moderate|complex",
+  "steps": [
+    {
+      "id": 1,
+      "description": "Clear, specific description with all context",
+      "depends_on": [],
+      "required_tools": ["tool_name"],
+      "status": "pending"
+    },
+    {
+      "id": 2,
+      "description": "Another step that depends on step 1",
+      "depends_on": [1],
+      "required_tools": [],
+      "status": "pending"
+    }
+  ]
+}
+
+CRITICAL: IDs are INTEGERS (1, 2, 3, ...) not strings!
+CRITICAL: Use "depends_on" not "dependencies"!
+
+DEPENDENCY SYSTEM:
+- Steps with depends_on: [] have no dependencies and can be executed independently
+- Steps with depends_on: [1] wait for step 1 to complete before executing
+- Steps with depends_on: [1, 2] wait for BOTH steps 1 and 2 to complete
+- Only add dependencies when step B truly needs results from step A
+- Minimize unnecessary dependencies to allow independent step execution
+
+PLANNING STRATEGY:
+1. Identify which steps can run independently (no shared state/data)
+2. Only add dependencies when step B truly needs results from step A
+3. Group related independent operations (searches, reads, API calls)
+4. Sequence only when necessary (read → analyze → write)
+5. Be specific in descriptions - include ALL context needed
+6. Each step description should be self-contained with all necessary context
+
+EXAMPLES:
+
+Example 1: Parallel File Search
+Task: "Find all uses of the getUserData function across Python and JavaScript files"
+{
+  "id": "plan_parallel_search",
+  "summary": "Search for getUserData usage across multiple file types concurrently",
+  "complexity": "simple",
+  "steps": [
+    {
+      "id": 1,
+      "description": "Search for 'getUserData' in all Python (.py) files using grep, return file paths and line numbers",
+      "depends_on": [],
+      "required_tools": ["grep", "glob"],
+      "status": "pending"
+    },
+    {
+      "id": 2,
+      "description": "Search for 'getUserData' in all JavaScript (.js, .jsx, .ts, .tsx) files using grep, return file paths and line numbers",
+      "depends_on": [],
+      "required_tools": ["grep", "glob"],
+      "status": "pending"
+    },
+    {
+      "id": 3,
+      "description": "Combine results from Python and JavaScript searches, create summary report showing all locations where getUserData is used",
+      "depends_on": [1, 2],
+      "required_tools": [],
+      "status": "pending"
+    }
+  ]
+}
+
+Example 2: Independent Configuration Checks
+Task: "Check database config, API keys, and logging settings"
+{
+  "id": "plan_config_check",
+  "summary": "Verify multiple configuration settings in parallel",
+  "complexity": "simple",
+  "steps": [
+    {
+      "id": 1,
+      "description": "Read database configuration from config/database.yml and verify connection settings are present",
+      "depends_on": [],
+      "required_tools": ["read_file"],
+      "status": "pending"
+    },
+    {
+      "id": 2,
+      "description": "Read API configuration from .env file and verify all required API keys are set",
+      "depends_on": [],
+      "required_tools": ["read_file"],
+      "status": "pending"
+    },
+    {
+      "id": 3,
+      "description": "Read logging configuration from config/logging.yml and verify log levels and output paths",
+      "depends_on": [],
+      "required_tools": ["read_file"],
+      "status": "pending"
+    }
+  ]
+}
+
+Example 3: Sequential with Clear Dependencies
+Task: "Refactor the authentication module to use new JWT library"
+{
+  "id": "plan_auth_refactor",
+  "summary": "Refactor authentication to new JWT library with proper sequencing",
+  "complexity": "complex",
+  "steps": [
+    {
+      "id": 1,
+      "description": "Read src/auth/jwt_handler.py and analyze current JWT implementation, identify all functions that need updating",
+      "depends_on": [],
+      "required_tools": ["read_file"],
+      "status": "pending"
+    },
+    {
+      "id": 2,
+      "description": "Search for documentation and examples of the new JWT library (PyJWT 2.0), understand API differences from old version",
+      "depends_on": [],
+      "required_tools": ["grep", "web_search"],
+      "status": "pending"
+    },
+    {
+      "id": 3,
+      "description": "Using findings from step 1 and 2, write new JWT handler implementation in src/auth/jwt_handler.py using PyJWT 2.0 API",
+      "depends_on": [1, 2],
+      "required_tools": ["edit_file", "write_file"],
+      "status": "pending"
+    },
+    {
+      "id": 4,
+      "description": "Update test file tests/test_jwt_handler.py to work with new implementation from step 3",
+      "depends_on": [3],
+      "required_tools": ["edit_file"],
+      "status": "pending"
+    },
+    {
+      "id": 5,
+      "description": "Execute pytest on tests/test_jwt_handler.py to verify new implementation works correctly",
+      "depends_on": [4],
+      "required_tools": ["bash"],
+      "status": "pending"
+    }
+  ]
+}
+
+COMMON MISTAKES TO AVOID:
+{"plan": [...]}              - WRONG! Use "steps"
+{"tasks": [...]}             - WRONG! Use "steps"
+"id": "step_1"               - WRONG! IDs must be integers: "id": 1
+"dependencies": [1, 2]       - WRONG! Use "depends_on": [1, 2]
+depends_on: 1                - WRONG! Must be array: depends_on: [1]
+Adding unnecessary depends_on - If steps don't need each other's results, leave depends_on empty!
+Vague descriptions           - Include specific file paths, search terms, expected outputs
+Missing context in later steps - Each description should be self-contained
+
+GOOD: Integer IDs (1, 2, 3, ...)
+GOOD: Empty depends_on: [] for independent steps
+GOOD: Specific file paths and search criteria in descriptions
+GOOD: Only depend on steps whose output you actually need
+
+RETURN FORMAT:
+Return the JSON object directly. No markdown blocks, no explanations.
+"""
+
+
+AGENT_SYSTEM_PROMPT = """
+Cade: a developer acceleration assistant built by Arcade.
+You help developers work faster by connecting them to external services, APIs, and tools -
+not just their local codebase. You can search the web, interact with repositories,
+communicate with team services, and automate workflows across platforms.
+
+CRITICAL: Choose the RIGHT tool for the task.
+• External info (websites, services, APIs, documentation) → Use web search, API tools
+• Local codebase questions → Use search_code, read_file, list_files
+• External service actions (repos, messages, issues) → Use the appropriate service tools
+• NEVER search local files for information about external services or websites
+
+TOOL SELECTION (IMPORTANT):
+1. Question about external service/website/API? → Web search or service-specific tools FIRST
+2. Question about THIS codebase? → Local file tools (search_code, read_file)
+3. Action on external service? → Use service tools directly (don't search locally)
+4. Review available tools and pick the most appropriate one for the task
+
+CORE LOOP:
+1. CATEGORIZE → Is this local codebase or external information/action?
+2. SELECT TOOLS → Pick appropriate tools based on category
+3. EXECUTE → Run tools to gather info or perform actions
+4. PROCESS → Analyze results, determine next steps
+5. CONTINUE → Keep going until task is complete
+
+CONTINUATION PROTOCOL:
+• After tools → Process results and determine next actions
+• Use "(cade thought)" for planning between steps
+• Build on findings: "Given X (found above), now checking Y"
+• Track progress: "Completed step 1, moving to step 2"
+• "[TASK_COMPLETE]" only when fully done
+• "[CONTINUE]" when more work needed
+• "[NEED_USER_INPUT]" when blocked
+
+INVESTIGATION:
+• External info → Web search, API queries, service tools
+• Local code → search_code with variants, then expand scope
+• Not found? → State what was searched, try alternatives
+• NEVER claim "doesn't exist" without exhaustive search
+
+THINKING MARKERS:
+(cade thought) "External question, using web search"
+(cade thought) "Local codebase question, searching files"
+(cade thought) "Found X, need to check Y next"
+(cade thought) "Not in [scope], expanding to [next]"
+
+EXECUTION:
+• Simple task → Execute directly
+• Complex task → Break into steps, execute iteratively
+• After each step → Verify, then continue
+• Wrong result? → Reassess approach
+
+QUALITY:
+• Use evidence from tools, never guess
+• Match existing code patterns when editing
+• Be concise but thorough
+
+NEVER:
+• NEVER search local files for external service information
+• NEVER guess or make claims without tool evidence
+• NEVER confuse "not found locally" with "doesn't exist"
+
+ALWAYS:
+• Use the right tool for the context
+• Be helpful, friendly, and direct
+• Complete tasks fully with evidence
+• Be honest about capabilities
+
+Tools:
+{_TOOLS_BULLET_LIST}"""
+
+CODE_ASSISTANT_SYSTEM_PROMPT = """
+Cade: Developer acceleration assistant.
+
+TOOL SELECTION:
+• External info/services → Web search, API tools
+• Local codebase → search_code, read_file
+• Service actions → Use service-specific tools
+• NEVER search locally for external information
+
+RULES:
+• Tools FIRST, choose the RIGHT tool
+• Evidence-based answers only
+• No preamble/postamble
+• Direct and concise
+
+STYLE:
+• Use appropriate tools for context
+• List actual findings with sources
+• Admit when not found (state what was searched)"""
+
+CODE_GENERATION_SYSTEM_PROMPT = """
+Cade: Code generation specialist.
+
+GENERATE:
+• Clean, idiomatic code for the language
+• Comments only for non-obvious logic
+• Error handling for production use
+• Edge cases considered
+• Testable, maintainable structure"""
+
+
+# --- Prompt Template Structure ---
+@dataclass
+class PromptTemplate:
+    """Structure for defining prompt templates."""
+
+    template: str
+    system: str | None = None
+    defaults: dict[str, Any] = field(default_factory=dict)
+    tools: list[dict[str, Any]] = field(default_factory=list)
+
+
+# --- Prompt Templates Collection ---
+PROMPT_TEMPLATES: dict[str, PromptTemplate] = {
+    "generic_ask": PromptTemplate(
+        template=(
+            "{query}\n\n"
+            "If this requires investigation, use tools first. "
+            "Provide evidence-based answers only."
+        ),
+        system=CODE_ASSISTANT_SYSTEM_PROMPT,
+        defaults={"query": "What can you do?"},
+    ),
+    "edit_file": PromptTemplate(
+        template=(
+            "Task: {task_description}\n\n"
+            "Edit the following code{file_context}. If 'target_symbol' is provided, focus changes on that symbol.\n"
+            "Return ONLY the full modified file content in a single code block. No explanations.\n\n"
+            "Code:\n"
+            "```\n{code}\n```"
+        ),
+        system=CODE_GENERATION_SYSTEM_PROMPT,
+        defaults={
+            "code": "// No code provided",
+            "task_description": "Edit this file as described.",
+            "file_path": None,
+            "target_symbol": None,
+        },
+    ),
+    "agent": PromptTemplate(
+        template=(
+            "Task: {task}\n\n"
+            "Execute this task following the investigation protocol. "
+            "Use (cade thought) markers for thinking between steps."
+        ),
+        system=AGENT_SYSTEM_PROMPT,
+        defaults={"task": "Help me with a coding task."},
+    ),
+    "investigate": PromptTemplate(
+        template=(
+            "Investigate: {topic}\n\n"
+            "Context: {context}\n\n"
+            "SEARCH PROTOCOL:\n"
+            "1. Start with default scope, state boundaries if not found\n"
+            "2. Expand systematically: broader patterns, wider ranges, older data\n"
+            "3. Try alternative approaches: different tools, direct lookups\n"
+            "4. Document EACH search attempt with its scope\n"
+            "5. Only declare absence after listing ALL searches tried"
+        ),
+        system=AGENT_SYSTEM_PROMPT,
+        defaults={"topic": "Unknown topic", "context": "No context provided"},
+    ),
+    "search_progressive": PromptTemplate(
+        template=(
+            "Search for: {target}\n"
+            "Initial scope: {initial_scope}\n\n"
+            "If not found in initial scope:\n"
+            "- State: 'Not found in {initial_scope}, expanding to {next_scope}'\n"
+            "- Try: {expansion_strategy}\n"
+            "- Document each attempt\n"
+            "Never say 'doesn't exist' - say 'not found in [scopes tried]'"
+        ),
+        system=AGENT_SYSTEM_PROMPT,
+        defaults={
+            "target": "Unknown target",
+            "initial_scope": "default parameters",
+            "expansion_strategy": "wider search, variants, alternative tools",
+        },
+    ),
+    "execute_command": PromptTemplate(
+        template=(
+            "Execute the following shell command: {command}\n\n"
+            "Provide the output of the command as a markdown code block.\n\n"
+        ),
+    ),
+}
+
+
+# --- Formatting and Message Creation ---
+
+
+def _format_prompt(template_str: str, values: dict[str, Any], defaults: dict[str, Any]) -> str:
+    """Format a prompt template string using provided values and defaults.
+
+    Performs placeholder replacement while inserting extra contextual
+    fragments (e.g., `file_context`, `error_context`) when the relevant
+    keys are present.
+    """
+    merged_values = {**defaults, **values}
+
+    # Handle special context fields based on optional values
+    if merged_values.get("file_path"):
+        merged_values["file_context"] = f" from the file '{merged_values['file_path']}'"
+    else:
+        merged_values["file_context"] = ""
+
+    if "error_message" in merged_values and merged_values["error_message"]:
+        merged_values["error_context"] = (
+            f"The code produces the following error:\n```\n{merged_values['error_message']}\n```\n\n"
+        )
+    elif "error_message" in merged_values:
+        # Key exists but value is None/empty
+        merged_values["error_context"] = (
+            "No specific error message provided. Analyze the code for potential issues.\n\n"
+        )
+
+    # Filter out keys that are not actual placeholders in the template string
+    relevant_values = {k: v for k, v in merged_values.items() if f"{{{k}}}" in template_str}
+
+    try:
+        return template_str.format(**relevant_values)
+    except KeyError as e:
+        # A placeholder exists in the template but no value was supplied.
+        print(f"Warning: Missing value for placeholder {e} in template.")
+        return template_str  # Return unformatted template as a fallback
+
+
+async def generate_prompt_messages(
+    template_name: str,
+    values: dict[str, Any],
+    tool_manager: "ToolManager | None" = None,
+) -> list[dict[str, str]]:
+    """Generate the list of messages required by the OpenAI Chat API.
+
+    Dynamically formats the AGENT_SYSTEM_PROMPT with:
+    - Environment context (paths, limits, config)
+    - Available tools list
+
+    Args:
+        template_name: Name of the prompt template (must exist in PROMPT_TEMPLATES)
+        values: Runtime values to substitute into the template placeholders
+        tool_manager: Optional ToolManager instance to retrieve available tools
+
+    Returns:
+        List of message objects in OpenAI Chat API format
+    """
+    template = PROMPT_TEMPLATES.get(template_name)
+    if not template:
+        raise ValueError(f"Prompt template '{template_name}' not found.")
+
+    # Format user prompt
+    user_prompt: str = _format_prompt(template.template, values, template.defaults)
+
+    messages: list[dict[str, str]] = []
+
+    if template.system:
+        system_prompt_content = template.system
+
+        # Build replacement values for system prompt placeholders
+        replacements: dict[str, str] = {}
+
+        # Generate environment context if placeholder exists
+        if "{_ENVIRONMENT_CONTEXT}" in template.system:
+            try:
+                replacements["_ENVIRONMENT_CONTEXT"] = get_environment_context()
+            except Exception as e:
+                log.warning(f"Failed to generate environment context: {e}")
+                replacements["_ENVIRONMENT_CONTEXT"] = "(Environment context unavailable)"
+
+        # Generate tools list if placeholder exists and tool_manager provided
+        if "{_TOOLS_BULLET_LIST}" in template.system:
+            tools_bullet_list = "(No tools available)"
+            if tool_manager:
+                try:
+                    agent_tool_schemas = await tool_manager.get_tools()
+                    if agent_tool_schemas:
+                        tools_info = []
+                        for i, schema in enumerate(agent_tool_schemas, start=1):
+                            func_info = schema.get("function", {})
+                            name = func_info.get("name", "Unknown Tool")
+                            desc = func_info.get("description", "No description.")
+                            # Truncate long descriptions
+                            if len(desc) > 80:
+                                desc = desc[:77] + "..."
+                            tools_info.append(f"  {i}. {name}: {desc}")
+                        if tools_info:
+                            tools_bullet_list = "\n".join(tools_info)
+                except Exception as e:
+                    log.warning(f"Failed to list tools for agent prompt: {e}", exc_info=True)
+                    tools_bullet_list = "(Error retrieving tools)"
+            replacements["_TOOLS_BULLET_LIST"] = tools_bullet_list
+
+        # Apply all replacements
+        if replacements:
+            try:
+                system_prompt_content = template.system.format(**replacements)
+            except KeyError as e:
+                log.warning(f"Missing placeholder value: {e}")
+                # Partial format - replace what we can
+                for key, value in replacements.items():
+                    system_prompt_content = system_prompt_content.replace(f"{{{key}}}", value)
+
+        messages.append({"role": MessageRole.SYSTEM.value, "content": system_prompt_content})
+
+    messages.append({"role": MessageRole.USER.value, "content": user_prompt})
+
+    return messages