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.
Files changed (69) hide show
  1. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/PKG-INFO +2 -2
  2. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/README.md +1 -1
  3. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/annotations_client.py +158 -13
  4. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/annotations_dto.py +48 -1
  5. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_annotations_client.py +224 -16
  6. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_annotations_dto.py +96 -0
  7. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/gts_agency_python_sdk.egg-info/PKG-INFO +2 -2
  8. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/pyproject.toml +1 -1
  9. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/LICENSE +0 -0
  10. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/__init__.py +0 -0
  11. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/auth_hooks.py +0 -0
  12. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/client.py +0 -0
  13. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/credentials.py +0 -0
  14. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/__init__.py +0 -0
  15. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/base_client.py +0 -0
  16. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/datasets_client.py +0 -0
  17. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/datasets_dto.py +0 -0
  18. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/datasource_client.py +0 -0
  19. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/datasource_dto.py +0 -0
  20. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/files_client.py +0 -0
  21. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/files_dto.py +0 -0
  22. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/gateway_client.py +0 -0
  23. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/gateway_dto.py +0 -0
  24. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/ontology_client.py +0 -0
  25. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/ontology_dto.py +0 -0
  26. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/prompts_client.py +0 -0
  27. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/rules_client.py +0 -0
  28. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/rules_dto.py +0 -0
  29. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_client.py +0 -0
  30. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_dto.py +0 -0
  31. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_templates_client.py +0 -0
  32. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_templates_dto.py +0 -0
  33. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_vault_client.py +0 -0
  34. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_vault_dto.py +0 -0
  35. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/work_queue_client.py +0 -0
  36. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/work_queue_dto.py +0 -0
  37. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/domain.py +0 -0
  38. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/observability/__init__.py +0 -0
  39. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/observability/auth.py +0 -0
  40. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/observability/bootstrap.py +0 -0
  41. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/__init__.py +0 -0
  42. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/conftest.py +0 -0
  43. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_base_client.py +0 -0
  44. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_client_facade.py +0 -0
  45. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_credentials.py +0 -0
  46. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_files_client.py +0 -0
  47. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_files_dto.py +0 -0
  48. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_gateway_dto.py +0 -0
  49. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_gateway_facade.py +0 -0
  50. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_gateway_openai.py +0 -0
  51. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_observability_auth.py +0 -0
  52. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_observability_facade_threadsafety.py +0 -0
  53. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_observability_langfuse.py +0 -0
  54. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_observability_packaging.py +0 -0
  55. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_observability_pipeline.py +0 -0
  56. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_client.py +0 -0
  57. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_dto.py +0 -0
  58. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_templates_client.py +0 -0
  59. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_templates_dto.py +0 -0
  60. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_vault_client.py +0 -0
  61. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_vault_dto.py +0 -0
  62. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_stub_requests.py +0 -0
  63. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_work_queue_client.py +0 -0
  64. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_work_queue_dto.py +0 -0
  65. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/gts_agency_python_sdk.egg-info/SOURCES.txt +0 -0
  66. {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
  67. {gts_agency_python_sdk-0.0.1rc14 → gts_agency_python_sdk-0.0.1rc15}/gts_agency_python_sdk.egg-info/requires.txt +0 -0
  68. {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
  69. {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.1rc14
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 (``/api/annotations``, ``/api/annotation-specs``).
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: a batch is **created** in ``DRAFT`` and the graph **upload**
5
- is what materialises the jobs and flips the batch to ``ACTIVE``. The graph the
6
- upload accepts is the same ``create.graph`` payload agents already build for the
7
- ontology sandbox (``run_id`` / ``vertices`` / ``edges``), so a caller that has one
8
- can push it as-is — see :meth:`AgencyAnnotationsClient.push_graph`, the one-call
9
- convenience over the whole flow.
10
-
11
- Contract verified against gts-comand ``8d64a64a``
12
- (``crates/comand/src/handler/annotations.rs``, ``service/annotation_service.rs``).
13
- Every handler here requires a principal with a local user id **and** organisation
14
- write permission on ``Resource::Annotations``.
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 in one call: create → upload → read back.
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
- completed_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
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 test_creates_uploads_and_reads_back_in_order(self, client, stub_requests):
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, _ = stub_requests.calls
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[1].kwargs["files"]["file"][1]) == GRAPH
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
- # The batch was created before the upload failed: two calls, no read-back, and the
390
- # DRAFT batch survives server-side (documented residue, recoverable via list_batches).
391
- assert len(stub_requests.calls) == 2
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.1rc14
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.1rc14"
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"}]