model2data-studio 0.3.0__tar.gz → 0.5.0__tar.gz

{model2data_studio-0.3.0 → model2data_studio-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: model2data-studio
-Version: 0.3.0
+Version: 0.5.0
 Summary: Generate a model2data studio project's data from the command line, so CI can rebuild fixtures instead of committing them.
 Project-URL: Homepage, https://www.jbanalytica.com/model2data/
 Project-URL: Studio, https://studio.jbanalytica.com
@@ -52,7 +52,10 @@ uvx model2data-studio --help
 
 It needs an API key from a **Pro** account on the studio: see
 [pricing](https://www.jbanalytica.com/model2data/pricing/). The client is MIT
-licensed; the studio it talks to is not open source.
+licensed; the studio it talks to is not open source. (To use the studio from
+Claude or another MCP client without a key, see [the MCP
+server](#the-mcp-server-generating-from-an-agent-instead-of-a-shell): the
+studio's own endpoint needs only a sign-in.)
 
 ## Configuration
 
@@ -70,7 +73,9 @@ the account, so put it in your CI provider's secrets rather than in a file.
 Leave the key's access on **Generate and export**, which is the default and
 covers everything below: reading a project, generating, exporting. A key with
 **Read only** access is refused by `generate` with a 403 saying so. **Generate
-and save** adds writing the project back, which `push` and `dashboard push` need — for a
+and save** adds writing the project back, which `push`, `project create`, `model push`,
+`metrics push` and `dashboard push` need (`project create` also needs a key that is not
+limited to one project) — for a
 pipeline that pushes a model up rather than pulling data down — and **Full access** adds
 deleting a project and managing its share links, which the CLI never does. A
 key that leaks out of a CI log can only do what it was given.
@@ -86,10 +91,18 @@ model2data-studio generate --project <id> --out . --format dbt --adapter duckdb
 
 model2data-studio push --project <id> shop.model2data.yml   # save a model as the project's
 
+model2data-studio project create Shop --model shop.model2data.yml --metrics shop.metrics.yml
+model2data-studio model check shop.model2data.yml           # exits 1 on an error; no key needed
+model2data-studio model push <id> shop.model2data.yml       # replace the model, keep the rest
+model2data-studio model guide                               # how to write one: the model spec
+
 model2data-studio metrics list --project ID            # what each metric computes
 model2data-studio metrics check --project shop.metrics.yml  # exits 1 on an error, for CI
 model2data-studio metrics values --project ID --seed 42 --as-of 2026-10-01
 model2data-studio metrics suggest --project shop.model2data.yml -o shop.metrics.yml
+model2data-studio metrics check shop.metrics.yml --model shop.model2data.yml   # or --project <id>
+model2data-studio metrics push <id> shop.metrics.yml        # replace the metrics file, keep the rest
+model2data-studio metrics guide                             # how to write one: the metrics spec
 
 model2data-studio dashboard pull <id> --out dashboards/       # one <name>.dashboard.yml each
 model2data-studio dashboard push <id> dashboards/*.dashboard.yml
@@ -200,7 +213,10 @@ runs on the free plan.
 | | |
 | --- | --- |
 | `metrics list --project TARGET` | each metric's name, label, kind, what it computes, its filter and its date column; a metric the model implies rather than the file writes is marked `*` |
-| `metrics check --project TARGET` | every issue as `file:line: error: path: message`, the shape a CI log viewer links; exits 1 on an error, 0 on warnings alone |
+| `metrics check --project TARGET` | every issue as `file:line:column: error: path: message`, the shape a CI log viewer links; exits 1 on an error, 0 on warnings alone |
+| `metrics check FILE.metrics.yml --model FILE` | the same, for a metrics file against a model file (YAML, JSON or DBML), wherever the two live; `--project ID` instead reads it against a saved project's model. Needs no key with `--model` |
+| `metrics push PROJECT_ID FILE.metrics.yml` | checks the file against the project's model, then saves it as the project's metrics file, keeping the model, dashboards and settings; says which metrics were added and removed. Nothing is saved on an error |
+| `metrics guide` | the guide to writing a metrics file, as markdown: the metrics spec, then what the studio adds (no key needed) |
 | `metrics values --project TARGET` | generates the data (the same run `generate` makes with the same arguments) and prints each metric's known value. `--seed`, `--rows` and `--as-of` as for `generate`; `--by-month` adds each month; `--json` prints the values shaped like the export's `metric_values.json` (its `run` and `metrics`; the spec version and rounding note are the export's own) |
 | `metrics suggest --project TARGET` | a metrics file of the metrics the model implies, to start one from: stdout, or `-o FILE` (`--force` to replace one) |
 
@@ -254,6 +270,40 @@ A dashboard file that names something the project does not have is still saved:
 that is a warning, not an error, so a dashboard can be sketched before the
 metric it needs exists.
 
+## Building a project: model, metrics, dashboards
+
+A whole project can be built from files, by a pipeline or an agent, without
+opening the studio: a model (`<stem>.model2data.yml`, model2data's open
+[model spec](https://github.com/JB-Analytica/model2data/blob/main/model2data/spec/README.md),
+or DBML), a metrics file (the
+[metrics spec](https://github.com/JB-Analytica/model2data/blob/main/model2data/spec/metrics/README.md))
+and dashboard files. Each kind has a guide (the spec, served by the studio), a
+check that says where each error is by line and column, and a save that checks
+first and saves nothing on an error. Since 0.4.0.
+
+| | |
+| --- | --- |
+| `project create NAME --model FILE [--metrics FILE]` | checks both, then creates the project (100 rows a table, seed 42, dates anchored on today) and prints its id and studio URL. The plan's project limit applies |
+| `model check FILE` | every error and warning as `file:line:column: error: message`; exits 1 on an error. Needs no key |
+| `model push PROJECT_ID FILE` | checks the model, then saves it as the project's model, keeping its metrics file, dashboards, settings and canvas; says how the tables changed, and whether the project's metrics file still reads against it |
+| `model guide` | the guide to writing a model, as markdown (no key needed) |
+
+DBML is saved as the model document it converts to, so the project generates
+straight away. A save reads the project first and replaces only its own part;
+if the project is saved elsewhere in between, it reads it again once rather
+than writing over that save.
+
+The order of work:
+
+1. `model guide`, write `shop.model2data.yml`, `model check` it until it is clean.
+2. `project create Shop --model shop.model2data.yml`: note the id it prints.
+3. `metrics guide`, write `shop.metrics.yml`, `metrics check shop.metrics.yml --project <id>`.
+4. `metrics push <id> shop.metrics.yml`, then `metrics values --project <id>` to see
+   that the numbers come out as intended.
+5. `dashboard guide --project <id>`, write `sales.dashboard.yml`,
+   `dashboard check sales.dashboard.yml --project <id>`.
+6. `dashboard push <id> sales.dashboard.yml`, and open the URL it prints.
+
 ## Regenerating dbt seeds in CI
 
 ```yaml
@@ -315,11 +365,44 @@ would compare against rows anchored on today and fail at the first midnight.
 
 ## The MCP server: generating from an agent instead of a shell
 
-The same account, the same key, the same API — for the editor rather than the
-terminal. The studio is where a schema is *designed*, with a diagram and a
-preview to design it against; the agent in your editor is where the data is
-wanted, and asking it for "two hundred believable orders from my webshop model"
-should not mean pasting DBML into a chat.
+The same account, the same API — for an agent rather than the terminal. The
+studio is where a schema is *designed*, with a diagram and a preview to design
+it against; the agent in your editor or chat is where the data is wanted, and
+asking it for "two hundred believable orders from my webshop model" should not
+mean pasting DBML into a chat.
+
+There are two ways to connect, with the same tools behind both.
+
+### One URL: the studio's own MCP endpoint
+
+The studio serves these tools itself at `https://studio.jbanalytica.com/mcp`.
+Add that URL to your MCP client and sign in to the studio in your browser when
+it asks; there is no key to copy, nothing to install and no config file. It
+works with a free account, within the free plan's limits.
+
+- **Claude** (web, desktop and mobile): *Settings → Connectors → Add custom
+  connector*, paste `https://studio.jbanalytica.com/mcp`, then *Connect* and
+  approve the connection in the studio.
+- **Claude Code**:
+
+  ```bash
+  claude mcp add --transport http model2data-studio https://studio.jbanalytica.com/mcp
+  ```
+
+  then run `/mcp` in Claude Code and pick the server to sign in.
+- **Anything else** that speaks Streamable HTTP with OAuth: the same URL.
+
+A connected app appears in the studio under *API keys* in the account menu,
+marked *Connected app*; *Disconnect* there takes its access away at once. It can
+read your projects, create them and save their models, metrics files and
+dashboards, and generate previews and metric values. It cannot delete a project,
+share one, or manage your keys. `write_data` is not offered there: a server on
+the studio would write the files to the studio's disk, not yours.
+
+### Local: this package, with an API key
+
+For CI, for a self-hosted studio, or for writing fixtures straight to disk with
+`write_data`, run the server from this package with an API key (Pro):
 
 ```bash
 uvx --from 'model2data-studio[mcp]' model2data-studio mcp   # the SDK is an extra, see below
@@ -351,7 +434,7 @@ and for anything that reads a JSON config (Claude Desktop, Cursor, Zed):
 
 `MODEL2DATA_STUDIO_URL` works here too, for a self-hosted studio.
 
-Twelve tools:
+Nineteen tools (eighteen at the studio's own endpoint, which has no `write_data`):
 
 | | |
 | --- | --- |
@@ -362,12 +445,27 @@ Twelve tools:
 | `write_data` | generate and write the files, as `generate --out` does |
 | `list_metrics` | the project's metrics, a line each: what it computes, its filter, its date column |
 | `metric_values` | each metric's known value over a generated run, overall and by month (`seed`, `rows`, `as_of` as for `preview_data`). Pro, bar a bundled example. |
+| `get_model_guide` | how to write a model: the open model spec, then what the studio adds (no key needed) |
+| `check_model` | a model's errors and warnings (YAML, JSON or DBML), each with its line and column, and what it holds (no key needed) |
+| `create_project` | checks a model and, optionally, a metrics file, then creates a project from them; answers with its id and studio URL. Needs a key not limited to one project |
+| `save_model` | checks a model, then makes it a project's model, keeping everything else; says how the tables changed |
+| `get_metrics_guide` | how to write a metrics file: the open metrics spec, then what the studio adds (no key needed) |
+| `check_metrics` | a metrics file's errors and warnings, against a project's model (`project_id`) or a model's text (`model_text`, no key needed), and the metrics it defines |
+| `save_metrics` | checks a metrics file, then makes it a project's, keeping everything else; says which metrics were added and removed |
 | `list_dashboards` | the project's dashboards, by name |
 | `get_dashboard` | one dashboard file's text, to edit and save back |
 | `get_dashboard_guide` | how to write a dashboard file: the open dashboard spec, then what the studio adds (no key needed); with `project_id`, ending with that project's metrics and columns |
 | `check_dashboard` | a dashboard file's errors and warnings, each with its line and column, without saving (no key needed without `project_id`) |
 | `save_dashboard` | checks a dashboard file, then creates or replaces it by name; a file with errors is not saved and the errors come back. Answers with the link to the project |
 
+The server's instructions give an agent the order of work for building a
+project from nothing: `get_model_guide` → write the model → `check_model` →
+`create_project` → `get_metrics_guide` → write the metrics → `check_metrics` →
+`save_metrics` → `metric_values` to sanity-check the numbers →
+`get_dashboard_guide` → write a dashboard → `check_dashboard` →
+`save_dashboard` → the studio URL (and share link) to open. Every check and save
+is the studio's; the tools move text.
+
 `preview_data` is the one worth having. An agent that can *read* generated rows
 can act on them — write an assertion against them, notice that `shipped_at`
 precedes `ordered_at`, spot a column coming out as placeholder sentences. It
@@ -411,7 +509,7 @@ workflow refuses a tag that disagrees with any of them), merge, then tag the
 merge commit on `main` and push the tag:
 
 ```bash
-git tag cli-v0.3.0 && git push origin cli-v0.3.0
+git tag cli-v0.4.0 && git push origin cli-v0.4.0
 ```
 
 `.github/workflows/release-cli.yml` runs the tests, builds, publishes to PyPI

{model2data_studio-0.3.0 → model2data_studio-0.5.0}/README.md

@@ -23,7 +23,10 @@ uvx model2data-studio --help
 
 It needs an API key from a **Pro** account on the studio: see
 [pricing](https://www.jbanalytica.com/model2data/pricing/). The client is MIT
-licensed; the studio it talks to is not open source.
+licensed; the studio it talks to is not open source. (To use the studio from
+Claude or another MCP client without a key, see [the MCP
+server](#the-mcp-server-generating-from-an-agent-instead-of-a-shell): the
+studio's own endpoint needs only a sign-in.)
 
 ## Configuration
 
@@ -41,7 +44,9 @@ the account, so put it in your CI provider's secrets rather than in a file.
 Leave the key's access on **Generate and export**, which is the default and
 covers everything below: reading a project, generating, exporting. A key with
 **Read only** access is refused by `generate` with a 403 saying so. **Generate
-and save** adds writing the project back, which `push` and `dashboard push` need — for a
+and save** adds writing the project back, which `push`, `project create`, `model push`,
+`metrics push` and `dashboard push` need (`project create` also needs a key that is not
+limited to one project) — for a
 pipeline that pushes a model up rather than pulling data down — and **Full access** adds
 deleting a project and managing its share links, which the CLI never does. A
 key that leaks out of a CI log can only do what it was given.
@@ -57,10 +62,18 @@ model2data-studio generate --project <id> --out . --format dbt --adapter duckdb
 
 model2data-studio push --project <id> shop.model2data.yml   # save a model as the project's
 
+model2data-studio project create Shop --model shop.model2data.yml --metrics shop.metrics.yml
+model2data-studio model check shop.model2data.yml           # exits 1 on an error; no key needed
+model2data-studio model push <id> shop.model2data.yml       # replace the model, keep the rest
+model2data-studio model guide                               # how to write one: the model spec
+
 model2data-studio metrics list --project ID            # what each metric computes
 model2data-studio metrics check --project shop.metrics.yml  # exits 1 on an error, for CI
 model2data-studio metrics values --project ID --seed 42 --as-of 2026-10-01
 model2data-studio metrics suggest --project shop.model2data.yml -o shop.metrics.yml
+model2data-studio metrics check shop.metrics.yml --model shop.model2data.yml   # or --project <id>
+model2data-studio metrics push <id> shop.metrics.yml        # replace the metrics file, keep the rest
+model2data-studio metrics guide                             # how to write one: the metrics spec
 
 model2data-studio dashboard pull <id> --out dashboards/       # one <name>.dashboard.yml each
 model2data-studio dashboard push <id> dashboards/*.dashboard.yml
@@ -171,7 +184,10 @@ runs on the free plan.
 | | |
 | --- | --- |
 | `metrics list --project TARGET` | each metric's name, label, kind, what it computes, its filter and its date column; a metric the model implies rather than the file writes is marked `*` |
-| `metrics check --project TARGET` | every issue as `file:line: error: path: message`, the shape a CI log viewer links; exits 1 on an error, 0 on warnings alone |
+| `metrics check --project TARGET` | every issue as `file:line:column: error: path: message`, the shape a CI log viewer links; exits 1 on an error, 0 on warnings alone |
+| `metrics check FILE.metrics.yml --model FILE` | the same, for a metrics file against a model file (YAML, JSON or DBML), wherever the two live; `--project ID` instead reads it against a saved project's model. Needs no key with `--model` |
+| `metrics push PROJECT_ID FILE.metrics.yml` | checks the file against the project's model, then saves it as the project's metrics file, keeping the model, dashboards and settings; says which metrics were added and removed. Nothing is saved on an error |
+| `metrics guide` | the guide to writing a metrics file, as markdown: the metrics spec, then what the studio adds (no key needed) |
 | `metrics values --project TARGET` | generates the data (the same run `generate` makes with the same arguments) and prints each metric's known value. `--seed`, `--rows` and `--as-of` as for `generate`; `--by-month` adds each month; `--json` prints the values shaped like the export's `metric_values.json` (its `run` and `metrics`; the spec version and rounding note are the export's own) |
 | `metrics suggest --project TARGET` | a metrics file of the metrics the model implies, to start one from: stdout, or `-o FILE` (`--force` to replace one) |
 
@@ -225,6 +241,40 @@ A dashboard file that names something the project does not have is still saved:
 that is a warning, not an error, so a dashboard can be sketched before the
 metric it needs exists.
 
+## Building a project: model, metrics, dashboards
+
+A whole project can be built from files, by a pipeline or an agent, without
+opening the studio: a model (`<stem>.model2data.yml`, model2data's open
+[model spec](https://github.com/JB-Analytica/model2data/blob/main/model2data/spec/README.md),
+or DBML), a metrics file (the
+[metrics spec](https://github.com/JB-Analytica/model2data/blob/main/model2data/spec/metrics/README.md))
+and dashboard files. Each kind has a guide (the spec, served by the studio), a
+check that says where each error is by line and column, and a save that checks
+first and saves nothing on an error. Since 0.4.0.
+
+| | |
+| --- | --- |
+| `project create NAME --model FILE [--metrics FILE]` | checks both, then creates the project (100 rows a table, seed 42, dates anchored on today) and prints its id and studio URL. The plan's project limit applies |
+| `model check FILE` | every error and warning as `file:line:column: error: message`; exits 1 on an error. Needs no key |
+| `model push PROJECT_ID FILE` | checks the model, then saves it as the project's model, keeping its metrics file, dashboards, settings and canvas; says how the tables changed, and whether the project's metrics file still reads against it |
+| `model guide` | the guide to writing a model, as markdown (no key needed) |
+
+DBML is saved as the model document it converts to, so the project generates
+straight away. A save reads the project first and replaces only its own part;
+if the project is saved elsewhere in between, it reads it again once rather
+than writing over that save.
+
+The order of work:
+
+1. `model guide`, write `shop.model2data.yml`, `model check` it until it is clean.
+2. `project create Shop --model shop.model2data.yml`: note the id it prints.
+3. `metrics guide`, write `shop.metrics.yml`, `metrics check shop.metrics.yml --project <id>`.
+4. `metrics push <id> shop.metrics.yml`, then `metrics values --project <id>` to see
+   that the numbers come out as intended.
+5. `dashboard guide --project <id>`, write `sales.dashboard.yml`,
+   `dashboard check sales.dashboard.yml --project <id>`.
+6. `dashboard push <id> sales.dashboard.yml`, and open the URL it prints.
+
 ## Regenerating dbt seeds in CI
 
 ```yaml
@@ -286,11 +336,44 @@ would compare against rows anchored on today and fail at the first midnight.
 
 ## The MCP server: generating from an agent instead of a shell
 
-The same account, the same key, the same API — for the editor rather than the
-terminal. The studio is where a schema is *designed*, with a diagram and a
-preview to design it against; the agent in your editor is where the data is
-wanted, and asking it for "two hundred believable orders from my webshop model"
-should not mean pasting DBML into a chat.
+The same account, the same API — for an agent rather than the terminal. The
+studio is where a schema is *designed*, with a diagram and a preview to design
+it against; the agent in your editor or chat is where the data is wanted, and
+asking it for "two hundred believable orders from my webshop model" should not
+mean pasting DBML into a chat.
+
+There are two ways to connect, with the same tools behind both.
+
+### One URL: the studio's own MCP endpoint
+
+The studio serves these tools itself at `https://studio.jbanalytica.com/mcp`.
+Add that URL to your MCP client and sign in to the studio in your browser when
+it asks; there is no key to copy, nothing to install and no config file. It
+works with a free account, within the free plan's limits.
+
+- **Claude** (web, desktop and mobile): *Settings → Connectors → Add custom
+  connector*, paste `https://studio.jbanalytica.com/mcp`, then *Connect* and
+  approve the connection in the studio.
+- **Claude Code**:
+
+  ```bash
+  claude mcp add --transport http model2data-studio https://studio.jbanalytica.com/mcp
+  ```
+
+  then run `/mcp` in Claude Code and pick the server to sign in.
+- **Anything else** that speaks Streamable HTTP with OAuth: the same URL.
+
+A connected app appears in the studio under *API keys* in the account menu,
+marked *Connected app*; *Disconnect* there takes its access away at once. It can
+read your projects, create them and save their models, metrics files and
+dashboards, and generate previews and metric values. It cannot delete a project,
+share one, or manage your keys. `write_data` is not offered there: a server on
+the studio would write the files to the studio's disk, not yours.
+
+### Local: this package, with an API key
+
+For CI, for a self-hosted studio, or for writing fixtures straight to disk with
+`write_data`, run the server from this package with an API key (Pro):
 
 ```bash
 uvx --from 'model2data-studio[mcp]' model2data-studio mcp   # the SDK is an extra, see below
@@ -322,7 +405,7 @@ and for anything that reads a JSON config (Claude Desktop, Cursor, Zed):
 
 `MODEL2DATA_STUDIO_URL` works here too, for a self-hosted studio.
 
-Twelve tools:
+Nineteen tools (eighteen at the studio's own endpoint, which has no `write_data`):
 
 | | |
 | --- | --- |
@@ -333,12 +416,27 @@ Twelve tools:
 | `write_data` | generate and write the files, as `generate --out` does |
 | `list_metrics` | the project's metrics, a line each: what it computes, its filter, its date column |
 | `metric_values` | each metric's known value over a generated run, overall and by month (`seed`, `rows`, `as_of` as for `preview_data`). Pro, bar a bundled example. |
+| `get_model_guide` | how to write a model: the open model spec, then what the studio adds (no key needed) |
+| `check_model` | a model's errors and warnings (YAML, JSON or DBML), each with its line and column, and what it holds (no key needed) |
+| `create_project` | checks a model and, optionally, a metrics file, then creates a project from them; answers with its id and studio URL. Needs a key not limited to one project |
+| `save_model` | checks a model, then makes it a project's model, keeping everything else; says how the tables changed |
+| `get_metrics_guide` | how to write a metrics file: the open metrics spec, then what the studio adds (no key needed) |
+| `check_metrics` | a metrics file's errors and warnings, against a project's model (`project_id`) or a model's text (`model_text`, no key needed), and the metrics it defines |
+| `save_metrics` | checks a metrics file, then makes it a project's, keeping everything else; says which metrics were added and removed |
 | `list_dashboards` | the project's dashboards, by name |
 | `get_dashboard` | one dashboard file's text, to edit and save back |
 | `get_dashboard_guide` | how to write a dashboard file: the open dashboard spec, then what the studio adds (no key needed); with `project_id`, ending with that project's metrics and columns |
 | `check_dashboard` | a dashboard file's errors and warnings, each with its line and column, without saving (no key needed without `project_id`) |
 | `save_dashboard` | checks a dashboard file, then creates or replaces it by name; a file with errors is not saved and the errors come back. Answers with the link to the project |
 
+The server's instructions give an agent the order of work for building a
+project from nothing: `get_model_guide` → write the model → `check_model` →
+`create_project` → `get_metrics_guide` → write the metrics → `check_metrics` →
+`save_metrics` → `metric_values` to sanity-check the numbers →
+`get_dashboard_guide` → write a dashboard → `check_dashboard` →
+`save_dashboard` → the studio URL (and share link) to open. Every check and save
+is the studio's; the tools move text.
+
 `preview_data` is the one worth having. An agent that can *read* generated rows
 can act on them — write an assertion against them, notice that `shipped_at`
 precedes `ordered_at`, spot a column coming out as placeholder sentences. It
@@ -382,7 +480,7 @@ workflow refuses a tag that disagrees with any of them), merge, then tag the
 merge commit on `main` and push the tag:
 
 ```bash
-git tag cli-v0.3.0 && git push origin cli-v0.3.0
+git tag cli-v0.4.0 && git push origin cli-v0.4.0
 ```
 
 `.github/workflows/release-cli.yml` runs the tests, builds, publishes to PyPI

{model2data_studio-0.3.0 → model2data_studio-0.5.0}/model2data_studio/__init__.py

@@ -12,6 +12,6 @@ the studio's API does all of that, and this only knows how to ask.
 
 from __future__ import annotations
 
-__version__ = "0.3.0"
+__version__ = "0.5.0"
 
 __all__ = ["__version__"]