Private Preview - features may change without notice
GramSpec
Architecture Spec API Reference Pricing About
Start free

Architecture

How GramSpec works

The model of what your data means is built with the people who run the business, kept as one open document, and every app and agent works from it. Your database stays where it is. The details are in the specification and the API reference; this page is the map.

01 · The foundation

Built with the people who know what the data means

The model is the part of a foundation that fails, and everything else is built on top of it. Starmaker builds it with the business, and checks it against your data before anyone relies on it.

1 · YOUR WORDS 2 · YOUR DATA 3 · YOUR STAR The people who make the decisions say what they measure, in their own words “Each product belongs to exactly one subcategory.” The person who knows the database traces each word to where it comes from: a column that stores it, or the values it is worked out from Built, loaded and checked the star schema, on your rows the grain and every link checked against the source The model, kept as one open GRAM document the sentences, the keys and the rules, with every version kept, readable by any model
The business decides what the data means. The database shows where it lives. The rows confirm it.
  1. They say what they measure. The people who make the decisions describe the business in their own words. Each thing they name becomes a sentence they can read back and correct.
  2. Each word is traced to your data. The person who knows the database shows where each one comes from, whether it is stored in a column or worked out from other values.
  3. Built and checked. The star schema is loaded and tested against your rows, and it is ready for reports and AI the same day. The same model is kept in Grammar as a graph.

02 · The product

One model between AI and your data

The language model reads the graph, never your DDL, and never holds your credentials. Every query it writes is checked before it runs, and your database stays where it is.

MAKE THE MODEL Starmaker from a conversation Grammar sentences on a canvas USE IT Vision ask · pin · share Reason why a number moved Your own agents API · MCP GRAMSPEC The model the GRAM graph things · facts · keys · rules Language model reads the graph, never your DDL Checks before anything runs a read-only check on every query YOUR DATABASE Stays where it is credentials encrypted at rest, never in a prompt
The graph is the only picture of your database the model reads, and the checks stand between it and your data.
  1. Make the model. In Starmaker from a conversation, or in Grammar from sentences, a database or a Power BI template. Either way it becomes one graph.
  2. Ask. A question in Vision, an investigation in Reason, or your own agent through the API and MCP.
  3. The model reads the graph. It is given the graph, not your DDL, and never your connection details.
  4. SQL is written, then checked. Every query must pass a read-only check before it runs. Reason and agents over MCP also check every table and column it names against the graph (SQL Server today).
  5. Your database answers. Credentials are encrypted at rest and never enter a prompt. The model sees only the rows a query returns, capped, when it writes the answer.
  6. Answers show their SQL. A Vision answer and a Reason finding both show the query behind them.
When the graph has no path, it says so. Vision and Reason are built to name what is missing rather than guess. Boards and the explorer write their SQL from the graph itself, and name any missing piece exactly.

03 · The graph

Four ways in, one document out

However a model starts, it becomes the same open document, and everything downstream works from that one file.

WAYS IN A conversation Starmaker, or Grammar's modeler A live database its tables, keys and links A Power BI template what the report uses, or whole tables A graph file one you already have Grammar the model as sentences and on a canvas every version kept GRAM document one JSON file, open spec readable by any model checkable by the business WHERE IT GOES Vision and Reason asking and investigating API and MCP your apps and agents Export the file, on Enterprise
The document is produced by the model, so it never drifts away from it.
  1. Start from any of them. Say what the business measures in Starmaker, or describe it in sentences in Grammar. Read the tables, keys and links of a live database. Import a Power BI template and take the fields its report uses, or every column of those tables. Or open a graph file you already have.
  2. Read it and correct it. Every relationship is a sentence a business person can check, and every rule is visible on the canvas. The document follows the open GRAM specification.
  3. The same document feeds everything. Connect it to your database and it is ready for Vision and Reason; serve it to your own apps and agents through the API and MCP; on the Enterprise plan, export it as a file.

04 · The API and MCP

Your own software, on the same model

The GRAM API gives your own software the same model the apps use. On the bring-your-own-model lane, GramSpec sends the prompt and the graph and nothing else, so your questions, your rows and your model traffic stay with you.

GRAMSPEC YOUR INFRASTRUCTURE LANE A · BRING YOUR OWN MODEL The contract SystemPrompt: rules + dialect + graph AnalystKit: agent prompt + 7 tool schemas cache by hash · 304 when unchanged Your app runs the loop Your model any provider, your account Your database read-only, your rules 1 2 3 4 LANE B · MANAGED Your app no model of its own The pipeline Query: graph + question → model → SQL + a chart setting, returned to you spends your GramSpec AI allowance 5 6 Every request uses a per-user API key (Enterprise plan) · rate limits per user · each request logged
Lane A: GramSpec supplies the contract, and your data and model traffic never cross the line. Lane B: GramSpec runs the pipeline for you.
  1. Fetch the contract. One request returns the complete system prompt for your project, or the AnalystKit: the agent prompt, the graph and the seven tool schemas.
  2. Cache it by hash. The response carries a content hash. Send it back and you get 304 until the graph, the rules or the dialect change.
  3. Call your own model. Any provider, your account, your data residency.
  4. Run it on your own database, under your own read-only rules. On this lane GramSpec never sees a question, a row or your model traffic.
  5. Or take the managed lane. Send a question against a connected graph and GramSpec calls the model and returns the SQL and a chart setting. Your app runs the SQL.

Add questions to your product

SystemPrompt

Fetch the prompt, pair it with your customer's question, and call the model you already run.

Build an investigator

AnalystKit

The agent prompt, the graph and the tool schemas. You own the loop, the compute and the data.

No model of your own

Query

Send a question against a connected graph and get back the SQL and a chart setting, ready to use.

Connect an agent

MCP

Point Claude Code, Cursor or any MCP client at gramspec.com/mcp. It signs in with OAuth or an API key and gets eight read-only tools over your graphs.

Request and response shapes, caching and errors are in the API reference.

05 · Why the model comes first

The model is the part of a foundation that fails.

Storing and moving data is solved engineering, and it does its job well. What it cannot do is decide what the data means: what one row is, which customer is the customer, which date counts. Those are decisions. When nobody writes them down, every report and every AI answer makes its own guess.

Your database has probably run the business for years, keyed and constrained, and it is sound. The meaning the business attaches to it lives with the people who run the business and the person who knows the database, so that is where the model is built.

GRAM is a language for writing that meaning down, grounded in Object-Role Modeling and four decades of fact-based modeling research.

The method

Facts you can read out loud.

Every relationship in a GRAM graph is written as a sentence the business can read and check, like “Each product belongs to exactly one subcategory.” Behind each sentence are the rules that decide how a query joins and counts.

We tested what a machine actually uses. With every verb replaced by a generic label, the generated SQL came out the same, as long as the rules and the role names were intact. The sentence is for the people who check the model, and the rules are what make the query right.

We also built a graph in invented vocabulary, words no model had seen, with the rules intact, and the queries came back correct. Where a run failed, the cause was always something the graph had not yet written down, and each one became a fix.

Read the research paper (PDF)