askql 0.2.0__tar.gz

askql-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 askql authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

askql-0.2.0/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: askql
+Version: 0.2.0
+Summary: Safe natural-language-to-SQL: validated, read-only queries across many SQL engines.
+Author: askql maintainers
+License: MIT
+Project-URL: Homepage, https://github.com/TestAutomationArchitect/askql
+Project-URL: Source, https://github.com/TestAutomationArchitect/askql
+Project-URL: Changelog, https://github.com/TestAutomationArchitect/askql/blob/main/CHANGELOG.md
+Keywords: sql,nl2sql,text-to-sql,llm,guardrails,read-only,database
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqlglot>=23.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
+Provides-Extra: oracle
+Requires-Dist: python-oracledb>=2.0; extra == "oracle"
+Provides-Extra: mssql
+Requires-Dist: pymssql>=2.2; extra == "mssql"
+Provides-Extra: jdbc
+Requires-Dist: JayDeBeApi>=1.2; extra == "jdbc"
+Requires-Dist: JPype1>=1.5; extra == "jdbc"
+Provides-Extra: llm
+Requires-Dist: anthropic>=0.40; extra == "llm"
+Provides-Extra: llm-aws
+Requires-Dist: anthropic[bedrock]>=0.40; extra == "llm-aws"
+Provides-Extra: llm-vertex
+Requires-Dist: anthropic[vertex]>=0.40; extra == "llm-vertex"
+Provides-Extra: llm-openai
+Requires-Dist: openai>=1.40; extra == "llm-openai"
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers>=2.2; extra == "embeddings"
+Provides-Extra: api
+Requires-Dist: fastapi>=0.110; extra == "api"
+Requires-Dist: uvicorn[standard]>=0.27; extra == "api"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Dynamic: license-file
+
+# askql — Safe Natural-Language → SQL
+
+Translate plain-English questions into **validated, read-only SELECT** queries and run them
+against a relational database. Designed for **QA / dev environments only**, with
+defense-in-depth guardrails so an AI agent can never modify data or leak PII.
+
+> ⚠️ **Non-production by design.** This system executes only read-only `SELECT`
+> statements through a least-privilege DB user. Do not point it at a production
+> database without the Phase-3 approval workflow (see [ARCHITECTURE.md](ARCHITECTURE.md)).
+
+---
+
+## How it works
+
+```
+question ─▶ compress (pick ~10 relevant tables) ─▶ LLM writes SQL
+        ─▶ validate (AST guardrails)  ─▶ execute (read-only, rollback, timeout)
+        ─▶ markdown/CSV + audit log
+```
+
+Five defense layers: **AST validation → read-only DB user → connection hygiene →
+output caps → audit trail**. See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design and
+the security hardening applied on top of the source playbook.
+
+> **Credentials:** use whatever your org gives you — the tool runs with any user. A read-only
+> user is a recommended nice-to-have (defense in depth), not a requirement; if the connected
+> user can write, you get a one-line advisory, never a block.
+
+---
+
+## Quick start
+
+```bash
+# 1. Install (Python 3.11+; default driver is PostgreSQL)
+python -m venv .venv && .venv\Scripts\activate     # Windows PowerShell
+pip install -e ".[postgres,dev]"
+
+# 2. Configure
+copy .env.example .env          # then edit credentials
+#   edit config/settings.yaml   # set dialect + schemas
+
+# 3. Build the metadata pipeline (one command)
+python scripts/scrape_schema.py --schemas public --build-graph
+
+# 4. Ask a question (the orchestrator runs compress→validate→execute)
+askql ask "show me the 10 newest active accounts"
+
+# …or drive the steps manually:
+python scripts/compress_metadata.py --question "active accounts" --graph docs/schema-graph.json
+python scripts/validate_sql.py build/query.sql --max-rows 100
+python scripts/execute_sql.py build/query.sql --limit 50
+```
+
+No database handy? Everything except `execute` runs fully offline, and the executor
+has an **offline render mode** (`--rows-json`) used by the test suite.
+
+Verify your setup any time with the built-in health check:
+
+```bash
+python scripts/doctor.py        # config, credentials, transport, live connectivity, graph
+```
+
+---
+
+## Run in Docker (zero local install)
+
+The image bundles Python **and a JRE**, so the universal JDBC transport works without
+installing Java or native drivers on your machine. Mount your config, `.env`, and vendor JDBC
+jars at runtime:
+
+```bash
+docker build -t askql .
+
+# health check
+docker run --rm --env-file .env \
+  -v "$PWD/config:/app/config" -v "$PWD/jdbc-drivers:/app/jdbc-drivers" askql doctor
+
+# or via compose
+docker compose run --rm askql doctor
+docker compose run --rm askql execute build/query.sql --limit 50
+```
+
+Vendor JDBC jars aren't baked into the image (licensing) — drop them in `jdbc-drivers/` and
+they're mounted in. This is the "usable by all" path: one image, any database engine/version.
+
+---
+
+## REST API (connectivity-as-a-service)
+
+Run askql as a service so clients (a web UI, a Slack bot, scripts, other teams) hold **no**
+drivers, JVM, or credentials — they just call HTTP. The service applies the same validator,
+RBAC, read-only execution, and audit.
+
+```bash
+pip install -e ".[api,postgres,jdbc]"
+export T2S_API_KEYS="devkey:alice@corp"       # identity drives RBAC; omit + ALLOW_OPEN for dev
+askql-api                                         # or: uvicorn askql.api:app --port 8000
+#   or containerized:  docker compose up api
+```
+
+| Method & path | Auth | Purpose |
+|---------------|------|---------|
+| `GET /health` | public | liveness |
+| `GET /api/v1/databases` | public | registry names (no creds/conn strings) |
+| `POST /api/v1/validate` | required | `{sql, database?}` → guardrail check |
+| `POST /api/v1/compress` | required | `{question}` → focused schema slice |
+| `POST /api/v1/query` | required | `{sql, database?, max_rows?, format?}` → execute read-only |
+| `POST /api/v1/ask` | required | `{question, database?}` → compress→LLM→validate→retry→execute (needs `ANTHROPIC_API_KEY`) |
+
+```bash
+curl -s -X POST localhost:8000/api/v1/query -H "X-API-Key: devkey" \
+  -H "Content-Type: application/json" \
+  -d '{"sql":"SELECT first_name, salary FROM HR.EMPLOYEES WHERE ROWNUM <= 3","database":"oracle-prod"}'
+# → {"ok":true,"columns":["FIRST_NAME","SALARY"],"rows":[["Steven",24000], ...],"latency_ms":104}
+```
+
+Auth: `T2S_API_KEYS="key1:alice@corp,key2:bob@corp"` maps a key → identity (→ role in
+`config/access-control.yaml`). Writing endpoints refuse to run unless keys are set (or
+`T2S_API_ALLOW_OPEN=true` for local dev). A non-SELECT returns `400` before any DB work.
+
+### Choosing the model (provider-agnostic / BYOM)
+
+`/ask` (and `askql ask`) generates SQL through a pluggable provider — **you bring your own
+model.** The safety pipeline is identical regardless of provider; only `T2S_LLM_PROVIDER`
+changes. With nothing configured, generation falls back to the **BYO-LLM / IDE lane** (your
+Copilot / Claude Code agent does it — no backend model, no key).
+
+| `T2S_LLM_PROVIDER` | What it uses | Config |
+|--------------------|--------------|--------|
+| `anthropic` (auto) | Anthropic API | `ANTHROPIC_API_KEY` · `pip install '.[llm]'` |
+| `bedrock` | Claude on **AWS** | AWS creds/role · `'.[llm-aws]'` · `T2S_LLM_MODEL=anthropic.claude-…` |
+| `vertex` | Claude on **GCP** | GCP creds · `'.[llm-vertex]'` |
+| `openai` | OpenAI GPT | `OPENAI_API_KEY` · `'.[llm-openai]'` |
+| `azure-openai` | Azure OpenAI | `AZURE_OPENAI_API_KEY/_ENDPOINT/OPENAI_API_VERSION` · `'.[llm-openai]'` |
+| `openai-compatible` | **any** self-hosted / OSS (vLLM, Ollama, LM Studio, OpenRouter, GitHub Models) | `T2S_LLM_BASE_URL=…` + `T2S_LLM_MODEL=…` · `'.[llm-openai]'` |
+| `custom` | your own gateway | `T2S_LLM_FACTORY=module:callable` |
+| _unset / `none`_ | **BYO-LLM** — IDE agent (Copilot/Claude Code) | nothing |
+
+> **Copilot note:** Copilot has no server-side completions API, so it can't power the `/ask`
+> *service* — but it *is* the model in the **IDE lane** (the agent runs the scripts/skill with
+> its own model). For a token-based API in the GitHub/MS ecosystem, use Azure OpenAI or
+> "GitHub Models" via the `openai-compatible` provider.
+
+---
+
+## Use as a library
+
+`askql` is a clean, typed, importable package (`py.typed`) — build it into your own app. The
+public API is everything in `askql.__all__`; heavy/optional deps (DB drivers, LLM SDKs,
+FastAPI) load lazily, so `import askql` is light.
+
+```python
+from askql import validate, compress, execute_sql_text, ask, Settings, load_graph
+
+s = Settings(dialect="postgres", max_rows=100)
+
+# 1) Guardrail check (pure, no DB)
+r = validate("SELECT id, name FROM app.users LIMIT 10", settings=s)
+assert r.ok, r.errors
+
+# 2) Pick relevant tables for a question
+slice_ = compress(load_graph("schema-graph.json"), "active users this week", max_tables=8)
+
+# 3) Full NL->SQL (compress -> LLM -> validate -> retry -> execute), provider via env
+result = ask("how many active users this week", settings=s)   # needs an LLM provider configured
+```
+
+Everything is config-injectable (pass `Settings` / `DatabaseEntry` / a custom `SqlGenerator`) —
+no checked-out repo required. For pip-installed use, set `T2S_HOME` (config/data root) and/or
+`T2S_DATA_DIR` (writable dir for the audit log + caches) so nothing is written next to the
+installed package. Packaging/publishing details: [SHIPPING.md](SHIPPING.md).
+
+## Repository map
+
+| Path | What it is |
+|------|------------|
+| [src/askql/](src/askql/) | The library: validator, compressor, executor, drivers, scraper |
+| [scripts/](scripts/) | Thin CLI wrappers (the commands the agent/humans call) |
+| [config/](config/) | `settings.yaml`, `sensitive-columns.yaml`, `databases.yaml` |
+| [docs/domain-rules.md](docs/domain-rules.md) | Business logic hints the LLM reads |
+| [tests/](tests/) | Offline unit tests (validator / compressor / graph) |
+| [.claude/](.claude/) | Claude Code skill + permission settings |
+| [CLAUDE.md](CLAUDE.md) | Operating instructions for the AI agent |
+| [QUICKSTART.md](QUICKSTART.md) | Install + first run in your org (≈15 min) |
+| [SHIPPING.md](SHIPPING.md) | How to package, ship, and install (wheel / index / Docker) |
+| [PB/](PB/) | The original source playbook (reference) |
+
+---
+
+## Safety rules (non-negotiable)
+
+- Only `SELECT` (incl. `UNION`/`INTERSECT`/`EXCEPT`). No DDL/DML, no procedural code.
+- No `SELECT *` — explicit columns only (`COUNT(*)` is fine).
+- A row limit is **required** and capped at `max_rows`.
+- No system schemas, no sensitive columns (SSN, PASSWORD, …), no dangerous functions.
+- Every execution rolls back, times out, and is audited.
+
+See [CLAUDE.md](CLAUDE.md) for the agent workflow and [tests/](tests/) for the enforced behavior.

askql-0.2.0/README.md

@@ -0,0 +1,198 @@
+# askql — Safe Natural-Language → SQL
+
+Translate plain-English questions into **validated, read-only SELECT** queries and run them
+against a relational database. Designed for **QA / dev environments only**, with
+defense-in-depth guardrails so an AI agent can never modify data or leak PII.
+
+> ⚠️ **Non-production by design.** This system executes only read-only `SELECT`
+> statements through a least-privilege DB user. Do not point it at a production
+> database without the Phase-3 approval workflow (see [ARCHITECTURE.md](ARCHITECTURE.md)).
+
+---
+
+## How it works
+
+```
+question ─▶ compress (pick ~10 relevant tables) ─▶ LLM writes SQL
+        ─▶ validate (AST guardrails)  ─▶ execute (read-only, rollback, timeout)
+        ─▶ markdown/CSV + audit log
+```
+
+Five defense layers: **AST validation → read-only DB user → connection hygiene →
+output caps → audit trail**. See [ARCHITECTURE.md](ARCHITECTURE.md) for the full design and
+the security hardening applied on top of the source playbook.
+
+> **Credentials:** use whatever your org gives you — the tool runs with any user. A read-only
+> user is a recommended nice-to-have (defense in depth), not a requirement; if the connected
+> user can write, you get a one-line advisory, never a block.
+
+---
+
+## Quick start
+
+```bash
+# 1. Install (Python 3.11+; default driver is PostgreSQL)
+python -m venv .venv && .venv\Scripts\activate     # Windows PowerShell
+pip install -e ".[postgres,dev]"
+
+# 2. Configure
+copy .env.example .env          # then edit credentials
+#   edit config/settings.yaml   # set dialect + schemas
+
+# 3. Build the metadata pipeline (one command)
+python scripts/scrape_schema.py --schemas public --build-graph
+
+# 4. Ask a question (the orchestrator runs compress→validate→execute)
+askql ask "show me the 10 newest active accounts"
+
+# …or drive the steps manually:
+python scripts/compress_metadata.py --question "active accounts" --graph docs/schema-graph.json
+python scripts/validate_sql.py build/query.sql --max-rows 100
+python scripts/execute_sql.py build/query.sql --limit 50
+```
+
+No database handy? Everything except `execute` runs fully offline, and the executor
+has an **offline render mode** (`--rows-json`) used by the test suite.
+
+Verify your setup any time with the built-in health check:
+
+```bash
+python scripts/doctor.py        # config, credentials, transport, live connectivity, graph
+```
+
+---
+
+## Run in Docker (zero local install)
+
+The image bundles Python **and a JRE**, so the universal JDBC transport works without
+installing Java or native drivers on your machine. Mount your config, `.env`, and vendor JDBC
+jars at runtime:
+
+```bash
+docker build -t askql .
+
+# health check
+docker run --rm --env-file .env \
+  -v "$PWD/config:/app/config" -v "$PWD/jdbc-drivers:/app/jdbc-drivers" askql doctor
+
+# or via compose
+docker compose run --rm askql doctor
+docker compose run --rm askql execute build/query.sql --limit 50
+```
+
+Vendor JDBC jars aren't baked into the image (licensing) — drop them in `jdbc-drivers/` and
+they're mounted in. This is the "usable by all" path: one image, any database engine/version.
+
+---
+
+## REST API (connectivity-as-a-service)
+
+Run askql as a service so clients (a web UI, a Slack bot, scripts, other teams) hold **no**
+drivers, JVM, or credentials — they just call HTTP. The service applies the same validator,
+RBAC, read-only execution, and audit.
+
+```bash
+pip install -e ".[api,postgres,jdbc]"
+export T2S_API_KEYS="devkey:alice@corp"       # identity drives RBAC; omit + ALLOW_OPEN for dev
+askql-api                                         # or: uvicorn askql.api:app --port 8000
+#   or containerized:  docker compose up api
+```
+
+| Method & path | Auth | Purpose |
+|---------------|------|---------|
+| `GET /health` | public | liveness |
+| `GET /api/v1/databases` | public | registry names (no creds/conn strings) |
+| `POST /api/v1/validate` | required | `{sql, database?}` → guardrail check |
+| `POST /api/v1/compress` | required | `{question}` → focused schema slice |
+| `POST /api/v1/query` | required | `{sql, database?, max_rows?, format?}` → execute read-only |
+| `POST /api/v1/ask` | required | `{question, database?}` → compress→LLM→validate→retry→execute (needs `ANTHROPIC_API_KEY`) |
+
+```bash
+curl -s -X POST localhost:8000/api/v1/query -H "X-API-Key: devkey" \
+  -H "Content-Type: application/json" \
+  -d '{"sql":"SELECT first_name, salary FROM HR.EMPLOYEES WHERE ROWNUM <= 3","database":"oracle-prod"}'
+# → {"ok":true,"columns":["FIRST_NAME","SALARY"],"rows":[["Steven",24000], ...],"latency_ms":104}
+```
+
+Auth: `T2S_API_KEYS="key1:alice@corp,key2:bob@corp"` maps a key → identity (→ role in
+`config/access-control.yaml`). Writing endpoints refuse to run unless keys are set (or
+`T2S_API_ALLOW_OPEN=true` for local dev). A non-SELECT returns `400` before any DB work.
+
+### Choosing the model (provider-agnostic / BYOM)
+
+`/ask` (and `askql ask`) generates SQL through a pluggable provider — **you bring your own
+model.** The safety pipeline is identical regardless of provider; only `T2S_LLM_PROVIDER`
+changes. With nothing configured, generation falls back to the **BYO-LLM / IDE lane** (your
+Copilot / Claude Code agent does it — no backend model, no key).
+
+| `T2S_LLM_PROVIDER` | What it uses | Config |
+|--------------------|--------------|--------|
+| `anthropic` (auto) | Anthropic API | `ANTHROPIC_API_KEY` · `pip install '.[llm]'` |
+| `bedrock` | Claude on **AWS** | AWS creds/role · `'.[llm-aws]'` · `T2S_LLM_MODEL=anthropic.claude-…` |
+| `vertex` | Claude on **GCP** | GCP creds · `'.[llm-vertex]'` |
+| `openai` | OpenAI GPT | `OPENAI_API_KEY` · `'.[llm-openai]'` |
+| `azure-openai` | Azure OpenAI | `AZURE_OPENAI_API_KEY/_ENDPOINT/OPENAI_API_VERSION` · `'.[llm-openai]'` |
+| `openai-compatible` | **any** self-hosted / OSS (vLLM, Ollama, LM Studio, OpenRouter, GitHub Models) | `T2S_LLM_BASE_URL=…` + `T2S_LLM_MODEL=…` · `'.[llm-openai]'` |
+| `custom` | your own gateway | `T2S_LLM_FACTORY=module:callable` |
+| _unset / `none`_ | **BYO-LLM** — IDE agent (Copilot/Claude Code) | nothing |
+
+> **Copilot note:** Copilot has no server-side completions API, so it can't power the `/ask`
+> *service* — but it *is* the model in the **IDE lane** (the agent runs the scripts/skill with
+> its own model). For a token-based API in the GitHub/MS ecosystem, use Azure OpenAI or
+> "GitHub Models" via the `openai-compatible` provider.
+
+---
+
+## Use as a library
+
+`askql` is a clean, typed, importable package (`py.typed`) — build it into your own app. The
+public API is everything in `askql.__all__`; heavy/optional deps (DB drivers, LLM SDKs,
+FastAPI) load lazily, so `import askql` is light.
+
+```python
+from askql import validate, compress, execute_sql_text, ask, Settings, load_graph
+
+s = Settings(dialect="postgres", max_rows=100)
+
+# 1) Guardrail check (pure, no DB)
+r = validate("SELECT id, name FROM app.users LIMIT 10", settings=s)
+assert r.ok, r.errors
+
+# 2) Pick relevant tables for a question
+slice_ = compress(load_graph("schema-graph.json"), "active users this week", max_tables=8)
+
+# 3) Full NL->SQL (compress -> LLM -> validate -> retry -> execute), provider via env
+result = ask("how many active users this week", settings=s)   # needs an LLM provider configured
+```
+
+Everything is config-injectable (pass `Settings` / `DatabaseEntry` / a custom `SqlGenerator`) —
+no checked-out repo required. For pip-installed use, set `T2S_HOME` (config/data root) and/or
+`T2S_DATA_DIR` (writable dir for the audit log + caches) so nothing is written next to the
+installed package. Packaging/publishing details: [SHIPPING.md](SHIPPING.md).
+
+## Repository map
+
+| Path | What it is |
+|------|------------|
+| [src/askql/](src/askql/) | The library: validator, compressor, executor, drivers, scraper |
+| [scripts/](scripts/) | Thin CLI wrappers (the commands the agent/humans call) |
+| [config/](config/) | `settings.yaml`, `sensitive-columns.yaml`, `databases.yaml` |
+| [docs/domain-rules.md](docs/domain-rules.md) | Business logic hints the LLM reads |
+| [tests/](tests/) | Offline unit tests (validator / compressor / graph) |
+| [.claude/](.claude/) | Claude Code skill + permission settings |
+| [CLAUDE.md](CLAUDE.md) | Operating instructions for the AI agent |
+| [QUICKSTART.md](QUICKSTART.md) | Install + first run in your org (≈15 min) |
+| [SHIPPING.md](SHIPPING.md) | How to package, ship, and install (wheel / index / Docker) |
+| [PB/](PB/) | The original source playbook (reference) |
+
+---
+
+## Safety rules (non-negotiable)
+
+- Only `SELECT` (incl. `UNION`/`INTERSECT`/`EXCEPT`). No DDL/DML, no procedural code.
+- No `SELECT *` — explicit columns only (`COUNT(*)` is fine).
+- A row limit is **required** and capped at `max_rows`.
+- No system schemas, no sensitive columns (SSN, PASSWORD, …), no dangerous functions.
+- Every execution rolls back, times out, and is audited.
+
+See [CLAUDE.md](CLAUDE.md) for the agent workflow and [tests/](tests/) for the enforced behavior.

askql-0.2.0/pyproject.toml

@@ -0,0 +1,82 @@
+[project]
+name = "askql"
+version = "0.2.0"
+description = "Safe natural-language-to-SQL: validated, read-only queries across many SQL engines."
+requires-python = ">=3.11"
+readme = "README.md"
+dependencies = ["sqlglot>=23.0", "pyyaml>=6.0"]
+keywords = ["sql", "nl2sql", "text-to-sql", "llm", "guardrails", "read-only", "database"]
+authors = [{ name = "askql maintainers" }]
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Database",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+[project.urls]
+# TODO: point these at your repo/docs when published.
+Homepage = "https://github.com/TestAutomationArchitect/askql"
+Source = "https://github.com/TestAutomationArchitect/askql"
+Changelog = "https://github.com/TestAutomationArchitect/askql/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+postgres = ["psycopg[binary]>=3.1"]
+oracle = ["python-oracledb>=2.0"]
+mssql = ["pymssql>=2.2"]
+jdbc = ["JayDeBeApi>=1.2", "JPype1>=1.5"]   # universal transport (needs a JVM on host)
+# NL->SQL generation providers (pick what your org uses; the pipeline is identical):
+llm = ["anthropic>=0.40"]                    # Anthropic API
+llm-aws = ["anthropic[bedrock]>=0.40"]       # Claude on Amazon Bedrock
+llm-vertex = ["anthropic[vertex]>=0.40"]     # Claude on Google Vertex
+llm-openai = ["openai>=1.40"]                # OpenAI / Azure OpenAI / any OpenAI-compatible (BYOM)
+embeddings = ["sentence-transformers>=2.2"]  # local semantic table retrieval (or use openai embeddings)
+api = ["fastapi>=0.110", "uvicorn[standard]>=0.27"]
+dev = ["pytest>=8.0", "ruff>=0.5", "mypy>=1.10", "httpx>=0.27"]
+
+[project.scripts]
+# Single orchestrator entrypoint (compress -> generate -> validate -> execute).
+askql = "askql.cli:main"
+askql-api = "askql.api:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+askql = ["py.typed"]   # ship type-hint marker so consumers get types (PEP 561)
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "integration: requires a live database connection (skipped by default)",
+]
+
+[tool.ruff]
+line-length = 100
+src = ["src", "scripts", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "S"]   # incl. flake8-bandit (S) for security smells
+# S101: asserts are fine. S110: try/except/pass is a deliberate, documented pattern in the
+# audit/advisory/cleanup paths (those must never raise and break a query).
+ignore = ["S101", "S110"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S", "E501"]   # tests may embed long CSV/SQL fixtures
+
+[tool.mypy]
+python_version = "3.11"
+mypy_path = "src"
+packages = ["askql"]
+ignore_missing_imports = true
+explicit_package_bases = true

askql-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

askql-0.2.0/src/askql/__init__.py

@@ -0,0 +1,103 @@
+"""askql — safe natural-language-to-SQL with defense-in-depth guardrails.
+
+A library teams can build on: turn questions into validated, read-only SELECTs and run them
+safely against many SQL engines. Read-only by design; the validator is the single source of
+truth for what is safe to execute.
+
+Public API (stable surface — internals may change between minor versions):
+
+    from askql import validate, compress, ask, execute_sql_text, Settings
+
+Quick start (library use)::
+
+    from askql import validate, Settings
+    r = validate("SELECT id FROM s.t LIMIT 10", settings=Settings(dialect="postgres"))
+    assert r.ok
+
+Optional features install via extras: `askql[postgres]`, `[jdbc]`, `[llm]`, `[llm-openai]`,
+`[api]`. Heavy/optional deps (DB drivers, LLM SDKs, FastAPI, JPype) are imported lazily, so
+`import askql` is light and never fails on a missing optional dependency.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+# Config / models
+# Schema graph + per-question compression
+from .compressor import compress
+from .config import (
+    DatabaseEntry,
+    Settings,
+    data_dir,
+    load_database,
+    load_env_file,
+    load_sensitive_patterns,
+    load_settings,
+)
+
+# Connectivity (transport-agnostic)
+from .drivers import DatabaseDriver, get_driver
+
+# Execution (read-only)
+from .executor import (
+    ExecutionResult,
+    execute_sql,
+    execute_sql_text,
+    format_csv,
+    format_markdown,
+    sanitize_error,
+)
+
+# NL->SQL generation (provider-agnostic / BYOM)
+from .generate import GeneratorUnavailable, SqlGenerator, get_generator
+
+# Orchestration
+from .orchestrator import ask
+
+# RBAC (optional, opt-in by identity)
+from .policy import AccessDenied, Policy, get_policy, resolve_current_user
+from .schema_graph import build_graph, load_graph, write_graph
+
+# Validation (the safety core)
+from .validator import ValidationResult, validate
+
+__all__ = [
+    "__version__",
+    # config
+    "Settings",
+    "DatabaseEntry",
+    "load_settings",
+    "load_database",
+    "load_env_file",
+    "load_sensitive_patterns",
+    "data_dir",
+    # validation
+    "validate",
+    "ValidationResult",
+    # schema
+    "compress",
+    "build_graph",
+    "load_graph",
+    "write_graph",
+    # execution
+    "execute_sql",
+    "execute_sql_text",
+    "ExecutionResult",
+    "format_markdown",
+    "format_csv",
+    "sanitize_error",
+    # connectivity
+    "get_driver",
+    "DatabaseDriver",
+    # rbac
+    "get_policy",
+    "Policy",
+    "AccessDenied",
+    "resolve_current_user",
+    # generation
+    "ask",
+    "get_generator",
+    "SqlGenerator",
+    "GeneratorUnavailable",
+]