How GramSpec works

One graph between the model and your data

The language model never sees your DDL and never holds your credentials. It reads the GRAM graph — a compiled, closed-world description of your schema — and every query it writes is validated against that graph before a read-only connection runs it.

1. Model in Grammar. Connect a database (or start from nothing) and compile its structure into a GRAM graph — entities, fact types, keys, cardinality, and the constraints your schema never wrote down.
2. Ask in Dashboard or Analyst. A plain-English question, or a long-running investigation. Both consume the same graph.
3. The model reads the graph. Not your DDL, not your connection string, not your rows. The graph declares every join path and every rule the query must obey.
4. SQL is generated, then checked. The gate validates every query against the graph and blocks anything that is not a read.
5. Your database answers. Queries run over an encrypted connection with read-only enforcement; credentials never leave the server and never enter a prompt.
6. Results render as answers. Charts, tables, findings — each traceable to the SQL that produced it.

Three doors in, one document out

However a graph starts — from a live schema, from business prose, or from a Power BI model — it becomes the same portable document, and everything downstream consumes that one artifact.

1. Enter through any door. Point Grammar at a live database and the compiler reads keys, types, and relationships from the schema. Start from prose and the conversational modeler turns sentences into entities, facts, and constraints. Or import a Power BI template and take every field, or only what the report uses.
2. Refine on the canvas. Every relationship is a sentence a business person can verify; every constraint is visible notation. The compiled document conforms to the open GRAM specification.
3. The same document feeds everything. Bond it to a connection and it becomes a dataset for Dashboard's chat; open it in Analyst for investigations; on the Enterprise plan, export it as portable JSON or serve it through the API. One artifact, no copies to drift.

Two lanes, one line your data never crosses

The GRAM API hands your own software the same contract the GramSpec apps use. On the bring-your-own-model lane, GramSpec supplies the reasoning substrate and nothing else — your questions, your rows, and your model traffic stay on your side of the boundary.

1. Fetch the contract. One GET returns the complete system prompt for your project — or the AnalystKit: the agent prompt, the full graph, and the schemas for the seven analyst tools.
2. Cache it by hash. The response carries a content hash; revalidate with one header and get 304 until the graph, rules, or dialect actually change.
3. Call your own model. Any provider, your account, your data residency. The prompt is provider-neutral by design.
4. Execute on your own database. Your app runs the SQL under its own read-only rules. GramSpec never sees a question, a row, or a token of model traffic on this lane.
5. Or take the managed lane. POST a question against a dataset you own and GramSpec runs the whole pipeline — model call, parsing, chart config — and returns structured results.
6. Structured results either way. SQL blocks you can execute, chart configuration you can render, and honest refusals when the graph cannot answer.

Request and response shapes, caching, and the error contract live in the API reference.