interloper-toolkit 0.123.0__tar.gz → 0.124.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.123.0 → interloper_toolkit-0.124.0}/PKG-INFO +1 -1
  2. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/pyproject.toml +1 -1
  3. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/pyproject.toml.orig +1 -1
  4. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/src/interloper_toolkit/__init__.py +1 -2
  5. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/src/interloper_toolkit/analytics.py +10 -3
  6. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/src/interloper_toolkit/collection.py +34 -17
  7. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/src/interloper_toolkit/models.py +27 -22
  8. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/src/interloper_toolkit/tools.py +9 -9
  9. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/README.md +0 -0
  10. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/src/interloper_toolkit/authz.py +0 -0
  11. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/src/interloper_toolkit/catalog.py +0 -0
  12. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/src/interloper_toolkit/context.py +0 -0
  13. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/src/interloper_toolkit/jobs.py +0 -0
  14. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/src/interloper_toolkit/lineage.py +0 -0
  15. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/src/interloper_toolkit/scheduling.py +0 -0
  16. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/src/interloper_toolkit/sources.py +0 -0
  17. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.0}/src/interloper_toolkit/stats.py +0 -0
  18. {interloper_toolkit-0.123.0 → interloper_toolkit-0.124.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.123.0
3
+ Version: 0.124.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.123.0"
3
+ version = "0.124.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.123.0"
6
+ version = "0.124.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" }]
@@ -17,7 +17,7 @@ MCP server never registers a tool whose arguments carry credentials).
17
17
  from interloper_toolkit.authz import requires_role
18
18
  from interloper_toolkit.collection import bind_relation, unbind_relation
19
19
  from interloper_toolkit.context import ToolkitContext, serialize
20
- from interloper_toolkit.models import ToolError, UserRequest
20
+ from interloper_toolkit.models import ToolError
21
21
  from interloper_toolkit.tools import TOOLS, Effect, Tool
22
22
 
23
23
  __all__ = [
@@ -26,7 +26,6 @@ __all__ = [
26
26
  "Tool",
27
27
  "ToolError",
28
28
  "ToolkitContext",
29
- "UserRequest",
30
29
  "bind_relation",
31
30
  "requires_role",
32
31
  "serialize",
@@ -118,7 +118,10 @@ def asset_coverage(
118
118
  An asset counts as covered for a partition once any run's execution of it
119
119
  succeeded, whatever the run targeted, so a run where most assets
120
120
  succeeded shows what is actually missing. Every asset the job targets
121
- appears, directly or through a source it targets.
121
+ appears, directly or through a source it targets. A snapshot asset (an
122
+ entity read as the vendor holds it now) owes only the periods a run
123
+ observed in; a past one without a success is missed, and is never
124
+ offered for a backfill, which cannot read the past.
122
125
 
123
126
  Args:
124
127
  component_id: UUID of the job.
@@ -130,13 +133,17 @@ def asset_coverage(
130
133
  offset: Number of assets to skip, for paging past the first page.
131
134
 
132
135
  Returns the page of assets, least covered first, each with its covered,
133
- failed and never-run partition counts and its missing partitions as
136
+ failed, missed and never-run partition counts and its missing partitions as
134
137
  ranges ready for a backfill, plus a rollup of the range's partitions by
135
138
  whether all, some or none of the assets are covered.
136
139
  """
137
140
  try:
138
141
  coverage = ctx.store.insights.coverage_by_key(
139
- ctx.org_id, UUID(component_id), start_key=start_key, end_key=end_key
142
+ ctx.org_id,
143
+ UUID(component_id),
144
+ start_key=start_key,
145
+ end_key=end_key,
146
+ now=datetime.datetime.now(tz=datetime.timezone.utc),
140
147
  )
141
148
  return AssetCoverage.from_coverage(coverage, limit=limit, offset=offset)
142
149
  except Exception as e:
@@ -308,19 +308,40 @@ def unbind_relation(ctx: ToolkitContext, component_id: str, name: str, dst_id: s
308
308
  # -- Connections (kind-specific by nature) ---------------------------------------
309
309
 
310
310
 
311
+ def connection_definition(ctx: ToolkitContext, connection_key: str) -> dict[str, Any] | ToolError:
312
+ """The catalog's connection definition under a key.
313
+
314
+ Not a tool: the surfaces' connection setup tools share it to refuse an
315
+ unknown key the same way.
316
+
317
+ Args:
318
+ ctx: The toolkit context.
319
+ connection_key: Catalog key of the connection definition.
320
+
321
+ Returns:
322
+ The definition, or an error listing the valid connection keys.
323
+ """
324
+ defn = ctx.catalog.get(connection_key)
325
+ if defn is None or defn.get("kind") != "connection":
326
+ return ToolError(
327
+ error=f"Connection definition '{connection_key}' not found in catalog",
328
+ valid_values=sorted(k for k, d in ctx.catalog.items() if d.get("kind") == "connection"),
329
+ )
330
+ return defn
331
+
332
+
311
333
  def request_connection_setup(
312
334
  ctx: ToolkitContext, connection_key: str, name: str | None = None
313
335
  ) -> ConnectionSetup | ToolError:
314
- """Hand the user to the app's secure connection setup form.
336
+ """Hand the user a link to the app's secure connection setup form.
315
337
 
316
- Call this to let the user create a connection: the app presents the form
317
- for the given definition (OAuth sign-in when available, manual credential
318
- entry otherwise) and the credentials go directly to the API. Never ask the
319
- user to share credentials in the chat instead. In the app the form opens
320
- in the conversation; elsewhere, give the user ``setup_url`` to open it,
321
- ask them to say when they are done, then verify with check_connection.
322
- A null ``setup_url`` means this deployment has no public app URL: the
323
- user sets the connection up in the app themselves.
338
+ Call this to let the user create a connection: the form for the given
339
+ definition (OAuth sign-in when available, manual credential entry
340
+ otherwise) sends the credentials directly to the API. Never ask the user
341
+ to share credentials in the chat instead. Give the user ``setup_url`` to
342
+ open it, ask them to say when they are done, then verify with
343
+ check_connection. A null ``setup_url`` means this deployment has no
344
+ public app URL: the user sets the connection up in the app themselves.
324
345
 
325
346
  The response notes whether the user can sign in with the provider
326
347
  (``oauth_available``) or must enter credentials manually; an unknown key
@@ -332,17 +353,13 @@ def request_connection_setup(
332
353
  name: Optional display name to prefill in the form.
333
354
  """
334
355
  try:
335
- defn = ctx.catalog.get(connection_key)
336
- if defn is None or defn.get("kind") != "connection":
337
- return ToolError(
338
- error=f"Connection definition '{connection_key}' not found in catalog",
339
- valid_values=sorted(k for k, d in ctx.catalog.items() if d.get("kind") == "connection"),
340
- )
356
+ defn = connection_definition(ctx, connection_key)
357
+ if isinstance(defn, ToolError):
358
+ return defn
341
359
  oauth = (defn.get("config_schema") or {}).get("x-oauth")
342
360
  return ConnectionSetup(
343
361
  message=(
344
- "Setup form presented to the user. Ask them to complete it "
345
- "(and to say so when done), then verify with list_components."
362
+ "Give the user the setup link, ask them to say when they are done, then verify with list_components."
346
363
  ),
347
364
  connection_key=connection_key,
348
365
  name=name,
@@ -270,15 +270,7 @@ class ConnectionsCreated(BaseModel):
270
270
  failed: list[FailedInstance]
271
271
 
272
272
 
273
- class UserRequest(BaseModel):
274
- """A result that asks the user for something the model cannot supply.
275
-
276
- An interactive surface takes it to the user and answers the call with
277
- their input; elsewhere it is an ordinary result the model relays.
278
- """
279
-
280
-
281
- class ConnectionSetup(UserRequest):
273
+ class ConnectionSetup(BaseModel):
282
274
  """The hand-off ``request_connection_setup`` makes.
283
275
 
284
276
  ``setup_url`` opens the app's connection form for this definition, when
@@ -922,36 +914,43 @@ class AssetCoverageRow(BaseModel):
922
914
 
923
915
  A partition is ``covered`` once any run's execution of the asset
924
916
  succeeded, ``failed`` when executions of it only failed, and
925
- ``never_run`` when no run executed the asset for it. ``missing`` lists
926
- the uncovered partitions as ranges, at most 20 of them.
917
+ ``never_run`` when it is owed and no execution of it reached a verdict.
918
+ A snapshot asset (an entity read as the vendor holds it now) owes only
919
+ the periods a run observed in while they are current; one that ended
920
+ without a success is ``missed``, which no backfill can recover.
921
+ ``missing`` lists the owed, uncovered partitions as ranges, at most 20
922
+ of them, missed ones excluded.
927
923
  """
928
924
 
929
925
  asset_id: UUID
930
926
  asset_key: str | None = None
931
927
  covered: int
932
928
  failed: int
929
+ missed: int
933
930
  never_run: int
934
931
  missing: list[PartitionRange]
935
932
  missing_ranges_total: int
936
933
 
937
934
  @classmethod
938
935
  def from_coverage(cls, asset: AssetKeyCoverage, keys: list[str]) -> AssetCoverageRow:
939
- """Count an asset's keys by state and range its uncovered ones.
936
+ """Count an asset's keys by state and range its owed, uncovered ones.
940
937
 
941
938
  Args:
942
- asset: The asset's covered and failed keys.
939
+ asset: The asset's owed, covered, failed and missed keys.
943
940
  keys: Every key of the range, in order.
944
941
 
945
942
  Returns:
946
943
  The row.
947
944
  """
948
- ranges = PartitionRange.from_keys([key for key in keys if key not in asset.covered], keys)
945
+ owed = [key for key in keys if key in asset.expected and key not in asset.covered]
946
+ ranges = PartitionRange.from_keys(owed, keys)
949
947
  return cls(
950
948
  asset_id=asset.asset_id,
951
949
  asset_key=asset.asset_key,
952
950
  covered=len(asset.covered),
953
951
  failed=len(asset.failed),
954
- never_run=len(keys) - len(asset.covered) - len(asset.failed),
952
+ missed=len(asset.missed),
953
+ never_run=len(asset.expected) - len(asset.covered) - len(asset.failed),
955
954
  missing=ranges[:_MISSING_RANGES_LIMIT],
956
955
  missing_ranges_total=len(ranges),
957
956
  )
@@ -960,8 +959,9 @@ class AssetCoverageRow(BaseModel):
960
959
  class AssetCoverage(BaseModel):
961
960
  """Per-asset partition coverage of a job over a range, least covered first.
962
961
 
963
- The rollup counts the range's partitions by how many of the job's assets
964
- are covered for them: all, some, or none.
962
+ The rollup counts the range's partitions by how many of the assets owing
963
+ them are covered: all, some, or none. A partition no asset owes (only
964
+ snapshot assets, none observing in it) counts in none of the three.
965
965
  """
966
966
 
967
967
  status: Literal["success"] = "success"
@@ -993,17 +993,22 @@ class AssetCoverage(BaseModel):
993
993
  (AssetCoverageRow.from_coverage(asset, keys) for asset in coverage.assets),
994
994
  key=lambda row: (row.covered, row.asset_key or ""),
995
995
  )
996
- per_key = [sum(key in asset.covered for asset in coverage.assets) for key in keys]
997
- everyone = len(coverage.assets)
996
+ per_key = [
997
+ (
998
+ sum(key in asset.covered for asset in coverage.assets),
999
+ sum(key in asset.expected for asset in coverage.assets),
1000
+ )
1001
+ for key in keys
1002
+ ]
998
1003
  page = assets[offset : offset + limit]
999
1004
  return cls(
1000
1005
  component_id=coverage.job_id,
1001
1006
  start_key=keys[0],
1002
1007
  end_key=keys[-1],
1003
1008
  partitions=len(keys),
1004
- all_covered=sum(count == everyone for count in per_key) if everyone else 0,
1005
- partly_covered=sum(0 < count < everyone for count in per_key),
1006
- none_covered=sum(count == 0 for count in per_key),
1009
+ all_covered=sum(0 < owed == count for count, owed in per_key),
1010
+ partly_covered=sum(0 < count < owed for count, owed in per_key),
1011
+ none_covered=sum(count == 0 < owed for count, owed in per_key),
1007
1012
  count=len(page),
1008
1013
  total=len(assets),
1009
1014
  assets=page,
@@ -1,11 +1,12 @@
1
- """The tool table: every tool the AI surfaces expose, with its effect on the platform.
2
-
3
- A surface (the agent, the MCP server) registers this table rather than a
4
- list of its own. The effect is the one fact a surface derives its behaviour
5
- from: MCP maps it to the annotations a client keys on, the agent to which
6
- calls wait for the user's approval. ``carries_secrets`` marks a tool whose
7
- arguments would carry credentials; a surface that transports arguments
8
- through a third party leaves it out.
1
+ """The tool table: the tools every AI surface exposes alike, with their effect on the platform.
2
+
3
+ A surface (the agent, the MCP server) registers this table, plus its own
4
+ tools for what only it can do, such as handing the user a form. The effect
5
+ is the one fact a surface derives its behaviour from: MCP maps it to the
6
+ annotations a client keys on, the agent to which calls wait for the user's
7
+ approval. ``carries_secrets`` marks a tool whose arguments would carry
8
+ credentials; a surface that transports arguments through a third party
9
+ leaves it out.
9
10
  """
10
11
 
11
12
  from __future__ import annotations
@@ -171,7 +172,6 @@ TOOLS: tuple[Tool, ...] = (
171
172
  Tool(collection.delete_component, Effect.DELETE, "Delete a component"),
172
173
  Tool(collection.bind_relation, Effect.EDIT, "Bind a relation"),
173
174
  Tool(collection.unbind_relation, Effect.EDIT, "Unbind a relation"),
174
- Tool(collection.request_connection_setup, Effect.READ, "Request a connection setup"),
175
175
  Tool(collection.check_connection, Effect.READ_PROVIDER, "Check a connection"),
176
176
  Tool(collection.create_connections, Effect.CREATE, "Create connections", carries_secrets=True),
177
177
  # Sources and jobs