Anumana — know what your query will cost, before you run it

The feedback loop your agent is missing

An AI agent writing SQL or a vector search has no idea it just triggered a full-table scan or a brute-force search over every embedding. Anumana is the EXPLAIN-grade check it never had — it never runs the query, and it never fakes a number.

preflight_query

Will this SQL be costly? Risk tier, rows scanned vs returned, scan strategy, overhead flags — without running it.

suggest_query

Grade the agent's candidate against the real planner: accept it, or refine with a verified cheaper rewrite.

explain_query_working

How does it run? The logical order plus the real physical plan, bottom-up, in plain English.

rewrite_query

Make it cheaper — an equivalent rewrite with before/after planner cost, and index suggestions gated on selectivity.

preflight_vector_search

Catches the RAG traps: brute-force ANN scan with no HNSW index, top_k too large, unbounded search.

describe_schema

Reads your real catalog — tables, columns, indexes, row counts — so the agent writes grounded SQL, not guesses.

12 engines, 7 paradigms

An engine qualifies only if it exposes a cost signal readable without running the query. LIVE = proven end-to-end against a real instance. UNTESTED = written & unit-checked offline, promoted one at a time.

Engine	Paradigm	Cost signal	Status
Postgres	Relational	`EXPLAIN JSON`	LIVE
SQLite	Relational (embedded)	`EXPLAIN QUERY PLAN`	LIVE
MySQL / MariaDB	Relational	`EXPLAIN FORMAT=JSON`	UNTESTED
pgvector	Vector / RAG	`EXPLAIN` on ANN	UNTESTED
MongoDB	Document	`queryPlanner`	UNTESTED
DynamoDB	Key-value	rule-based	UNTESTED
FalkorDB	Graph (Cypher)	`GRAPH.EXPLAIN`	UNTESTED
Cassandra / ScyllaDB	Wide-column	rule-based (partition key)	UNTESTED
Amazon Redshift	MPP warehouse	text `EXPLAIN`	UNTESTED
Google BigQuery	Serverless warehouse	dry-run → $ cost	UNTESTED
Snowflake	Cloud warehouse	`EXPLAIN USING JSON`	UNTESTED
ClickHouse	OLAP	`EXPLAIN ESTIMATE`	UNTESTED

BigQuery is special. It bills per byte scanned, and its dry run returns the exact bytes a query would scan — so Anumana reports a real dollar cost before you run it, not a planner abstraction.

Install

Anumana rides inside Claude, Cursor, Windsurf, Codex, Kiro, or any MCP-compatible agent. The user installs it; the agent discovers the tools automatically on connect.

pip install anumana-mcp        # once published to PyPI
# or from source:
git clone https://github.com/sinhaKAN-ra/anumana.git
cd anumana && pip install -e .

Point your agent at it with an mcpServers config block (use a read-only role):

{
  "mcpServers": {
    "anumana": {
      "command": "anumana-mcp",
      "env": { "ANUMANA_DSN": "postgres://readonly@localhost:5432/mydb" }
    }
  }
}

No database handy? Omit ANUMANA_DSN and use preflight_schema_only — it analyses pasted CREATE TABLE DDL with no connection at all.

The one honest rule

Planner cost is unitless — not milliseconds. Anumana never fakes a ~3.2s number. It reports rows scanned, scan strategy, a risk tier, overhead flags, and the cost-delta of a rewrite — all defensible, nothing invented. Every estimate carries an accuracy tier. It never executes your query: EXPLAIN, never EXPLAIN ANALYZE.