cassis-cli 0.4.0__tar.gz → 1.0.0__tar.gz

{cassis_cli-0.4.0 → cassis_cli-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cassis-cli
-Version: 0.4.0
+Version: 1.0.0
 Summary: Cassis CLI — run Cassis actions (ontology validation, upload and publish) from your CI pipelines
 License: Proprietary
 Keywords: cassis,ontology,ci,text-to-sql
@@ -26,7 +26,11 @@ Run Cassis actions from your CI pipelines:
 - `cassis ontology fmt` rewrites the ontology files in canonical form (think `black`/`gofmt` for the ontology), so hand or agent edits pass the round-trip check.
 - `cassis ontology upload` uploads the ontology files to a Cassis project (full replace) and, by default, publishes them immediately as a new version — so a merge to your main branch can go live in one CI step.
 - `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local YAML files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket).
+- `cassis ontology pull` and `cassis ontology fmt` also write `<base-path>/AGENTS.md`, the Cassis ontology modeling guide, into the checkout (default `cassis/AGENTS.md`) — a managed file (generated banner; the CLI overwrites local edits) so a repo-aware coding agent loads current Cassis modeling doctrine by convention. It sits inside the ontology directory but is not part of the ontology tree (the CLI reads only `*.yml`/`*.yaml`), so it is never uploaded, validated, or pruned. Commit it alongside your ontology changes. The guide text ships inside the CLI package, so its version tracks the **installed cassis-cli version** — upgrade the CLI (`pip install -U cassis-cli`) and re-run `fmt` to pick up doctrine updates; an unpinned `pip install cassis-cli` in CI gets them automatically. The banner stamps a doctrine version, and the CLI never *downgrades* the file: if the checkout's `AGENTS.md` was written by a newer doctrine (a newer CLI, or Cassis itself on a publish), `fmt`/`pull` leave it in place, print an upgrade notice, and `fmt --check` still passes.
+- The CLI identifies itself to the API (`User-Agent: cassis-cli/<version>`), and successful API responses advertise the newest published version — when you are behind, commands print a one-line upgrade notice on stderr (purely informational; output and exit codes are unchanged).
 - `cassis eval run` runs the project's eval suite against your local ontology files (scored in-memory — nothing is pushed to Cassis) and prints per-question results, so you can test the changes on your git branch before merging.
+- `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
+- `cassis eval add-case` adds a gold question/SQL case to the project's eval suite — after fixing an ontology issue, add the question users were failing on so `eval run` guards it from regressing.
 
 ## Install
 
@@ -77,6 +81,14 @@ cassis eval run --project ... --branch feature-x
 
 # Start the run and return immediately (poll in the webapp):
 cassis eval run --project ... --no-wait
+
+# Probe questions through the text-to-SQL agent using the local ontology files
+# (one full agent run per question, expect ~30-90s each; repeat -q for several):
+cassis ontology test --project ... -q "How much was refunded last month?" -q "Net revenue in Q1?"
+
+# Add a gold case to the eval suite (rejected if the exact question already exists):
+cassis eval add-case --project ... -q "How much was refunded last month?" \
+  --gold-sql "SELECT SUM(refunded_cents) / 100.0 FROM public.orders WHERE ..."
 ```
 
 Configuration (flags take precedence over env vars):
@@ -86,7 +98,7 @@ Configuration (flags take precedence over env vars):
 | `--api-key` | `CASSIS_API_KEY` | — (required)                |
 | `--api-url` | `CASSIS_API_URL` | `https://app.getcassis.com` |
 | `--base-path` | `CASSIS_BASE_PATH` | `cassis` — must match the project's git-sync "Path" setting |
-| `--project` (pull, upload, eval run) | `CASSIS_PROJECT_ID` | — (required)      |
+| `--project` (pull, upload, eval run, eval add-case, test) | `CASSIS_PROJECT_ID` | — (required)      |
 
 `cassis eval run` also accepts `--label` (run label in the Evals page; defaults
 to the branch name from the CI environment or the local git checkout; rejected
@@ -114,12 +126,12 @@ cassis ontology fmt --check
 
 | Code | Meaning                                                                        |
 | ---- | ------------------------------------------------------------------------------ |
-| 0    | Ontology is valid (check) / pulled (pull) / uploaded (upload) / eval run completed all-passed (eval run) |
-| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run) |
+| 0    | Ontology is valid (check) / pulled (pull) / uploaded (upload) / eval run completed all-passed (eval run) / every probe completed (test — whatever its outcome; probes are informational, don't gate CI on them) |
+| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed) |
 | 2    | Usage error (missing API key or project, no ontology directory, unreadable file, tree over the size limits) |
-| 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another run already active, or `--timeout` reached |
+| 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another run already active, out of credits, or `--timeout` reached |
 
-Commands that send the local tree (`check`, `upload`, `eval run`) accept up to
+Commands that send the local tree (`check`, `fmt`, `upload`, `eval run`, `test`) accept up to
 2000 YAML files / 5 MB total — far above real ontologies (a few hundred small
 files). Beyond that the CLI fails fast with exit 2 before uploading anything;
 double-check `--base-path` if you hit it.

{cassis_cli-0.4.0 → cassis_cli-1.0.0}/README.md

@@ -6,7 +6,11 @@ Run Cassis actions from your CI pipelines:
 - `cassis ontology fmt` rewrites the ontology files in canonical form (think `black`/`gofmt` for the ontology), so hand or agent edits pass the round-trip check.
 - `cassis ontology upload` uploads the ontology files to a Cassis project (full replace) and, by default, publishes them immediately as a new version — so a merge to your main branch can go live in one CI step.
 - `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local YAML files are pruned), so you can start editing from the current state, or bootstrap a repo that isn't git-synced (e.g. Bitbucket).
+- `cassis ontology pull` and `cassis ontology fmt` also write `<base-path>/AGENTS.md`, the Cassis ontology modeling guide, into the checkout (default `cassis/AGENTS.md`) — a managed file (generated banner; the CLI overwrites local edits) so a repo-aware coding agent loads current Cassis modeling doctrine by convention. It sits inside the ontology directory but is not part of the ontology tree (the CLI reads only `*.yml`/`*.yaml`), so it is never uploaded, validated, or pruned. Commit it alongside your ontology changes. The guide text ships inside the CLI package, so its version tracks the **installed cassis-cli version** — upgrade the CLI (`pip install -U cassis-cli`) and re-run `fmt` to pick up doctrine updates; an unpinned `pip install cassis-cli` in CI gets them automatically. The banner stamps a doctrine version, and the CLI never *downgrades* the file: if the checkout's `AGENTS.md` was written by a newer doctrine (a newer CLI, or Cassis itself on a publish), `fmt`/`pull` leave it in place, print an upgrade notice, and `fmt --check` still passes.
+- The CLI identifies itself to the API (`User-Agent: cassis-cli/<version>`), and successful API responses advertise the newest published version — when you are behind, commands print a one-line upgrade notice on stderr (purely informational; output and exit codes are unchanged).
 - `cassis eval run` runs the project's eval suite against your local ontology files (scored in-memory — nothing is pushed to Cassis) and prints per-question results, so you can test the changes on your git branch before merging.
+- `cassis ontology test` runs individual questions through the text-to-SQL agent using your local ontology files, so you can check that a change actually works (e.g. a new column gets picked) — where `eval run` only checks for regressions on existing eval cases.
+- `cassis eval add-case` adds a gold question/SQL case to the project's eval suite — after fixing an ontology issue, add the question users were failing on so `eval run` guards it from regressing.
 
 ## Install
 
@@ -57,6 +61,14 @@ cassis eval run --project ... --branch feature-x
 
 # Start the run and return immediately (poll in the webapp):
 cassis eval run --project ... --no-wait
+
+# Probe questions through the text-to-SQL agent using the local ontology files
+# (one full agent run per question, expect ~30-90s each; repeat -q for several):
+cassis ontology test --project ... -q "How much was refunded last month?" -q "Net revenue in Q1?"
+
+# Add a gold case to the eval suite (rejected if the exact question already exists):
+cassis eval add-case --project ... -q "How much was refunded last month?" \
+  --gold-sql "SELECT SUM(refunded_cents) / 100.0 FROM public.orders WHERE ..."
 ```
 
 Configuration (flags take precedence over env vars):
@@ -66,7 +78,7 @@ Configuration (flags take precedence over env vars):
 | `--api-key` | `CASSIS_API_KEY` | — (required)                |
 | `--api-url` | `CASSIS_API_URL` | `https://app.getcassis.com` |
 | `--base-path` | `CASSIS_BASE_PATH` | `cassis` — must match the project's git-sync "Path" setting |
-| `--project` (pull, upload, eval run) | `CASSIS_PROJECT_ID` | — (required)      |
+| `--project` (pull, upload, eval run, eval add-case, test) | `CASSIS_PROJECT_ID` | — (required)      |
 
 `cassis eval run` also accepts `--label` (run label in the Evals page; defaults
 to the branch name from the CI environment or the local git checkout; rejected
@@ -94,12 +106,12 @@ cassis ontology fmt --check
 
 | Code | Meaning                                                                        |
 | ---- | ------------------------------------------------------------------------------ |
-| 0    | Ontology is valid (check) / pulled (pull) / uploaded (upload) / eval run completed all-passed (eval run) |
-| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run) |
+| 0    | Ontology is valid (check) / pulled (pull) / uploaded (upload) / eval run completed all-passed (eval run) / every probe completed (test — whatever its outcome; probes are informational, don't gate CI on them) |
+| 1    | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run; test: invalid tree or a probe failed) |
 | 2    | Usage error (missing API key or project, no ontology directory, unreadable file, tree over the size limits) |
-| 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another run already active, or `--timeout` reached |
+| 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another run already active, out of credits, or `--timeout` reached |
 
-Commands that send the local tree (`check`, `upload`, `eval run`) accept up to
+Commands that send the local tree (`check`, `fmt`, `upload`, `eval run`, `test`) accept up to
 2000 YAML files / 5 MB total — far above real ontologies (a few hundred small
 files). Beyond that the CLI fails fast with exit 2 before uploading anything;
 double-check `--base-path` if you hit it.

{cassis_cli-0.4.0 → cassis_cli-1.0.0}/cassis_cli/__init__.py

@@ -1,3 +1,3 @@
 """Cassis CLI — run Cassis actions from your CI pipelines."""
 
-__version__ = "0.4.0"
+__version__ = "1.0.0"

{cassis_cli-0.4.0 → cassis_cli-1.0.0}/cassis_cli/api.py

@@ -2,13 +2,73 @@
 
 from __future__ import annotations
 
+import sys
 from typing import Any, Optional
 
 import httpx
+from cassis_cli import __version__
 
 DEFAULT_API_URL = "https://app.getcassis.com"
 TIMEOUT_SECONDS = 60.0
 
+USER_AGENT = f"cassis-cli/{__version__}"
+
+# Response header the CI endpoints set to the newest cassis-cli on PyPI.
+LATEST_VERSION_HEADER = "x-cassis-cli-latest"
+
+_upgrade_notice_shown = False
+
+
+def _version_tuple(version: str) -> Optional[tuple[int, ...]]:
+    try:
+        return tuple(int(part) for part in version.strip().split("."))
+    except ValueError:
+        return None
+
+
+def _maybe_print_upgrade_notice(response: httpx.Response) -> None:
+    """Print a one-time stderr notice when the server advertises a newer CLI.
+
+    Purely informational — never changes behavior or exit codes. Staying
+    current matters beyond bugfixes: the ontology modeling guide written to
+    ``cassis/AGENTS.md`` ships inside this package, so an old CLI keeps old
+    doctrine in the repo.
+    """
+    global _upgrade_notice_shown
+    if _upgrade_notice_shown:
+        return
+    latest = response.headers.get(LATEST_VERSION_HEADER)
+    if not latest:
+        return
+    mine, theirs = _version_tuple(__version__), _version_tuple(latest)
+    if mine is None or theirs is None:
+        return
+    # Zero-pad to equal length so "0.6" == "0.6.0" (same rule as the webapp's
+    # Agent setup page — the comparison logic exists on both surfaces).
+    width = max(len(mine), len(theirs))
+    if theirs + (0,) * (width - len(theirs)) <= mine + (0,) * (width - len(mine)):
+        return
+    _upgrade_notice_shown = True
+    print(
+        f"notice: cassis-cli {latest} is available (you have {__version__}) — "
+        "run `pip install -U cassis-cli`, then `cassis ontology fmt` to refresh cassis/AGENTS.md.",
+        file=sys.stderr,
+    )
+
+
+def _client(*, timeout: float = TIMEOUT_SECONDS, transport: Optional[httpx.BaseTransport] = None) -> httpx.Client:
+    """Build the HTTP client every API call goes through.
+
+    Identifies the CLI to the server (User-Agent) and watches responses for
+    the newer-version advertisement.
+    """
+    return httpx.Client(
+        timeout=timeout,
+        transport=transport,
+        headers={"User-Agent": USER_AGENT},
+        event_hooks={"response": [_maybe_print_upgrade_notice]},
+    )
+
 
 class ApiError(Exception):
     """Transport or HTTP-level failure talking to the Cassis API."""
@@ -52,6 +112,14 @@ def _project_scope_error(response: httpx.Response) -> ApiError:
     )
 
 
+def _detail_or_text(response: httpx.Response) -> Any:
+    """Return the error response's ``detail`` (str or structured), falling back to its body."""
+    try:
+        return response.json().get("detail") or response.text[:500]
+    except ValueError:
+        return response.text[:500]
+
+
 def _parse_json_response(response: httpx.Response, url: str) -> Any:
     try:
         return response.json()
@@ -71,7 +139,7 @@ def post_ontology_check(
     """POST the ontology tree to /api/ci/ontology-check and return the response body."""
     url = api_url.rstrip("/") + "/api/ci/ontology-check"
     try:
-        with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as client:
+        with _client(transport=transport) as client:
             response = client.post(
                 url,
                 json={"files": files},
@@ -110,7 +178,7 @@ def post_ontology_import(
     if label is not None:
         body["label"] = label
     try:
-        with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as client:
+        with _client(transport=transport) as client:
             response = client.post(
                 url,
                 json=body,
@@ -122,11 +190,7 @@ def post_ontology_import(
     if response.status_code == 401:
         raise AuthError("The Cassis API rejected the API key (invalid or expired).")
     if response.status_code == 400:
-        try:
-            detail = response.json().get("detail") or response.text[:500]
-        except ValueError:
-            detail = response.text[:500]
-        raise UploadValidationError(str(detail))
+        raise UploadValidationError(str(_detail_or_text(response)))
     if response.status_code in (403, 404):
         raise _project_scope_error(response)
     if response.status_code >= 400:
@@ -149,7 +213,7 @@ def get_ontology_export(
     """GET /api/ci/projects/{project_id}/ontology/export and return the files tree."""
     url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/ontology/export"
     try:
-        with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as client:
+        with _client(transport=transport) as client:
             response = client.get(url, headers={"Authorization": f"Bearer {api_key}"})
     except httpx.HTTPError as exc:
         raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
@@ -186,7 +250,7 @@ def post_eval_run_start(
     if label is not None:
         body["label"] = label
     try:
-        with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as client:
+        with _client(transport=transport) as client:
             response = client.post(url, json=body, headers={"Authorization": f"Bearer {api_key}"})
     except httpx.HTTPError as exc:
         raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
@@ -194,11 +258,7 @@ def post_eval_run_start(
     if response.status_code == 401:
         raise AuthError("The Cassis API rejected the API key (invalid or expired).")
     if response.status_code == 400:
-        try:
-            detail = response.json().get("detail") or response.text[:500]
-        except ValueError:
-            detail = response.text[:500]
-        raise EvalStartValidationError(detail)
+        raise EvalStartValidationError(_detail_or_text(response))
     if response.status_code == 409:
         raise EvalRunActiveError(
             "An eval run is already active for this project — wait for it to finish or cancel it "
@@ -214,10 +274,55 @@ def post_eval_run_start(
     return result
 
 
+class EvalCaseExistsError(ApiError):
+    """The project already has an eval case with this exact question."""
+
+
+class EvalCaseGoldSqlError(ApiError):
+    """The API rejected the gold SQL (400): it does not run against the project's data source."""
+
+
+def post_eval_case_create(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    question: str,
+    gold_sql: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST to /api/ci/projects/{project_id}/eval/cases and return the created case."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/eval/cases"
+    try:
+        with _client(transport=transport) as client:
+            response = client.post(
+                url,
+                json={"question": question, "gold_sql": gold_sql},
+                headers={"Authorization": f"Bearer {api_key}"},
+            )
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    if response.status_code == 409:
+        raise EvalCaseExistsError(str(_detail_or_text(response)))
+    if response.status_code == 400:
+        raise EvalCaseGoldSqlError(str(_detail_or_text(response)))
+    if response.status_code in (403, 404):
+        raise _project_scope_error(response)
+    if response.status_code >= 400:
+        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+    result = _parse_json_response(response, url)
+    if not isinstance(result, dict) or not all(key in result for key in ("id", "question", "gold_sql")):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
 def _get_eval_json(url: str, api_key: str, transport: Optional[httpx.BaseTransport]) -> Any:
     """GET an eval-run URL with the shared error mapping."""
     try:
-        with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as client:
+        with _client(transport=transport) as client:
             response = client.get(url, headers={"Authorization": f"Bearer {api_key}"})
     except httpx.HTTPError as exc:
         raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
@@ -274,7 +379,7 @@ def post_eval_run_cancel(
     """POST /api/ci/projects/{project_id}/eval/runs/{run_id}/cancel."""
     url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/eval/runs/{run_id}/cancel"
     try:
-        with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as client:
+        with _client(transport=transport) as client:
             response = client.post(url, headers={"Authorization": f"Bearer {api_key}"})
     except httpx.HTTPError as exc:
         raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
@@ -296,7 +401,7 @@ def post_ontology_fmt(
     """POST the ontology tree to /api/ci/ontology-fmt and return the response body."""
     url = api_url.rstrip("/") + "/api/ci/ontology-fmt"
     try:
-        with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as client:
+        with _client(transport=transport) as client:
             response = client.post(
                 url,
                 json={"files": files},
@@ -320,3 +425,59 @@ def post_ontology_fmt(
     ):
         raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
     return result
+
+
+# The server-side probe budget is 300s; leave headroom for transport.
+ONTOLOGY_TEST_TIMEOUT_SECONDS = 330.0
+
+
+class OntologyTestValidationError(ApiError):
+    """The API rejected the ontology tree as invalid (400).
+
+    ``detail`` keeps the structured payload (``{"message", "findings"}``) for
+    display.
+    """
+
+    def __init__(self, detail: object) -> None:
+        super().__init__(str(detail))
+        self.detail = detail
+
+
+def post_ontology_test(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    files: dict[str, str],
+    question: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST to /api/ci/projects/{project_id}/ontology/test and return the probe outcome.
+
+    Blocks for the duration of the agent run (up to ~5 minutes server-side).
+    """
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/ontology/test"
+    try:
+        with _client(timeout=ONTOLOGY_TEST_TIMEOUT_SECONDS, transport=transport) as client:
+            response = client.post(
+                url,
+                json={"files": files, "question": question},
+                headers={"Authorization": f"Bearer {api_key}"},
+            )
+    except httpx.HTTPError as exc:
+        raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    if response.status_code == 400:
+        raise OntologyTestValidationError(_detail_or_text(response))
+    if response.status_code == 402:
+        raise ApiError("Your organization has run out of credits. Contact your administrator to top up.")
+    if response.status_code in (403, 404):
+        raise _project_scope_error(response)
+    if response.status_code >= 400:
+        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+    result = _parse_json_response(response, url)
+    if not isinstance(result, dict) or "status" not in result:
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result

{cassis_cli-0.4.0 → cassis_cli-1.0.0}/cassis_cli/eval.py

@@ -15,10 +15,13 @@ from cassis_cli.api import (
     DEFAULT_API_URL,
     ApiError,
     AuthError,
+    EvalCaseExistsError,
+    EvalCaseGoldSqlError,
     EvalRunActiveError,
     EvalStartValidationError,
     get_eval_run,
     get_eval_run_results,
+    post_eval_case_create,
     post_eval_run_cancel,
     post_eval_run_start,
 )
@@ -139,6 +142,79 @@ def _print_summary(run: dict[str, Any]) -> None:
     typer.echo(", ".join(parts))
 
 
+@app.command(name="add-case")
+def add_case(
+    project_id: str = typer.Option(
+        ...,
+        "--project",
+        envvar="CASSIS_PROJECT_ID",
+        help="Target Cassis project ID (UUID, shown in the project's URL).",
+    ),
+    question: str = typer.Option(
+        ...,
+        "-q",
+        "--question",
+        help="The natural-language question the case guards.",
+    ),
+    gold_sql: str = typer.Option(
+        ...,
+        "--gold-sql",
+        help="The correct SQL for the question; executed at run time to produce the expected output.",
+    ),
+    api_key: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        envvar="CASSIS_API_KEY",
+        help="Cassis API key (sk-k6-...). Create one in Organization settings -> API keys.",
+    ),
+    api_url: str = typer.Option(
+        DEFAULT_API_URL,
+        "--api-url",
+        envvar="CASSIS_API_URL",
+        help="Cassis API base URL.",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Print the created case as raw JSON."),
+) -> None:
+    """Add a gold test case to the project's eval suite.
+
+    Closes the loop after fixing an ontology issue: the question users were
+    failing on becomes a gold case, so `cassis eval run` guards it from
+    regressing. On an executable data source the gold SQL is run before the
+    case is stored, so a case that cannot execute never enters the suite.
+    Exits 0 on creation, 1 on a duplicate question or gold SQL that does not
+    run, 2 on usage errors, 3 on transport/API errors.
+    """
+    api_key = require_api_key(api_key)
+    try:
+        UUID(project_id)
+    except ValueError:
+        typer.secho(f"--project must be a project ID (UUID), got {project_id!r}.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE)
+    if not question.strip() or not gold_sql.strip():
+        typer.secho("--question and --gold-sql must not be empty.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE)
+
+    try:
+        case = post_eval_case_create(
+            api_url=api_url, api_key=api_key, project_id=project_id, question=question, gold_sql=gold_sql
+        )
+    except (EvalCaseExistsError, EvalCaseGoldSqlError) as exc:
+        typer.secho(str(exc), fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(EXIT_VALIDATION_FAILED) from exc
+    except AuthError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_TRANSPORT) from exc
+    except ApiError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_TRANSPORT) from exc
+
+    if json_output:
+        typer.echo(json.dumps(case, indent=2))
+    else:
+        typer.secho(f"✓ Added eval case {case['id']}: {case['question']}", fg=typer.colors.GREEN)
+    raise typer.Exit(EXIT_OK)
+
+
 @app.command()
 def run(
     path: Path = typer.Argument(

cassis_cli-1.0.0/cassis_cli/guide.py

@@ -0,0 +1,97 @@
+"""The ontology modeling guide the CLI writes into a git-synced checkout.
+
+``ontology_design_guide.md`` in this package is a byte-for-byte copy of the
+canonical ``docs/ontology-design-guide.md`` (a repo-root test enforces they stay
+identical — the backend image doesn't ship ``docs/``, so the CLI carries its own
+copy). ``pull`` writes it into the checkout as ``<base_path>/AGENTS.md`` and
+``fmt`` keeps it canonical, so a repo-aware agent loads current Cassis modeling
+doctrine by convention. The file is managed: a banner marks it generated and the
+CLI overwrites local edits, exactly as ``fmt`` rewrites drifted ontology YAML.
+
+Two writers manage the file — this CLI and the Cassis server's git export — and
+they may run different doctrine versions (the guide ships inside each). The
+banner stamps its ``DOCTRINE_VERSION`` so an older CLI never *downgrades* a
+guide a newer writer produced: ``refresh_guide`` leaves a newer-stamped file in
+place and the CLI tells the user to upgrade instead.
+
+``AGENTS.md`` sits inside the ontology base path but is never part of the
+ontology tree — ``collect_files`` globs only ``*.yml`` / ``*.yaml``, so check,
+fmt-of-YAML, upload, and pull-prune all ignore it.
+"""
+
+from __future__ import annotations
+
+import re
+from importlib import resources
+from pathlib import Path
+from typing import Literal
+
+GUIDE_FILENAME = "AGENTS.md"
+
+# Monotonic version of the doctrine text below. Bump it whenever
+# ontology_design_guide.md changes (a backend test enforces the pairing) — it
+# is what lets an older writer recognize a newer guide and leave it alone.
+DOCTRINE_VERSION = 1
+
+# Must stay byte-identical to backend/app/services/ontology_guide.py::_BANNER —
+# the server-side git export writes the same file, and differing banners would
+# make the two writers churn the file against each other.
+_BANNER = (
+    "<!--\n"
+    f"Generated by Cassis — the ontology modeling guide (doctrine v{DOCTRINE_VERSION}).\n"
+    "Do NOT edit: Cassis and cassis-cli (`ontology pull` / `ontology fmt`) overwrite this file.\n"
+    "-->\n\n"
+)
+
+_DOCTRINE_VERSION_RE = re.compile(r"doctrine v(\d+)\b")
+
+GuideStatus = Literal["current", "stale", "newer", "missing"]
+
+
+def canonical_guide() -> str:
+    """Return the managed ``AGENTS.md`` content: banner + the packaged guide."""
+    body = resources.files("cassis_cli").joinpath("ontology_design_guide.md").read_text(encoding="utf-8")
+    return _BANNER + body
+
+
+def guide_status(ontology_dir: Path) -> GuideStatus:
+    """Classify ``<ontology_dir>/AGENTS.md`` against the guide this CLI carries.
+
+    - ``current``: byte-identical to what this CLI would write.
+    - ``newer``: stamped with a higher doctrine version (written by a newer
+      CLI or by the Cassis server) — must not be overwritten by this CLI.
+    - ``stale``: anything else that exists (older doctrine, local edits, or an
+      unversioned banner).
+    - ``missing``: absent or unreadable.
+    """
+    try:
+        existing = (ontology_dir / GUIDE_FILENAME).read_text(encoding="utf-8")
+    except OSError:
+        return "missing"
+    if existing == canonical_guide():
+        return "current"
+    # Only a leading banner comment carries the stamp — the guide body may
+    # legitimately mention "doctrine vN" as prose, and a hand-written file has
+    # no banner at all. Both must read as "stale", never as "newer" (which is
+    # never repaired and nags the user to upgrade a CLI that is already current).
+    if existing.lstrip().startswith("<!--") and "-->" in existing:
+        match = _DOCTRINE_VERSION_RE.search(existing.split("-->", 1)[0])
+        if match is not None and int(match.group(1)) > DOCTRINE_VERSION:
+            return "newer"
+    return "stale"
+
+
+def refresh_guide(ontology_dir: Path) -> GuideStatus:
+    """Bring ``<ontology_dir>/AGENTS.md`` up to this CLI's doctrine, never down.
+
+    Writes the managed guide when the file is ``stale`` or ``missing``; leaves
+    ``current`` and ``newer`` files untouched. Returns the status found before
+    writing, so the caller can report what happened (and nudge an upgrade on
+    ``newer``). Raises OSError on a local write failure (the caller maps it to
+    a usage-level exit).
+    """
+    status = guide_status(ontology_dir)
+    if status in ("stale", "missing"):
+        ontology_dir.mkdir(parents=True, exist_ok=True)
+        (ontology_dir / GUIDE_FILENAME).write_text(canonical_guide(), encoding="utf-8")
+    return status

{cassis_cli-0.4.0 → cassis_cli-1.0.0}/cassis_cli/ontology.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
-from typing import Optional
+from typing import List, Optional
 from uuid import UUID
 
 import typer
@@ -12,11 +12,13 @@ from cassis_cli.api import (
     DEFAULT_API_URL,
     ApiError,
     AuthError,
+    OntologyTestValidationError,
     UploadValidationError,
     get_ontology_export,
     post_ontology_check,
     post_ontology_fmt,
     post_ontology_import,
+    post_ontology_test,
 )
 from cassis_cli.common import (
     DEFAULT_BASE_PATH,
@@ -28,10 +30,25 @@ from cassis_cli.common import (
 from cassis_cli.common import collect_files as _collect_files
 from cassis_cli.common import collect_tree as _collect_tree
 from cassis_cli.common import require_api_key as _require_api_key
+from cassis_cli.guide import DOCTRINE_VERSION, GUIDE_FILENAME, guide_status, refresh_guide
 
 app = typer.Typer(no_args_is_help=True, help="Ontology commands.")
 
 
+def _warn_newer_guide(base_path: str) -> None:
+    """Tell the user their checkout's AGENTS.md outruns this CLI's doctrine.
+
+    A newer-stamped guide (written by a newer CLI or by the Cassis server) is
+    never overwritten — the fix is upgrading the CLI, so say so and move on.
+    """
+    typer.secho(
+        f"notice: {base_path}/{GUIDE_FILENAME} carries a newer Cassis doctrine than this CLI "
+        f"(v{DOCTRINE_VERSION}) — leaving it in place; run `pip install -U cassis-cli` to update.",
+        fg=typer.colors.YELLOW,
+        err=True,
+    )
+
+
 @app.command()
 def check(
     path: Path = typer.Argument(
@@ -183,12 +200,26 @@ def pull(
                 raise typer.Exit(EXIT_USAGE) from exc
             deleted.append(rel)
 
+    # Managed modeling guide: refresh AGENTS.md so a repo-aware agent loads
+    # current Cassis doctrine. Not part of the ontology tree (YAML-only), so it
+    # was neither pulled above nor pruned.
+    try:
+        guide_state = refresh_guide(ontology_dir)
+    except OSError as exc:
+        typer.secho(f"Cannot write {ontology_dir / GUIDE_FILENAME}: {exc}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE) from exc
+    guide_written = guide_state in ("stale", "missing")
+    if guide_state == "newer":
+        _warn_newer_guide(base_path)
+
     if json_output:
-        typer.echo(json.dumps({"written": written, "deleted": deleted}, indent=2))
+        typer.echo(json.dumps({"written": written, "deleted": deleted, "guide_written": guide_written}, indent=2))
     else:
         summary = f"✓ Pulled {len(written)} files into {ontology_dir}"
         if deleted:
             summary += f" ({len(deleted)} stale files deleted)"
+        if guide_written:
+            summary += f"; wrote {base_path}/{GUIDE_FILENAME}"
         typer.secho(f"{summary}.", fg=typer.colors.GREEN)
     raise typer.Exit(EXIT_OK)
 
@@ -346,7 +377,16 @@ def fmt(
 
     changed = result["changed_paths"]
     removed = result["removed_paths"]
-    if not changed and not removed:
+    # The managed AGENTS.md guide is canonicalized alongside the YAML tree
+    # (it isn't in the tree, so the server round-trip above never sees it).
+    # A guide stamped with a NEWER doctrine than this CLI carries is left
+    # alone and does not fail --check: the repo is fine, the CLI is old.
+    guide_state = guide_status(ontology_dir)
+    guide_stale = guide_state in ("stale", "missing")
+    if guide_state == "newer":
+        _warn_newer_guide(base_path)
+
+    if not changed and not removed and not guide_stale:
         typer.secho(f"✓ {len(files)} file(s) already canonical.", fg=typer.colors.GREEN)
         raise typer.Exit(EXIT_OK)
 
@@ -355,6 +395,8 @@ def fmt(
             typer.echo(f"would rewrite {base_path}/{p}")
         for p in removed:
             typer.echo(f"would remove {base_path}/{p}")
+        if guide_stale:
+            typer.echo(f"would rewrite {base_path}/{GUIDE_FILENAME}")
         raise typer.Exit(EXIT_VALIDATION_FAILED)
 
     for p in changed:
@@ -365,10 +407,160 @@ def fmt(
     for p in removed:
         (ontology_dir / p).unlink(missing_ok=True)
         typer.echo(f"removed {base_path}/{p}")
-    typer.secho(
-        f"Formatted {len(changed)} file(s)"
-        + (f", removed {len(removed)}" if removed else "")
-        + ". Review the diff: fields Cassis does not recognize are dropped.",
-        fg=typer.colors.YELLOW,
-    )
+    if guide_stale:
+        try:
+            refresh_guide(ontology_dir)
+        except OSError as exc:
+            typer.secho(f"Cannot write {ontology_dir / GUIDE_FILENAME}: {exc}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_USAGE) from exc
+        typer.echo(f"rewrote {base_path}/{GUIDE_FILENAME}")
+
+    if changed or removed:
+        typer.secho(
+            f"Formatted {len(changed)} file(s)"
+            + (f", removed {len(removed)}" if removed else "")
+            + ". Review the diff: fields Cassis does not recognize are dropped.",
+            fg=typer.colors.YELLOW,
+        )
+    else:
+        # Only the guide was refreshed — the "rewrote ..." line above already said so.
+        typer.secho(f"✓ {len(files)} file(s) already canonical.", fg=typer.colors.GREEN)
     raise typer.Exit(EXIT_OK)
+
+
+@app.command()
+def test(
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository checkout root (the directory containing the ontology export path).",
+    ),
+    question: List[str] = typer.Option(
+        ...,
+        "--question",
+        "-q",
+        help="Natural-language question to probe (repeat for several).",
+    ),
+    project_id: str = typer.Option(
+        ...,
+        "--project",
+        envvar="CASSIS_PROJECT_ID",
+        help="Target Cassis project ID (UUID, shown in the project's URL).",
+    ),
+    api_key: Optional[str] = typer.Option(
+        None,
+        "--api-key",
+        envvar="CASSIS_API_KEY",
+        help="Cassis API key (sk-k6-...). Create one in Organization settings -> API keys.",
+    ),
+    api_url: str = typer.Option(
+        DEFAULT_API_URL,
+        "--api-url",
+        envvar="CASSIS_API_URL",
+        help="Cassis API base URL.",
+    ),
+    base_path: str = typer.Option(
+        DEFAULT_BASE_PATH,
+        "--base-path",
+        envvar="CASSIS_BASE_PATH",
+        help="Repository directory the ontology is exported under (the project's git-sync Path setting).",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Print the raw JSON outcomes."),
+) -> None:
+    """Run questions through the text-to-SQL agent using your local ontology files.
+
+    The behavioral probe: checks that a change actually WORKS — e.g. that a
+    new column gets picked —
+    where `cassis eval run` only checks for regressions on existing gold
+    cases. Each question is one full agent run (expect ~30-90s each); nothing
+    is persisted server-side. The outcome is informational, not a gate: read
+    the SQL and answer, don't wire the exit code into CI verdicts. Exits 0
+    when every probe completed (whatever its outcome), 1 when the tree is
+    invalid or a probe failed, 2 on usage errors, 3 on transport errors.
+    """
+    api_key = _require_api_key(api_key)
+    try:
+        UUID(project_id)
+    except ValueError:
+        typer.secho(f"--project must be a project ID (UUID), got {project_id!r}.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE)
+    files, base_path = _collect_tree(path, base_path)
+
+    outcomes: "list[dict]" = []
+    failed = False
+    for q in question:
+        try:
+            outcome = post_ontology_test(
+                api_url=api_url, api_key=api_key, project_id=project_id, files=files, question=q
+            )
+        except OntologyTestValidationError as exc:
+            _print_test_validation_failure(exc.detail, base_path)
+            raise typer.Exit(EXIT_VALIDATION_FAILED) from exc
+        except AuthError as exc:
+            typer.secho(str(exc), fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_TRANSPORT) from exc
+        except ApiError as exc:
+            typer.secho(str(exc), fg=typer.colors.RED, err=True)
+            raise typer.Exit(EXIT_TRANSPORT) from exc
+        outcomes.append(outcome)
+        if not json_output:
+            _print_test_outcome(q, outcome)
+        if outcome.get("status") != "completed":
+            failed = True
+
+    if json_output:
+        # Always a list, regardless of how many questions ran — scripts
+        # shouldn't have to branch on the shape.
+        typer.echo(json.dumps(outcomes, indent=2))
+    raise typer.Exit(EXIT_VALIDATION_FAILED if failed else EXIT_OK)
+
+
+def _print_test_validation_failure(detail: object, base_path: str) -> None:
+    """Print a structured 400 from the test endpoint (invalid tree findings, or a plain message)."""
+    if isinstance(detail, dict) and isinstance(detail.get("findings"), list):
+        typer.secho("Ontology validation failed:", fg=typer.colors.RED, bold=True, err=True)
+        message = detail.get("message")
+        if message:
+            typer.echo(message, err=True)
+        for finding in detail["findings"]:
+            location = f"{base_path}/{finding.get('path')}: " if finding.get("path") else ""
+            typer.echo(f"  {location}{finding.get('message', '')} ({finding.get('stage', '?')})", err=True)
+    else:
+        typer.secho(str(detail), fg=typer.colors.RED, err=True)
+
+
+_TEST_RESULT_ROWS_SHOWN = 10
+
+
+def _print_test_outcome(question: str, outcome: "dict") -> None:
+    typer.secho(f"▶ {question}", bold=True)
+    if outcome.get("status") != "completed":
+        typer.secho(f"  probe failed: {outcome.get('error', 'unknown error')}", fg=typer.colors.RED)
+        if outcome.get("generated_sql"):
+            typer.echo(f"  SQL before failure:\n{_indent(outcome['generated_sql'])}")
+        return
+    run_status = outcome.get("run_status", "?")
+    color = typer.colors.GREEN if run_status == "success" else typer.colors.YELLOW
+    duration = f" ({outcome['duration_seconds']:.0f}s)" if outcome.get("duration_seconds") is not None else ""
+    typer.secho(f"  {run_status}{duration}", fg=color)
+    if outcome.get("generated_sql"):
+        typer.echo(_indent(outcome["generated_sql"]))
+    if outcome.get("answer"):
+        typer.echo(f"  Answer: {outcome['answer']}")
+    results = outcome.get("results")
+    # None means the SQL was never executed (schema-only source); an empty
+    # list means the query ran and returned nothing — show the distinction.
+    if results is not None:
+        total = outcome.get("total_rows", len(results))
+        typer.echo(f"  Results ({total} row{'s' if total != 1 else ''}):")
+        for row in results[:_TEST_RESULT_ROWS_SHOWN]:
+            typer.echo(f"    {row}")
+        if len(results) > _TEST_RESULT_ROWS_SHOWN or outcome.get("truncated"):
+            typer.echo("    ...")
+    for concept in outcome.get("missing_concepts") or []:
+        typer.secho(f"  missing concept: {concept}", fg=typer.colors.YELLOW)
+    for warning in outcome.get("warnings") or []:
+        typer.secho(f"  warning: {warning}", fg=typer.colors.YELLOW)
+
+
+def _indent(text: str) -> str:
+    return "\n".join(f"    {line}" for line in text.splitlines())

cassis_cli-1.0.0/cassis_cli/ontology_design_guide.md

@@ -0,0 +1,405 @@
+# Cassis Ontology Design Guide
+
+This is the canonical guide to modeling a Cassis ontology well. It is written for
+whoever edits the ontology — a person or an AI agent — working in the project's
+git repository. The rules here are not style preference: they follow from **how
+the text-to-SQL agent actually reads the ontology**, so breaking them produces
+wrong SQL, not just messy files.
+
+Read this before proposing an ontology change.
+
+---
+
+## 1. What a Cassis ontology is
+
+The ontology is the curated business context the agent uses to translate a
+natural-language question into SQL. It has five kinds of object plus one
+project-level field, edited as YAML files under the repository's ontology
+directory (`cassis/` by default):
+
+| Layer | What it is | Key fields |
+|---|---|---|
+| **Root context** (`_project.yml → context_md`) | One free-text block, always in the agent's prompt | markdown |
+| **Domains** | A navigable tree grouping the business by subject area | `path`, `display_name`, `description`, `context_md` |
+| **Tables** | A physical warehouse table (introspected) or a virtual one (SQL-defined) placed in a domain | `name` (`schema.TABLE`), `description`, `synonyms`, `grain`, columns |
+| **Columns** | Enrichment on a table's columns | `description`, `unit`, `synonyms` |
+| **Joins** | A known way two tables relate | `from_schema`/`from_table`, `to_schema`/`to_table`, `column_pairs`, `condition_sql`, `cardinality`, `description` |
+| **Metrics** | A reusable business measure | `name`, `display_name`, `expression`, `table_schema`/`table_name`, `filters`, `unit`, `synonyms`, `notes`, `precomputed_in` |
+
+On disk, the export layout is fixed — create each object in its canonical home
+(`cassis ontology fmt` normalizes drift, but start in the right place):
+
+```
+cassis/                          (the git-sync base path)
+  _project.yml                   root context (context_md), project display name
+  domains/<path>/_domain.yml     one per domain, nested by path
+  tables/<schema>/<table>.yml    one per table, columns inline
+  metrics/<name>.yml             one per metric
+  joins.yml                      ALL joins, one list in one file
+```
+
+Joins and metrics are never embedded inside a table's file, and a table's file
+never carries keys the schema doesn't define — unknown keys are dropped at sync
+time (run `cassis ontology fmt` to see what would be lost).
+
+The **published** ontology is an immutable numbered snapshot — what production
+answers from. The **unpublished** ontology is the editable state (the published
+base plus unpublished changes). In a git-synced project the repository *is* the
+edit surface: you edit the YAML, open a pull request, and merging syncs and
+publishes it.
+
+Physical tables and their columns come from schema introspection — you never
+invent them; you *enrich* them (place them in a domain, describe them, set units
+and synonyms). The one exception is a virtual table, which you define with a
+`sql` body (see §5).
+
+The one governing principle everything below serves:
+
+> **Each fact lives in exactly one place, at the most specific layer that fully
+> owns it. Never duplicate across layers. Never hand-write what the agent already
+> reads automatically.**
+
+---
+
+## 2. How the agent reads your ontology
+
+The agent has no other ground truth. It does not see the warehouse, the dbt
+project, or the raw schema — only the strings in the ontology. If a fact isn't
+there, it doesn't exist for the agent; if a string contradicts the data, the
+agent confidently writes wrong SQL. Three mechanics drive every rule that follows.
+
+**Retrieval is structured and automatic.** The agent navigates the domain tree
+with a `get(path)` call and inspects a table with `get_table("schema.TABLE")`.
+These assemble structured fields for free:
+
+- `get(path)` returns the domain's `context_md` **plus** each direct sub-domain
+  (`path`, `display_name`, `description`), each table (`name`, `description`,
+  `synonyms`, `grain`), and each metric (full definition).
+- `get_table("schema.TABLE")` returns the table's columns, `grain`, and its
+  **joins** (each with its condition, cardinality, and description).
+- The **root** domain — its `root_context`, direct children, root tables, root
+  metrics — is injected into the prompt at the start of every conversation.
+
+Because those fields are surfaced automatically, **restating them in prose is
+pure redundancy** — and redundant copies drift, which is how the ontology starts
+lying to the agent. `context_md` and `description` are for the connective tissue
+the structured fields can't carry, nothing the fields already carry.
+
+**Minimum tokens to answer.** Every byte the agent reads costs context, and a
+real ontology does not fit in the prompt at once — it is retrieved piecemeal.
+Keep free-text fields concise; don't state what the object's own name already
+makes obvious; watch your largest tables, since column count drives rendered
+cost.
+
+**Vocabulary in prose fields is the only vocabulary the agent has.** In prose
+fields (descriptions, `context_md`, root context) refer to tables by their
+`schema.TABLE` ontology name, never by some other alias the agent can't map back.
+In SQL-bearing fields (a metric's `expression`/`filters`, a virtual table's
+`sql`, a join's `condition_sql`) use real physical identifiers — those are SQL
+and must match the warehouse (see §7).
+
+---
+
+## 3. The placement contract
+
+Put each fact at the lowest layer that fully owns it:
+
+```
+column synonym / column description      single-column facts: meaning, encoding, unit, date format, nulls
+  → table description                    single-table facts: grain, scope, mandatory filters, "use this not that"
+    → domain context_md                  cross-table routing, disambiguation, vocabulary spanning tables
+      → root context                     truly global rules only: corporate identity, entity hierarchy, global conventions
+```
+
+Plus two non-prose homes that pull facts *out* of prose entirely:
+
+- A **recurring calculation that encodes a business rule** → a **metric**, not a
+  sentence.
+- **How two tables relate** → a **join**, not a "joins to X on Y" note.
+
+A fact written one layer too high is redundant (the tool already surfaces the
+lower layer) or stranded where the agent won't look. A fact written one layer too
+low can't express the cross-object relationship it's really about. The test for
+`context_md`: imagine pushing the fact one domain level deeper — if that would
+force you to copy it across sibling sub-domains, it belongs at this shared level;
+otherwise push it down.
+
+**Never restate the structured fields:**
+
+- Direct sub-domains are surfaced with their descriptions → no "Sub-domains: …"
+  lists. If a child reads too thin to stand alone, fix its `description`; don't
+  re-list it in the parent.
+- Tables are surfaced with description, synonyms, grain → no `## Tables` block.
+  Per-table facts go on that table's `description`; keep only genuinely
+  cross-table routing in `context_md`.
+- Metrics are surfaced with their full definition → don't re-paste a formula in
+  prose. Point to a metric by name **only** when it lives in a *different* domain
+  than the prose discussing it; a domain's own metrics are surfaced alongside its
+  `context_md` already.
+- Joins are surfaced with their condition and cardinality → don't enumerate join
+  keys in prose. The only join content that belongs in prose is a join+filter
+  *recipe* no single structured join can express.
+
+---
+
+## 4. Domains and `context_md`
+
+Build a domain hierarchy that mirrors **how the business thinks about its data**,
+not the raw schema layout. Nest as deep as the structure genuinely warrants
+(there is no level cap), but don't add a level that carries no distinct context of
+its own — an empty navigational domain is just noise. Every table and every
+metric names a `domain_path` that must resolve to a domain you've declared (or the
+root, `""`).
+
+A useful convention inside `context_md`: a `## Terms` section for the domain's
+vocabulary and disambiguation, and a `## Notes` section for routing hints and
+scope caveats. Omit either if you have nothing for it.
+
+`context_md` carries only the connective tissue the structured fields can't:
+
+- **Cross-table routing and disambiguation** — which table answers which
+  question; "two different 'active users'" and which to use when.
+- **Business rules, scope and temporal caveats, aggregation traps** that span
+  more than one object.
+- **Vocabulary / glossary** that maps to no single table (acronyms, internal
+  project names, business terms).
+- A short **orientation paragraph** for a navigational domain.
+- Markdown **links** to related domains, using the resolvable domain path
+  (`[berries](play/features/berries)`), not a bare filename.
+
+**Root context** — the `context_md` in `_project.yml`, injected into every
+conversation — **holds only what applies across almost every query:** corporate
+identity, the core entity hierarchy (how the central models relate — e.g. "users
+belong to companies via enrollments; primary enrollments are employees, partner
+and child are dependents"), global country/timestamp/currency conventions,
+default population exclusions, and cross-cutting vocabulary that maps to no single
+domain. Everything domain-specific moves down.
+
+---
+
+## 5. Tables
+
+A table's `description` answers *"what is this, and what must the SQL agent know
+to use it correctly?"* — business meaning **plus** the correctness facts (scope,
+mandatory filters, gotchas). Always **state the grain explicitly** ("one row per
+order"; "one row per (user_id, day)") so the agent aggregates correctly, and set
+the `grain` field to the identifying column(s). Don't enumerate the columns — the
+column list is surfaced automatically.
+
+Use `synonyms` for alternate names a user might say ("purchases", "transactions"),
+never an "also known as" sentence in the description.
+
+When a table's rows have non-obvious semantics, put the rule in the description:
+a table that keeps one row per entity chosen by a priority ordering, a
+`GROUPING SETS` table whose discriminator column must be filtered to avoid
+double-counting, a JSON/array column and how to query it. Don't silently omit a
+messy column — surface it with guidance.
+
+**Virtual tables are a last resort — almost never the right answer.** A virtual
+table is a `sql`-defined `SELECT` placed in the ontology. Do **not** reach for one
+to hold a single field, a metric, or a simple rollup: use a **metric** for a
+recurring calculation, a **column** description to clarify a field, a **join** to
+relate two tables, or **enrich an existing physical table**. A virtual table is
+justified only when a genuinely complex object cannot be represented by any
+physical table — e.g. extracting structured rows out of a nested JSON/blob
+column, or reshaping an entity split across an unusable physical layout. When you
+do create one, prefer selecting from existing physical tables (don't duplicate a
+fact table), list its columns so they can be enriched, and quote/case identifiers
+in the `sql` per §7.
+
+---
+
+## 6. Columns
+
+Column enrichment is `description`, `unit`, and `synonyms` — you cannot add or
+rename columns (they come from introspection). The `description` is the SQL
+agent's only per-column guidance, so it carries both the semantic meaning and the
+SQL-correctness facts: possible values, encoding, units, date format, null
+behavior, any mandatory filter.
+
+- **Prioritize the trap columns.** Disambiguate similarly-named columns
+  (`created_at` vs `updated_at`, `amount` vs `net_amount`), numeric-encoded
+  columns, numbers-that-are-timestamps, dates-stored-as-text. Skip the
+  self-explanatory ones — a description that just restates the column name is
+  wasted tokens.
+- **Set `unit`** whenever a number is a currency, percentage, or duration —
+  aggregation correctness depends on it.
+- **Use `synonyms`** for 1–3 short, plain alternate terms a user might use.
+- **Keep the join key queryable.** A foreign-key column stays a real, described
+  column even when a join covers the relationship — hiding it leaves the agent
+  unable to filter or group on it without traversing the join. Test: imagine a
+  question that filters or groups by this column *directly*. If you can, describe
+  it; if the column only ever appears via the join, it needs less attention.
+
+---
+
+## 7. Joins
+
+All joins live in the single `joins.yml` file, one list entry per join. An entry
+names its two endpoints with schema and table split into separate keys, carries
+the joined column pairs, and the `condition_sql` — the ON-clause boolean
+expression, with every column table-qualified and quoted in the warehouse
+dialect. Add a business `description` and set `cardinality` (`one_to_one` /
+`one_to_many` / `many_to_one` / `many_to_many`, read from the `from` side to the
+`to` side):
+
+```yaml
+- from_schema: public
+  from_table: orders
+  to_schema: public
+  to_table: customers
+  column_pairs:
+  - from_column: customer_id
+    to_column: id
+  condition_sql: '"public"."orders"."customer_id" = "public"."customers"."id"'
+  cardinality: many_to_one
+  description: Each order is placed by exactly one customer.
+```
+
+Fill in both `column_pairs` and `condition_sql` — the agent is shown both.
+
+- Cover every foreign key and every obvious `*_id` reference between tables. FK
+  joins are pre-seeded from introspection — confirm them and add a description;
+  then add the ones the heuristic missed (columns whose names diverge across the
+  two tables, or relationships that go through a bridge table).
+- **Join forms:** a simple join is a single-column equality
+  (`a.x = b.y`); a **composite** join ANDs the equalities
+  (`a.x = b.x AND a.y = b.y`); a **filtered** join ANDs a filter
+  (`a.x = b.y AND b.type = 'order'`); a **functional** join uses a function
+  (`DATE_TRUNC('day', b.ts) = a.day`).
+- **Avoid join explosion — the single biggest failure mode.** A column shared by
+  many tables (`country_id`) must **not** get a join between every pair; it
+  degrades agent quality badly. Pick one hub table for a shared key and link the
+  peers to it (hub-and-spoke). Coincidental column-name matches — two unrelated
+  tables that both happen to have a `contract_id` — get **no** join.
+
+---
+
+## 8. Metrics
+
+Define a metric when a calculation **recurs and encodes a business rule** — e.g.
+revenue net of refunds, active-user counts with a specific definition. Don't turn
+every column into a metric.
+
+- `expression` is the **aggregation expression only** (`SUM(net_amount)`,
+  `COUNT(DISTINCT customer_id)`), never a full `SELECT`.
+- `table_schema` + `table_name` name the base table it aggregates over (omit
+  only for a genuinely cross-table metric).
+- `filters` is any mandatory `WHERE` condition always applied
+  (`status <> 'cancelled'`).
+- `unit` for non-obvious result quantities; `synonyms` for alternate names;
+  `precomputed_in` the `schema.TABLE` of a rollup that already materializes it, if
+  one exists.
+
+One file per metric under `metrics/<name>.yml`:
+
+```yaml
+name: net_revenue
+display_name: Net Revenue
+domain_path: sales
+table_schema: public
+table_name: orders
+expression: SUM(amount_cents - refunded_cents)
+filters: status NOT IN ('cancelled', 'refunded')
+unit: euro cents
+synonyms:
+- net sales
+- revenue net of refunds
+description: Gross order amount minus refunds, excluding cancelled and refunded orders.
+```
+
+A metric definition beats a prose "revenue = net revenue excluding tax" note —
+the metric is surfaced structurally and can be reused; the prose drifts.
+
+---
+
+## 9. Identifiers and case — where SQL silently breaks
+
+A stored `name` on a table or column is a **physical identifier**, not a display
+string. The SQL agent quotes every identifier to preserve case
+(`"schema"."table"."column"`), and quoted identifiers are **case-sensitive** in
+Snowflake and Postgres. So the ontology's stored identifier case **must equal the
+warehouse's stored case**, or generated SQL fails with errors like
+`Schema "core" does not exist`.
+
+- Seed the physical layer from schema introspection, which returns the real case
+  (Snowflake unquoted DDL is stored UPPERCASE; Postgres lowercase). Never
+  hand-lowercase identifiers from a spreadsheet and import them.
+- This applies to **identifiers only**: `schema_name`/`table_name`, column `name`,
+  `grain`, join endpoints (`from_schema`/`from_table`/…), `column_pairs` and
+  `condition_sql`, and metric `table_schema`/`table_name`/`expression`/`filters`. Logical fields — domain paths, display names, descriptions,
+  **synonyms**, `context_md` — stay natural language; the matching layer there is
+  case-insensitive and should read naturally.
+- **Schema-qualify everything.** Table references in SQL and prose carry the
+  `schema.TABLE` form (`dbt_core.fct_orders`), so a scope rule about `raw.users`
+  never accidentally catches `core.users`, and a prefix that doesn't match what
+  the warehouse actually has doesn't silently resolve to nothing.
+
+---
+
+## 10. Examples and enums — handle like loaded weapons
+
+An inaccurate example primes the agent **more strongly** than a correct prose
+description, so a wrong example is worse than none.
+
+- **Use real stored enum values verbatim.** Never hand-wave a list with "etc." —
+  the agent reads `etc.` as license to invent values. If you don't have the exact
+  values, omit the list rather than approximate it. When two columns supposedly
+  share an enum, verify they're identical before encoding both.
+- **Be wary of analogies to external products** — they mislead the moment the
+  real mechanic diverges.
+- **Don't describe things that don't exist.** Every table, column, and value you
+  reference must be real.
+
+---
+
+## 11. Cross-cutting disciplines
+
+- **One home, then de-duplicate.** When you learn a fact, put it in exactly one
+  place — the most specific layer that owns it — and, if the same fact already
+  appears elsewhere, remove the copy or leave a one-line pointer. When a
+  stakeholder clarifies something, scan every layer for places that need the
+  update and land it in only one.
+- **Work back to the source, not a derived copy.** Model from the warehouse
+  schema and the authoritative source SQL, not from a previously-written
+  description. Each derivation loses information; chaining them compounds the
+  loss. Where sources disagree, pick one authoritative source and document why it
+  wins.
+- **Scope every edit to what was asked.** Don't bundle unrequested companion
+  changes (extra metrics, synonyms, reorganizations) into a change. When you spot
+  an adjacent improvement, note it and let a human opt in. The one exception: a
+  metric you place in a *different* domain than the prose that discusses it takes
+  a one-line pointer in that prose, as part of the same change.
+- **Ground writes in the real schema.** Before referencing a physical table or
+  column, confirm it exists. Don't invent tables or columns; the physical schema
+  is fixed.
+- **Ask for the business meaning; don't guess.** A term like "active user" or
+  "last month" has a project-specific definition (time window, criteria, filters).
+  Encode the business's actual definition, not a textbook default.
+
+---
+
+## 12. Working in a git-synced repo
+
+The repository is the source of truth. Edit the YAML, then verify before opening
+a pull request — the CLI runs the same checks the platform does, from your
+checkout:
+
+- `cassis ontology check` — validate the files (YAML parse, round-trip, semantic
+  checks); the same gate that runs on the pull request.
+- `cassis ontology fmt` — rewrite the files in canonical form, so hand or agent
+  edits round-trip cleanly and any dropped/unknown fields become visible in the
+  diff before you commit.
+- `cassis ontology test -q "…"` — run a real question through the text-to-SQL
+  agent against your local files, to confirm a change actually *works* (e.g. a new
+  column gets picked), not just that it validates.
+- `cassis eval run` — score the project's eval suite against your local files to
+  check the change for regressions before merging.
+
+Merging the pull request syncs and publishes the ontology; nothing reaches
+production answers until then.
+
+---
+
+*This guide is the single canonical home for Cassis ontology modeling doctrine.
+When a new pattern generalizes beyond one project, it belongs here.*

{cassis_cli-0.4.0 → cassis_cli-1.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cassis-cli"
-version = "0.4.0"
+version = "1.0.0"
 description = "Cassis CLI — run Cassis actions (ontology validation, upload and publish) from your CI pipelines"
 readme = "README.md"
 license = { text = "Proprietary" }
@@ -19,6 +19,9 @@ cassis = "cassis_cli.main:app"
 
 [tool.poetry]
 packages = [{ include = "cassis_cli" }]
+# Ship the bundled modeling guide (non-.py data) in the wheel/sdist — the CLI
+# reads it at runtime to write <base_path>/AGENTS.md.
+include = [{ path = "cassis_cli/ontology_design_guide.md", format = ["sdist", "wheel"] }]
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^9.0.0"