snippbot 0.1.0__py3-none-any.whl

claude_gateway/__init__.py

@@ -0,0 +1,16 @@
+"""
+Claude Gateway - HTTP Gateway for Claude CLI with Multi-Agent Support
+
+A unified gateway server that provides:
+- OpenAI Chat Completions API compatibility (/v1/chat/completions)
+- Anthropic Messages API compatibility (/v1/messages)
+- Multi-agent support with SSH-based file access
+- Real-time streaming via Server-Sent Events (SSE)
+- Tool/function call parsing
+- Embeddings API (with optional sentence-transformers)
+- Artifacts management
+- Awakening experience for onboarding
+"""
+
+__version__ = "5.1.0"
+__all__ = ["__version__"]

claude_gateway/__main__.py

@@ -0,0 +1,11 @@
+"""
+Entry point for running the gateway as a module.
+
+Usage:
+    python -m claude_gateway [port] [config_path]
+"""
+
+from claude_gateway.server import main
+
+if __name__ == "__main__":
+    main()

claude_gateway/claude/__init__.py

@@ -0,0 +1,14 @@
+"""Claude CLI integration - subprocess handling and message parsing."""
+
+from claude_gateway.claude.cli import call_claude, call_claude_streaming, find_claude_path, get_claude_path
+from claude_gateway.claude.parser import parse_function_calls, messages_to_prompt, tools_to_prompt
+
+__all__ = [
+    "call_claude",
+    "call_claude_streaming",
+    "find_claude_path",
+    "get_claude_path",
+    "parse_function_calls",
+    "messages_to_prompt",
+    "tools_to_prompt",
+]

claude_gateway/claude/cli.py

@@ -0,0 +1,174 @@
+"""
+Claude CLI subprocess integration.
+
+Handles:
+- Finding the Claude CLI executable
+- Executing non-streaming requests
+- Executing streaming requests with subprocess.Popen
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import time
+
+from claude_gateway.logging import log
+from claude_gateway.models import map_model_name, DEFAULT_SYSTEM_PROMPT
+
+
+def find_claude_path() -> str | None:
+    """Find claude CLI, checking env var first, then common locations.
+
+    Returns the path to the Claude CLI binary, or None if not found.
+    """
+    env_path = os.environ.get("CLAUDE_PATH")
+    if env_path and os.path.exists(env_path):
+        return env_path
+
+    # Common locations to check
+    candidates = [
+        os.path.expanduser("~/.local/bin/claude"),
+        os.path.expanduser("~/.npm-global/bin/claude"),
+        os.path.expanduser("~/node_modules/.bin/claude"),
+        os.path.expanduser("~/.npm/bin/claude"),
+        "/usr/local/bin/claude",
+        os.path.expanduser("~/bin/claude"),
+    ]
+
+    # On Windows, also check AppData
+    if sys.platform == "win32":
+        candidates.extend([
+            os.path.expanduser("~/AppData/Local/Programs/claude/claude.exe"),
+            os.path.expanduser("~/.claude/claude.exe"),
+        ])
+
+    for path in candidates:
+        if os.path.exists(path) and os.access(path, os.X_OK):
+            return path
+
+    # Try system PATH as last resort
+    return shutil.which("claude")
+
+
+def get_claude_path() -> str:
+    """Get the Claude CLI path, raising FileNotFoundError if not found."""
+    path = find_claude_path()
+    if path is None:
+        raise FileNotFoundError(
+            "Claude CLI not found. Install with: npm install -g @anthropic-ai/claude-code"
+        )
+    return path
+
+
+def call_claude(
+    prompt: str,
+    model: str,
+    system_prompt: str | None = None,
+    disable_tools: bool = True,
+    image_temp_dir: str | None = None,
+) -> tuple[subprocess.CompletedProcess, float, str]:
+    """Call Claude CLI and return result (non-streaming).
+
+    Args:
+        prompt: The prompt to send
+        model: Model name
+        system_prompt: Optional system prompt
+        disable_tools: If True, disables internal tool execution so we get raw tool calls
+        image_temp_dir: If set, enables Read tool and grants access to this directory
+                        so Claude can read saved image files.
+
+    Returns:
+        Tuple of (CompletedProcess, elapsed_seconds, cli_model_name)
+
+    Raises:
+        FileNotFoundError: If Claude CLI is not installed
+    """
+    claude_path = get_claude_path()
+    cli_model = map_model_name(model)
+    cmd = [claude_path, '-p', prompt, '--model', cli_model, '--output-format', 'json']
+
+    if image_temp_dir:
+        # Enable only the Read tool so Claude can view saved image files
+        cmd.extend(['--tools', 'Read'])
+        cmd.extend(['--add-dir', image_temp_dir])
+    elif disable_tools:
+        # Prevent CLI from executing tools so we get raw tool_calls in output.
+        # NOTE: --tools '' breaks when MCP tools are configured (disables entire
+        # tool_use mechanism, causing hangs). Use --max-turns 1 instead — it lets
+        # the model produce tool calls normally but stops the CLI from executing them.
+        cmd.extend(['--max-turns', '1'])
+
+    # Use --system-prompt to override Claude Code's default identity
+    effective_system = system_prompt if system_prompt else DEFAULT_SYSTEM_PROMPT
+    cmd.extend(['--system-prompt', effective_system])
+
+    start_time = time.time()
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        timeout=300  # 5 minute timeout
+    )
+    elapsed = time.time() - start_time
+
+    return result, elapsed, cli_model
+
+
+def call_claude_streaming(
+    prompt: str,
+    model: str,
+    system_prompt: str | None = None,
+    disable_tools: bool = True,
+    image_temp_dir: str | None = None,
+) -> tuple[subprocess.Popen, str]:
+    """Call Claude CLI and return a subprocess with streaming stdout.
+
+    Returns (process, cli_model). Read process.stdout line by line for
+    streaming JSON events. Caller must handle process cleanup.
+
+    Args:
+        prompt: The prompt to send
+        model: Model name
+        system_prompt: Optional system prompt
+        disable_tools: If True, disables internal tool execution so we get raw tool calls
+        image_temp_dir: If set, enables Read tool and grants access to this directory
+                        so Claude can read saved image files.
+
+    Raises:
+        FileNotFoundError: If Claude CLI is not installed
+    """
+    claude_path = get_claude_path()
+    cli_model = map_model_name(model)
+    log(f"[CLI] Model mapping: '{model}' -> '{cli_model}'")
+    cmd = [
+        claude_path, '-p', prompt, '--model', cli_model,
+        '--output-format', 'stream-json', '--verbose',
+        '--include-partial-messages'
+    ]
+
+    if image_temp_dir:
+        # Enable only the Read tool so Claude can view saved image files
+        cmd.extend(['--tools', 'Read'])
+        cmd.extend(['--add-dir', image_temp_dir])
+        log(f"[CLI] Image temp dir: {image_temp_dir} — Read tool enabled")
+    elif disable_tools:
+        # Prevent CLI from executing tools — see call_claude() for rationale
+        cmd.extend(['--max-turns', '1'])
+
+    effective_system = system_prompt if system_prompt else DEFAULT_SYSTEM_PROMPT
+    cmd.extend(['--system-prompt', effective_system])
+
+    process = subprocess.Popen(
+        cmd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        encoding="utf-8",
+        bufsize=1  # line-buffered
+    )
+
+    return process, cli_model

claude_gateway/claude/parser.py

@@ -0,0 +1,295 @@
+"""
+Message parsing and tool/function call conversion.
+
+Handles:
+- Parsing XML function_calls from Claude's response text
+- Converting OpenAI tools array to text description
+- Converting messages array to prompt string
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import re
+import tempfile
+import uuid
+
+
+def parse_function_calls(text: str) -> tuple[str, list[dict]]:
+    """Parse XML function_calls from Claude's response text.
+
+    Returns tuple: (clean_text, tool_calls_list)
+    - clean_text: response with function_calls XML removed
+    - tool_calls_list: list of OpenAI-format tool_calls
+    """
+    tool_calls = []
+
+    # Find all <invoke> blocks (can be inside <function_calls> or standalone)
+    invoke_pattern = r'<invoke\s+name="([^"]+)">\s*(.*?)\s*</invoke>'
+    matches = re.findall(invoke_pattern, text, re.DOTALL)
+
+    print(f"[PARSER] Found {len(matches)} invoke blocks in text ({len(text)} chars)", flush=True)
+
+    for i, (func_name, params_block) in enumerate(matches):
+        print(f"[PARSER] Invoke {i}: func_name='{func_name}', params_block_len={len(params_block)}", flush=True)
+        # Parse parameters - use non-greedy match to handle content with < characters
+        # Old pattern [^<]* would truncate at first < in content (breaks heredocs, etc.)
+        param_pattern = r'<parameter\s+name="([^"]+)">(.*?)</parameter>'
+        params = dict(re.findall(param_pattern, params_block, re.DOTALL))
+        print(f"[PARSER] Invoke {i}: parsed {len(params)} params: {list(params.keys())}", flush=True)
+        for pname, pval in params.items():
+            print(f"[PARSER]   param '{pname}': {len(pval)} chars, preview='{pval[:100]}...'", flush=True)
+
+        tool_call = {
+            "id": f"call_{uuid.uuid4().hex[:24]}",
+            "type": "function",
+            "function": {
+                "name": func_name,
+                "arguments": json.dumps(params)
+            }
+        }
+        tool_calls.append(tool_call)
+
+    # Remove all function_calls blocks and invoke blocks from text
+    clean_text = text
+    # Remove complete function_calls blocks
+    clean_text = re.sub(r'<function_calls>.*?</function_calls>', '', clean_text, flags=re.DOTALL)
+    # Remove standalone invoke blocks
+    clean_text = re.sub(r'<invoke\s+name="[^"]+">.*?</invoke>', '', clean_text, flags=re.DOTALL)
+    # Remove orphaned function_calls tags
+    clean_text = re.sub(r'</?function_calls>', '', clean_text)
+    # Clean up extra whitespace
+    clean_text = re.sub(r'\n\s*\n\s*\n', '\n\n', clean_text).strip()
+
+    return clean_text, tool_calls
+
+
+def tools_to_prompt(tools: list | None) -> str:
+    """Convert OpenAI tools array to a text description for the prompt.
+
+    Uses mandatory language to ensure Claude uses tools when appropriate,
+    especially for interactive tools like ask_questions.
+    """
+    if not tools:
+        return ""
+
+    # Check if ask_questions tool is present - use extra strong language
+    has_ask_questions = any(
+        t.get("function", {}).get("name") == "ask_questions" or t.get("name") == "ask_questions"
+        for t in tools if t.get("type") == "function" or "name" in t
+    )
+
+    tool_desc = "\n\n"
+    tool_desc += "=" * 60 + "\n"
+    tool_desc += "MANDATORY TOOL USAGE INSTRUCTIONS\n"
+    tool_desc += "=" * 60 + "\n\n"
+
+    tool_desc += "You MUST use tools when they are relevant to the conversation.\n"
+    tool_desc += "DO NOT write plain text responses when a tool should be used instead.\n\n"
+
+    if has_ask_questions:
+        tool_desc += "CRITICAL: When you need to ask the user questions, you MUST use the `ask_questions` tool.\n"
+        tool_desc += "DO NOT write questions as plain markdown text. ALWAYS use the ask_questions tool.\n"
+        tool_desc += "This enables interactive UI elements (checkboxes, radio buttons, text inputs).\n\n"
+
+    tool_desc += "To invoke a tool, output XML in EXACTLY this format:\n"
+    tool_desc += '<function_calls>\n<invoke name="TOOL_NAME">\n<parameter name="PARAM">value</parameter>\n</invoke>\n</function_calls>\n\n'
+
+    tool_desc += "IMPORTANT:\n"
+    tool_desc += "- You MUST output the <function_calls> XML block when using tools\n"
+    tool_desc += "- The XML must be well-formed with proper opening and closing tags\n"
+    tool_desc += "- Use the exact parameter names shown below\n\n"
+
+    tool_desc += "Available tools:\n"
+
+    for tool in tools:
+        if tool.get("type") == "function":
+            func = tool.get("function", {})
+            name = func.get("name", "unknown")
+            desc = func.get("description", "No description")
+            params = func.get("parameters", {})
+
+            tool_desc += f"\n- {name}: {desc}\n"
+            if params.get("properties"):
+                tool_desc += "  Parameters:\n"
+                for pname, pinfo in params["properties"].items():
+                    ptype = pinfo.get("type", "string")
+                    pdesc = pinfo.get("description", "")
+                    required = pname in params.get("required", [])
+                    req_str = " (required)" if required else ""
+                    tool_desc += f"    - {pname} ({ptype}){req_str}: {pdesc}\n"
+        elif "name" in tool:
+            # Handle simplified tool format without "function" wrapper
+            name = tool.get("name", "unknown")
+            desc = tool.get("description", "No description")
+            params = tool.get("input_schema", tool.get("parameters", {}))
+
+            tool_desc += f"\n- {name}: {desc}\n"
+            if params.get("properties"):
+                tool_desc += "  Parameters:\n"
+                for pname, pinfo in params["properties"].items():
+                    ptype = pinfo.get("type", "string")
+                    pdesc = pinfo.get("description", "")
+                    required = pname in params.get("required", [])
+                    req_str = " (required)" if required else ""
+                    tool_desc += f"    - {pname} ({ptype}){req_str}: {pdesc}\n"
+
+    tool_desc += "\n" + "=" * 60 + "\n"
+    tool_desc += "Remember: USE THE TOOLS. Do not write plain text alternatives.\n"
+    tool_desc += "=" * 60 + "\n"
+
+    return tool_desc
+
+
+def save_message_images(messages: list) -> tuple[list, str | None]:
+    """Extract base64 images from messages, save to temp files, replace with file path refs.
+
+    Scans all messages for image content blocks (OpenAI ``image_url`` and
+    Anthropic ``image`` formats).  Base64 image data is decoded and written to
+    a temporary directory.  The original image blocks are replaced with plain
+    text blocks containing the temp file path so that Claude CLI can read them
+    via the Read tool.
+
+    Returns:
+        (modified_messages, temp_dir) — *temp_dir* is ``None`` when no images
+        were found.  The caller is responsible for cleaning up *temp_dir* after
+        the CLI call completes.
+    """
+    temp_dir: str | None = None
+    modified: list[dict] = []
+
+    for msg in messages:
+        content = msg.get("content", "")
+        if not isinstance(content, list):
+            modified.append(msg)
+            continue
+
+        new_blocks: list = []
+        for block in content:
+            if not isinstance(block, dict):
+                new_blocks.append(block)
+                continue
+
+            btype = block.get("type")
+
+            # Anthropic format: {"type": "image", "source": {"type": "base64", ...}}
+            if btype == "image" and block.get("source", {}).get("type") == "base64":
+                if temp_dir is None:
+                    temp_dir = tempfile.mkdtemp(prefix="snippbot-images-")
+                source = block["source"]
+                ext = source.get("media_type", "image/png").split("/")[-1]
+                fname = f"{uuid.uuid4().hex[:12]}.{ext}"
+                fpath = os.path.join(temp_dir, fname)
+                with open(fpath, "wb") as f:
+                    f.write(base64.b64decode(source["data"]))
+                new_blocks.append({"type": "text", "text": f"[Attached image: {fpath}]"})
+
+            # OpenAI format: {"type": "image_url", "image_url": {"url": "data:..."}}
+            elif btype == "image_url":
+                url = block.get("image_url", {}).get("url", "")
+                if url.startswith("data:"):
+                    if temp_dir is None:
+                        temp_dir = tempfile.mkdtemp(prefix="snippbot-images-")
+                    # data:image/png;base64,AAAA...
+                    header, data = url.split(",", 1)
+                    media = header.split(":")[1].split(";")[0]
+                    ext = media.split("/")[-1]
+                    fname = f"{uuid.uuid4().hex[:12]}.{ext}"
+                    fpath = os.path.join(temp_dir, fname)
+                    with open(fpath, "wb") as f:
+                        f.write(base64.b64decode(data))
+                    new_blocks.append({"type": "text", "text": f"[Attached image: {fpath}]"})
+                else:
+                    # Keep HTTP URL references as-is
+                    new_blocks.append(block)
+
+            else:
+                new_blocks.append(block)
+
+        modified.append({**msg, "content": new_blocks})
+
+    return modified, temp_dir
+
+
+def messages_to_prompt(
+    messages: list,
+    system_prompt: str | None = None,
+    tools: list | None = None
+) -> str:
+    """Convert messages array to a single prompt string."""
+    parts = []
+
+    # Add system prompt first if provided
+    if system_prompt:
+        parts.append(f"System: {system_prompt}")
+
+    # Add tools description if provided
+    if tools:
+        tool_desc = tools_to_prompt(tools)
+        if tool_desc:
+            parts.append(tool_desc)
+
+    for msg in messages:
+        role = msg.get("role", "user")
+        content = msg.get("content", "")
+
+        # Handle content that's a list of content blocks
+        if isinstance(content, list):
+            text_parts = []
+            for block in content:
+                if isinstance(block, dict):
+                    block_type = block.get("type")
+
+                    if block_type == "text":
+                        text_parts.append(block.get("text", ""))
+
+                    elif block_type == "image_url":
+                        # OpenAI format: {"type": "image_url", "image_url": {"url": "..."}}
+                        image_url = block.get("image_url", {})
+                        url = image_url.get("url", "")
+                        if url.startswith("data:"):
+                            text_parts.append("[Image: base64-encoded image attached]")
+                        else:
+                            text_parts.append(f"[Image URL: {url}]")
+
+                    elif block_type == "image":
+                        # Anthropic format: {"type": "image", "source": {"type": "base64", ...}}
+                        source = block.get("source", {})
+                        source_type = source.get("type", "")
+                        if source_type == "base64":
+                            media_type = source.get("media_type", "image/png")
+                            text_parts.append(f"[Image: {media_type} attached]")
+                        elif source_type == "url":
+                            url = source.get("url", "")
+                            text_parts.append(f"[Image URL: {url}]")
+
+                    elif block_type == "file":
+                        # File attachment
+                        file_name = block.get("file_name", block.get("name", "file"))
+                        file_content = block.get("content", block.get("text", ""))
+                        text_parts.append(f"\n--- Attached File: {file_name} ---\n{file_content}\n--- End File ---\n")
+
+                    elif block_type == "document":
+                        # Document attachment
+                        doc_name = block.get("name", block.get("file_name", "document"))
+                        doc_text = block.get("text", block.get("content", ""))
+                        text_parts.append(f"\n--- Attached Document: {doc_name} ---\n{doc_text}\n--- End Document ---\n")
+
+                elif isinstance(block, str):
+                    text_parts.append(block)
+            content = "\n".join(text_parts)
+
+        if role == "user":
+            parts.append(f"Human: {content}")
+        elif role == "assistant":
+            parts.append(f"Assistant: {content}")
+        elif role == "system":
+            parts.insert(0, f"System: {content}")
+        elif role == "tool":
+            # Tool result message
+            tool_call_id = msg.get("tool_call_id", "")
+            parts.append(f"Tool Result ({tool_call_id}): {content}")
+
+    return "\n\n".join(parts)