interloper-toolkit 0.76.0__tar.gz → 0.78.0__tar.gz

{interloper_toolkit-0.76.0 → interloper_toolkit-0.78.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: interloper-toolkit
-Version: 0.76.0
+Version: 0.78.0
 Summary: Interloper shared read-only tool functions for AI surfaces (agent, MCP)
 Author: Guillaume Onfroy
 Author-email: Guillaume Onfroy <guillaume@digitlcloud.com>

{interloper_toolkit-0.76.0 → interloper_toolkit-0.78.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "interloper-toolkit"
-version = "0.76.0"
+version = "0.78.0"
 description = "Interloper shared read-only tool functions for AI surfaces (agent, MCP)"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -14,7 +14,7 @@ name = "Guillaume Onfroy"
 email = "guillaume@digitlcloud.com"
 
 [build-system]
-requires = ["uv_build>=0.11.5,<0.12"]
+requires = ["uv_build>=0.12.9,<0.13"]
 build-backend = "uv_build"
 
 [tool.uv.sources.interloper-core]
@@ -54,6 +54,8 @@ convention = "google"
     "D102",
     "D103",
     "D104",
+    "RUF069",
+    "PLW0108",
 ]
 "src/interloper_toolkit/{analytics,catalog,collection,lineage,scheduling}.py" = [
     "D417",

{interloper_toolkit-0.76.0 → interloper_toolkit-0.78.0}/pyproject.toml.orig

@@ -3,7 +3,7 @@
 # ###############
 [project]
 name = "interloper-toolkit"
-version = "0.76.0"
+version = "0.78.0"
 description = "Interloper shared read-only tool functions for AI surfaces (agent, MCP)"
 readme = "README.md"
 authors = [{ name = "Guillaume Onfroy", email = "guillaume@digitlcloud.com" }]
@@ -14,7 +14,7 @@ dependencies = [
 ]
 
 [build-system]
-requires = ["uv_build>=0.11.5,<0.12"]
+requires = ["uv_build>=0.12.9,<0.13"]
 build-backend = "uv_build"
 
 [tool.uv.sources]
@@ -36,5 +36,5 @@ convention = "google"
 
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401", "F403"]
-"tests/**" = ["ANN", "F811", "D101", "D102", "D103", "D104"]
+"tests/**" = ["ANN", "F811", "D101", "D102", "D103", "D104", "RUF069", "PLW0108"]
 "src/interloper_toolkit/{analytics,catalog,collection,lineage,scheduling}.py" = ["D417", "DOC201", "BLE001"]

interloper_toolkit-0.78.0/src/interloper_toolkit/__init__.py

@@ -0,0 +1,23 @@
+"""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.
+
+Almost every function here is read-only; the sole exceptions are
+:func:`interloper_toolkit.collection.bind_relation` and
+:func:`interloper_toolkit.collection.unbind_relation`, which write and are
+re-exported here as this package's whole write surface. A surface that must
+stay read-only (the MCP server's own registration is one) never registers
+those two; the ADK agent, whose own write tools already live beside them,
+does.
+"""
+
+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", "serialize", "unbind_relation"]

{interloper_toolkit-0.76.0 → interloper_toolkit-0.78.0}/src/interloper_toolkit/catalog.py

@@ -122,7 +122,7 @@ def list_definitions(
 def get_definition(ctx: ToolkitContext, key: str) -> DefinitionDetail | ToolError:
     """Get a component definition's full catalog detail.
 
-    For a source this includes the config schema, resource slots,
+    For a source this includes the config schema, declared relations,
     destination types, and all its assets with their schemas. This is the
     catalog definition (the component *type*), not an instance from the
     org's collection.

interloper_toolkit-0.78.0/src/interloper_toolkit/collection.py

@@ -0,0 +1,120 @@
+"""Collection tools: the org's component instances.
+
+``list_components`` is read-only, shared with surfaces that must stay
+read-only (kind-specific creation and connection operations stay with the
+agent). ``bind_relation`` and ``unbind_relation`` are the exception: they
+write, generically over every kind's declared relations, so a caller must
+never register them alongside a read-only tool set (see
+``interloper_mcp.tools``, deliberately read-only), only wherever that
+surface's own write tools already live.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from interloper.component import KINDS
+from interloper.errors import ConfigError, NotFoundError
+
+from interloper_toolkit.context import ToolkitContext
+from interloper_toolkit.models import (
+    BindResult,
+    ComponentCounts,
+    ComponentList,
+    ComponentSummary,
+    ToolError,
+    UnbindResult,
+)
+
+
+def list_components(
+    ctx: ToolkitContext, kind: str | None = None
+) -> ComponentCounts | ComponentList | ToolError:
+    """List the components in the organisation's collection.
+
+    This answers "what do we have?" — what *could* be added (the catalog of
+    definitions) is the Catalog specialist's domain. Sensitive kinds
+    (connections, configs, resources) always return identity and metadata
+    only — never credential or config values.
+
+    Args:
+        kind: Component kind to list — e.g. 'source', 'connection',
+            'destination'. Omit for per-kind counts only; call again with a
+            kind for the entries.
+    """
+    try:
+        if kind is None:
+            counts: dict[str, int] = {}
+            for c in ctx.store.components.list_all(ctx.org_id):
+                counts[c.kind] = counts.get(c.kind, 0) + 1
+            return ComponentCounts(
+                component_counts=counts,
+                message="Call again with a kind for the entries.",
+            )
+        if kind not in KINDS:
+            return ToolError(error=f"Unknown kind '{kind}'", valid_kinds=sorted(KINDS.keys()))
+
+        results = []
+        for c in ctx.store.components.list_all(ctx.org_id, kinds=[kind]):
+            entry = ComponentSummary(
+                id=str(c.id),
+                key=c.key,
+                name=c.name,
+                type_name=(ctx.catalog.get(c.key) or {}).get("name", c.key),
+                created_at=c.created_at,
+            )
+            # Fail closed: a sensitive kind's config is (or wraps) credentials.
+            if not KINDS[kind].sensitive:
+                entry.config = c.config
+            if kind == "source":
+                entry.asset_count = len(c.children)
+            results.append(entry)
+
+        return ComponentList(kind=kind, count=len(results), components=results)
+    except Exception as e:
+        return ToolError(error=str(e))
+
+
+# -- Relations (write) ---------------------------------------------------------
+
+
+def bind_relation(ctx: ToolkitContext, component_id: str, name: str, dst_id: str) -> BindResult | ToolError:
+    """Bind one component to another under a declared relation name.
+
+    Works on any kind: a source's connection, a job's watched assets, a
+    destination target, whatever the component's own class declares under
+    that name. A ``many`` name accumulates; a single-valued one repoints, so
+    rebinding it needs no prior unbind_relation call. Recap what the binding
+    changes and get the user's explicit confirmation BEFORE calling this.
+
+    Args:
+        component_id: UUID of the component the relation originates from.
+        name: Relation name, which the component's class must declare.
+        dst_id: UUID of the destination component the relation points at.
+            Must belong to the same organisation as the source.
+    """
+    try:
+        row = ctx.store.relations.add(UUID(component_id), name=name, dst_id=UUID(dst_id))
+    except (ConfigError, NotFoundError, ValueError) as e:
+        return ToolError(error=str(e))
+    return BindResult(src_id=str(row.src_id), name=row.name, dst_id=str(row.dst_id), dst_kind=row.dst_kind)
+
+
+def unbind_relation(ctx: ToolkitContext, component_id: str, name: str, dst_id: str) -> UnbindResult | ToolError:
+    """Detach one component from another under a declared relation name.
+
+    A non-optional relation cannot be emptied, only repointed with
+    bind_relation. Recap what the component loses and get the user's
+    explicit confirmation BEFORE calling this.
+
+    Args:
+        component_id: UUID of the component the relation originates from.
+        name: Relation name the edge is filed under.
+        dst_id: UUID of the destination the removed edge points at. Removing
+            an edge that isn't there is a no-op.
+    """
+    try:
+        ctx.store.relations.remove(UUID(component_id), name=name, dst_id=UUID(dst_id))
+    except (ConfigError, NotFoundError, ValueError) as e:
+        return ToolError(error=str(e))
+    return UnbindResult(src_id=component_id, name=name, dst_id=dst_id)

{interloper_toolkit-0.76.0 → interloper_toolkit-0.78.0}/src/interloper_toolkit/lineage.py

@@ -10,11 +10,11 @@ from interloper_toolkit.models import (
     AssetRef,
     CrossSourceDependencies,
     CrossSourceEdge,
-    DependencyEdge,
     DownstreamResult,
     ImpactAnalysis,
     LineageItem,
     LineageResult,
+    RelationEdge,
     ToolError,
     UpstreamResult,
 )
@@ -27,19 +27,19 @@ def get_upstream(ctx: ToolkitContext, asset_id: str) -> UpstreamResult | ToolErr
         asset_id: UUID of the asset to inspect.
 
     Returns the list of upstream assets that this asset depends on,
-    including the parameter name used for each dependency.
+    including the relation name used for each dependency.
     """
     try:
-        deps = ctx.store.relations.list_all(ctx.org_id, type="dependency")
+        deps = ctx.store.relations.list_all(ctx.org_id, src_kind="asset", dst_kind="asset")
         target = UUID(asset_id)
 
         upstream = []
         for dep in deps:
             if dep.src_id == target:
                 asset = ctx.store.components.get(dep.dst_id, kind="asset")
-                upstream.append(DependencyEdge(
+                upstream.append(RelationEdge(
                     asset_id=str(dep.dst_id),
-                    param_name=dep.slot,
+                    param_name=dep.name,
                     asset_key=asset.key,
                     source_id=str(asset.parent_id),
                 ))
@@ -58,16 +58,16 @@ def get_downstream(ctx: ToolkitContext, asset_id: str) -> DownstreamResult | Too
     Returns the list of assets that directly depend on this asset.
     """
     try:
-        deps = ctx.store.relations.list_all(ctx.org_id, type="dependency")
+        deps = ctx.store.relations.list_all(ctx.org_id, src_kind="asset", dst_kind="asset")
         target = UUID(asset_id)
 
         downstream = []
         for dep in deps:
             if dep.dst_id == target:
                 asset = ctx.store.components.get(dep.src_id, kind="asset")
-                downstream.append(DependencyEdge(
+                downstream.append(RelationEdge(
                     asset_id=str(dep.src_id),
-                    param_name=dep.slot,
+                    param_name=dep.name,
                     asset_key=asset.key,
                     source_id=str(asset.parent_id),
                 ))
@@ -165,7 +165,7 @@ def cross_source_dependencies(ctx: ToolkitContext) -> CrossSourceDependencies |
     different sources.
     """
     try:
-        deps = ctx.store.relations.list_all(ctx.org_id, type="dependency")
+        deps = ctx.store.relations.list_all(ctx.org_id, src_kind="asset", dst_kind="asset")
         assets = ctx.store.components.list_all(ctx.org_id, kinds=["asset"])
 
         asset_source: dict[UUID, UUID | None] = {}
@@ -186,7 +186,7 @@ def cross_source_dependencies(ctx: ToolkitContext) -> CrossSourceDependencies |
                     downstream=asset_info.get(dep.src_id, AssetRef()),
                     upstream_asset_id=str(dep.dst_id),
                     upstream=asset_info.get(dep.dst_id, AssetRef()),
-                    param_name=dep.slot,
+                    param_name=dep.name,
                 ))
 
         return CrossSourceDependencies(cross_source_count=len(cross_deps), dependencies=cross_deps)
@@ -201,7 +201,7 @@ def _build_adjacency(
     ctx: ToolkitContext,
     direction: str,
 ) -> tuple[dict[UUID, list[UUID]], dict[UUID, dict[str, str]]]:
-    """Build an adjacency map and asset info lookup from all dependencies.
+    """Build an adjacency map and asset info lookup from all asset-to-asset relations.
 
     Args:
         ctx: The toolkit context.
@@ -211,7 +211,7 @@ def _build_adjacency(
         ``(adjacency_map, asset_info_map)`` — info values feed
         :class:`LineageItem` kwargs (asset_key, source_id, source_key).
     """
-    deps = ctx.store.relations.list_all(ctx.org_id, type="dependency")
+    deps = ctx.store.relations.list_all(ctx.org_id, src_kind="asset", dst_kind="asset")
     assets = ctx.store.components.list_all(ctx.org_id, kinds=["asset"])
 
     asset_info: dict[UUID, dict[str, str]] = {}

{interloper_toolkit-0.76.0 → interloper_toolkit-0.78.0}/src/interloper_toolkit/models.py

@@ -180,11 +180,30 @@ class ComponentList(BaseModel):
     components: list[ComponentSummary]
 
 
+class BindResult(BaseModel):
+    """One relation edge created or repointed by ``bind_relation``."""
+
+    status: Literal["success"] = "success"
+    src_id: str
+    name: str
+    dst_id: str
+    dst_kind: str
+
+
+class UnbindResult(BaseModel):
+    """One relation edge removed by ``unbind_relation``."""
+
+    status: Literal["success"] = "success"
+    src_id: str
+    name: str
+    dst_id: str
+
+
 # -- Lineage --------------------------------------------------------------------
 
 
-class DependencyEdge(BaseModel):
-    """A direct dependency edge from the perspective of one asset."""
+class RelationEdge(BaseModel):
+    """A direct asset-to-asset relation edge from the perspective of one asset."""
 
     asset_id: str
     param_name: str
@@ -197,7 +216,7 @@ class UpstreamResult(BaseModel):
 
     status: Literal["success"] = "success"
     asset_id: str
-    upstream: list[DependencyEdge]
+    upstream: list[RelationEdge]
 
 
 class DownstreamResult(BaseModel):
@@ -205,7 +224,7 @@ class DownstreamResult(BaseModel):
 
     status: Literal["success"] = "success"
     asset_id: str
-    downstream: list[DependencyEdge]
+    downstream: list[RelationEdge]
 
 
 class LineageItem(BaseModel):

interloper_toolkit-0.76.0/src/interloper_toolkit/__init__.py

@@ -1,14 +0,0 @@
-"""Read-only 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.
-"""
-
-from interloper_toolkit.context import ToolkitContext, serialize
-from interloper_toolkit.models import ToolError
-
-__all__ = ["ToolError", "ToolkitContext", "serialize"]

interloper_toolkit-0.76.0/src/interloper_toolkit/collection.py

@@ -1,60 +0,0 @@
-"""Collection tools — the org's component instances, read-only.
-
-Creation and connection operations stay with the agent; this module is
-shared with surfaces that must stay read-only.
-"""
-
-from __future__ import annotations
-
-from interloper.component import KINDS
-
-from interloper_toolkit.context import ToolkitContext
-from interloper_toolkit.models import ComponentCounts, ComponentList, ComponentSummary, ToolError
-
-
-def list_components(
-    ctx: ToolkitContext, kind: str | None = None
-) -> ComponentCounts | ComponentList | ToolError:
-    """List the components in the organisation's collection.
-
-    This answers "what do we have?" — what *could* be added (the catalog of
-    definitions) is the Catalog specialist's domain. Sensitive kinds
-    (connections, configs, resources) always return identity and metadata
-    only — never credential or config values.
-
-    Args:
-        kind: Component kind to list — e.g. 'source', 'connection',
-            'destination'. Omit for per-kind counts only; call again with a
-            kind for the entries.
-    """
-    try:
-        if kind is None:
-            counts: dict[str, int] = {}
-            for c in ctx.store.components.list_all(ctx.org_id):
-                counts[c.kind] = counts.get(c.kind, 0) + 1
-            return ComponentCounts(
-                component_counts=counts,
-                message="Call again with a kind for the entries.",
-            )
-        if kind not in KINDS:
-            return ToolError(error=f"Unknown kind '{kind}'", valid_kinds=sorted(KINDS.keys()))
-
-        results = []
-        for c in ctx.store.components.list_all(ctx.org_id, kinds=[kind]):
-            entry = ComponentSummary(
-                id=str(c.id),
-                key=c.key,
-                name=c.name,
-                type_name=(ctx.catalog.get(c.key) or {}).get("name", c.key),
-                created_at=c.created_at,
-            )
-            # Fail closed: a sensitive kind's config is (or wraps) credentials.
-            if not KINDS[kind].sensitive:
-                entry.config = c.config
-            if kind == "source":
-                entry.asset_count = len(c.children)
-            results.append(entry)
-
-        return ComponentList(kind=kind, count=len(results), components=results)
-    except Exception as e:
-        return ToolError(error=str(e))