Metadata-Version: 2.4
Name: groundedql
Version: 0.3.0
Summary: GroundedQL — Intent-driven, deterministic natural language to SQL for Postgres.
Author: Alexander Abakah
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Certifore/groundedql
Project-URL: Documentation, https://certifore.github.io/groundedql_docs
Project-URL: Repository, https://github.com/Certifore/groundedql
Project-URL: Issues, https://github.com/Certifore/groundedql/issues
Keywords: sql,intent,grounded,postgres,sqlalchemy,llm,analytics,natural-language,text-to-sql
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: psycopg2-binary
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml
Provides-Extra: memory
Requires-Dist: chromadb>=0.4; extra == "memory"
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: google
Requires-Dist: google-generativeai>=0.5.0; extra == "google"
Provides-Extra: benchmark
Requires-Dist: langchain-openai>=0.2; extra == "benchmark"
Requires-Dist: langchain-google-genai>=2.0; extra == "benchmark"
Requires-Dist: langchain-community>=0.3; extra == "benchmark"
Requires-Dist: python-dotenv; extra == "benchmark"
Provides-Extra: dev
Requires-Dist: ruff>=0.6.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Requires-Dist: python-dotenv; extra == "dev"
Dynamic: license-file

# GroundedQL

![GroundedQL - Reliable natural-language analytics through deterministic SQL compilation](assets/groundedql-social-preview.png)

Intent-driven, deterministic natural language to SQL for Postgres.  
Instead of letting an LLM generate free-form SQL, the LLM extracts a lightweight **QueryIntent**, and GroundedQL deterministically compiles it into parameterized SQL and executes it safely.

## Install

```bash
pip install groundedql
```

To use the OpenAI SDK adapter shown below:

```bash
pip install "groundedql[openai]"
```

With optional few-shot memory (recommended for production):

```bash
pip install "groundedql[memory]"
```

<details>
<summary>Install from source</summary>

```bash
git clone https://github.com/Certifore/groundedql
cd groundedql
pip install -e ".[dev]"
```
</details>

## Quick Start

### 1. Generate your schema from the database

```bash
groundedql init --db "postgresql://user:pass@host/db"
# → config/schema.yaml  (tables, columns, types, PKs, links — all auto-detected)
```

### 2. Enrich with LLM-generated descriptions (optional, recommended)

```bash
export LLM_API_KEY=sk-...   # works with any OpenAI-compatible provider
groundedql describe --schema config/schema.yaml --db "postgresql://user:pass@host/db"
# → Adds table + column descriptions using sample data for context
```

### 3. Ask questions

```python
from sqlalchemy import create_engine
from openai import OpenAI
from groundedql.agent import QueryAgent

engine = create_engine("postgresql+psycopg2://user:pass@host/db")

agent = QueryAgent(
    engine=engine,
    schema_path="config/schema.yaml",
    llm=OpenAI(api_key="sk-..."),
)

result = agent.ask("how many plumbing issues last year?")
print(result["rows"])
print(result["sql"])
```

### Use Mistral instead of OpenAI

```bash
export MISTRAL_AI=...
# optional
export MISTRAL_MODEL=mistral-small-latest
```

```python
agent = QueryAgent(
    engine=engine,
    schema_path="config/schema.yaml",
    llm="mistral",  # or "mistral:mistral-small-latest"
)
```

### Use a local Ollama model

```bash
export OLLAMA_MODEL=groundedql-gemma4
# optional
export OLLAMA_BASE_URL=http://127.0.0.1:11434
export OLLAMA_NUM_CTX=8192
```

```python
agent = QueryAgent(
    engine=engine,
    schema_path="config/schema.yaml",
    llm="ollama",  # or "ollama:groundedql-gemma4"
)
```

## CLI Reference

| Command | Description |
|---|---|
| `groundedql init --db URL` | Introspect Postgres and generate `schema.yaml` |
| `groundedql describe --schema PATH --db URL` | Enrich schema with LLM-generated descriptions |

Run `groundedql --help` for full options.

## Documentation

Full documentation, benchmarks, and guides are at [certifore.github.io/groundedql_docs](https://certifore.github.io/groundedql_docs) ([source](https://github.com/Certifore/groundedql_docs)).

See [ROADMAP.md](ROADMAP.md) for planned capabilities (lookup, trends, ratios, multi-step NL, and expressiveness goals).

Existing users of the previous package name should read [MIGRATION.md](MIGRATION.md).

## Contributing

Contributions are welcome through pull requests. Please read
[CONTRIBUTING.md](CONTRIBUTING.md) before submitting changes. The lead maintainer reviews
and merges all changes into the official repository and is the only person who publishes
official releases.

## License

GroundedQL is licensed under the [Apache License 2.0](LICENSE).
