How GramSpec works
Three views of the system, at the altitude an architect evaluates: how the apps share one graph substrate, how a knowledge graph is created and flows through the product, and how the API paths keep your data and your model on your side of the line. Details live in the specification and the API reference; this page is the map.
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.
- 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.
- Ask in Vision or Reason. A plain-English question, or a long-running investigation. Both consume the same graph.
- 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.
- SQL is generated, then checked. The gate validates every query against the graph and blocks anything that is not a read.
- Your database answers. Queries run over an encrypted connection with read-only enforcement; credentials never leave the server and never enter a prompt.
- 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.
- 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.
- 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.
- The same document feeds everything. Bond it to a connection and it becomes a dataset for Vision's chat; open it in Reason 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.
- 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.
- 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.
- Call your own model. Any provider, your account, your data residency. The prompt is provider-neutral by design.
- 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.
- 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.
- Structured results either way. SQL blocks you can execute, chart configuration you can render, and honest refusals when the graph cannot answer.
SystemPrompt
Add "ask your data" to your product: fetch the prompt, pair it with your customer's question, call the model you already run.
AnalystKit
Build a claims investigator or procurement copilot: the kit hands you the agent brain; you own the loop, the compute, and the data plane.
Query
Point at a dataset, ask a question, get parsed SQL and chart config back. GramSpec runs the pipeline end to end.
Request and response shapes, caching, and the error contract live in the API reference.
Conceptualization became optional, then it went obsolete.
Somewhere between self-service and the cloud, conceptual data modeling stopped being anyone’s job. The efforts focused on data movement; the meaning was left to take care of itself.
Your database is most likely normalized, keyed, constrained, and it has been running your business for years. The foundation is sound. What was missing is the layer that links the physical data to the business concepts.
That layer went missing for an ordinary reason: nothing in the workflow ever asked for it. Pipelines run without anyone stating what one row means. Reports ship without anyone declaring which customer is the customer. The tools never asked, so the answer was never written down, and a discipline that was once taught quietly stopped being taught.
The work lives on the boundary between the conceptual and the physical. GRAM is a language for that boundary, grounded in Object-Role Modeling and four decades of fact-based modeling research.
Facts you can read out loud.
Every relationship in a GRAM graph is a fact type with a natural-language reading: a sentence. The sentence is the model.
This method has deep roots. Fact-based modeling came out of linguistics research in the 1970s and has been compiling conceptual models into production schemas ever since. The sentences were written for humans, but now there are machines that also read.
Here is what our research found when we tested that: the machine does not need the verbs. Replace every predicate with a generic label and the SQL comes out the same, provided the constraints and role names survive. The sentence is how the business checks the model. The constraint is why the query is right.
We tested the harder direction too: a graph built in invented vocabulary, terms no model has ever encountered, with the constraints intact. The queries came back correct. Where a run did fail, the diagnosis pointed every time at a carrier the graph had not yet declared, and each one became a fix. Unfamiliar words were never the problem. Descriptions and synonyms help a model guess; declared structure removes the guess.