gts-agency-python-sdk 0.0.1rc14__tar.gz → 0.0.1rc15__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.
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/PKG-INFO +2 -2
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/README.md +1 -1
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/annotations_client.py +158 -13
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/annotations_dto.py +48 -1
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_annotations_client.py +224 -16
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_annotations_dto.py +96 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/gts_agency_python_sdk.egg-info/PKG-INFO +2 -2
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/pyproject.toml +1 -1
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/LICENSE +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/auth_hooks.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/credentials.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/base_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/datasets_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/datasets_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/datasource_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/datasource_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/files_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/files_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/gateway_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/gateway_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/ontology_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/ontology_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/prompts_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/rules_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/rules_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_templates_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_templates_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_vault_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_vault_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/work_queue_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/work_queue_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/domain.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/observability/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/observability/auth.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/observability/bootstrap.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/conftest.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_base_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_client_facade.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_credentials.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_files_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_files_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_gateway_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_gateway_facade.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_gateway_openai.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_observability_auth.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_observability_facade_threadsafety.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_observability_langfuse.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_observability_packaging.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_observability_pipeline.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_templates_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_templates_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_vault_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_vault_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_stub_requests.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_work_queue_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_work_queue_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/gts_agency_python_sdk.egg-info/SOURCES.txt +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/gts_agency_python_sdk.egg-info/dependency_links.txt +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/gts_agency_python_sdk.egg-info/requires.txt +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/gts_agency_python_sdk.egg-info/top_level.txt +0 -0
- {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/setup.cfg +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: gts-agency_python-sdk
|
|
3
|
-
Version: 0.0.
|
|
3
|
+
Version: 0.0.1rc15
|
|
4
4
|
Author-email: Ground Control Systems <engineering@groundcontrolsystems.com>
|
|
5
5
|
Requires-Python: >=3.12
|
|
6
6
|
Description-Content-Type: text/markdown
|
|
@@ -81,7 +81,7 @@ Access each API domain through the facade:
|
|
|
81
81
|
- `client.work_queues()` — work-queue ingestion: create items with exactly-once external refs, publish, claim by ref, queue-scoped owner lookup (`get_items_by_ref`), unblock/retry/reprocess, delete, and `list()` to resolve a queue name→id (409 returns a typed claim-lost result from the error envelope's `error.details`, plus a `contended` flag — not an exception)
|
|
82
82
|
- `client.sessions()` — report progress on a dispatched control-plane session: `attach` to the inherited session then `update` its status/result/events/metrics (the agent inherits the session, never self-registers — no `register`)
|
|
83
83
|
- `client.session_templates()` — list session templates to resolve a template name → id (read-only)
|
|
84
|
-
- `client.annotations()` — publish a knowledge graph as annotator work: `push_graph()` does create-batch → multipart upload → read-back in one call (one job per `class: "rule"` vertex), plus the individual legs, batch reads, and the job specifications that seed each job's checklist ([docs/annotations.md](docs/annotations.md))
|
|
84
|
+
- `client.annotations()` — publish a knowledge graph as annotator work: `push_graph()` does resolve-workflow → create-batch → bind-workflow → multipart upload → read-back in one call (one job per `class: "rule"` vertex), plus the individual legs, `bind_workflow`/`list_workflows` (a batch cannot hold jobs until a workflow is bound to it), batch reads, and the job specifications that seed each job's checklist ([docs/annotations.md](docs/annotations.md))
|
|
85
85
|
- `client.gateway(org_id=..., gateway_base_url=...)` — OpenAI-compatible LLM calls routed through the org's agentgateway (shared credentials + `x-org` routing header)
|
|
86
86
|
|
|
87
87
|
### Rules Example
|
|
@@ -57,7 +57,7 @@ Access each API domain through the facade:
|
|
|
57
57
|
- `client.work_queues()` — work-queue ingestion: create items with exactly-once external refs, publish, claim by ref, queue-scoped owner lookup (`get_items_by_ref`), unblock/retry/reprocess, delete, and `list()` to resolve a queue name→id (409 returns a typed claim-lost result from the error envelope's `error.details`, plus a `contended` flag — not an exception)
|
|
58
58
|
- `client.sessions()` — report progress on a dispatched control-plane session: `attach` to the inherited session then `update` its status/result/events/metrics (the agent inherits the session, never self-registers — no `register`)
|
|
59
59
|
- `client.session_templates()` — list session templates to resolve a template name → id (read-only)
|
|
60
|
-
- `client.annotations()` — publish a knowledge graph as annotator work: `push_graph()` does create-batch → multipart upload → read-back in one call (one job per `class: "rule"` vertex), plus the individual legs, batch reads, and the job specifications that seed each job's checklist ([docs/annotations.md](docs/annotations.md))
|
|
60
|
+
- `client.annotations()` — publish a knowledge graph as annotator work: `push_graph()` does resolve-workflow → create-batch → bind-workflow → multipart upload → read-back in one call (one job per `class: "rule"` vertex), plus the individual legs, `bind_workflow`/`list_workflows` (a batch cannot hold jobs until a workflow is bound to it), batch reads, and the job specifications that seed each job's checklist ([docs/annotations.md](docs/annotations.md))
|
|
61
61
|
- `client.gateway(org_id=..., gateway_base_url=...)` — OpenAI-compatible LLM calls routed through the org's agentgateway (shared credentials + `x-org` routing header)
|
|
62
62
|
|
|
63
63
|
### Rules Example
|
|
@@ -1,17 +1,25 @@
|
|
|
1
|
-
"""Client for the annotations API
|
|
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).
|
|
2
6
|
|
|
3
7
|
Publishes a knowledge graph as work for human annotators. There is no single
|
|
4
|
-
"publish" endpoint
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
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.
|
|
15
23
|
"""
|
|
16
24
|
|
|
17
25
|
from __future__ import annotations
|
|
@@ -30,6 +38,9 @@ from agency_sdk.delegates.annotations_dto import (
|
|
|
30
38
|
AnnotationBatchResponse,
|
|
31
39
|
AnnotationSpec,
|
|
32
40
|
AnnotationSpecsPagedResult,
|
|
41
|
+
AnnotationWorkflow,
|
|
42
|
+
AnnotationWorkflowsPagedResult,
|
|
43
|
+
BindWorkflowResult,
|
|
33
44
|
CreateBatchResult,
|
|
34
45
|
CreateSpecResult,
|
|
35
46
|
PushGraphResult,
|
|
@@ -39,6 +50,14 @@ from agency_sdk.delegates.base_client import BaseDelegateClient
|
|
|
39
50
|
#: The job specifications live under their own root, NOT under ``api_path``.
|
|
40
51
|
SPECS_PATH = "/api/annotation-specs"
|
|
41
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
|
+
|
|
42
61
|
#: Upload bodies are assembled in memory and the server caps the request body at
|
|
43
62
|
#: 50 MiB; a graph larger than this is rejected before it reaches the handler.
|
|
44
63
|
UPLOAD_TIMEOUT_SECONDS = 300
|
|
@@ -58,6 +77,17 @@ def _command_id(body: Mapping[str, Any], subject: str) -> str:
|
|
|
58
77
|
return identifier
|
|
59
78
|
|
|
60
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
|
+
|
|
61
91
|
class _AnnotationSpecsEndpoint(BaseDelegateClient):
|
|
62
92
|
"""The job specifications, which hang off their own API root.
|
|
63
93
|
|
|
@@ -76,6 +106,7 @@ class AgencyAnnotationsClient(BaseDelegateClient):
|
|
|
76
106
|
def __init__(self, token_supplier: CredentialsSupplier, base_url: str = "http://localhost:9003"):
|
|
77
107
|
super().__init__(token_supplier=token_supplier, base_url=base_url)
|
|
78
108
|
self._specs = _AnnotationSpecsEndpoint(token_supplier=token_supplier, base_url=base_url)
|
|
109
|
+
self._workflows = _AnnotationWorkflowsEndpoint(token_supplier=token_supplier, base_url=base_url)
|
|
79
110
|
|
|
80
111
|
def create_batch(
|
|
81
112
|
self,
|
|
@@ -198,6 +229,99 @@ class AgencyAnnotationsClient(BaseDelegateClient):
|
|
|
198
229
|
)
|
|
199
230
|
response.raise_for_status()
|
|
200
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
|
+
|
|
201
325
|
def push_graph(
|
|
202
326
|
self,
|
|
203
327
|
organisation_id: int,
|
|
@@ -212,14 +336,24 @@ class AgencyAnnotationsClient(BaseDelegateClient):
|
|
|
212
336
|
target_class: str | None = None,
|
|
213
337
|
hops: int | None = None,
|
|
214
338
|
filename: str | None = None,
|
|
339
|
+
workflow_id: str | None = None,
|
|
340
|
+
rebind_reason: str | None = None,
|
|
215
341
|
) -> PushGraphResult:
|
|
216
|
-
"""Publish a graph as annotation jobs
|
|
342
|
+
"""Publish a graph as annotation jobs: create → bind → upload → read back.
|
|
217
343
|
|
|
218
344
|
The whole flow an agent needs at the end of its pipeline. Arguments are the
|
|
219
345
|
union of :meth:`create_batch`'s and :meth:`upload_graph`'s; the returned
|
|
220
346
|
``total_jobs`` and ``status`` come from the read-back, so they are what the
|
|
221
347
|
annotators will actually see.
|
|
222
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
|
+
|
|
223
357
|
The graph source is validated before the batch is created, so a malformed
|
|
224
358
|
call cannot leave anything behind. An upload that the server rejects (no
|
|
225
359
|
matching vertices, oversized body, …) is a different matter: the batch has
|
|
@@ -234,6 +368,10 @@ class AgencyAnnotationsClient(BaseDelegateClient):
|
|
|
234
368
|
"""
|
|
235
369
|
if (graph is None) == (file_path is None):
|
|
236
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)
|
|
237
375
|
created = self.create_batch(
|
|
238
376
|
organisation_id,
|
|
239
377
|
name=name,
|
|
@@ -241,6 +379,13 @@ class AgencyAnnotationsClient(BaseDelegateClient):
|
|
|
241
379
|
instructions=instructions,
|
|
242
380
|
confidentiality_level=confidentiality_level,
|
|
243
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
|
+
)
|
|
244
389
|
self.upload_graph(
|
|
245
390
|
organisation_id,
|
|
246
391
|
created.id,
|
|
@@ -78,7 +78,14 @@ class AnnotationBatch(BaseModel):
|
|
|
78
78
|
target_class: str | None = None
|
|
79
79
|
context_hops: int | None = None
|
|
80
80
|
total_jobs: int
|
|
81
|
-
|
|
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
|
|
82
89
|
status: int
|
|
83
90
|
confidentiality_level: str
|
|
84
91
|
audit_data: dict[str, Any] | None = None
|
|
@@ -139,6 +146,46 @@ class AnnotationSpecsPagedResult(BaseModel):
|
|
|
139
146
|
items: list[AnnotationSpec]
|
|
140
147
|
|
|
141
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
|
+
|
|
142
189
|
class PushGraphResult(BaseModel):
|
|
143
190
|
"""Outcome of the create → upload → read-back push.
|
|
144
191
|
|
|
@@ -311,23 +311,23 @@ class TestSpecs:
|
|
|
311
311
|
|
|
312
312
|
|
|
313
313
|
class TestPushGraph:
|
|
314
|
+
"""The push legs other than workflow resolution, which TestPushGraphBindsAWorkflow owns.
|
|
315
|
+
|
|
316
|
+
These pass ``workflow_id`` so the workflow lookup is skipped and each test stays
|
|
317
|
+
about one thing.
|
|
318
|
+
"""
|
|
319
|
+
|
|
314
320
|
def _queue_happy_path(self, stub_requests):
|
|
315
321
|
stub_requests.queue(json_data=CREATED_ENVELOPE) # create
|
|
322
|
+
stub_requests.queue(json_data=BOUND_ENVELOPE) # bind
|
|
316
323
|
stub_requests.queue(json_data=None) # upload (null body)
|
|
317
324
|
stub_requests.queue(json_data=ACTIVE_BATCH_JSON) # read-back
|
|
318
325
|
|
|
319
|
-
def
|
|
326
|
+
def test_reports_the_read_back_batch(self, client, stub_requests):
|
|
320
327
|
self._queue_happy_path(stub_requests)
|
|
321
328
|
|
|
322
|
-
result = client.push_graph(organisation_id=2, name="MTUS Knee 2026", graph=GRAPH)
|
|
329
|
+
result = client.push_graph(organisation_id=2, name="MTUS Knee 2026", graph=GRAPH, workflow_id="w-1")
|
|
323
330
|
|
|
324
|
-
create, upload, read_back = stub_requests.calls
|
|
325
|
-
assert (create.method, create.url) == ("POST", "http://cp.test/api/annotations/_command")
|
|
326
|
-
assert upload.url == f"http://cp.test/api/annotations/{CREATED_ENVELOPE['data']['id']}/upload"
|
|
327
|
-
assert (read_back.method, read_back.url) == (
|
|
328
|
-
"GET",
|
|
329
|
-
f"http://cp.test/api/annotations/{CREATED_ENVELOPE['data']['id']}",
|
|
330
|
-
)
|
|
331
331
|
assert result.batch_id == CREATED_ENVELOPE["data"]["id"]
|
|
332
332
|
assert result.total_jobs == 325
|
|
333
333
|
assert result.status == BatchStatus.ACTIVE
|
|
@@ -346,9 +346,10 @@ class TestPushGraph:
|
|
|
346
346
|
job_type="rule_validation",
|
|
347
347
|
target_class="rule",
|
|
348
348
|
hops=2,
|
|
349
|
+
workflow_id="w-1",
|
|
349
350
|
)
|
|
350
351
|
|
|
351
|
-
create, upload,
|
|
352
|
+
create, _bind, upload, _read_back = stub_requests.calls
|
|
352
353
|
assert create.kwargs["json"]["payload"] == {
|
|
353
354
|
"name": "MTUS Knee 2026",
|
|
354
355
|
"batch_type": "graph",
|
|
@@ -368,9 +369,9 @@ class TestPushGraph:
|
|
|
368
369
|
graph_file.write_text(json.dumps(GRAPH))
|
|
369
370
|
self._queue_happy_path(stub_requests)
|
|
370
371
|
|
|
371
|
-
result = client.push_graph(organisation_id=2, name="MTUS Knee 2026", file_path=graph_file)
|
|
372
|
+
result = client.push_graph(organisation_id=2, name="MTUS Knee 2026", file_path=graph_file, workflow_id="w-1")
|
|
372
373
|
|
|
373
|
-
assert json.loads(stub_requests.calls[
|
|
374
|
+
assert json.loads(stub_requests.calls[2].kwargs["files"]["file"][1]) == GRAPH
|
|
374
375
|
assert result.total_jobs == 325
|
|
375
376
|
|
|
376
377
|
def test_validates_the_graph_source_before_creating_a_batch(self, client, stub_requests):
|
|
@@ -381,11 +382,218 @@ class TestPushGraph:
|
|
|
381
382
|
|
|
382
383
|
def test_a_failed_upload_propagates_and_leaves_the_draft_batch(self, client, stub_requests):
|
|
383
384
|
stub_requests.queue(json_data=CREATED_ENVELOPE)
|
|
385
|
+
stub_requests.queue(json_data=BOUND_ENVELOPE)
|
|
384
386
|
stub_requests.queue(json_data={"error": {"message": "No vertices of class 'rule' found"}}, status_code=400)
|
|
385
387
|
|
|
386
388
|
with pytest.raises(requests.HTTPError):
|
|
387
|
-
client.push_graph(organisation_id=2, name="MTUS Knee 2026", graph={"vertices": []})
|
|
389
|
+
client.push_graph(organisation_id=2, name="MTUS Knee 2026", graph={"vertices": []}, workflow_id="w-1")
|
|
390
|
+
|
|
391
|
+
# The batch was created and bound before the upload failed: three calls, no
|
|
392
|
+
# read-back, and the DRAFT batch survives server-side (documented residue,
|
|
393
|
+
# recoverable via list_batches).
|
|
394
|
+
assert len(stub_requests.calls) == 3
|
|
395
|
+
|
|
396
|
+
|
|
397
|
+
WORKFLOWS_PAGE = {
|
|
398
|
+
"page": {"page": 0, "size": 50, "total": 3},
|
|
399
|
+
"items": [
|
|
400
|
+
{
|
|
401
|
+
"id": "sys-wf-dataset-2",
|
|
402
|
+
"code": "dataset_single_step",
|
|
403
|
+
"name": "Dataset single step",
|
|
404
|
+
"description": None,
|
|
405
|
+
"target_batch_type": "dataset",
|
|
406
|
+
"is_system": True,
|
|
407
|
+
"status": "active",
|
|
408
|
+
"current_published_version_id": "sys-wfv-dataset-2",
|
|
409
|
+
"draft_version_id": None,
|
|
410
|
+
},
|
|
411
|
+
{
|
|
412
|
+
"id": "org-wf-graph-draft",
|
|
413
|
+
"code": "graph_draft_only",
|
|
414
|
+
"name": "Graph, never published",
|
|
415
|
+
"description": None,
|
|
416
|
+
"target_batch_type": "graph",
|
|
417
|
+
"is_system": False,
|
|
418
|
+
"status": "active",
|
|
419
|
+
"current_published_version_id": None,
|
|
420
|
+
"draft_version_id": "draft-1",
|
|
421
|
+
},
|
|
422
|
+
{
|
|
423
|
+
"id": "sys-wf-graph-2",
|
|
424
|
+
"code": "graph_two_step",
|
|
425
|
+
"name": "Graph two-step review",
|
|
426
|
+
"description": None,
|
|
427
|
+
"target_batch_type": "graph",
|
|
428
|
+
"is_system": True,
|
|
429
|
+
"status": "active",
|
|
430
|
+
"current_published_version_id": "sys-wfv-graph-2",
|
|
431
|
+
"draft_version_id": None,
|
|
432
|
+
},
|
|
433
|
+
],
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
BOUND_ENVELOPE = {
|
|
437
|
+
"success": True,
|
|
438
|
+
"message": "0 job(s) re-governed",
|
|
439
|
+
"data": {"jobs_regoverned": 0, "workflow_version_id": "sys-wfv-graph-2"},
|
|
440
|
+
}
|
|
441
|
+
|
|
442
|
+
|
|
443
|
+
class TestWorkflows:
|
|
444
|
+
def test_list_workflows_hits_the_workflows_root(self, client, stub_requests):
|
|
445
|
+
stub_requests.queue(json_data=WORKFLOWS_PAGE)
|
|
446
|
+
|
|
447
|
+
result = client.list_workflows(organisation_id=2)
|
|
448
|
+
|
|
449
|
+
call = stub_requests.calls[0]
|
|
450
|
+
assert call.method == "GET"
|
|
451
|
+
assert call.url == "http://cp.test/api/annotation-workflows"
|
|
452
|
+
assert call.kwargs["params"] == {"o": "2", "p": "0", "s": "50"}
|
|
453
|
+
assert [w.id for w in result.items] == ["sys-wf-dataset-2", "org-wf-graph-draft", "sys-wf-graph-2"]
|
|
454
|
+
|
|
455
|
+
def test_list_workflows_forwards_pagination(self, client, stub_requests):
|
|
456
|
+
stub_requests.queue(json_data={"page": {"page": 1, "size": 5, "total": 0}, "items": []})
|
|
457
|
+
|
|
458
|
+
client.list_workflows(organisation_id=9, page=1, size=5)
|
|
459
|
+
|
|
460
|
+
assert stub_requests.calls[0].kwargs["params"] == {"o": "9", "p": "1", "s": "5"}
|
|
461
|
+
|
|
462
|
+
def test_bind_workflow_posts_the_command_envelope(self, client, stub_requests):
|
|
463
|
+
stub_requests.queue(json_data=BOUND_ENVELOPE)
|
|
464
|
+
|
|
465
|
+
result = client.bind_workflow(organisation_id=2, batch_id="b-1", workflow_id="sys-wf-graph-2")
|
|
466
|
+
|
|
467
|
+
call = stub_requests.calls[0]
|
|
468
|
+
assert call.method == "POST"
|
|
469
|
+
assert call.url == "http://cp.test/api/annotations/b-1/_command"
|
|
470
|
+
assert call.kwargs["json"] == {
|
|
471
|
+
"command": "bind_workflow",
|
|
472
|
+
"organisation": 2,
|
|
473
|
+
"payload": {"job_type": "*", "workflow_id": "sys-wf-graph-2"},
|
|
474
|
+
}
|
|
475
|
+
assert result.workflow_version_id == "sys-wfv-graph-2"
|
|
476
|
+
assert result.jobs_regoverned == 0
|
|
477
|
+
|
|
478
|
+
def test_bind_workflow_forwards_job_type_and_rebind_reason(self, client, stub_requests):
|
|
479
|
+
stub_requests.queue(json_data=BOUND_ENVELOPE)
|
|
480
|
+
|
|
481
|
+
client.bind_workflow(
|
|
482
|
+
organisation_id=2,
|
|
483
|
+
batch_id="b-1",
|
|
484
|
+
workflow_id="sys-wf-graph-2",
|
|
485
|
+
job_type="dbq_rules",
|
|
486
|
+
rebind_reason="moving to the two-step review",
|
|
487
|
+
)
|
|
488
|
+
|
|
489
|
+
assert stub_requests.calls[0].kwargs["json"]["payload"] == {
|
|
490
|
+
"job_type": "dbq_rules",
|
|
491
|
+
"workflow_id": "sys-wf-graph-2",
|
|
492
|
+
"rebind_reason": "moving to the two-step review",
|
|
493
|
+
}
|
|
494
|
+
|
|
495
|
+
|
|
496
|
+
class TestPushGraphBindsAWorkflow:
|
|
497
|
+
"""Issue #14: a batch cannot hold jobs until a workflow is bound to it.
|
|
498
|
+
|
|
499
|
+
The server's insert trigger refuses every job otherwise, surfacing as an opaque
|
|
500
|
+
500 from the upload, so push_graph has to bind between create and upload.
|
|
501
|
+
"""
|
|
502
|
+
|
|
503
|
+
def _queue_full_push(self, stub_requests):
|
|
504
|
+
stub_requests.queue(json_data=WORKFLOWS_PAGE) # resolve
|
|
505
|
+
stub_requests.queue(json_data=CREATED_ENVELOPE) # create
|
|
506
|
+
stub_requests.queue(json_data=BOUND_ENVELOPE) # bind
|
|
507
|
+
stub_requests.queue(json_data=None) # upload (null body)
|
|
508
|
+
stub_requests.queue(json_data=ACTIVE_BATCH_JSON) # read back
|
|
509
|
+
|
|
510
|
+
def test_resolves_creates_binds_uploads_then_reads_back_in_order(self, client, stub_requests):
|
|
511
|
+
self._queue_full_push(stub_requests)
|
|
512
|
+
|
|
513
|
+
result = client.push_graph(organisation_id=2, name="MTUS Knee 2026", graph=GRAPH)
|
|
514
|
+
|
|
515
|
+
batch_id = CREATED_ENVELOPE["data"]["id"]
|
|
516
|
+
assert [(c.method, c.url) for c in stub_requests.calls] == [
|
|
517
|
+
("GET", "http://cp.test/api/annotation-workflows"),
|
|
518
|
+
("POST", "http://cp.test/api/annotations/_command"),
|
|
519
|
+
("POST", f"http://cp.test/api/annotations/{batch_id}/_command"),
|
|
520
|
+
("POST", f"http://cp.test/api/annotations/{batch_id}/upload"),
|
|
521
|
+
("GET", f"http://cp.test/api/annotations/{batch_id}"),
|
|
522
|
+
]
|
|
523
|
+
assert result.total_jobs == 325
|
|
524
|
+
|
|
525
|
+
def test_binds_the_published_system_workflow_matching_the_batch_type(self, client, stub_requests):
|
|
526
|
+
# The page also holds a dataset workflow and an unpublished graph one; neither
|
|
527
|
+
# is bindable here — the dataset one governs the wrong batch type, and a
|
|
528
|
+
# workflow with no published version cannot be bound at all.
|
|
529
|
+
self._queue_full_push(stub_requests)
|
|
530
|
+
|
|
531
|
+
client.push_graph(organisation_id=2, name="n", graph=GRAPH)
|
|
532
|
+
|
|
533
|
+
assert stub_requests.calls[2].kwargs["json"]["payload"] == {
|
|
534
|
+
"job_type": "*",
|
|
535
|
+
"workflow_id": "sys-wf-graph-2",
|
|
536
|
+
}
|
|
537
|
+
|
|
538
|
+
def test_an_explicit_workflow_id_skips_the_lookup(self, client, stub_requests):
|
|
539
|
+
stub_requests.queue(json_data=CREATED_ENVELOPE)
|
|
540
|
+
stub_requests.queue(json_data=BOUND_ENVELOPE)
|
|
541
|
+
stub_requests.queue(json_data=None)
|
|
542
|
+
stub_requests.queue(json_data=ACTIVE_BATCH_JSON)
|
|
543
|
+
|
|
544
|
+
client.push_graph(organisation_id=2, name="n", graph=GRAPH, workflow_id="org-wf-custom")
|
|
545
|
+
|
|
546
|
+
assert stub_requests.calls[0].url == "http://cp.test/api/annotations/_command" # no workflow list
|
|
547
|
+
assert stub_requests.calls[1].kwargs["json"]["payload"]["workflow_id"] == "org-wf-custom"
|
|
548
|
+
|
|
549
|
+
def test_forwards_a_rebind_reason(self, client, stub_requests):
|
|
550
|
+
stub_requests.queue(json_data=CREATED_ENVELOPE)
|
|
551
|
+
stub_requests.queue(json_data=BOUND_ENVELOPE)
|
|
552
|
+
stub_requests.queue(json_data=None)
|
|
553
|
+
stub_requests.queue(json_data=ACTIVE_BATCH_JSON)
|
|
554
|
+
|
|
555
|
+
client.push_graph(
|
|
556
|
+
organisation_id=2, name="n", graph=GRAPH, workflow_id="w-1", rebind_reason="switching review flow"
|
|
557
|
+
)
|
|
558
|
+
|
|
559
|
+
assert stub_requests.calls[1].kwargs["json"]["payload"]["rebind_reason"] == "switching review flow"
|
|
560
|
+
|
|
561
|
+
def test_no_bindable_workflow_raises_before_creating_a_batch(self, client, stub_requests):
|
|
562
|
+
# Only a dataset workflow on offer: pushing a graph batch cannot proceed, and
|
|
563
|
+
# must not leave a batch behind while failing.
|
|
564
|
+
stub_requests.queue(
|
|
565
|
+
json_data={"page": {"page": 0, "size": 50, "total": 1}, "items": [WORKFLOWS_PAGE["items"][0]]}
|
|
566
|
+
)
|
|
567
|
+
|
|
568
|
+
with pytest.raises(ValueError, match="no bindable annotation workflow"):
|
|
569
|
+
client.push_graph(organisation_id=2, name="n", graph=GRAPH)
|
|
570
|
+
|
|
571
|
+
assert len(stub_requests.calls) == 1 # the lookup only; nothing was created
|
|
572
|
+
|
|
573
|
+
def test_a_pre_workflow_server_404s_the_lookup_and_the_bind_is_skipped(self, client, stub_requests):
|
|
574
|
+
# Control planes older than the workflow model have no such endpoint and need
|
|
575
|
+
# no binding; the push must still work against them.
|
|
576
|
+
stub_requests.queue(json_data={"error": {"message": "Not Found"}}, status_code=404)
|
|
577
|
+
stub_requests.queue(json_data=CREATED_ENVELOPE)
|
|
578
|
+
stub_requests.queue(json_data=None)
|
|
579
|
+
stub_requests.queue(json_data=ACTIVE_BATCH_JSON)
|
|
580
|
+
|
|
581
|
+
result = client.push_graph(organisation_id=2, name="n", graph=GRAPH)
|
|
582
|
+
|
|
583
|
+
assert [c.method for c in stub_requests.calls] == ["GET", "POST", "POST", "GET"]
|
|
584
|
+
assert "_command" not in stub_requests.calls[2].url # straight to the upload
|
|
585
|
+
assert result.total_jobs == 325
|
|
586
|
+
|
|
587
|
+
def test_other_errors_from_the_lookup_propagate(self, client, stub_requests):
|
|
588
|
+
stub_requests.queue(json_data={"error": {"message": "boom"}}, status_code=500)
|
|
589
|
+
|
|
590
|
+
with pytest.raises(requests.HTTPError):
|
|
591
|
+
client.push_graph(organisation_id=2, name="n", graph=GRAPH)
|
|
592
|
+
|
|
593
|
+
assert len(stub_requests.calls) == 1
|
|
388
594
|
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
595
|
+
def test_validates_the_graph_source_before_anything_else(self, client, stub_requests):
|
|
596
|
+
with pytest.raises(ValueError, match="exactly one"):
|
|
597
|
+
client.push_graph(organisation_id=2, name="n")
|
|
598
|
+
|
|
599
|
+
assert stub_requests.calls == []
|
|
@@ -14,7 +14,10 @@ from agency_sdk.delegates.annotations_dto import (
|
|
|
14
14
|
AnnotationBatchResponse,
|
|
15
15
|
AnnotationSpec,
|
|
16
16
|
AnnotationSpecsPagedResult,
|
|
17
|
+
AnnotationWorkflow,
|
|
18
|
+
AnnotationWorkflowsPagedResult,
|
|
17
19
|
BatchStatus,
|
|
20
|
+
BindWorkflowResult,
|
|
18
21
|
CreateBatchResult,
|
|
19
22
|
CreateSpecResult,
|
|
20
23
|
PushGraphResult,
|
|
@@ -201,3 +204,96 @@ def test_status_enums_match_the_server_constants():
|
|
|
201
204
|
|
|
202
205
|
def test_module_constants_document_the_server_defaults():
|
|
203
206
|
assert (BATCH_TYPE_GRAPH, DEFAULT_JOB_TYPE, DEFAULT_TARGET_CLASS) == ("graph", "rule_validation", "rule")
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
#: A batch as the control plane returns it since the job-counter split (gts-comand eda4f9ca):
|
|
210
|
+
#: `completed_jobs` is gone, replaced by resolved/accepted/rejected. Transcribed from a live
|
|
211
|
+
#: `GET /api/annotations/{id}?o=2`.
|
|
212
|
+
SPLIT_COUNTER_BATCH_JSON = {
|
|
213
|
+
"id": "7324f779-3e61-418e-be3b-2a3faf296a27",
|
|
214
|
+
"organisation_id": 2,
|
|
215
|
+
"name": "DBQ: Knee and Lower Leg — source_text verification",
|
|
216
|
+
"description": "Rebuilt from archived run xval17 with the current producer.",
|
|
217
|
+
"instructions": None,
|
|
218
|
+
"batch_type": "graph",
|
|
219
|
+
"graph_uri": "2/annotations/7324f779-3e61-418e-be3b-2a3faf296a27/graph.json",
|
|
220
|
+
"graph_run_id": "ac4-source-text-probe",
|
|
221
|
+
"target_class": "rule",
|
|
222
|
+
"context_hops": 1,
|
|
223
|
+
"total_jobs": 14,
|
|
224
|
+
"resolved_jobs": 3,
|
|
225
|
+
"accepted_jobs": 2,
|
|
226
|
+
"rejected_jobs": 1,
|
|
227
|
+
"status": 1,
|
|
228
|
+
"confidentiality_level": "INTERNAL",
|
|
229
|
+
"audit_data": {"created_on": "2026-08-21 10:00:00Z", "created_by": "901"},
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
WORKFLOW_JSON = {
|
|
233
|
+
"id": "sys-wf-graph-2",
|
|
234
|
+
"code": "graph_two_step",
|
|
235
|
+
"name": "Graph two-step review",
|
|
236
|
+
"description": "One person annotates, a different person approves.",
|
|
237
|
+
"target_batch_type": "graph",
|
|
238
|
+
"is_system": True,
|
|
239
|
+
"status": "active",
|
|
240
|
+
"current_published_version_id": "sys-wfv-graph-2",
|
|
241
|
+
"draft_version_id": None,
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
def test_batch_parses_the_split_job_counters():
|
|
246
|
+
batch = AnnotationBatch(**SPLIT_COUNTER_BATCH_JSON)
|
|
247
|
+
|
|
248
|
+
assert batch.total_jobs == 14
|
|
249
|
+
assert batch.resolved_jobs == 3
|
|
250
|
+
assert batch.accepted_jobs == 2
|
|
251
|
+
assert batch.rejected_jobs == 1
|
|
252
|
+
# The pre-split counter simply is not sent any more; it must not be required.
|
|
253
|
+
assert batch.completed_jobs is None
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
def test_batch_still_parses_a_pre_split_server_payload():
|
|
257
|
+
# One model has to cover both server generations: older control planes send
|
|
258
|
+
# completed_jobs and none of the three new counters.
|
|
259
|
+
batch = AnnotationBatch(**ACTIVE_BATCH_JSON)
|
|
260
|
+
|
|
261
|
+
assert batch.completed_jobs == 0
|
|
262
|
+
assert batch.resolved_jobs is None
|
|
263
|
+
assert batch.accepted_jobs is None
|
|
264
|
+
assert batch.rejected_jobs is None
|
|
265
|
+
|
|
266
|
+
|
|
267
|
+
def test_batch_response_parses_the_live_single_read():
|
|
268
|
+
response = AnnotationBatchResponse(**{**SPLIT_COUNTER_BATCH_JSON, "viewer_role": "admin"})
|
|
269
|
+
|
|
270
|
+
assert response.viewer_role == "admin"
|
|
271
|
+
assert response.accepted_jobs == 2
|
|
272
|
+
assert response.status == BatchStatus.ACTIVE
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
def test_annotation_workflow_deserialises():
|
|
276
|
+
workflow = AnnotationWorkflow(**WORKFLOW_JSON)
|
|
277
|
+
|
|
278
|
+
assert workflow.id == "sys-wf-graph-2"
|
|
279
|
+
assert workflow.target_batch_type == "graph"
|
|
280
|
+
assert workflow.is_system is True
|
|
281
|
+
assert workflow.status == "active"
|
|
282
|
+
assert workflow.current_published_version_id == "sys-wfv-graph-2"
|
|
283
|
+
assert workflow.draft_version_id is None
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
def test_annotation_workflows_paged_result_wraps_page_and_items():
|
|
287
|
+
result = AnnotationWorkflowsPagedResult(**{"page": {"page": 0, "size": 50, "total": 1}, "items": [WORKFLOW_JSON]})
|
|
288
|
+
|
|
289
|
+
assert result.page.total == 1
|
|
290
|
+
assert [w.code for w in result.items] == ["graph_two_step"]
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
def test_bind_workflow_result_carries_the_bound_version_and_regoverned_count():
|
|
294
|
+
result = BindWorkflowResult(
|
|
295
|
+
success=True, message="0 job(s) re-governed", workflow_version_id="sys-wfv-graph-2", jobs_regoverned=0
|
|
296
|
+
)
|
|
297
|
+
|
|
298
|
+
assert result.workflow_version_id == "sys-wfv-graph-2"
|
|
299
|
+
assert result.jobs_regoverned == 0
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: gts-agency_python-sdk
|
|
3
|
-
Version: 0.0.
|
|
3
|
+
Version: 0.0.1rc15
|
|
4
4
|
Author-email: Ground Control Systems <engineering@groundcontrolsystems.com>
|
|
5
5
|
Requires-Python: >=3.12
|
|
6
6
|
Description-Content-Type: text/markdown
|
|
@@ -81,7 +81,7 @@ Access each API domain through the facade:
|
|
|
81
81
|
- `client.work_queues()` — work-queue ingestion: create items with exactly-once external refs, publish, claim by ref, queue-scoped owner lookup (`get_items_by_ref`), unblock/retry/reprocess, delete, and `list()` to resolve a queue name→id (409 returns a typed claim-lost result from the error envelope's `error.details`, plus a `contended` flag — not an exception)
|
|
82
82
|
- `client.sessions()` — report progress on a dispatched control-plane session: `attach` to the inherited session then `update` its status/result/events/metrics (the agent inherits the session, never self-registers — no `register`)
|
|
83
83
|
- `client.session_templates()` — list session templates to resolve a template name → id (read-only)
|
|
84
|
-
- `client.annotations()` — publish a knowledge graph as annotator work: `push_graph()` does create-batch → multipart upload → read-back in one call (one job per `class: "rule"` vertex), plus the individual legs, batch reads, and the job specifications that seed each job's checklist ([docs/annotations.md](docs/annotations.md))
|
|
84
|
+
- `client.annotations()` — publish a knowledge graph as annotator work: `push_graph()` does resolve-workflow → create-batch → bind-workflow → multipart upload → read-back in one call (one job per `class: "rule"` vertex), plus the individual legs, `bind_workflow`/`list_workflows` (a batch cannot hold jobs until a workflow is bound to it), batch reads, and the job specifications that seed each job's checklist ([docs/annotations.md](docs/annotations.md))
|
|
85
85
|
- `client.gateway(org_id=..., gateway_base_url=...)` — OpenAI-compatible LLM calls routed through the org's agentgateway (shared credentials + `x-org` routing header)
|
|
86
86
|
|
|
87
87
|
### Rules Example
|
|
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "gts-agency_python-sdk"
|
|
7
|
-
version = "0.0.
|
|
7
|
+
version = "0.0.1rc15"
|
|
8
8
|
description = ""
|
|
9
9
|
requires-python = ">=3.12"
|
|
10
10
|
authors = [{name="Ground Control Systems", email="engineering@groundcontrolsystems.com"}]
|
|
File without changes
|
|
File without changes
|
{gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/auth_hooks.py
RENAMED
|
File without changes
|
|
File without changes
|
{gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/credentials.py
RENAMED
|
File without changes
|
{gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/__init__.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
{gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/observability/auth.py
RENAMED
|
File without changes
|
|
File without changes
|
{gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/__init__.py
RENAMED
|
File without changes
|
{gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/conftest.py
RENAMED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|