toolfuncs 0.1.0__py3-none-any.whl

toolfuncs/__init__.py

@@ -0,0 +1,89 @@
+"""Function-first Python tools with matching import and CLI interfaces."""
+
+from __future__ import annotations
+
+from types import ModuleType
+
+from ._discovery import Tool, ToolKind, discover_tools, load_tool, resolve_tool
+from ._errors import (
+    DependencyMetadataError,
+    ImportConflictError,
+    ImportNameError,
+    InvalidSourceError,
+    ShimConflictError,
+    ToolDefinitionError,
+    ToolfuncsError,
+    ToolMetadataError,
+    ToolNotFoundError,
+)
+from ._importer import import_path
+from ._shims import SyncResult, sync
+from .sdk import (
+    UNSET,
+    App,
+    Group,
+    Parameter,
+    ResultAction,
+    Token,
+    application,
+    json_result_action,
+    run,
+    to_jsonable_python,
+    types,
+    validators,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "UNSET",
+    "App",
+    "DependencyMetadataError",
+    "Group",
+    "ImportConflictError",
+    "ImportNameError",
+    "InvalidSourceError",
+    "Parameter",
+    "ResultAction",
+    "ShimConflictError",
+    "SyncResult",
+    "Token",
+    "Tool",
+    "ToolDefinitionError",
+    "ToolKind",
+    "ToolMetadataError",
+    "ToolNotFoundError",
+    "ToolfuncsError",
+    "application",
+    "discover_tools",
+    "import_path",
+    "json_result_action",
+    "load_tool",
+    "resolve_tool",
+    "run",
+    "sync",
+    "to_jsonable_python",
+    "types",
+    "validators",
+]
+
+_PUBLIC_API = frozenset(__all__)
+
+
+def __getattr__(name: str) -> ModuleType:
+    """Dynamically expose scoped tools for ``from toolfuncs import name``."""
+
+    if name.startswith("_"):
+        raise AttributeError(name)
+    try:
+        module = load_tool(name)
+    except ToolNotFoundError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    globals()[name] = module
+    return module
+
+
+def __dir__() -> list[str]:
+    """Include effective scoped tools in interactive completion."""
+
+    return sorted(_PUBLIC_API | {tool.name for tool in discover_tools()})

toolfuncs/__main__.py

@@ -0,0 +1,79 @@
+"""Management and universal dispatch CLI for toolfuncs."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Sequence
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+from pydantic_core import to_jsonable_python
+
+from ._discovery import discover_tools, load_tool, resolve_tool
+from ._shims import sync
+from .sdk import run as run_module
+
+_HELP = """\
+Usage:
+  toolfuncs TOOL [ARGS...]
+  toolfuncs run TOOL [ARGS...]
+  toolfuncs list
+  toolfuncs describe TOOL
+  toolfuncs sync [--bin-dir DIRECTORY]
+
+Project tools in the nearest .agents/tools directory shadow tools in
+~/.agents/tools. TOOL is dispatched to the typed functions registered on its
+module-level app. Use `toolfuncs TOOL --help` for the generated function CLI.
+"""
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Dispatch the management command or one scoped function-first tool."""
+
+    tokens = list(sys.argv[1:] if argv is None else argv)
+    if not tokens or tokens[0] in {"-h", "--help", "help"}:
+        print(_HELP, end="")
+        return 0
+
+    command = tokens.pop(0)
+    if command == "list":
+        if tokens:
+            raise SystemExit("toolfuncs list accepts no arguments")
+        _print_json([asdict(tool) for tool in discover_tools()])
+        return 0
+    if command == "describe":
+        if len(tokens) != 1:
+            raise SystemExit("usage: toolfuncs describe TOOL")
+        tool = resolve_tool(tokens[0])
+        _print_json(asdict(tool))
+        return 0
+    if command == "sync":
+        bin_dir = _parse_sync(tokens)
+        _print_json(asdict(sync(bin_dir)))
+        return 0
+    if command == "run":
+        if not tokens:
+            raise SystemExit("usage: toolfuncs run TOOL [ARGS...]")
+        command = tokens.pop(0)
+
+    module = load_tool(command)
+    result = run_module(tokens, module=module)
+    return result if isinstance(result, int) else 0
+
+
+def _parse_sync(tokens: list[str]) -> Path:
+    if not tokens:
+        return Path.home() / ".local" / "bin"
+    if len(tokens) == 2 and tokens[0] == "--bin-dir":
+        return Path(tokens[1])
+    raise SystemExit("usage: toolfuncs sync [--bin-dir DIRECTORY]")
+
+
+def _print_json(value: Any) -> None:
+    print(json.dumps(value, default=to_jsonable_python, allow_nan=False))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

toolfuncs/_discovery.py

@@ -0,0 +1,147 @@
+"""Scoped discovery for project and user tool directories."""
+
+from __future__ import annotations
+
+import keyword
+from dataclasses import dataclass
+from pathlib import Path
+from types import ModuleType
+from typing import Literal
+
+from ._errors import InvalidSourceError, ToolNotFoundError
+from ._importer import import_path
+from ._metadata import inline_tool_metadata, project_tool_metadata
+
+Scope = Literal["project", "user"]
+ToolKind = Literal["script", "package"]
+
+
+@dataclass(frozen=True, slots=True)
+class Tool:
+    """One effective tool source found in a discovery scope."""
+
+    name: str
+    path: Path
+    scope: Scope
+    kind: ToolKind
+    description: str
+
+
+_INITIAL_CWD = Path.cwd().resolve()
+_INITIAL_HOME = Path.home().resolve()
+
+
+def discover_tools(
+    *, cwd: str | Path | None = None, home: str | Path | None = None
+) -> tuple[Tool, ...]:
+    """Return effective tools, with the nearest project scope shadowing user scope."""
+
+    working_directory = Path(cwd).expanduser().resolve() if cwd is not None else _INITIAL_CWD
+    home_directory = Path(home).expanduser().resolve() if home is not None else _INITIAL_HOME
+    user = _scan_root(home_directory / ".agents" / "tools", scope="user")
+    project_root = _nearest_project_tools_root(working_directory, home=home_directory)
+    project = _scan_root(project_root, scope="project") if project_root is not None else {}
+    effective = {**user, **project}
+    return tuple(effective[name] for name in sorted(effective))
+
+
+def resolve_tool(
+    name: str,
+    *,
+    cwd: str | Path | None = None,
+    home: str | Path | None = None,
+) -> Tool:
+    """Resolve one effective scoped tool by its Python identifier."""
+
+    _validate_tool_name(name)
+    for tool in discover_tools(cwd=cwd, home=home):
+        if tool.name == name:
+            return tool
+    roots = _discovery_roots(cwd=cwd, home=home)
+    rendered = ", ".join(str(root) for root in roots)
+    raise ToolNotFoundError(f"no tool named {name!r} in scoped roots: {rendered}")
+
+
+def load_tool(
+    name: str,
+    *,
+    cwd: str | Path | None = None,
+    home: str | Path | None = None,
+    reload: bool = False,
+) -> ModuleType:
+    """Resolve and import one effective tool module."""
+
+    tool = resolve_tool(name, cwd=cwd, home=home)
+    return import_path(tool.path, import_name=tool.name, reload=reload)
+
+
+def _nearest_project_tools_root(cwd: Path, *, home: Path) -> Path | None:
+    current = cwd if cwd.is_dir() else cwd.parent
+    for directory in (current, *current.parents):
+        if directory == home:
+            break
+        candidate = directory / ".agents" / "tools"
+        if candidate.is_dir():
+            return candidate
+    return None
+
+
+def _discovery_roots(
+    *, cwd: str | Path | None = None, home: str | Path | None = None
+) -> tuple[Path, ...]:
+    working_directory = Path(cwd).expanduser().resolve() if cwd is not None else _INITIAL_CWD
+    home_directory = Path(home).expanduser().resolve() if home is not None else _INITIAL_HOME
+    project = _nearest_project_tools_root(working_directory, home=home_directory)
+    roots = (home_directory / ".agents" / "tools",)
+    return (project, *roots) if project is not None else roots
+
+
+def _scan_root(root: Path, *, scope: Scope) -> dict[str, Tool]:
+    if not root.is_dir():
+        return {}
+    tools: dict[str, Tool] = {}
+    for entry in sorted(root.iterdir(), key=lambda path: path.name):
+        if entry.name.startswith((".", "_")):
+            continue
+        if entry.is_file() and entry.suffix == ".py":
+            name = entry.stem
+            kind: ToolKind = "script"
+        elif entry.is_dir():
+            name = entry.name
+            kind = "package"
+        else:
+            continue
+        _validate_tool_name(name, path=entry)
+        if kind == "script":
+            metadata = inline_tool_metadata(entry)
+        else:
+            initializer = entry / "src" / name / "__init__.py"
+            if not initializer.is_file():
+                raise InvalidSourceError(
+                    f"packaged tool {entry} must define src/{name}/__init__.py"
+                )
+            metadata = project_tool_metadata(entry, tool_name=name)
+        if previous := tools.get(name):
+            raise InvalidSourceError(
+                f"tool root {root} defines {name!r} more than once: {previous.path} and {entry}"
+            )
+        tools[name] = Tool(
+            name=name,
+            path=entry,
+            scope=scope,
+            kind=kind,
+            description=metadata.description,
+        )
+    return tools
+
+
+def _validate_tool_name(name: str, *, path: Path | None = None) -> None:
+    if name.isidentifier() and not keyword.iskeyword(name):
+        return
+    context = f" at {path}" if path is not None else ""
+    raise InvalidSourceError(
+        f"tool name {name!r}{context} is not a valid non-keyword Python identifier"
+    )
+
+
+__all__ = ["Scope", "Tool", "ToolKind", "discover_tools", "load_tool", "resolve_tool"]

toolfuncs/_errors.py

@@ -0,0 +1,50 @@
+"""Public exception hierarchy for toolfuncs."""
+
+
+class ToolfuncsError(Exception):
+    """Base class for toolfuncs failures."""
+
+
+class InvalidSourceError(ToolfuncsError, ValueError):
+    """A source cannot be interpreted as a supported Python tool."""
+
+
+class DependencyMetadataError(InvalidSourceError):
+    """Inline or project dependency metadata is invalid or ambiguous."""
+
+
+class ToolMetadataError(InvalidSourceError):
+    """Static metadata for a discoverable tool is missing or invalid."""
+
+
+class ImportNameError(InvalidSourceError):
+    """A Python import name is invalid or cannot be inferred."""
+
+
+class ImportConflictError(ToolfuncsError, ImportError):
+    """A source or import name conflicts with an earlier path import."""
+
+
+class ToolNotFoundError(ToolfuncsError, ImportError):
+    """No effective scoped tool has the requested name."""
+
+
+class ToolDefinitionError(ToolfuncsError):
+    """A discovered module does not define a valid function-first tool."""
+
+
+class ShimConflictError(ToolfuncsError):
+    """A shim target exists but is not managed by toolfuncs."""
+
+
+__all__ = [
+    "DependencyMetadataError",
+    "ImportConflictError",
+    "ImportNameError",
+    "InvalidSourceError",
+    "ShimConflictError",
+    "ToolDefinitionError",
+    "ToolMetadataError",
+    "ToolNotFoundError",
+    "ToolfuncsError",
+]