levain-sdk 0.1.0__py3-none-any.whl

levain_sdk/__init__.py

@@ -0,0 +1,21 @@
+"""Levain Recipe SDK — helpers for recipe node functions.
+
+Zero dependency on levain. Levain depends on the SDK,
+not the other way around.
+"""
+
+from .errors import (
+    AgentError,
+    GitHubAPIError,
+    KneadError,
+    OperationTimeoutError,
+)
+from .shell import run_checks
+
+__all__ = [
+    "AgentError",
+    "GitHubAPIError",
+    "KneadError",
+    "OperationTimeoutError",
+    "run_checks",
+]

levain_sdk/_mcp.py

@@ -0,0 +1,30 @@
+"""Shared helper for FastMCP → ClaudeAgentOptions config.
+
+Every platform MCP server (``levain-build``, ``knead-review``)
+needs the same dance: pull the FastMCP
+instance's private ``_mcp_server`` attribute and wrap it in the
+``McpSdkServerConfig`` shape the SDK expects.  Kept central so a
+FastMCP API change is patched in one place, not three.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def sdk_mcp_config(mcp_instance: Any, server_name: str) -> dict[str, Any]:
+    """Return an in-process MCP server config for ``ClaudeAgentOptions``.
+
+    ``_mcp_server`` is a private attribute of FastMCP; re-verify
+    it exists when bumping the ``fastmcp`` pin (tested against
+    3.1.1).  A missing attribute means the FastMCP internals
+    moved and the caller needs to track the new shape.
+    """
+    server = getattr(mcp_instance, "_mcp_server", None)
+    if server is None or not hasattr(server, "run"):
+        raise RuntimeError(
+            f"FastMCP internal API changed — _mcp_server no longer "
+            f"exists or changed type (server={server_name!r}).  Pin "
+            f"fastmcp to the version this was tested against."
+        )
+    return {"type": "sdk", "name": server_name, "instance": server}

levain_sdk/agents_tools/__init__.py

@@ -0,0 +1,20 @@
+"""Agent-to-agent calling tools (the ``levain-agents`` MCP).
+
+The ``call_agent`` tool lets an agent delegate a task to one of the
+workspace's other agents. The tool only *signals* the request; the
+recipe's worker-side ``CallAgent`` node performs the dispatch via
+the harness A2A machinery (:mod:`levain.agent.harness.a2a`), so the
+untrusted sandbox never reaches dispatch directly.
+
+Lives in the customer SDK (moved from ``platform_sdk`` so it works on
+the customer image — the managed Levain assistant is the first
+consumer there, and A2A is a customer-facing capability anyway). The
+worker still gates who may actually be called: dispatch authorizes
+from the caller run's own context, never from the sandbox's claims.
+"""
+
+# Env var the harness injects per turn with the JSON list of agents
+# the Levain agent may call (base64). Read by the recipe's Respond
+# node to render the choices into the prompt — discovery is
+# prompt-side, not a tool round-trip.
+ENV_CALLABLE_AGENTS = "LEVAIN_CALLABLE_AGENTS_B64"

levain_sdk/agents_tools/mcp.py

@@ -0,0 +1,119 @@
+"""FastMCP server exposing the agent-to-agent ``call_agent`` tool.
+
+Runs in-process inside the sandbox via stdio. Lets an agent
+delegate a task to one of the workspace's other agents.
+
+This is a *signal* tool, not an RPC client: calling it only records
+the requested ``(agent, request)`` in a signal file. The Levain
+recipe's ``Respond`` node reads that signal after the agent's SDK
+session returns (:func:`consume_call`), routes the graph to a
+``CallAgent`` node, and that node — running in the **trusted
+worker** — performs the dispatch via the harness A2A machinery and
+feeds the result back into the next ``Respond`` turn. The untrusted
+sandbox never reaches dispatch directly and never supplies the
+caller's identity; the worker authorizes from the caller run's own
+context. The tool call itself only records a module-level signal
+that the node wrapper consumes after the agent returns.
+
+Discovery is prompt-side: the worker injects the callable-agents
+list into the ``Respond`` prompt, so there's no ``list_agents``
+tool here.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from fastmcp import FastMCP
+
+from levain_sdk._mcp import sdk_mcp_config
+
+log = logging.getLogger("knead")
+
+mcp = FastMCP("levain-agents")
+
+
+@dataclass
+class _AgentCall:
+    """A delegation the Levain agent requested this turn."""
+
+    slug: str
+    request: str
+
+
+# File-backed signal, written by ``call_agent`` and reset by ``init``
+# on each Respond dispatch so a stale request can't leak across
+# turns. Single-slot: the tool's contract is "call it, then wrap up",
+# so at most one delegation per session (the recipe loops for more).
+# A file rather than a module global because the server doesn't
+# always share a process with the node that reads the signal: the
+# Claude engine runs it in-process, but the Hermes engine runs it as
+# a stdio subprocess (``levain_sdk.mcp_stdio``). Same pattern as the
+# ``levain-memory`` queue.
+_SIGNAL_PATH = Path("/tmp/levain-agents/call.json")
+
+
+def init(repo_root: str = "", branch: str = "", iteration: int = 0) -> None:
+    """Reset the pending-call signal for this Respond dispatch."""
+    del repo_root, branch, iteration
+    _SIGNAL_PATH.unlink(missing_ok=True)
+
+
+def consume_call() -> _AgentCall | None:
+    """Return the captured delegation, if any, and clear it."""
+    try:
+        raw = _SIGNAL_PATH.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return None
+    _SIGNAL_PATH.unlink(missing_ok=True)
+    try:
+        record = json.loads(raw)
+    except ValueError:
+        log.warning("CALL_AGENT  unparseable signal file; ignoring")
+        return None
+    return _AgentCall(
+        slug=str(record.get("slug") or ""),
+        request=str(record.get("request") or ""),
+    )
+
+
+@mcp.tool
+async def call_agent(agent: str, request: str) -> dict[str, Any]:
+    """Hand a task to one of the workspace's other agents.
+
+    Use the ``agent`` slug from the list of available agents in your
+    instructions. ``request`` is what you want that agent to do, in
+    plain language — it's delivered as the agent's prompt.
+
+    Calling this **ends your current turn**: the agent runs and you
+    are re-invoked with its result, which you then use to answer.
+    The agent may take several minutes depending on the task, so
+    close your turn with a short note telling the user what you
+    handed off and that the answer is coming — don't also answer
+    the question yourself.
+    Call it only when an available agent clearly fits the task; do
+    not invent a slug.
+    """
+    slug = (agent or "").strip()
+    record = {"slug": slug, "request": (request or "").strip()}
+    _SIGNAL_PATH.parent.mkdir(parents=True, exist_ok=True)
+    _SIGNAL_PATH.write_text(json.dumps(record), encoding="utf-8")
+    log.info("CALL_AGENT  delegation requested (agent=%r)", slug)
+    return {
+        "ok": True,
+        "message": (
+            f"Delegating to {slug!r}. Stop here — you'll be re-invoked "
+            "with the agent's result, which can take several minutes. "
+            "End your turn with a one-line heads-up that you've handed "
+            "this off; don't answer the question yourself."
+        ),
+    }
+
+
+def create_agents_mcp_server() -> dict[str, Any]:
+    """Return an in-process MCP server config for ClaudeAgentOptions."""
+    return sdk_mcp_config(mcp, "levain-agents")

levain_sdk/app_data/__init__.py

@@ -0,0 +1 @@
+"""Synced platform data — workspace-scoped query tools for agents."""

levain_sdk/app_data/mcp.py

@@ -0,0 +1,225 @@
+"""FastMCP server exposing synced platform-app data to agents.
+
+A recipe opts in via ``@mcp_servers ["levain-app-data"]``. The harness injects,
+on the attached platform-app integrations' ``metadata.app_data``, a **direct
+ClickHouse connection** for this run: the workspace's readonly CH account
+(``agent_user_<ws>``) plus a short-lived workspace JWT used as its password.
+ClickHouse validates that JWT via its ``levain_agent_auth`` callback and applies
+the account's row policy, so queries are workspace-scoped **at the database** —
+the agent sees only its own workspace's rows, over a read-only, capped account.
+
+Tables cover the connected apps: Stripe (charges, subscriptions, invoices),
+Shopify (orders, checkouts, products), app events, and daily ads campaign
+metrics. ``list_app_tables`` returns the authoritative schema.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+from typing import Any
+
+from fastmcp import FastMCP
+
+from .._mcp import sdk_mcp_config
+from ..integrations import load_attached
+from .query import (
+    AppDataUnavailable,
+    QueryError,
+    build_sql,
+    probe_coverage,
+    run_query,
+)
+
+log = logging.getLogger(__name__)
+
+mcp = FastMCP("levain-app-data")
+
+# ClickHouse connection + shipped table manifest for this run.
+_conn: dict[str, Any] = {}
+_tables: dict[str, Any] = {}
+# Row count + time span per table, probed once per run (see ``_coverage``).
+_coverage_cache: dict[str, dict[str, Any]] | None = None
+_coverage_lock = asyncio.Lock()
+
+
+def init(
+    repo_root: str,
+    branch: str = "",
+    iteration: int = 0,
+) -> None:
+    """Locate the ClickHouse connection from attached integrations."""
+    global _conn, _tables, _coverage_cache
+    _conn = {}
+    _tables = {}
+    _coverage_cache = None
+    for integ in load_attached():
+        app_data = (integ.get("metadata") or {}).get("app_data") or {}
+        if app_data.get("ch_host") and app_data.get("ch_token"):
+            _conn = {
+                "ch_host": app_data["ch_host"],
+                "ch_port": app_data.get("ch_port", 8123),
+                "ch_database": app_data.get("ch_database", "default"),
+                "ch_user": app_data["ch_user"],
+                "ch_token": app_data["ch_token"],
+                "ch_distributed": bool(app_data.get("ch_distributed")),
+            }
+            _tables = app_data.get("tables") or {}
+            return
+    # Fallback for platform recipes / tests that inject a connection directly.
+    host = os.environ.get("LEVAIN_APP_DATA_CH_HOST", "")
+    if host:
+        _conn = {
+            "ch_host": host,
+            "ch_port": int(os.environ.get("LEVAIN_APP_DATA_CH_PORT", "8123")),
+            "ch_database": os.environ.get("LEVAIN_APP_DATA_CH_DB", "default"),
+            "ch_user": os.environ.get("LEVAIN_APP_DATA_CH_USER", ""),
+            "ch_token": os.environ.get("LEVAIN_APP_DATA_CH_TOKEN", ""),
+            "ch_distributed": os.environ.get("LEVAIN_APP_DATA_CH_DIST") == "1",
+        }
+        raw = os.environ.get("LEVAIN_APP_DATA_TABLES", "")
+        _tables = json.loads(raw) if raw else {}
+
+
+def _require_conn() -> None:
+    if not _conn:
+        raise RuntimeError(
+            "app-data is not available on this run — connect a platform "
+            "app (Stripe, Shopify, Google Ads, Meta Ads) and attach it to "
+            "this agent"
+        )
+
+
+async def _coverage() -> dict[str, dict[str, Any]]:
+    """Cached per-table row count and time span for this run."""
+    global _coverage_cache
+    async with _coverage_lock:
+        if _coverage_cache is None:
+            _coverage_cache = await probe_coverage(_conn, _tables)
+    return _coverage_cache
+
+
+@mcp.tool()
+async def list_app_tables() -> dict[str, Any]:
+    """Describe the queryable synced-data tables, columns, and coverage.
+
+    Call this first to learn table names, columns, and each table's time
+    column before using ``query_app_data``. Each table also carries its
+    ``row_count`` and the ``first_at``/``last_at`` timestamps it actually
+    holds — pick a time window inside that span instead of guessing one, and
+    skip tables whose ``row_count`` is 0.
+    """
+    _require_conn()
+    coverage = await _coverage()
+    tables = {
+        name: {**spec, **coverage[name]} if name in coverage else spec
+        for name, spec in _tables.items()
+    }
+    return {"tables": tables}
+
+
+@mcp.tool()
+async def query_app_data(
+    table: str,
+    columns: list[str] | None = None,
+    filters: list[dict[str, Any]] | None = None,
+    aggregates: list[dict[str, Any]] | None = None,
+    group_by: list[str] | None = None,
+    order_by: list[dict[str, Any]] | None = None,
+    since: str | None = None,
+    until: str | None = None,
+    limit: int = 100,
+) -> dict[str, Any]:
+    """Query a synced-data table (workspace-scoped, read-only).
+
+    Choose ``since``/``until`` from the coverage ``list_app_tables`` reports
+    for the table, not from an assumed range. A result with ``row_count`` 0
+    carries a ``hint`` with the table's real row count and time span — read
+    it and correct the query, rather than retrying another guess.
+
+    Args:
+        table: one of the tables from ``list_app_tables``.
+        columns: columns to select (omit for all, or rely on aggregates).
+        filters: ``[{"column": ..., "op": "="|"!="|">"|">="|"<"|"<="|"in"|
+            "like", "value": ...}]``.
+        aggregates: ``[{"fn": "count"|"sum"|"avg"|"min"|"max", "column": ...,
+            "alias": ...}]`` — combine with ``group_by`` for rollups.
+        group_by: grouping columns. When set, ``columns`` may list only
+            group-by keys — bare non-grouped columns are dropped (ClickHouse
+            requires every selected column to be a group key or aggregated).
+        order_by: ``[{"column": ..., "desc": true}]``. When ``group_by`` is
+            set, each column must be a group-by key or an aggregate alias.
+        since/until: ISO bounds on the table's time column.
+        limit: max rows (≤1000).
+
+    Example — failed charge volume by week:
+        ``query_app_data(table="stripe_charges",
+        filters=[{"column": "status", "value": "failed"}],
+        aggregates=[{"fn": "count", "alias": "n"},
+        {"fn": "sum", "column": "amount", "alias": "total"}],
+        group_by=["currency"], since="2026-05-01")``
+    """
+    _require_conn()
+    spec = _tables.get(table)
+    if spec is None:
+        return {"error": f"unknown table {table!r}; one of {sorted(_tables)}"}
+    resolved = f"{table}_distributed" if _conn["ch_distributed"] else table
+    try:
+        sql, params = build_sql(
+            spec,
+            resolved,
+            columns=columns or [],
+            filters=filters or [],
+            aggregates=aggregates or [],
+            group_by=group_by or [],
+            order_by=order_by or [],
+            since=since,
+            until=until,
+            limit=limit,
+        )
+    except QueryError as e:
+        # Ship the table's schema with the rejection so the corrected retry
+        # needs no extra ``list_app_tables`` round trip.
+        return {
+            "error": str(e),
+            "table": table,
+            "time_column": spec["time_column"],
+            "columns": spec["columns"],
+        }
+    try:
+        rows = await run_query(_conn, sql, params)
+    except (AppDataUnavailable, QueryError) as e:
+        return {"error": str(e)}
+    if rows:
+        return {"rows": rows, "row_count": len(rows)}
+    # Empty means the filters/window missed, not that the table is empty —
+    # ship what the table actually holds so the retry is corrected in one
+    # step instead of guessing another window.
+    result: dict[str, Any] = {"rows": rows, "row_count": 0}
+    covered = (await _coverage()).get(table)
+    if covered:
+        if covered.get("row_count"):
+            message = (
+                "no rows matched — the filters or time window are off, not "
+                "the table. Correct them from this coverage rather than "
+                "retrying another guess"
+            )
+        else:
+            message = (
+                "this table has nothing synced yet — no filter or window "
+                "change will return rows; try a different table"
+            )
+        result["hint"] = {
+            "message": message,
+            "table": table,
+            "time_column": spec["time_column"],
+            **covered,
+        }
+    return result
+
+
+def create_app_data_mcp_server() -> dict[str, Any]:
+    """Registry factory — see ``levain_sdk.mcp_registry``."""
+    return sdk_mcp_config(mcp, "levain-app-data")