Ir al contenido
← Ecosistema

Salida estructurada que no inventa nombres

pg_grammar_guard v0.4.9

Una gramática compilada desde tu catálogo vivo: el modelo no puede nombrar lo que no existe.

Compila una gramática a nivel de token desde el catálogo, para que un modelo restringido no pueda nombrar una tabla, una columna o un valor que no existe; y avisa cuando una gramática que aprobaste dejó de describir tu base. No corregido después: incapaz.

Instalar

CREATE EXTENSION pg_grammar_guard;

En simple

Hace imposible que la IA invente nombres de tablas o columnas que no existen en tu base de datos.

  1. La situación

    Le pides a la IA que arme una consulta sobre tus datos: "muéstrame las facturas de este cliente".

  2. Sin esta pieza

    Inventa una columna "email_direccion" que no existe. La consulta falla, o peor: devuelve nada en silencio y alguien toma una decisión con una pantalla vacía.

  3. Con esta pieza

    La IA solo puede elegir entre los nombres reales de tu base, tomados en vivo. No es que se corrija después: no puede escribir lo que no existe. Y se vigila que esa lista siga al día.

Por qué importa si decides

  • Menos errores de la IA sobre tus datos, y no por confianza sino por construcción
  • Funciona con los motores de IA más usados en la industria
  • Honesto con su límite: hace imposible lo inventado, no garantiza la respuesta correcta
Para el equipo técnico

El problema

Todos creen que la salida estructurada impide que el modelo invente. No lo hace.

Un JSON Schema garantiza que el JSON parsea y que column es un string. No puede garantizar que el string sea una columna que existe, porque un esquema se escribe una vez y tu catálogo cambia en cada migración. El modelo devuelve {"table": "customers", "column": "email_address"}, perfectamente válido, y la consulta falla en runtime, o peor, devuelve nada en silencio.

Una gramática restringe la forma. En general, forma no es verdad. Pero para identificadores la forma ES la verdad, porque el conjunto de nombres válidos está en el catálogo.

Cómo funciona

Compilar, entregar al sampler, vigilar

  1. 01

    grammar_for_json(fields)

    Cada campo: nombre, tipo (enum, integer…), valores (catalog_tables, catalog_columns, catalog_enum) y si es obligatorio. Sale GBNF.

  2. 02

    Correlacionado

    catalog_correlated(tables): las columnas dependen de la tabla elegida. Es más grande que la gramática plana y se mantiene lineal en pares (tabla, columna).

  3. 03

    Dónde corre

    llama.cpp (grammar), y XGrammar, el backend por defecto de vLLM, SGLang, TensorRT-LLM y MLC-LLM, que sigue la misma especificación GBNF. Comprobado: cada gramática del README y un catálogo real compilan en ambos.

  4. 04

    La mitad guardiana

    Una gramática generada el mes pasado contra un esquema migrado la semana pasada sigue restringiendo y sigue pareciendo protección. Desde 0.3.0 esa mitad es pg_living_assertions: watch() guarda la CONSULTA (no la spec) y check_grammar() la reconstruye desde el catálogo vivo cada vez, con la edad de cada veredicto.

SQL

Uso

Restringe un subconjunto, no todo el catálogo: una gramática con todas las tablas de la base vuelve a ser el tool schema gigante que se quería evitar, y crece con cada relación.

psql · pg_grammar_guardsql
CREATE EXTENSION pg_grammar_guard;

SELECT grammar_guard.grammar_for_json(ARRAY[
    ROW('table',  'enum', grammar_guard.catalog_tables(ARRAY['app']), true),
    ROW('column', 'enum', grammar_guard.catalog_columns('app.customers'), true),
    ROW('limit',  'integer', NULL, false)
]::grammar_guard.grammar_field[]);
-- root ::= "{" ws "\"table\"" ws ":" ws f1-table ws "," ... "}"
-- f1-table  ::= "\"app.customers\"" | "\"app.invoices\""
-- f2-column ::= "\"id\"" | "\"tax_id\"" | "\"name\""

-- una vez, cuando estés conforme (toma la CONSULTA, no la spec):
SELECT grammar_guard.watch('answer_v1',
    $$select jsonb_build_array(grammar_guard.catalog_correlated(
               ARRAY['public.invoices', 'public.customers']))$$,
    'shipped 2026-09-03');
-- en CI o desde un monitor:
SELECT grammar_guard.check_grammar('answer_v1');   -- holds | broken | erroring | …

Lo que garantiza

Medido

  • Matriz 11 a 19 verde con make installcheck (medido 2026-09-16); 11 y 12 llegaron con 0.4.1.
  • Las pruebas con un modelo (con gramática y con un control sin ella) y los tamaños de gramática en un catálogo real están en el README del repo.
  • Los arreglos siempre tienen tope: un ( ... )* sin tope es un loop esperando ocurrir. Truncar es mucho menos malo que no parar nunca: un arreglo corto sigue siendo JSON válido y cerrado.
  • SQL puro: sin biblioteca compartida, y solo lee los catálogos.

Lo que no hace

Lo que no hace

  • Hace inalcanzable lo inexistente. No hace correcta la respuesta: un modelo restringido a tus diez tablas reales igual elegirá la equivocada de las diez, y esta extensión la emitirá feliz. Medido: restringido, respondió "deploy to production" con una capacidad real que era la incorrecta. Bien formado, incorrecto.
  • No genera una gramática para SQL: enumerar nombres es la parte donde el catálogo es la única fuente de verdad; parsear SQL es un problema resuelto que no necesita vivir en tu base.
  • Requiere pg_living_assertions (PostgreSQL 11+): por eso 10 queda fuera.
  • Solo para conjuntos cerrados, los que el catálogo conoce completos: nombres de tablas, columnas de una tabla, etiquetas de un enum. Los abiertos (rutas de archivos, comandos, texto libre, SQL arbitrario) van a tu validador, siempre: una gramática sobre un conjunto abierto no falla con ruido, deja inalcanzable la respuesta correcta.

Para la empresa

Para la empresa

Es la pieza para equipos que ya usan salida estructurada con un modelo y descubrieron que el esquema no sabe qué columnas existen. La gramática sale de la base, y la base vigila que siga siendo cierta.

  • Compatible con vLLM, SGLang, TensorRT-LLM, MLC-LLM (XGrammar) y llama.cpp
  • Gramáticas por caso de uso, con las tablas que ese caso puede tocar
  • Vigilancia con fecha vía pg_living_assertions: un deploy gate o un cron reciben una respuesta real

Ficha técnica

Versión medida
0.4.9 (imagen pública 0.3.6, 13-11-2026)
PostgreSQL
11 a 19 verdes (installcheck, 2026-09-16)
Depende de
pg_living_assertions (la mitad guardiana)
Formato
GBNF (llama.cpp, XGrammar)
Licencia
Apache-2.0
Edición Enterprise
Incluida (PostgreSQL 18)
Pruébala Hablar