diff --git a/README.md b/README.md index 1dd45e9..4916cc6 100644 --- a/README.md +++ b/README.md @@ -206,6 +206,48 @@ Detection resolves `mdl` in order: an explicit `modelith.mdlPath` setting, a pro `.venv`, `mdl` on PATH, the active conda or virtualenv, then the common per-user install locations. A standard `uv tool install modelith-dbt` needs no configuration. +## Ask the model, in Copilot Chat + +The extension wires Modelith into GitHub Copilot Chat, one integration per mode. Both +speak to the model through the same `mdl` query layer the canvas and LSP use, so the +answers are grounded in the committed model, not guessed — and neither needs an API key +or a `mcp.json`. + +**`@modelith` in Ask mode.** Type `@modelith` and ask about the model in plain English. +Intent is parsed by your own Copilot model and grounded with the real facts — entities, +attributes, keys, relationships, ontology alignments — so it answers the question you +actually asked and refuses to invent structure that isn't there. + +Ask a model-wide question and it grounds on every entity. Here it works through +normalization entity by entity, reasoning from each candidate key, and is honest about +the one thing the model doesn't yet capture — arbitrary functional dependencies: + +> `@modelith are all models in BCNF? Answer entity by entity` + +![The @modelith chat participant answering a BCNF question with a per-entity table: benchmark, counterparty, portfolio, price, transaction each "Appears BCNF" on their single key, instrument under its recorded pk/unique keys, position "cannot assess: no key defined", closing that a definitive determination needs the full set of functional dependencies — the pension_ibor canvas beside it](docs/assets/chat-participant-bcnf.png) + +Ask a targeted question and it grounds on that entity in full — attributes, nullability, +relationships — and reasons from the entity's meaning: + +> `@modelith how would you define keys for the position entity?` + +![The @modelith chat participant proposing a composite key (portfolio_code, instrument_id, as_of_date) for the position entity, noting all three are currently nullable so should be non-null for a primary key, and that the model doesn't confirm uniqueness so the business rule needs validating — with a pointer to Agent mode for the edit](docs/assets/chat-participant-keys.png) + +There are slash commands for the common asks — `@modelith /list` for the entity list and +`@modelith /explain ` for one entity in full — but free text works just as well. + +**Modelith tools in Agent mode.** Switch Copilot Chat to Agent mode and the model is +available as tools the agent can call in its plan/act loop: `list_entities`, `get_entity`, +`search_ontology`, `get_model_context`, `validate`, and the write tools `create_entity` +and `update_entity`. The agent can ground itself in what exists, search the ontology for +an alignment, and write validated entities straight into your checkout — direct-write, so +you review the git diff, the same trust boundary as the CLI. The server is the `mdl mcp` +subcommand, registered automatically and scoped to your workspace model (needs VS Code +1.99+; older hosts keep every other feature). + +The same query layer is on the CLI too: `mdl model context | entities | entity | +detail` print the model as JSON. + ## What it models Modelith represents the core data-modeling taxonomy as first-class, git-tracked objects: @@ -990,8 +1032,10 @@ catalog. |---|---| | Studio | `mdl studio` — the model in a browser, in two modes. Default: a **modeler** stages edits and proposes them as one pull request, never seeing git. `--direct`: an **engineer** writes the working tree and commits themselves. Terms, the ERD (scoped by subject area), the subject-area picker, a semantic diff and the proposal flow. Distributable on its own with `--export`. | | VS Code extension | Where engineers actually live: the canvas beside your YAML, following the active editor, plus diagnostics on save and generate / drift / lint commands. See [In VS Code](#in-vs-code). | -| `mdl` CLI | The full command set: init, validate, lint, generate, reverse, drift, diff, studio, subject-area, ontology, emit, export, import, gov, catalog, and more | +| Copilot Chat | `@modelith` answers about the model in Ask mode; Modelith tools (`mdl mcp`) let the agent read and write the model in Agent mode. Grounded in the committed model. See [Ask the model, in Copilot Chat](#ask-the-model-in-copilot-chat). | +| `mdl` CLI | The full command set: init, validate, lint, generate, reverse, drift, diff, model, studio, subject-area, ontology, emit, export, import, gov, catalog, and more | | Language server | `mdl lsp` (one server for VS Code, Cursor, Windsurf, JetBrains, and CI): drift and contract diagnostics on the dbt files, hover cards, code actions | +| MCP server | `mdl mcp` — the model as tools for any MCP client (Copilot agent mode, Claude Desktop, Cursor) | | Architect canvas | `mdl serve` — the ER editor the VS Code extension embeds. `mdl studio --direct` is the same editing model with Studio's chrome. | ## CLI reference @@ -1013,6 +1057,8 @@ mdl studio --direct engineer mode: edits write the mdl studio --catalog browse published models, open one to edit mdl studio --export write its static files, to host anywhere mdl serve [--read-only] [?subject_area=] architect ER canvas + read API (VS Code embeds this) +mdl model context|entities|entity |detail read the model as JSON (the AI surfaces' query layer) +mdl mcp [--repo ] MCP server (stdio): model tools for an AI agent mdl ontology search|check browse; layer rules + coverage report mdl ontology lock|fetch|add pin a source, fetch+verify, vendor a file mdl ontology align|promote propose alignments (§2), accept them @@ -1042,6 +1088,7 @@ packages/ collibra/ Collibra governance adapter server/ read API (FastAPI) + hosts the canvas build lsp/ language server (pygls) + mcp/ MCP server (mdl mcp): model + ontology tools for AI agents cli/ mdl canvas/ web canvas source (Vite + React + React Flow) vscode/ VS Code extension (TypeScript + esbuild) diff --git a/docs/assets/chat-participant-bcnf.png b/docs/assets/chat-participant-bcnf.png new file mode 100644 index 0000000..f6a2149 Binary files /dev/null and b/docs/assets/chat-participant-bcnf.png differ diff --git a/docs/assets/chat-participant-keys.png b/docs/assets/chat-participant-keys.png new file mode 100644 index 0000000..7d4260c Binary files /dev/null and b/docs/assets/chat-participant-keys.png differ