ripperdoc 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

ripperdoc/core/agents.py

@@ -11,11 +11,63 @@ from typing import Any, Dict, Iterable, List, Optional, Tuple
 import yaml
 
 from ripperdoc.utils.log import get_logger
+from ripperdoc.tools.ask_user_question_tool import AskUserQuestionTool
+from ripperdoc.tools.bash_output_tool import BashOutputTool
+from ripperdoc.tools.bash_tool import BashTool
+from ripperdoc.tools.enter_plan_mode_tool import EnterPlanModeTool
+from ripperdoc.tools.exit_plan_mode_tool import ExitPlanModeTool
+from ripperdoc.tools.file_edit_tool import FileEditTool
+from ripperdoc.tools.file_read_tool import FileReadTool
+from ripperdoc.tools.file_write_tool import FileWriteTool
+from ripperdoc.tools.glob_tool import GlobTool
+from ripperdoc.tools.grep_tool import GrepTool
+from ripperdoc.tools.kill_bash_tool import KillBashTool
+from ripperdoc.tools.ls_tool import LSTool
+from ripperdoc.tools.multi_edit_tool import MultiEditTool
+from ripperdoc.tools.notebook_edit_tool import NotebookEditTool
+from ripperdoc.tools.todo_tool import TodoReadTool, TodoWriteTool
+from ripperdoc.tools.tool_search_tool import ToolSearchTool
+from ripperdoc.tools.mcp_tools import (
+    ListMcpResourcesTool,
+    ListMcpServersTool,
+    ReadMcpResourceTool,
+)
 
 
 logger = get_logger()
 
 
+def _safe_tool_name(factory: Any, fallback: str) -> str:
+    try:
+        name = getattr(factory(), "name", None)
+        return str(name) if name else fallback
+    except Exception:
+        return fallback
+
+
+GLOB_TOOL_NAME = _safe_tool_name(GlobTool, "Glob")
+GREP_TOOL_NAME = _safe_tool_name(GrepTool, "Grep")
+VIEW_TOOL_NAME = _safe_tool_name(FileReadTool, "View")
+FILE_EDIT_TOOL_NAME = _safe_tool_name(FileEditTool, "FileEdit")
+MULTI_EDIT_TOOL_NAME = _safe_tool_name(MultiEditTool, "MultiEdit")
+NOTEBOOK_EDIT_TOOL_NAME = _safe_tool_name(NotebookEditTool, "NotebookEdit")
+FILE_WRITE_TOOL_NAME = _safe_tool_name(FileWriteTool, "FileWrite")
+LS_TOOL_NAME = _safe_tool_name(LSTool, "LS")
+BASH_TOOL_NAME = _safe_tool_name(BashTool, "Bash")
+BASH_OUTPUT_TOOL_NAME = _safe_tool_name(BashOutputTool, "BashOutput")
+KILL_BASH_TOOL_NAME = _safe_tool_name(KillBashTool, "KillBash")
+TODO_READ_TOOL_NAME = _safe_tool_name(TodoReadTool, "TodoRead")
+TODO_WRITE_TOOL_NAME = _safe_tool_name(TodoWriteTool, "TodoWrite")
+ASK_USER_QUESTION_TOOL_NAME = _safe_tool_name(AskUserQuestionTool, "AskUserQuestion")
+ENTER_PLAN_MODE_TOOL_NAME = _safe_tool_name(EnterPlanModeTool, "EnterPlanMode")
+EXIT_PLAN_MODE_TOOL_NAME = _safe_tool_name(ExitPlanModeTool, "ExitPlanMode")
+TOOL_SEARCH_TOOL_NAME = _safe_tool_name(ToolSearchTool, "ToolSearch")
+MCP_LIST_SERVERS_TOOL_NAME = _safe_tool_name(ListMcpServersTool, "ListMcpServers")
+MCP_LIST_RESOURCES_TOOL_NAME = _safe_tool_name(ListMcpResourcesTool, "ListMcpResources")
+MCP_READ_RESOURCE_TOOL_NAME = _safe_tool_name(ReadMcpResourceTool, "ReadMcpResource")
+TASK_TOOL_NAME = "Task"
+
+
 AGENT_DIR_NAME = "agents"
 
 
@@ -50,9 +102,99 @@ class AgentLoadResult:
     failed_files: List[Tuple[Path, str]]
 
 
-GENERAL_AGENT_PROMPT = """You are a general-purpose subagent for Ripperdoc. Work autonomously on the task provided by the parent agent. Use the allowed tools to research, edit files, and run commands as needed. When you finish, provide a concise report describing what you changed, what you investigated, and any follow-ups the parent agent should share with the user."""
-
-CODE_REVIEW_AGENT_PROMPT = """You are a code review subagent. Inspect the code and summarize risks, bugs, missing tests, security concerns, and regressions. Do not make code changes. Provide clear, actionable feedback that the parent agent can relay to the user."""
+GENERAL_AGENT_PROMPT = (
+    "You are a general-purpose subagent for Ripperdoc. Work autonomously on the task "
+    "provided by the parent agent. Use the allowed tools to research, edit files, and "
+    "run commands as needed. When you finish, provide a concise report describing what "
+    "you changed, what you investigated, and any follow-ups the parent agent should "
+    "share with the user."
+)
+
+CODE_REVIEW_AGENT_PROMPT = (
+    "You are a code review subagent. Inspect the code and summarize risks, bugs, "
+    "missing tests, security concerns, and regressions. Do not make code changes. "
+    "Provide clear, actionable feedback that the parent agent can relay to the user."
+)
+
+EXPLORE_AGENT_PROMPT = (
+    "You are a file search specialist. "
+    "You excel at thoroughly navigating and exploring codebases.\n\n"
+    "=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===\n"
+    "This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:\n"
+    "- Creating new files (no Write, touch, or file creation of any kind)\n"
+    "- Modifying existing files (no Edit operations)\n"
+    "- Deleting files (no rm or deletion)\n"
+    "- Moving or copying files (no mv or cp)\n"
+    "- Creating temporary files anywhere, including /tmp\n"
+    "- Using redirect operators (>, >>, |) or heredocs to write to files\n"
+    "- Running ANY commands that change system state\n\n"
+    "Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access "
+    "to file editing tools - attempting to edit files will fail.\n\n"
+    "Your strengths:\n"
+    "- Rapidly finding files using glob patterns\n"
+    "- Searching code and text with powerful regex patterns\n"
+    "- Reading and analyzing file contents\n\n"
+    "Guidelines:\n"
+    f"- Use {GLOB_TOOL_NAME} for broad file pattern matching\n"
+    f"- Use {GREP_TOOL_NAME} for searching file contents with regex\n"
+    f"- Use {VIEW_TOOL_NAME} when you know the specific file path you need to read\n"
+    f"- Use {BASH_TOOL_NAME} ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)\n"
+    f"- NEVER use {BASH_TOOL_NAME} for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification\n"
+    "- Adapt your search approach based on the thoroughness level specified by the caller\n"
+    "- Return file paths as absolute paths in your final response\n"
+    "- For clear communication, avoid using emojis\n"
+    "- Communicate your final report directly as a regular message - do NOT attempt to create files\n\n"
+    "NOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:\n"
+    "- Make efficient use of the tools that you have at your disposal: be smart about how you search for files and implementations\n"
+    "- Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files\n\n"
+    "Complete the user's search request efficiently and report your findings clearly."
+)
+
+PLAN_AGENT_PROMPT = (
+    "You are a software architect and planning specialist. Your role is "
+    "to explore the codebase and design implementation plans.\n\n"
+    "=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===\n"
+    "This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:\n"
+    "- Creating new files (no Write, touch, or file creation of any kind)\n"
+    "- Modifying existing files (no Edit operations)\n"
+    "- Deleting files (no rm or deletion)\n"
+    "- Moving or copying files (no mv or cp)\n"
+    "- Creating temporary files anywhere, including /tmp\n"
+    "- Using redirect operators (>, >>, |) or heredocs to write to files\n"
+    "- Running ANY commands that change system state\n\n"
+    "Your role is EXCLUSIVELY to explore the codebase and design implementation plans. "
+    "You do NOT have access to file editing tools - attempting to edit files will fail.\n\n"
+    "You will be provided with a set of requirements and optionally a perspective on how "
+    "to approach the design process.\n\n"
+    "## Your Process\n\n"
+    "1. **Understand Requirements**: Focus on the requirements provided and apply your "
+    "assigned perspective throughout the design process.\n\n"
+    "2. **Explore Thoroughly**:\n"
+    "   - Read any files provided to you in the initial prompt\n"
+    f"   - Find existing patterns and conventions using {GLOB_TOOL_NAME}, {GREP_TOOL_NAME}, and {VIEW_TOOL_NAME}\n"
+    "   - Understand the current architecture\n"
+    "   - Identify similar features as reference\n"
+    "   - Trace through relevant code paths\n"
+    f"   - Use {BASH_TOOL_NAME} ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)\n"
+    f"   - NEVER use {BASH_TOOL_NAME} for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification\n\n"
+    "3. **Design Solution**:\n"
+    "   - Create implementation approach based on your assigned perspective\n"
+    "   - Consider trade-offs and architectural decisions\n"
+    "   - Follow existing patterns where appropriate\n\n"
+    "4. **Detail the Plan**:\n"
+    "   - Provide step-by-step implementation strategy\n"
+    "   - Identify dependencies and sequencing\n"
+    "   - Anticipate potential challenges\n\n"
+    "## Required Output\n\n"
+    "End your response with:\n\n"
+    "### Critical Files for Implementation\n"
+    "List 3-5 files most critical for implementing this plan:\n"
+    "- path/to/file1.ts - [Brief reason: e.g., \"Core logic to modify\"]\n"
+    "- path/to/file2.ts - [Brief reason: e.g., \"Interfaces to implement\"]\n"
+    "- path/to/file3.ts - [Brief reason: e.g., \"Pattern to follow\"]\n\n"
+    "REMEMBER: You can ONLY explore and plan. You CANNOT and MUST NOT write, edit, or "
+    "modify any files. You do NOT have access to file editing tools."
+)
 
 
 def _built_in_agents() -> List[AgentDefinition]:
@@ -79,6 +221,34 @@ def _built_in_agents() -> List[AgentDefinition]:
             location=AgentLocation.BUILT_IN,
             color="yellow",
         ),
+        AgentDefinition(
+            agent_type="explore",
+            when_to_use=(
+                'Fast agent specialized for exploring codebases. Use this when you need to quickly find '
+                'files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), '
+                'or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, '
+                'specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, '
+                'or "very thorough" for comprehensive analysis across multiple locations and naming conventions.'
+            ),
+            tools=["View", "Glob", "Grep"],
+            system_prompt=EXPLORE_AGENT_PROMPT,
+            location=AgentLocation.BUILT_IN,
+            color="green",
+            model="task",
+        ),
+        AgentDefinition(
+            agent_type="plan",
+            when_to_use=(
+                "Software architect agent for designing implementation plans. Use this when "
+                "you need to plan the implementation strategy for a task. Returns step-by-step "
+                "plans, identifies critical files, and considers architectural trade-offs."
+            ),
+            tools=["View", "Glob", "Grep"],
+            system_prompt=PLAN_AGENT_PROMPT,
+            location=AgentLocation.BUILT_IN,
+            color="blue",
+            model=None,
+        ),
     ]
 
 
@@ -136,9 +306,7 @@ def _parse_agent_file(
     try:
         text = path.read_text(encoding="utf-8")
     except Exception as exc:
-        logger.exception(
-            "Failed to read agent file", extra={"error": str(exc), "path": str(path)}
-        )
+        logger.exception("Failed to read agent file", extra={"error": str(exc), "path": str(path)})
         return None, f"Failed to read agent file {path}: {exc}"
 
     frontmatter, body = _split_frontmatter(text)

ripperdoc/core/config.py

@@ -100,6 +100,8 @@ class ModelProfile(BaseModel):
     provider: ProviderType
     model: str
     api_key: Optional[str] = None
+    # Anthropic supports either api_key or auth_token; api_key takes precedence when both are set.
+    auth_token: Optional[str] = None
     api_base: Optional[str] = None
     max_tokens: int = 4096
     temperature: float = 0.7
@@ -108,6 +110,9 @@ class ModelProfile(BaseModel):
     # Tool handling for OpenAI-compatible providers. "native" uses tool_calls, "text" flattens tool
     # interactions into plain text to support providers that reject tool roles.
     openai_tool_mode: Literal["native", "text"] = "native"
+    # Pricing (USD per 1M tokens). Leave as 0 to skip cost calculation.
+    input_cost_per_million_tokens: float = 0.0
+    output_cost_per_million_tokens: float = 0.0
 
 
 class ModelPointers(BaseModel):
@@ -255,7 +260,10 @@ class ConfigManager:
                 self._project_config = ProjectConfig()
                 logger.debug(
                     "[config] Project config not found; using defaults",
-                    extra={"path": str(config_path), "project_path": str(self.current_project_path)},
+                    extra={
+                        "path": str(config_path),
+                        "project_path": str(self.current_project_path),
+                    },
                 )
 
         return self._project_config

ripperdoc/core/default_tools.py

@@ -18,6 +18,9 @@ from ripperdoc.tools.glob_tool import GlobTool
 from ripperdoc.tools.ls_tool import LSTool
 from ripperdoc.tools.grep_tool import GrepTool
 from ripperdoc.tools.todo_tool import TodoReadTool, TodoWriteTool
+from ripperdoc.tools.ask_user_question_tool import AskUserQuestionTool
+from ripperdoc.tools.enter_plan_mode_tool import EnterPlanModeTool
+from ripperdoc.tools.exit_plan_mode_tool import ExitPlanModeTool
 from ripperdoc.tools.task_tool import TaskTool
 from ripperdoc.tools.tool_search_tool import ToolSearchTool
 from ripperdoc.tools.mcp_tools import (
@@ -47,6 +50,9 @@ def get_default_tools() -> List[Tool[Any, Any]]:
         GrepTool(),
         TodoReadTool(),
         TodoWriteTool(),
+        AskUserQuestionTool(),
+        EnterPlanModeTool(),
+        ExitPlanModeTool(),
         ToolSearchTool(),
         ListMcpServersTool(),
         ListMcpResourcesTool(),

ripperdoc/core/providers/__init__.py

@@ -0,0 +1,47 @@
+"""Provider client registry with optional dependencies."""
+
+from __future__ import annotations
+
+import importlib
+from typing import Optional, TYPE_CHECKING, Type, cast
+
+from ripperdoc.core.config import ProviderType
+from ripperdoc.core.providers.base import ProviderClient
+from ripperdoc.utils.log import get_logger
+
+if TYPE_CHECKING:  # pragma: no cover - type checking only
+    from ripperdoc.core.providers.anthropic import AnthropicClient  # noqa: F401
+    from ripperdoc.core.providers.gemini import GeminiClient  # noqa: F401
+    from ripperdoc.core.providers.openai import OpenAIClient  # noqa: F401
+
+logger = get_logger()
+
+
+def _load_client(module: str, cls: str, extra: str) -> Type[ProviderClient]:
+    """Dynamically import a provider client, pointing users to the right extra."""
+    try:
+        mod = importlib.import_module(f"ripperdoc.core.providers.{module}")
+        client_cls = cast(Type[ProviderClient], getattr(mod, cls, None))
+        if client_cls is None:
+            raise ImportError(f"{cls} not found in {module}")
+        return client_cls
+    except ImportError as exc:
+        raise RuntimeError(
+            f"{cls} requires optional dependency group '{extra}'. "
+            f"Install with `pip install ripperdoc[{extra}]`."
+        ) from exc
+
+
+def get_provider_client(provider: ProviderType) -> Optional[ProviderClient]:
+    """Return a provider client for the given protocol."""
+    if provider == ProviderType.ANTHROPIC:
+        return _load_client("anthropic", "AnthropicClient", "anthropic")()
+    if provider == ProviderType.OPENAI_COMPATIBLE:
+        return _load_client("openai", "OpenAIClient", "openai")()
+    if provider == ProviderType.GEMINI:
+        return _load_client("gemini", "GeminiClient", "gemini")()
+    logger.warning("[providers] Unsupported provider", extra={"provider": provider})
+    return None
+
+
+__all__ = ["ProviderClient", "get_provider_client"]

ripperdoc/core/providers/anthropic.py

@@ -0,0 +1,147 @@
+"""Anthropic provider client."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Awaitable, Callable, Dict, List, Optional
+
+from anthropic import AsyncAnthropic
+
+from ripperdoc.core.config import ModelProfile
+from ripperdoc.core.providers.base import (
+    ProgressCallback,
+    ProviderClient,
+    ProviderResponse,
+    call_with_timeout_and_retries,
+    iter_with_timeout,
+    sanitize_tool_history,
+)
+from ripperdoc.core.query_utils import (
+    anthropic_usage_tokens,
+    build_anthropic_tool_schemas,
+    content_blocks_from_anthropic_response,
+    estimate_cost_usd,
+)
+from ripperdoc.core.tool import Tool
+from ripperdoc.utils.log import get_logger
+from ripperdoc.utils.session_usage import record_usage
+
+logger = get_logger()
+
+
+class AnthropicClient(ProviderClient):
+    """Anthropic client with streaming and non-streaming support."""
+
+    def __init__(self, client_factory: Optional[Callable[[], Awaitable[AsyncAnthropic]]] = None):
+        self._client_factory = client_factory
+
+    async def _client(self, kwargs: Dict[str, Any]) -> AsyncAnthropic:
+        if self._client_factory:
+            return await self._client_factory()
+        return AsyncAnthropic(**kwargs)
+
+    async def call(
+        self,
+        *,
+        model_profile: ModelProfile,
+        system_prompt: str,
+        normalized_messages: Any,
+        tools: List[Tool[Any, Any]],
+        tool_mode: str,
+        stream: bool,
+        progress_callback: Optional[ProgressCallback],
+        request_timeout: Optional[float],
+        max_retries: int,
+    ) -> ProviderResponse:
+        start_time = time.time()
+        tool_schemas = await build_anthropic_tool_schemas(tools)
+        collected_text: List[str] = []
+
+        anthropic_kwargs = {"base_url": model_profile.api_base}
+        if model_profile.api_key:
+            anthropic_kwargs["api_key"] = model_profile.api_key
+        auth_token = getattr(model_profile, "auth_token", None)
+        if auth_token:
+            anthropic_kwargs["auth_token"] = auth_token
+
+        normalized_messages = sanitize_tool_history(list(normalized_messages))
+
+        async with await self._client(anthropic_kwargs) as client:
+
+            async def _stream_request() -> Any:
+                stream_cm = client.messages.stream(
+                    model=model_profile.model,
+                    max_tokens=model_profile.max_tokens,
+                    system=system_prompt,
+                    messages=normalized_messages,  # type: ignore[arg-type]
+                    tools=tool_schemas if tool_schemas else None,  # type: ignore
+                    temperature=model_profile.temperature,
+                )
+                stream_resp = (
+                    await asyncio.wait_for(stream_cm.__aenter__(), timeout=request_timeout)
+                    if request_timeout and request_timeout > 0
+                    else await stream_cm.__aenter__()
+                )
+                try:
+                    async for text in iter_with_timeout(stream_resp.text_stream, request_timeout):
+                        if text:
+                            collected_text.append(text)
+                            if progress_callback:
+                                try:
+                                    await progress_callback(text)
+                                except Exception:
+                                    logger.exception("[anthropic_client] Stream callback failed")
+                    getter = getattr(stream_resp, "get_final_response", None) or getattr(
+                        stream_resp, "get_final_message", None
+                    )
+                    if getter:
+                        return await getter()
+                    return None
+                finally:
+                    await stream_cm.__aexit__(None, None, None)
+
+            async def _non_stream_request() -> Any:
+                return await client.messages.create(
+                    model=model_profile.model,
+                    max_tokens=model_profile.max_tokens,
+                    system=system_prompt,
+                    messages=normalized_messages,  # type: ignore[arg-type]
+                    tools=tool_schemas if tool_schemas else None,  # type: ignore
+                    temperature=model_profile.temperature,
+                )
+
+            timeout_for_call = None if stream else request_timeout
+            response = await call_with_timeout_and_retries(
+                _stream_request if stream else _non_stream_request,
+                timeout_for_call,
+                max_retries,
+            )
+
+        duration_ms = (time.time() - start_time) * 1000
+        usage_tokens = anthropic_usage_tokens(getattr(response, "usage", None))
+        cost_usd = estimate_cost_usd(model_profile, usage_tokens)
+        record_usage(
+            model_profile.model, duration_ms=duration_ms, cost_usd=cost_usd, **usage_tokens
+        )
+
+        content_blocks = content_blocks_from_anthropic_response(response, tool_mode)
+        if stream and collected_text and tool_mode == "text":
+            content_blocks = [{"type": "text", "text": "".join(collected_text)}]
+
+        logger.info(
+            "[anthropic_client] Response received",
+            extra={
+                "model": model_profile.model,
+                "duration_ms": round(duration_ms, 2),
+                "tool_mode": tool_mode,
+                "tool_schemas": len(tool_schemas),
+            },
+        )
+
+        return ProviderResponse(
+            content_blocks=content_blocks,
+            usage_tokens=usage_tokens,
+            cost_usd=cost_usd,
+            duration_ms=duration_ms,
+        )