interloper-toolkit 0.43.0__py3-none-any.whl

interloper_toolkit/scheduling.py

@@ -0,0 +1,172 @@
+"""Scheduling tools — jobs, runs, and backfills: read-only monitoring.
+
+Mutating operations (toggling jobs, triggering runs and backfills) live with
+the agent — this module is shared with surfaces that must stay read-only.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from interloper_toolkit.context import ToolkitContext
+from interloper_toolkit.models import (
+    BackfillList,
+    FailureList,
+    JobHealth,
+    JobHealthStats,
+    JobList,
+    RunDetail,
+    RunErrorEvent,
+    RunFailure,
+    RunList,
+    ToolError,
+)
+
+# --- Jobs ---
+
+
+def list_jobs(ctx: ToolkitContext) -> JobList | ToolError:
+    """List all scheduled jobs in the organisation.
+
+    Returns each job with its name, cron expression, enabled status,
+    last_run_at, and next_run_at.
+    """
+    try:
+        jobs = ctx.store.list_components(ctx.org_id, kinds=["job"])
+        return JobList(count=len(jobs), jobs=jobs)
+    except Exception as e:
+        return ToolError(error=str(e))
+
+
+def get_job_health(ctx: ToolkitContext, component_id: str) -> JobHealth | ToolError:
+    """Get health summary for a job: metadata, recent success/failure rate.
+
+    Args:
+        component_id: UUID of the job to inspect.
+
+    Returns job metadata plus success rate computed from the last 20 runs.
+    """
+    try:
+        jid = UUID(component_id)
+        job = ctx.store.get_component(jid, kind="job")
+        runs = ctx.store.list_runs(ctx.org_id, component_id=jid, limit=20)
+
+        total = len(runs)
+        success = sum(1 for r in runs if r.status == "success")
+        failed = sum(1 for r in runs if r.status == "failed")
+
+        # Compute average duration for completed runs
+        durations = []
+        for r in runs:
+            if r.started_at and r.completed_at:
+                delta = r.completed_at - r.started_at
+                durations.append(delta.total_seconds())
+        avg_duration_seconds = sum(durations) / len(durations) if durations else None
+
+        return JobHealth(
+            job=job,
+            health=JobHealthStats(
+                total_recent_runs=total,
+                success_count=success,
+                failed_count=failed,
+                success_rate=round(success / total, 2) if total > 0 else None,
+                avg_duration_seconds=round(avg_duration_seconds, 1) if avg_duration_seconds else None,
+            ),
+        )
+    except Exception as e:
+        return ToolError(error=str(e))
+
+
+# --- Runs ---
+
+
+def list_recent_runs(
+    ctx: ToolkitContext,
+    component_id: str | None = None,
+    status: str | None = None,
+    limit: int = 20,
+) -> RunList | ToolError:
+    """List recent runs with optional filters.
+
+    Args:
+        component_id: Filter by job UUID (optional).
+        status: Filter by status: 'queued', 'running', 'success', 'failed', 'canceled' (optional).
+        limit: Maximum number of runs to return (default 20).
+    """
+    try:
+        runs = ctx.store.list_runs(
+            ctx.org_id,
+            component_id=UUID(component_id) if component_id else None,
+            status=status,
+            limit=limit,
+        )
+        return RunList(count=len(runs), runs=runs)
+    except Exception as e:
+        return ToolError(error=str(e))
+
+
+def get_run_detail(ctx: ToolkitContext, run_id: str) -> RunDetail | ToolError:
+    """Get full detail for a single run including events and per-asset execution status.
+
+    Args:
+        run_id: UUID of the run.
+
+    Returns the run metadata, event timeline, and per-asset execution summary.
+    """
+    try:
+        rid = UUID(run_id)
+        run = ctx.store.get_run(rid)
+        events = ctx.store.list_events(run_id=rid)
+        asset_execs = ctx.store.list_asset_executions(rid)
+
+        return RunDetail(run=run, events=events, asset_executions=asset_execs)
+    except Exception as e:
+        return ToolError(error=str(e))
+
+
+def list_failures(ctx: ToolkitContext, limit: int = 20) -> FailureList | ToolError:
+    """List recent failed runs with their error events.
+
+    Args:
+        limit: Maximum number of failed runs to return (default 20).
+
+    Returns failed runs along with the error messages from their events.
+    """
+    try:
+        failed_runs = ctx.store.list_runs(ctx.org_id, status="failed", limit=limit)
+
+        results = []
+        for run in failed_runs:
+            run_id = run.id
+            events = ctx.store.list_events(run_id=run_id)
+            errors = [
+                RunErrorEvent(asset_key=e.asset_key, error=e.error, timestamp=e.timestamp)
+                for e in events
+                if e.error
+            ]
+            results.append(RunFailure(run=run, errors=errors))
+
+        return FailureList(count=len(results), failures=results)
+    except Exception as e:
+        return ToolError(error=str(e))
+
+
+# --- Backfills ---
+
+
+def list_backfills(ctx: ToolkitContext, active_only: bool = True) -> BackfillList | ToolError:
+    """List backfills, optionally filtered to active ones only.
+
+    Args:
+        active_only: If true, only return running/queued backfills (default true).
+
+    Returns backfills with their status, date range, and partition progress.
+    """
+    try:
+        if active_only:
+            backfills = ctx.store.list_active_backfills(ctx.org_id)
+        else:
+            backfills = ctx.store.list_backfills(ctx.org_id)
+        return BackfillList(count=len(backfills), backfills=backfills)
+    except Exception as e:
+        return ToolError(error=str(e))

interloper_toolkit-0.43.0.dist-info/METADATA

@@ -0,0 +1,40 @@
+Metadata-Version: 2.3
+Name: interloper-toolkit
+Version: 0.43.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.43.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+interloper_toolkit/__init__.py,sha256=DMqH8CcEPWezTUTEhN4sQlMyBrBgj8kO0fg1GYlMU58,627
+interloper_toolkit/analytics.py,sha256=QHzPmcp9i3iNS1bWXSU8rwCPsUs_hBVy0-H7ZkIdMlA,5178
+interloper_toolkit/catalog.py,sha256=YwFEPMsY-7cehLIZjBT3GV9X1aZx3MFjQRkOYopPbXk,12084
+interloper_toolkit/collection.py,sha256=akurHQcQ2gYPIRNR4QchpPiHxeOyO2lQI921YP_YnrM,2322
+interloper_toolkit/context.py,sha256=Euc7r0dOzSr0zMhfHWLrw8iV1wJkdT9P84S-Ml7Yj5M,1583
+interloper_toolkit/lineage.py,sha256=6ZkKlmzon9CTn3IM9do6qu3Sq6--RqcclObD3FTtcPI,8235
+interloper_toolkit/models.py,sha256=IVKTu8EKZrk6w0RApO1U6yM5X6rNT0hi37S1iULcncU,9956
+interloper_toolkit/scheduling.py,sha256=iSujke74Mj8SoeQn0qSonVY_RNvAAOmXS8mLMrAksbs,5440
+interloper_toolkit-0.43.0.dist-info/WHEEL,sha256=s49dN1sxqzkgPplo4QuUaKomil-_cbDzeLK4-pZKD-A,81
+interloper_toolkit-0.43.0.dist-info/METADATA,sha256=WhBZU3EN7cL7woYRI--yWAz5Bx2B7phDJtCGImsthAM,1830
+interloper_toolkit-0.43.0.dist-info/RECORD,,

interloper_toolkit-0.43.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.24
+Root-Is-Purelib: true
+Tag: py3-none-any