GroundedQL Documentation

Documentation, benchmarks, and guides for GroundedQL.

What is GroundedQL?

GroundedQL is an open-source semantic compiler for natural-language analytics over Postgres. A model proposes semantic hints; deterministic infrastructure resolves those hints against an allowlisted schema, builds a typed QueryPlan, validates it, and compiles parameterized SQL.

The model interprets language. The compiler owns execution.

Building the docs locally

pip install mkdocs-material
mkdocs serve

Then open http://localhost:8000.

Contents

• Getting Started — Install, configure, first query
• Core Concepts — Two-stage pipeline, value index, memory, normalization
• Why a Compiler? — Architecture and trust boundaries
• Benchmarks — Current results, methodology, and limitations
• Open Source — License, governance, and contribution philosophy
• Schema Reference — schema.yaml format and options
• QueryPlan Reference — Plan grammar, operators, rollup, joins
• API Reference — All public symbols and their contracts
• LLM Integration — OpenAI, Gemini, Groq, LangChain, Ollama
• Exceptions — Error types and handling
• Benchmark harnesses — Determinism, hallucination, and injection property tests

Governance

Contributions are proposed through pull requests. Alexander Abakah, the lead maintainer, reviews and merges changes into the official repository and is the only person who publishes official releases and the official groundedql package to PyPI.

License

This documentation project is licensed under the Apache License 2.0.