lagaam-ai/lagaam

missing partition filter or an accidental cross join doesn't cost you a bill —
it costs everyone else their queries. Lagaam is an MCP server that sits
between your AI agents and your lakehouse (Trino and Apache Pinot): every
query is schema-grounded, priced from the engine's own plan before it runs,
checked against a budget, and audited — and the bad one is refused before it
runs, with a fix the agent can act on.
Real session, real Trino, nothing mocked — reproduce it with
uv run --project server python examples/demo.py.
Real session, real Pinot 1.5.1 realtime table, nothing mocked — reproduce it
with uv run --project server python examples/demopinot.py.
## The problem
Agents write syntactically-valid, catastrophic SQL, and on a shared cluster
the damage isn't theirs alone. A missing partition filter turns into a full
scan that ties up every worker; an accidental cross join fills worker memory
while everyone else's queries wait behind it; a retry loop runs it again. A
SELECT drags 40 columns into a context window that needed 2. The usual
fix is to not give agents database access at all.
Lagaam gives them access with reins on:
Cost is a quotation, not a bill. Every query is priced from the
engine's own plan before execution — EXPLAIN (TYPE IO) for the bytes it
would scan, EXPLAIN (TYPE LOGICAL) for the widest row count any operator
would build (the number a cross join blows and a LIMIT cannot hide).
Over budget → blocked, with the number and the fix.
Un-estimable means no. No table statistics, a self-join that breaks
the estimate, a passthrough the planner can't see — the gate fails safe
instead of hoping.
Read-only, enforced in the AST. Single SELECT only. No DDL/DML, no
multi-statement injection, no SELECT , no table-function passthrough,
and a LIMIT is injected when missing. Validated SQL is re-rendered, so
what runs is exactly what was checked.
Agents ground themselves. listcatalogs and describetable return
exact names, types, and row estimates — scoped to the agent's table grant,
so the agent never learns names it isn't allowed to touch.
Results are verified before they're trusted. Zero rows, truncated
pages, all-NULL columns — the agent gets a warning with a next action, not
a silently misleading answer.
Every call is audited. One JSONL line per tool call: who, what,
allowed or denied, and why.
## Doesn't Trino already limit this?
It limits a query once it is running. Lagaam refuses it before it starts.
Keep both.
| | Acts | What the agent sees | Catches a cross join that reads little |
| query.max-scan-physical-bytes | during execution: terminated once the bytes are scanned | a query failure | no — it counts bytes read, not rows built |
| query.max-execution-time | during execution: terminated after the time is spent | a query failure | only after it has held the cluster that long |
| Resource groups (hardPhysicalDataScanLimit, softMemoryLimit, …) | on the next query: new queries queue once the group is over its share | its later queries wait | no — the running query continues |
| Lagaam | before execution, from EXPLAIN | a refusal with the number and the fix | yes — it prices the rows the widest step would build |