toolplane-python-client 0.1.0__py3-none-any.whl

toolplane/provider_cli.py

@@ -0,0 +1,268 @@
+"""toolplane-provider: serve, validate, test, and inspect tool files.
+
+The consumer of a tools file — a Python module using the bare ``@tool``
+decorator. ``serve`` binds the collected tools to a session and runs the
+provider loop (claim, execute, heartbeat, lease renewal); ``validate``
+checks the file without executing it; ``call`` runs one tool locally;
+``schema`` prints a tool's generated JSON schema.
+"""
+
+import argparse
+import ast
+import json
+import logging
+import sys
+from typing import List, Optional, Tuple
+
+from toolplane import Toolplane
+from toolplane.core.errors import ToolplaneError
+from toolplane.provider_registry import RegistryTool, clear, collect
+from toolplane.utils.schema import generate_schema_from_function
+
+logger = logging.getLogger("toolplane.provider_cli")
+
+
+def _load_module(path: str):
+    """Import a tools file as a module (executes it — the standard Python
+    import contract; use ``validate`` for an execution-free check)."""
+    import importlib.abc
+
+    spec = importlib.util.spec_from_file_location("_toolplane_tools", path)
+    if spec is None or spec.loader is None:
+        raise ValueError(f"cannot import {path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _registry_tools(path: str) -> List[RegistryTool]:
+    clear()
+    _load_module(path)
+    return collect()
+
+
+def _decorated_functions(source: str) -> List[Tuple[str, Optional[str]]]:
+    """Extract (function name, schema literal) pairs for functions
+    decorated with @tool, without executing the module."""
+    parsed = ast.parse(source)
+    pairs: List[Tuple[str, Optional[str]]] = []
+    for node in ast.walk(parsed):
+        if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        for decorator in node.decorator_list:
+            name = None
+            if isinstance(decorator, ast.Name) and decorator.id == "tool":
+                name = node.name
+            elif isinstance(decorator, ast.Call):
+                func = decorator.func
+                if isinstance(func, ast.Name) and func.id == "tool":
+                    name = node.name
+            if name:
+                pairs.append((node.name, _schema_kwarg_literal(decorator)))
+                break
+    return pairs
+
+
+def _schema_kwarg_literal(decorator: ast.AST) -> Optional[str]:
+    if not isinstance(decorator, ast.Call):
+        return None
+    for keyword in decorator.keywords:
+        if keyword.arg == "schema" and isinstance(keyword.value, ast.Constant):
+            value = keyword.value.value
+            return value if isinstance(value, str) else None
+    return None
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    """Execution-free check of a tools file: parseable, every @tool
+    function collectable, schemas well-formed (JSON object root — the
+    server's registration bar)."""
+    path = args.file
+    try:
+        with open(path, "r", encoding="utf-8") as handle:
+            source = handle.read()
+    except OSError as exc:
+        print(f"cannot read {path}: {exc}", file=sys.stderr)
+        return 2
+
+    try:
+        pairs = _decorated_functions(source)
+    except SyntaxError as exc:
+        print(f"{path} is not valid Python: {exc}", file=sys.stderr)
+        return 2
+
+    if not pairs:
+        print(f"{path}: no @tool functions found — nothing to serve", file=sys.stderr)
+        return 2
+
+    failures = 0
+    for name, schema_literal in pairs:
+        if schema_literal is None:
+            continue
+        try:
+            decoded = json.loads(schema_literal)
+        except json.JSONDecodeError as exc:
+            print(f"  {name}: schema is not valid JSON: {exc}")
+            failures += 1
+            continue
+        if not isinstance(decoded, dict):
+            print(f"  {name}: schema root must be a JSON object")
+            failures += 1
+
+    if failures:
+        print(f"{path}: {failures} invalid schema(s)", file=sys.stderr)
+        return 2
+
+    print(f"{path}: OK — {len(pairs)} tool(s): {', '.join(name for name, _ in pairs)}")
+    return 0
+
+
+def cmd_serve(args: argparse.Namespace) -> int:
+    tools = _registry_tools(args.file)
+    if not tools:
+        print(
+            f"{args.file}: no @tool functions found — nothing to serve", file=sys.stderr
+        )
+        return 2
+
+    client = Toolplane(
+        server_host=args.host,
+        server_port=args.port,
+        api_key=args.api_key or "",
+    )
+    client = Toolplane(
+        server_host=args.host,
+        server_port=args.port,
+        api_key=args.api_key or "",
+    )
+    runtime = client.provider_runtime()
+    runtime._poll_interval = args.poll_interval
+    try:
+        session = runtime.create_session(session_id=args.session or None)
+    except ToolplaneError as exc:
+        # The session already exists (a re-serve or another provider owns
+        # it): attach to it instead of failing.
+        if args.session and "already exists" in str(exc).lower():
+            session = runtime.attach_session(args.session)
+        else:
+            raise
+
+    for entry in tools:
+        schema = entry.schema or generate_schema_from_function(entry.func)
+        runtime.tool(
+            session_id=session.session_id,
+            name=entry.name,
+            description=entry.description,
+            stream=entry.stream,
+            tags=entry.tags,
+        )
+        session.register_tool(
+            name=entry.name,
+            func=entry.func,
+            schema=schema,
+            description=entry.description,
+            stream=entry.stream,
+            tags=entry.tags or [],
+        )
+
+    print(f"serving {len(tools)} tool(s) in session {session.session_id}")
+    try:
+        runtime.run_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        runtime.stop()
+    return 0
+
+
+def cmd_call(args: argparse.Namespace) -> int:
+    tools = _registry_tools(args.file)
+    entry = next((t for t in tools if t.name == args.tool), None)
+    if entry is None:
+        print(
+            f"tool {args.tool} not found in {args.file}; available: "
+            f"{', '.join(t.name for t in tools) or '(none)'}",
+            file=sys.stderr,
+        )
+        return 3
+    try:
+        input_data = json.loads(args.input) if args.input else {}
+    except json.JSONDecodeError as exc:
+        print(f"--input must be a JSON object: {exc}", file=sys.stderr)
+        return 2
+    result = entry.func(**input_data) if isinstance(input_data, dict) else entry.func()
+    print(json.dumps(result, default=str) if not isinstance(result, str) else result)
+    return 0
+
+
+def cmd_schema(args: argparse.Namespace) -> int:
+    tools = _registry_tools(args.file)
+    entry = next((t for t in tools if t.name == args.tool), None)
+    if entry is None:
+        print(f"tool {args.tool} not found in {args.file}", file=sys.stderr)
+        return 3
+    generated = entry.schema or generate_schema_from_function(entry.func)
+    # generate_schema_from_function wraps the schema with name/description;
+    # the operator wants the schema itself.
+    body = (
+        generated.get("schema", generated) if isinstance(generated, dict) else generated
+    )
+    print(json.dumps(body, indent=2))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="toolplane-provider",
+        description="Serve and manage Toolplane tool files (bare @tool modules).",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    serve = sub.add_parser("serve", help="bind a tools file to a session and serve it")
+    serve.add_argument(
+        "file", nargs="?", default="tools.py", help="tools file (default: ./tools.py)"
+    )
+    serve.add_argument(
+        "--session",
+        default=None,
+        help="session id (created when missing; generated when omitted)",
+    )
+    serve.add_argument("--host", default="localhost")
+    serve.add_argument("--port", type=int, default=9001)
+    serve.add_argument("--api-key", default="")
+    serve.add_argument("--poll-interval", type=float, default=1.0)
+    serve.set_defaults(func=cmd_serve)
+
+    validate = sub.add_parser(
+        "validate", help="check a tools file without executing it"
+    )
+    validate.add_argument("file", help="tools file")
+    validate.set_defaults(func=cmd_validate)
+
+    call = sub.add_parser("call", help="run one tool locally (no server)")
+    call.add_argument("file", help="tools file")
+    call.add_argument("tool", help="tool name")
+    call.add_argument(
+        "--input", default="{}", help="tool input as a JSON object string"
+    )
+    call.set_defaults(func=cmd_call)
+
+    schema = sub.add_parser("schema", help="print a tool's generated JSON schema")
+    schema.add_argument("file", help="tools file")
+    schema.add_argument("tool", help="tool name")
+    schema.set_defaults(func=cmd_schema)
+
+    return parser
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    logging.basicConfig(
+        level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s"
+    )
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

toolplane/provider_registry.py

@@ -0,0 +1,77 @@
+"""Module-level tool registry for file-based tool modules.
+
+A tools file decorated with the bare ``@tool`` imports nothing from
+Toolplane and binds no session at import time — metadata is collected
+here and the ``toolplane-provider`` CLI binds it to a session at serve.
+Importing such a module performs no I/O.
+
+    from toolplane.provider_registry import tool
+
+    @tool(name="add", description="Add two numbers")
+    def add(a: int, b: int) -> int:
+        return a + b
+"""
+
+import threading
+from dataclasses import dataclass
+from typing import Callable, List, Optional
+
+_lock = threading.Lock()
+_registry: List["RegistryTool"] = []
+
+
+@dataclass
+class RegistryTool:
+    """A collected tool definition, pre-binding."""
+
+    name: str
+    func: Callable
+    description: Optional[str] = None
+    stream: bool = False
+    tags: Optional[List[str]] = None
+    schema: Optional[dict] = None
+
+
+def tool(
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    stream: bool = False,
+    tags: Optional[List[str]] = None,
+    schema: Optional[dict] = None,
+):
+    """Collect a tool definition into the module registry. Import-time
+    only: no session, no server, no I/O. Works bare (@tool) or with
+    arguments (@tool(name=..., description=...))."""
+
+    def _register(func: Callable) -> Callable:
+        with _lock:
+            _registry.append(
+                RegistryTool(
+                    name=name or func.__name__,
+                    func=func,
+                    description=description,
+                    stream=stream,
+                    tags=list(tags) if tags else None,
+                    schema=schema,
+                )
+            )
+        return func
+
+    # Bare usage: @tool directly above a function.
+    if callable(name):
+        func, name = name, None
+        return _register(func)
+
+    return _register
+
+
+def collect() -> List[RegistryTool]:
+    """Snapshot the collected tools."""
+    with _lock:
+        return list(_registry)
+
+
+def clear() -> None:
+    """Reset the registry (test isolation)."""
+    with _lock:
+        _registry.clear()

toolplane/provider_runtime.py

@@ -0,0 +1,302 @@
+"""Explicit provider runtime for machine-backed execution."""
+
+import logging
+import threading
+import time
+from dataclasses import dataclass
+from typing import Any, Callable, Iterable, List, Optional, Set
+
+logger = logging.getLogger(__name__)
+
+try:
+    from .core.errors import ConnectionError, ToolplaneError
+except ImportError:
+    from core.errors import ConnectionError, ToolplaneError
+
+
+@dataclass
+class _PendingTool:
+    """A tool registration deferred until the runtime starts."""
+
+    session_id: str
+    name: str
+    func: Callable
+    description: Optional[str] = None
+    stream: bool = False
+    tags: List[str] = None
+
+
+class ProviderRuntime:
+    """Owns the provider lifecycle for an Toolplane client instance."""
+
+    def __init__(
+        self,
+        client: Any,
+        session_ids: Optional[Iterable[str]] = None,
+        poll_interval: Optional[float] = None,
+        heartbeat_interval: Optional[int] = None,
+    ):
+        self.client = client
+        self._registration_lock = threading.Lock()
+        self._pending_registrations: List[_PendingTool] = []
+        self._session_ids: Set[str] = set(session_ids or [])
+        self._poll_interval = (
+            poll_interval
+            if poll_interval is not None
+            else getattr(client.config, "poll_interval", 1.0)
+        )
+        self._heartbeat_interval = (
+            heartbeat_interval
+            if heartbeat_interval is not None
+            else getattr(client.config, "heartbeat_interval", 60)
+        )
+        self._running = False
+        self._main_thread: Optional[threading.Thread] = None
+        self._lock = threading.RLock()
+
+    @property
+    def running(self) -> bool:
+        return self._running
+
+    def add_sessions(self, session_ids: Optional[Iterable[str]]) -> None:
+        if not session_ids:
+            return
+        for session_id in session_ids:
+            if session_id:
+                self._session_ids.add(session_id)
+
+    def managed_session_ids(self) -> List[str]:
+        session_ids: List[str] = []
+        seen: Set[str] = set()
+        for session_id in list(self._session_ids) + list(
+            getattr(self.client, "session_ids", [])
+        ):
+            if not session_id or session_id in seen:
+                continue
+            session_ids.append(session_id)
+            seen.add(session_id)
+        return session_ids
+
+    def attach_session(self, session_id: str, register_machine: bool = True):
+        if not session_id:
+            raise ToolplaneError(
+                "ProviderRuntime.attach_session requires a non-empty session_id"
+            )
+
+        if not self.client.connection_manager.connected:
+            if not self.client.connect():
+                raise ConnectionError("Failed to connect to server")
+
+        self._session_ids.add(session_id)
+        return self.client.ensure_session_context(
+            session_id,
+            create_if_missing=False,
+            register_machine=register_machine,
+        )
+
+    def create_session(
+        self,
+        session_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        namespace: Optional[str] = None,
+        register_machine: bool = True,
+    ):
+        context = self.client.create_session(
+            session_id=session_id,
+            user_id=user_id,
+            name=name,
+            description=description,
+            namespace=namespace,
+            register_machine=False,
+        )
+        self._session_ids.add(context.session_id)
+        if register_machine and not getattr(context, "machine_id", None):
+            context = self.attach_session(context.session_id, register_machine=True)
+        return context
+
+    def register_tool(
+        self,
+        session_id: str,
+        name: str,
+        func: Callable,
+        schema: Optional[dict] = None,
+        description: Optional[str] = None,
+        stream: bool = False,
+        tags: Optional[List[str]] = None,
+    ) -> Callable:
+        context = self.attach_session(session_id, register_machine=True)
+        context.register_tool(
+            name=name,
+            func=func,
+            schema=schema,
+            description=description,
+            stream=stream,
+            tags=tags,
+        )
+        return func
+
+    def tool(
+        self,
+        session_id: Optional[str] = None,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        stream: bool = False,
+        tags: Optional[List[str]] = None,
+    ):
+        """Queue a tool for registration at runtime start.
+
+        Decorating defers the (network) registration until
+        start_in_background/run_forever/poll_once, so importing a module of
+        decorated tools performs no I/O. session_id may be omitted when the
+        runtime manages exactly one session: the tool binds to it at
+        start (file-based tool modules use this to stay session-free).
+        """
+
+        def decorator(func: Callable) -> Callable:
+            with self._registration_lock:
+                self._pending_registrations.append(
+                    _PendingTool(
+                        session_id=session_id,
+                        name=name or func.__name__,
+                        func=func,
+                        description=description,
+                        stream=stream,
+                        tags=tags or [],
+                    )
+                )
+            return func
+
+        return decorator
+
+    def _resolve_default_session(self) -> str:
+        """Resolve the session an unbound (session_id=None) deferred tool
+        registers into: the runtime's single managed session. Ambiguous or
+        empty setups fail loudly instead of guessing."""
+        managed = self.managed_session_ids()
+        if len(managed) == 1:
+            return managed[0]
+        raise ToolplaneError(
+            "tool has no session_id and the runtime does not manage exactly "
+            f"one session (managed: {managed or 'none'}); bind it explicitly "
+            "or manage a single session"
+        )
+
+    def _apply_pending_registrations(self) -> None:
+        """Attach sessions and register every deferred tool.
+
+        A failed registration puts the item back at the head of the queue so
+        a later start attempt retries it; tools are never silently lost.
+        """
+        while True:
+            with self._registration_lock:
+                if not self._pending_registrations:
+                    return
+                item = self._pending_registrations.pop(0)
+
+            try:
+                self.register_tool(
+                    session_id=item.session_id or self._resolve_default_session(),
+                    name=item.name,
+                    func=item.func,
+                    description=item.description,
+                    stream=item.stream,
+                    tags=item.tags,
+                )
+            except Exception:
+                with self._registration_lock:
+                    self._pending_registrations.insert(0, item)
+                raise
+
+    def poll_once(self) -> None:
+        self._apply_pending_registrations()
+        for session_id in self.managed_session_ids():
+            context = self.client.ensure_session_context(
+                session_id,
+                create_if_missing=False,
+                register_machine=False,
+            )
+            if getattr(context, "machine_id", None):
+                context.poll_requests()
+
+    def start_in_background(
+        self, session_ids: Optional[Iterable[str]] = None
+    ) -> "ProviderRuntime":
+        # Queued @tool registrations may introduce the very sessions this
+        # call is about to check for; apply them before validating.
+        self._apply_pending_registrations()
+        with self._lock:
+            self.add_sessions(session_ids)
+            if self._running:
+                return self
+
+            if not self.client.connection_manager.connected:
+                if not self.client.connect():
+                    raise ConnectionError("Failed to connect to server")
+            else:
+                self.client._initialize_sessions(register_machine=False)
+
+            managed_session_ids = self.managed_session_ids()
+            if not managed_session_ids:
+                raise ToolplaneError(
+                    "ProviderRuntime requires at least one attached or configured session"
+                )
+
+            self._apply_pending_registrations()
+
+            for session_id in managed_session_ids:
+                self.attach_session(session_id, register_machine=True)
+
+            self.client.machine_manager.start_heartbeat(self._heartbeat_interval)
+            # Keep claimed executions alive: the renewal loop extends each
+            # in-flight lease so long-running tools are not reclaimed mid-run.
+            self.client.request_manager.start_lease_renewal()
+            self._running = True
+            if hasattr(self.client, "running"):
+                self.client.running = True
+            self._main_thread = threading.Thread(
+                target=self._main_loop,
+                name="toolplane-provider-runtime",
+                daemon=True,
+            )
+            self._main_thread.start()
+            return self
+
+    def run_forever(self, session_ids: Optional[Iterable[str]] = None) -> None:
+        self.start_in_background(session_ids=session_ids)
+        try:
+            while self._running:
+                time.sleep(1)
+        except KeyboardInterrupt:
+            self.stop()
+
+    def stop(self) -> None:
+        with self._lock:
+            self._running = False
+            if hasattr(self.client, "running"):
+                self.client.running = False
+
+        if self._main_thread:
+            self._main_thread.join(timeout=1)
+            self._main_thread = None
+
+        self.client.request_manager.stop_lease_renewal()
+        self.client.machine_manager.stop_heartbeat()
+
+    def close(self) -> None:
+        self.stop()
+
+    def _main_loop(self) -> None:
+        while self._running:
+            try:
+                self.poll_once()
+            except Exception as exc:
+                logger.warning("Error in provider runtime loop: %s", exc)
+            time.sleep(self._poll_interval)
+
+    def __enter__(self) -> "ProviderRuntime":
+        return self.start_in_background()
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        self.stop()