interloper-toolkit 0.119.0__tar.gz → 0.121.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/PKG-INFO +1 -1
  2. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/pyproject.toml +1 -1
  3. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/pyproject.toml.orig +1 -1
  4. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/src/interloper_toolkit/collection.py +11 -53
  5. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/src/interloper_toolkit/models.py +2 -5
  6. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/src/interloper_toolkit/sources.py +3 -5
  7. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/src/interloper_toolkit/tools.py +56 -8
  8. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/README.md +0 -0
  9. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/src/interloper_toolkit/__init__.py +0 -0
  10. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/src/interloper_toolkit/analytics.py +0 -0
  11. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/src/interloper_toolkit/authz.py +0 -0
  12. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/src/interloper_toolkit/catalog.py +0 -0
  13. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/src/interloper_toolkit/context.py +0 -0
  14. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/src/interloper_toolkit/jobs.py +0 -0
  15. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/src/interloper_toolkit/lineage.py +0 -0
  16. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/src/interloper_toolkit/scheduling.py +0 -0
  17. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/src/interloper_toolkit/stats.py +0 -0
  18. {interloper_toolkit-0.119.0 → interloper_toolkit-0.121.0}/src/interloper_toolkit/utils.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.3
2
2
  Name: interloper-toolkit
3
- Version: 0.119.0
3
+ Version: 0.121.0
4
4
  Summary: Interloper tool functions shared by the AI surfaces (agent, MCP)
5
5
  Author: Guillaume Onfroy
6
6
  Author-email: Guillaume Onfroy <guillaume@digitlcloud.com>
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "interloper-toolkit"
3
- version = "0.119.0"
3
+ version = "0.121.0"
4
4
  description = "Interloper tool functions shared by the AI surfaces (agent, MCP)"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.10"
@@ -3,7 +3,7 @@
3
3
  # ###############
4
4
  [project]
5
5
  name = "interloper-toolkit"
6
- version = "0.119.0"
6
+ version = "0.121.0"
7
7
  description = "Interloper tool functions shared by the AI surfaces (agent, MCP)"
8
8
  readme = "README.md"
9
9
  authors = [{ name = "Guillaume Onfroy", email = "guillaume@digitlcloud.com" }]
@@ -11,19 +11,16 @@ the browser submits credentials to the API directly.
11
11
 
12
12
  from __future__ import annotations
13
13
 
14
- import asyncio
15
14
  import logging
16
15
  from typing import Any
17
16
  from urllib.parse import urlencode
18
17
  from uuid import UUID
19
18
 
20
- import httpx2
21
19
  from interloper.component import KINDS
22
20
  from interloper.connection import Connection
23
- from interloper.errors import CatalogKeyError, ConfigError, ConnectionCheckError
21
+ from interloper.errors import CatalogKeyError, ConfigError
24
22
  from interloper.oauth import OAuthAppCredentials
25
23
  from interloper.settings import AppSettings
26
- from interloper.utils import invoke
27
24
  from interloper_db import ComponentDriftError, ComponentQuery, HydrationError, InUseError, NotFoundError
28
25
  from pydantic import ValidationError
29
26
 
@@ -351,7 +348,7 @@ def request_connection_setup(
351
348
  name=name,
352
349
  oauth=oauth is not None,
353
350
  oauth_available=OAuthAppCredentials.is_configured(oauth["provider"]) if oauth else False,
354
- setup_url=_setup_url(connection_key, name),
351
+ setup_url=_setup_url(ctx, connection_key, name),
355
352
  )
356
353
  except Exception as e:
357
354
  return ToolError(error=str(e))
@@ -453,32 +450,19 @@ async def check_connection(ctx: ToolkitContext, connection_id: str) -> Connectio
453
450
  message = "The stored connection could not be reconstructed."
454
451
  return ConnectionCheck(connection=info, ok=False, live=False, category="config", message=message)
455
452
 
456
- if not isinstance(conn, Connection) or not conn.checkable():
457
- return ConnectionCheck(
458
- connection=info,
459
- ok=True,
460
- live=False,
461
- message="This connection type implements no live check; the stored config hydrates.",
462
- )
463
- try:
464
- ok = bool(await asyncio.wait_for(invoke(conn.check), timeout=_CHECK_TIMEOUT))
465
- except Exception as e:
466
- logger.error("Connection check failed for '%s' (%s): %s", component.name, component.key, e)
467
- category, message = categorise(e)
468
- return ConnectionCheck(connection=info, ok=False, live=True, category=category, message=message)
469
- if not ok:
470
- return ConnectionCheck(
471
- connection=info, ok=False, live=True, category="error", message="The connection check failed."
472
- )
473
- return ConnectionCheck(connection=info, ok=True, live=True)
453
+ if not isinstance(conn, Connection):
454
+ return ConnectionCheck(connection=info, ok=True, live=False)
455
+ result = await conn.verify(timeout=_CHECK_TIMEOUT)
456
+ return ConnectionCheck(connection=info, **result.model_dump())
474
457
  except Exception as e:
475
458
  return ToolError(error=str(e))
476
459
 
477
460
 
478
- def _setup_url(connection_key: str, name: str | None) -> str | None:
479
- """The app's connection form for a definition, pre-filled with a name.
461
+ def _setup_url(ctx: ToolkitContext, connection_key: str, name: str | None) -> str | None:
462
+ """The app's connection form for a definition in the context's organisation, pre-filled with a name.
480
463
 
481
464
  Args:
465
+ ctx: The call's context, whose organisation's slug leads the path.
482
466
  connection_key: The connection definition to open the form for.
483
467
  name: The display name to prefill, or ``None``.
484
468
 
@@ -488,32 +472,6 @@ def _setup_url(connection_key: str, name: str | None) -> str | None:
488
472
  base = AppSettings.get().server.external_url.rstrip("/")
489
473
  if not base:
490
474
  return None
475
+ slug = ctx.store.organisations.get(ctx.org_id).slug
491
476
  query = {"new": connection_key, **({"name": name} if name else {})}
492
- return f"{base}/components/connections?{urlencode(query)}"
493
-
494
-
495
- def categorise(exc: Exception) -> tuple[str, str]:
496
- """Map a provider call's failure to an LLM-safe ``(category, message)`` pair.
497
-
498
- Written against the categorisation contract documented on
499
- ``Connection.check()``. Raw provider errors may carry URLs with tokens,
500
- and a tool's output enters the model context — only curated messages
501
- leave here; details are logged server-side.
502
-
503
- Args:
504
- exc: The exception the provider call raised.
505
-
506
- Returns:
507
- The ``(category, message)`` pair.
508
- """
509
- if isinstance(exc, ConnectionCheckError):
510
- return "error", str(exc)
511
- if isinstance(exc, httpx2.HTTPStatusError):
512
- if exc.response.status_code in (401, 403):
513
- return "auth", "The provider rejected the credentials."
514
- return "error", f"The provider responded with HTTP {exc.response.status_code}."
515
- if isinstance(exc, (TimeoutError, httpx2.TimeoutException)):
516
- return "network", "The provider did not respond in time."
517
- if isinstance(exc, httpx2.TransportError):
518
- return "network", "The provider could not be reached."
519
- return "error", "The connection check failed unexpectedly."
477
+ return f"{base}/{slug}/components/connections?{urlencode(query)}"
@@ -27,6 +27,7 @@ from datetime import datetime
27
27
  from typing import Any, Literal
28
28
  from uuid import UUID
29
29
 
30
+ from interloper.connection import CheckResult
30
31
  from interloper_db.models import Backfill, Component, Event, Execution, Run
31
32
  from interloper_db.store.insights import (
32
33
  Activity,
@@ -293,7 +294,7 @@ class ConnectionSetup(UserRequest):
293
294
  setup_url: str | None = None
294
295
 
295
296
 
296
- class ConnectionCheck(BaseModel):
297
+ class ConnectionCheck(CheckResult):
297
298
  """The outcome of a connection's health check.
298
299
 
299
300
  ``live`` is false when the type implements no check and only hydration
@@ -303,10 +304,6 @@ class ConnectionCheck(BaseModel):
303
304
 
304
305
  status: Literal["success"] = "success"
305
306
  connection: ComponentRef
306
- ok: bool
307
- live: bool
308
- category: str | None = None
309
- message: str | None = None
310
307
 
311
308
 
312
309
  class BindResult(BaseModel):
@@ -13,6 +13,7 @@ import logging
13
13
  from typing import Any
14
14
  from uuid import UUID
15
15
 
16
+ from interloper.connection import CheckResult
16
17
  from interloper.errors import CatalogKeyError, ConfigError
17
18
  from interloper.resource import is_fetch_field_provider
18
19
  from interloper.utils import invoke
@@ -56,9 +57,6 @@ async def resolve_source_field_options(
56
57
  names: most definitions have exactly one fetchable field and it
57
58
  is picked automatically (the response names it).
58
59
  """
59
- # Imported here: collection imports this module for the asset helpers.
60
- from interloper_toolkit.collection import categorise
61
-
62
60
  try:
63
61
  defn = ctx.catalog.get(source_key)
64
62
  if defn is None or defn.get("kind") != "source":
@@ -93,8 +91,8 @@ async def resolve_source_field_options(
93
91
  items = list(await asyncio.wait_for(invoke(fn), timeout=_RESOLVE_TIMEOUT) or [])
94
92
  except Exception as e:
95
93
  logger.error("Resolving %s.%s via '%s' failed: %s", source_key, field, component.name, e)
96
- category, message = categorise(e)
97
- return ToolError(error=message, category=category)
94
+ failure = CheckResult.from_failure(e)
95
+ return ToolError(error=failure.message or "The provider call failed.", category=failure.category)
98
96
 
99
97
  label_key, value_key = fetch.get("label_key"), fetch.get("value_key")
100
98
  options = [
@@ -13,13 +13,14 @@ from __future__ import annotations
13
13
  import inspect
14
14
  import types
15
15
  import typing
16
- from collections.abc import Callable
16
+ from collections.abc import Callable, Sequence
17
17
  from dataclasses import dataclass
18
18
  from enum import Enum
19
19
  from typing import Any
20
20
 
21
21
  from interloper_toolkit import analytics, catalog, collection, jobs, lineage, scheduling, sources
22
22
  from interloper_toolkit.context import ToolkitContext
23
+ from interloper_toolkit.models import ToolError
23
24
 
24
25
 
25
26
  class Effect(str, Enum):
@@ -66,18 +67,27 @@ class Tool:
66
67
  """
67
68
  return self.effect in (Effect.CREATE, Effect.CANCEL, Effect.DELETE)
68
69
 
69
- def bind(self, context: Callable[..., ToolkitContext], *leading: inspect.Parameter) -> types.FunctionType:
70
+ def bind(
71
+ self,
72
+ context: Callable[..., ToolkitContext | ToolError],
73
+ *leading: inspect.Parameter,
74
+ trailing: Sequence[inspect.Parameter] = (),
75
+ ) -> types.FunctionType:
70
76
  """Adapt the function to a surface that supplies the context itself.
71
77
 
72
78
  The bound function keeps the name, docstring and every parameter but
73
79
  the context, so the schema a model sees is exactly the toolkit's.
74
80
  ``leading`` are the surface's own parameters in the context's place,
75
- if any; ``context`` receives their values and returns the context to
76
- call with.
81
+ if any, and ``trailing`` its own keyword-only parameters after the
82
+ toolkit's. ``context`` receives the leading values positionally, then
83
+ the trailing values as keywords, and returns the context to call with.
84
+ A :class:`~interloper_toolkit.models.ToolError` it returns is the
85
+ bound function's result: the toolkit function is not called.
77
86
 
78
87
  Args:
79
- context: Derives the toolkit context from the leading arguments.
88
+ context: Derives the toolkit context from the surface's arguments, or refuses the call.
80
89
  *leading: Parameters the bound function takes before the toolkit's own.
90
+ trailing: Keyword-only parameters the bound function takes after the toolkit's own.
81
91
 
82
92
  Returns:
83
93
  The bound function, with an explicit signature and annotations.
@@ -85,18 +95,28 @@ class Tool:
85
95
  signature = inspect.signature(self.fn)
86
96
  hints = typing.get_type_hints(self.fn)
87
97
  _, *rest = signature.parameters
88
- parameters = [*leading, *(signature.parameters[name].replace(annotation=hints[name]) for name in rest)]
98
+ parameters = [
99
+ *leading,
100
+ *(signature.parameters[name].replace(annotation=hints[name]) for name in rest),
101
+ *trailing,
102
+ ]
89
103
  returns = hints.get("return", Any)
90
104
  split = len(leading)
91
105
 
92
106
  if inspect.iscoroutinefunction(self.fn):
93
107
 
94
108
  async def tool(*args: Any, **kwargs: Any) -> Any:
95
- return await self.fn(context(*args[:split]), *args[split:], **kwargs)
109
+ derived = self._derive(context, split, trailing, args, kwargs)
110
+ if isinstance(derived, ToolError):
111
+ return derived
112
+ return await self.fn(derived, *args[split:], **kwargs)
96
113
  else:
97
114
 
98
115
  def tool(*args: Any, **kwargs: Any) -> Any:
99
- return self.fn(context(*args[:split]), *args[split:], **kwargs)
116
+ derived = self._derive(context, split, trailing, args, kwargs)
117
+ if isinstance(derived, ToolError):
118
+ return derived
119
+ return self.fn(derived, *args[split:], **kwargs)
100
120
 
101
121
  tool.__name__ = tool.__qualname__ = self.name
102
122
  tool.__module__ = self.fn.__module__
@@ -105,6 +125,34 @@ class Tool:
105
125
  tool.__annotations__ = {p.name: p.annotation for p in parameters} | {"return": returns}
106
126
  return tool
107
127
 
128
+ @staticmethod
129
+ def _derive(
130
+ context: Callable[..., ToolkitContext | ToolError],
131
+ split: int,
132
+ trailing: Sequence[inspect.Parameter],
133
+ args: tuple[Any, ...],
134
+ kwargs: dict[str, Any],
135
+ ) -> ToolkitContext | ToolError:
136
+ """Call the surface's context with its own arguments, taking the trailing ones out of the call.
137
+
138
+ Args:
139
+ context: The surface's context callable.
140
+ split: How many leading arguments the call carries.
141
+ trailing: The surface's keyword-only parameters, whose values are removed from ``kwargs``.
142
+ args: The bound function's positional arguments.
143
+ kwargs: The bound function's keyword arguments, left with the toolkit function's own.
144
+
145
+ Returns:
146
+ The toolkit context, or the refusal the surface returned.
147
+ """
148
+ values = {
149
+ parameter.name: kwargs.pop(parameter.name)
150
+ if parameter.default is inspect.Parameter.empty
151
+ else kwargs.pop(parameter.name, parameter.default)
152
+ for parameter in trailing
153
+ }
154
+ return context(*args[:split], **values)
155
+
108
156
 
109
157
  TOOLS: tuple[Tool, ...] = (
110
158
  # Catalog