Ontologiq documentation
Ontologiq is a command-line compiler for your operational ontology: the business objects your company runs on — customers, orders, contracts — described once, in YAML, next to your code.
An AI agent cannot complete a governed action on its own. That sentence is the product. The ontology underneath — identity, state, relations — is what makes it expressible:
requires: state == 'open'only means something when state is computed from live data and the order has an identity that outlives the conversation.
Start here
| Page | What it covers |
|---|---|
| Demo | The product’s reason to exist, in one walkthrough: an AI agent proposes an action, cannot execute it, a human approves it, and the precondition is checked again at that moment — then the audit trail of all of it. |
| Quickstart | A working project in five minutes, no credentials. Install, scaffold, build, look at a record. |
New here? The demo shows why this exists; the quickstart gets it running on your machine. Twenty minutes for both and you will know whether this is useful to you.
Understand
| Page | What it covers |
|---|---|
| How it fits together | The five moving parts — data, ontology, AI agent, human, operational system — and which power each one holds. Start here if you are asking “but what does it actually do?” |
| Concepts | Objects, identity, properties, state, relations and governed actions — the model behind the format. |
| Security model | What is enforced, what is only declared, and the threats each control answers. Read before trusting it with anything. |
| Roadmap and status | What works, what is deferred on purpose, known limitations, and where help would matter. |
Reference
| Page | What it covers |
|---|---|
| YAML reference | Every field of the format, with the semantics the compiler implements. |
| CLI reference | Every command and flag, and what each one does and does not touch. |
| MCP reference | The tools generated for AI agents, their inputs and outcomes, and connecting Claude Desktop. |
| Workbench | The ontology as a live page — objects, records, dry runs, the approval queue — with no write path, on purpose. |
| Adapters | Which warehouses are supported, connection settings, and how to write an adapter. |
In three sentences
You describe an object once: where it lives, what identifies it, what states it can be in, what it relates to, and which actions may be performed on it. The compiler turns that into SQL views your analysts can query, a catalog for tooling, and typed MCP tools an AI agent can call. Actions carry roles, preconditions, approval rules and an audit trail — and never write to your database, because effects are your webhooks and your handlers.
What it is not
It is not a metrics layer — Cube, MetricFlow and OSI model aggregates, and this is the layer of entities underneath them. It is not a data-access proxy: anyone with warehouse credentials can query your tables directly, and Ontologiq governs the path you give to agents, not the database. It is not a BI tool, an orchestrator, or a database.
Status
Alpha, and honest about it. Objects, state, relations, governed actions, SQL compilation, the MCP server, the action runtime and the visual workbench work end to end on DuckDB today. Postgres and MySQL run the whole loop against live servers in CI, and Databricks has passed the same smoke against a live serverless warehouse — the adapters page says exactly what is and is not proven.
The project is built and maintained by one person so far. Issues, ideas and pull requests are genuinely welcome — see contributing.