cassis-cli 1.6.0__tar.gz → 2.0.0__tar.gz

{cassis_cli-1.6.0 → cassis_cli-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cassis-cli
-Version: 1.6.0
+Version: 2.0.0
 Summary: Validate, test and evaluate your Cassis ontology from your terminal, then publish it
 License: Apache-2.0
 License-File: LICENSE
@@ -35,11 +35,10 @@ Validate, test and evaluate your ontology from your terminal, then publish it. T
 - `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.
 - `cassis eval list-cases` and `cassis eval delete-case` maintain the suite: list the current cases with their ids, and prune one that is stale or wrong (e.g. its gold SQL encodes a definition the ontology has since changed).
-- `cassis schema push` uploads a DDL file to detect source-schema changes on a DDL-only project (same as the webapp's "Update from DDL" button): Cassis diffs the DDL against the ontology and surfaces added, dropped, and changed objects in Ontology > Review > Data source for approval. The file speaks only for the schemas it contains — a partial export (one schema of many) never removes the others; pass `--complete` when it is the project's complete source schema so schemas absent from it are treated as dropped. Waits for the detection run to finish and exits 0 only when it completed — the schema is stored and applied atomically with run completion, so exit 0 means the DDL parsed and the project now uses it.
+- `cassis schema plan <ddl>` (or `--warehouse` on a project connected to a warehouse) previews what a schema update would change before anything is applied: the source schema diff, the ontology changes Cassis will make (every change on a table placed in the ontology, with everything a drop takes with it) and warnings, terraform-style. `cassis schema apply <ddl>` (or `--plan <id>`) writes the resulting ontology files into the local checkout, app untouched, for review with `git diff`. `cassis schema push <ddl> [--publish]` pushes the new schema and the local ontology to the app (`--yes` in CI). The file speaks only for the schemas it contains — pass `--complete` when it is the project's complete source schema so schemas absent from it are treated as dropped. With `--warehouse` the server introspects the connected warehouse instead of parsing a file; the plan is always whole-source.
 - `cassis projects list` lists the projects your API key can reach — id (what `--project` and `CASSIS_PROJECT_ID` take), name, published ontology version, and data-source dialect — so a pipeline or agent can discover the project id from the terminal instead of fishing it out of a webapp URL.
-- `cassis status` shows the project's published version (number, label, git commit), whether unpublished changes await publication, the git-sync binding, how many Data source review items are pending (with the breaking count, when there are any), and how your local git HEAD relates to the published commit (in sync / N commits ahead / diverged). `cassis status --watch` polls until the published commit matches your local HEAD — e.g. right after merging a PR whose CI publishes the ontology — instead of watching the GitHub Actions tab.
+- `cassis status` shows the project's published version (number, label, git commit), whether unpublished changes await publication, the git-sync binding, a schema plan waiting to be applied, and how your local git HEAD relates to the published commit (in sync / N commits ahead / diverged). `cassis status --watch` polls until the published commit matches your local HEAD — e.g. right after merging a PR whose CI publishes the ontology — instead of watching the GitHub Actions tab.
 - `cassis issues` triages the issues Cassis raised on the project — what it found wrong while answering questions (an ontology gap, missing data) — without leaving the checkout: `issues list` (filterable by status, impact and cause), `issues show <id>` for the diagnosis, suggested action and the occurrences behind it, `issues evidence <id> <occurrence-id>` for what the agent actually saw, and `issues resolve` / `dismiss` / `reopen` once you've acted on it.
-- `cassis source-changes` reads the project's Data source review queue — the schema drift Cassis detected between the source and what the ontology tracks: `source-changes list` (paginated, pending by default, breaking severity flagged) and `source-changes show <id>` for one change's impact references and suggested edit. Read-only: approving or dismissing stays in the webapp; fix headlessly by editing the ontology files and opening a pull request.
 - `cassis verify` runs the full local gate in one verb — `ontology fmt --check`, `ontology check`, `eval run` — stopping at the first failure. One command in a checkout ("is this change safe to merge?"), one job in CI. `--no-eval` skips the eval suite.
 
 ## Install
@@ -125,13 +124,20 @@ cassis eval delete-case 019f0000-0000-7000-8000-0000000000ca --project ...
 # Pull the source schema into <base-path>/.schema.json (gitignored local snapshot):
 cassis schema pull
 
-# Push a DDL file to detect source-schema changes (DDL-only projects);
-# exits 0 only once the run completed and the schema is applied:
-cassis schema push schema.sql
+# Preview, apply locally and push a schema update from a DDL file (DDL-only projects):
+cassis schema plan schema.sql --complete
+cassis schema apply schema.sql --complete      # writes cassis/ locally
+cassis schema push schema.sql --complete --yes  # schema + ontology to the app
+cassis schema plan --warehouse                   # warehouse-connected projects: introspect instead
 
 # List the projects the API key can reach (id, name, published version, dialect):
 cassis projects list
 
+# Refresh the issues from the conversations nobody has analyzed yet (the same pass as the
+# webapp's "Analyze conversations" button; waits for the result, --no-wait returns at once,
+# and Ctrl-C cancels the run server-side and exits 130):
+cassis issues analyze
+
 # Triage the issues Cassis raised (filter by --status/--impact/--cause; --json for raw output):
 cassis issues list --status open
 cassis issues show 019f0000-0000-7000-8000-0000000000e1
@@ -190,9 +196,9 @@ cassis ontology fmt --check
 | Code | Meaning                                                                        |
 | ---- | ------------------------------------------------------------------------------ |
 | 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; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project; schema push: failed or cancelled detection run, or the project won't accept the push (a run is already in flight, or it is warehouse-connected rather than DDL-only); source-changes show: no such change in the project) |
+| 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; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project; issues analyze: failed or cancelled analysis run; schema plan/apply: the plan failed (unparseable or truncated DDL), is stale or expired, the apply failed, or the project won't accept it (a plan is being applied, a DDL was given for a warehouse-connected project, or --warehouse for a DDL-only one)) |
 | 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 eval run already active, out of credits, or `--timeout` reached |
+| 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another eval run or issue analysis already active, out of credits, or `--timeout` reached |
 
 Commands that send the local tree (`check`, `fmt`, `upload`, `eval run`, `test`) accept up to
 20,000 ontology files / 100 MB total (path + content bytes) — sized for ontologies of

{cassis_cli-1.6.0 → cassis_cli-2.0.0}/README.md

@@ -13,11 +13,10 @@ Validate, test and evaluate your ontology from your terminal, then publish it. T
 - `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.
 - `cassis eval list-cases` and `cassis eval delete-case` maintain the suite: list the current cases with their ids, and prune one that is stale or wrong (e.g. its gold SQL encodes a definition the ontology has since changed).
-- `cassis schema push` uploads a DDL file to detect source-schema changes on a DDL-only project (same as the webapp's "Update from DDL" button): Cassis diffs the DDL against the ontology and surfaces added, dropped, and changed objects in Ontology > Review > Data source for approval. The file speaks only for the schemas it contains — a partial export (one schema of many) never removes the others; pass `--complete` when it is the project's complete source schema so schemas absent from it are treated as dropped. Waits for the detection run to finish and exits 0 only when it completed — the schema is stored and applied atomically with run completion, so exit 0 means the DDL parsed and the project now uses it.
+- `cassis schema plan <ddl>` (or `--warehouse` on a project connected to a warehouse) previews what a schema update would change before anything is applied: the source schema diff, the ontology changes Cassis will make (every change on a table placed in the ontology, with everything a drop takes with it) and warnings, terraform-style. `cassis schema apply <ddl>` (or `--plan <id>`) writes the resulting ontology files into the local checkout, app untouched, for review with `git diff`. `cassis schema push <ddl> [--publish]` pushes the new schema and the local ontology to the app (`--yes` in CI). The file speaks only for the schemas it contains — pass `--complete` when it is the project's complete source schema so schemas absent from it are treated as dropped. With `--warehouse` the server introspects the connected warehouse instead of parsing a file; the plan is always whole-source.
 - `cassis projects list` lists the projects your API key can reach — id (what `--project` and `CASSIS_PROJECT_ID` take), name, published ontology version, and data-source dialect — so a pipeline or agent can discover the project id from the terminal instead of fishing it out of a webapp URL.
-- `cassis status` shows the project's published version (number, label, git commit), whether unpublished changes await publication, the git-sync binding, how many Data source review items are pending (with the breaking count, when there are any), and how your local git HEAD relates to the published commit (in sync / N commits ahead / diverged). `cassis status --watch` polls until the published commit matches your local HEAD — e.g. right after merging a PR whose CI publishes the ontology — instead of watching the GitHub Actions tab.
+- `cassis status` shows the project's published version (number, label, git commit), whether unpublished changes await publication, the git-sync binding, a schema plan waiting to be applied, and how your local git HEAD relates to the published commit (in sync / N commits ahead / diverged). `cassis status --watch` polls until the published commit matches your local HEAD — e.g. right after merging a PR whose CI publishes the ontology — instead of watching the GitHub Actions tab.
 - `cassis issues` triages the issues Cassis raised on the project — what it found wrong while answering questions (an ontology gap, missing data) — without leaving the checkout: `issues list` (filterable by status, impact and cause), `issues show <id>` for the diagnosis, suggested action and the occurrences behind it, `issues evidence <id> <occurrence-id>` for what the agent actually saw, and `issues resolve` / `dismiss` / `reopen` once you've acted on it.
-- `cassis source-changes` reads the project's Data source review queue — the schema drift Cassis detected between the source and what the ontology tracks: `source-changes list` (paginated, pending by default, breaking severity flagged) and `source-changes show <id>` for one change's impact references and suggested edit. Read-only: approving or dismissing stays in the webapp; fix headlessly by editing the ontology files and opening a pull request.
 - `cassis verify` runs the full local gate in one verb — `ontology fmt --check`, `ontology check`, `eval run` — stopping at the first failure. One command in a checkout ("is this change safe to merge?"), one job in CI. `--no-eval` skips the eval suite.
 
 ## Install
@@ -103,13 +102,20 @@ cassis eval delete-case 019f0000-0000-7000-8000-0000000000ca --project ...
 # Pull the source schema into <base-path>/.schema.json (gitignored local snapshot):
 cassis schema pull
 
-# Push a DDL file to detect source-schema changes (DDL-only projects);
-# exits 0 only once the run completed and the schema is applied:
-cassis schema push schema.sql
+# Preview, apply locally and push a schema update from a DDL file (DDL-only projects):
+cassis schema plan schema.sql --complete
+cassis schema apply schema.sql --complete      # writes cassis/ locally
+cassis schema push schema.sql --complete --yes  # schema + ontology to the app
+cassis schema plan --warehouse                   # warehouse-connected projects: introspect instead
 
 # List the projects the API key can reach (id, name, published version, dialect):
 cassis projects list
 
+# Refresh the issues from the conversations nobody has analyzed yet (the same pass as the
+# webapp's "Analyze conversations" button; waits for the result, --no-wait returns at once,
+# and Ctrl-C cancels the run server-side and exits 130):
+cassis issues analyze
+
 # Triage the issues Cassis raised (filter by --status/--impact/--cause; --json for raw output):
 cassis issues list --status open
 cassis issues show 019f0000-0000-7000-8000-0000000000e1
@@ -168,9 +174,9 @@ cassis ontology fmt --check
 | Code | Meaning                                                                        |
 | ---- | ------------------------------------------------------------------------------ |
 | 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; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project; schema push: failed or cancelled detection run, or the project won't accept the push (a run is already in flight, or it is warehouse-connected rather than DDL-only); source-changes show: no such change in the project) |
+| 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; add-case: duplicate question or gold SQL that does not run; delete-case: no such case in the project; issues: no such issue or occurrence in the project; issues analyze: failed or cancelled analysis run; schema plan/apply: the plan failed (unparseable or truncated DDL), is stale or expired, the apply failed, or the project won't accept it (a plan is being applied, a DDL was given for a warehouse-connected project, or --warehouse for a DDL-only one)) |
 | 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 eval run already active, out of credits, or `--timeout` reached |
+| 3    | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another eval run or issue analysis already active, out of credits, or `--timeout` reached |
 
 Commands that send the local tree (`check`, `fmt`, `upload`, `eval run`, `test`) accept up to
 20,000 ontology files / 100 MB total (path + content bytes) — sized for ontologies of

{cassis_cli-1.6.0 → cassis_cli-2.0.0}/cassis_cli/api.py

@@ -353,11 +353,57 @@ def get_schema_export(
     return result
 
 
-class SourceChangeConflictError(ApiError):
-    """A concurrent detection run is already active, or the project has a connected data source."""
+class SchemaPlanConflictError(ApiError):
+    """409 from the schema-plan routes: a plan is already active, the project is connected, the plan is stale / expired / not ready."""
 
 
-def post_detect_from_ddl(
+class SchemaPlanNotFoundError(ApiError):
+    """404 with the server's exact detail `"Schema plan not found"` (a project-scope 404 is a different error)."""
+
+
+class ServerTooOldError(ApiError):
+    """The server has no schema-plan routes (bare FastAPI 404): upgrade the server first."""
+
+
+_SCHEMA_PLAN_NOT_FOUND = "Schema plan not found"
+
+
+def _raise_for_schema_plan_status(response: httpx.Response) -> None:
+    """Map the schema-plan routes' error statuses to the CLI's exceptions; return on 2xx.
+
+    One ladder for every plan route (start, read, apply, checkout): the 409
+    conflict and the exact-detail 404 are wire contracts cassis-cli matches.
+    A bare FastAPI 404 means the server predates schema plans altogether.
+    """
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    if response.status_code == 409:
+        raise SchemaPlanConflictError(str(_detail_or_text(response)))
+    if response.status_code == 404:
+        detail = _detail_or_text(response)
+        if detail == _SCHEMA_PLAN_NOT_FOUND:
+            raise SchemaPlanNotFoundError(_SCHEMA_PLAN_NOT_FOUND)
+        if detail == "Not Found":
+            raise ServerTooOldError(
+                "This Cassis server has no schema plans yet: upgrade the server first, "
+                "or pin cassis-cli<2.0 to keep the previous `schema push`."
+            )
+        raise _project_scope_error(response)
+    if response.status_code == 403:
+        raise _project_scope_error(response)
+    if response.status_code >= 400:
+        raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
+
+
+def _schema_plan_response(response: httpx.Response, url: str) -> dict[str, Any]:
+    _raise_for_schema_plan_status(response)
+    result = _parse_json_response(response, url)
+    if not isinstance(result, dict) or "id" not in result or "status" not in result:
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def post_schema_plan(
     *,
     api_url: str,
     api_key: str,
@@ -366,10 +412,10 @@ def post_detect_from_ddl(
     complete_source: bool = False,
     transport: Optional[httpx.BaseTransport] = None,
 ) -> dict[str, Any]:
-    """POST /api/ci/projects/{project_id}/source-changes/detect-from-ddl and return the run record."""
-    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/source-changes/detect-from-ddl"
+    """POST /api/ci/projects/{project_id}/schema/plans and return the PLANNING plan record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/schema/plans"
     try:
-        with _client(transport=transport) as client:
+        with _client(timeout=ONTOLOGY_TREE_TIMEOUT_SECONDS, transport=transport) as client:
             response = client.post(
                 url,
                 json={"ddl": ddl, "complete_source": complete_source},
@@ -377,49 +423,88 @@ def post_detect_from_ddl(
             )
     except httpx.HTTPError as exc:
         raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
+    return _schema_plan_response(response, url)
 
-    if response.status_code == 401:
-        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
-    if response.status_code == 409:
-        raise SourceChangeConflictError(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 "run_id" not in result:
-        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
-    return result
+
+def post_schema_plan_warehouse(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST /api/ci/projects/{project_id}/schema/plans/warehouse and return the PLANNING plan record.
+
+    The server introspects the project's connected warehouse instead of parsing
+    a DDL; the plan is always whole-source.
+    """
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/schema/plans/warehouse"
+    try:
+        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
+    return _schema_plan_response(response, url)
 
 
-def get_source_change_run(
+def get_schema_plan(
     *,
     api_url: str,
     api_key: str,
     project_id: str,
-    run_id: str,
+    plan_id: str,
     transport: Optional[httpx.BaseTransport] = None,
 ) -> dict[str, Any]:
-    """GET /api/ci/projects/{project_id}/source-changes/runs/{run_id} and return the run record."""
-    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/source-changes/runs/{run_id}"
+    """GET /api/ci/projects/{project_id}/schema/plans/{plan_id} and return the plan record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/schema/plans/{plan_id}"
     try:
         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
+    return _schema_plan_response(response, url)
 
-    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 get_schema_plan_checkout(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    plan_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """GET /api/ci/projects/{project_id}/schema/plans/{plan_id}/checkout: the post-apply ontology tree."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/schema/plans/{plan_id}/checkout"
+    try:
+        with _client(timeout=ONTOLOGY_TREE_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
+    _raise_for_schema_plan_status(response)
     result = _parse_json_response(response, url)
-    if not isinstance(result, dict) or "run_id" not in result:
+    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
 
 
+def post_schema_plan_apply(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    plan_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST /api/ci/projects/{project_id}/schema/plans/{plan_id}/apply and return the APPLYING plan record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/schema/plans/{plan_id}/apply"
+    try:
+        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
+    return _schema_plan_response(response, url)
+
+
 def post_eval_run_start(
     *,
     api_url: str,
@@ -635,7 +720,11 @@ def post_eval_run_cancel(
 
 
 class IssueNotFoundError(ApiError):
-    """The project has no issue (or occurrence) with this id."""
+    """The project has no issue, occurrence or issue-analysis run with this id.
+
+    Raised off the server's exact 404 detail, so it separates "this id doesn't
+    exist" from "this project isn't in scope for your key", which 404s too.
+    """
 
 
 def _get_issue_json(
@@ -645,8 +734,14 @@ def _get_issue_json(
     *,
     params: Optional[dict[str, str]] = None,
     not_found_message: Optional[str] = None,
+    not_found_detail: str = "Issue not found",
 ) -> Any:
-    """GET an issues URL with the shared error mapping."""
+    """GET an issues URL with the shared error mapping.
+
+    `not_found_detail` is the server's exact 404 detail for "this id does not
+    exist in the project" — `"Issue not found"` for issues and occurrences,
+    `"Issue-analysis run not found"` for analysis runs.
+    """
     try:
         with _client(transport=transport) as client:
             response = client.get(url, params=params, headers={"Authorization": f"Bearer {api_key}"})
@@ -657,8 +752,8 @@ def _get_issue_json(
         raise AuthError("The Cassis API rejected the API key (invalid or expired).")
     # Exact-match wire contract with the issue endpoints' 404 detail (see the
     # issue routes in backend/app/endpoints/ci.py): it distinguishes a missing
-    # issue or occurrence (exit 1) from a project-scope 404 (exit 3).
-    if response.status_code == 404 and not_found_message and _detail_or_text(response) == "Issue not found":
+    # issue, occurrence or run (exit 1) from a project-scope 404 (exit 3).
+    if response.status_code == 404 and not_found_message and _detail_or_text(response) == not_found_detail:
         raise IssueNotFoundError(not_found_message)
     if response.status_code in (403, 404):
         raise _project_scope_error(response)
@@ -761,80 +856,6 @@ def post_issue_status(
     return result
 
 
-class SourceChangeNotFoundError(ApiError):
-    """The project has no source change with this id."""
-
-
-def get_source_changes(
-    *,
-    api_url: str,
-    api_key: str,
-    project_id: str,
-    status: Optional[str] = None,
-    limit: Optional[int] = None,
-    offset: Optional[int] = None,
-    transport: Optional[httpx.BaseTransport] = None,
-) -> dict[str, Any]:
-    """GET /api/ci/projects/{project_id}/source-changes and return the {items, total} page."""
-    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/source-changes"
-    params: dict[str, str] = {}
-    if status:
-        params["status"] = status
-    if limit is not None:
-        params["limit"] = str(limit)
-    if offset is not None:
-        params["offset"] = str(offset)
-    try:
-        with _client(transport=transport) as client:
-            response = client.get(url, params=params or None, 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("items"), list) or "total" not in result:
-        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
-    return result
-
-
-def get_source_change(
-    *,
-    api_url: str,
-    api_key: str,
-    project_id: str,
-    change_id: str,
-    transport: Optional[httpx.BaseTransport] = None,
-) -> dict[str, Any]:
-    """GET /api/ci/projects/{project_id}/source-changes/{change_id} and return the full change."""
-    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/source-changes/{change_id}"
-    try:
-        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
-
-    if response.status_code == 401:
-        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
-    # Exact-match wire contract with the source-change endpoints' 404 detail
-    # (see backend/app/endpoints/ci.py): it distinguishes a missing change
-    # (exit 1) from a project-scope 404 (exit 3).
-    if response.status_code == 404 and _detail_or_text(response) == "Source change not found":
-        raise SourceChangeNotFoundError(f"No source change {change_id} in project {project_id}.")
-    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 "id" not in result:
-        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
-    return result
-
-
 def post_ontology_fmt(
     *,
     api_url: str,
@@ -925,3 +946,102 @@ def post_ontology_test(
     if not isinstance(result, dict) or "status" not in result:
         raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
     return result
+
+
+class IssueAnalysisActiveError(ApiError):
+    """An issue-analysis run is already in flight for the project (HTTP 409)."""
+
+
+class NothingToAnalyzeError(ApiError):
+    """Every conversation on the project has already been analyzed (HTTP 422)."""
+
+
+_ANALYSIS_RUN_KEYS = ("id", "status", "total_chats", "chats_analyzed", "occurrences_created", "issues_touched")
+
+
+def _check_analysis_run_shape(result: Any, url: str) -> dict[str, Any]:
+    if not isinstance(result, dict) or not all(key in result for key in _ANALYSIS_RUN_KEYS):
+        raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
+    return result
+
+
+def post_issue_analysis_start(
+    *,
+    api_url: str,
+    api_key: str,
+    project_id: str,
+    transport: Optional[httpx.BaseTransport] = None,
+) -> dict[str, Any]:
+    """POST /api/ci/projects/{project_id}/issue-analysis/runs and return the run record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/issue-analysis/runs"
+    try:
+        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
+
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    if response.status_code == 409:
+        raise IssueAnalysisActiveError(
+            "An issue analysis is already running for this project — wait for it to finish, "
+            "or cancel it from the webapp's Issues page."
+        )
+    if response.status_code == 422 and "analyz" in response.text.lower():
+        # The route takes no body, so its 422 is the server's "nothing to
+        # analyze" answer; any other 422 falls through to the generic error.
+        raise NothingToAnalyzeError("Nothing to analyze: every conversation on this project has already been analyzed.")
+    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 _check_analysis_run_shape(_parse_json_response(response, url), url)
+
+
+def get_issue_analysis_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}/issue-analysis/runs/{run_id} and return the run record."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/issue-analysis/runs/{run_id}"
+    return _check_analysis_run_shape(
+        _get_issue_json(
+            url,
+            api_key,
+            transport,
+            not_found_message=f"No issue-analysis run {run_id} in this project.",
+            not_found_detail="Issue-analysis run not found",
+        ),
+        url,
+    )
+
+
+def post_issue_analysis_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}/issue-analysis/runs/{run_id}/cancel."""
+    url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/issue-analysis/runs/{run_id}/cancel"
+    try:
+        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
+    if response.status_code == 401:
+        raise AuthError("The Cassis API rejected the API key (invalid or expired).")
+    # Same exact-match contract as `get_issue_analysis_run`: a missing run is
+    # not a project-scope problem.
+    if response.status_code == 404 and _detail_or_text(response) == "Issue-analysis run not found":
+        raise IssueNotFoundError(f"No issue-analysis run {run_id} in this project.")
+    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]}")