thwip-cli 1.0.0__py3-none-any.whl

thwip/tools/__init__.py

@@ -0,0 +1,184 @@
+"""
+Tool registry and schema translator for LLMs.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from thwip.tools.file_editor import FileEditor
+from thwip.tools.terminal import TerminalRunner
+from thwip.tools.code_runner import CodeRunner
+from thwip.tools.git_ops import GitOps
+
+
+class ToolManager:
+    """Manages tool execution and provides schemas for agent tool calling."""
+
+    def __init__(self, project_path: str = ".") -> None:
+        self.project_path = project_path
+        self.file_editor = FileEditor(project_path)
+        self.terminal = TerminalRunner(project_path)
+        self.code_runner = CodeRunner(project_path)
+        self.git = GitOps(project_path)
+
+    def get_openai_tools(self) -> list[dict[str, Any]]:
+        """Return tool definitions formatted for OpenAI / DeepSeek / Groq."""
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": "read_file",
+                    "description": "Read content of a file in the project.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "file_path": {"type": "string", "description": "Relative path to file"},
+                        },
+                        "required": ["file_path"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "write_file",
+                    "description": "Write or overwrite content in a file.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "file_path": {"type": "string", "description": "Relative path to file"},
+                            "content": {"type": "string", "description": "Full file content"},
+                        },
+                        "required": ["file_path", "content"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "edit_file",
+                    "description": "Replace exact target string with replacement text in a file.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "file_path": {"type": "string", "description": "Relative path to file"},
+                            "old_str": {"type": "string", "description": "Exact text to find and replace"},
+                            "new_str": {"type": "string", "description": "Replacement text"},
+                        },
+                        "required": ["file_path", "old_str", "new_str"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "run_command",
+                    "description": "Run a shell command in project directory.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "command": {"type": "string", "description": "Terminal command to run"},
+                        },
+                        "required": ["command"],
+                    },
+                },
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "list_files",
+                    "description": "List files in the project workspace.",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "sub_dir": {"type": "string", "description": "Subdirectory to list (default .)"},
+                        },
+                    },
+                },
+            },
+        ]
+
+    def get_anthropic_tools(self) -> list[dict[str, Any]]:
+        """Return tool definitions formatted for Anthropic Claude."""
+        return [
+            {
+                "name": "read_file",
+                "description": "Read content of a file in the project.",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "file_path": {"type": "string", "description": "Relative path to file"},
+                    },
+                    "required": ["file_path"],
+                },
+            },
+            {
+                "name": "write_file",
+                "description": "Write or overwrite content in a file.",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "file_path": {"type": "string", "description": "Relative path to file"},
+                        "content": {"type": "string", "description": "Full file content"},
+                    },
+                    "required": ["file_path", "content"],
+                },
+            },
+            {
+                "name": "edit_file",
+                "description": "Replace exact target string with replacement text in a file.",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "file_path": {"type": "string", "description": "Relative path to file"},
+                        "old_str": {"type": "string", "description": "Exact text to find and replace"},
+                        "new_str": {"type": "string", "description": "Replacement text"},
+                    },
+                    "required": ["file_path", "old_str", "new_str"],
+                },
+            },
+            {
+                "name": "run_command",
+                "description": "Run a shell command in project directory.",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "command": {"type": "string", "description": "Terminal command to run"},
+                    },
+                    "required": ["command"],
+                },
+            },
+            {
+                "name": "list_files",
+                "description": "List files in the project workspace.",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "sub_dir": {"type": "string", "description": "Subdirectory to list (default .)"},
+                    },
+                },
+            },
+        ]
+
+    def execute_tool(self, tool_name: str, args: dict[str, Any]) -> str:
+        """Execute a tool by name with arguments and return output."""
+        if tool_name == "read_file":
+            return self.file_editor.read_file(args.get("file_path", ""))
+        elif tool_name == "write_file":
+            return self.file_editor.write_file(args.get("file_path", ""), args.get("content", ""))
+        elif tool_name == "edit_file":
+            return self.file_editor.edit_file(
+                args.get("file_path", ""), args.get("old_str", ""), args.get("new_str", "")
+            )
+        elif tool_name == "run_command":
+            return self.terminal.run_command(args.get("command", ""))
+        elif tool_name == "list_files":
+            return self.file_editor.list_files(args.get("sub_dir", "."))
+        elif tool_name == "git_status":
+            return self.git.status()
+        elif tool_name == "git_diff":
+            return self.git.diff(args.get("staged", False))
+        elif tool_name == "run_python":
+            return self.code_runner.run_python(args.get("code", ""))
+        else:
+            return f"Error: Unknown tool '{tool_name}'."

thwip/tools/code_runner.py

@@ -0,0 +1,62 @@
+"""
+Code execution runners for Python, Node, and scripts.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+class CodeRunner:
+    """Executes arbitrary code snippets in isolated temporary files."""
+
+    def __init__(self, project_path: str | Path = ".") -> None:
+        self.project_path = Path(project_path).resolve()
+
+    def run_python(self, code: str, timeout: int = 20) -> str:
+        """Execute a Python snippet."""
+        with tempfile.NamedTemporaryFile(suffix=".py", mode="w", delete=False) as f:
+            f.write(code)
+            temp_file = f.name
+        try:
+            res = subprocess.run(
+                ["python3", temp_file],
+                cwd=str(self.project_path),
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+            out = res.stdout.strip()
+            err = res.stderr.strip()
+            return f"Return code: {res.returncode}\n{out}\n{err}".strip()
+        except subprocess.TimeoutExpired:
+            return f"Timeout: Python script exceeded {timeout}s."
+        except Exception as e:
+            return f"Execution error: {e}"
+        finally:
+            Path(temp_file).unlink(missing_ok=True)
+
+    def run_node(self, code: str, timeout: int = 20) -> str:
+        """Execute a Node.js snippet."""
+        with tempfile.NamedTemporaryFile(suffix=".js", mode="w", delete=False) as f:
+            f.write(code)
+            temp_file = f.name
+        try:
+            res = subprocess.run(
+                ["node", temp_file],
+                cwd=str(self.project_path),
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+            out = res.stdout.strip()
+            err = res.stderr.strip()
+            return f"Return code: {res.returncode}\n{out}\n{err}".strip()
+        except subprocess.TimeoutExpired:
+            return f"Timeout: Node script exceeded {timeout}s."
+        except Exception as e:
+            return f"Execution error: {e}"
+        finally:
+            Path(temp_file).unlink(missing_ok=True)

thwip/tools/file_editor.py

@@ -0,0 +1,92 @@
+"""
+File operations tool for coding agents.
+
+Read, write, edit, search files within the project working directory.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+
+class FileEditor:
+    """Provides safe file operations rooted in a project directory."""
+
+    def __init__(self, project_path: str | Path = ".") -> None:
+        self.project_path = Path(project_path).resolve()
+
+    def _resolve_path(self, file_path: str) -> Path:
+        p = Path(file_path)
+        if not p.is_absolute():
+            p = self.project_path / p
+        return p.resolve()
+
+    def read_file(self, file_path: str, max_lines: int = 500) -> str:
+        """Read content of a file."""
+        target = self._resolve_path(file_path)
+        if not target.is_file():
+            return f"Error: File '{file_path}' does not exist."
+        try:
+            lines = target.read_text(encoding="utf-8", errors="replace").splitlines()
+            if len(lines) > max_lines:
+                preview = "\n".join(lines[:max_lines])
+                return f"{preview}\n\n... [Truncated: showing first {max_lines} of {len(lines)} lines]"
+            return "\n".join(lines)
+        except Exception as e:
+            return f"Error reading file '{file_path}': {e}"
+
+    def write_file(self, file_path: str, content: str) -> str:
+        """Write/overwrite content to a file, creating parent directories if needed."""
+        target = self._resolve_path(file_path)
+        try:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(content, encoding="utf-8")
+            return f"Successfully wrote {len(content.splitlines())} lines to '{file_path}'."
+        except Exception as e:
+            return f"Error writing to file '{file_path}': {e}"
+
+    def edit_file(self, file_path: str, old_str: str, new_str: str) -> str:
+        """Replace exact target content with new content in a file."""
+        target = self._resolve_path(file_path)
+        if not target.is_file():
+            return f"Error: File '{file_path}' does not exist."
+        try:
+            content = target.read_text(encoding="utf-8")
+            if old_str not in content:
+                return f"Error: Target text to replace not found in '{file_path}'."
+            count = content.count(old_str)
+            if count > 1:
+                return f"Error: Target text found {count} times. Please specify a more unique target block."
+            new_content = content.replace(old_str, new_str, 1)
+            target.write_text(new_content, encoding="utf-8")
+            return f"Successfully updated '{file_path}'."
+        except Exception as e:
+            return f"Error editing file '{file_path}': {e}"
+
+    def list_files(self, sub_dir: str = ".", max_entries: int = 100) -> str:
+        """List files and directories within project."""
+        target = self._resolve_path(sub_dir)
+        if not target.is_dir():
+            return f"Error: Directory '{sub_dir}' does not exist."
+        entries = []
+        try:
+            for root, dirs, files in os.walk(target):
+                # Skip hidden folders like .git, node_modules, __pycache__
+                dirs[:] = [d for d in dirs if not d.startswith(".") and d != "node_modules" and d != "__pycache__"]
+                for f in files:
+                    if f.startswith("."):
+                        continue
+                    full_p = Path(root) / f
+                    rel_p = full_p.relative_to(self.project_path)
+                    entries.append(str(rel_p))
+                    if len(entries) >= max_entries:
+                        break
+                if len(entries) >= max_entries:
+                    break
+            if not entries:
+                return "Directory is empty."
+            return "\n".join(sorted(entries))
+        except Exception as e:
+            return f"Error listing directory: {e}"

thwip/tools/git_ops.py

@@ -0,0 +1,44 @@
+"""
+Git operations tool for coding agents.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+class GitOps:
+    """Git version control integration."""
+
+    def __init__(self, project_path: str | Path = ".") -> None:
+        self.project_path = Path(project_path).resolve()
+
+    def _run_git(self, args: list[str]) -> str:
+        try:
+            res = subprocess.run(
+                ["git"] + args,
+                cwd=str(self.project_path),
+                capture_output=True,
+                text=True,
+                timeout=15,
+            )
+            out = res.stdout.strip()
+            err = res.stderr.strip()
+            if res.returncode != 0:
+                return f"Git error (code {res.returncode}): {err or out}"
+            return out or "Success."
+        except Exception as e:
+            return f"Git operation failed: {e}"
+
+    def status(self) -> str:
+        return self._run_git(["status", "--short"])
+
+    def diff(self, staged: bool = False) -> str:
+        args = ["diff"]
+        if staged:
+            args.append("--staged")
+        return self._run_git(args)
+
+    def log(self, max_count: int = 5) -> str:
+        return self._run_git(["log", f"-n{max_count}", "--oneline"])

thwip/tools/terminal.py

@@ -0,0 +1,65 @@
+"""
+Terminal execution tools for coding agents.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import subprocess
+from pathlib import Path
+
+
+class TerminalRunner:
+    """Executes commands and captures output in the project directory."""
+
+    def __init__(self, project_path: str | Path = ".") -> None:
+        self.project_path = Path(project_path).resolve()
+
+    def run_command(self, command: str, timeout: int = 30) -> str:
+        """Run a shell command synchronously and return combined stdout/stderr."""
+        try:
+            res = subprocess.run(
+                command,
+                shell=True,
+                cwd=str(self.project_path),
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+            out = res.stdout.strip()
+            err = res.stderr.strip()
+            ret = res.returncode
+            res_str = f"Exit code: {ret}\n"
+            if out:
+                res_str += f"STDOUT:\n{out}\n"
+            if err:
+                res_str += f"STDERR:\n{err}\n"
+            return res_str.strip()
+        except subprocess.TimeoutExpired:
+            return f"Error: Command timed out after {timeout} seconds."
+        except Exception as e:
+            return f"Error executing command: {e}"
+
+    async def run_command_async(self, command: str, timeout: int = 30) -> str:
+        """Run a shell command asynchronously."""
+        try:
+            proc = await asyncio.create_subprocess_shell(
+                command,
+                cwd=str(self.project_path),
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+            out = stdout.decode("utf-8", errors="replace").strip()
+            err = stderr.decode("utf-8", errors="replace").strip()
+            ret = proc.returncode
+            res_str = f"Exit code: {ret}\n"
+            if out:
+                res_str += f"STDOUT:\n{out}\n"
+            if err:
+                res_str += f"STDERR:\n{err}\n"
+            return res_str.strip()
+        except asyncio.TimeoutError:
+            return f"Error: Command timed out after {timeout} seconds."
+        except Exception as e:
+            return f"Error executing command: {e}"

thwip/utils.py

@@ -0,0 +1,110 @@
+"""
+Utility functions for thwip.
+
+Streaming helpers, markdown rendering, token counting, cost estimation.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from typing import AsyncIterator
+
+
+# ---------------------------------------------------------------------------
+# Token & Cost Estimation
+# ---------------------------------------------------------------------------
+
+# Approximate cost per 1M tokens (input/output): updated periodically
+MODEL_PRICING: dict[str, dict[str, float]] = {
+    # Anthropic
+    "claude-sonnet-4": {"input": 3.0, "output": 15.0},
+    "claude-opus-4": {"input": 15.0, "output": 75.0},
+    "claude-haiku-3.5": {"input": 0.80, "output": 4.0},
+    # Google
+    "gemini-2.5-pro": {"input": 1.25, "output": 10.0},
+    "gemini-2.5-flash": {"input": 0.15, "output": 0.60},
+    # OpenAI
+    "gpt-4.1": {"input": 2.0, "output": 8.0},
+    "gpt-4o": {"input": 2.5, "output": 10.0},
+    "o3": {"input": 2.0, "output": 8.0},
+    "o4-mini": {"input": 1.10, "output": 4.40},
+    "codex-mini": {"input": 1.50, "output": 6.0},
+    # DeepSeek
+    "deepseek-chat": {"input": 0.14, "output": 0.28},
+    "deepseek-reasoner": {"input": 0.55, "output": 2.19},
+    # Groq
+    "llama-3.3-70b-versatile": {"input": 0.59, "output": 0.79},
+    "mixtral-8x7b-32768": {"input": 0.24, "output": 0.24},
+    # Mistral
+    "mistral-large-latest": {"input": 2.0, "output": 6.0},
+    "codestral-latest": {"input": 0.30, "output": 0.90},
+}
+
+
+def estimate_cost(model: str, input_tokens: int, output_tokens: int) -> float:
+    """Estimate cost in USD for a given model and token counts."""
+    pricing = MODEL_PRICING.get(model)
+    if not pricing:
+        return 0.0
+    input_cost = (input_tokens / 1_000_000) * pricing["input"]
+    output_cost = (output_tokens / 1_000_000) * pricing["output"]
+    return input_cost + output_cost
+
+
+def format_cost(cost: float) -> str:
+    """Format cost as a readable string."""
+    if cost < 0.01:
+        return f"${cost:.6f}"
+    elif cost < 1.0:
+        return f"${cost:.4f}"
+    else:
+        return f"${cost:.2f}"
+
+
+def format_tokens(count: int) -> str:
+    """Format token count with commas."""
+    if count >= 1_000_000:
+        return f"{count / 1_000_000:.1f}M"
+    elif count >= 1_000:
+        return f"{count / 1_000:.1f}K"
+    return str(count)
+
+
+# ---------------------------------------------------------------------------
+# Async Helpers
+# ---------------------------------------------------------------------------
+
+async def collect_stream(stream: AsyncIterator[str]) -> str:
+    """Collect all chunks from an async stream into a single string."""
+    parts: list[str] = []
+    async for chunk in stream:
+        parts.append(chunk)
+    return "".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# String Helpers
+# ---------------------------------------------------------------------------
+
+def truncate(text: str, max_len: int = 80) -> str:
+    """Truncate text with ellipsis."""
+    if len(text) <= max_len:
+        return text
+    return text[: max_len - 3] + "..."
+
+
+def mask_key(key: str) -> str:
+    """Mask an API key for display: sk-ant-...xyz123"""
+    if not key or len(key) < 10:
+        return "****"
+    return f"{key[:7]}...{key[-6:]}"
+
+
+def slugify(text: str) -> str:
+    """Convert text to a URL/filename-safe slug."""
+    import re
+    text = text.lower().strip()
+    text = re.sub(r"[^\w\s-]", "", text)
+    text = re.sub(r"[\s_]+", "-", text)
+    return text.strip("-")