toolchestrator 0.6.0__py3-none-any.whl

toolchestrator/__init__.py

@@ -0,0 +1,39 @@
+"""Toolchestrator client library.
+
+Connects a tool running on this machine to a Toolchestrator hub:
+
+* **Register** the tool once with a personal access token (``tcu_...``); the
+  tool receives its own API key (``tck_...``) which is written to a local
+  ``.toolchestrator.json`` config file (gitignore it!).
+* **Sync** the tool's data model schemas (versioned on the hub) and records.
+* **Read** other visible tools' data (filtered/projected/ordered via
+  ``read``), **declare connections** with a purpose (``connect_to``),
+  **enqueue** tasks on them (or **call** an action synchronously and get
+  the result back), and **subscribe** to their data changes.
+* **Serve** actions: a blocking long-poll loop that claims tasks queued for
+  this tool and runs local handler functions (``data_handlers`` route
+  ``data.changed`` notifications per source tool/model).
+* **Serve a web UI** (``serve_web``): tunnel a local web app's full HTTP
+  through the hub so visible users reach it in their browser — this machine
+  still makes only outbound connections.
+
+Quick start::
+
+    from toolchestrator import Toolchestrator
+
+    # one time, writes .toolchestrator.json in the current directory:
+    tc = Toolchestrator.register(
+        "http://localhost:8787", "tcu_...", "invoice-radar", "Invoice Radar",
+        description="Tracks vendor invoices", sharing_scope="private")
+
+    # every run afterwards:
+    tc = Toolchestrator()                 # loads .toolchestrator.json
+    tc.sync_schema("invoice", schema)     # JSON Schema dict
+    tc.sync_data("invoice", rows, id_field="id")
+    tc.serve({"mark_paid": mark_paid})    # blocking task loop
+"""
+
+from .client import Toolchestrator, ToolchestratorError
+
+__version__ = "0.6.0"
+__all__ = ["Toolchestrator", "ToolchestratorError", "__version__"]

toolchestrator/client.py

@@ -0,0 +1,1034 @@
+"""Core client for the Toolchestrator hub HTTP API.
+
+Everything a connected tool does is outbound HTTP: push (register, schemas,
+data, task results, heartbeat) and long-poll (tasks). The hub never connects
+back to the tool's machine, so this client works from laptops behind NAT.
+
+Compatible with Python 3.9+. The only third-party dependency is ``requests``.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import os
+import threading
+import time
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple
+
+import requests
+
+logger = logging.getLogger("toolchestrator")
+
+CONFIG_FILENAME = ".toolchestrator.json"
+ENV_URL = "TOOLCHESTRATOR_URL"
+ENV_API_KEY = "TOOLCHESTRATOR_API_KEY"
+
+# Handler signature: fn(payload, task) -> result dict (or None).
+Handler = Callable[[Dict[str, Any], Dict[str, Any]], Optional[Dict[str, Any]]]
+
+# data.changed routing table: (source_slug, model_name) -> handler.
+DataHandlers = Dict[Tuple[str, str], Handler]
+
+_UNSET = object()  # sentinel so update() can distinguish "not passed" from None
+
+# Hop-by-hop headers (RFC 7230 §6.1) plus request routing headers that must
+# never reach the local target: the forwarded ``host`` would point at the hub,
+# and ``content-length`` is recomputed by requests from the actual body.
+_HOP_BY_HOP = frozenset((
+    "connection", "keep-alive", "proxy-authenticate", "proxy-authorization",
+    "te", "trailers", "transfer-encoding", "upgrade",
+))
+_STRIP_REQUEST_HEADERS = _HOP_BY_HOP | frozenset(("host", "content-length"))
+# On the way back, requests has already decoded the body, so length/encoding
+# headers copied verbatim would misdescribe the bytes handed to the browser.
+_STRIP_RESPONSE_HEADERS = _HOP_BY_HOP | frozenset(
+    ("content-length", "content-encoding"))
+
+
+class ToolchestratorError(Exception):
+    """Raised for HTTP errors from the hub and client-side misconfiguration.
+
+    Attributes:
+        status_code: HTTP status code, or ``None`` for client-side/network
+            errors.
+        detail: the hub's ``{"detail": ...}`` error payload when available.
+        task_id: the task id (``task_...``) when a synchronous :meth:`call`
+            did not finish in time, so the caller can poll :meth:`get_task`;
+            ``None`` otherwise.
+    """
+
+    def __init__(self, message: str, status_code: Optional[int] = None,
+                 detail: Optional[Any] = None,
+                 task_id: Optional[str] = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail
+        self.task_id = task_id
+
+
+def _find_config(start_dir: str) -> Optional[str]:
+    """Walk up from ``start_dir`` looking for a ``.toolchestrator.json`` file.
+
+    Returns the absolute path of the first one found, or ``None``.
+    """
+    current = os.path.abspath(start_dir)
+    while True:
+        candidate = os.path.join(current, CONFIG_FILENAME)
+        if os.path.isfile(candidate):
+            return candidate
+        parent = os.path.dirname(current)
+        if parent == current:  # reached filesystem root
+            return None
+        current = parent
+
+
+class Toolchestrator:
+    """A connected tool's handle on the Toolchestrator hub.
+
+    Two ways to get one:
+
+    * :meth:`Toolchestrator.register` — one-time registration with a personal
+      access token (``tcu_...``). Creates the tool on the hub, receives the
+      tool's own API key (``tck_...``), and writes ``.toolchestrator.json``
+      in the current directory.
+    * ``Toolchestrator()`` — every run afterwards. Loads
+      ``.toolchestrator.json`` by walking up from the current working
+      directory; the environment variables ``TOOLCHESTRATOR_URL`` and
+      ``TOOLCHESTRATOR_API_KEY`` override the file's values, and explicit
+      constructor arguments override both.
+
+    All methods raise :class:`ToolchestratorError` on failure.
+    """
+
+    def __init__(self, base_url: Optional[str] = None,
+                 api_key: Optional[str] = None,
+                 tool_id: Optional[str] = None,
+                 slug: Optional[str] = None,
+                 config_path: Optional[str] = None):
+        """Load configuration and prepare an authenticated HTTP session.
+
+        Args:
+            base_url: hub URL, e.g. ``http://localhost:8787``. Optional if
+                present in the config file or ``TOOLCHESTRATOR_URL``.
+            api_key: this tool's API key (``tck_...``). Optional if present
+                in the config file or ``TOOLCHESTRATOR_API_KEY``.
+            tool_id: this tool's id (``t_...``). Normally read from the
+                config file.
+            slug: this tool's slug. Normally read from the config file.
+            config_path: explicit path to a ``.toolchestrator.json`` file;
+                when omitted the file is searched for by walking up from the
+                current working directory.
+        """
+        cfg: Dict[str, Any] = {}
+        found = config_path or _find_config(os.getcwd())
+        if found and os.path.isfile(found):
+            try:
+                with open(found, "r", encoding="utf-8") as fh:
+                    cfg = json.load(fh)
+            except (OSError, ValueError) as exc:
+                raise ToolchestratorError(
+                    "could not read config file %s: %s" % (found, exc))
+        self.config_path = found if cfg else None
+
+        self.base_url = (base_url or os.environ.get(ENV_URL)
+                         or cfg.get("base_url") or "").rstrip("/")
+        self.api_key = (api_key or os.environ.get(ENV_API_KEY)
+                        or cfg.get("api_key"))
+        self.tool_id = tool_id or cfg.get("tool_id")
+        self.slug = slug or cfg.get("slug")
+
+        if not self.base_url or not self.api_key:
+            raise ToolchestratorError(
+                "no Toolchestrator configuration found: expected a "
+                ".toolchestrator.json file in this directory or a parent "
+                "(created by Toolchestrator.register), or the environment "
+                "variables %s and %s" % (ENV_URL, ENV_API_KEY))
+
+        self._session = requests.Session()
+        self._session.headers["Authorization"] = "Bearer %s" % self.api_key
+
+    # ------------------------------------------------------------------ #
+    # Registration                                                       #
+    # ------------------------------------------------------------------ #
+
+    @classmethod
+    def register(cls, base_url: str, personal_token: str, slug: str,
+                 name: str, description: str = "",
+                 problem_statement: str = "", usage: str = "",
+                 sharing_scope: str = "private",
+                 department: Optional[str] = None,
+                 actions: Optional[List[str]] = None,
+                 reconnect: bool = False,
+                 config_dir: Optional[str] = None) -> "Toolchestrator":
+        """Register this tool on the hub (one time) and save local config.
+
+        Uses a *personal access token* (``tcu_...``, created by the user in
+        the dashboard under Settings) — never a password. On success the hub
+        returns the tool's own API key (``tck_...``), which is written
+        together with the hub URL, tool id, and slug into
+        ``.toolchestrator.json`` in the current directory (add that file to
+        .gitignore — it contains a secret).
+
+        Args:
+            base_url: hub URL, e.g. ``http://localhost:8787``.
+            personal_token: the user's personal access token (``tcu_...``).
+            slug: URL-friendly unique-per-company identifier, e.g.
+                ``invoice-radar``.
+            name: human-readable tool name.
+            description: what the tool does (shown in the hub catalog).
+            problem_statement: the problem this tool solves and for whom.
+            usage: how people/tools are meant to use it.
+            sharing_scope: ``"private"`` (default), ``"department"``, or
+                ``"company"``. Start private; widen deliberately.
+            department: department *name* (e.g. ``"Finance"``) or ``None``.
+            actions: list of action names this tool can execute via tasks
+                (``serve`` updates this automatically from handler keys).
+            reconnect: if the slug already exists and you own it, pass
+                ``True`` to rotate the API key and update metadata instead
+                of failing with 409.
+            config_dir: directory to write ``.toolchestrator.json`` into
+                (defaults to the current working directory).
+
+        Returns:
+            A ready-to-use :class:`Toolchestrator` instance authenticated
+            with the new tool API key.
+        """
+        url = base_url.rstrip("/") + "/api/tools/register"
+        body = {
+            "slug": slug,
+            "name": name,
+            "description": description,
+            "problem_statement": problem_statement,
+            "usage": usage,
+            "sharing_scope": sharing_scope,
+            "department": department,
+            "actions": list(actions) if actions else [],
+            "reconnect": bool(reconnect),
+        }
+        try:
+            resp = requests.post(
+                url, json=body, timeout=30,
+                headers={"Authorization": "Bearer %s" % personal_token})
+        except requests.RequestException as exc:
+            raise ToolchestratorError("could not reach hub at %s: %s"
+                                      % (base_url, exc))
+        if resp.status_code >= 400:
+            raise ToolchestratorError(
+                "registration failed (%s): %s"
+                % (resp.status_code, _extract_detail(resp)),
+                status_code=resp.status_code, detail=_extract_detail(resp))
+
+        data = resp.json()
+        tool = data["tool"]
+        api_key = data["api_key"]
+
+        target_dir = os.path.abspath(config_dir or os.getcwd())
+        config_path = os.path.join(target_dir, CONFIG_FILENAME)
+        config = {
+            "base_url": base_url.rstrip("/"),
+            "api_key": api_key,
+            "tool_id": tool["id"],
+            "slug": tool["slug"],
+        }
+        with open(config_path, "w", encoding="utf-8") as fh:
+            json.dump(config, fh, indent=2)
+            fh.write("\n")
+        try:
+            os.chmod(config_path, 0o600)  # contains a secret
+        except OSError:
+            pass
+
+        client = cls(base_url=base_url, api_key=api_key,
+                     tool_id=tool["id"], slug=tool["slug"])
+        client.config_path = config_path
+        return client
+
+    # ------------------------------------------------------------------ #
+    # Schemas & data                                                     #
+    # ------------------------------------------------------------------ #
+
+    def sync_schema(self, model_name: str,
+                    json_schema: Dict[str, Any]) -> Dict[str, Any]:
+        """Push (or confirm) the JSON Schema for one of this tool's models.
+
+        Schema versions on the hub are immutable: pushing a schema identical
+        to the latest version is a no-op (``changed: False``); a different
+        schema creates version n+1. Call this at tool startup or whenever
+        the local storage shape changes — before the first ``sync_data`` for
+        the model.
+
+        When a push creates a new version, the hub diffs it against the
+        previous one and returns a ``warnings`` list naming any field a
+        consumer of this model depends on that was removed or whose
+        definition changed — a soft-locked contract this push breaks (the
+        version is still created; the hub never blocks). Each warning is
+        logged (``logger.warning``) so an agent or CLI running unattended
+        sees it, and the full response — warnings included — is returned so
+        the caller can surface or act on them.
+
+        Args:
+            model_name: model identifier, e.g. ``"invoice"``.
+            json_schema: a JSON Schema dict describing one record's payload.
+
+        Returns:
+            ``{"model": ..., "version": int, "changed": bool,
+            "warnings": [str]}`` (``warnings`` empty when the push is
+            additive-only or the model has no dependents).
+        """
+        data = self._request(
+            "PUT", "/api/tools/%s/schemas/%s" % (self._self_ref(), model_name),
+            json_body={"json_schema": json_schema})
+        for warning in (data.get("warnings") or []):
+            logger.warning("schema %s: %s", model_name, warning)
+        return data
+
+    def schemas(self, tool: Optional[str] = None) -> Dict[str, Any]:
+        """List the versioned model schemas a tool publishes on the hub.
+
+        Inspect what models and fields already exist — this tool's own, or
+        (with ``tool`` set) another visible tool's — so the agent building or
+        editing a tool **reuses** an existing model instead of duplicating
+        it. Visibility is evaluated as this tool's owner.
+
+        Args:
+            tool: the tool's slug or id to inspect; ``None`` (default) means
+                this tool itself.
+
+        Returns:
+            ``{"models": [{"name": str, "versions": [{"version": int,
+            "json_schema": dict, "created_at": str}]}]}`` — newest version
+            first per model.
+        """
+        ref = tool if tool is not None else self._self_ref()
+        return self._request("GET", "/api/tools/%s/schemas" % ref)
+
+    def sync_data(self, model_name: str, records: Iterable[Dict[str, Any]],
+                  id_field: str = "id",
+                  deleted_ids: Optional[Iterable[str]] = None,
+                  schema_version: Optional[int] = None) -> Dict[str, Any]:
+        """Upsert records for one of this tool's models on the hub.
+
+        Each record is sent whole as the payload; its stable external id is
+        taken from ``record[id_field]``. Re-syncing the same external id
+        updates the stored record (upsert), so it is safe to sync the full
+        current state, or only rows changed since the last sync.
+
+        Requires a schema for the model (``sync_schema``) to have been
+        pushed first.
+
+        Args:
+            model_name: model identifier, e.g. ``"invoice"``.
+            records: iterable of dicts; each must contain ``id_field``.
+            id_field: key holding each record's stable unique id
+                (default ``"id"``).
+            deleted_ids: external ids to delete from the hub, if any.
+            schema_version: pin records to a specific schema version;
+                default ``None`` uses the latest version on the hub.
+
+        Returns:
+            ``{"upserted": int, "deleted": int, "schema_version": int}``.
+        """
+        wire_records = []
+        for record in records:
+            if id_field not in record:
+                raise ToolchestratorError(
+                    "record is missing id_field %r: %r" % (id_field, record))
+            wire_records.append({
+                "external_id": str(record[id_field]),
+                "payload": record,
+            })
+        body = {
+            "records": wire_records,
+            "schema_version": schema_version,
+            "deleted_ids": list(deleted_ids) if deleted_ids else [],
+        }
+        return self._request(
+            "POST",
+            "/api/tools/%s/data/%s/sync" % (self._self_ref(), model_name),
+            json_body=body)
+
+    def read(self, tool: str, model: str,
+             where: Optional[Dict[str, Any]] = None,
+             fields: Optional[List[str]] = None,
+             order_by: Optional[str] = None,
+             since: Optional[str] = None,
+             limit: int = 200) -> List[Dict[str, Any]]:
+        """Query another tool's records — filtered, projected, and ordered.
+
+        The hub does the work (SQLite ``json_extract`` over payloads), so
+        read only what you need instead of dumping whole models. Visibility
+        is evaluated as this tool's owner: private tools of other users are
+        not accessible, department/company scopes apply. Reading another
+        tool's data also registers/refreshes a **connection** on the hub
+        (observability, not access control) — declare its purpose with
+        :meth:`connect_to`.
+
+        Args:
+            tool: the other tool's slug or id.
+            model: model name, e.g. ``"invoice"``.
+            where: filter over top-level payload fields, AND-ed together.
+                A scalar value means equality; a dict value uses operators
+                ``$eq``, ``$ne``, ``$gt``, ``$gte``, ``$lt``, ``$lte``,
+                ``$in`` (list), ``$contains`` (case-insensitive substring,
+                strings only). Example:
+                ``{"status": "overdue", "amount": {"$gte": 1000}}``.
+            fields: top-level payload keys to keep; other keys are dropped
+                server-side (``_external_id`` / ``_updated_at`` always
+                remain).
+            order_by: ``"<field>"``, ``"<field>:asc"``, or
+                ``"<field>:desc"``; ``updated_at`` sorts on the hub column.
+                Default ``updated_at:desc``.
+            since: ISO-8601 timestamp; only records updated after it.
+            limit: maximum number of records to return (paginates
+                transparently over the server's 200-per-page cap).
+
+        Returns:
+            List of record payload dicts, each with the hub bookkeeping keys
+            ``_external_id`` and ``_updated_at`` merged in.
+        """
+        base_params: Dict[str, Any] = {}
+        if where is not None:
+            base_params["where"] = json.dumps(where)
+        if fields:  # an empty list means "no projection", same as None
+            base_params["fields"] = ",".join(fields)
+        if order_by is not None:
+            base_params["order_by"] = order_by
+        if since is not None:
+            base_params["since"] = since
+
+        out: List[Dict[str, Any]] = []
+        offset = 0
+        while len(out) < limit:
+            page_size = min(200, limit - len(out))
+            params = dict(base_params)
+            params["limit"] = page_size
+            params["offset"] = offset
+            data = self._request(
+                "GET", "/api/tools/%s/data/%s" % (tool, model), params=params)
+            batch = data.get("records", [])
+            for rec in batch:
+                merged = dict(rec.get("payload") or {})
+                merged["_external_id"] = rec.get("external_id")
+                merged["_updated_at"] = rec.get("updated_at")
+                out.append(merged)
+            if len(batch) < page_size:
+                break
+            offset += len(batch)
+        return out
+
+    def fetch_data(self, tool: str, model: str, since: Optional[str] = None,
+                   limit: int = 200) -> List[Dict[str, Any]]:
+        """Fetch another tool's records from the hub (visibility permitting).
+
+        Kept for compatibility; delegates to :meth:`read`, which also takes
+        ``where`` / ``fields`` / ``order_by`` for filtered reads.
+
+        Args:
+            tool: the other tool's slug or id.
+            model: model name, e.g. ``"invoice"``.
+            since: ISO-8601 timestamp; only records updated after it.
+            limit: maximum number of records to return (paginates
+                transparently over the server's 200-per-page cap).
+
+        Returns:
+            List of record payload dicts, each with the hub bookkeeping keys
+            ``_external_id`` and ``_updated_at`` merged in.
+        """
+        return self.read(tool, model, since=since, limit=limit)
+
+    # ------------------------------------------------------------------ #
+    # Connections                                                        #
+    # ------------------------------------------------------------------ #
+
+    def connect_to(self, tool: str, model: str,
+                   purpose: Optional[str] = None) -> Dict[str, Any]:
+        """Declare that this tool reads ``tool``'s ``model`` — and say why.
+
+        Connections are observability, not access control: reading another
+        tool's data already records one automatically (``declared: false``),
+        but declaring it with a purpose makes the company data map explain
+        *why* the data flows. Idempotent upsert: calling again updates the
+        purpose and marks the connection declared.
+
+        Args:
+            tool: the source tool's slug or id (must be visible, and must
+                have a schema for ``model``).
+            model: the source model name this tool reads.
+            purpose: one line on why this tool reads that data, e.g.
+                ``"Correlate overdue invoices with at-risk accounts"``
+                (max 500 chars).
+
+        Returns:
+            The connection dict (``{"id": "conn_...", "declared": True,
+            "reads_count": ..., ...}``).
+        """
+        body = {
+            "source_tool_id": tool,
+            "model_name": model,
+            "consumer_tool_id": self._self_ref(),
+            "purpose": purpose,
+        }
+        return self._request("POST", "/api/connections", json_body=body)
+
+    def connections(self) -> List[Dict[str, Any]]:
+        """List this tool's connections (as source or consumer).
+
+        Returns:
+            List of connection dicts: source/consumer tool refs, model name,
+            purpose, ``declared`` flag, read stats (``reads_count``,
+            ``records_read``, ``last_read_at``).
+        """
+        data = self._request("GET", "/api/connections",
+                             params={"tool": self._self_ref()})
+        return data["connections"]
+
+    def dependents(self) -> Dict[str, Any]:
+        """List the OTHER tools that read this tool's models — its dependents.
+
+        Field-level dependency awareness: for each model this tool publishes,
+        the hub reports which other tools consume it and exactly which fields
+        they depend on (accumulated from their reads; a whole-model reader
+        depends on every current field). A field a consumer reads is a
+        soft-locked contract — removing, renaming, or changing its type
+        breaks that consumer — so call this before editing this tool's data
+        model to see who would break.
+
+        Returns:
+            ``{"models": [{"model": str, "latest_version": int, "dependents":
+            [{"tool": {"slug": str, "name": str}, "purpose": str,
+            "declared": bool, "fields": [str], "all_fields": bool,
+            "reads_count": int, "last_read_at": str}]}]}`` — a dependent with
+            ``all_fields`` true depends on every current field of the model.
+        """
+        return self._request(
+            "GET", "/api/tools/%s/dependents" % self._self_ref())
+
+    # ------------------------------------------------------------------ #
+    # Discovery, tasks, metadata                                         #
+    # ------------------------------------------------------------------ #
+
+    def list_tools(self, q: Optional[str] = None) -> List[Dict[str, Any]]:
+        """List tools on the hub visible to this tool's owner.
+
+        Args:
+            q: optional search over tool name/description.
+
+        Returns:
+            List of tool dicts (id, slug, name, description, sharing_scope,
+            actions, online, models, ...).
+        """
+        params = {"q": q} if q else None
+        return self._request("GET", "/api/tools", params=params)["tools"]
+
+    def enqueue(self, tool: str, action: str,
+                payload: Optional[Dict[str, Any]] = None,
+                timeout_s: int = 300,
+                max_attempts: int = 3) -> Dict[str, Any]:
+        """Queue a task for another (or this) tool to execute.
+
+        Execution is eventual, not live RPC: the target tool picks the task
+        up next time it polls (``serve``). Poll the returned task's id with
+        :meth:`get_task` to observe the result.
+
+        Args:
+            tool: target tool's slug or id (must be visible).
+            action: action name the target handles, e.g. ``"mark_paid"``.
+            payload: JSON-serializable dict passed to the target's handler.
+            timeout_s: seconds a claimed run may take before it is requeued
+                or failed (default 300).
+            max_attempts: total attempts before the task fails permanently
+                (default 3).
+
+        Returns:
+            The created task dict (``{"id": "task_...", "status": "queued",
+            ...}``).
+        """
+        body = {
+            "action": action,
+            "payload": payload or {},
+            "timeout_s": timeout_s,
+            "max_attempts": max_attempts,
+        }
+        return self._request("POST", "/api/tools/%s/tasks" % tool,
+                             json_body=body)
+
+    def call(self, tool: str, action: str,
+             payload: Optional[Dict[str, Any]] = None,
+             timeout_s: int = 300, wait: int = 30) -> Dict[str, Any]:
+        """Call another (or this) tool's action synchronously and get its result.
+
+        Where :meth:`enqueue` is fire-and-forget, ``call`` queues the task and
+        then blocks on the hub while it long-polls internally up to ``wait``
+        seconds for the serving machine to finish, returning the result in one
+        step. The serving machine stays outbound-only — the hub is the meeting
+        point — so this works even for another user's shared tool behind NAT.
+
+        Args:
+            tool: target tool's slug or id (must be visible).
+            action: action name the target handles, e.g. ``"mark_paid"``.
+            payload: JSON-serializable dict passed to the target's handler.
+            timeout_s: seconds a claimed run may take before it is requeued
+                or failed (default 300).
+            wait: seconds to wait for a terminal result before giving up
+                (default 30; the hub clamps to 0–60, where 0 returns as soon
+                as the task is created).
+
+        Returns:
+            The action's result dict, when the task finished successfully.
+
+        Raises:
+            ToolchestratorError: if the handler failed (message is the
+                handler's error); or if the tool did not finish within
+                ``wait`` because it is still running or offline — then the
+                exception's ``task_id`` attribute carries the task id so the
+                caller can poll :meth:`get_task` for the eventual result.
+        """
+        body = {
+            "action": action,
+            "payload": payload or {},
+            "timeout_s": timeout_s,
+            "wait": wait,
+        }
+        data = self._request("POST", "/api/tools/%s/call" % tool,
+                             json_body=body, timeout=wait + 15)
+        task = data.get("task") or {}
+        if data.get("finished"):
+            if task.get("status") == "succeeded":
+                result = task.get("result")
+                return result if result is not None else {}
+            raise ToolchestratorError(task.get("error") or "task failed",
+                                      task_id=task.get("id"))
+        state = "still running" if data.get("tool_online") else "offline"
+        raise ToolchestratorError(
+            "call to %s did not finish within %ss (%s); poll task %s with "
+            "get_task for the result" % (tool, wait, state, task.get("id")),
+            task_id=task.get("id"))
+
+    def get_task(self, task_id: str) -> Dict[str, Any]:
+        """Fetch one task by id (``task_...``): status, result, error, etc."""
+        return self._request("GET", "/api/tasks/%s" % task_id)
+
+    def heartbeat(self) -> Dict[str, Any]:
+        """Tell the hub this tool is alive (marks it online for ~90s).
+
+        Polling for tasks also refreshes presence, so a tool running
+        ``serve`` does not need explicit heartbeats.
+        """
+        return self._request(
+            "POST", "/api/tools/%s/heartbeat" % self._self_ref())
+
+    def update(self, name: Any = _UNSET, description: Any = _UNSET,
+               problem_statement: Any = _UNSET, usage: Any = _UNSET,
+               sharing_scope: Any = _UNSET, department: Any = _UNSET,
+               actions: Any = _UNSET, slug: Any = _UNSET) -> Dict[str, Any]:
+        """Update this tool's metadata on the hub.
+
+        Only the arguments you pass are changed; ``None`` is a real value
+        (e.g. ``department=None`` clears the department).
+
+        Args:
+            name / description / problem_statement / usage: catalog text.
+            sharing_scope: ``"private"``, ``"department"``, or ``"company"``.
+            department: department name or ``None``.
+            actions: list of action names this tool executes.
+            slug: new slug (stays unique per company).
+
+        Returns:
+            The updated tool dict.
+        """
+        body: Dict[str, Any] = {}
+        for key, value in (("name", name), ("description", description),
+                           ("problem_statement", problem_statement),
+                           ("usage", usage), ("sharing_scope", sharing_scope),
+                           ("department", department), ("actions", actions),
+                           ("slug", slug)):
+            if value is not _UNSET:
+                body[key] = value
+        tool = self._request("PATCH", "/api/tools/%s" % self._self_ref(),
+                             json_body=body)
+        if isinstance(tool, dict) and tool.get("slug"):
+            self.slug = tool["slug"]
+        return tool
+
+    def subscribe(self, source_tool: str, model: str) -> Dict[str, Any]:
+        """Subscribe this tool to another tool's data changes.
+
+        After the source tool syncs changes to ``model``, the hub queues a
+        ``data.changed`` task for this tool with payload
+        ``{"source_tool": <slug>, "model_name", "upserted", "deleted"}`` —
+        handle it in ``serve`` with a ``"data.changed"`` handler key.
+
+        Args:
+            source_tool: the source tool's slug or id (must be visible).
+            model: the source model name to watch.
+
+        Returns:
+            The created subscription dict. Raises with status 409 if the
+            subscription already exists.
+        """
+        body = {
+            "source_tool_id": source_tool,
+            "model_name": model,
+            "subscriber_tool_id": self._self_ref(),
+        }
+        return self._request("POST", "/api/subscriptions", json_body=body)
+
+    # ------------------------------------------------------------------ #
+    # Serving tasks                                                      #
+    # ------------------------------------------------------------------ #
+
+    def serve(self, handlers: Dict[str, Handler],
+              data_handlers: Optional[DataHandlers] = None,
+              poll_wait: int = 20) -> None:
+        """Blocking loop: poll the hub for tasks and run local handlers.
+
+        On start, PATCHes this tool's ``actions`` to the handler keys so the
+        hub (and its dashboard) advertise exactly what this tool can do.
+        Then long-polls forever, claiming one task at a time and reporting
+        its result. Stop with Ctrl-C (KeyboardInterrupt propagates).
+
+        Handler contract — ``fn(payload: dict, task: dict) -> dict | None``:
+
+        * return a dict (or ``None``) → task ``succeeded`` with that result;
+        * raise any exception → task ``failed`` with the exception message
+          (the hub retries while attempts remain);
+        * a polled action with no handler → task ``failed`` with
+          ``"no handler for <action>"``.
+
+        ``data.changed`` tasks (subscription notifications) are routed
+        through ``data_handlers`` first, by
+        ``(payload["source_tool"], payload["model_name"])``; an unmatched
+        one falls back to ``handlers["data.changed"]`` if present, else
+        fails with the normal no-handler error.
+
+        Network errors are logged and retried after a short sleep; the loop
+        never exits on its own.
+
+        Args:
+            handlers: mapping of action name → handler function. Include a
+                ``"data.changed"`` key to receive subscription
+                notifications not matched by ``data_handlers``.
+            data_handlers: mapping of ``(source_slug, model_name)`` →
+                handler for that source's ``data.changed`` notifications.
+            poll_wait: long-poll wait in seconds per request (server caps
+                at 25).
+        """
+        actions = set(handlers.keys())
+        if data_handlers:
+            actions.add("data.changed")
+        self.update(actions=sorted(actions))
+        logger.info("serving actions %s for tool %s",
+                    sorted(actions), self.slug or self.tool_id)
+        while True:
+            try:
+                self.serve_once(handlers, data_handlers=data_handlers,
+                                wait=poll_wait)
+            except ToolchestratorError as exc:
+                logger.warning("poll failed (%s); retrying in 3s", exc)
+                time.sleep(3)
+
+    def serve_once(self, handlers: Dict[str, Handler],
+                   data_handlers: Optional[DataHandlers] = None,
+                   wait: int = 5) -> int:
+        """Single poll: claim up to one task, execute it, report the result.
+
+        Same handler contract and ``data.changed`` routing as :meth:`serve`.
+        Useful in tests and for tools that check for work on their own
+        schedule (e.g. from cron).
+
+        Args:
+            handlers: mapping of action name → handler function.
+            data_handlers: mapping of ``(source_slug, model_name)`` →
+                handler for that source's ``data.changed`` notifications.
+            wait: long-poll wait in seconds (0 returns immediately if no
+                task is queued).
+
+        Returns:
+            Number of tasks handled (0 or 1).
+        """
+        data = self._request(
+            "GET", "/api/tools/%s/tasks/poll" % self._self_ref(),
+            params={"wait": wait, "max": 1}, timeout=wait + 15)
+        tasks = data.get("tasks", [])
+        for task in tasks:
+            self._execute_task(handlers, task, data_handlers=data_handlers)
+        return len(tasks)
+
+    def _execute_task(self, handlers: Dict[str, Handler],
+                      task: Dict[str, Any],
+                      data_handlers: Optional[DataHandlers] = None) -> None:
+        """Run the handler for one claimed task and post its result."""
+        task_id = task["id"]
+        action = task.get("action")
+        payload = task.get("payload") or {}
+        handler: Optional[Handler] = None
+        if action == "data.changed" and data_handlers:
+            handler = data_handlers.get(
+                (payload.get("source_tool"), payload.get("model_name")))
+        if handler is None and action is not None:
+            handler = handlers.get(action)
+        if handler is None:
+            self._post_result(task_id, "failed",
+                              error="no handler for %s" % action)
+            return
+        try:
+            result = handler(payload, task)
+        except Exception as exc:  # noqa: BLE001 — any handler error fails the task
+            message = str(exc) or exc.__class__.__name__
+            logger.warning("handler for %s raised: %s", action, message)
+            self._post_result(task_id, "failed", error=message)
+        else:
+            self._post_result(task_id, "succeeded",
+                              result=result if result is not None else {})
+
+    def _post_result(self, task_id: str, status: str,
+                     result: Optional[Dict[str, Any]] = None,
+                     error: Optional[str] = None) -> Dict[str, Any]:
+        """Report a claimed task's outcome to the hub."""
+        if status == "succeeded":
+            body: Dict[str, Any] = {"status": "succeeded",
+                                    "result": result if result is not None else {}}
+        else:
+            body = {"status": "failed", "error": error or "unknown error"}
+        return self._request("POST", "/api/tasks/%s/result" % task_id,
+                             json_body=body)
+
+    # ------------------------------------------------------------------ #
+    # Serving a web UI (app tunnel)                                       #
+    # ------------------------------------------------------------------ #
+
+    def serve_web(self, target: str, workers: int = 8) -> None:
+        """Blocking loop: tunnel a local web app's HTTP through the hub.
+
+        Where :meth:`serve` tunnels named *actions*, ``serve_web`` tunnels full
+        *HTTP*, so a tool that runs a local web UI (e.g. a Flask app on
+        ``http://127.0.0.1:5000``) can be reached through the hub by any user
+        who can see the tool. This machine stays outbound-only: it opens a
+        single **outbound WebSocket** to the hub, receives forwarded browser
+        requests over it, replays each one against ``target``, and sends the
+        response back over the same socket — the hub is the only party
+        accepting inbound (browser) traffic.
+
+        Requests are handled concurrently in a small thread pool so a slow
+        response cannot stall the others; every send back over the shared
+        socket is serialized by a lock. Run this alongside :meth:`serve` in a
+        separate thread or process if the tool serves both actions and a UI.
+
+        **SSRF containment.** The outbound URL is built *strictly* from the
+        fixed local ``target`` plus the forwarded path and query — the hub
+        never sends, and this client never reads, any request-supplied host, so
+        a forwarded request can only ever reach ``target``. Paths containing
+        ``..`` are refused with a 400 without touching the target. The local
+        target also never sees the hub credentials: forwarding uses a plain
+        ``requests`` call, not this client's authenticated session.
+
+        The WebSocket is reconnected with exponential backoff on any drop, like
+        :meth:`serve`; the loop never exits on its own (stop with Ctrl-C).
+
+        Args:
+            target: base URL of the local web app, e.g.
+                ``"http://127.0.0.1:5000"`` (any path/query on it is ignored —
+                only the scheme/host/port are used).
+            workers: size of the thread pool forwarding requests concurrently.
+        """
+        try:
+            import websocket  # type: ignore
+        except ImportError as exc:  # pragma: no cover — dependency is declared
+            raise ToolchestratorError(
+                "serve_web needs the 'websocket-client' package; install it "
+                "with: pip install 'websocket-client>=1.5'") from exc
+
+        target = target.rstrip("/")
+        ws_url = self._tunnel_ws_url()
+        header = ["Authorization: Bearer %s" % self.api_key]
+        logger.info("tunnelling web UI at %s through tool %s (workers=%d)",
+                    target, self.slug or self.tool_id, workers)
+        executor = ThreadPoolExecutor(max_workers=workers)
+        backoff = 1.0
+        try:
+            while True:
+                try:
+                    ws = websocket.create_connection(ws_url, header=header)
+                except Exception as exc:  # noqa: BLE001 — any connect error retries
+                    logger.warning("tunnel connect failed (%s); retrying in "
+                                   "%.0fs", exc, backoff)
+                    time.sleep(backoff)
+                    backoff = min(backoff * 2, 30.0)
+                    continue
+                backoff = 1.0  # clean connect resets the backoff
+                send_lock = threading.Lock()
+                logger.info("tunnel websocket connected for tool %s",
+                            self.slug or self.tool_id)
+                try:
+                    while True:
+                        message = ws.recv()
+                        if message is None or message == "":
+                            break  # server closed the socket
+                        try:
+                            req = json.loads(message)
+                        except (ValueError, TypeError):
+                            continue  # ignore malformed frames
+                        executor.submit(self._forward_web_request,
+                                        target, ws, send_lock, req)
+                except Exception as exc:  # noqa: BLE001 — any drop reconnects
+                    logger.warning("tunnel websocket dropped (%s); "
+                                   "reconnecting in %.0fs", exc, backoff)
+                finally:
+                    try:
+                        ws.close()
+                    except Exception:  # noqa: BLE001 — best-effort close
+                        pass
+                time.sleep(backoff)
+                backoff = min(backoff * 2, 30.0)
+        finally:
+            executor.shutdown(wait=False)
+
+    def _tunnel_ws_url(self) -> str:
+        """Build the tunnel WebSocket URL from the hub base URL.
+
+        Derives the scheme from ``self.base_url`` (``http`` → ``ws``,
+        ``https`` → ``wss``) and appends this tool's tunnel path.
+        """
+        base = self.base_url
+        if base.startswith("https://"):
+            ws_base = "wss://" + base[len("https://"):]
+        elif base.startswith("http://"):
+            ws_base = "ws://" + base[len("http://"):]
+        else:  # already ws://, wss://, or scheme-less — use as-is
+            ws_base = base
+        return ws_base + "/api/tools/%s/tunnel/ws" % self._self_ref()
+
+    def _forward_web_request(self, target: str, ws: Any,
+                             send_lock: "threading.Lock",
+                             req: Dict[str, Any]) -> None:
+        """Replay one forwarded request against ``target`` and send the reply.
+
+        Runs in the thread pool. Any failure reaching the local target is
+        turned into a 502 so the waiting browser request resolves instead of
+        hanging until the hub's timeout. The response frame is sent back over
+        the shared ``ws`` under ``send_lock`` (many workers share one socket).
+        """
+        req_id = req.get("req_id")
+        if not req_id:
+            return
+        try:
+            status, headers, body = self._perform_web_forward(target, req)
+        except Exception as exc:  # noqa: BLE001 — any error becomes a 502 reply
+            logger.warning("forwarding request %s failed: %s", req_id, exc)
+            status = 502
+            headers = {"Content-Type": "text/plain; charset=utf-8"}
+            body = ("tunnel target error: %s" % exc).encode("utf-8")
+        self._send_tunnel_response(ws, send_lock, req_id, status, headers, body)
+
+    def _perform_web_forward(self, target: str, req: Dict[str, Any]
+                             ) -> Tuple[int, Dict[str, str], bytes]:
+        """Send one forwarded request to the local target; return its reply.
+
+        Returns ``(status, headers, body_bytes)``. The outbound URL is built
+        strictly as ``target + path + ("?" + query)`` — never from any
+        request-supplied host — and ``..`` paths are refused (400) up front.
+        """
+        path = req.get("path") or "/"
+        if ".." in path:
+            return (400, {"Content-Type": "text/plain; charset=utf-8"},
+                    b"refused: path contains '..'")
+        if not path.startswith("/"):
+            path = "/" + path
+        query = req.get("query") or ""
+        url = target + path + (("?" + query) if query else "")
+        method = (req.get("method") or "GET").upper()
+        headers = _filter_headers(req.get("headers") or {},
+                                  _STRIP_REQUEST_HEADERS)
+        body_b64 = req.get("body_b64")
+        body = base64.b64decode(body_b64) if body_b64 else None
+        # A plain requests call (not self._session) so the hub credentials are
+        # never sent to the local target; no redirect following so the browser
+        # sees 3xx responses itself.
+        resp = requests.request(method, url, headers=headers, data=body,
+                                timeout=30, allow_redirects=False)
+        resp_headers = _filter_headers(resp.headers, _STRIP_RESPONSE_HEADERS)
+        return (resp.status_code, resp_headers, resp.content)
+
+    def _send_tunnel_response(self, ws: Any, send_lock: "threading.Lock",
+                              req_id: str, status: int,
+                              headers: Dict[str, str], body: bytes) -> None:
+        """Send one tunnelled response frame back over the socket (best-effort).
+
+        Serialized by ``send_lock`` because worker threads share one socket.
+        """
+        frame = {
+            "req_id": req_id,
+            "status": int(status),
+            "headers": dict(headers),
+            "body_b64": base64.b64encode(body or b"").decode("ascii"),
+        }
+        message = json.dumps(frame)
+        try:
+            with send_lock:
+                ws.send(message)
+        except Exception as exc:  # noqa: BLE001 — a dead socket reconnects in the loop
+            logger.warning("sending tunnel response for %s failed: %s",
+                           req_id, exc)
+
+    # ------------------------------------------------------------------ #
+    # Internals                                                          #
+    # ------------------------------------------------------------------ #
+
+    def _self_ref(self) -> str:
+        """This tool's identifier for URL paths (id preferred, else slug)."""
+        ref = self.tool_id or self.slug
+        if not ref:
+            raise ToolchestratorError(
+                "this client has no tool identity (tool_id/slug): load it "
+                "from a .toolchestrator.json written by "
+                "Toolchestrator.register, or pass tool_id= explicitly")
+        return ref
+
+    def _request(self, method: str, path: str,
+                 json_body: Optional[Dict[str, Any]] = None,
+                 params: Optional[Dict[str, Any]] = None,
+                 timeout: int = 30) -> Any:
+        """Send one authenticated request; raise ToolchestratorError on failure."""
+        url = self.base_url + path
+        try:
+            resp = self._session.request(method, url, json=json_body,
+                                         params=params, timeout=timeout)
+        except requests.RequestException as exc:
+            raise ToolchestratorError("request to %s failed: %s" % (url, exc))
+        if resp.status_code >= 400:
+            detail = _extract_detail(resp)
+            raise ToolchestratorError(
+                "%s %s -> %s: %s" % (method, path, resp.status_code, detail),
+                status_code=resp.status_code, detail=detail)
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+
+
+def _filter_headers(headers: Any, drop: "frozenset") -> Dict[str, str]:
+    """Copy ``headers`` (dict or requests CaseInsensitiveDict), dropping any
+    whose lower-cased name is in ``drop``. Values are coerced to ``str``."""
+    out: Dict[str, str] = {}
+    try:
+        items = headers.items()
+    except AttributeError:
+        items = []
+    for name, value in items:
+        if str(name).lower() in drop:
+            continue
+        out[str(name)] = str(value)
+    return out
+
+
+def _extract_detail(resp: "requests.Response") -> Any:
+    """Best-effort extraction of the hub's ``{"detail": ...}`` error body."""
+    try:
+        body = resp.json()
+        if isinstance(body, dict) and "detail" in body:
+            return body["detail"]
+        return body
+    except ValueError:
+        return resp.text[:500]

toolchestrator-0.6.0.dist-info/METADATA

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: toolchestrator
+Version: 0.6.0
+Summary: Connect a local tool to a Toolchestrator hub: registry, versioned schema/data sync, task serving, cross-tool reads/calls, and web-UI tunnelling.
+Author-email: Stevica Kuharski <kstevica@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://toolchestrator.com
+Project-URL: Connect guide, https://hub.toolchestrator.com/skill
+Keywords: toolchestrator,orchestration,internal-tools,claude-code,ai-tools,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Requires-Dist: websocket-client>=1.5
+Dynamic: license-file
+
+# toolchestrator
+
+The Python client for [Toolchestrator](https://toolchestrator.com) — connect a small local
+tool to your company's hub without moving it off the machine it runs on.
+
+With this client a connected tool can:
+
+- register itself in the company **registry** (name, author, the problem it solves);
+- publish **versioned JSON-Schema** data models and **sync records** to the hub;
+- **serve remote task actions** over an outbound long-poll (the hub never connects into your
+  machine);
+- **read other tools' data** through the hub with filtered queries;
+- **invoke** another tool's action and get the result back (`tc.call`);
+- **expose its own local web UI** through the hub (`tc.serve_web`).
+
+Works on Python 3.9+; depends only on `requests` and `websocket-client`.
+
+## Install
+
+```bash
+pip install toolchestrator
+```
+
+## Quick start
+
+```python
+from toolchestrator import Toolchestrator
+
+# one-time registration, with a personal token from your hub's Settings page
+tc = Toolchestrator.register(
+    "https://hub.example.com",        # your company's hub URL
+    "tcu_...",                        # personal access token
+    "invoice-radar", "Invoice Radar",
+    description="Tracks vendor invoices and flags overdue ones.",
+    sharing_scope="private",          # start private; widen deliberately
+)
+
+# afterwards, anywhere in the tool (loads .toolchestrator.json):
+tc = Toolchestrator()
+tc.sync_schema("invoice", invoice_schema)
+tc.sync_data("invoice", rows, id_field="id")
+tc.serve({"mark_paid": handle_mark_paid})   # execute tasks queued on the hub
+```
+
+The easiest way to connect a tool is to let an AI coding agent do the wiring: point it at
+your hub's connect guide (`<your-hub-url>/skill`) and ask it to *"connect this tool to
+Toolchestrator"*. The hub URL always comes from you — the client never assumes one.
+
+## License
+
+MIT © Stevica Kuharski

toolchestrator-0.6.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+toolchestrator/__init__.py,sha256=EfvYag-kebRTGsS3uaSqBZmfLaF2k-EXXspExkG7JAI,1793
+toolchestrator/client.py,sha256=LPI6FDFFzHHwj9CeK1HexMAVkDxImWDBhxp4XqLAI0Q,47568
+toolchestrator-0.6.0.dist-info/licenses/LICENSE,sha256=ZH09wJV0YqfGR3_U7gXGsgaYOYT2eTYFbe7_Ev288gs,1073
+toolchestrator-0.6.0.dist-info/METADATA,sha256=HiAa7K2v7Yi5DGvgc9SeZHZzl0j2JOCxHd8NUGcYrOE,3078
+toolchestrator-0.6.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+toolchestrator-0.6.0.dist-info/top_level.txt,sha256=0XqBTq-CCPtZXfrFFGkdRtnixmm7v035Q88F6UE65-Y,15
+toolchestrator-0.6.0.dist-info/RECORD,,

toolchestrator-0.6.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

toolchestrator-0.6.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stevica Kuharski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

toolchestrator-0.6.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+toolchestrator