Understand
The deterministic parser reads explicit instructions locally. It claims one only when it understands every word; anything else goes to your model.
Skip to content01 02 03
Open source · MIT · TypeScript
Let users ask your tables anything.
Pragma turns plain language into a validated search, filter, sort and pagination query that any table, API or database can run. Explicit requests are answered in the browser in about a millisecond; your own model handles the rest.
Works with
- React
- TanStack Table
- Next.js
- Express
- Hono
- Bun
- Deno
- OpenAI
- Claude
- Gemini
- Ollama
- Vercel AI SDK
How it works
The model proposes. The engine decides.
Natural language is only the input. The source of truth is a typed query checked against your schema.
Validate
Every proposal is checked against your schema: fields, operators, value types, limits. Hidden fields are unreachable. Nothing is guessed.
Apply & explain
Changes apply to the current query, so follow-ups just work. Chips and explanations come from the validated result, so they match what runs.
Features
Everything a query bar needs, nothing it shouldn't do.
Local first, model second
Most instructions never leave the browser. The model is called only for phrasing the parser can't fully understand, and answers are cached.
- answered without a model
- 76%
- median local latency
- 0.46 ms
- full browser bundle
- 61 kB
Safe by construction
- Field exists and is visible
- Operator allowed for the type
- Value coerced and in range
- Hidden fields: unreachable
- Row data: never sent to a model
Asks instead of guessing
Ambiguous requests get options that apply instantly, with no second model call.
@ column autocomplete
Suggestions come from the schema, locally. Types and aliases included.
Bring your own model
One small interface. Keys stay on your server, with retries, fallbacks and a circuit breaker built in.
Refuses what it can't answer
Requests outside the schema get a reason and suggestions instead of an invented filter. Every warning and error has a stable code.
Error codes →Quick start
From install to first query in minutes.
Describe your table once. Drop in the ask bar. Feed the query to your table or your API.
tsx
import { createEngine, defineSchema } from '@avinash-baraiya/pragma';
import { AskBar, PragmaProvider, QueryChips } from '@avinash-baraiya/pragma/react';
import '@avinash-baraiya/pragma/styles.css';
const schema = defineSchema({
schemaVersion: '1',
resource: 'customers',
fields: [
{ id: 'name', label: 'Name', type: 'string' },
{ id: 'country', label: 'Country', type: 'string' },
{ id: 'revenue', label: 'Revenue', type: 'number' },
{ id: 'createdAt', label: 'Signed up', type: 'datetime' },
],
});
const engine = createEngine({ schema });
export function App() {
return (
<PragmaProvider engine={engine}>
<AskBar />
<QueryChips />
<CustomersTable /> {/* reads usePragma().query */}
</PragmaProvider>
);
}ts
// app/api/pragma/route.ts: only needed for free phrasing. Keys stay here.
import { createPragmaHandler } from '@avinash-baraiya/pragma/server';
import { gemini } from '@avinash-baraiya/pragma/providers/gemini';
export const POST = createPragmaHandler({
schemas: { customers: schema },
provider: gemini({ model: 'gemini-3.5-flash-lite', apiKey: process.env.GEMINI_API_KEY! }),
});json
{
"version": "1.0",
"resource": "customers",
"search": null,
"filter": {
"type": "group",
"logic": "and",
"children": [
{ "type": "condition", "field": "country", "operator": "eq", "value": "India" },
{
"type": "condition",
"field": "createdAt",
"operator": "last",
"value": { "amount": 30, "unit": "day" }
}
]
},
"sort": [{ "field": "revenue", "direction": "desc" }],
"pagination": { "type": "page", "page": 1, "pageSize": 20 }
}Try it before you install it.
The playground runs the real engine on 500 sample customers, right in your browser.