interloper-toolkit 0.89.0__tar.gz → 0.91.0__tar.gz

interloper_toolkit-0.91.0/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.3
+Name: interloper-toolkit
+Version: 0.91.0
+Summary: Interloper tool functions shared by the AI surfaces (agent, MCP)
+Author: Guillaume Onfroy
+Author-email: Guillaume Onfroy <guillaume@digitlcloud.com>
+Requires-Dist: interloper-core
+Requires-Dist: interloper-db
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# interloper-toolkit
+
+The tool functions shared by interloper's AI surfaces: the chat agent
+(`interloper-agent`) and the MCP server (`interloper-mcp`).
+
+Every function takes a frozen `ToolkitContext(store, catalog, org_id, role)`
+as its first argument and returns `<SuccessModel> | ToolError`: typed
+pydantic results (see `models.py`) discriminated by the literal `status`
+field, never raising. The models are the tool contract: MCP derives per-tool
+output schemas from them, row-projecting models act as an allowlist of what
+leaves the platform, and full-row payloads embed the interloper-db models to
+keep that coupling visible rather than duplicated. The docstrings are
+LLM-facing: both surfaces adopt them verbatim as tool descriptions.
+
+Reads take no role; writes declare the role they need with `requires_role`
+and refuse below it, as a structured `ToolError`.
+
+`tools.TOOLS` is the table both surfaces register: every tool with its
+`Effect` (read, read through a provider, edit, create, launch, cancel). A
+surface derives its behaviour from the effect (MCP annotations, the agent's
+approvals) and `Tool.bind` adapts a function to the way the surface supplies
+the context. A tool that `carries_secrets` in its arguments is left off any
+surface that transports arguments through a third party.
+
+Modules:
+
+- `catalog`: the component definitions the platform ships (list, detail,
+  asset schemas, field search, schema comparison)
+- `collection`: the org's component instances (listing, edits, relations,
+  connection checks and setup; sensitive kinds project identity only)
+- `sources` and `jobs`: creating sources, resolving their fields, creating jobs
+- `lineage`: dependency analysis, impact assessment, DAG traversal
+- `scheduling`: jobs, runs and backfills, monitoring and control
+- `analytics`: run statistics, partition coverage, data freshness
+- `tools`: the table above
+
+Depends only on `interloper-core` and `interloper-db`; no LLM-framework
+dependencies (no pydantic-ai, no mcp).

interloper_toolkit-0.91.0/README.md

@@ -0,0 +1,38 @@
+# interloper-toolkit
+
+The tool functions shared by interloper's AI surfaces: the chat agent
+(`interloper-agent`) and the MCP server (`interloper-mcp`).
+
+Every function takes a frozen `ToolkitContext(store, catalog, org_id, role)`
+as its first argument and returns `<SuccessModel> | ToolError`: typed
+pydantic results (see `models.py`) discriminated by the literal `status`
+field, never raising. The models are the tool contract: MCP derives per-tool
+output schemas from them, row-projecting models act as an allowlist of what
+leaves the platform, and full-row payloads embed the interloper-db models to
+keep that coupling visible rather than duplicated. The docstrings are
+LLM-facing: both surfaces adopt them verbatim as tool descriptions.
+
+Reads take no role; writes declare the role they need with `requires_role`
+and refuse below it, as a structured `ToolError`.
+
+`tools.TOOLS` is the table both surfaces register: every tool with its
+`Effect` (read, read through a provider, edit, create, launch, cancel). A
+surface derives its behaviour from the effect (MCP annotations, the agent's
+approvals) and `Tool.bind` adapts a function to the way the surface supplies
+the context. A tool that `carries_secrets` in its arguments is left off any
+surface that transports arguments through a third party.
+
+Modules:
+
+- `catalog`: the component definitions the platform ships (list, detail,
+  asset schemas, field search, schema comparison)
+- `collection`: the org's component instances (listing, edits, relations,
+  connection checks and setup; sensitive kinds project identity only)
+- `sources` and `jobs`: creating sources, resolving their fields, creating jobs
+- `lineage`: dependency analysis, impact assessment, DAG traversal
+- `scheduling`: jobs, runs and backfills, monitoring and control
+- `analytics`: run statistics, partition coverage, data freshness
+- `tools`: the table above
+
+Depends only on `interloper-core` and `interloper-db`; no LLM-framework
+dependencies (no pydantic-ai, no mcp).

{interloper_toolkit-0.89.0 → interloper_toolkit-0.91.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "interloper-toolkit"
-version = "0.89.0"
-description = "Interloper shared read-only tool functions for AI surfaces (agent, MCP)"
+version = "0.91.0"
+description = "Interloper tool functions shared by the AI surfaces (agent, MCP)"
 readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [

{interloper_toolkit-0.89.0 → interloper_toolkit-0.91.0}/pyproject.toml.orig

@@ -3,8 +3,8 @@
 # ###############
 [project]
 name = "interloper-toolkit"
-version = "0.89.0"
-description = "Interloper shared read-only tool functions for AI surfaces (agent, MCP)"
+version = "0.91.0"
+description = "Interloper tool functions shared by the AI surfaces (agent, MCP)"
 readme = "README.md"
 authors = [{ name = "Guillaume Onfroy", email = "guillaume@digitlcloud.com" }]
 requires-python = ">=3.10"

interloper_toolkit-0.91.0/src/interloper_toolkit/__init__.py

@@ -0,0 +1,34 @@
+"""Tool functions shared by the AI surfaces (agent, MCP server).
+
+Every function takes a :class:`~interloper_toolkit.context.ToolkitContext`
+as its first argument and returns ``<SuccessModel> | ToolError``: typed
+pydantic results (see :mod:`interloper_toolkit.models`) discriminated by
+the literal ``status`` field, never raising. The docstrings are LLM-facing:
+the surfaces adopt them verbatim as tool descriptions.
+
+Reads take no role; writes declare the role they need with
+:func:`~interloper_toolkit.authz.requires_role` and refuse below it.
+:data:`~interloper_toolkit.tools.TOOLS` is the table the surfaces register,
+each tool with its :class:`~interloper_toolkit.tools.Effect`; a surface
+derives its behaviour from that and leaves out what it cannot carry (the
+MCP server never registers a tool whose arguments carry credentials).
+"""
+
+from interloper_toolkit.authz import requires_role
+from interloper_toolkit.collection import bind_relation, unbind_relation
+from interloper_toolkit.context import ToolkitContext, serialize
+from interloper_toolkit.models import ToolError, UserRequest
+from interloper_toolkit.tools import TOOLS, Effect, Tool
+
+__all__ = [
+    "TOOLS",
+    "Effect",
+    "Tool",
+    "ToolError",
+    "ToolkitContext",
+    "UserRequest",
+    "bind_relation",
+    "requires_role",
+    "serialize",
+    "unbind_relation",
+]

{interloper_toolkit-0.89.0 → interloper_toolkit-0.91.0}/src/interloper_toolkit/collection.py

@@ -17,7 +17,7 @@ from typing import Any
 from urllib.parse import urlencode
 from uuid import UUID
 
-import httpx
+import httpx2
 from interloper.component import KINDS
 from interloper.connection.base import Connection
 from interloper.errors import (
@@ -466,12 +466,12 @@ def categorise(exc: Exception) -> tuple[str, str]:
     """
     if isinstance(exc, ConnectionCheckError):
         return "error", str(exc)
-    if isinstance(exc, httpx.HTTPStatusError):
+    if isinstance(exc, httpx2.HTTPStatusError):
         if exc.response.status_code in (401, 403):
             return "auth", "The provider rejected the credentials."
         return "error", f"The provider responded with HTTP {exc.response.status_code}."
-    if isinstance(exc, (TimeoutError, httpx.TimeoutException)):
+    if isinstance(exc, (TimeoutError, httpx2.TimeoutException)):
         return "network", "The provider did not respond in time."
-    if isinstance(exc, httpx.TransportError):
+    if isinstance(exc, httpx2.TransportError):
         return "network", "The provider could not be reached."
     return "error", "The connection check failed unexpectedly."

{interloper_toolkit-0.89.0 → interloper_toolkit-0.91.0}/src/interloper_toolkit/errors.py

@@ -3,7 +3,7 @@
 Every error the platform records went through
 :func:`interloper.errors.format_exception`, so it opens with the exception's
 type name; what follows is the library's own message. Three families carry
-an HTTP request in a recognisable shape: httpx (``Client error '429 …' for
+an HTTP request in a recognisable shape: httpx2 (``Client error '429 …' for
 url '…'``), google-api-core (``403 POST https://…: message``) and the
 Facebook SDK (``Method:`` / ``Path:`` / ``Status:`` lines over a JSON body
 with ``code`` and ``error_subcode``). Everything else is grouped by its
@@ -49,8 +49,8 @@ def classify(text: str) -> ErrorCause:
 
     status: int | None = None
     method: str | None = None
-    if httpx := _HTTPX_STATUS.search(message):
-        status = int(httpx.group(1))
+    if httpx2 := _HTTPX_STATUS.search(message):
+        status = int(httpx2.group(1))
     elif google := _GOOGLE_STATUS.match(message.strip()):
         status = int(google.group(1))
         method = google.group(2)

{interloper_toolkit-0.89.0 → interloper_toolkit-0.91.0}/src/interloper_toolkit/models.py

@@ -228,7 +228,24 @@ class ConnectionsCreated(BaseModel):
     failed: list[FailedInstance]
 
 
-class ConnectionSetup(BaseModel):
+class UserRequest(BaseModel):
+    """A result that asks the user for something the model cannot supply.
+
+    An interactive surface takes it to the user and answers the call with
+    their input; elsewhere it is an ordinary result the model relays.
+    """
+
+    @property
+    def awaits_user(self) -> bool:
+        """Whether the user is being asked.
+
+        Returns:
+            True unless the request resolved in place after all.
+        """
+        return True
+
+
+class ConnectionSetup(UserRequest):
     """The hand-off ``request_connection_setup`` makes.
 
     ``setup_url`` opens the app's connection form for this definition, when
@@ -246,6 +263,15 @@ class ConnectionSetup(BaseModel):
     setup_url: str | None = None
     existing: list[ComponentRef] = []
 
+    @property
+    def awaits_user(self) -> bool:
+        """Whether the form is presented.
+
+        Returns:
+            False when the existing connections were listed instead.
+        """
+        return not self.existing
+
 
 class ConnectionCheck(BaseModel):
     """The outcome of a connection's health check.

{interloper_toolkit-0.89.0 → interloper_toolkit-0.91.0}/src/interloper_toolkit/scheduling.py

@@ -229,7 +229,10 @@ def retry_run(ctx: ToolkitContext, run_id: str, scope: str = "all") -> RunRetrie
             the operations that failed or were canceled.
 
     Returns the queued attempt; its ``attempt`` number and ``root_run_id``
-    tie it to the run it retries. A run that is not failed cannot be retried.
+    tie it to the run it retries. The retry continues from the stack's latest
+    attempt, so retrying an earlier attempt retries the stack. A run that is
+    not failed, or a stack whose latest attempt is pending or succeeded,
+    cannot be retried.
     """
     try:
         ctx.store.runs.get(UUID(run_id), org_id=ctx.org_id)

interloper_toolkit-0.91.0/src/interloper_toolkit/tools.py

@@ -0,0 +1,158 @@
+"""The tool table: every tool the AI surfaces expose, with its effect on the platform.
+
+A surface (the agent, the MCP server) registers this table rather than a
+list of its own. The effect is the one fact a surface derives its behaviour
+from: MCP maps it to the annotations a client keys on, the agent to which
+calls wait for the user's approval. ``carries_secrets`` marks a tool whose
+arguments would carry credentials; a surface that transports arguments
+through a third party leaves it out.
+"""
+
+from __future__ import annotations
+
+import inspect
+import types
+import typing
+from collections.abc import Callable
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from interloper_toolkit import analytics, catalog, collection, jobs, lineage, scheduling, sources
+from interloper_toolkit.context import ToolkitContext
+
+
+class Effect(str, Enum):
+    """What a tool does to the platform."""
+
+    READ = "read"
+    READ_PROVIDER = "read_provider"
+    EDIT = "edit"
+    CREATE = "create"
+    LAUNCH = "launch"
+    CANCEL = "cancel"
+
+
+@dataclass(frozen=True)
+class Tool:
+    """A toolkit function as the surfaces expose it.
+
+    Args:
+        fn: The toolkit function, sync or async, taking the context first.
+        effect: What it does to the platform.
+        carries_secrets: Whether its arguments carry credentials.
+    """
+
+    fn: types.FunctionType
+    effect: Effect
+    carries_secrets: bool = False
+
+    @property
+    def name(self) -> str:
+        """The tool's name, which is the function's.
+
+        Returns:
+            The function name.
+        """
+        return self.fn.__name__
+
+    @property
+    def needs_approval(self) -> bool:
+        """Whether an interactive surface waits for the user before the call runs.
+
+        Returns:
+            True for creates and cancels, the calls a user wants to confirm.
+        """
+        return self.effect in (Effect.CREATE, Effect.CANCEL)
+
+    def bind(self, context: Callable[..., ToolkitContext], *leading: inspect.Parameter) -> types.FunctionType:
+        """Adapt the function to a surface that supplies the context itself.
+
+        The bound function keeps the name, docstring and every parameter but
+        the context, so the schema a model sees is exactly the toolkit's.
+        ``leading`` are the surface's own parameters in the context's place,
+        if any; ``context`` receives their values and returns the context to
+        call with.
+
+        Args:
+            context: Derives the toolkit context from the leading arguments.
+            *leading: Parameters the bound function takes before the toolkit's own.
+
+        Returns:
+            The bound function, with an explicit signature and annotations.
+        """
+        signature = inspect.signature(self.fn)
+        hints = typing.get_type_hints(self.fn)
+        _, *rest = signature.parameters
+        parameters = [*leading, *(signature.parameters[name].replace(annotation=hints[name]) for name in rest)]
+        returns = hints.get("return", Any)
+        split = len(leading)
+
+        if inspect.iscoroutinefunction(self.fn):
+
+            async def tool(*args: Any, **kwargs: Any) -> Any:
+                return await self.fn(context(*args[:split]), *args[split:], **kwargs)
+        else:
+
+            def tool(*args: Any, **kwargs: Any) -> Any:
+                return self.fn(context(*args[:split]), *args[split:], **kwargs)
+
+        tool.__name__ = tool.__qualname__ = self.name
+        tool.__module__ = self.fn.__module__
+        tool.__doc__ = self.fn.__doc__
+        tool.__signature__ = signature.replace(parameters=parameters, return_annotation=returns)  # ty: ignore[invalid-assignment]
+        tool.__annotations__ = {p.name: p.annotation for p in parameters} | {"return": returns}
+        return tool
+
+
+TOOLS: tuple[Tool, ...] = (
+    # Catalog
+    Tool(catalog.list_definitions, Effect.READ),
+    Tool(catalog.get_definition, Effect.READ),
+    Tool(catalog.get_asset_schema, Effect.READ),
+    Tool(catalog.search_fields, Effect.READ),
+    Tool(catalog.compare_schemas, Effect.READ),
+    # Collection
+    Tool(collection.list_components, Effect.READ),
+    Tool(collection.update_component, Effect.EDIT),
+    Tool(collection.bind_relation, Effect.EDIT),
+    Tool(collection.unbind_relation, Effect.EDIT),
+    Tool(collection.request_connection_setup, Effect.READ),
+    Tool(collection.check_connection, Effect.READ_PROVIDER),
+    Tool(collection.create_connections, Effect.CREATE, carries_secrets=True),
+    # Sources and jobs
+    Tool(sources.resolve_source_field_options, Effect.READ_PROVIDER),
+    Tool(sources.create_source, Effect.CREATE),
+    Tool(sources.create_sources, Effect.CREATE),
+    Tool(jobs.create_job, Effect.CREATE),
+    # Lineage
+    Tool(lineage.get_upstream, Effect.READ),
+    Tool(lineage.get_downstream, Effect.READ),
+    Tool(lineage.get_full_lineage, Effect.READ),
+    Tool(lineage.impact_analysis, Effect.READ),
+    Tool(lineage.cross_source_dependencies, Effect.READ),
+    # Scheduling
+    Tool(scheduling.list_jobs, Effect.READ),
+    Tool(scheduling.get_job_health, Effect.READ),
+    Tool(scheduling.toggle_job, Effect.EDIT),
+    Tool(scheduling.toggle_asset, Effect.EDIT),
+    Tool(scheduling.list_recent_runs, Effect.READ),
+    Tool(scheduling.get_run_detail, Effect.READ),
+    Tool(scheduling.list_run_events, Effect.READ),
+    Tool(scheduling.get_event, Effect.READ),
+    Tool(scheduling.list_failures, Effect.READ),
+    Tool(scheduling.error_breakdown, Effect.READ),
+    Tool(scheduling.trigger_run, Effect.LAUNCH),
+    Tool(scheduling.retry_run, Effect.LAUNCH),
+    Tool(scheduling.list_backfills, Effect.READ),
+    Tool(scheduling.backfill_timeline, Effect.READ),
+    Tool(scheduling.trigger_backfill, Effect.LAUNCH),
+    Tool(scheduling.cancel_backfill, Effect.CANCEL),
+    # Analytics
+    Tool(analytics.run_history_summary, Effect.READ),
+    Tool(analytics.partition_coverage, Effect.READ),
+    Tool(analytics.freshness_check, Effect.READ),
+    Tool(analytics.run_stats, Effect.READ),
+    Tool(analytics.asset_coverage, Effect.READ),
+)
+"""Every tool the surfaces expose."""

interloper_toolkit-0.89.0/PKG-INFO

@@ -1,40 +0,0 @@
-Metadata-Version: 2.3
-Name: interloper-toolkit
-Version: 0.89.0
-Summary: Interloper shared read-only tool functions for AI surfaces (agent, MCP)
-Author: Guillaume Onfroy
-Author-email: Guillaume Onfroy <guillaume@digitlcloud.com>
-Requires-Dist: interloper-core
-Requires-Dist: interloper-db
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-
-# interloper-toolkit
-
-The read-only tool functions shared by interloper's AI surfaces — the ADK
-chat agent (`interloper-agent`) and the MCP server (`interloper-mcp`).
-
-Every function takes a frozen `ToolkitContext(store, catalog, org_id)` as its
-first argument and returns `<SuccessModel> | ToolError` — typed pydantic
-results (see `models.py`) discriminated by the literal `status` field, never
-raising. The models are the tool contract: MCP derives per-tool output
-schemas from them, row-projecting models act as an allowlist of what leaves
-the platform, and full-row payloads embed the interloper-db models to keep
-that coupling visible rather than duplicated. The docstrings are LLM-facing:
-both consumers surface them verbatim as tool descriptions.
-
-Modules:
-
-- `catalog` — the component definitions the platform ships (list, detail,
-  asset schemas, field search, schema comparison)
-- `collection` — the org's component instances (read-only listing; sensitive
-  kinds project identity/metadata only)
-- `lineage` — dependency analysis, impact assessment, DAG traversal
-- `scheduling` — jobs, runs, and backfills: read-only monitoring
-- `analytics` — run statistics, partition coverage, data freshness
-
-Mutating operations (trigger/toggle/create) deliberately live with the agent,
-not here — this package is safe to expose on read-only surfaces.
-
-Depends only on `interloper-core` and `interloper-db`; no LLM-framework
-dependencies (no google-adk, no mcp).

interloper_toolkit-0.89.0/README.md

@@ -1,29 +0,0 @@
-# interloper-toolkit
-
-The read-only tool functions shared by interloper's AI surfaces — the ADK
-chat agent (`interloper-agent`) and the MCP server (`interloper-mcp`).
-
-Every function takes a frozen `ToolkitContext(store, catalog, org_id)` as its
-first argument and returns `<SuccessModel> | ToolError` — typed pydantic
-results (see `models.py`) discriminated by the literal `status` field, never
-raising. The models are the tool contract: MCP derives per-tool output
-schemas from them, row-projecting models act as an allowlist of what leaves
-the platform, and full-row payloads embed the interloper-db models to keep
-that coupling visible rather than duplicated. The docstrings are LLM-facing:
-both consumers surface them verbatim as tool descriptions.
-
-Modules:
-
-- `catalog` — the component definitions the platform ships (list, detail,
-  asset schemas, field search, schema comparison)
-- `collection` — the org's component instances (read-only listing; sensitive
-  kinds project identity/metadata only)
-- `lineage` — dependency analysis, impact assessment, DAG traversal
-- `scheduling` — jobs, runs, and backfills: read-only monitoring
-- `analytics` — run statistics, partition coverage, data freshness
-
-Mutating operations (trigger/toggle/create) deliberately live with the agent,
-not here — this package is safe to expose on read-only surfaces.
-
-Depends only on `interloper-core` and `interloper-db`; no LLM-framework
-dependencies (no google-adk, no mcp).

interloper_toolkit-0.89.0/src/interloper_toolkit/__init__.py

@@ -1,22 +0,0 @@
-"""Tool functions shared by AI surfaces (agent, MCP server).
-
-Every function takes a :class:`~interloper_toolkit.context.ToolkitContext`
-as its first argument and returns ``<SuccessModel> | ToolError`` — typed
-pydantic results (see :mod:`interloper_toolkit.models`) discriminated by
-the literal ``status`` field, never raising. The docstrings are LLM-facing:
-both the ADK agent and the MCP server surface them verbatim as tool
-descriptions.
-
-Reads take no role; writes declare the role they need with
-:func:`~interloper_toolkit.authz.requires_role` and refuse below it. Which
-functions a surface exposes is that surface's registration list (the MCP
-server, for one, never registers ``create_connections``, whose arguments
-would carry credentials through the client).
-"""
-
-from interloper_toolkit.authz import requires_role
-from interloper_toolkit.collection import bind_relation, unbind_relation
-from interloper_toolkit.context import ToolkitContext, serialize
-from interloper_toolkit.models import ToolError
-
-__all__ = ["ToolError", "ToolkitContext", "bind_relation", "requires_role", "serialize", "unbind_relation"]