io.github.sinhaKAN-ra/anumana

Read a database's REAL schema — tables/collections, columns/fields, INDEXES, and row counts — so you can write a grounded, cost-aware query BEFORE guessing. Call this FIRST when a user asks for data and you don't already know the schema; it tells you which columns are indexed so your query hits an index, not a full scan. READ-ONLY catalog access — never reads data rows. If the schema can't be read it returns `need_from_user` naming what to ask the user for. Pass target=<name> in a multi-DB setup; combine with list_targets to find which DB has the data.

Explain in plain English HOW a query behaves — two layers: (1) the logical gather order (FROM -> WHERE -> GROUP BY -> HAVING -> SELECT -> ORDER BY -> LIMIT), why 'LIMIT 10' can still be slow; and (2) the actual physical plan the engine chose for THIS query, bottom-up. Call when a user asks why a query is slow or how it runs. Teaching tool. Pass target=<name> in a multi-DB setup.

List the operator's standing enforcement policies — the rules that can BLOCK or WARN on a query regardless of what you intend. Each has a name, scope (which target/engine), condition (risk tier and/or flag), and action (block/warn/allow). preflight_query and suggest_query already apply these and attach the verdict; call this to explain to a user WHY a query was blocked. No policies configured means open by default (nothing blocked).

List the databases Anumana is configured to analyse — each with its name, engine, and whether it's diagnosable. Call this FIRST in a multi-DB setup to see which target holds the data the user asked for, then pass target=<name> to the other tools. In a single-DB setup you can omit target and the one database is used. Never returns connection strings or secrets.

Before running ANY SQL query you (the agent) just wrote, check how costly it will be on the real schema — WITHOUT executing it. Returns a risk tier (cheap/moderate/expensive/dangerous), rows scanned vs returned, scan strategy, and overhead flags (missing index, SELECT *, no LIMIT, N+1 / nested-loop blowup). EXPLAIN only — never runs the query. In a multi-DB setup pass target=<name> (see list_targets). For similarity search use preflight_vector_search; with no DB use preflight_schema_only.

Analyse a query against pasted CREATE TABLE DDL with NO database connection — the zero-trust, offline front door. Call when the user gave you their schema (DDL) but not DB credentials. Catches SELECT *, missing LIMIT, un-indexed filter columns, LIKE '%...', functions on filtered columns. HEURISTIC only (no live counts) and says so. No target needed.

Before running a VECTOR SIMILARITY SEARCH (pgvector: `ORDER BY embedding <-> $1 LIMIT k`, cosine `<=>`, inner-product `<#>`), check its cost WITHOUT running it — for any RAG / semantic-search / nearest-neighbour query you generate. Catches the vector traps a plain SQL check misses: brute-force scan with no HNSW/IVFFlat index (FULL_VECTOR_SCAN), top_k too large (TOP_K_TOO_LARGE), unbounded search (UNBOUNDED_VECTOR_SEARCH), and metadata- filter/ANN recall loss (VECTOR_FILTER_INTERACTION). EXPLAIN only. Pass target=<name> in a multi-DB setup; the target should be a pgvector engine.

Rewrite a slow query into a cheaper, equivalent one and PROVE the improvement by EXPLAIN-ing both and comparing planner cost. Call after a preflight flags a query expensive/dangerous. Returns the rewritten query, what changed, before/after cost, and index suggestions — ONLY suggesting a btree index when the filter is selective enough to help (an HNSW index for a vector target). Includes equivalence caveats. Pass target=<name> in a multi-DB setup.

Grade a query you (the agent) wrote for a user's data request and get told whether to RUN it or REFINE it — the check step of generate->check-> refine. Workflow: (1) describe_schema_tool to learn columns + indexes, (2) write a candidate for the user's intent, (3) call this. Returns `next_action`: 'accept' (cheap/moderate — run it) or 'refine' (expensive/ dangerous — here are the high-severity flags + a VERIFIED cheaper rewrite; fix and call again). You write the SQL; Anumana owns cost truth. Bound your loop to ~3 rounds. Pass target=<name> in a multi-DB setup.