Metadata-Version: 2.5
Name: querygate
Version: 0.1.0.dev0
Summary: The governance, human-in-the-loop, and audit layer that text-to-SQL is missing. LangGraph-orchestrated; Vanna as the default engine.
Author: Shamik Saha
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: audit,governance,human-in-the-loop,langgraph,nl2sql,text-to-sql,vanna
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Database
Requires-Python: >=3.11
Requires-Dist: langgraph>=0.2
Requires-Dist: psycopg[binary]>=3.1
Requires-Dist: pydantic>=2
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: eval
Requires-Dist: sqlglot>=25; extra == 'eval'
Provides-Extra: frontend
Requires-Dist: gradio>=4; extra == 'frontend'
Provides-Extra: vanna
Requires-Dist: vanna<3,>=2.0; extra == 'vanna'
Description-Content-Type: text/markdown

# querygate

**Vanna answers questions with your database. querygate makes sure a human said yes first — and can prove it.**

*The moat: airgapped · evaluated · audited · human-gated.*

Text-to-SQL engines (Vanna, WrenAI, DB-GPT) generate SQL well. None of them answer the
questions an enterprise deployment actually asks:

- *Who approved this query before it ran?*
- *What did the model try before it got it right?*
- *How do we pause for a human — and resume cleanly when they answer an hour later?*
- *Can this run fully airgapped?*

querygate is that missing layer. It is **not** another engine — it orchestrates one
(Vanna by default, swappable by config) inside a checkpointed LangGraph flow with two
human gates:

```
rewrite → ambiguity check ⟲ → schema retrieval → SQL generation → validation ⟲
        (clarify interrupt)                                    (retry loop)
                          → human approval → execute
                          (approve interrupt)
```

1. **Clarify before generating** — catches ambiguous intent ("recent" — by which date?).
2. **Approve before executing** — a human sees the SQL before it touches the database.
   Mandatory by default; relaxable only by explicit config.

## What ships in the box
- **The graph** (`core/graph.py`) — checkpointed, interrupt-driven, resumable across slow
  human responses. The retry loop is invisible to the UI; only real interrupts surface.
- **Pluggable everything** (`core/deps.py`) — `SchemaProvider`, `GenerationModel`,
  `DBConnector`, `AuditSink` protocols. A deployment is one YAML file, zero code.
- **Audit trail** — every generation attempt (not just the final one), every clarification,
  every approval decision, as JSONL. Approved pairs are training-ready for a future
  self-learning loop by design.
- **Safety preflight** — refuses to start against a database role without
  `default_transaction_read_only=on`, `statement_timeout`, and an idle timeout.
  Row limits enforced on execution.
- **Offline eval harness** — frozen gold sets, execution-accuracy scoring (result-set
  comparison), optional LLM-jury rubric tier that supplements — never replaces — it.
- **Airgap-first** — local models via Ollama, pgvector on your existing Postgres,
  no runtime downloads, no external calls. See `docs/airgap-deployment.md`.

## Status
`0.1.0.dev` — scaffold. See the roadmap in `docs/charter.md`.

## License
Apache-2.0
