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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: model2data-studio
-Version: 0.3.0
+Version: 0.4.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
@@ -70,7 +70,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 +88,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 +210,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 +267,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
@@ -351,7 +398,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:
 
 | | |
 | --- | --- |
@@ -362,12 +409,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 +473,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.4.0}/README.md

@@ -41,7 +41,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 +59,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 +181,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 +238,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
@@ -322,7 +369,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:
 
 | | |
 | --- | --- |
@@ -333,12 +380,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 +444,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.4.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.4.0"
 
 __all__ = ["__version__"]

model2data_studio-0.4.0/model2data_studio/building.py

@@ -0,0 +1,367 @@
+"""Building a project from files: create it from a model, then save its model and metrics.
+
+Both the CLI (`project create`, `model push`, `metrics push`) and the MCP server
+(`create_project`, `save_model`, `save_metrics`) go through here, so a pipeline
+and an agent cannot come to save a project differently.
+
+Nothing here reads a model or a metrics file. The studio checks each one first
+(`POST /api/model/check`, `POST /api/metrics/check`), and a file with an error
+is not saved: the error comes back as `Rejected`, each issue with its line and
+column. A save then goes through `PUT /api/projects/{id}` the way the studio's
+own editor saves: the whole project, read first, with only the one field
+replaced, and the `updatedAt` it was read at, so a save that lands on someone
+else's is refused rather than written over it (and read again, once).
+
+DBML is saved as the model document it converts to: the studio generates from a
+model document directly, whereas DBML needs a parse only the editor makes, so a
+project created from DBML here would not generate until it was opened there.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import uuid
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from .client import ChangedElsewhere, StudioClient, StudioError, dashboard_issue
+
+# What a save keeps of the project as it is stored: everything but the text it
+# replaces. `schema` (the editor's parse of DBML) is kept only while the text it
+# is a parse of is.
+KEPT_ON_SAVE = (
+    "name",
+    "positions",
+    "rows",
+    "rowOverrides",
+    "seed",
+    "asOf",
+    "locale",
+    "timeProfile",
+    "skew",
+    "adapter",
+    "defects",
+)
+
+# A new project's settings, as the studio's own "new project" has them: the free
+# plan's row count, a pinned seed, dates anchored on the day it was made.
+NEW_PROJECT_ROWS = 100
+NEW_PROJECT_SEED = 42
+
+
+@dataclass(frozen=True)
+class Issue:
+    """One error or warning in a model or metrics file."""
+
+    severity: str  # "error" or "warning"
+    line: int | None
+    column: int | None
+    message: str
+
+    @property
+    def is_error(self) -> bool:
+        return self.severity != "warning"
+
+    def text(self, where: str = "") -> str:
+        """`where:line:column: error: message`, or `line 3, column 5: error: message`."""
+        issue = {"line": self.line, "column": self.column, "message": self.message}
+        return dashboard_issue(issue, where, self.severity)
+
+
+def _issue(raw: Mapping[str, Any], severity: str | None = None) -> Issue:
+    path = str(raw.get("path") or "")
+    message = str(raw.get("message") or "")
+    return Issue(
+        severity=severity or ("warning" if raw.get("severity") == "warning" else "error"),
+        line=raw.get("line"),
+        column=raw.get("column"),
+        message=f"{path}: {message}" if path else message,
+    )
+
+
+def model_issues(checked: Mapping[str, Any]) -> list[Issue]:
+    """A model check's errors, then its warnings."""
+    return [_issue(raw, "error") for raw in checked.get("errors") or []] + [
+        _issue(raw, "warning") for raw in checked.get("warnings") or []
+    ]
+
+
+def metrics_issues(checked: Mapping[str, Any]) -> list[Issue]:
+    """A metrics check's issues, errors first, as the studio sorts them."""
+    return [_issue(raw) for raw in checked.get("issues") or []]
+
+
+class Rejected(StudioError):
+    """A file the studio found errors in, so nothing was saved. `which` is
+    "model" or "metrics"; `issues` are the check's, warnings included."""
+
+    def __init__(self, which: str, issues: list[Issue]) -> None:
+        self.which = which
+        self.issues = issues
+        noun = "model" if which == "model" else "metrics file"
+        super().__init__(
+            "\n".join(
+                [f"The {noun} has errors, so nothing was saved:", *(i.text() for i in issues)]
+            )
+        )
+
+
+def describe_summary(summary: Mapping[str, Any] | None) -> str:
+    """`3 tables (customers, orders, products), 21 columns`."""
+    if not summary:
+        return "no tables"
+    tables = int(summary.get("tables") or 0)
+    names = ", ".join(str(name) for name in summary.get("tableNames") or [])
+    columns = int(summary.get("columns") or 0)
+    return (
+        f"{tables} table{'' if tables == 1 else 's'}"
+        + (f" ({names})" if names else "")
+        + f", {columns} column{'' if columns == 1 else 's'}"
+    )
+
+
+# --- Checking ----------------------------------------------------------------------
+
+
+@dataclass
+class CheckedModel:
+    """A model the studio read without errors: the text to save (DBML as its
+    model document), what it holds and its warnings."""
+
+    text: str
+    format: str
+    summary: dict[str, Any] | None
+    warnings: list[Issue]
+
+    @property
+    def converted(self) -> bool:
+        return self.format == "dbml"
+
+
+def checked_model(client: StudioClient, text: str) -> CheckedModel:
+    """The model, checked; raises `Rejected` when it has an error."""
+    checked = client.check_model(text)
+    issues = model_issues(checked)
+    if checked.get("ok") is False or any(issue.is_error for issue in issues):
+        raise Rejected("model", issues)
+    fmt = str(checked.get("format") or "yaml")
+    saved = str(checked.get("yaml") or "") if fmt == "dbml" else text
+    if not saved:
+        raise StudioError("The studio did not convert the DBML to a model; nothing was saved.")
+    return CheckedModel(saved, fmt, checked.get("summary"), issues)
+
+
+@dataclass
+class CheckedMetrics:
+    """A metrics file the studio read without errors: its metric names and warnings."""
+
+    names: list[str]
+    inferred: bool
+    warnings: list[Issue]
+
+
+def checked_metrics(
+    client: StudioClient,
+    text: str,
+    *,
+    model_text: str | None = None,
+    project_id: str | None = None,
+    project_name: str | None = None,
+) -> CheckedMetrics:
+    """The metrics file, checked against `model_text` or a saved project's model;
+    raises `Rejected` when it has an error."""
+    checked = client.check_metrics(model_text, text, project_name, project_id=project_id)
+    issues = metrics_issues(checked)
+    if any(issue.is_error for issue in issues):
+        raise Rejected("metrics", issues)
+    names = [str(metric.get("name")) for metric in checked.get("metrics") or []]
+    return CheckedMetrics(names, bool(checked.get("inferred")), issues)
+
+
+# --- Saving -----------------------------------------------------------------------
+
+
+def _save(
+    client: StudioClient,
+    project_id: str,
+    change: Callable[[dict[str, Any]], dict[str, Any]],
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Read the project, apply `change` to a body built from it, and save it,
+    reading again once if it was saved elsewhere in between. The project as it
+    was read, and as it was saved."""
+    for attempt in range(2):
+        saved = client.get_project(project_id)
+        body: dict[str, Any] = {name: saved[name] for name in KEPT_ON_SAVE if name in saved}
+        body.update(
+            {
+                "id": saved.get("id", project_id),
+                "dbml": saved.get("dbml") or "",
+                "schema": saved.get("schema"),
+            }
+        )
+        if saved.get("updatedAt"):
+            body["baseUpdatedAt"] = saved["updatedAt"]
+        if "draftRev" in saved:
+            body["draftRev"] = saved["draftRev"]
+        body.update(change(saved))
+        try:
+            return saved, client.save_project(project_id, body)
+        except ChangedElsewhere:
+            if attempt:
+                raise StudioError(
+                    "The project kept changing in the studio while this was being saved, so "
+                    "nothing was saved. Try again once it is quiet."
+                ) from None
+    raise AssertionError("unreachable")  # pragma: no cover
+
+
+@dataclass
+class Created:
+    id: str
+    name: str
+    url: str
+    model: CheckedModel
+    metrics: CheckedMetrics | None
+
+
+def create_project(
+    client: StudioClient,
+    name: str,
+    model_text: str,
+    metrics_text: str | None = None,
+    *,
+    new_id: Callable[[], str] = lambda: str(uuid.uuid4()),
+    today: Callable[[], dt.date] = dt.date.today,
+) -> Created:
+    """Check the model (and metrics file), then create a project from them.
+
+    Raises `Rejected` when either has an error, before anything is created.
+    """
+    if not name.strip():
+        raise StudioError("A project needs a name.")
+    model = checked_model(client, model_text)
+    metrics = None
+    if metrics_text is not None and metrics_text.strip():
+        metrics = checked_metrics(
+            client, metrics_text, model_text=model.text, project_name=name.strip()
+        )
+    project_id = new_id()
+    body = {
+        "id": project_id,
+        "name": name.strip(),
+        "dbml": model.text,
+        "metrics": metrics_text or "",
+        "schema": None,
+        "positions": {},
+        "rows": NEW_PROJECT_ROWS,
+        "rowOverrides": {},
+        "seed": NEW_PROJECT_SEED,
+        "asOf": today().isoformat(),
+        "locale": None,
+        "timeProfile": None,
+        "skew": 0,
+        "adapter": "duckdb",
+    }
+    try:
+        created = client.save_project(project_id, body)
+    except StudioError as error:
+        if "No such project" in str(error):
+            # The one way a brand-new id is "not there": a key confined to one project.
+            raise StudioError(
+                "This API key is limited to one project, so it cannot create another. Use a "
+                "key that is not limited to a project, with save access."
+            ) from error
+        raise StudioError(f"The project was not created. {error}") from error
+    return Created(
+        id=str(created.get("id") or project_id),
+        name=str(created.get("name") or name),
+        url=client.project_url(project_id),
+        model=model,
+        metrics=metrics,
+    )
+
+
+@dataclass
+class SavedModel:
+    name: str
+    url: str
+    model: CheckedModel
+    before: dict[str, Any] | None
+    # The project's metrics file, read against the new model: its errors and
+    # warnings (the file is kept as it is either way).
+    metrics_issues: list[Issue] = field(default_factory=list)
+
+
+def save_model(client: StudioClient, project_id: str, text: str) -> SavedModel:
+    """Check a model, then save it as the project's model, keeping everything else.
+
+    Raises `Rejected` when the model has an error. The project's metrics file
+    is kept; when it no longer reads against the new model, that is reported.
+    """
+    model = checked_model(client, text)
+    current = client.get_project(project_id)
+    before = None
+    if (current.get("dbml") or "").strip():
+        try:
+            before = client.check_model(str(current["dbml"])).get("summary")
+        except StudioError:
+            before = None
+    metrics_text = str(current.get("metrics") or "")
+    issues: list[Issue] = []
+    if metrics_text.strip():
+        checked = client.check_metrics(model.text, metrics_text, current.get("name") or None)
+        issues = metrics_issues(checked)
+    saved, _ = _save(client, project_id, lambda _saved: {"dbml": model.text, "schema": None})
+    return SavedModel(
+        name=str(saved.get("name") or project_id),
+        url=client.project_url(project_id),
+        model=model,
+        before=before,
+        metrics_issues=issues,
+    )
+
+
+@dataclass
+class SavedMetrics:
+    name: str
+    url: str
+    metrics: CheckedMetrics
+    before: list[str] | None
+
+
+def save_metrics(client: StudioClient, project_id: str, text: str) -> SavedMetrics:
+    """Check a metrics file against the project's model, then save it as the
+    project's metrics file, keeping everything else. Raises `Rejected` when it
+    has an error."""
+    metrics = checked_metrics(client, text, project_id=project_id)
+    current = client.get_project(project_id)
+    before = None
+    try:
+        before = checked_metrics(
+            client, str(current.get("metrics") or ""), project_id=project_id
+        ).names
+    except StudioError:
+        before = None
+    saved, _ = _save(client, project_id, lambda _saved: {"metrics": text})
+    return SavedMetrics(
+        name=str(saved.get("name") or project_id),
+        url=client.project_url(project_id),
+        metrics=metrics,
+        before=before,
+    )
+
+
+def metrics_change(before: list[str] | None, after: list[str]) -> str:
+    """`5 metrics (was 3): added aov, revenue; removed gmv`."""
+    head = f"{len(after)} metric{'' if len(after) == 1 else 's'}"
+    if before is None:
+        return head
+    added = [name for name in after if name not in before]
+    removed = [name for name in before if name not in after]
+    parts = []
+    if added:
+        parts.append(f"added {', '.join(added)}")
+    if removed:
+        parts.append(f"removed {', '.join(removed)}")
+    return f"{head} (was {len(before)})" + (f": {'; '.join(parts)}" if parts else "")