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.
- agency_sdk/__init__.py +0 -0
- agency_sdk/auth_hooks.py +55 -0
- agency_sdk/client.py +212 -0
- agency_sdk/credentials.py +54 -0
- agency_sdk/delegates/__init__.py +0 -0
- agency_sdk/delegates/annotations_client.py +495 -0
- agency_sdk/delegates/annotations_dto.py +200 -0
- agency_sdk/delegates/base_client.py +126 -0
- agency_sdk/delegates/datasets_client.py +109 -0
- agency_sdk/delegates/datasets_dto.py +81 -0
- agency_sdk/delegates/datasource_client.py +44 -0
- agency_sdk/delegates/datasource_dto.py +107 -0
- agency_sdk/delegates/files_client.py +184 -0
- agency_sdk/delegates/files_dto.py +36 -0
- agency_sdk/delegates/gateway_client.py +81 -0
- agency_sdk/delegates/gateway_dto.py +37 -0
- agency_sdk/delegates/ontology_client.py +203 -0
- agency_sdk/delegates/ontology_dto.py +221 -0
- agency_sdk/delegates/prompts_client.py +56 -0
- agency_sdk/delegates/rules_client.py +33 -0
- agency_sdk/delegates/rules_dto.py +108 -0
- agency_sdk/delegates/session_client.py +95 -0
- agency_sdk/delegates/session_dto.py +94 -0
- agency_sdk/delegates/session_templates_client.py +23 -0
- agency_sdk/delegates/session_templates_dto.py +27 -0
- agency_sdk/delegates/session_vault_client.py +135 -0
- agency_sdk/delegates/session_vault_dto.py +75 -0
- agency_sdk/delegates/work_queue_client.py +230 -0
- agency_sdk/delegates/work_queue_dto.py +127 -0
- agency_sdk/domain.py +140 -0
- agency_sdk/observability/__init__.py +60 -0
- agency_sdk/observability/auth.py +15 -0
- agency_sdk/observability/bootstrap.py +344 -0
- agency_sdk/test/__init__.py +0 -0
- agency_sdk/test/conftest.py +106 -0
- agency_sdk/test/test_annotations_client.py +599 -0
- agency_sdk/test/test_annotations_dto.py +299 -0
- agency_sdk/test/test_base_client.py +153 -0
- agency_sdk/test/test_client_facade.py +105 -0
- agency_sdk/test/test_credentials.py +67 -0
- agency_sdk/test/test_files_client.py +264 -0
- agency_sdk/test/test_files_dto.py +93 -0
- agency_sdk/test/test_gateway_dto.py +70 -0
- agency_sdk/test/test_gateway_facade.py +229 -0
- agency_sdk/test/test_gateway_openai.py +76 -0
- agency_sdk/test/test_observability_auth.py +125 -0
- agency_sdk/test/test_observability_facade_threadsafety.py +50 -0
- agency_sdk/test/test_observability_langfuse.py +76 -0
- agency_sdk/test/test_observability_packaging.py +78 -0
- agency_sdk/test/test_observability_pipeline.py +246 -0
- agency_sdk/test/test_ontology_client.py +152 -0
- agency_sdk/test/test_ontology_dto.py +158 -0
- agency_sdk/test/test_session_client.py +128 -0
- agency_sdk/test/test_session_dto.py +75 -0
- agency_sdk/test/test_session_templates_client.py +36 -0
- agency_sdk/test/test_session_templates_dto.py +45 -0
- agency_sdk/test/test_session_vault_client.py +151 -0
- agency_sdk/test/test_session_vault_dto.py +27 -0
- agency_sdk/test/test_stub_requests.py +39 -0
- agency_sdk/test/test_work_queue_client.py +388 -0
- agency_sdk/test/test_work_queue_dto.py +233 -0
- gts_agency_python_sdk-0.0.1.dist-info/METADATA +221 -0
- gts_agency_python_sdk-0.0.1.dist-info/RECORD +66 -0
- gts_agency_python_sdk-0.0.1.dist-info/WHEEL +5 -0
- gts_agency_python_sdk-0.0.1.dist-info/licenses/LICENSE +201 -0
- 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
|