IntentQL: a semantic compiler for natural-language Postgres analytics

I just released IntentQL 0.2.4 - an open-source semantic compiler for natural-language analytics over Postgres.

The problem

Most text-to-SQL systems let the model generate executable SQL directly. When something breaks, it's hard to tell whether the failure was language understanding, schema selection, joins, or safety.

The approach

IntentQL splits the problem:

1. Model -> lightweight semantic hints (dataset, filters, metrics, etc.)
2. Compiler -> resolves hints against an allowlisted schema.yaml, builds a typed QueryPlan, validates it, compiles parameterized SQL

The model interprets language. The compiler owns execution.

Filter values become bind parameters - not string-concatenated SQL.

Quick start

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

from sqlalchemy import create_engine
from intentql.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 "intentql[memory]"
pip install "intentql[openai]"

What you get

• Schema allowlisting (schema.yaml)
• Typed intermediate representation (QueryPlan)
• Deterministic validation and compilation
• Parameterized Postgres SQL via SQLAlchemy
• Mistral, Ollama, and OpenAI-compatible providers

Links

• Documentation: https://certifore.github.io/intentql_docs
• GitHub: https://github.com/Certifore/intentql
• PyPI: https://pypi.org/project/intentql/
• Release: https://github.com/Certifore/intentql/releases/tag/v0.2.4

Licensed under Apache 2.0. Feedback welcome on GitHub Discussions.

If you're building NL analytics on Postgres and want the model out of the SQL driver's seat, I'd love your feedback.