onetool-mcp 1.0.0b1__py3-none-any.whl

ot/registry/parser.py

@@ -0,0 +1,269 @@
+"""AST parsing utilities for extracting function information."""
+
+from __future__ import annotations
+
+import ast
+from typing import Any
+
+from docstring_parser import parse as parse_docstring_lib
+
+from .models import ArgInfo, ToolInfo
+
+
+def parse_function(
+    node: ast.FunctionDef, module: str, pack: str | None = None
+) -> ToolInfo:
+    """Extract information from a function AST node.
+
+    Args:
+        node: AST FunctionDef node.
+        module: Module path for the function.
+        pack: Optional pack name for namespace-qualified tool names.
+
+    Returns:
+        ToolInfo with extracted signature and docstring info.
+    """
+    # Extract signature (with pack-qualified name if pack is provided)
+    signature = extract_signature(node, pack=pack)
+
+    # Parse docstring
+    docstring = ast.get_docstring(node) or ""
+    doc_info = parse_docstring(docstring)
+
+    # Extract args
+    args = extract_args(node, doc_info.get("args", {}))
+
+    # Extract @tool decorator metadata if present
+    decorator_info = extract_tool_decorator(node)
+
+    # Decorator description overrides docstring if provided
+    description = decorator_info.get("description") or doc_info.get("description", "")
+
+    # Use pack-qualified name if pack is provided
+    qualified_name = f"{pack}.{node.name}" if pack else node.name
+
+    return ToolInfo(
+        name=qualified_name,
+        pack=pack,
+        module=module,
+        signature=signature,
+        description=description,
+        args=args,
+        returns=doc_info.get("returns", ""),
+        examples=decorator_info.get("examples", []),
+        tags=decorator_info.get("tags", []),
+        enabled=decorator_info.get("enabled", True),
+        deprecated=decorator_info.get("deprecated", False),
+        deprecated_message=decorator_info.get("deprecated_message"),
+    )
+
+
+def extract_tool_decorator(node: ast.FunctionDef) -> dict[str, Any]:
+    """Extract metadata from @tool decorator if present.
+
+    Args:
+        node: AST FunctionDef node.
+
+    Returns:
+        Dict with decorator metadata (description, examples, tags, enabled, deprecated).
+    """
+    result: dict[str, Any] = {}
+
+    for decorator in node.decorator_list:
+        # Look for @tool(...) decorator
+        if isinstance(decorator, ast.Call):
+            func = decorator.func
+            if isinstance(func, ast.Name) and func.id == "tool":
+                # Extract keyword arguments
+                for keyword in decorator.keywords:
+                    if keyword.arg == "description":
+                        if isinstance(keyword.value, ast.Constant):
+                            result["description"] = keyword.value.value
+                    elif keyword.arg == "examples":
+                        if isinstance(keyword.value, ast.List):
+                            result["examples"] = [
+                                elt.value
+                                for elt in keyword.value.elts
+                                if isinstance(elt, ast.Constant)
+                            ]
+                    elif keyword.arg == "tags":
+                        if isinstance(keyword.value, ast.List):
+                            result["tags"] = [
+                                elt.value
+                                for elt in keyword.value.elts
+                                if isinstance(elt, ast.Constant)
+                            ]
+                    elif keyword.arg == "enabled":
+                        if isinstance(keyword.value, ast.Constant):
+                            result["enabled"] = keyword.value.value
+                    elif keyword.arg == "deprecated" and isinstance(
+                        keyword.value, ast.Constant
+                    ):
+                        result["deprecated"] = keyword.value.value
+                    elif keyword.arg == "deprecated_message" and isinstance(
+                        keyword.value, ast.Constant
+                    ):
+                        result["deprecated_message"] = keyword.value.value
+                break
+
+    return result
+
+
+def extract_signature(node: ast.FunctionDef, pack: str | None = None) -> str:
+    """Extract function signature string.
+
+    Args:
+        node: AST FunctionDef node.
+        pack: Optional pack name for namespace-qualified tool names.
+
+    Returns:
+        Signature string like 'pack.func_name(arg: type = default) -> return_type'
+    """
+    parts: list[str] = []
+
+    # Process regular args
+    args = node.args
+    defaults = args.defaults
+    num_defaults = len(defaults)
+    num_args = len(args.args)
+
+    for i, arg in enumerate(args.args):
+        arg_str = arg.arg
+        # Add type annotation
+        if arg.annotation:
+            arg_str += f": {annotation_to_str(arg.annotation)}"
+
+        # Add default value if present
+        default_idx = i - (num_args - num_defaults)
+        if default_idx >= 0:
+            default = defaults[default_idx]
+            arg_str += f" = {value_to_str(default)}"
+
+        parts.append(arg_str)
+
+    # Process keyword-only args
+    kw_defaults = args.kw_defaults
+    for i, arg in enumerate(args.kwonlyargs):
+        arg_str = arg.arg
+        if arg.annotation:
+            arg_str += f": {annotation_to_str(arg.annotation)}"
+        if kw_defaults[i] is not None:
+            arg_str += f" = {value_to_str(kw_defaults[i])}"
+        parts.append(arg_str)
+
+    # Build signature with pack-qualified name if pack is provided
+    func_name = f"{pack}.{node.name}" if pack else node.name
+    sig = f"{func_name}({', '.join(parts)})"
+
+    # Add return type
+    if node.returns:
+        sig += f" -> {annotation_to_str(node.returns)}"
+
+    return sig
+
+
+def annotation_to_str(node: ast.expr) -> str:
+    """Convert AST annotation node to string.
+
+    Args:
+        node: AST expression node representing a type annotation.
+
+    Returns:
+        String representation of the type.
+    """
+    return ast.unparse(node)
+
+
+def value_to_str(node: ast.expr | None) -> str:
+    """Convert AST value node to string representation.
+
+    Args:
+        node: AST expression node representing a default value.
+
+    Returns:
+        String representation of the value.
+    """
+    if node is None:
+        return "None"
+    return ast.unparse(node)
+
+
+def extract_args(
+    node: ast.FunctionDef, docstring_args: dict[str, str]
+) -> list[ArgInfo]:
+    """Extract argument information from function node.
+
+    Args:
+        node: AST FunctionDef node.
+        docstring_args: Dict of arg_name -> description from docstring.
+
+    Returns:
+        List of ArgInfo objects.
+    """
+    result: list[ArgInfo] = []
+    args = node.args
+    defaults = args.defaults
+    num_defaults = len(defaults)
+    num_args = len(args.args)
+
+    for i, arg in enumerate(args.args):
+        type_str = "Any"
+        if arg.annotation:
+            type_str = annotation_to_str(arg.annotation)
+
+        default_str: str | None = None
+        default_idx = i - (num_args - num_defaults)
+        if default_idx >= 0:
+            default_str = value_to_str(defaults[default_idx])
+
+        result.append(
+            ArgInfo(
+                name=arg.arg,
+                type=type_str,
+                default=default_str,
+                description=docstring_args.get(arg.arg, ""),
+            )
+        )
+
+    # Keyword-only args
+    kw_defaults = args.kw_defaults
+    for i, arg in enumerate(args.kwonlyargs):
+        type_str = "Any"
+        if arg.annotation:
+            type_str = annotation_to_str(arg.annotation)
+
+        default_str = None
+        if kw_defaults[i] is not None:
+            default_str = value_to_str(kw_defaults[i])
+
+        result.append(
+            ArgInfo(
+                name=arg.arg,
+                type=type_str,
+                default=default_str,
+                description=docstring_args.get(arg.arg, ""),
+            )
+        )
+
+    return result
+
+
+def parse_docstring(docstring: str) -> dict[str, Any]:
+    """Parse Google-style docstring.
+
+    Args:
+        docstring: The docstring to parse.
+
+    Returns:
+        Dict with 'description', 'args', and 'returns' keys.
+    """
+    if not docstring:
+        return {"description": "", "args": {}, "returns": ""}
+
+    parsed = parse_docstring_lib(docstring)
+
+    return {
+        "description": parsed.short_description or "",
+        "args": {p.arg_name: p.description or "" for p in parsed.params},
+        "returns": parsed.returns.description if parsed.returns else "",
+    }

ot/registry/registry.py

@@ -0,0 +1,413 @@
+"""Tool registry class for auto-discovering Python tools."""
+
+from __future__ import annotations
+
+import ast
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+
+from loguru import logger
+
+from ot.logging import LogEntry
+
+from .parser import parse_function
+
+if TYPE_CHECKING:
+    from .models import ToolInfo
+
+
+class ToolRegistry:
+    """Registry for auto-discovered Python tools.
+
+    Scans a directory for Python files and extracts function information
+    using AST parsing (no execution required).
+    """
+
+    def __init__(self, tools_path: Path | None = None) -> None:
+        """Initialize the registry.
+
+        Args:
+            tools_path: Path to tools directory. Defaults to 'src/ot_tools/'.
+        """
+        self._tools_path = tools_path or Path("src/ot_tools")
+        self._tools: dict[str, ToolInfo] = {}
+
+    @property
+    def tools_path(self) -> Path:
+        """Return the tools directory path."""
+        return self._tools_path
+
+    @property
+    def tools(self) -> dict[str, ToolInfo]:
+        """Return dictionary of registered tools by name."""
+        return self._tools.copy()
+
+    def scan_files(self, files: list[Path]) -> list[ToolInfo]:
+        """Scan specific Python files and register public functions.
+
+        Args:
+            files: List of Python files to scan.
+
+        Returns:
+            List of registered ToolInfo objects.
+        """
+        # Track previous state to detect changes
+        previous_tools = dict(self._tools)
+        self._tools.clear()
+
+        for py_file in files:
+            if not py_file.exists():
+                logger.debug(
+                    LogEntry(span="registry.scan", path=str(py_file), exists=False)
+                )
+                continue
+            try:
+                tools = self.parse_file(py_file)
+                for tool in tools:
+                    if tool.name in self._tools:
+                        logger.warning(
+                            LogEntry(
+                                span="registry.duplicate",
+                                tool=tool.name,
+                                file=str(py_file),
+                            )
+                        )
+                    self._tools[tool.name] = tool
+            except SyntaxError as e:
+                logger.warning(
+                    LogEntry(
+                        span="registry.error",
+                        file=str(py_file),
+                        error=str(e),
+                        errorType="SyntaxError",
+                    )
+                )
+            except Exception as e:
+                logger.warning(
+                    LogEntry(
+                        span="registry.error",
+                        file=str(py_file),
+                        error=str(e),
+                        errorType=type(e).__name__,
+                    )
+                )
+
+        # Detect added/changed/removed tools
+        added: list[str] = []
+        changed: list[str] = []
+        removed: list[str] = []
+
+        for name, tool in self._tools.items():
+            if name not in previous_tools:
+                added.append(name)
+            elif tool.signature != previous_tools[name].signature:
+                changed.append(name)
+
+        for name in previous_tools:
+            if name not in self._tools:
+                removed.append(name)
+
+        # Only log if this is first scan or there are changes
+        if not previous_tools:
+            # First scan - log all tools
+            logger.info(
+                LogEntry(
+                    span="registry.ready",
+                    path="tools",
+                    toolCount=len(self._tools),
+                    tools=[tool.name for tool in self._tools.values()],
+                )
+            )
+        elif added or changed or removed:
+            # Subsequent scan with changes
+            logger.info(
+                LogEntry(
+                    span="registry.changed",
+                    path="tools",
+                    toolCount=len(self._tools),
+                    added=added if added else None,
+                    changed=changed if changed else None,
+                    removed=removed if removed else None,
+                )
+            )
+
+        return list(self._tools.values())
+
+    def scan_directory(self, path: Path | None = None) -> list[ToolInfo]:
+        """Scan directory for Python files and register public functions.
+
+        Args:
+            path: Directory to scan. Defaults to self.tools_path.
+
+        Returns:
+            List of registered ToolInfo objects.
+        """
+        scan_path = path or self._tools_path
+
+        if not scan_path.exists():
+            logger.debug(
+                LogEntry(span="registry.scan", path=str(scan_path), exists=False)
+            )
+            return []
+
+        if not scan_path.is_dir():
+            logger.warning(
+                LogEntry(span="registry.scan", path=str(scan_path), isDir=False)
+            )
+            return []
+
+        py_files = list(scan_path.glob("*.py"))
+        return self.scan_files(py_files)
+
+    def parse_file(self, path: Path) -> list[ToolInfo]:
+        """Parse a Python file and extract public function information.
+
+        Args:
+            path: Path to Python file.
+
+        Returns:
+            List of ToolInfo for exported functions (respects __all__ and pack).
+        """
+        source = path.read_text(encoding="utf-8")
+        tree = ast.parse(source, filename=str(path))
+
+        # Module name: tools/gold_prices.py -> tools.gold_prices
+        module_name = f"tools.{path.stem}"
+
+        # Extract pack variable (e.g., pack = "code")
+        pack = self._extract_pack(tree)
+
+        # Extract __all__ list if present
+        export_names = self._extract_all(tree)
+
+        # Extract __ot_requires__ dependencies
+        requires = self._extract_requires(tree)
+
+        tools: list[ToolInfo] = []
+        for node in ast.walk(tree):
+            if isinstance(node, ast.FunctionDef):
+                # Skip private functions
+                if node.name.startswith("_"):
+                    continue
+
+                # If __all__ is defined, only include exported functions
+                if export_names is not None and node.name not in export_names:
+                    continue
+
+                tool = parse_function(node, module_name, pack=pack)
+                # Attach module-level requires to tool
+                if requires:
+                    tool.requires = requires
+                tools.append(tool)
+
+        return tools
+
+    def _extract_pack(self, tree: ast.Module) -> str | None:
+        """Extract pack variable from module AST.
+
+        Looks for module-level assignment: pack = "pack_name"
+
+        Args:
+            tree: Parsed AST module.
+
+        Returns:
+            Pack name string if found, None otherwise.
+        """
+        for node in tree.body:
+            if isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if (
+                        isinstance(target, ast.Name)
+                        and target.id == "pack"
+                        and isinstance(node.value, ast.Constant)
+                        and isinstance(node.value.value, str)
+                    ):
+                        return node.value.value
+        return None
+
+    def _extract_all(self, tree: ast.Module) -> set[str] | None:
+        """Extract __all__ list from module AST.
+
+        Looks for module-level assignment: __all__ = ["func1", "func2"]
+
+        Args:
+            tree: Parsed AST module.
+
+        Returns:
+            Set of exported names if __all__ is defined, None otherwise.
+        """
+        for node in tree.body:
+            if isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if (
+                        isinstance(target, ast.Name)
+                        and target.id == "__all__"
+                        and isinstance(node.value, ast.List)
+                    ):
+                        names: set[str] = set()
+                        for elt in node.value.elts:
+                            if isinstance(elt, ast.Constant) and isinstance(
+                                elt.value, str
+                            ):
+                                names.add(elt.value)
+                        return names
+        return None
+
+    def _extract_requires(
+        self, tree: ast.Module
+    ) -> dict[str, list[tuple[str, ...] | dict[str, str] | str]] | None:
+        """Extract __ot_requires__ dict from module AST.
+
+        Looks for module-level assignment: __ot_requires__ = {"cli": [...], "lib": [...]}
+
+        Args:
+            tree: Parsed AST module.
+
+        Returns:
+            Dict with 'cli' and 'lib' dependency lists if found, None otherwise.
+        """
+        for node in tree.body:
+            if isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if isinstance(target, ast.Name) and target.id == "__ot_requires__":
+                        try:
+                            # Safely evaluate the dict literal
+                            result = ast.literal_eval(ast.unparse(node.value))
+                            return cast(
+                                "dict[str, list[tuple[str, ...] | dict[str, str] | str]]",
+                                result,
+                            )
+                        except (ValueError, TypeError):
+                            return None
+        return None
+
+    def format_json(self) -> str:
+        """Format registry as JSON for LLM context.
+
+        Returns:
+            JSON string with tool definitions.
+        """
+        if not self._tools:
+            return '{"tools":[]}'
+
+        tools_list: list[dict[str, Any]] = []
+        for tool in self._tools.values():
+            tool_dict: dict[str, Any] = {
+                "name": tool.name,
+                "module": tool.module,
+                "signature": tool.signature,
+            }
+            if tool.description:
+                tool_dict["description"] = tool.description
+            if tool.args:
+                tool_dict["args"] = [
+                    {
+                        k: v
+                        for k, v in {
+                            "name": arg.name,
+                            "type": arg.type,
+                            "default": arg.default,
+                            "description": arg.description if arg.description else None,
+                        }.items()
+                        if v is not None
+                    }
+                    for arg in tool.args
+                ]
+            if tool.returns:
+                tool_dict["returns"] = tool.returns
+
+            tools_list.append(tool_dict)
+
+        return json.dumps({"tools": tools_list}, ensure_ascii=False, indent=2)
+
+    def format_summary(self) -> str:
+        """Format registry summary for CLI display.
+
+        Returns:
+            Human-readable summary of registered tools.
+        """
+        if not self._tools:
+            return "No tools registered."
+
+        lines = [f"Registered tools ({len(self._tools)}):"]
+        for tool in self._tools.values():
+            lines.append(f"  - {tool.signature}")
+            if tool.description:
+                lines.append(f"      {tool.description}")
+
+        return "\n".join(lines)
+
+    def get_tool(self, name: str) -> ToolInfo | None:
+        """Get tool by name.
+
+        Args:
+            name: Tool function name.
+
+        Returns:
+            ToolInfo if found, None otherwise.
+        """
+        return self._tools.get(name)
+
+    def register_tool(self, tool: ToolInfo) -> None:
+        """Register a tool programmatically.
+
+        Used for tools that aren't loaded from files (e.g., ot pack tools).
+
+        Args:
+            tool: ToolInfo object to register.
+        """
+        self._tools[tool.name] = tool
+
+    def describe_tool(self, name: str) -> str:
+        """Get detailed description of a tool.
+
+        Args:
+            name: Tool function name.
+
+        Returns:
+            Detailed tool description string.
+        """
+        tool = self._tools.get(name)
+        if not tool:
+            return f"Tool '{name}' not found."
+
+        lines = [
+            f"Tool: {tool.name}",
+            f"Module: {tool.module}",
+            f"Signature: {tool.signature}",
+        ]
+
+        # Show deprecation warning first
+        if tool.deprecated:
+            msg = tool.deprecated_message or "This tool is deprecated"
+            lines.append(f"DEPRECATED: {msg}")
+
+        if not tool.enabled:
+            lines.append("Status: DISABLED")
+
+        if tool.description:
+            lines.append(f"Description: {tool.description}")
+
+        if tool.tags:
+            lines.append(f"Tags: {', '.join(tool.tags)}")
+
+        if tool.args:
+            lines.append("Arguments:")
+            for arg in tool.args:
+                arg_line = f"  - {arg.name}: {arg.type}"
+                if arg.default is not None:
+                    arg_line += f" = {arg.default}"
+                lines.append(arg_line)
+                if arg.description:
+                    lines.append(f"      {arg.description}")
+
+        if tool.returns:
+            lines.append(f"Returns: {tool.returns}")
+
+        if tool.examples:
+            lines.append("Examples:")
+            for example in tool.examples:
+                lines.append(f"  {example}")
+
+        return "\n".join(lines)