GroundedQL: a semantic compiler for natural-language Postgres analytics

I just released GroundedQL 0.3.0, an open-source semantic compiler for reliable natural-language analytics over Postgres.

The problem

Most text-to-SQL systems allow a language model to generate executable SQL directly. When a query fails, it can be difficult to determine whether the problem came from language interpretation, schema selection, joins, SQL generation, or safety.

The approach

GroundedQL separates interpretation from execution:

1. Model → proposes lightweight semantic hints such as datasets, filters, dimensions, and metrics
2. Compiler → resolves those hints against an allowlisted schema.yaml, builds and validates a typed QueryPlan, then compiles parameterized SQL

The model interprets language. The compiler owns execution.

Filter values become bind parameters rather than string-concatenated SQL.

Quick start

pip install groundedql
groundedql init --db "postgresql://user:pass@host/db"

from sqlalchemy import create_engine
from groundedql.agent import QueryAgent

agent = QueryAgent(
    engine=create_engine("postgresql+psycopg2://user:pass@host/db"),
    schema_path="config/schema.yaml",
    llm="mistral",
)

result = agent.ask("Which customers placed the most orders last year?")

print(result["rows"])
print(result["sql"])

Optional extras:

pip install "groundedql[memory]"
pip install "groundedql[openai]"

What GroundedQL provides

• Schema allowlisting through schema.yaml
• A typed intermediate representation called QueryPlan
• Deterministic validation and SQL compilation
• Parameterized Postgres SQL through SQLAlchemy
• Support for Mistral, Ollama, and OpenAI-compatible providers
• Inspectable plans that can be tested independently of the model

GroundedQL is licensed under Apache License 2.0. Contributions, feedback, and real-world testing are welcome.

Links

• Documentation: https://certifore.github.io/groundedql_docs/
• GitHub: https://github.com/Certifore/groundedql
• PyPI: https://pypi.org/project/groundedql/
• Release: https://github.com/Certifore/groundedql/releases/tag/v0.3.0
• Discussions: https://github.com/Certifore/groundedql/discussions

If you are building natural-language analytics over Postgres and want the model out of the SQL driver's seat, I would love your feedback.