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