interloper-agent 0.2.0__py3-none-any.whl

interloper_agent/__init__.py

@@ -0,0 +1,4 @@
+from interloper_agent import agent
+from interloper_agent.context import init, set_catalog, set_store
+
+__all__ = ["agent", "init", "set_catalog", "set_store"]

interloper_agent/agent.py

@@ -0,0 +1,90 @@
+"""Interloper Agent — multi-agent system for asset discovery, lineage, and operations."""
+
+from google.adk.agents import Agent
+
+from interloper_agent.prompts import (
+    ACTION_INSTRUCTION,
+    ANALYTICS_INSTRUCTION,
+    CATALOG_INSTRUCTION,
+    LINEAGE_INSTRUCTION,
+    OPERATIONS_INSTRUCTION,
+    ROOT_INSTRUCTION,
+)
+from interloper_agent.tools import actions, analytics, catalog, lineage, operations
+
+catalog_agent = Agent(
+    name="CatalogAgent",
+    model="gemini-2.5-flash",
+    description="Discovers sources, inspects asset schemas, searches fields across the catalog, and compares schemas.",
+    instruction=CATALOG_INSTRUCTION,
+    tools=[
+        catalog.list_sources,
+        catalog.get_source_detail,
+        catalog.get_asset_schema,
+        catalog.search_fields,
+        catalog.compare_schemas,
+        catalog.list_destinations,
+    ],
+)
+
+lineage_agent = Agent(
+    name="LineageAgent",
+    model="gemini-2.5-flash",
+    description="Analyzes asset dependencies — upstream/downstream traversal, impact analysis, and cross-source edges.",
+    instruction=LINEAGE_INSTRUCTION,
+    tools=[
+        lineage.get_upstream,
+        lineage.get_downstream,
+        lineage.get_full_lineage,
+        lineage.impact_analysis,
+        lineage.cross_source_dependencies,
+    ],
+)
+
+operations_agent = Agent(
+    name="OperationsAgent",
+    model="gemini-2.5-flash",
+    description="Monitors run health, recent failures, job schedules, and backfill progress.",
+    instruction=OPERATIONS_INSTRUCTION,
+    tools=[
+        operations.list_recent_runs,
+        operations.get_run_detail,
+        operations.list_failures,
+        operations.get_job_health,
+        operations.list_jobs,
+        operations.list_backfills,
+    ],
+)
+
+analytics_agent = Agent(
+    name="AnalyticsAgent",
+    model="gemini-2.5-flash",
+    description="Provides run statistics, partition coverage analysis, and data freshness checks.",
+    instruction=ANALYTICS_INSTRUCTION,
+    tools=[
+        analytics.run_history_summary,
+        analytics.partition_coverage,
+        analytics.freshness_check,
+    ],
+)
+
+action_agent = Agent(
+    name="ActionAgent",
+    model="gemini-2.5-flash",
+    description="Triggers runs, starts backfills, and toggles jobs or assets on/off.",
+    instruction=ACTION_INSTRUCTION,
+    tools=[
+        actions.trigger_run,
+        actions.trigger_backfill,
+        actions.toggle_job,
+        actions.toggle_asset,
+    ],
+)
+
+root_agent = Agent(
+    name="InterloperAgent",
+    model="gemini-2.5-flash",
+    instruction=ROOT_INSTRUCTION,
+    description="Main Interloper assistant that routes queries to specialized sub-agents.",
+    sub_agents=[catalog_agent, lineage_agent, operations_agent, analytics_agent, action_agent],
+)

interloper_agent/context.py

@@ -0,0 +1,103 @@
+"""Store, catalog, and session context for agent tools."""
+
+from __future__ import annotations
+
+import datetime
+from typing import Any
+from uuid import UUID
+
+from google.adk.tools.tool_context import ToolContext
+from interloper.catalog.base import Catalog
+from interloper_db import Store, init_engine
+
+_store: Store | None = None
+_catalog: Catalog | None = None
+
+
+def init(database_url: str, catalog: Catalog) -> None:
+    """Initialize the agent context with a database connection and catalog.
+
+    Args:
+        database_url: PostgreSQL connection string.
+        catalog: Catalog instance.
+    """
+    global _store, _catalog  # noqa: PLW0603
+    init_engine(database_url)
+    _catalog = catalog
+    _store = Store(catalog=catalog)
+
+
+def set_store(store: Store) -> None:
+    """Set the global Store instance (used by interloper-api integration).
+
+    Args:
+        store: An already-initialized Store.
+    """
+    global _store  # noqa: PLW0603
+    _store = store
+
+
+def set_catalog(catalog: Catalog) -> None:
+    """Set the global catalog instance (used by interloper-api integration).
+
+    Args:
+        catalog: Catalog instance.
+    """
+    global _catalog  # noqa: PLW0603
+    _catalog = catalog
+
+
+def get_store() -> Store:
+    """Return the global Store instance."""
+    if _store is None:
+        raise RuntimeError("Agent context not initialized. Call init() or set_store() first.")
+    return _store
+
+
+def get_catalog() -> dict[str, Any]:
+    """Return the global catalog as a serialized dict."""
+    if _catalog is None:
+        raise RuntimeError("Agent context not initialized. Call init() or set_catalog() first.")
+    return _catalog.dump()
+
+
+def get_org_id(tool_context: ToolContext) -> UUID:
+    """Extract the organisation ID from ADK session state.
+
+    The caller must set ``session.state["org_id"]`` before invoking the agent.
+
+    Args:
+        tool_context: Injected by ADK.
+    """
+    raw = tool_context.state.get("org_id")
+    if raw is None:
+        raise ValueError("org_id not set in session state")
+    return UUID(str(raw))
+
+
+def serialize(obj: Any) -> Any:
+    """Convert a SQLModel instance (or collection) to a JSON-safe dict.
+
+    Recursively handles UUIDs, datetimes, dates, lists, and nested models.
+
+    Args:
+        obj: A SQLModel row, dict, list, or primitive.
+    """
+    if obj is None:
+        return None
+    if isinstance(obj, (str, int, float, bool)):
+        return obj
+    if isinstance(obj, UUID):
+        return str(obj)
+    if isinstance(obj, datetime.datetime):
+        return obj.isoformat()
+    if isinstance(obj, datetime.date):
+        return obj.isoformat()
+    if isinstance(obj, dict):
+        return {k: serialize(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [serialize(item) for item in obj]
+    # SQLModel / Pydantic BaseModel
+    if hasattr(obj, "model_dump"):
+        return serialize(obj.model_dump())
+    return str(obj)

interloper_agent/prompts.py

@@ -0,0 +1,113 @@
+"""Instruction strings for all agents."""
+
+ROOT_INSTRUCTION = """\
+You are Interloper Assistant, an AI agent for the Interloper data asset platform.
+
+You help users understand their data catalog, asset dependencies, operational health,
+and can take actions like triggering runs or backfills.
+
+Route questions to the appropriate specialist:
+
+- **CatalogAgent** — "What sources do we have?", "Show me the schema for X",
+  "Which assets have a spend field?", "Compare Facebook and TikTok schemas"
+- **LineageAgent** — "What depends on X?", "What's upstream of Y?",
+  "If Google Ads breaks, what's affected?", "Show cross-source dependencies"
+- **OperationsAgent** — "Did last night's runs succeed?", "Which assets failed?",
+  "What's the cron schedule?", "Show backfill progress"
+- **AnalyticsAgent** — "How often do runs fail?", "Any partition gaps?",
+  "When was the last successful run for each job?"
+- **ActionAgent** — "Re-run the Facebook job for yesterday", "Backfill March 1-15",
+  "Disable the campaign_matcher job"
+
+Always be concise and present data in a structured way. Use tables when listing
+multiple items. When referencing assets, use the qualified key (source_key.asset_key).
+"""
+
+CATALOG_INSTRUCTION = """\
+You are the Catalog specialist for Interloper.
+
+You help users discover sources, understand asset schemas, find fields across the
+catalog, and compare schemas between different assets.
+
+When presenting schemas:
+- List field names, types, and descriptions clearly
+- Note which fields are required vs optional
+- Highlight partition columns when present
+
+When listing sources:
+- Include their asset count and key
+- Note which are configured (have DB instances) vs only in the catalog
+
+When comparing schemas:
+- Show shared fields, fields unique to each, and any type mismatches
+"""
+
+LINEAGE_INSTRUCTION = """\
+You are the Lineage specialist for Interloper.
+
+You help users understand data dependencies between assets — which assets feed
+into which, cross-source dependency edges, and impact analysis.
+
+When showing lineage:
+- Present it as a clear chain or tree
+- Use qualified keys (source_key.asset_key)
+- Distinguish required vs optional dependencies
+
+For impact analysis:
+- Emphasize the total number of affected downstream assets
+- Group by source for clarity
+- Note which assets are leaves (final outputs)
+"""
+
+OPERATIONS_INSTRUCTION = """\
+You are the Operations specialist for Interloper.
+
+You help users understand run health, recent failures, job schedules, and backfill
+progress.
+
+When showing failures:
+- Always include the error message from events
+- Note which specific asset within the run failed
+- Summarize patterns (e.g., "3 of last 5 runs failed")
+
+When showing job status:
+- Decode cron expressions to human-readable schedules
+- Show last_run_at and next_run_at
+- Compute success rate from recent runs
+
+Present timestamps in a human-readable format relative to now when useful
+(e.g., "2 hours ago").
+"""
+
+ANALYTICS_INSTRUCTION = """\
+You are the Analytics specialist for Interloper.
+
+You help users understand trends in run performance, partition coverage gaps,
+and data freshness across their jobs.
+
+When presenting statistics:
+- Include counts, percentages, and averages
+- Flag concerning trends (rising failure rates, growing gaps)
+- Compare against recent history for context
+
+For partition coverage:
+- Clearly list missing dates in a range
+- Calculate the coverage percentage
+
+For freshness:
+- Flag any job that hasn't run successfully in over 24 hours
+"""
+
+ACTION_INSTRUCTION = """\
+You are the Action specialist for Interloper.
+
+You can trigger runs, start backfills, and toggle jobs or assets on or off.
+
+Important rules:
+- Always confirm what you are about to do before executing
+- Describe the action clearly: which job, which dates, what will change
+- After executing, report the result including the created run/backfill ID
+- For backfills, confirm the date range and concurrency settings
+
+Never execute destructive actions without explicit user confirmation.
+"""

interloper_agent/tools/actions.py

@@ -0,0 +1,133 @@
+"""Action tools — trigger runs, backfills, and toggle state."""
+
+from __future__ import annotations
+
+import datetime
+from typing import Any
+from uuid import UUID
+
+from google.adk.tools.tool_context import ToolContext
+
+from interloper_agent.context import get_org_id, get_store, serialize
+
+
+def trigger_run(
+    job_id: str,
+    partition_date: str | None = None,
+    tool_context: ToolContext = None,  # type: ignore[assignment]
+) -> dict[str, Any]:
+    """Queue a single run for a job.
+
+    Args:
+        job_id: UUID of the job to run.
+        partition_date: Optional partition date in ISO format (YYYY-MM-DD).
+    """
+    try:
+        org_id = get_org_id(tool_context)
+        store = get_store()
+        pd = datetime.date.fromisoformat(partition_date) if partition_date else None
+        run = store.create_run(org_id, job_id=UUID(job_id), partition_date=pd)
+        return {
+            "status": "success",
+            "message": "Run queued successfully",
+            "run": serialize(run),
+        }
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def trigger_backfill(
+    job_id: str,
+    start_date: str,
+    end_date: str,
+    concurrency: int = 1,
+    fail_fast: bool = False,
+    tool_context: ToolContext = None,  # type: ignore[assignment]
+) -> dict[str, Any]:
+    """Start a backfill for a job over a date range.
+
+    Args:
+        job_id: UUID of the job.
+        start_date: Start date in ISO format (YYYY-MM-DD).
+        end_date: End date in ISO format (YYYY-MM-DD), inclusive.
+        concurrency: Max number of runs in-flight at once (default 1).
+        fail_fast: If true, cancel remaining runs on first failure (default false).
+    """
+    try:
+        org_id = get_org_id(tool_context)
+        store = get_store()
+        backfill = store.create_backfill(
+            org_id,
+            job_id=UUID(job_id),
+            start_date=datetime.date.fromisoformat(start_date),
+            end_date=datetime.date.fromisoformat(end_date),
+            concurrency=concurrency,
+            fail_fast=fail_fast,
+        )
+        return {
+            "status": "success",
+            "message": "Backfill created successfully",
+            "backfill": serialize(backfill),
+        }
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def toggle_job(
+    job_id: str,
+    enabled: bool,
+    tool_context: ToolContext = None,  # type: ignore[assignment]
+) -> dict[str, Any]:
+    """Enable or disable a scheduled job.
+
+    Args:
+        job_id: UUID of the job.
+        enabled: True to enable, false to disable.
+    """
+    try:
+        store = get_store()
+        jid = UUID(job_id)
+        job = store.get_job(jid)
+        updated = store.update_job(
+            jid,
+            name=job.name,
+            cron=job.cron,
+            source_ids=[s.id for s in job.sources if s.id] if job.sources else None,
+            asset_ids=[a.id for a in job.assets if a.id] if job.assets else None,
+            tags=job.tags,
+            enabled=enabled,
+            partitioned=job.partitioned,
+            backfill_days=job.backfill_days,
+        )
+        action = "enabled" if enabled else "disabled"
+        return {
+            "status": "success",
+            "message": f"Job '{job.name}' {action}",
+            "job": serialize(updated),
+        }
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def toggle_asset(
+    asset_id: str,
+    materializable: bool,
+    tool_context: ToolContext = None,  # type: ignore[assignment]
+) -> dict[str, Any]:
+    """Enable or disable materialization for an asset.
+
+    Args:
+        asset_id: UUID of the asset.
+        materializable: True to enable materialization, false to disable.
+    """
+    try:
+        store = get_store()
+        updated = store.update_asset(UUID(asset_id), materializable=materializable)
+        action = "enabled" if materializable else "disabled"
+        return {
+            "status": "success",
+            "message": f"Asset '{updated.key}' materialization {action}",
+            "asset": serialize(updated),
+        }
+    except Exception as e:
+        return {"status": "error", "error": str(e)}

interloper_agent/tools/analytics.py

@@ -0,0 +1,158 @@
+"""Analytics tools — run statistics, partition coverage, and data freshness."""
+
+from __future__ import annotations
+
+import datetime
+from typing import Any
+from uuid import UUID
+
+from google.adk.tools.tool_context import ToolContext
+
+from interloper_agent.context import get_org_id, get_store, serialize
+
+
+def run_history_summary(
+    job_id: str | None = None,
+    days: int = 7,
+    tool_context: ToolContext = None,  # type: ignore[assignment]
+) -> dict[str, Any]:
+    """Summarize run statistics over a period.
+
+    Args:
+        job_id: Filter to a specific job UUID (optional, all jobs if omitted).
+        days: Number of days to look back (default 7).
+
+    Returns aggregate counts (total, success, failed, canceled),
+    success rate, and average duration.
+    """
+    try:
+        org_id = get_org_id(tool_context)
+        store = get_store()
+        runs = store.list_runs(
+            org_id,
+            job_id=UUID(job_id) if job_id else None,
+            limit=500,
+        )
+
+        cutoff = datetime.datetime.now(tz=datetime.timezone.utc) - datetime.timedelta(days=days)
+        recent = [r for r in runs if r.created_at and r.created_at >= cutoff]
+
+        total = len(recent)
+        by_status: dict[str, int] = {}
+        durations: list[float] = []
+        for r in recent:
+            by_status[r.status] = by_status.get(r.status, 0) + 1
+            if r.started_at and r.completed_at:
+                durations.append((r.completed_at - r.started_at).total_seconds())
+
+        success = by_status.get("success", 0)
+        return {
+            "status": "success",
+            "period_days": days,
+            "job_id": job_id,
+            "total_runs": total,
+            "by_status": by_status,
+            "success_rate": round(success / total, 2) if total > 0 else None,
+            "avg_duration_seconds": round(sum(durations) / len(durations), 1) if durations else None,
+        }
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def partition_coverage(
+    job_id: str,
+    start_date: str,
+    end_date: str,
+    tool_context: ToolContext = None,  # type: ignore[assignment]
+) -> dict[str, Any]:
+    """Check partition coverage for a job over a date range.
+
+    Args:
+        job_id: UUID of the job.
+        start_date: Start date in ISO format (YYYY-MM-DD).
+        end_date: End date in ISO format (YYYY-MM-DD), inclusive.
+
+    Returns which dates have successful runs and which are missing.
+    """
+    try:
+        org_id = get_org_id(tool_context)
+        store = get_store()
+        jid = UUID(job_id)
+        runs = store.list_runs(org_id, job_id=jid, limit=1000)
+
+        start = datetime.date.fromisoformat(start_date)
+        end = datetime.date.fromisoformat(end_date)
+
+        # Collect dates with successful runs
+        covered: set[datetime.date] = set()
+        for r in runs:
+            if r.status == "success" and r.partition_date:
+                if start <= r.partition_date <= end:
+                    covered.add(r.partition_date)
+
+        # Build expected date range
+        expected: list[datetime.date] = []
+        current = start
+        while current <= end:
+            expected.append(current)
+            current += datetime.timedelta(days=1)
+
+        missing = sorted(set(expected) - covered)
+        coverage_pct = round(len(covered) / len(expected) * 100, 1) if expected else 100.0
+
+        return {
+            "status": "success",
+            "job_id": job_id,
+            "start_date": start_date,
+            "end_date": end_date,
+            "total_days": len(expected),
+            "covered_days": len(covered),
+            "missing_days": len(missing),
+            "coverage_percent": coverage_pct,
+            "missing_dates": [d.isoformat() for d in missing],
+        }
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def freshness_check(tool_context: ToolContext) -> dict[str, Any]:
+    """Check data freshness for all jobs.
+
+    Returns the last successful run timestamp for each job and flags
+    any that haven't succeeded in over 24 hours.
+    """
+    try:
+        org_id = get_org_id(tool_context)
+        store = get_store()
+        jobs = store.list_jobs(org_id)
+        now = datetime.datetime.now(tz=datetime.timezone.utc)
+
+        results = []
+        for job in jobs:
+            if not job.enabled:
+                continue
+            job_id = job.id  # type: ignore[assignment]
+            runs = store.list_runs(org_id, job_id=job_id, status="success", limit=1)
+            last_success = runs[0] if runs else None
+
+            hours_since = None
+            if last_success and last_success.completed_at:
+                delta = now - last_success.completed_at
+                hours_since = round(delta.total_seconds() / 3600, 1)
+
+            results.append({
+                "job": serialize(job),
+                "last_success_at": serialize(last_success.completed_at) if last_success else None,
+                "hours_since_success": hours_since,
+                "stale": hours_since is None or hours_since > 24,
+            })
+
+        stale_count = sum(1 for r in results if r["stale"])
+        return {
+            "status": "success",
+            "total_jobs": len(results),
+            "stale_count": stale_count,
+            "jobs": results,
+        }
+    except Exception as e:
+        return {"status": "error", "error": str(e)}

interloper_agent/tools/catalog.py

@@ -0,0 +1,261 @@
+"""Catalog tools — discovery, schema inspection, and field search."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from google.adk.tools.tool_context import ToolContext
+
+from interloper_agent.context import get_catalog, get_org_id, get_store, serialize
+
+
+def list_sources(tool_context: ToolContext) -> dict[str, Any]:
+    """List all sources registered in the organisation.
+
+    Returns each source with its key, name, asset count, and creation date.
+    Also indicates which catalog sources have configured DB instances.
+    """
+    try:
+        org_id = get_org_id(tool_context)
+        store = get_store()
+        catalog = get_catalog()
+
+        db_sources = store.list_sources(org_id)
+        db_by_key: dict[str, Any] = {}
+        for s in db_sources:
+            entry = serialize(s)
+            entry["asset_count"] = len(s.assets) if s.assets else 0
+            db_by_key[s.key] = entry
+
+        # Enrich with catalog metadata
+        results = []
+        for key, defn in catalog.items():
+            if defn.get("kind") != "source":
+                continue
+            item: dict[str, Any] = {
+                "key": key,
+                "name": defn.get("name", key),
+                "description": defn.get("description"),
+                "icon": defn.get("icon"),
+                "catalog_asset_count": len(defn.get("assets", [])),
+                "tags": defn.get("tags", []),
+            }
+            if key in db_by_key:
+                item["configured"] = True
+                item["instance"] = db_by_key[key]
+            else:
+                item["configured"] = False
+            results.append(item)
+
+        return {"status": "success", "sources": results}
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def get_source_detail(source_key: str, tool_context: ToolContext) -> dict[str, Any]:
+    """Get full catalog detail for a source type.
+
+    Args:
+        source_key: The source key (e.g. 'facebook_ads').
+
+    Returns the source definition including config schema, resource types,
+    destination types, and a list of all its assets with their schemas.
+    """
+    try:
+        catalog = get_catalog()
+        defn = catalog.get(source_key)
+        if defn is None or defn.get("kind") != "source":
+            return {"status": "error", "error": f"Source '{source_key}' not found in catalog"}
+        return {"status": "success", "source": defn}
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def get_asset_schema(source_key: str, asset_key: str, tool_context: ToolContext) -> dict[str, Any]:
+    """Get the JSON schema for a specific asset within a source.
+
+    Args:
+        source_key: The source key (e.g. 'facebook_ads').
+        asset_key: The asset key within the source (e.g. 'ad_insights').
+
+    Returns the asset schema with field names, types, and descriptions.
+    """
+    try:
+        catalog = get_catalog()
+        defn = catalog.get(source_key)
+        if defn is None or defn.get("kind") != "source":
+            return {"status": "error", "error": f"Source '{source_key}' not found in catalog"}
+
+        for asset_def in defn.get("assets", []):
+            if asset_def.get("key") == asset_key:
+                schema = asset_def.get("asset_schema")
+                return {
+                    "status": "success",
+                    "source_key": source_key,
+                    "asset_key": asset_key,
+                    "qualified_key": f"{source_key}.{asset_key}",
+                    "schema": schema,
+                    "partitioning": asset_def.get("partitioning"),
+                    "tags": asset_def.get("tags", []),
+                    "requires": asset_def.get("requires", {}),
+                    "optional_requires": asset_def.get("optional_requires", {}),
+                }
+            # Also match by qualified_key
+            if asset_def.get("qualified_key") == f"{source_key}.{asset_key}":
+                schema = asset_def.get("asset_schema")
+                return {
+                    "status": "success",
+                    "source_key": source_key,
+                    "asset_key": asset_key,
+                    "qualified_key": f"{source_key}.{asset_key}",
+                    "schema": schema,
+                    "partitioning": asset_def.get("partitioning"),
+                    "tags": asset_def.get("tags", []),
+                    "requires": asset_def.get("requires", {}),
+                    "optional_requires": asset_def.get("optional_requires", {}),
+                }
+
+        return {"status": "error", "error": f"Asset '{asset_key}' not found in source '{source_key}'"}
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def search_fields(query: str, tool_context: ToolContext) -> dict[str, Any]:
+    """Search for fields across all asset schemas matching a query string.
+
+    Args:
+        query: Substring to search for in field names and descriptions (case-insensitive).
+
+    Returns matching fields grouped by source and asset, with field type and description.
+    """
+    try:
+        catalog = get_catalog()
+        query_lower = query.lower()
+        matches: list[dict[str, Any]] = []
+
+        for key, defn in catalog.items():
+            if defn.get("kind") != "source":
+                continue
+            source_key = key
+            for asset_def in defn.get("assets", []):
+                asset_key = asset_def.get("key", "")
+                schema = asset_def.get("asset_schema")
+                if not schema or "properties" not in schema:
+                    continue
+                for field_name, field_info in schema["properties"].items():
+                    field_desc = field_info.get("description", "")
+                    if query_lower in field_name.lower() or query_lower in field_desc.lower():
+                        matches.append({
+                            "source_key": source_key,
+                            "asset_key": asset_key,
+                            "qualified_key": f"{source_key}.{asset_key}",
+                            "field_name": field_name,
+                            "field_type": _extract_type(field_info),
+                            "description": field_desc,
+                        })
+
+        return {"status": "success", "query": query, "match_count": len(matches), "matches": matches}
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def compare_schemas(
+    source_key_a: str,
+    asset_key_a: str,
+    source_key_b: str,
+    asset_key_b: str,
+    tool_context: ToolContext,
+) -> dict[str, Any]:
+    """Compare the schemas of two assets side by side.
+
+    Args:
+        source_key_a: Source key for the first asset.
+        asset_key_a: Asset key for the first asset.
+        source_key_b: Source key for the second asset.
+        asset_key_b: Asset key for the second asset.
+
+    Returns shared fields, fields unique to each asset, and any type mismatches.
+    """
+    try:
+        schema_a = _get_schema_properties(source_key_a, asset_key_a)
+        schema_b = _get_schema_properties(source_key_b, asset_key_b)
+
+        if isinstance(schema_a, dict) and "error" in schema_a:
+            return {"status": "error", "error": schema_a["error"]}
+        if isinstance(schema_b, dict) and "error" in schema_b:
+            return {"status": "error", "error": schema_b["error"]}
+
+        assert isinstance(schema_a, dict) and isinstance(schema_b, dict)
+        fields_a = set(schema_a.keys())
+        fields_b = set(schema_b.keys())
+
+        shared = fields_a & fields_b
+        only_a = fields_a - fields_b
+        only_b = fields_b - fields_a
+
+        shared_details = []
+        for field in sorted(shared):
+            type_a = _extract_type(schema_a[field])
+            type_b = _extract_type(schema_b[field])
+            shared_details.append({
+                "field": field,
+                "type_a": type_a,
+                "type_b": type_b,
+                "type_match": type_a == type_b,
+            })
+
+        return {
+            "status": "success",
+            "asset_a": f"{source_key_a}.{asset_key_a}",
+            "asset_b": f"{source_key_b}.{asset_key_b}",
+            "shared_count": len(shared),
+            "only_a_count": len(only_a),
+            "only_b_count": len(only_b),
+            "shared_fields": shared_details,
+            "only_in_a": sorted(only_a),
+            "only_in_b": sorted(only_b),
+        }
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def list_destinations(tool_context: ToolContext) -> dict[str, Any]:
+    """List all configured destinations in the organisation.
+
+    Returns each destination with its key, name, config, and resource bindings.
+    """
+    try:
+        org_id = get_org_id(tool_context)
+        store = get_store()
+        destinations = store.list_destinations(org_id)
+        return {"status": "success", "destinations": [serialize(d) for d in destinations]}
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _extract_type(field_info: dict[str, Any]) -> str:
+    """Extract a human-readable type string from a JSON schema field definition."""
+    if "anyOf" in field_info:
+        types = [t.get("type", "unknown") for t in field_info["anyOf"] if t.get("type") != "null"]
+        return types[0] if len(types) == 1 else " | ".join(types) if types else "any"
+    return field_info.get("type", "unknown")
+
+
+def _get_schema_properties(source_key: str, asset_key: str) -> dict[str, Any]:
+    """Retrieve the properties dict from an asset's JSON schema."""
+    catalog = get_catalog()
+    defn = catalog.get(source_key)
+    if defn is None or defn.get("kind") != "source":
+        return {"error": f"Source '{source_key}' not found in catalog"}
+    for asset_def in defn.get("assets", []):
+        if asset_def.get("key") == asset_key:
+            schema = asset_def.get("asset_schema")
+            if not schema or "properties" not in schema:
+                return {"error": f"Asset '{source_key}.{asset_key}' has no schema"}
+            return schema["properties"]
+    return {"error": f"Asset '{asset_key}' not found in source '{source_key}'"}

interloper_agent/tools/lineage.py

@@ -0,0 +1,244 @@
+"""Lineage tools — dependency analysis, impact assessment, and DAG traversal."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+from uuid import UUID
+
+from google.adk.tools.tool_context import ToolContext
+
+from interloper_agent.context import get_org_id, get_store
+
+
+def get_upstream(asset_id: str, tool_context: ToolContext) -> dict[str, Any]:
+    """Get the direct upstream dependencies of an asset.
+
+    Args:
+        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.
+    """
+    try:
+        org_id = get_org_id(tool_context)
+        store = get_store()
+        deps = store.list_dependencies(org_id)
+        target = UUID(asset_id)
+
+        upstream = []
+        for dep in deps:
+            if dep.asset_id == target:
+                asset = store.get_asset(dep.upstream_asset_id)
+                upstream.append({
+                    "upstream_asset_id": str(dep.upstream_asset_id),
+                    "param_name": dep.param_name,
+                    "asset_key": asset.key,
+                    "source_id": str(asset.source_id),
+                })
+
+        return {"status": "success", "asset_id": asset_id, "upstream": upstream}
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def get_downstream(asset_id: str, tool_context: ToolContext) -> dict[str, Any]:
+    """Get the direct downstream dependents of an asset.
+
+    Args:
+        asset_id: UUID of the asset to inspect.
+
+    Returns the list of assets that directly depend on this asset.
+    """
+    try:
+        org_id = get_org_id(tool_context)
+        store = get_store()
+        deps = store.list_dependencies(org_id)
+        target = UUID(asset_id)
+
+        downstream = []
+        for dep in deps:
+            if dep.upstream_asset_id == target:
+                asset = store.get_asset(dep.asset_id)
+                downstream.append({
+                    "asset_id": str(dep.asset_id),
+                    "param_name": dep.param_name,
+                    "asset_key": asset.key,
+                    "source_id": str(asset.source_id),
+                })
+
+        return {"status": "success", "asset_id": asset_id, "downstream": downstream}
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def get_full_lineage(asset_id: str, direction: str = "upstream", tool_context: ToolContext = None) -> dict[str, Any]:  # type: ignore[assignment]
+    """Recursively traverse the full lineage of an asset.
+
+    Args:
+        asset_id: UUID of the asset to start from.
+        direction: Either 'upstream' (ancestors) or 'downstream' (dependents).
+
+    Returns an ordered list of assets in the lineage chain with depth levels.
+    """
+    try:
+        org_id = get_org_id(tool_context)
+        adj, asset_info = _build_adjacency(org_id, direction)
+        target = UUID(asset_id)
+
+        visited: set[UUID] = set()
+        result: list[dict[str, Any]] = []
+        queue: list[tuple[UUID, int]] = [(target, 0)]
+
+        while queue:
+            current, depth = queue.pop(0)
+            if current in visited:
+                continue
+            visited.add(current)
+            if current != target:
+                info = asset_info.get(current, {})
+                result.append({"asset_id": str(current), "depth": depth, **info})
+            for neighbor in adj.get(current, []):
+                if neighbor not in visited:
+                    queue.append((neighbor, depth + 1))
+
+        return {
+            "status": "success",
+            "asset_id": asset_id,
+            "direction": direction,
+            "lineage_count": len(result),
+            "lineage": result,
+        }
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def impact_analysis(asset_id: str, tool_context: ToolContext) -> dict[str, Any]:
+    """Analyze the downstream impact if an asset fails or is disabled.
+
+    Args:
+        asset_id: UUID of the asset to analyze.
+
+    Returns all downstream assets grouped by source, with total affected count.
+    """
+    try:
+        org_id = get_org_id(tool_context)
+        adj, asset_info = _build_adjacency(org_id, "downstream")
+        target = UUID(asset_id)
+
+        visited: set[UUID] = set()
+        affected: list[dict[str, Any]] = []
+        queue: list[tuple[UUID, int]] = [(target, 0)]
+
+        while queue:
+            current, depth = queue.pop(0)
+            if current in visited:
+                continue
+            visited.add(current)
+            if current != target:
+                info = asset_info.get(current, {})
+                affected.append({"asset_id": str(current), "depth": depth, **info})
+            for neighbor in adj.get(current, []):
+                if neighbor not in visited:
+                    queue.append((neighbor, depth + 1))
+
+        # Group by source
+        by_source: dict[str, list[dict[str, Any]]] = defaultdict(list)
+        for item in affected:
+            by_source[item.get("source_key", "unknown")].append(item)
+
+        return {
+            "status": "success",
+            "asset_id": asset_id,
+            "total_affected": len(affected),
+            "by_source": {k: v for k, v in by_source.items()},
+        }
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def cross_source_dependencies(tool_context: ToolContext) -> dict[str, Any]:
+    """List all dependency edges that cross source boundaries.
+
+    Returns edges where the upstream and downstream assets belong to
+    different sources.
+    """
+    try:
+        org_id = get_org_id(tool_context)
+        store = get_store()
+        deps = store.list_dependencies(org_id)
+        assets = store.list_assets(org_id)
+
+        asset_source: dict[UUID, UUID | None] = {}
+        asset_info: dict[UUID, dict[str, str]] = {}
+        for a in assets:
+            if not a.id:
+                continue
+            asset_source[a.id] = a.source_id
+            asset_info[a.id] = {"asset_key": a.key, "source_id": str(a.source_id) if a.source_id else ""}
+
+        cross_deps = []
+        for dep in deps:
+            src_down = asset_source.get(dep.asset_id)
+            src_up = asset_source.get(dep.upstream_asset_id)
+            if src_down and src_up and src_down != src_up:
+                cross_deps.append({
+                    "downstream_asset_id": str(dep.asset_id),
+                    "downstream": asset_info.get(dep.asset_id, {}),
+                    "upstream_asset_id": str(dep.upstream_asset_id),
+                    "upstream": asset_info.get(dep.upstream_asset_id, {}),
+                    "param_name": dep.param_name,
+                })
+
+        return {"status": "success", "cross_source_count": len(cross_deps), "dependencies": cross_deps}
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _build_adjacency(
+    org_id: UUID,
+    direction: str,
+) -> tuple[dict[UUID, list[UUID]], dict[UUID, dict[str, Any]]]:
+    """Build an adjacency map and asset info lookup from all dependencies.
+
+    Args:
+        org_id: Organisation scope.
+        direction: 'upstream' builds child→parents; 'downstream' builds parent→children.
+
+    Returns:
+        (adjacency_map, asset_info_map)
+    """
+    store = get_store()
+    deps = store.list_dependencies(org_id)
+    assets = store.list_assets(org_id)
+
+    asset_info: dict[UUID, dict[str, Any]] = {}
+    source_keys: dict[UUID, str] = {}
+    for a in assets:
+        if not a.id:
+            continue
+        asset_info[a.id] = {"asset_key": a.key, "source_id": str(a.source_id) if a.source_id else ""}
+        if a.source and a.source_id:
+            source_keys[a.source_id] = a.source.key
+
+    # Add source_key to asset_info
+    for uid, info in asset_info.items():
+        sid_str = info["source_id"]
+        if sid_str:
+            info["source_key"] = source_keys.get(UUID(sid_str), "unknown")
+        else:
+            info["source_key"] = ""
+
+    adj: dict[UUID, list[UUID]] = defaultdict(list)
+    for dep in deps:
+        if direction == "upstream":
+            adj[dep.asset_id].append(dep.upstream_asset_id)
+        else:
+            adj[dep.upstream_asset_id].append(dep.asset_id)
+
+    return adj, asset_info

interloper_agent/tools/operations.py

@@ -0,0 +1,171 @@
+"""Operations tools — run health, job status, failures, and backfill monitoring."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from google.adk.tools.tool_context import ToolContext
+
+from interloper_agent.context import get_org_id, get_store, serialize
+
+
+def list_recent_runs(
+    job_id: str | None = None,
+    status: str | None = None,
+    limit: int = 20,
+    tool_context: ToolContext = None,  # type: ignore[assignment]
+) -> dict[str, Any]:
+    """List recent runs with optional filters.
+
+    Args:
+        job_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:
+        org_id = get_org_id(tool_context)
+        store = get_store()
+        runs = store.list_runs(
+            org_id,
+            job_id=UUID(job_id) if job_id else None,
+            status=status,
+            limit=limit,
+        )
+        return {"status": "success", "count": len(runs), "runs": [serialize(r) for r in runs]}
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def get_run_detail(run_id: str, tool_context: ToolContext) -> dict[str, Any]:
+    """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:
+        store = get_store()
+        rid = UUID(run_id)
+        run = store.get_run(rid)
+        events = store.list_events(run_id=rid)
+        asset_execs = store.list_asset_executions(rid)
+
+        return {
+            "status": "success",
+            "run": serialize(run),
+            "events": [serialize(e) for e in events],
+            "asset_executions": asset_execs,
+        }
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def list_failures(limit: int = 20, tool_context: ToolContext = None) -> dict[str, Any]:  # type: ignore[assignment]
+    """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:
+        org_id = get_org_id(tool_context)
+        store = get_store()
+        failed_runs = store.list_runs(org_id, status="failed", limit=limit)
+
+        results = []
+        for run in failed_runs:
+            run_id = run.id  # type: ignore[assignment]
+            events = store.list_events(run_id=run_id)
+            errors = [
+                {"asset_key": e.asset_key, "error": e.error, "timestamp": serialize(e.timestamp)}
+                for e in events
+                if e.error
+            ]
+            results.append({
+                "run": serialize(run),
+                "errors": errors,
+            })
+
+        return {"status": "success", "count": len(results), "failures": results}
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def get_job_health(job_id: str, tool_context: ToolContext) -> dict[str, Any]:
+    """Get health summary for a job: metadata, recent success/failure rate.
+
+    Args:
+        job_id: UUID of the job to inspect.
+
+    Returns job metadata plus success rate computed from the last 20 runs.
+    """
+    try:
+        org_id = get_org_id(tool_context)
+        store = get_store()
+        jid = UUID(job_id)
+        job = store.get_job(jid)
+        runs = store.list_runs(org_id, job_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 {
+            "status": "success",
+            "job": serialize(job),
+            "health": {
+                "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 {"status": "error", "error": str(e)}
+
+
+def list_jobs(tool_context: ToolContext) -> dict[str, Any]:
+    """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:
+        org_id = get_org_id(tool_context)
+        store = get_store()
+        jobs = store.list_jobs(org_id)
+        return {"status": "success", "count": len(jobs), "jobs": [serialize(j) for j in jobs]}
+    except Exception as e:
+        return {"status": "error", "error": str(e)}
+
+
+def list_backfills(active_only: bool = True, tool_context: ToolContext = None) -> dict[str, Any]:  # type: ignore[assignment]
+    """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:
+        org_id = get_org_id(tool_context)
+        store = get_store()
+        if active_only:
+            backfills = store.list_active_backfills(org_id)
+        else:
+            backfills = store.list_backfills(org_id)
+        return {"status": "success", "count": len(backfills), "backfills": [serialize(b) for b in backfills]}
+    except Exception as e:
+        return {"status": "error", "error": str(e)}

interloper_agent-0.2.0.dist-info/METADATA

@@ -0,0 +1,16 @@
+Metadata-Version: 2.3
+Name: interloper-agent
+Version: 0.2.0
+Summary: Interloper AI agent powered by Google ADK
+Author: Guillaume Onfroy
+Author-email: Guillaume Onfroy <guillaume@digitlcloud.com>
+Requires-Dist: interloper-core
+Requires-Dist: interloper-db
+Requires-Dist: interloper-assets
+Requires-Dist: google-adk>=1.0.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# interloper-agent
+
+Interloper AI agent powered by [Google ADK](https://google.github.io/adk-docs/).

interloper_agent-0.2.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+interloper_agent/__init__.py,sha256=Toi-D_RUs3W5-TjHwWQgUNVFdlXseGa1fSlHOrEOI_Y,158
+interloper_agent/agent.py,sha256=wnySEoZh3MxUS6UzCMq0b5Fg4JgMP3yylieMhkPNQXE,2740
+interloper_agent/context.py,sha256=WP-_I9uHR4LGM1q8YWr3rzKUJrcUsS81P0_4fhEuCNA,2927
+interloper_agent/prompts.py,sha256=hy35kpi9huU5PGUDx4f2bODL7lc0W05IDwpLt-k0Kn4,4027
+interloper_agent/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+interloper_agent/tools/actions.py,sha256=woGQtTFcbQv3FSqf-RwicbXAcSJFiwQBZBunjDGXp88,4184
+interloper_agent/tools/analytics.py,sha256=tdjCscOefrcJrjq4ehbRSULNhV7DLGg4Mowjw9LW4VY,5401
+interloper_agent/tools/catalog.py,sha256=PEjfUbnNPPteIHeXy-Zq760FPtWtu8kMMWqMGAioYcg,10355
+interloper_agent/tools/lineage.py,sha256=5flThYz5Ar1zlF98A2CtTRIgTjU_3VtU3o_l85pwRJQ,8476
+interloper_agent/tools/operations.py,sha256=8rfeNExTe9LLh-qj812EAdVKqlUZ8HAPuIjDBJcL-0I,5913
+interloper_agent-0.2.0.dist-info/WHEEL,sha256=f5fWSvWsg5Knq5GWa6t1nJIug0Tqo69GqAWD_9LbBKw,81
+interloper_agent-0.2.0.dist-info/METADATA,sha256=T78qnLme1EUVxeoRI_6fKXDTw7hUolWxAFrXiJhA-M8,487
+interloper_agent-0.2.0.dist-info/RECORD,,

interloper_agent-0.2.0.dist-info/WHEEL

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