tinychat-builtin-tools 0.1.0__tar.gz

tinychat_builtin_tools-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: tinychat-builtin-tools
+Version: 0.1.0
+Summary: Built-in tools for TinyChat: file I/O, shell execution, search, and workflow
+License-Expression: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: tinychat-ai

tinychat_builtin_tools-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tinychat-builtin-tools"
+version = "0.1.0"
+description = "Built-in tools for TinyChat: file I/O, shell execution, search, and workflow"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = [
+    "tinychat-ai",
+]
+
+[project.entry-points."tinychat.tools"]
+read_file = "tinychat_builtin_tools.files:ReadFileTool"
+write_file = "tinychat_builtin_tools.files:WriteFileTool"
+edit_file = "tinychat_builtin_tools.files:EditFileTool"
+exec_shell = "tinychat_builtin_tools.shell:ExecShellTool"
+list_directory = "tinychat_builtin_tools.fs:ListDirectoryTool"
+glob = "tinychat_builtin_tools.search:GlobTool"
+grep = "tinychat_builtin_tools.search:GrepTool"
+todo_list = "tinychat_builtin_tools.todos:TodoListTool"
+no_action = "tinychat_builtin_tools.no_action:NoActionTool"
+
+[tool.setuptools.packages.find]
+where = ["src"]

tinychat_builtin_tools-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tinychat_builtin_tools-0.1.0/src/tinychat_builtin_tools/__init__.py

@@ -0,0 +1,3 @@
+"""TinyChat built-in tools plugin."""
+
+__version__ = "0.1.0"

tinychat_builtin_tools-0.1.0/src/tinychat_builtin_tools/command_config.py

@@ -0,0 +1,141 @@
+"""Command configuration loader for shell tool whitelist."""
+
+from dataclasses import dataclass, field
+from typing import Any
+from pathlib import Path
+import logging
+import os
+
+try:
+    import tomllib
+except ImportError:
+    import tomli as tomllib
+
+from tinychat_builtin_tools.shell_defaults import get_default_commands
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CommandConfig:
+    """Configuration for command whitelist."""
+    
+    version: int = 1
+    override_defaults: bool = False
+    commands: dict[str, Any] = field(default_factory=dict)
+
+
+class CommandConfigLoader:
+    """Loads command whitelist configuration from TOML file."""
+    
+    def __init__(self) -> None:
+        """Initialize the config loader."""
+        self._config_path: Path | None = None
+    
+    def get_config_path(self) -> Path:
+        """Return the path to commands.toml configuration file.
+        
+        Uses XDG_CONFIG_HOME if set, otherwise ~/.config
+        
+        Returns:
+            Path to ~/.config/tinychat/commands.toml or ${XDG_CONFIG_HOME}/tinychat/commands.toml
+        """
+        if self._config_path:
+            return self._config_path
+        
+        xdg_config = os.environ.get("XDG_CONFIG_HOME")
+        if xdg_config:
+            config_dir = Path(xdg_config) / "tinychat"
+        else:
+            config_dir = Path.home() / ".config" / "tinychat"
+        
+        self._config_path = config_dir / "commands.toml"
+        return self._config_path
+    
+    def load(self) -> CommandConfig:
+        """Load command configuration from file.
+        
+        If file doesn't exist, returns default configuration.
+        If override_defaults is False, merges user config with defaults.
+        
+        Returns:
+            CommandConfig with loaded settings
+        """
+        config_path = self.get_config_path()
+        
+        if not config_path.exists():
+            logger.debug(f"Config file not found at {config_path}, using defaults")
+            return CommandConfig(
+                version=1,
+                override_defaults=False,
+                commands=get_default_commands(),
+            )
+        
+        try:
+            with open(config_path, "rb") as f:
+                data = tomllib.load(f)
+        except (tomllib.TOMLDecodeError, OSError) as e:
+            logger.warning(f"Failed to parse config file {config_path}: {e}")
+            return CommandConfig(
+                version=1,
+                override_defaults=False,
+                commands=get_default_commands(),
+            )
+        
+        version = data.get("version", 1)
+        override_defaults = data.get("override_defaults", False)
+        user_commands = self._parse_commands(data)
+        
+        if override_defaults:
+            # Use only user-defined commands
+            final_commands = user_commands
+        else:
+            # Merge defaults with user commands (user takes precedence)
+            final_commands = get_default_commands()
+            final_commands.update(user_commands)
+        
+        return CommandConfig(
+            version=version,
+            override_defaults=override_defaults,
+            commands=final_commands,
+        )
+    
+    def _parse_commands(self, data: dict[str, Any]) -> dict[str, Any]:
+        """Parse command definitions from TOML data.
+        
+        Supports two formats:
+        1. Array format: [[commands]]
+        2. Dict format: [commands.name]
+        
+        Args:
+            data: Parsed TOML data
+            
+        Returns:
+            Dict mapping command name to its configuration
+        """
+        result: dict[str, Any] = {}
+        
+        # Try array format: [[commands]]
+        commands_list = data.get("commands", [])
+        if isinstance(commands_list, list):
+            for cmd_def in commands_list:
+                if not isinstance(cmd_def, dict):
+                    continue
+                name = cmd_def.get("name")
+                if not name:
+                    continue
+                result[name] = {
+                    "allowed_args": cmd_def.get("allowed_args", []),
+                    "blocked_args": cmd_def.get("blocked_args", []),
+                }
+        elif isinstance(commands_list, dict):
+            # Dict format: [commands.name]
+            for name, cmd_def in commands_list.items():
+                if not isinstance(cmd_def, dict):
+                    continue
+                result[name] = {
+                    "allowed_args": cmd_def.get("allowed_args", []),
+                    "blocked_args": cmd_def.get("blocked_args", []),
+                }
+        
+        return result

tinychat_builtin_tools-0.1.0/src/tinychat_builtin_tools/files.py

@@ -0,0 +1,295 @@
+"""File operation tools: read_file and write_file."""
+
+import os
+from typing import Any
+
+from tinychat.tools.base import Tool, ToolParameter, ToolResult
+
+
+class ReadFileTool(Tool):
+    """Tool for reading text files with offset/limit/tail support."""
+
+    @property
+    def name(self) -> str:
+        return "read_file"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Read the contents of a text file from the filesystem. "
+            "Use when you need to inspect actual file contents to answer a question "
+            "or when the user explicitly asks to read/view a file. "
+            "Do NOT use this for: translation, explaining concepts, or any task "
+            "that does not require reading a specific file. "
+            "Returns: ToolResult with success (bool), output (str), error (str|None), "
+            "metadata.total_lines (int), metadata.lines_returned (int)."
+        )
+
+    @property
+    def parameters(self) -> list[ToolParameter]:
+        return [
+            ToolParameter(
+                name="path",
+                type="string",
+                description="Absolute or relative path to the file to read",
+                required=True,
+            ),
+            ToolParameter(
+                name="offset",
+                type="number",
+                description="Line number to start reading from (1-indexed)",
+                required=False,
+                default=1,
+            ),
+            ToolParameter(
+                name="limit",
+                type="number",
+                description="Maximum number of lines to read",
+                required=False,
+                default=2000,
+            ),
+            ToolParameter(
+                name="tail",
+                type="number",
+                description="Read the last N lines of the file (overrides offset/limit)",
+                required=False,
+            ),
+        ]
+
+    async def execute(self, arguments: dict[str, Any]) -> ToolResult:
+        path = arguments.get("path", "")
+        offset = arguments.get("offset", 1)
+        limit = arguments.get("limit", 2000)
+        tail = arguments.get("tail")
+
+        if not os.path.isfile(path):
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"File not found: {path}",
+            )
+
+        try:
+            with open(path, "r", encoding="utf-8", errors="replace") as f:
+                all_lines = f.readlines()
+        except Exception as e:
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"Error reading file: {e}",
+            )
+
+        if tail is not None and tail > 0:
+            selected = all_lines[-tail:]
+        else:
+            start = max(0, offset - 1)
+            selected = all_lines[start : start + limit]
+
+        output = "".join(selected)
+        total_lines = len(all_lines)
+
+        return ToolResult(
+            success=True,
+            output=output,
+            metadata={
+                "total_lines": total_lines,
+                "lines_returned": len(selected),
+            },
+        )
+
+
+class WriteFileTool(Tool):
+    """Tool for writing content to files."""
+
+    @property
+    def name(self) -> str:
+        return "write_file"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Write content to a file. Creates the file if it does not exist, "
+            "or overwrites it if it does. Parent directories will be created automatically. "
+            "Use when you need to create or edit a file that the user explicitly asks for. "
+            "Do NOT use this for generating text, answering questions, or any task "
+            "that does not require writing to a specific file. "
+            "Returns: ToolResult with success (bool), output (str), error (str|None), "
+            "metadata.path (str), metadata.characters_written (int)."
+        )
+
+    @property
+    def parameters(self) -> list[ToolParameter]:
+        return [
+            ToolParameter(
+                name="path",
+                type="string",
+                description="Absolute or relative path to the file to write",
+                required=True,
+            ),
+            ToolParameter(
+                name="content",
+                type="string",
+                description="The content to write to the file",
+                required=True,
+            ),
+        ]
+
+    async def execute(self, arguments: dict[str, Any]) -> ToolResult:
+        path = arguments.get("path", "")
+        content = arguments.get("content", "")
+
+        if not path:
+            return ToolResult(
+                success=False,
+                output="",
+                error="No file path provided",
+            )
+
+        try:
+            parent = os.path.dirname(path)
+            if parent:
+                os.makedirs(parent, exist_ok=True)
+
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(content)
+
+            return ToolResult(
+                success=True,
+                output=f"Successfully wrote {len(content)} characters to {path}",
+                metadata={
+                    "path": path,
+                    "characters_written": len(content),
+                },
+            )
+        except Exception as e:
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"Error writing file: {e}",
+            )
+
+
+class EditFileTool(Tool):
+    """Tool for editing files by replacing strings."""
+
+    @property
+    def name(self) -> str:
+        return "edit_file"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Edit a text file by replacing a specific string with new content. "
+            "Supports replacing all occurrences with the replace_all flag. "
+            "Use when you need to modify specific content in an existing file. "
+            "Do NOT use this for creating new files, appending content, "
+            "or any task that does not require editing an existing file. "
+            "Returns: ToolResult with success (bool), output (str), error (str|None), "
+            "metadata.replacements_made (int)."
+        )
+
+    @property
+    def parameters(self) -> list[ToolParameter]:
+        return [
+            ToolParameter(
+                name="path",
+                type="string",
+                description="Absolute or relative path to the file to edit",
+                required=True,
+            ),
+            ToolParameter(
+                name="old_string",
+                type="string",
+                description="The exact string to find and replace",
+                required=True,
+            ),
+            ToolParameter(
+                name="new_string",
+                type="string",
+                description="The replacement string",
+                required=True,
+            ),
+            ToolParameter(
+                name="replace_all",
+                type="boolean",
+                description="Replace all occurrences of old_string (default: false)",
+                required=False,
+                default=False,
+            ),
+        ]
+
+    async def execute(self, arguments: dict[str, Any]) -> ToolResult:
+        path = arguments.get("path", "")
+        old_string = arguments.get("old_string", "")
+        new_string = arguments.get("new_string", "")
+        replace_all = arguments.get("replace_all", False)
+
+        if not path:
+            return ToolResult(
+                success=False,
+                output="",
+                error="No file path provided",
+            )
+
+        if not old_string:
+            return ToolResult(
+                success=False,
+                output="",
+                error="old_string cannot be empty",
+            )
+
+        if not os.path.isfile(path):
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"File not found: {path}",
+            )
+
+        try:
+            with open(path, "r", encoding="utf-8", errors="replace") as f:
+                content = f.read()
+        except Exception as e:
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"Error reading file: {e}",
+            )
+
+        if replace_all:
+            new_content = content.replace(old_string, new_string)
+            replacements_made = content.count(old_string)
+        else:
+            if old_string in content:
+                new_content = content.replace(old_string, new_string, 1)
+                replacements_made = 1
+            else:
+                return ToolResult(
+                    success=False,
+                    output="",
+                    error=f"String '{old_string}' not found in file",
+                )
+
+        if replacements_made == 0 and not replace_all:
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"String '{old_string}' not found in file",
+            )
+
+        try:
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(new_content)
+
+            return ToolResult(
+                success=True,
+                output=f"Successfully made {replacements_made} replacement(s) in {path}",
+                metadata={
+                    "replacements_made": replacements_made,
+                },
+            )
+        except Exception as e:
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"Error writing file: {e}",
+            )

tinychat_builtin_tools-0.1.0/src/tinychat_builtin_tools/fs.py

@@ -0,0 +1,76 @@
+"""Filesystem operation tools."""
+
+import os
+from typing import Any
+
+from tinychat.tools.base import Tool, ToolParameter, ToolResult
+
+
+class ListDirectoryTool(Tool):
+    """Tool for listing directory contents."""
+
+    @property
+    def name(self) -> str:
+        return "list_directory"
+
+    @property
+    def description(self) -> str:
+        return (
+            "List the contents of a directory. "
+            "Use when you need to explore the filesystem, find files, "
+            "or understand the structure of a directory. "
+            "Do NOT use this for reading file contents, writing files, "
+            "translation, or any task that does not require listing directory contents. "
+            "Returns: ToolResult with success (bool), output (str), error (str|None), "
+            "metadata.entry_count (int). Subdirectories are marked with '/' suffix."
+        )
+
+    @property
+    def parameters(self) -> list[ToolParameter]:
+        return [
+            ToolParameter(
+                name="path",
+                type="string",
+                description="Absolute or relative path to the directory to list",
+                required=False,
+                default=".",
+            ),
+        ]
+
+    async def execute(self, arguments: dict[str, Any]) -> ToolResult:
+        path = arguments.get("path", ".")
+
+        if not os.path.isdir(path):
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"Directory not found: {path}",
+            )
+
+        try:
+            entries = os.listdir(path)
+            sorted_entries = sorted(entries)
+
+            output_lines = []
+            for entry in sorted_entries:
+                entry_path = os.path.join(path, entry)
+                if os.path.isdir(entry_path):
+                    output_lines.append(f"{entry}/")
+                else:
+                    output_lines.append(entry)
+
+            output = "\n".join(output_lines)
+
+            return ToolResult(
+                success=True,
+                output=output,
+                metadata={
+                    "entry_count": len(sorted_entries),
+                },
+            )
+        except Exception as e:
+            return ToolResult(
+                success=False,
+                output="",
+                error=f"Error listing directory: {e}",
+            )

tinychat_builtin_tools-0.1.0/src/tinychat_builtin_tools/no_action.py

@@ -0,0 +1,27 @@
+"""No-action tool: explicit exit channel to avoid unnecessary tool calls."""
+
+from typing import Any
+
+from tinychat.tools.base import Tool, ToolParameter, ToolResult
+
+
+class NoActionTool(Tool):
+    @property
+    def name(self) -> str:
+        return "no_action"
+
+    @property
+    def description(self) -> str:
+        return (
+            "Use this tool when you can answer the user's question directly "
+            "from your own knowledge without needing any external tool. "
+            "This is the default choice for most questions. "
+            "Do NOT use any other tool if you can answer directly."
+        )
+
+    @property
+    def parameters(self) -> list[ToolParameter]:
+        return []
+
+    async def execute(self, arguments: dict[str, Any]) -> ToolResult:
+        return ToolResult(success=True, output="")