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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cassis-cli
-Version: 0.2.0
+Version: 0.4.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
@@ -23,7 +23,10 @@ Description-Content-Type: text/markdown
 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 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.
 
 ## Install
 
@@ -35,7 +38,7 @@ pip install cassis-cli
 
 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 `upload`: find the project ID (UUID) in the project's URL and expose it as `CASSIS_PROJECT_ID` (or pass `--project`).
+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`).
 
 ## Usage
 
@@ -46,6 +49,10 @@ cassis ontology check
 # Or point at the checkout explicitly:
 cassis ontology check /path/to/checkout
 
+# Download the project's unpublished ontology into the checkout (full sync;
+# review with git diff — pass --no-prune to keep local files it would delete):
+cassis ontology pull --project 019f0000-0000-7000-8000-000000000000
+
 # Upload the ontology to a project and publish it immediately:
 cassis ontology upload --project 019f0000-0000-7000-8000-000000000000
 
@@ -57,7 +64,19 @@ cassis ontology upload --project ... --label "release 1.2"
 
 # Machine-readable output:
 cassis ontology check --json
+cassis ontology pull --project ... --json
 cassis ontology upload --project ... --json
+cassis eval run --project ... --json
+
+# Run the eval suite against the local ontology files and wait for results
+# (the run is labelled with your git branch name in the Evals page):
+cassis eval run --project ...
+
+# Run against an existing Cassis ontology branch, or the unpublished ontology:
+cassis eval run --project ... --branch feature-x
+
+# Start the run and return immediately (poll in the webapp):
+cassis eval run --project ... --no-wait
 ```
 
 Configuration (flags take precedence over env vars):
@@ -67,20 +86,43 @@ 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` (upload only) | `CASSIS_PROJECT_ID` | — (required)      |
+| `--project` (pull, upload, eval run) | `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
+with `--branch`, whose runs are labelled with the branch name), `--wait/--no-wait`, `--poll-interval` (5 s),
+`--timeout` (30 min — the run keeps going server-side if the CLI stops waiting),
+and Ctrl-C cancels the run (exit 130). It prints a deep link to the run's page
+in the Evals UI; `--app-url` / `CASSIS_APP_URL` overrides the link's base URL
+when the webapp is not served from the API host (defaults to `--api-url`).
+
+### Formatting
+
+```bash
+# Rewrite the ontology files in canonical form (in place)
+cassis ontology fmt
+
+# CI mode: fail (exit 1) if any file is not canonical, write nothing
+cassis ontology fmt --check
+```
+
+`fmt` uses the exact serializer the validation round-trip compares against, so a formatted tree cannot fail that stage. Formatting does not run import validation — `check` remains the pass/fail gate for semantic problems (dangling references, incomplete metrics).
+
+**Review the diff before committing**: canonical form keeps exactly the fields Cassis understands. Unknown fields (typos) are dropped — the rewrite makes them visible in `git diff` instead of losing them silently at sync time. Files with duplicate YAML keys are rejected (fix them by hand: the formatter can't know which value you meant).
 
 ### Exit codes
 
 | Code | Meaning                                                                        |
 | ---- | ------------------------------------------------------------------------------ |
-| 0    | Ontology is valid (check) / uploaded (upload)                                  |
-| 1    | Validation failed (check: findings printed; upload: nothing imported)          |
+| 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) |
 | 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) |
+| 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another run already active, or `--timeout` reached |
 
-Both commands 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.
+Commands that send the local tree (`check`, `upload`, `eval run`) 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.
 
 `upload` replaces the project's entire ontology with the uploaded tree. A
 never-published project always goes live immediately on first upload (even
@@ -105,6 +147,20 @@ jobs:
         env:
           CASSIS_API_KEY: ${{ secrets.CASSIS_API_KEY }}
 
+  ontology-eval:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install cassis-cli
+      - run: cassis eval run
+        env:
+          CASSIS_API_KEY: ${{ secrets.CASSIS_API_KEY }}
+          CASSIS_PROJECT_ID: ${{ vars.CASSIS_PROJECT_ID }}
+
   ontology-publish:
     runs-on: ubuntu-latest
     if: github.ref == 'refs/heads/main'
@@ -131,6 +187,17 @@ ontology-check:
   variables:
     CASSIS_API_KEY: $CASSIS_API_KEY
 
+ontology-eval:
+  image: python:3.12-slim
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  script:
+    - pip install cassis-cli
+    - cassis eval run
+  variables:
+    CASSIS_API_KEY: $CASSIS_API_KEY
+    CASSIS_PROJECT_ID: $CASSIS_PROJECT_ID
+
 ontology-publish:
   image: python:3.12-slim
   rules:

cassis_cli-0.4.0/README.md

@@ -0,0 +1,191 @@
+# Cassis CLI
+
+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 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.
+
+## Install
+
+```bash
+pip install cassis-cli
+```
+
+## 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`).
+
+## Usage
+
+```bash
+# From the root of a repository synced with Cassis (contains the ontology export directory, cassis/ by default):
+cassis ontology check
+
+# Or point at the checkout explicitly:
+cassis ontology check /path/to/checkout
+
+# Download the project's unpublished ontology into the checkout (full sync;
+# review with git diff — pass --no-prune to keep local files it would delete):
+cassis ontology pull --project 019f0000-0000-7000-8000-000000000000
+
+# Upload the ontology to a project and publish it immediately:
+cassis ontology upload --project 019f0000-0000-7000-8000-000000000000
+
+# Upload without publishing (the tree becomes the project's unpublished ontology, to review in Cassis):
+cassis ontology upload --project ... --no-publish
+
+# Label the published version:
+cassis ontology upload --project ... --label "release 1.2"
+
+# Machine-readable output:
+cassis ontology check --json
+cassis ontology pull --project ... --json
+cassis ontology upload --project ... --json
+cassis eval run --project ... --json
+
+# Run the eval suite against the local ontology files and wait for results
+# (the run is labelled with your git branch name in the Evals page):
+cassis eval run --project ...
+
+# Run against an existing Cassis ontology branch, or the unpublished ontology:
+cassis eval run --project ... --branch feature-x
+
+# Start the run and return immediately (poll in the webapp):
+cassis eval run --project ... --no-wait
+```
+
+Configuration (flags take precedence over env vars):
+
+| Flag        | Env var          | Default                     |
+| ----------- | ---------------- | --------------------------- |
+| `--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)      |
+
+`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
+with `--branch`, whose runs are labelled with the branch name), `--wait/--no-wait`, `--poll-interval` (5 s),
+`--timeout` (30 min — the run keeps going server-side if the CLI stops waiting),
+and Ctrl-C cancels the run (exit 130). It prints a deep link to the run's page
+in the Evals UI; `--app-url` / `CASSIS_APP_URL` overrides the link's base URL
+when the webapp is not served from the API host (defaults to `--api-url`).
+
+### Formatting
+
+```bash
+# Rewrite the ontology files in canonical form (in place)
+cassis ontology fmt
+
+# CI mode: fail (exit 1) if any file is not canonical, write nothing
+cassis ontology fmt --check
+```
+
+`fmt` uses the exact serializer the validation round-trip compares against, so a formatted tree cannot fail that stage. Formatting does not run import validation — `check` remains the pass/fail gate for semantic problems (dangling references, incomplete metrics).
+
+**Review the diff before committing**: canonical form keeps exactly the fields Cassis understands. Unknown fields (typos) are dropped — the rewrite makes them visible in `git diff` instead of losing them silently at sync time. Files with duplicate YAML keys are rejected (fix them by hand: the formatter can't know which value you meant).
+
+### Exit codes
+
+| 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) |
+| 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 |
+
+Commands that send the local tree (`check`, `upload`, `eval run`) 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.
+
+`upload` replaces the project's entire ontology with the uploaded tree. A
+never-published project always goes live immediately on first upload (even
+with `--no-publish`), matching imports from the Cassis app. Publishing is
+idempotent: re-uploading content identical to the published version reports
+that version instead of creating a new one, so re-running the CI job on
+unchanged files is a no-op.
+
+### GitHub Actions example
+
+```yaml
+jobs:
+  ontology-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install cassis-cli
+      - run: cassis ontology check
+        env:
+          CASSIS_API_KEY: ${{ secrets.CASSIS_API_KEY }}
+
+  ontology-eval:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install cassis-cli
+      - run: cassis eval run
+        env:
+          CASSIS_API_KEY: ${{ secrets.CASSIS_API_KEY }}
+          CASSIS_PROJECT_ID: ${{ vars.CASSIS_PROJECT_ID }}
+
+  ontology-publish:
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install cassis-cli
+      - run: cassis ontology upload
+        env:
+          CASSIS_API_KEY: ${{ secrets.CASSIS_API_KEY }}
+          CASSIS_PROJECT_ID: ${{ vars.CASSIS_PROJECT_ID }}
+```
+
+### GitLab CI example
+
+```yaml
+ontology-check:
+  image: python:3.12-slim
+  script:
+    - pip install cassis-cli
+    - cassis ontology check
+  variables:
+    CASSIS_API_KEY: $CASSIS_API_KEY
+
+ontology-eval:
+  image: python:3.12-slim
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  script:
+    - pip install cassis-cli
+    - cassis eval run
+  variables:
+    CASSIS_API_KEY: $CASSIS_API_KEY
+    CASSIS_PROJECT_ID: $CASSIS_PROJECT_ID
+
+ontology-publish:
+  image: python:3.12-slim
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+  script:
+    - pip install cassis-cli
+    - cassis ontology upload
+  variables:
+    CASSIS_API_KEY: $CASSIS_API_KEY
+    CASSIS_PROJECT_ID: $CASSIS_PROJECT_ID
+```

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

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

cassis_cli-0.4.0/cassis_cli/api.py

@@ -0,0 +1,322 @@
+"""Thin HTTP client for the Cassis API."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+DEFAULT_API_URL = "https://app.getcassis.com"
+TIMEOUT_SECONDS = 60.0
+
+
+class ApiError(Exception):
+    """Transport or HTTP-level failure talking to the Cassis API."""
+
+
+class AuthError(ApiError):
+    """The API rejected the API key (401)."""
+
+
+class UploadValidationError(ApiError):
+    """The API rejected the uploaded ontology tree as invalid (400)."""
+
+
+class EvalStartValidationError(ApiError):
+    """The API rejected the eval-run start request (400): invalid tree or no test cases.
+
+    ``detail`` keeps the structured payload (``{"message", "findings"}`` for an
+    invalid tree, or a plain string) for display.
+    """
+
+    def __init__(self, detail: object) -> None:
+        super().__init__(str(detail))
+        self.detail = detail
+
+
+class EvalRunActiveError(ApiError):
+    """Another eval run is already active for the project (409)."""
+
+
+def _project_scope_error(response: httpx.Response) -> ApiError:
+    # Surface the server's own message when it names the missing resource
+    # (e.g. "Branch 'x' not found") — the generic hint covers the rest.
+    try:
+        detail = response.json().get("detail")
+    except ValueError:
+        detail = None
+    prefix = f"{detail} " if isinstance(detail, str) and detail else ""
+    return ApiError(
+        f"{prefix}(HTTP {response.status_code}). Check --project and that "
+        "the API key belongs to the project's organization and can edit it."
+    )
+
+
+def _parse_json_response(response: httpx.Response, url: str) -> Any:
+    try:
+        return response.json()
+    except ValueError as exc:  # json.JSONDecodeError — e.g. a proxy or portal answering HTML with a 200
+        raise ApiError(
+            f"The Cassis API at {url} returned a non-JSON response — check the API URL and any proxy in between."
+        ) from exc
+
+
+def post_ontology_check(
+    *,
+    api_url: str,
+    api_key: str,
+    files: dict[str, str],
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """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:
+            response = client.post(
+                url,
+                json={"files": files},
+                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 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 ("passed", "title", "summary"))
+        or not isinstance(result.get("findings"), list)
+    ):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def post_ontology_import(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    files: dict[str, str],
+    publish: bool,
+    label: Optional[str] = None,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST the ontology tree to /api/ci/projects/{project_id}/ontology/import and return the response body."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/ontology/import"
+    body: dict[str, Any] = {"files": files, "publish": publish}
+    if label is not None:
+        body["label"] = label
+    try:
+        with httpx.Client(timeout=TIMEOUT_SECONDS, 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
+
+    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))
+    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 ("domain_count", "table_count", "join_count", "metric_count", "published_version")
+    ):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def get_ontology_export(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, str]:
+    """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:
+            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
+
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    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 isinstance(result.get("files"), dict):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result["files"]
+
+
+def post_eval_run_start(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    files: Optional[dict[str, str]] = None,
+    branch: Optional[str] = None,
+    label: Optional[str] = None,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST to /api/ci/projects/{project_id}/eval/runs and return the run record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/eval/runs"
+    body: dict[str, Any] = {}
+    if files is not None:
+        body["files"] = files
+    if branch is not None:
+        body["branch"] = branch
+    if label is not None:
+        body["label"] = label
+    try:
+        with httpx.Client(timeout=TIMEOUT_SECONDS, 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
+
+    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)
+    if response.status_code == 409:
+        raise EvalRunActiveError(
+            "An eval run is already active for this project — wait for it to finish or cancel it "
+            "(in the webapp's Evals page, or with the run id printed when it was started)."
+        )
+    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 ("run_id", "status", "total_cases")):
+        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:
+            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
+
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    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]}")
+    return _parse_json_response(response, url)
+
+
+def get_eval_run(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    run_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """GET /api/ci/projects/{project_id}/eval/runs/{run_id} and return the run record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/eval/runs/{run_id}"
+    result = _get_eval_json(url, api_key, transport)
+    if not isinstance(result, dict) or not all(key in result for key in ("run_id", "status", "total_cases")):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def get_eval_run_results(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    run_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> list[dict[str, Any]]:
+    """GET /api/ci/projects/{project_id}/eval/runs/{run_id}/results and return the result list."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/eval/runs/{run_id}/results"
+    result = _get_eval_json(url, api_key, transport)
+    if not isinstance(result, list):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def post_eval_run_cancel(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    run_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> None:
+    """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:
+            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
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    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]}")
+
+
+def post_ontology_fmt(
+    *,
+    api_url: str,
+    api_key: str,
+    files: dict[str, str],
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """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:
+            response = client.post(
+                url,
+                json={"files": files},
+                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 ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+    result = _parse_json_response(response, url)
+    if (
+        not isinstance(result, dict)
+        or "ok" not in result
+        or not isinstance(result.get("findings"), list)
+        or not isinstance(result.get("changed_paths"), list)
+        or not isinstance(result.get("removed_paths"), list)
+        or (result["ok"] and not isinstance(result.get("files"), dict))
+    ):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result