cassis-cli 0.1.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. cassis_cli-0.3.0/PKG-INFO +197 -0
  2. cassis_cli-0.3.0/README.md +176 -0
  3. {cassis_cli-0.1.0 → cassis_cli-0.3.0}/cassis_cli/__init__.py +1 -1
  4. cassis_cli-0.3.0/cassis_cli/api.py +286 -0
  5. cassis_cli-0.1.0/cassis_cli/ontology.py → cassis_cli-0.3.0/cassis_cli/common.py +18 -64
  6. cassis_cli-0.3.0/cassis_cli/eval.py +356 -0
  7. {cassis_cli-0.1.0 → cassis_cli-0.3.0}/cassis_cli/main.py +2 -0
  8. cassis_cli-0.3.0/cassis_cli/ontology.py +283 -0
  9. {cassis_cli-0.1.0 → cassis_cli-0.3.0}/pyproject.toml +2 -2
  10. cassis_cli-0.1.0/PKG-INFO +0 -98
  11. cassis_cli-0.1.0/README.md +0 -77
  12. cassis_cli-0.1.0/cassis_cli/api.py +0 -56
cassis_cli-0.3.0/PKG-INFO ADDED
@@ -0,0 +1,197 @@
1
+ Metadata-Version: 2.4
2
+ Name: cassis-cli
3
+ Version: 0.3.0
4
+ Summary: Cassis CLI — run Cassis actions (ontology validation, upload and publish) from your CI pipelines
5
+ License: Proprietary
6
+ Keywords: cassis,ontology,ci,text-to-sql
7
+ Author: Cassis
8
+ Author-email: tech.admin@getcassis.com
9
+ Requires-Python: >=3.10,<4.0
10
+ Classifier: License :: Other/Proprietary License
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.10
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Programming Language :: Python :: 3.14
17
+ Requires-Dist: httpx (>=0.24,<1.0)
18
+ Requires-Dist: typer (>=0.12,<1.0)
19
+ Description-Content-Type: text/markdown
20
+
21
+ # Cassis CLI
22
+
23
+ Run Cassis actions from your CI pipelines:
24
+
25
+ - `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.
26
+ - `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.
27
+ - `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).
28
+ - `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.
29
+
30
+ ## Install
31
+
32
+ ```bash
33
+ pip install cassis-cli
34
+ ```
35
+
36
+ ## Setup
37
+
38
+ 1. Create an API key in Cassis under **Organization settings → API keys** (keys start with `sk-k6-`).
39
+ 2. Store it as a CI secret and expose it as `CASSIS_API_KEY`.
40
+ 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`).
41
+
42
+ ## Usage
43
+
44
+ ```bash
45
+ # From the root of a repository synced with Cassis (contains the ontology export directory, cassis/ by default):
46
+ cassis ontology check
47
+
48
+ # Or point at the checkout explicitly:
49
+ cassis ontology check /path/to/checkout
50
+
51
+ # Download the project's unpublished ontology into the checkout (full sync;
52
+ # review with git diff — pass --no-prune to keep local files it would delete):
53
+ cassis ontology pull --project 019f0000-0000-7000-8000-000000000000
54
+
55
+ # Upload the ontology to a project and publish it immediately:
56
+ cassis ontology upload --project 019f0000-0000-7000-8000-000000000000
57
+
58
+ # Upload without publishing (the tree becomes the project's unpublished ontology, to review in Cassis):
59
+ cassis ontology upload --project ... --no-publish
60
+
61
+ # Label the published version:
62
+ cassis ontology upload --project ... --label "release 1.2"
63
+
64
+ # Machine-readable output:
65
+ cassis ontology check --json
66
+ cassis ontology pull --project ... --json
67
+ cassis ontology upload --project ... --json
68
+ cassis eval run --project ... --json
69
+
70
+ # Run the eval suite against the local ontology files and wait for results
71
+ # (the run is labelled with your git branch name in the Evals page):
72
+ cassis eval run --project ...
73
+
74
+ # Run against an existing Cassis ontology branch, or the unpublished ontology:
75
+ cassis eval run --project ... --branch feature-x
76
+
77
+ # Start the run and return immediately (poll in the webapp):
78
+ cassis eval run --project ... --no-wait
79
+ ```
80
+
81
+ Configuration (flags take precedence over env vars):
82
+
83
+ | Flag | Env var | Default |
84
+ | ----------- | ---------------- | --------------------------- |
85
+ | `--api-key` | `CASSIS_API_KEY` | — (required) |
86
+ | `--api-url` | `CASSIS_API_URL` | `https://app.getcassis.com` |
87
+ | `--base-path` | `CASSIS_BASE_PATH` | `cassis` — must match the project's git-sync "Path" setting |
88
+ | `--project` (pull, upload, eval run) | `CASSIS_PROJECT_ID` | — (required) |
89
+
90
+ `cassis eval run` also accepts `--label` (run label in the Evals page; defaults
91
+ to the branch name from the CI environment or the local git checkout; rejected
92
+ with `--branch`, whose runs are labelled with the branch name), `--wait/--no-wait`, `--poll-interval` (5 s),
93
+ `--timeout` (30 min — the run keeps going server-side if the CLI stops waiting),
94
+ and Ctrl-C cancels the run (exit 130). It prints a deep link to the run's page
95
+ in the Evals UI; `--app-url` / `CASSIS_APP_URL` overrides the link's base URL
96
+ when the webapp is not served from the API host (defaults to `--api-url`).
97
+
98
+ ### Exit codes
99
+
100
+ | Code | Meaning |
101
+ | ---- | ------------------------------------------------------------------------------ |
102
+ | 0 | Ontology is valid (check) / pulled (pull) / uploaded (upload) / eval run completed all-passed (eval run) |
103
+ | 1 | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run) |
104
+ | 2 | Usage error (missing API key or project, no ontology directory, unreadable file, tree over the size limits) |
105
+ | 3 | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another run already active, or `--timeout` reached |
106
+
107
+ Commands that send the local tree (`check`, `upload`, `eval run`) accept up to
108
+ 2000 YAML files / 5 MB total — far above real ontologies (a few hundred small
109
+ files). Beyond that the CLI fails fast with exit 2 before uploading anything;
110
+ double-check `--base-path` if you hit it.
111
+
112
+ `upload` replaces the project's entire ontology with the uploaded tree. A
113
+ never-published project always goes live immediately on first upload (even
114
+ with `--no-publish`), matching imports from the Cassis app. Publishing is
115
+ idempotent: re-uploading content identical to the published version reports
116
+ that version instead of creating a new one, so re-running the CI job on
117
+ unchanged files is a no-op.
118
+
119
+ ### GitHub Actions example
120
+
121
+ ```yaml
122
+ jobs:
123
+ ontology-check:
124
+ runs-on: ubuntu-latest
125
+ steps:
126
+ - uses: actions/checkout@v4
127
+ - uses: actions/setup-python@v5
128
+ with:
129
+ python-version: "3.12"
130
+ - run: pip install cassis-cli
131
+ - run: cassis ontology check
132
+ env:
133
+ CASSIS_API_KEY: ${{ secrets.CASSIS_API_KEY }}
134
+
135
+ ontology-eval:
136
+ runs-on: ubuntu-latest
137
+ if: github.event_name == 'pull_request'
138
+ steps:
139
+ - uses: actions/checkout@v4
140
+ - uses: actions/setup-python@v5
141
+ with:
142
+ python-version: "3.12"
143
+ - run: pip install cassis-cli
144
+ - run: cassis eval run
145
+ env:
146
+ CASSIS_API_KEY: ${{ secrets.CASSIS_API_KEY }}
147
+ CASSIS_PROJECT_ID: ${{ vars.CASSIS_PROJECT_ID }}
148
+
149
+ ontology-publish:
150
+ runs-on: ubuntu-latest
151
+ if: github.ref == 'refs/heads/main'
152
+ steps:
153
+ - uses: actions/checkout@v4
154
+ - uses: actions/setup-python@v5
155
+ with:
156
+ python-version: "3.12"
157
+ - run: pip install cassis-cli
158
+ - run: cassis ontology upload
159
+ env:
160
+ CASSIS_API_KEY: ${{ secrets.CASSIS_API_KEY }}
161
+ CASSIS_PROJECT_ID: ${{ vars.CASSIS_PROJECT_ID }}
162
+ ```
163
+
164
+ ### GitLab CI example
165
+
166
+ ```yaml
167
+ ontology-check:
168
+ image: python:3.12-slim
169
+ script:
170
+ - pip install cassis-cli
171
+ - cassis ontology check
172
+ variables:
173
+ CASSIS_API_KEY: $CASSIS_API_KEY
174
+
175
+ ontology-eval:
176
+ image: python:3.12-slim
177
+ rules:
178
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
179
+ script:
180
+ - pip install cassis-cli
181
+ - cassis eval run
182
+ variables:
183
+ CASSIS_API_KEY: $CASSIS_API_KEY
184
+ CASSIS_PROJECT_ID: $CASSIS_PROJECT_ID
185
+
186
+ ontology-publish:
187
+ image: python:3.12-slim
188
+ rules:
189
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
190
+ script:
191
+ - pip install cassis-cli
192
+ - cassis ontology upload
193
+ variables:
194
+ CASSIS_API_KEY: $CASSIS_API_KEY
195
+ CASSIS_PROJECT_ID: $CASSIS_PROJECT_ID
196
+ ```
197
+
cassis_cli-0.3.0/README.md ADDED
@@ -0,0 +1,176 @@
1
+ # Cassis CLI
2
+
3
+ Run Cassis actions from your CI pipelines:
4
+
5
+ - `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.
6
+ - `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.
7
+ - `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).
8
+ - `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.
9
+
10
+ ## Install
11
+
12
+ ```bash
13
+ pip install cassis-cli
14
+ ```
15
+
16
+ ## Setup
17
+
18
+ 1. Create an API key in Cassis under **Organization settings → API keys** (keys start with `sk-k6-`).
19
+ 2. Store it as a CI secret and expose it as `CASSIS_API_KEY`.
20
+ 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`).
21
+
22
+ ## Usage
23
+
24
+ ```bash
25
+ # From the root of a repository synced with Cassis (contains the ontology export directory, cassis/ by default):
26
+ cassis ontology check
27
+
28
+ # Or point at the checkout explicitly:
29
+ cassis ontology check /path/to/checkout
30
+
31
+ # Download the project's unpublished ontology into the checkout (full sync;
32
+ # review with git diff — pass --no-prune to keep local files it would delete):
33
+ cassis ontology pull --project 019f0000-0000-7000-8000-000000000000
34
+
35
+ # Upload the ontology to a project and publish it immediately:
36
+ cassis ontology upload --project 019f0000-0000-7000-8000-000000000000
37
+
38
+ # Upload without publishing (the tree becomes the project's unpublished ontology, to review in Cassis):
39
+ cassis ontology upload --project ... --no-publish
40
+
41
+ # Label the published version:
42
+ cassis ontology upload --project ... --label "release 1.2"
43
+
44
+ # Machine-readable output:
45
+ cassis ontology check --json
46
+ cassis ontology pull --project ... --json
47
+ cassis ontology upload --project ... --json
48
+ cassis eval run --project ... --json
49
+
50
+ # Run the eval suite against the local ontology files and wait for results
51
+ # (the run is labelled with your git branch name in the Evals page):
52
+ cassis eval run --project ...
53
+
54
+ # Run against an existing Cassis ontology branch, or the unpublished ontology:
55
+ cassis eval run --project ... --branch feature-x
56
+
57
+ # Start the run and return immediately (poll in the webapp):
58
+ cassis eval run --project ... --no-wait
59
+ ```
60
+
61
+ Configuration (flags take precedence over env vars):
62
+
63
+ | Flag | Env var | Default |
64
+ | ----------- | ---------------- | --------------------------- |
65
+ | `--api-key` | `CASSIS_API_KEY` | — (required) |
66
+ | `--api-url` | `CASSIS_API_URL` | `https://app.getcassis.com` |
67
+ | `--base-path` | `CASSIS_BASE_PATH` | `cassis` — must match the project's git-sync "Path" setting |
68
+ | `--project` (pull, upload, eval run) | `CASSIS_PROJECT_ID` | — (required) |
69
+
70
+ `cassis eval run` also accepts `--label` (run label in the Evals page; defaults
71
+ to the branch name from the CI environment or the local git checkout; rejected
72
+ with `--branch`, whose runs are labelled with the branch name), `--wait/--no-wait`, `--poll-interval` (5 s),
73
+ `--timeout` (30 min — the run keeps going server-side if the CLI stops waiting),
74
+ and Ctrl-C cancels the run (exit 130). It prints a deep link to the run's page
75
+ in the Evals UI; `--app-url` / `CASSIS_APP_URL` overrides the link's base URL
76
+ when the webapp is not served from the API host (defaults to `--api-url`).
77
+
78
+ ### Exit codes
79
+
80
+ | Code | Meaning |
81
+ | ---- | ------------------------------------------------------------------------------ |
82
+ | 0 | Ontology is valid (check) / pulled (pull) / uploaded (upload) / eval run completed all-passed (eval run) |
83
+ | 1 | Validation failed (check: findings printed; upload: nothing imported; eval run: invalid tree, failed cases, or failed/cancelled run) |
84
+ | 2 | Usage error (missing API key or project, no ontology directory, unreadable file, tree over the size limits) |
85
+ | 3 | Transport/API error (unreachable API, invalid key, inaccessible project, unexpected response), another run already active, or `--timeout` reached |
86
+
87
+ Commands that send the local tree (`check`, `upload`, `eval run`) accept up to
88
+ 2000 YAML files / 5 MB total — far above real ontologies (a few hundred small
89
+ files). Beyond that the CLI fails fast with exit 2 before uploading anything;
90
+ double-check `--base-path` if you hit it.
91
+
92
+ `upload` replaces the project's entire ontology with the uploaded tree. A
93
+ never-published project always goes live immediately on first upload (even
94
+ with `--no-publish`), matching imports from the Cassis app. Publishing is
95
+ idempotent: re-uploading content identical to the published version reports
96
+ that version instead of creating a new one, so re-running the CI job on
97
+ unchanged files is a no-op.
98
+
99
+ ### GitHub Actions example
100
+
101
+ ```yaml
102
+ jobs:
103
+ ontology-check:
104
+ runs-on: ubuntu-latest
105
+ steps:
106
+ - uses: actions/checkout@v4
107
+ - uses: actions/setup-python@v5
108
+ with:
109
+ python-version: "3.12"
110
+ - run: pip install cassis-cli
111
+ - run: cassis ontology check
112
+ env:
113
+ CASSIS_API_KEY: ${{ secrets.CASSIS_API_KEY }}
114
+
115
+ ontology-eval:
116
+ runs-on: ubuntu-latest
117
+ if: github.event_name == 'pull_request'
118
+ steps:
119
+ - uses: actions/checkout@v4
120
+ - uses: actions/setup-python@v5
121
+ with:
122
+ python-version: "3.12"
123
+ - run: pip install cassis-cli
124
+ - run: cassis eval run
125
+ env:
126
+ CASSIS_API_KEY: ${{ secrets.CASSIS_API_KEY }}
127
+ CASSIS_PROJECT_ID: ${{ vars.CASSIS_PROJECT_ID }}
128
+
129
+ ontology-publish:
130
+ runs-on: ubuntu-latest
131
+ if: github.ref == 'refs/heads/main'
132
+ steps:
133
+ - uses: actions/checkout@v4
134
+ - uses: actions/setup-python@v5
135
+ with:
136
+ python-version: "3.12"
137
+ - run: pip install cassis-cli
138
+ - run: cassis ontology upload
139
+ env:
140
+ CASSIS_API_KEY: ${{ secrets.CASSIS_API_KEY }}
141
+ CASSIS_PROJECT_ID: ${{ vars.CASSIS_PROJECT_ID }}
142
+ ```
143
+
144
+ ### GitLab CI example
145
+
146
+ ```yaml
147
+ ontology-check:
148
+ image: python:3.12-slim
149
+ script:
150
+ - pip install cassis-cli
151
+ - cassis ontology check
152
+ variables:
153
+ CASSIS_API_KEY: $CASSIS_API_KEY
154
+
155
+ ontology-eval:
156
+ image: python:3.12-slim
157
+ rules:
158
+ - if: $CI_PIPELINE_SOURCE == "merge_request_event"
159
+ script:
160
+ - pip install cassis-cli
161
+ - cassis eval run
162
+ variables:
163
+ CASSIS_API_KEY: $CASSIS_API_KEY
164
+ CASSIS_PROJECT_ID: $CASSIS_PROJECT_ID
165
+
166
+ ontology-publish:
167
+ image: python:3.12-slim
168
+ rules:
169
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
170
+ script:
171
+ - pip install cassis-cli
172
+ - cassis ontology upload
173
+ variables:
174
+ CASSIS_API_KEY: $CASSIS_API_KEY
175
+ CASSIS_PROJECT_ID: $CASSIS_PROJECT_ID
176
+ ```
{cassis_cli-0.1.0 → cassis_cli-0.3.0}/cassis_cli/__init__.py RENAMED
@@ -1,3 +1,3 @@
1
1
  """Cassis CLI — run Cassis actions from your CI pipelines."""
2
2
 
3
- __version__ = "0.1.0"
3
+ __version__ = "0.3.0"
cassis_cli-0.3.0/cassis_cli/api.py ADDED
@@ -0,0 +1,286 @@
1
+ """Thin HTTP client for the Cassis API."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any, Optional
6
+
7
+ import httpx
8
+
9
+ DEFAULT_API_URL = "https://app.getcassis.com"
10
+ TIMEOUT_SECONDS = 60.0
11
+
12
+
13
+ class ApiError(Exception):
14
+ """Transport or HTTP-level failure talking to the Cassis API."""
15
+
16
+
17
+ class AuthError(ApiError):
18
+ """The API rejected the API key (401)."""
19
+
20
+
21
+ class UploadValidationError(ApiError):
22
+ """The API rejected the uploaded ontology tree as invalid (400)."""
23
+
24
+
25
+ class EvalStartValidationError(ApiError):
26
+ """The API rejected the eval-run start request (400): invalid tree or no test cases.
27
+
28
+ ``detail`` keeps the structured payload (``{"message", "findings"}`` for an
29
+ invalid tree, or a plain string) for display.
30
+ """
31
+
32
+ def __init__(self, detail: object) -> None:
33
+ super().__init__(str(detail))
34
+ self.detail = detail
35
+
36
+
37
+ class EvalRunActiveError(ApiError):
38
+ """Another eval run is already active for the project (409)."""
39
+
40
+
41
+ def _project_scope_error(response: httpx.Response) -> ApiError:
42
+ # Surface the server's own message when it names the missing resource
43
+ # (e.g. "Branch 'x' not found") — the generic hint covers the rest.
44
+ try:
45
+ detail = response.json().get("detail")
46
+ except ValueError:
47
+ detail = None
48
+ prefix = f"{detail} " if isinstance(detail, str) and detail else ""
49
+ return ApiError(
50
+ f"{prefix}(HTTP {response.status_code}). Check --project and that "
51
+ "the API key belongs to the project's organization and can edit it."
52
+ )
53
+
54
+
55
+ def _parse_json_response(response: httpx.Response, url: str) -> Any:
56
+ try:
57
+ return response.json()
58
+ except ValueError as exc: # json.JSONDecodeError — e.g. a proxy or portal answering HTML with a 200
59
+ raise ApiError(
60
+ f"The Cassis API at {url} returned a non-JSON response — check the API URL and any proxy in between."
61
+ ) from exc
62
+
63
+
64
+ def post_ontology_check(
65
+ *,
66
+ api_url: str,
67
+ api_key: str,
68
+ files: dict[str, str],
69
+ transport: Optional[httpx.BaseTransport] = None,
70
+ ) -> dict[str, Any]:
71
+ """POST the ontology tree to /api/ci/ontology-check and return the response body."""
72
+ url = api_url.rstrip("/") + "/api/ci/ontology-check"
73
+ try:
74
+ with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as client:
75
+ response = client.post(
76
+ url,
77
+ json={"files": files},
78
+ headers={"Authorization": f"Bearer {api_key}"},
79
+ )
80
+ except httpx.HTTPError as exc:
81
+ raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
82
+
83
+ if response.status_code == 401:
84
+ raise AuthError("The Cassis API rejected the API key (invalid or expired).")
85
+ if response.status_code >= 400:
86
+ raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
87
+ result = _parse_json_response(response, url)
88
+ if (
89
+ not isinstance(result, dict)
90
+ or not all(key in result for key in ("passed", "title", "summary"))
91
+ or not isinstance(result.get("findings"), list)
92
+ ):
93
+ raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
94
+ return result
95
+
96
+
97
+ def post_ontology_import(
98
+ *,
99
+ api_url: str,
100
+ api_key: str,
101
+ project_id: str,
102
+ files: dict[str, str],
103
+ publish: bool,
104
+ label: Optional[str] = None,
105
+ transport: Optional[httpx.BaseTransport] = None,
106
+ ) -> dict[str, Any]:
107
+ """POST the ontology tree to /api/ci/projects/{project_id}/ontology/import and return the response body."""
108
+ url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/ontology/import"
109
+ body: dict[str, Any] = {"files": files, "publish": publish}
110
+ if label is not None:
111
+ body["label"] = label
112
+ try:
113
+ with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as client:
114
+ response = client.post(
115
+ url,
116
+ json=body,
117
+ headers={"Authorization": f"Bearer {api_key}"},
118
+ )
119
+ except httpx.HTTPError as exc:
120
+ raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
121
+
122
+ if response.status_code == 401:
123
+ raise AuthError("The Cassis API rejected the API key (invalid or expired).")
124
+ if response.status_code == 400:
125
+ try:
126
+ detail = response.json().get("detail") or response.text[:500]
127
+ except ValueError:
128
+ detail = response.text[:500]
129
+ raise UploadValidationError(str(detail))
130
+ if response.status_code in (403, 404):
131
+ raise _project_scope_error(response)
132
+ if response.status_code >= 400:
133
+ raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
134
+ result = _parse_json_response(response, url)
135
+ if not isinstance(result, dict) or not all(
136
+ key in result for key in ("domain_count", "table_count", "join_count", "metric_count", "published_version")
137
+ ):
138
+ raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
139
+ return result
140
+
141
+
142
+ def get_ontology_export(
143
+ *,
144
+ api_url: str,
145
+ api_key: str,
146
+ project_id: str,
147
+ transport: Optional[httpx.BaseTransport] = None,
148
+ ) -> dict[str, str]:
149
+ """GET /api/ci/projects/{project_id}/ontology/export and return the files tree."""
150
+ url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/ontology/export"
151
+ try:
152
+ with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as client:
153
+ response = client.get(url, headers={"Authorization": f"Bearer {api_key}"})
154
+ except httpx.HTTPError as exc:
155
+ raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
156
+
157
+ if response.status_code == 401:
158
+ raise AuthError("The Cassis API rejected the API key (invalid or expired).")
159
+ if response.status_code in (403, 404):
160
+ raise _project_scope_error(response)
161
+ if response.status_code >= 400:
162
+ raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
163
+ result = _parse_json_response(response, url)
164
+ if not isinstance(result, dict) or not isinstance(result.get("files"), dict):
165
+ raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
166
+ return result["files"]
167
+
168
+
169
+ def post_eval_run_start(
170
+ *,
171
+ api_url: str,
172
+ api_key: str,
173
+ project_id: str,
174
+ files: Optional[dict[str, str]] = None,
175
+ branch: Optional[str] = None,
176
+ label: Optional[str] = None,
177
+ transport: Optional[httpx.BaseTransport] = None,
178
+ ) -> dict[str, Any]:
179
+ """POST to /api/ci/projects/{project_id}/eval/runs and return the run record."""
180
+ url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/eval/runs"
181
+ body: dict[str, Any] = {}
182
+ if files is not None:
183
+ body["files"] = files
184
+ if branch is not None:
185
+ body["branch"] = branch
186
+ if label is not None:
187
+ body["label"] = label
188
+ try:
189
+ with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as client:
190
+ response = client.post(url, json=body, headers={"Authorization": f"Bearer {api_key}"})
191
+ except httpx.HTTPError as exc:
192
+ raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
193
+
194
+ if response.status_code == 401:
195
+ raise AuthError("The Cassis API rejected the API key (invalid or expired).")
196
+ if response.status_code == 400:
197
+ try:
198
+ detail = response.json().get("detail") or response.text[:500]
199
+ except ValueError:
200
+ detail = response.text[:500]
201
+ raise EvalStartValidationError(detail)
202
+ if response.status_code == 409:
203
+ raise EvalRunActiveError(
204
+ "An eval run is already active for this project — wait for it to finish or cancel it "
205
+ "(in the webapp's Evals page, or with the run id printed when it was started)."
206
+ )
207
+ if response.status_code in (403, 404):
208
+ raise _project_scope_error(response)
209
+ if response.status_code >= 400:
210
+ raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
211
+ result = _parse_json_response(response, url)
212
+ if not isinstance(result, dict) or not all(key in result for key in ("run_id", "status", "total_cases")):
213
+ raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
214
+ return result
215
+
216
+
217
+ def _get_eval_json(url: str, api_key: str, transport: Optional[httpx.BaseTransport]) -> Any:
218
+ """GET an eval-run URL with the shared error mapping."""
219
+ try:
220
+ with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as client:
221
+ response = client.get(url, headers={"Authorization": f"Bearer {api_key}"})
222
+ except httpx.HTTPError as exc:
223
+ raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
224
+
225
+ if response.status_code == 401:
226
+ raise AuthError("The Cassis API rejected the API key (invalid or expired).")
227
+ if response.status_code in (403, 404):
228
+ raise _project_scope_error(response)
229
+ if response.status_code >= 400:
230
+ raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")
231
+ return _parse_json_response(response, url)
232
+
233
+
234
+ def get_eval_run(
235
+ *,
236
+ api_url: str,
237
+ api_key: str,
238
+ project_id: str,
239
+ run_id: str,
240
+ transport: Optional[httpx.BaseTransport] = None,
241
+ ) -> dict[str, Any]:
242
+ """GET /api/ci/projects/{project_id}/eval/runs/{run_id} and return the run record."""
243
+ url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/eval/runs/{run_id}"
244
+ result = _get_eval_json(url, api_key, transport)
245
+ if not isinstance(result, dict) or not all(key in result for key in ("run_id", "status", "total_cases")):
246
+ raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
247
+ return result
248
+
249
+
250
+ def get_eval_run_results(
251
+ *,
252
+ api_url: str,
253
+ api_key: str,
254
+ project_id: str,
255
+ run_id: str,
256
+ transport: Optional[httpx.BaseTransport] = None,
257
+ ) -> list[dict[str, Any]]:
258
+ """GET /api/ci/projects/{project_id}/eval/runs/{run_id}/results and return the result list."""
259
+ url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/eval/runs/{run_id}/results"
260
+ result = _get_eval_json(url, api_key, transport)
261
+ if not isinstance(result, list):
262
+ raise ApiError(f"Unexpected response shape from the Cassis API at {url}.")
263
+ return result
264
+
265
+
266
+ def post_eval_run_cancel(
267
+ *,
268
+ api_url: str,
269
+ api_key: str,
270
+ project_id: str,
271
+ run_id: str,
272
+ transport: Optional[httpx.BaseTransport] = None,
273
+ ) -> None:
274
+ """POST /api/ci/projects/{project_id}/eval/runs/{run_id}/cancel."""
275
+ url = api_url.rstrip("/") + f"/api/ci/projects/{project_id}/eval/runs/{run_id}/cancel"
276
+ try:
277
+ with httpx.Client(timeout=TIMEOUT_SECONDS, transport=transport) as client:
278
+ response = client.post(url, headers={"Authorization": f"Bearer {api_key}"})
279
+ except httpx.HTTPError as exc:
280
+ raise ApiError(f"Could not reach the Cassis API at {url}: {exc}") from exc
281
+ if response.status_code == 401:
282
+ raise AuthError("The Cassis API rejected the API key (invalid or expired).")
283
+ if response.status_code in (403, 404):
284
+ raise _project_scope_error(response)
285
+ if response.status_code >= 400:
286
+ raise ApiError(f"Cassis API returned HTTP {response.status_code}: {response.text[:500]}")