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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cassis-cli
-Version: 1.0.0
+Version: 1.1.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
@@ -25,8 +25,8 @@ Run Cassis actions from your CI pipelines:
 - `cassis ontology check` validates the ontology files in your repository with the exact same checks as the Cassis GitHub PR check (YAML parsing, round-trip, import validation) — so you can gate merges in any CI system, not just GitHub.
 - `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.
+- `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local ontology 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 (which is the YAML files plus the domain Markdown files `domains/**/README.md`), 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.
@@ -38,11 +38,21 @@ Run Cassis actions from your CI pipelines:
 pip install cassis-cli
 ```
 
+## Ontology file format
+
+The ontology tree under `<base-path>` (default `cassis/`) is:
+
+- **Project identity** — `project.yml`: the Cassis project id and format version. Written by `pull` and by server-side publish (the contexts that know the id); a local `fmt` won't create it.
+- **Domains** — Markdown files: every domain is the `README.md` of its folder — `domains/README.md` for the root, `domains/<path>/README.md` for each sub-domain. Each has a small YAML frontmatter block (`type`, `title`, `description`) and a Markdown body carrying the domain's `context_md`; a generated section at the bottom links the domain's tables and metrics (kept current by `fmt`/`pull` — edit your prose above it, and the PR check fails if the links are stale, so re-run `fmt`). The layout is a Cassis profile inspired by [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf): the files render on GitHub and read in any Markdown editor, but Cassis validates them strictly (unknown keys are flagged, not preserved).
+- **Tables, joins, metrics** — YAML, unchanged: `tables/<schema>/<table>.yml`, `joins.yml`, `metrics/<name>.yml`.
+
+**Migrating an existing repo** (domains were YAML `_project.yml` / `_domain.yml` before cassis-cli 1.1.0): upgrade and run `cassis ontology fmt` (or `cassis ontology pull` if you have no local edits) — it rewrites the domain files to Markdown and removes the old ones. Review the diff and commit. Cassis reads the old YAML domain files too, so an un-migrated repo keeps working until you convert it. **Uploading requires cassis-cli ≥ 1.1.0** — the server rejects an older CLI (which would drop the Markdown domain files) with a clear upgrade error.
+
 ## Setup
 
 1. Create an API key in Cassis under **Organization settings → API keys** (keys start with `sk-k6-`).
 2. Store it as a CI secret and expose it as `CASSIS_API_KEY`.
-3. For `pull`, `upload` and `eval run`: find the project ID (UUID) in the project's URL and expose it as `CASSIS_PROJECT_ID` (or pass `--project`).
+3. For `pull`, `upload`, `eval run`, `ontology test`, and `eval add-case`: the project ID (UUID) is taken from `<base-path>/project.yml` in the checkout (written by `pull` and by publishing) — so once a repo is pulled you don't need to pass it. To override, or before the first pull, set `CASSIS_PROJECT_ID` or pass `--project` (find the UUID in the project's URL).
 
 ## Usage
 
@@ -132,7 +142,7 @@ cassis ontology fmt --check
 | 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`, `fmt`, `upload`, `eval run`, `test`) accept up to
-2000 YAML files / 5 MB total — far above real ontologies (a few hundred small
+2000 ontology 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-1.0.0 → cassis_cli-1.1.0}/README.md

@@ -5,8 +5,8 @@ Run Cassis actions from your CI pipelines:
 - `cassis ontology check` validates the ontology files in your repository with the exact same checks as the Cassis GitHub PR check (YAML parsing, round-trip, import validation) — so you can gate merges in any CI system, not just GitHub.
 - `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.
+- `cassis ontology pull` downloads the project's unpublished ontology into your repository checkout (full sync — stale local ontology 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 (which is the YAML files plus the domain Markdown files `domains/**/README.md`), 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.
@@ -18,11 +18,21 @@ Run Cassis actions from your CI pipelines:
 pip install cassis-cli
 ```
 
+## Ontology file format
+
+The ontology tree under `<base-path>` (default `cassis/`) is:
+
+- **Project identity** — `project.yml`: the Cassis project id and format version. Written by `pull` and by server-side publish (the contexts that know the id); a local `fmt` won't create it.
+- **Domains** — Markdown files: every domain is the `README.md` of its folder — `domains/README.md` for the root, `domains/<path>/README.md` for each sub-domain. Each has a small YAML frontmatter block (`type`, `title`, `description`) and a Markdown body carrying the domain's `context_md`; a generated section at the bottom links the domain's tables and metrics (kept current by `fmt`/`pull` — edit your prose above it, and the PR check fails if the links are stale, so re-run `fmt`). The layout is a Cassis profile inspired by [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf): the files render on GitHub and read in any Markdown editor, but Cassis validates them strictly (unknown keys are flagged, not preserved).
+- **Tables, joins, metrics** — YAML, unchanged: `tables/<schema>/<table>.yml`, `joins.yml`, `metrics/<name>.yml`.
+
+**Migrating an existing repo** (domains were YAML `_project.yml` / `_domain.yml` before cassis-cli 1.1.0): upgrade and run `cassis ontology fmt` (or `cassis ontology pull` if you have no local edits) — it rewrites the domain files to Markdown and removes the old ones. Review the diff and commit. Cassis reads the old YAML domain files too, so an un-migrated repo keeps working until you convert it. **Uploading requires cassis-cli ≥ 1.1.0** — the server rejects an older CLI (which would drop the Markdown domain files) with a clear upgrade error.
+
 ## Setup
 
 1. Create an API key in Cassis under **Organization settings → API keys** (keys start with `sk-k6-`).
 2. Store it as a CI secret and expose it as `CASSIS_API_KEY`.
-3. For `pull`, `upload` and `eval run`: find the project ID (UUID) in the project's URL and expose it as `CASSIS_PROJECT_ID` (or pass `--project`).
+3. For `pull`, `upload`, `eval run`, `ontology test`, and `eval add-case`: the project ID (UUID) is taken from `<base-path>/project.yml` in the checkout (written by `pull` and by publishing) — so once a repo is pulled you don't need to pass it. To override, or before the first pull, set `CASSIS_PROJECT_ID` or pass `--project` (find the UUID in the project's URL).
 
 ## Usage
 
@@ -112,7 +122,7 @@ cassis ontology fmt --check
 | 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`, `fmt`, `upload`, `eval run`, `test`) accept up to
-2000 YAML files / 5 MB total — far above real ontologies (a few hundred small
+2000 ontology 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-1.0.0 → cassis_cli-1.1.0}/cassis_cli/__init__.py

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

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

@@ -191,6 +191,8 @@ def post_ontology_import(
         raise AuthError("The Cassis API rejected the API key (invalid or expired).")
     if response.status_code == 400:
         raise UploadValidationError(str(_detail_or_text(response)))
+    if response.status_code == 426:  # this CLI is too old for the server's ontology format
+        raise UploadValidationError(str(_detail_or_text(response)))
     if response.status_code in (403, 404):
         raise _project_scope_error(response)
     if response.status_code >= 400:

cassis_cli-1.1.0/cassis_cli/common.py

@@ -0,0 +1,177 @@
+"""Helpers shared by the `cassis` subcommands (tree collection, auth, exit codes)."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Optional
+from uuid import UUID
+
+import typer
+
+# Repository directory the ontology tree is exported under. Must match the
+# project's git-sync "Path" setting in Cassis (default "cassis").
+DEFAULT_BASE_PATH = "cassis"
+
+# Exit codes (documented in the README; stable contract for CI scripts).
+EXIT_OK = 0
+EXIT_VALIDATION_FAILED = 1
+EXIT_USAGE = 2
+EXIT_TRANSPORT = 3
+
+# Request ceilings of the /api/ci file-tree endpoints, mirrored so oversized
+# trees fail fast with a clear message before any upload. Source of truth:
+# backend/app/schemas/ci.py (the server's 422 remains the backstop).
+MAX_FILES = 2000
+MAX_TOTAL_BYTES = 5 * 1024 * 1024
+
+
+def is_ontology_file(rel_path: str) -> bool:
+    """Whether a base-relative path is an ontology file the server reads.
+
+    YAML (``project.yml``, tables, joins, metrics, legacy domains) plus domain
+    Markdown — every domain is the ``README.md`` of its folder, root included
+    (``domains/README.md``), so ``domains/**/README.md`` covers them all. Mirrors
+    the server's ``ontology_fs.is_ontology_tree_file`` (kept in sync by hand —
+    the CLI can't import the backend). Excludes the managed ``AGENTS.md`` and any
+    stray Markdown note, so neither is uploaded nor deleted by ``pull --prune``.
+    """
+    if rel_path.endswith((".yml", ".yaml")):
+        return True
+    return rel_path.startswith("domains/") and rel_path.endswith("/README.md")
+
+
+def is_legacy_domain_file(rel_path: str) -> bool:
+    """Whether a base-relative path is a legacy (pre-Markdown) domain file.
+
+    Used to report the one-time migration to the Markdown domain format, when
+    ``pull``/``fmt`` remove a ``_project.yml``/``_domain.yml`` and write the
+    ``domains/README.md`` (and sub-domain ``README.md``) that replaces it.
+    """
+    return rel_path == "_project.yml" or rel_path.endswith("/_domain.yml")
+
+
+def collect_files(ontology_dir: Path) -> dict[str, str]:
+    """Read every ontology file under the ontology dir, keyed by posix relpath.
+
+    Ontology files are YAML and domain Markdown (see ``is_ontology_file``); the
+    managed ``AGENTS.md`` and stray notes are skipped. Exits 2 (usage) on an
+    unreadable or non-UTF-8 file — a local checkout problem, reported before
+    anything is sent to the API.
+    """
+    files: dict[str, str] = {}
+    for pattern in ("**/*.yml", "**/*.yaml", "**/*.md"):
+        for file in sorted(ontology_dir.glob(pattern)):
+            if not file.is_file():
+                continue
+            rel = file.relative_to(ontology_dir).as_posix()
+            if not is_ontology_file(rel):
+                continue
+            try:
+                files[rel] = file.read_text(encoding="utf-8")
+            except (UnicodeDecodeError, OSError) as exc:
+                typer.secho(f"Cannot read {file}: {exc}", fg=typer.colors.RED, err=True)
+                raise typer.Exit(EXIT_USAGE) from exc
+    return files
+
+
+# project.yml is a two-line machine-written file (`cassis_format_version`, `project_id`);
+# match the id line directly rather than pull in a YAML parser just for this.
+_PROJECT_ID_LINE = re.compile(r"^project_id:\s*['\"]?([^'\"\s]+)['\"]?\s*$")
+
+
+def read_project_id_from_dir(ontology_dir: Path) -> Optional[str]:
+    """Return the ``project_id`` recorded in ``<ontology_dir>/project.yml``, or None."""
+    try:
+        text = (ontology_dir / "project.yml").read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as _exc:  # `as` keeps black from stripping the parens (3.14-only syntax)
+        return None
+    for line in text.splitlines():
+        match = _PROJECT_ID_LINE.match(line.strip())
+        if match:
+            return match.group(1)
+    return None
+
+
+def resolve_project_id(project_id: Optional[str], ontology_dir: Path) -> str:
+    """Resolve the target project id, defaulting to the checkout's ``project.yml``.
+
+    Precedence: an explicit ``--project`` / ``CASSIS_PROJECT_ID`` wins; otherwise
+    the ``project_id`` recorded in ``<base-path>/project.yml`` (written by
+    ``pull`` / publish) is used, and where it came from is noted on stderr so a
+    stale value in a copied repo is visible. Exits 2 (usage) when neither is
+    available or the value isn't a UUID.
+    """
+    from_file = False
+    if not project_id:
+        project_id = read_project_id_from_dir(ontology_dir)
+        from_file = project_id is not None
+    if not project_id:
+        typer.secho(
+            f"No project. Pass --project (or set CASSIS_PROJECT_ID), or run in a checkout whose "
+            f"{ontology_dir.name}/project.yml records it (written by `cassis ontology pull` or a publish).",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(EXIT_USAGE)
+    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 from_file:
+        typer.secho(f"Using project {project_id} from {ontology_dir.name}/project.yml.", fg=typer.colors.CYAN, err=True)
+    return project_id
+
+
+def require_api_key(api_key: Optional[str]) -> str:
+    """Exit 2 (usage) when no API key was provided."""
+    if not api_key:
+        typer.secho(
+            "No API key. Set CASSIS_API_KEY or pass --api-key "
+            "(create one in Cassis under Organization settings -> API keys).",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(EXIT_USAGE)
+    return api_key
+
+
+def collect_tree(path: Path, base_path: str) -> "tuple[dict[str, str], str]":
+    """Resolve the ontology dir under the checkout and read its file tree.
+
+    Returns ``(files, normalized_base_path)``. Exits 2 (usage) on an empty or
+    missing dir, or a tree beyond the API request ceilings — all local checkout
+    problems, reported before anything is sent to the API.
+    """
+    base_path = base_path.strip().strip("/")
+    if not base_path:
+        typer.secho("--base-path must not be empty.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE)
+
+    ontology_dir = path / Path(base_path)
+    if not ontology_dir.is_dir():
+        typer.secho(
+            f"No {base_path}/ directory found under {path}. "
+            "If the project exports to a custom path, pass it with --base-path (or CASSIS_BASE_PATH).",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(EXIT_USAGE)
+
+    files = collect_files(ontology_dir)
+    if not files:
+        typer.secho(f"No ontology files found under {ontology_dir}.", fg=typer.colors.RED, err=True)
+        raise typer.Exit(EXIT_USAGE)
+
+    total_bytes = sum(len(content.encode()) for content in files.values())
+    if len(files) > MAX_FILES or total_bytes > MAX_TOTAL_BYTES:
+        typer.secho(
+            f"Ontology tree too large: {len(files)} files / {total_bytes / (1024 * 1024):.1f} MB "
+            f"(limits: {MAX_FILES} files / {MAX_TOTAL_BYTES // (1024 * 1024)} MB). "
+            "Check that --base-path points at the ontology directory, not a larger tree.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(EXIT_USAGE)
+    return files, base_path

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

@@ -8,7 +8,6 @@ import subprocess
 import time
 from pathlib import Path
 from typing import Any, Optional
-from uuid import UUID
 
 import typer
 from cassis_cli.api import (
@@ -33,6 +32,7 @@ from cassis_cli.common import (
     EXIT_VALIDATION_FAILED,
     collect_tree,
     require_api_key,
+    resolve_project_id,
 )
 
 app = typer.Typer(no_args_is_help=True, help="Eval commands.")
@@ -144,11 +144,15 @@ def _print_summary(run: dict[str, Any]) -> None:
 
 @app.command(name="add-case")
 def add_case(
-    project_id: str = typer.Option(
-        ...,
+    path: Path = typer.Argument(
+        Path("."),
+        help="Repository checkout root (holds <base-path>/project.yml for the --project default).",
+    ),
+    project_id: Optional[str] = typer.Option(
+        None,
         "--project",
         envvar="CASSIS_PROJECT_ID",
-        help="Target Cassis project ID (UUID, shown in the project's URL).",
+        help="Target Cassis project ID (UUID). Defaults to the id in <base-path>/project.yml.",
     ),
     question: str = typer.Option(
         ...,
@@ -173,6 +177,12 @@ def add_case(
         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 (holds project.yml for the --project default).",
+    ),
     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.
@@ -185,11 +195,7 @@ def add_case(
     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)
+    project_id = resolve_project_id(project_id, path / Path(base_path))
     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)
@@ -221,11 +227,11 @@ def run(
         Path("."),
         help="Repository checkout root (the directory containing the ontology export path).",
     ),
-    project_id: str = typer.Option(
-        ...,
+    project_id: Optional[str] = typer.Option(
+        None,
         "--project",
         envvar="CASSIS_PROJECT_ID",
-        help="Target Cassis project ID (UUID, shown in the project's URL).",
+        help="Target Cassis project ID (UUID). Defaults to the id in <base-path>/project.yml.",
     ),
     api_key: Optional[str] = typer.Option(
         None,
@@ -272,18 +278,13 @@ def run(
 ) -> None:
     """Run the project's eval suite against your local ontology files.
 
-    Uploads the local YAML tree and scores it in-memory — nothing is pushed or
+    Uploads the local ontology file tree and scores it in-memory — nothing is pushed or
     persisted in Cassis besides the eval run itself. With --branch, runs against
     an existing Cassis branch instead (no files are sent). Exits 0 when the run
     completes with every case passed, 1 on any failed case / failed run /
     invalid tree, 2 on usage errors, 3 on transport errors or --timeout.
     """
     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 branch is not None and label is not None:
         typer.secho(
             "--label cannot be used with --branch: branch runs are labelled with the branch name.",
@@ -297,6 +298,7 @@ def run(
         files, base_path = collect_tree(path, base_path)
         if label is None:
             label = _git_branch(path)
+    project_id = resolve_project_id(project_id, path / Path(base_path))
 
     try:
         run_record = post_eval_run_start(

{cassis_cli-1.0.0 → cassis_cli-1.1.0}/cassis_cli/guide.py

@@ -6,7 +6,7 @@ identical — the backend image doesn't ship ``docs/``, so the CLI carries its o
 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.
+CLI overwrites local edits, exactly as ``fmt`` rewrites drifted ontology files.
 
 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
@@ -31,7 +31,7 @@ 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
+DOCTRINE_VERSION = 3
 
 # 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

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

@@ -5,7 +5,6 @@ from __future__ import annotations
 import json
 from pathlib import Path
 from typing import List, Optional
-from uuid import UUID
 
 import typer
 from cassis_cli.api import (
@@ -29,7 +28,9 @@ 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 is_legacy_domain_file as _is_legacy_domain_file
 from cassis_cli.common import require_api_key as _require_api_key
+from cassis_cli.common import resolve_project_id as _resolve_project_id
 from cassis_cli.guide import DOCTRINE_VERSION, GUIDE_FILENAME, guide_status, refresh_guide
 
 app = typer.Typer(no_args_is_help=True, help="Ontology commands.")
@@ -113,11 +114,11 @@ def pull(
         Path("."),
         help="Repository checkout root (the directory containing the ontology export path).",
     ),
-    project_id: str = typer.Option(
-        ...,
+    project_id: Optional[str] = typer.Option(
+        None,
         "--project",
         envvar="CASSIS_PROJECT_ID",
-        help="Source Cassis project ID (UUID, shown in the project's URL).",
+        help="Source Cassis project ID (UUID). Defaults to the id in <base-path>/project.yml.",
     ),
     api_key: Optional[str] = typer.Option(
         None,
@@ -140,28 +141,24 @@ def pull(
     prune: bool = typer.Option(
         True,
         "--prune/--no-prune",
-        help="Delete local YAML files that no longer exist in the project's ontology (default: prune).",
+        help="Delete local ontology files that no longer exist in the project's ontology (default: prune).",
     ),
     json_output: bool = typer.Option(False, "--json", help="Print a JSON summary of written/deleted files."),
 ) -> None:
     """Download the project's unpublished ontology into a repository checkout.
 
-    Writes the ontology YAML tree under the export path (full sync: files are
-    overwritten and, unless --no-prune, stale local YAML files are deleted, so
-    the checkout ends up matching the project exactly). Review the changes with
+    Writes the ontology tree under the export path (full sync: files are
+    overwritten and, unless --no-prune, stale local ontology files are deleted,
+    so the checkout ends up matching the project exactly). Review the changes with
     git diff before committing. Exits 0 on success, 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)
     base_path = base_path.strip().strip("/")
     if not base_path:
         typer.secho("--base-path must not be empty.", fg=typer.colors.RED, err=True)
         raise typer.Exit(EXIT_USAGE)
+    project_id = _resolve_project_id(project_id, path / Path(base_path))
 
     try:
         files = get_ontology_export(api_url=api_url, api_key=api_key, project_id=project_id)
@@ -221,6 +218,13 @@ def pull(
         if guide_written:
             summary += f"; wrote {base_path}/{GUIDE_FILENAME}"
         typer.secho(f"{summary}.", fg=typer.colors.GREEN)
+        migrated = sum(1 for rel in deleted if _is_legacy_domain_file(rel))
+        if migrated:
+            typer.secho(
+                f"  Migrated {migrated} domain(s) to Markdown README.md files; "
+                "the old _domain.yml / _project.yml were removed. Review the diff before committing.",
+                fg=typer.colors.YELLOW,
+            )
     raise typer.Exit(EXIT_OK)
 
 
@@ -230,11 +234,11 @@ def upload(
         Path("."),
         help="Repository checkout root (the directory containing the ontology export path).",
     ),
-    project_id: str = typer.Option(
-        ...,
+    project_id: Optional[str] = typer.Option(
+        None,
         "--project",
         envvar="CASSIS_PROJECT_ID",
-        help="Target Cassis project ID (UUID, shown in the project's URL).",
+        help="Target Cassis project ID (UUID). Defaults to the id in <base-path>/project.yml.",
     ),
     api_key: Optional[str] = typer.Option(
         None,
@@ -270,12 +274,8 @@ def upload(
     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)
     files, base_path = _collect_tree(path, base_path)
+    project_id = _resolve_project_id(project_id, path / Path(base_path))
 
     try:
         result = post_ontology_import(
@@ -377,7 +377,7 @@ def fmt(
 
     changed = result["changed_paths"]
     removed = result["removed_paths"]
-    # The managed AGENTS.md guide is canonicalized alongside the YAML tree
+    # The managed AGENTS.md guide is canonicalized alongside the ontology 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.
@@ -422,6 +422,13 @@ def fmt(
             + ". Review the diff: fields Cassis does not recognize are dropped.",
             fg=typer.colors.YELLOW,
         )
+        migrated = sum(1 for p in removed if _is_legacy_domain_file(p))
+        if migrated:
+            typer.secho(
+                f"Migrated {migrated} domain(s) to Markdown README.md files; "
+                "the old _domain.yml / _project.yml were removed.",
+                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)
@@ -440,11 +447,11 @@ def test(
         "-q",
         help="Natural-language question to probe (repeat for several).",
     ),
-    project_id: str = typer.Option(
-        ...,
+    project_id: Optional[str] = typer.Option(
+        None,
         "--project",
         envvar="CASSIS_PROJECT_ID",
-        help="Target Cassis project ID (UUID, shown in the project's URL).",
+        help="Target Cassis project ID (UUID). Defaults to the id in <base-path>/project.yml.",
     ),
     api_key: Optional[str] = typer.Option(
         None,
@@ -478,12 +485,8 @@ def test(
     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)
+    project_id = _resolve_project_id(project_id, path / Path(base_path))
 
     outcomes: "list[dict]" = []
     failed = False

{cassis_cli-1.0.0 → cassis_cli-1.1.0}/cassis_cli/ontology_design_guide.md

@@ -13,13 +13,13 @@ 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):
+natural-language question into SQL. It has five kinds of object plus a project-level root context, edited as
+files under the repository's ontology directory (`cassis/` by default) —
+domains as Markdown, everything else as YAML:
 
 | Layer | What it is | Key fields |
 |---|---|---|
-| **Root context** (`_project.yml → context_md`) | One free-text block, always in the agent's prompt | markdown |
+| **Root context** (`domains/README.md` body) | 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` |
@@ -31,11 +31,12 @@ On disk, the export layout is fixed — create each object in its canonical home
 
 ```
 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
+  project.yml                    project identity: project id + Cassis format version (written by publish / pull)
+  domains/README.md              root domain (path ""): frontmatter (type/title/description) + context_md body
+  domains/<path>/README.md       one per sub-domain, nested by path (same Markdown format)
+  tables/<schema>/<table>.yml    one per table, columns inline (YAML)
+  metrics/<name>.yml             one per metric (YAML)
+  joins.yml                      ALL joins, one list in one file (YAML)
 ```
 
 Joins and metrics are never embedded inside a table's file, and a table's file
@@ -45,7 +46,7 @@ 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
+edit surface: you edit the files, open a pull request, and merging syncs and
 publishes it.
 
 Physical tables and their columns come from schema introspection — you never
@@ -151,6 +152,12 @@ 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, `""`).
 
+Each domain is a Markdown file (`domains/<path>/README.md`, or `domains/README.md`
+for the root). Its YAML frontmatter holds the structured fields — `type: Domain`,
+`title:` (the display name), `description:` — and the Markdown body **is** the
+domain's `context_md`. Write the display name as `title`, not `display_name`: an
+unrecognized frontmatter key is dropped on sync.
+
 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.
@@ -167,7 +174,7 @@ scope caveats. Omit either if you have nothing for it.
 - 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
+**Root context** — the body of the root domain (`domains/README.md`), 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
@@ -381,11 +388,11 @@ description, so a wrong example is worse than none.
 
 ## 12. Working in a git-synced repo
 
-The repository is the source of truth. Edit the YAML, then verify before opening
+The repository is the source of truth. Edit the files, 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
+- `cassis ontology check` — validate the files (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

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

@@ -1,6 +1,6 @@
 [project]
 name = "cassis-cli"
-version = "1.0.0"
+version = "1.1.0"
 description = "Cassis CLI — run Cassis actions (ontology validation, upload and publish) from your CI pipelines"
 readme = "README.md"
 license = { text = "Proprietary" }

cassis_cli-1.0.0/cassis_cli/common.py

@@ -1,95 +0,0 @@
-"""Helpers shared by the `cassis` subcommands (tree collection, auth, exit codes)."""
-
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Optional
-
-import typer
-
-# Repository directory the ontology tree is exported under. Must match the
-# project's git-sync "Path" setting in Cassis (default "cassis").
-DEFAULT_BASE_PATH = "cassis"
-
-# Exit codes (documented in the README; stable contract for CI scripts).
-EXIT_OK = 0
-EXIT_VALIDATION_FAILED = 1
-EXIT_USAGE = 2
-EXIT_TRANSPORT = 3
-
-# Request ceilings of the /api/ci file-tree endpoints, mirrored so oversized
-# trees fail fast with a clear message before any upload. Source of truth:
-# backend/app/schemas/ci.py (the server's 422 remains the backstop).
-MAX_FILES = 2000
-MAX_TOTAL_BYTES = 5 * 1024 * 1024
-
-
-def collect_files(ontology_dir: Path) -> dict[str, str]:
-    """Read every YAML file under the ontology dir, keyed by posix relpath.
-
-    Exits 2 (usage) on an unreadable or non-UTF-8 file — a local checkout
-    problem, reported before anything is sent to the API.
-    """
-    files: dict[str, str] = {}
-    for pattern in ("**/*.yml", "**/*.yaml"):
-        for file in sorted(ontology_dir.glob(pattern)):
-            if file.is_file():
-                try:
-                    files[file.relative_to(ontology_dir).as_posix()] = file.read_text(encoding="utf-8")
-                except (UnicodeDecodeError, OSError) as exc:
-                    typer.secho(f"Cannot read {file}: {exc}", fg=typer.colors.RED, err=True)
-                    raise typer.Exit(EXIT_USAGE) from exc
-    return files
-
-
-def require_api_key(api_key: Optional[str]) -> str:
-    """Exit 2 (usage) when no API key was provided."""
-    if not api_key:
-        typer.secho(
-            "No API key. Set CASSIS_API_KEY or pass --api-key "
-            "(create one in Cassis under Organization settings -> API keys).",
-            fg=typer.colors.RED,
-            err=True,
-        )
-        raise typer.Exit(EXIT_USAGE)
-    return api_key
-
-
-def collect_tree(path: Path, base_path: str) -> "tuple[dict[str, str], str]":
-    """Resolve the ontology dir under the checkout and read its YAML tree.
-
-    Returns ``(files, normalized_base_path)``. Exits 2 (usage) on an empty or
-    missing dir, or a tree beyond the API request ceilings — all local checkout
-    problems, reported before anything is sent to the API.
-    """
-    base_path = base_path.strip().strip("/")
-    if not base_path:
-        typer.secho("--base-path must not be empty.", fg=typer.colors.RED, err=True)
-        raise typer.Exit(EXIT_USAGE)
-
-    ontology_dir = path / Path(base_path)
-    if not ontology_dir.is_dir():
-        typer.secho(
-            f"No {base_path}/ directory found under {path}. "
-            "If the project exports to a custom path, pass it with --base-path (or CASSIS_BASE_PATH).",
-            fg=typer.colors.RED,
-            err=True,
-        )
-        raise typer.Exit(EXIT_USAGE)
-
-    files = collect_files(ontology_dir)
-    if not files:
-        typer.secho(f"No YAML files found under {ontology_dir}.", fg=typer.colors.RED, err=True)
-        raise typer.Exit(EXIT_USAGE)
-
-    total_bytes = sum(len(content.encode()) for content in files.values())
-    if len(files) > MAX_FILES or total_bytes > MAX_TOTAL_BYTES:
-        typer.secho(
-            f"Ontology tree too large: {len(files)} files / {total_bytes / (1024 * 1024):.1f} MB "
-            f"(limits: {MAX_FILES} files / {MAX_TOTAL_BYTES // (1024 * 1024)} MB). "
-            "Check that --base-path points at the ontology directory, not a larger tree.",
-            fg=typer.colors.RED,
-            err=True,
-        )
-        raise typer.Exit(EXIT_USAGE)
-    return files, base_path