gts-agency-python-sdk 0.0.1__py3-none-any.whl

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 (66) hide show
  1. agency_sdk/__init__.py +0 -0
  2. agency_sdk/auth_hooks.py +55 -0
  3. agency_sdk/client.py +212 -0
  4. agency_sdk/credentials.py +54 -0
  5. agency_sdk/delegates/__init__.py +0 -0
  6. agency_sdk/delegates/annotations_client.py +495 -0
  7. agency_sdk/delegates/annotations_dto.py +200 -0
  8. agency_sdk/delegates/base_client.py +126 -0
  9. agency_sdk/delegates/datasets_client.py +109 -0
  10. agency_sdk/delegates/datasets_dto.py +81 -0
  11. agency_sdk/delegates/datasource_client.py +44 -0
  12. agency_sdk/delegates/datasource_dto.py +107 -0
  13. agency_sdk/delegates/files_client.py +184 -0
  14. agency_sdk/delegates/files_dto.py +36 -0
  15. agency_sdk/delegates/gateway_client.py +81 -0
  16. agency_sdk/delegates/gateway_dto.py +37 -0
  17. agency_sdk/delegates/ontology_client.py +203 -0
  18. agency_sdk/delegates/ontology_dto.py +221 -0
  19. agency_sdk/delegates/prompts_client.py +56 -0
  20. agency_sdk/delegates/rules_client.py +33 -0
  21. agency_sdk/delegates/rules_dto.py +108 -0
  22. agency_sdk/delegates/session_client.py +95 -0
  23. agency_sdk/delegates/session_dto.py +94 -0
  24. agency_sdk/delegates/session_templates_client.py +23 -0
  25. agency_sdk/delegates/session_templates_dto.py +27 -0
  26. agency_sdk/delegates/session_vault_client.py +135 -0
  27. agency_sdk/delegates/session_vault_dto.py +75 -0
  28. agency_sdk/delegates/work_queue_client.py +230 -0
  29. agency_sdk/delegates/work_queue_dto.py +127 -0
  30. agency_sdk/domain.py +140 -0
  31. agency_sdk/observability/__init__.py +60 -0
  32. agency_sdk/observability/auth.py +15 -0
  33. agency_sdk/observability/bootstrap.py +344 -0
  34. agency_sdk/test/__init__.py +0 -0
  35. agency_sdk/test/conftest.py +106 -0
  36. agency_sdk/test/test_annotations_client.py +599 -0
  37. agency_sdk/test/test_annotations_dto.py +299 -0
  38. agency_sdk/test/test_base_client.py +153 -0
  39. agency_sdk/test/test_client_facade.py +105 -0
  40. agency_sdk/test/test_credentials.py +67 -0
  41. agency_sdk/test/test_files_client.py +264 -0
  42. agency_sdk/test/test_files_dto.py +93 -0
  43. agency_sdk/test/test_gateway_dto.py +70 -0
  44. agency_sdk/test/test_gateway_facade.py +229 -0
  45. agency_sdk/test/test_gateway_openai.py +76 -0
  46. agency_sdk/test/test_observability_auth.py +125 -0
  47. agency_sdk/test/test_observability_facade_threadsafety.py +50 -0
  48. agency_sdk/test/test_observability_langfuse.py +76 -0
  49. agency_sdk/test/test_observability_packaging.py +78 -0
  50. agency_sdk/test/test_observability_pipeline.py +246 -0
  51. agency_sdk/test/test_ontology_client.py +152 -0
  52. agency_sdk/test/test_ontology_dto.py +158 -0
  53. agency_sdk/test/test_session_client.py +128 -0
  54. agency_sdk/test/test_session_dto.py +75 -0
  55. agency_sdk/test/test_session_templates_client.py +36 -0
  56. agency_sdk/test/test_session_templates_dto.py +45 -0
  57. agency_sdk/test/test_session_vault_client.py +151 -0
  58. agency_sdk/test/test_session_vault_dto.py +27 -0
  59. agency_sdk/test/test_stub_requests.py +39 -0
  60. agency_sdk/test/test_work_queue_client.py +388 -0
  61. agency_sdk/test/test_work_queue_dto.py +233 -0
  62. gts_agency_python_sdk-0.0.1.dist-info/METADATA +221 -0
  63. gts_agency_python_sdk-0.0.1.dist-info/RECORD +66 -0
  64. gts_agency_python_sdk-0.0.1.dist-info/WHEEL +5 -0
  65. gts_agency_python_sdk-0.0.1.dist-info/licenses/LICENSE +201 -0
  66. gts_agency_python_sdk-0.0.1.dist-info/top_level.txt +1 -0
@@ -0,0 +1,495 @@
1
+ """Client for the annotations API.
2
+
3
+ Covers ``/api/annotations`` plus two sibling roots the same capability needs:
4
+ ``/api/annotation-specs`` (job checklists) and ``/api/annotation-workflows`` (the
5
+ review flows a batch is bound to).
6
+
7
+ Publishes a knowledge graph as work for human annotators. There is no single
8
+ "publish" endpoint. A batch is **created** in ``DRAFT``; a workflow must then be
9
+ **bound** to it, because the server resolves every job's governing workflow from the
10
+ batch and refuses the insert when there is none; and the graph **upload** is what
11
+ materialises the jobs and flips the batch to ``ACTIVE``. The graph the upload accepts
12
+ is the same ``create.graph`` payload agents already build for the ontology sandbox
13
+ (``run_id`` / ``vertices`` / ``edges``), so a caller that has one can push it as-is —
14
+ see :meth:`AgencyAnnotationsClient.push_graph`, the one-call convenience over the
15
+ whole flow.
16
+
17
+ Contract verified against gts-comand ``eda4f9ca``
18
+ (``crates/comand/src/handler/annotations.rs``, ``service/annotation_service.rs``,
19
+ ``service/annotation_binding_service.rs``, and the ``annotation_job_before_insert``
20
+ trigger in ``data/95__annotation_state_constraints.sql``). Every handler here requires
21
+ a principal with a local user id **and** organisation write permission on
22
+ ``Resource::Annotations``; ``bind_workflow`` additionally gates on workflow-execute.
23
+ """
24
+
25
+ from __future__ import annotations
26
+
27
+ import json
28
+ from collections.abc import Mapping
29
+ from pathlib import Path
30
+ from typing import Any
31
+
32
+ import requests
33
+
34
+ from agency_sdk.credentials import CredentialsSupplier
35
+ from agency_sdk.delegates.annotations_dto import (
36
+ BATCH_TYPE_GRAPH,
37
+ AnnotationBatchesPagedResult,
38
+ AnnotationBatchResponse,
39
+ AnnotationSpec,
40
+ AnnotationSpecsPagedResult,
41
+ AnnotationWorkflow,
42
+ AnnotationWorkflowsPagedResult,
43
+ BindWorkflowResult,
44
+ CreateBatchResult,
45
+ CreateSpecResult,
46
+ PushGraphResult,
47
+ )
48
+ from agency_sdk.delegates.base_client import BaseDelegateClient
49
+
50
+ #: The job specifications live under their own root, NOT under ``api_path``.
51
+ SPECS_PATH = "/api/annotation-specs"
52
+
53
+ #: The workflows an organisation can bind to a batch — also their own root.
54
+ WORKFLOWS_PATH = "/api/annotation-workflows"
55
+
56
+ #: ``job_type`` value that binds a workflow as the batch's default, covering every
57
+ #: job type. The server's insert trigger resolves ``(batch_id, job_type)`` first and
58
+ #: falls back to this, so a single default binding is enough for any upload.
59
+ WILDCARD_JOB_TYPE = "*"
60
+
61
+ #: Upload bodies are assembled in memory and the server caps the request body at
62
+ #: 50 MiB; a graph larger than this is rejected before it reaches the handler.
63
+ UPLOAD_TIMEOUT_SECONDS = 300
64
+
65
+
66
+ def _command_id(body: Mapping[str, Any], subject: str) -> str:
67
+ """Lift ``data.id`` out of the standard ``{success, message, data}`` envelope.
68
+
69
+ A 2xx without an id means the server accepted the command but told us nothing
70
+ usable, so the caller cannot continue the flow — surface that as a ``ValueError``
71
+ rather than returning a half-built result.
72
+ """
73
+ data = body.get("data")
74
+ identifier = data.get("id") if isinstance(data, Mapping) else None
75
+ if not isinstance(identifier, str) or not identifier:
76
+ raise ValueError(f"server returned no {subject} id: {body!r}")
77
+ return identifier
78
+
79
+
80
+ class _AnnotationWorkflowsEndpoint(BaseDelegateClient):
81
+ """The annotation workflows, which hang off their own API root.
82
+
83
+ Module-private for the same reason as :class:`_AnnotationSpecsEndpoint`: it keeps
84
+ the workflows on the shared request plumbing without exposing a second delegate
85
+ for what is one capability from the caller's point of view.
86
+ """
87
+
88
+ api_path = WORKFLOWS_PATH
89
+
90
+
91
+ class _AnnotationSpecsEndpoint(BaseDelegateClient):
92
+ """The job specifications, which hang off their own API root.
93
+
94
+ Module-private: the specs are part of the annotations surface and are reached
95
+ through :class:`AgencyAnnotationsClient`. Modelling them as a sibling delegate
96
+ keeps them on the shared request plumbing (bearer, timeout, read retries)
97
+ instead of hand-rolling a second one for a different path prefix.
98
+ """
99
+
100
+ api_path = SPECS_PATH
101
+
102
+
103
+ class AgencyAnnotationsClient(BaseDelegateClient):
104
+ api_path = "/api/annotations"
105
+
106
+ def __init__(self, token_supplier: CredentialsSupplier, base_url: str = "http://localhost:9003"):
107
+ super().__init__(token_supplier=token_supplier, base_url=base_url)
108
+ self._specs = _AnnotationSpecsEndpoint(token_supplier=token_supplier, base_url=base_url)
109
+ self._workflows = _AnnotationWorkflowsEndpoint(token_supplier=token_supplier, base_url=base_url)
110
+
111
+ def create_batch(
112
+ self,
113
+ organisation_id: int,
114
+ *,
115
+ name: str,
116
+ description: str | None = None,
117
+ instructions: str | None = None,
118
+ batch_type: str = BATCH_TYPE_GRAPH,
119
+ confidentiality_level: str | None = None,
120
+ ) -> CreateBatchResult:
121
+ """Create an annotation batch. It starts in ``DRAFT`` with no jobs.
122
+
123
+ Jobs are materialised by :meth:`upload_graph`, which also flips the batch to
124
+ ``ACTIVE`` — a batch on its own is an empty container.
125
+
126
+ Args:
127
+ organisation_id: The organisation ID.
128
+ name: Batch name, as shown to annotators.
129
+ description: Optional free-text description.
130
+ instructions: Optional annotation instructions, shown in the screen's
131
+ title bar.
132
+ batch_type: ``"graph"`` (default, the rule-annotation path) or
133
+ ``"dataset"``.
134
+ confidentiality_level: ``"INTERNAL"`` (server default) or
135
+ ``"RESTRICTED"``, which gates the batch behind explicit membership
136
+ and seeds the caller as its first admin. Unknown levels are
137
+ rejected server-side with a 400.
138
+
139
+ Raises:
140
+ ValueError: If the server's command envelope carries no batch id.
141
+ """
142
+ payload: dict[str, Any] = {"name": name, "batch_type": batch_type}
143
+ if description is not None:
144
+ payload["description"] = description
145
+ if instructions is not None:
146
+ payload["instructions"] = instructions
147
+ if confidentiality_level is not None:
148
+ payload["confidentiality_level"] = confidentiality_level
149
+ body = self._make_request(
150
+ "POST", "/_command", data={"command": "create", "organisation": organisation_id, "payload": payload}
151
+ )
152
+ return CreateBatchResult(success=body["success"], message=body["message"], id=_command_id(body, "batch"))
153
+
154
+ def upload_graph(
155
+ self,
156
+ organisation_id: int,
157
+ batch_id: str,
158
+ *,
159
+ graph: Mapping[str, Any] | None = None,
160
+ file_path: str | Path | None = None,
161
+ job_type: str | None = None,
162
+ target_class: str | None = None,
163
+ hops: int | None = None,
164
+ filename: str | None = None,
165
+ ) -> None:
166
+ """Upload a graph to a DRAFT batch, materialising one job per target vertex.
167
+
168
+ The server creates a job for every vertex whose ``class`` equals
169
+ ``target_class``, attaches each one's ``hops``-hop undirected neighbourhood
170
+ as context, seeds its checklist from the specification whose ``code`` matches
171
+ ``job_type`` (empty when there is none — see :meth:`create_spec`), stores the
172
+ raw file, and flips the batch to ``ACTIVE`` with ``total_jobs`` set.
173
+
174
+ The graph is the same ``{run_id, vertices, edges}`` payload agents send to
175
+ the ontology sandbox, so a sandbox graph can be pushed unchanged.
176
+
177
+ Nothing is returned: the endpoint's response body is ``null``. Read the job
178
+ count back with :meth:`get_batch` (or use :meth:`push_graph`, which does).
179
+
180
+ Memory: ``requests`` assembles the whole multipart body in memory, and the
181
+ server caps the request body at 50 MiB.
182
+
183
+ Transport: this posts directly rather than through :meth:`_request`, whose
184
+ JSON content type would corrupt a multipart body. No retry behaviour is lost
185
+ by doing so — the base client only auto-retries reads, so a ``POST`` gets a
186
+ single attempt either way. That is the right policy here: a connection reset
187
+ can arrive *after* the server committed the upload, and re-sending would meet
188
+ the now-ACTIVE batch with a 400 rather than land twice.
189
+
190
+ Args:
191
+ organisation_id: The organisation ID.
192
+ batch_id: The DRAFT batch to fill.
193
+ graph: The graph as a mapping. Mutually exclusive with ``file_path``.
194
+ file_path: A local ``.json`` graph file. Mutually exclusive with ``graph``.
195
+ job_type: Job type to create (server default ``"rule_validation"``).
196
+ target_class: Vertex class to turn into jobs (server default ``"rule"``).
197
+ hops: Neighbourhood hops attached as context (server default ``1``).
198
+ filename: Multipart filename. Defaults to the source file's name, or
199
+ ``"graph.json"`` for an in-memory graph.
200
+
201
+ Raises:
202
+ ValueError: If not exactly one of ``graph`` / ``file_path`` is given;
203
+ raised before any network call.
204
+ requests.HTTPError: 400 if the batch is not in DRAFT, the JSON does not
205
+ parse, ``vertices`` is missing, or no vertex matches ``target_class``.
206
+ """
207
+ if (graph is None) == (file_path is None):
208
+ raise ValueError("pass exactly one of graph or file_path")
209
+ if graph is not None:
210
+ body = json.dumps(graph).encode()
211
+ upload_name = filename or "graph.json"
212
+ else:
213
+ source = Path(file_path) # type: ignore[arg-type] # exactly-one check above
214
+ body = source.read_bytes()
215
+ upload_name = filename or source.name
216
+ params = {"o": str(organisation_id)}
217
+ if job_type is not None:
218
+ params["job_type"] = job_type
219
+ if target_class is not None:
220
+ params["target_class"] = target_class
221
+ if hops is not None:
222
+ params["hops"] = str(hops)
223
+ response = requests.post(
224
+ f"{self.base_url}{self.api_path}/{batch_id}/upload",
225
+ headers={"Authorization": f"Bearer {self.token_supplier.bearer_token()}"},
226
+ params=params,
227
+ files={"file": (upload_name, body, "application/json")},
228
+ timeout=UPLOAD_TIMEOUT_SECONDS,
229
+ )
230
+ response.raise_for_status()
231
+
232
+ def list_workflows(self, organisation_id: int, *, page: int = 0, size: int = 50) -> AnnotationWorkflowsPagedResult:
233
+ """List the workflows an organisation can bind to a batch (paged).
234
+
235
+ Used to resolve a workflow id rather than hardcode one: the system workflows
236
+ are seeded **per organisation**, so ``sys-wf-graph-2`` is org 2's id and
237
+ nobody else's.
238
+ """
239
+ params = {"o": str(organisation_id), "p": str(page), "s": str(size)}
240
+ return AnnotationWorkflowsPagedResult(**self._workflows._make_request("GET", "", params=params))
241
+
242
+ def bind_workflow(
243
+ self,
244
+ organisation_id: int,
245
+ batch_id: str,
246
+ *,
247
+ workflow_id: str,
248
+ job_type: str = WILDCARD_JOB_TYPE,
249
+ rebind_reason: str | None = None,
250
+ ) -> BindWorkflowResult:
251
+ """Bind a workflow to a batch, without which the batch can hold no jobs.
252
+
253
+ A batch is created with **no** binding, and the server's insert trigger
254
+ resolves every job's governing workflow from the batch's bindings —
255
+ ``(batch_id, job_type)`` first, then ``(batch_id, "*")`` — refusing the insert
256
+ when neither exists. So this must run between :meth:`create_batch` and
257
+ :meth:`upload_graph`; :meth:`push_graph` does it for you.
258
+
259
+ Binding is a deliberate, separately-permissioned step (the server gates it on
260
+ workflow-execute rather than batch admin) because which workflow governs a
261
+ batch is a policy choice — an organisation can have several per batch type.
262
+
263
+ Args:
264
+ organisation_id: The organisation ID.
265
+ batch_id: The batch to bind.
266
+ workflow_id: The workflow, e.g. from :meth:`list_workflows`. The server
267
+ resolves it to its **published** version, so an unpublished workflow
268
+ cannot be bound.
269
+ job_type: The job type this binding governs; ``"*"`` (default) makes it
270
+ the batch default covering every type.
271
+ rebind_reason: Required by the server when re-binding a job type that
272
+ already has accepted work, or when the incoming version disables
273
+ separation of duties.
274
+ """
275
+ payload: dict[str, Any] = {"job_type": job_type, "workflow_id": workflow_id}
276
+ if rebind_reason is not None:
277
+ payload["rebind_reason"] = rebind_reason
278
+ body = self._make_request(
279
+ "POST",
280
+ f"/{batch_id}/_command",
281
+ data={"command": "bind_workflow", "organisation": organisation_id, "payload": payload},
282
+ )
283
+ data = body.get("data") or {}
284
+ return BindWorkflowResult(
285
+ success=body["success"],
286
+ message=body["message"],
287
+ workflow_version_id=data.get("workflow_version_id", ""),
288
+ jobs_regoverned=data.get("jobs_regoverned", 0),
289
+ )
290
+
291
+ def _resolve_workflow_id(self, organisation_id: int, batch_type: str) -> str | None:
292
+ """Pick a bindable workflow for ``batch_type``, or ``None`` on a pre-workflow server.
293
+
294
+ Bindable means: governs this batch type, and has a published version — the
295
+ bind resolves the published version server-side, so a draft-only workflow
296
+ cannot be used. System workflows win, since those are the seeded defaults;
297
+ beyond that the server's order decides. Ambiguity is deliberately not an
298
+ error: an organisation with two graph workflows would otherwise be unable to
299
+ push at all, and such a caller can pass ``workflow_id`` explicitly.
300
+
301
+ A ``404`` means a control plane older than the workflow model, where no
302
+ binding exists or is needed; that returns ``None`` so the caller skips the
303
+ bind. Every other error propagates.
304
+ """
305
+ try:
306
+ page = self.list_workflows(organisation_id, size=100)
307
+ except requests.HTTPError as error:
308
+ if error.response is not None and error.response.status_code == 404:
309
+ return None
310
+ raise
311
+ bindable = [
312
+ workflow
313
+ for workflow in page.items
314
+ if workflow.target_batch_type == batch_type and workflow.current_published_version_id
315
+ ]
316
+ if not bindable:
317
+ offered = ", ".join(f"{w.code}({w.target_batch_type})" for w in page.items) or "none"
318
+ raise ValueError(
319
+ f"no bindable annotation workflow for batch_type {batch_type!r} in organisation "
320
+ f"{organisation_id}: a batch cannot hold jobs until a workflow is bound to it. "
321
+ f"Workflows offered: {offered}. Publish one, or pass workflow_id explicitly."
322
+ )
323
+ return sorted(bindable, key=lambda w: not w.is_system)[0].id
324
+
325
+ def push_graph(
326
+ self,
327
+ organisation_id: int,
328
+ *,
329
+ name: str,
330
+ graph: Mapping[str, Any] | None = None,
331
+ file_path: str | Path | None = None,
332
+ description: str | None = None,
333
+ instructions: str | None = None,
334
+ confidentiality_level: str | None = None,
335
+ job_type: str | None = None,
336
+ target_class: str | None = None,
337
+ hops: int | None = None,
338
+ filename: str | None = None,
339
+ workflow_id: str | None = None,
340
+ rebind_reason: str | None = None,
341
+ ) -> PushGraphResult:
342
+ """Publish a graph as annotation jobs: create → bind → upload → read back.
343
+
344
+ The whole flow an agent needs at the end of its pipeline. Arguments are the
345
+ union of :meth:`create_batch`'s and :meth:`upload_graph`'s; the returned
346
+ ``total_jobs`` and ``status`` come from the read-back, so they are what the
347
+ annotators will actually see.
348
+
349
+ The **bind** leg is not optional: a batch is created with no workflow, and the
350
+ server refuses to insert a job into an unbound batch — which surfaces as an
351
+ opaque 500 from the upload. By default the workflow is resolved from
352
+ :meth:`list_workflows` (published, matching the batch type, system first),
353
+ never hardcoded, since the seeded ids differ per organisation. Pass
354
+ ``workflow_id`` to choose one yourself and skip the lookup; against a control
355
+ plane predating workflows the lookup 404s and the bind is skipped.
356
+
357
+ The graph source is validated before the batch is created, so a malformed
358
+ call cannot leave anything behind. An upload that the server rejects (no
359
+ matching vertices, oversized body, …) is a different matter: the batch has
360
+ already been created, so the ``HTTPError`` propagates and an **empty DRAFT
361
+ batch stays server-side**. It holds no jobs and is findable via
362
+ :meth:`list_batches`; the SDK does not archive it on the caller's behalf.
363
+
364
+ Raises:
365
+ ValueError: If not exactly one of ``graph`` / ``file_path`` is given, or
366
+ if the create response carries no batch id.
367
+ requests.HTTPError: From any of the three legs.
368
+ """
369
+ if (graph is None) == (file_path is None):
370
+ raise ValueError("pass exactly one of graph or file_path")
371
+ # Resolve BEFORE creating anything: a batch with no bindable workflow is a
372
+ # batch that can never hold jobs, and failing after create_batch would strand
373
+ # exactly the empty DRAFT batch this method is trying not to leave behind.
374
+ resolved_workflow_id = workflow_id or self._resolve_workflow_id(organisation_id, BATCH_TYPE_GRAPH)
375
+ created = self.create_batch(
376
+ organisation_id,
377
+ name=name,
378
+ description=description,
379
+ instructions=instructions,
380
+ confidentiality_level=confidentiality_level,
381
+ )
382
+ if resolved_workflow_id is not None:
383
+ self.bind_workflow(
384
+ organisation_id,
385
+ created.id,
386
+ workflow_id=resolved_workflow_id,
387
+ rebind_reason=rebind_reason,
388
+ )
389
+ self.upload_graph(
390
+ organisation_id,
391
+ created.id,
392
+ graph=graph,
393
+ file_path=file_path,
394
+ job_type=job_type,
395
+ target_class=target_class,
396
+ hops=hops,
397
+ filename=filename,
398
+ )
399
+ batch = self.get_batch(organisation_id, created.id)
400
+ return PushGraphResult(batch_id=created.id, total_jobs=batch.total_jobs, status=batch.status, batch=batch)
401
+
402
+ def get_batch(self, organisation_id: int, batch_id: str) -> AnnotationBatchResponse:
403
+ """Read one batch, including the caller's ``viewer_role`` on it.
404
+
405
+ This is how the job count is obtained: a batch stays ``DRAFT`` with
406
+ ``total_jobs = 0`` until a graph is uploaded, after which it is ``ACTIVE``
407
+ with ``total_jobs`` set and the graph subtype fields hydrated. ``status`` is
408
+ an int — compare it against
409
+ :class:`~agency_sdk.delegates.annotations_dto.BatchStatus`.
410
+ """
411
+ params = {"o": str(organisation_id)}
412
+ return AnnotationBatchResponse(**self._make_request("GET", f"/{batch_id}", params=params))
413
+
414
+ def list_batches(
415
+ self,
416
+ organisation_id: int,
417
+ *,
418
+ page: int = 0,
419
+ size: int = 50,
420
+ batch_type: str | None = None,
421
+ view: str | None = None,
422
+ ) -> AnnotationBatchesPagedResult:
423
+ """List the org's batches (paged), e.g. to resolve a batch NAME → id.
424
+
425
+ Unlike :meth:`get_batch`, the items carry no ``viewer_role``. Name matching
426
+ is the caller's job; this returns the raw page.
427
+
428
+ Args:
429
+ organisation_id: The organisation ID.
430
+ page: Zero-indexed page number.
431
+ size: Page size (the server's own default is 10).
432
+ batch_type: Optional ``"graph"`` / ``"dataset"`` filter.
433
+ view: Optional server-side view filter.
434
+ """
435
+ params = {"o": str(organisation_id), "p": str(page), "s": str(size)}
436
+ if batch_type is not None:
437
+ params["batch_type"] = batch_type
438
+ if view is not None:
439
+ params["view"] = view
440
+ return AnnotationBatchesPagedResult(**self._make_request("GET", "", params=params))
441
+
442
+ def create_spec(
443
+ self,
444
+ organisation_id: int,
445
+ *,
446
+ code: str,
447
+ name: str,
448
+ checklist: Any,
449
+ instructions: str | None = None,
450
+ ) -> CreateSpecResult:
451
+ """Create a job specification — the checklist a job type's jobs start from.
452
+
453
+ On upload the server seeds each job's ``checklist_state`` with
454
+ ``{item_id: false}`` for every checklist item of the spec whose ``code``
455
+ equals the upload's ``job_type``. Seed the spec **before** pushing a graph;
456
+ without one the upload still succeeds and the jobs reach annotators with an
457
+ empty checklist. The spec is created ``ACTIVE``.
458
+
459
+ Nothing enforces ``code`` uniqueness per organisation and the lookup takes
460
+ the first match, so check with :meth:`get_spec` before creating.
461
+
462
+ Args:
463
+ organisation_id: The organisation ID.
464
+ code: The job type this spec applies to (e.g. ``"rule_validation"``).
465
+ name: Human-readable specification name.
466
+ checklist: The checklist, a JSON array whose items each carry an ``id``.
467
+ instructions: Optional instructions shown to the annotator.
468
+
469
+ Raises:
470
+ ValueError: If the server's command envelope carries no specification id.
471
+ """
472
+ payload: dict[str, Any] = {"code": code, "name": name, "checklist": checklist}
473
+ if instructions is not None:
474
+ payload["instructions"] = instructions
475
+ body = self._specs._make_request(
476
+ "POST", "/_command", data={"command": "create", "organisation": organisation_id, "payload": payload}
477
+ )
478
+ return CreateSpecResult(success=body["success"], message=body["message"], id=_command_id(body, "specification"))
479
+
480
+ def get_spec(self, organisation_id: int, code: str) -> AnnotationSpec:
481
+ """Read one job specification **by its code**.
482
+
483
+ Note the path segment is the spec's ``code`` (e.g. ``"rule_validation"``),
484
+ not its UUID, even though the server's own route names it ``{id}`` — it is
485
+ resolved with a by-code lookup.
486
+
487
+ Raises:
488
+ requests.HTTPError: 404 when the organisation has no spec with that code.
489
+ """
490
+ return AnnotationSpec(**self._specs._make_request("GET", f"/{code}", params={"o": str(organisation_id)}))
491
+
492
+ def list_specs(self, organisation_id: int, *, page: int = 0, size: int = 50) -> AnnotationSpecsPagedResult:
493
+ """List the org's job specifications (paged; the server's own default size is 10)."""
494
+ params = {"o": str(organisation_id), "p": str(page), "s": str(size)}
495
+ return AnnotationSpecsPagedResult(**self._specs._make_request("GET", "", params=params))
@@ -0,0 +1,200 @@
1
+ """DTOs for the annotations API (snake_case, matching the API).
2
+
3
+ Mirrors the gts-comand annotation models (`crates/comand/src/model/annotation.rs`,
4
+ `service/annotation_service.rs`, verified at `8d64a64a`):
5
+
6
+ - A **batch** is the container annotators work through. It is created in ``DRAFT``
7
+ with ``total_jobs = 0``; uploading a graph materialises one job per matching
8
+ vertex and flips it to ``ACTIVE``.
9
+ - The server serialises every field, so nulls arrive explicitly rather than being
10
+ omitted — each optional field therefore defaults to ``None`` and tolerates both.
11
+ - ``AnnotationBatchResponse`` is the single-batch read: the server flattens the
12
+ batch's own fields alongside ``viewer_role``, so this model extends
13
+ :class:`AnnotationBatch` rather than nesting it. The **list** read returns plain
14
+ batches (no ``viewer_role``).
15
+ - ``CreateBatchResult`` / ``CreateSpecResult`` wrap the platform's standard command
16
+ envelope ``{success, message, data}`` with ``data.id`` lifted to ``id`` — the
17
+ ``_command`` endpoints do **not** return a bare ``{"id": ...}``.
18
+ """
19
+
20
+ from enum import IntEnum
21
+ from typing import Any
22
+
23
+ from pydantic import BaseModel
24
+
25
+ from agency_sdk.delegates.datasets_dto import Page
26
+
27
+ #: Batch types the server accepts. Graph batches are the rule-annotation path.
28
+ BATCH_TYPE_GRAPH = "graph"
29
+ BATCH_TYPE_DATASET = "dataset"
30
+
31
+ #: Server-side defaults for the graph upload's query parameters. The SDK omits
32
+ #: these params when the caller leaves them unset, so the server stays the single
33
+ #: source of truth; they are exposed for documentation and for callers that want
34
+ #: to be explicit.
35
+ DEFAULT_JOB_TYPE = "rule_validation"
36
+ DEFAULT_TARGET_CLASS = "rule"
37
+ DEFAULT_CONTEXT_HOPS = 1
38
+
39
+ #: Confidentiality levels a batch may carry. ``RESTRICTED`` gates the batch behind
40
+ #: explicit membership (the creator is seeded as its first admin).
41
+ LEVEL_INTERNAL = "INTERNAL"
42
+ LEVEL_RESTRICTED = "RESTRICTED"
43
+
44
+
45
+ class BatchStatus(IntEnum):
46
+ """Lifecycle of an annotation batch (server ``BATCH_STATUS_*`` constants)."""
47
+
48
+ DRAFT = 0
49
+ ACTIVE = 1
50
+ COMPLETED = 2
51
+ ARCHIVED = 3
52
+
53
+
54
+ class SpecStatus(IntEnum):
55
+ """Lifecycle of a job specification (server ``SPEC_STATUS_*`` constants)."""
56
+
57
+ DRAFT = 0
58
+ ACTIVE = 1
59
+ ARCHIVED = 2
60
+
61
+
62
+ class AnnotationBatch(BaseModel):
63
+ """An annotation batch as returned by the annotations API.
64
+
65
+ ``graph_uri`` / ``graph_run_id`` / ``target_class`` / ``context_hops`` are the
66
+ graph subtype's fields: they are hydrated by a join and stay ``None`` until a
67
+ graph has been uploaded (and for dataset batches, always).
68
+ """
69
+
70
+ id: str
71
+ organisation_id: int
72
+ name: str
73
+ description: str | None = None
74
+ instructions: str | None = None
75
+ batch_type: str
76
+ graph_uri: str | None = None
77
+ graph_run_id: str | None = None
78
+ target_class: str | None = None
79
+ context_hops: int | None = None
80
+ total_jobs: int
81
+ # Job counters differ by server generation, so all four are optional and one
82
+ # model parses both. Older control planes send a single ``completed_jobs``;
83
+ # gts-comand replaced it with the three below, because "done" and "done well"
84
+ # are different questions that the one counter conflated.
85
+ completed_jobs: int | None = None
86
+ resolved_jobs: int | None = None
87
+ accepted_jobs: int | None = None
88
+ rejected_jobs: int | None = None
89
+ status: int
90
+ confidentiality_level: str
91
+ audit_data: dict[str, Any] | None = None
92
+
93
+
94
+ class AnnotationBatchResponse(AnnotationBatch):
95
+ """A single batch read, augmented with the caller's role on it.
96
+
97
+ ``viewer_role`` is ``None`` for non-members, ``"admin"`` / ``"member"`` for an
98
+ active membership.
99
+ """
100
+
101
+ viewer_role: str | None = None
102
+
103
+
104
+ class AnnotationBatchesPagedResult(BaseModel):
105
+ page: Page
106
+ items: list[AnnotationBatch]
107
+
108
+
109
+ class CommandResult(BaseModel):
110
+ """The standard ``{success, message, data}`` envelope with ``data.id`` lifted."""
111
+
112
+ success: bool
113
+ message: str
114
+ id: str
115
+
116
+
117
+ class CreateBatchResult(CommandResult):
118
+ """Outcome of ``create_batch``: the new batch's id (batch starts in ``DRAFT``)."""
119
+
120
+
121
+ class CreateSpecResult(CommandResult):
122
+ """Outcome of ``create_spec``: the new specification's id (created ``ACTIVE``)."""
123
+
124
+
125
+ class AnnotationSpec(BaseModel):
126
+ """A job specification: the checklist a job type's jobs are seeded from.
127
+
128
+ On upload the server looks the spec up by ``code`` == the upload's ``job_type``
129
+ and seeds each job's ``checklist_state`` with ``{item_id: false}`` per checklist
130
+ item. Without a matching spec the upload still succeeds and jobs get an empty
131
+ checklist.
132
+ """
133
+
134
+ id: str
135
+ organisation_id: int
136
+ code: str
137
+ name: str
138
+ instructions: str | None = None
139
+ checklist: Any = None
140
+ status: int
141
+ audit_data: dict[str, Any] | None = None
142
+
143
+
144
+ class AnnotationSpecsPagedResult(BaseModel):
145
+ page: Page
146
+ items: list[AnnotationSpec]
147
+
148
+
149
+ class AnnotationWorkflow(BaseModel):
150
+ """A workflow an organisation can bind to a batch, as listed by the API.
151
+
152
+ A batch cannot receive jobs until a workflow is bound to it, so publishing
153
+ starts by resolving one of these. ``target_batch_type`` says which batch type
154
+ it governs (``"graph"`` / ``"dataset"``), and only a workflow with a
155
+ ``current_published_version_id`` can be bound — the bind resolves the
156
+ *published* version server-side.
157
+ """
158
+
159
+ id: str
160
+ code: str
161
+ name: str
162
+ description: str | None = None
163
+ target_batch_type: str
164
+ is_system: bool
165
+ status: str
166
+ current_published_version_id: str | None = None
167
+ draft_version_id: str | None = None
168
+
169
+
170
+ class AnnotationWorkflowsPagedResult(BaseModel):
171
+ page: Page
172
+ items: list[AnnotationWorkflow]
173
+
174
+
175
+ class BindWorkflowResult(BaseModel):
176
+ """Outcome of binding a workflow to a batch.
177
+
178
+ ``jobs_regoverned`` is 0 for a batch that has no jobs yet — the normal case when
179
+ binding right after ``create_batch`` — and non-zero when re-binding a batch whose
180
+ jobs move to the new workflow.
181
+ """
182
+
183
+ success: bool
184
+ message: str
185
+ workflow_version_id: str
186
+ jobs_regoverned: int
187
+
188
+
189
+ class PushGraphResult(BaseModel):
190
+ """Outcome of the create → upload → read-back push.
191
+
192
+ ``total_jobs`` and ``status`` are read back from the server (the upload
193
+ endpoint's own response body is ``null``), so they reflect what the annotators
194
+ will actually see.
195
+ """
196
+
197
+ batch_id: str
198
+ total_jobs: int
199
+ status: int
200
+ batch: AnnotationBatchResponse