gts-agency-python-sdk 0.0.1rc15__tar.gz → 0.0.2rc2__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 (77) hide show
  1. {gts_agency_python_sdk-0.0.1rc15/gts_agency_python_sdk.egg-info → gts_agency_python_sdk-0.0.2rc2}/PKG-INFO +48 -4
  2. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/README.md +46 -3
  3. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/annotations_client.py +236 -4
  4. gts_agency_python_sdk-0.0.2rc2/agency_sdk/delegates/annotations_dto.py +460 -0
  5. gts_agency_python_sdk-0.0.2rc2/agency_sdk/delegates/datasets_client.py +395 -0
  6. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/datasets_dto.py +50 -0
  7. gts_agency_python_sdk-0.0.2rc2/agency_sdk/delegates/ontology_client.py +203 -0
  8. gts_agency_python_sdk-0.0.2rc2/agency_sdk/delegates/ontology_dto.py +221 -0
  9. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_annotations_client.py +418 -1
  10. gts_agency_python_sdk-0.0.2rc2/agency_sdk/test/test_annotations_dto.py +628 -0
  11. gts_agency_python_sdk-0.0.2rc2/agency_sdk/test/test_datasets_client.py +323 -0
  12. gts_agency_python_sdk-0.0.2rc2/agency_sdk/test/test_ontology_client.py +152 -0
  13. gts_agency_python_sdk-0.0.2rc2/agency_sdk/test/test_ontology_dto.py +158 -0
  14. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2/gts_agency_python_sdk.egg-info}/PKG-INFO +48 -4
  15. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/gts_agency_python_sdk.egg-info/SOURCES.txt +3 -0
  16. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/gts_agency_python_sdk.egg-info/requires.txt +1 -0
  17. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/pyproject.toml +6 -2
  18. gts_agency_python_sdk-0.0.1rc15/agency_sdk/delegates/annotations_dto.py +0 -200
  19. gts_agency_python_sdk-0.0.1rc15/agency_sdk/delegates/datasets_client.py +0 -109
  20. gts_agency_python_sdk-0.0.1rc15/agency_sdk/delegates/ontology_client.py +0 -102
  21. gts_agency_python_sdk-0.0.1rc15/agency_sdk/delegates/ontology_dto.py +0 -111
  22. gts_agency_python_sdk-0.0.1rc15/agency_sdk/test/test_annotations_dto.py +0 -299
  23. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/LICENSE +0 -0
  24. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/__init__.py +0 -0
  25. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/auth_hooks.py +0 -0
  26. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/client.py +0 -0
  27. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/credentials.py +0 -0
  28. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/__init__.py +0 -0
  29. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/base_client.py +0 -0
  30. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/datasource_client.py +0 -0
  31. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/datasource_dto.py +0 -0
  32. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/files_client.py +0 -0
  33. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/files_dto.py +0 -0
  34. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/gateway_client.py +0 -0
  35. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/gateway_dto.py +0 -0
  36. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/prompts_client.py +0 -0
  37. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/rules_client.py +0 -0
  38. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/rules_dto.py +0 -0
  39. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/session_client.py +0 -0
  40. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/session_dto.py +0 -0
  41. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/session_templates_client.py +0 -0
  42. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/session_templates_dto.py +0 -0
  43. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/session_vault_client.py +0 -0
  44. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/session_vault_dto.py +0 -0
  45. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/work_queue_client.py +0 -0
  46. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/delegates/work_queue_dto.py +0 -0
  47. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/domain.py +0 -0
  48. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/observability/__init__.py +0 -0
  49. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/observability/auth.py +0 -0
  50. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/observability/bootstrap.py +0 -0
  51. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/__init__.py +0 -0
  52. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/conftest.py +0 -0
  53. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_base_client.py +0 -0
  54. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_client_facade.py +0 -0
  55. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_credentials.py +0 -0
  56. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_files_client.py +0 -0
  57. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_files_dto.py +0 -0
  58. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_gateway_dto.py +0 -0
  59. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_gateway_facade.py +0 -0
  60. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_gateway_openai.py +0 -0
  61. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_observability_auth.py +0 -0
  62. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_observability_facade_threadsafety.py +0 -0
  63. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_observability_langfuse.py +0 -0
  64. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_observability_packaging.py +0 -0
  65. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_observability_pipeline.py +0 -0
  66. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_session_client.py +0 -0
  67. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_session_dto.py +0 -0
  68. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_session_templates_client.py +0 -0
  69. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_session_templates_dto.py +0 -0
  70. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_session_vault_client.py +0 -0
  71. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_session_vault_dto.py +0 -0
  72. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_stub_requests.py +0 -0
  73. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_work_queue_client.py +0 -0
  74. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/agency_sdk/test/test_work_queue_dto.py +0 -0
  75. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/gts_agency_python_sdk.egg-info/dependency_links.txt +0 -0
  76. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/gts_agency_python_sdk.egg-info/top_level.txt +0 -0
  77. {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc2}/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.1rc15
3
+ Version: 0.0.2rc2
4
4
  Author-email: Ground Control Systems <engineering@groundcontrolsystems.com>
5
5
  Requires-Python: >=3.12
6
6
  Description-Content-Type: text/markdown
@@ -20,6 +20,7 @@ Requires-Dist: pytest==7.4.0; extra == "dev"
20
20
  Requires-Dist: pytest-cov==4.1.0; extra == "dev"
21
21
  Requires-Dist: pre-commit==3.8.0; extra == "dev"
22
22
  Requires-Dist: black==23.12.1; extra == "dev"
23
+ Requires-Dist: bandit; extra == "dev"
23
24
  Dynamic: license-file
24
25
 
25
26
  # Agency Python SDK
@@ -71,19 +72,41 @@ client = AgencyClient(token_supplier=credentials, base_url="https://api.example.
71
72
 
72
73
  Access each API domain through the facade:
73
74
 
74
- - `client.dataset()` — datasets CRUD, filesystem traversal, clone
75
+ - `client.dataset()` — datasets CRUD, filesystem traversal, clone, and the write lifecycle `draft` → `push` → `publish` (`.agency/` workspace shared with `gts-cli`; [docs/datasets.md](docs/datasets.md))
75
76
  - `client.datasource()` — datasource and table introspection
76
77
  - `client.files()` — tenant file storage: list, upload, folder management, delete, signed URLs, `gtsf://` URI resolution, streamed download
77
- - `client.ontology()` — ontology export (JSON, Turtle, ISON) and entity-datasource mappings
78
+ - `client.ontology()` — list ontologies (name → id, optional `kind` filter), export (JSON snapshot, Turtle/OWL, SHACL, package, package-zip), and entity-datasource mappings
78
79
  - `client.prompts()` — prompt CRUD via command pattern
79
80
  - `client.rules()` — rule listing, detail, execution, and execution history
80
81
  - `client.session_vault()` — session-scoped key/value vault for agent state (classification-based encryption, audited reveal)
81
82
  - `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
83
  - `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
84
  - `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))
85
+ - `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. Reading the work back is read-only and four calls: `list_jobs` (paged summaries — the payloads live on the single read), `get_job`, `list_job_transitions` (approval evidence; its `note` is PHI-capable and must never be logged), `get_graph`, and `list_batch_members` (who held which role on a batch and when — role-per-row, and the display fields are PII) ([docs/annotations.md](docs/annotations.md))
85
86
  - `client.gateway(org_id=..., gateway_base_url=...)` — OpenAI-compatible LLM calls routed through the org's agentgateway (shared credentials + `x-org` routing header)
86
87
 
88
+ ### Dataset Write Example
89
+
90
+ `clone_dataset` writes an `.agency/` workspace. `push` uploads the tree's diff against it into the
91
+ current draft. A new dataset starts as a draft, so you only need `draft` after a publish.
92
+
93
+ ```python
94
+ datasets = client.dataset()
95
+
96
+ datasets.clone_dataset(dataset_id="ds-id", organisation_id=2, target_path="./samples")
97
+ datasets.draft(dataset_id="ds-id", organisation_id=2, root="./samples") # next mutable version
98
+
99
+ # ... edit files under ./samples (never inside .agency/) ...
100
+
101
+ result = datasets.push(organisation_id=2, root="./samples") # upload changed, delete removed
102
+ print(f"uploaded={result.uploaded} deleted={result.deleted}")
103
+
104
+ datasets.publish(dataset_id="ds-id", organisation_id=2, comment="Added Q1", root="./samples")
105
+ ```
106
+
107
+ A self-checking end-to-end run is in [`examples/quick_dataset_draft_push_publish.py`](examples/quick_dataset_draft_push_publish.py)
108
+ (set `AGENCY_DATASET_ID`; each run publishes one new version).
109
+
87
110
  ### Rules Example
88
111
 
89
112
  ```python
@@ -130,6 +153,27 @@ files.download(file_id=file_id, organisation_id=2, target_path="./report.pdf")
130
153
  See [docs/files_storage_flows.md](docs/files_storage_flows.md) for the full
131
154
  upload/download architecture.
132
155
 
156
+ ### Ontology Export Example
157
+
158
+ Agents retrieve a typed JSON snapshot and use its classes, relations, and
159
+ properties to decide how to treat data. Text formats (`turtle`, `shacl`,
160
+ `package`) return `str`; `package-zip` is binary and must go through
161
+ `export_bytes()`.
162
+
163
+ ```python
164
+ ontology = client.ontology()
165
+
166
+ listed = ontology.list(organisation_id=2)
167
+ ontology_id = next(item.id for item in listed.items if item.name == "claims")
168
+
169
+ snapshot = ontology.export_snapshot(ontology_id=ontology_id, organisation_id=2)
170
+ for entity in snapshot.entities.values():
171
+ print(f"{entity.entity_type}: {entity.label}")
172
+
173
+ turtle = ontology.export(ontology_id=ontology_id, organisation_id=2, export_format="turtle")
174
+ zip_bytes = ontology.export_bytes(ontology_id=ontology_id, organisation_id=2, export_format="package-zip")
175
+ ```
176
+
133
177
  ### Observability Example
134
178
 
135
179
  Opt-in OpenTelemetry tracing + log correlation, shipped to a Langfuse backend and
@@ -47,19 +47,41 @@ client = AgencyClient(token_supplier=credentials, base_url="https://api.example.
47
47
 
48
48
  Access each API domain through the facade:
49
49
 
50
- - `client.dataset()` — datasets CRUD, filesystem traversal, clone
50
+ - `client.dataset()` — datasets CRUD, filesystem traversal, clone, and the write lifecycle `draft` → `push` → `publish` (`.agency/` workspace shared with `gts-cli`; [docs/datasets.md](docs/datasets.md))
51
51
  - `client.datasource()` — datasource and table introspection
52
52
  - `client.files()` — tenant file storage: list, upload, folder management, delete, signed URLs, `gtsf://` URI resolution, streamed download
53
- - `client.ontology()` — ontology export (JSON, Turtle, ISON) and entity-datasource mappings
53
+ - `client.ontology()` — list ontologies (name → id, optional `kind` filter), export (JSON snapshot, Turtle/OWL, SHACL, package, package-zip), and entity-datasource mappings
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
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 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))
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. Reading the work back is read-only and four calls: `list_jobs` (paged summaries — the payloads live on the single read), `get_job`, `list_job_transitions` (approval evidence; its `note` is PHI-capable and must never be logged), `get_graph`, and `list_batch_members` (who held which role on a batch and when — role-per-row, and the display fields are PII) ([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
+ ### Dataset Write Example
64
+
65
+ `clone_dataset` writes an `.agency/` workspace. `push` uploads the tree's diff against it into the
66
+ current draft. A new dataset starts as a draft, so you only need `draft` after a publish.
67
+
68
+ ```python
69
+ datasets = client.dataset()
70
+
71
+ datasets.clone_dataset(dataset_id="ds-id", organisation_id=2, target_path="./samples")
72
+ datasets.draft(dataset_id="ds-id", organisation_id=2, root="./samples") # next mutable version
73
+
74
+ # ... edit files under ./samples (never inside .agency/) ...
75
+
76
+ result = datasets.push(organisation_id=2, root="./samples") # upload changed, delete removed
77
+ print(f"uploaded={result.uploaded} deleted={result.deleted}")
78
+
79
+ datasets.publish(dataset_id="ds-id", organisation_id=2, comment="Added Q1", root="./samples")
80
+ ```
81
+
82
+ A self-checking end-to-end run is in [`examples/quick_dataset_draft_push_publish.py`](examples/quick_dataset_draft_push_publish.py)
83
+ (set `AGENCY_DATASET_ID`; each run publishes one new version).
84
+
63
85
  ### Rules Example
64
86
 
65
87
  ```python
@@ -106,6 +128,27 @@ files.download(file_id=file_id, organisation_id=2, target_path="./report.pdf")
106
128
  See [docs/files_storage_flows.md](docs/files_storage_flows.md) for the full
107
129
  upload/download architecture.
108
130
 
131
+ ### Ontology Export Example
132
+
133
+ Agents retrieve a typed JSON snapshot and use its classes, relations, and
134
+ properties to decide how to treat data. Text formats (`turtle`, `shacl`,
135
+ `package`) return `str`; `package-zip` is binary and must go through
136
+ `export_bytes()`.
137
+
138
+ ```python
139
+ ontology = client.ontology()
140
+
141
+ listed = ontology.list(organisation_id=2)
142
+ ontology_id = next(item.id for item in listed.items if item.name == "claims")
143
+
144
+ snapshot = ontology.export_snapshot(ontology_id=ontology_id, organisation_id=2)
145
+ for entity in snapshot.entities.values():
146
+ print(f"{entity.entity_type}: {entity.label}")
147
+
148
+ turtle = ontology.export(ontology_id=ontology_id, organisation_id=2, export_format="turtle")
149
+ zip_bytes = ontology.export_bytes(ontology_id=ontology_id, organisation_id=2, export_format="package-zip")
150
+ ```
151
+
109
152
  ### Observability Example
110
153
 
111
154
  Opt-in OpenTelemetry tracing + log correlation, shipped to a Langfuse backend and
@@ -27,15 +27,24 @@ from __future__ import annotations
27
27
  import json
28
28
  from collections.abc import Mapping
29
29
  from pathlib import Path
30
- from typing import Any
30
+ from typing import Any, TypeVar
31
31
 
32
32
  import requests
33
+ from pydantic import ValidationError
34
+
35
+ from pydantic import BaseModel
33
36
 
34
37
  from agency_sdk.credentials import CredentialsSupplier
35
38
  from agency_sdk.delegates.annotations_dto import (
36
39
  BATCH_TYPE_GRAPH,
40
+ AnnotationBatch,
37
41
  AnnotationBatchesPagedResult,
42
+ AnnotationBatchMember,
43
+ AnnotationBatchMembersPagedResult,
38
44
  AnnotationBatchResponse,
45
+ AnnotationJob,
46
+ AnnotationJobsPagedResult,
47
+ AnnotationJobSummary,
39
48
  AnnotationSpec,
40
49
  AnnotationSpecsPagedResult,
41
50
  AnnotationWorkflow,
@@ -43,7 +52,11 @@ from agency_sdk.delegates.annotations_dto import (
43
52
  BindWorkflowResult,
44
53
  CreateBatchResult,
45
54
  CreateSpecResult,
55
+ JobTransitionEntry,
56
+ JobTransitionsPagedResult,
46
57
  PushGraphResult,
58
+ RejectedRow,
59
+ TolerantPage,
47
60
  )
48
61
  from agency_sdk.delegates.base_client import BaseDelegateClient
49
62
 
@@ -77,6 +90,42 @@ def _command_id(body: Mapping[str, Any], subject: str) -> str:
77
90
  return identifier
78
91
 
79
92
 
93
+ _PageT = TypeVar("_PageT", bound=TolerantPage)
94
+ _ItemT = TypeVar("_ItemT", bound=BaseModel)
95
+
96
+
97
+ def _parse_page(page_type: type[_PageT], item_type: type[_ItemT], body: Mapping[str, Any]) -> _PageT:
98
+ """Build a paged result, validating each row on its own.
99
+
100
+ The obvious construction — ``PagedResult(**body)`` over ``items: list[Item]`` —
101
+ validates the list as a unit, so **one bad row loses the whole page**: the
102
+ well-formed rows beside it become unreachable, not merely unreported. That blast
103
+ radius is what this avoids. A consumer typically filters scope *after* parsing, so
104
+ without this a row it was going to discard can stop it reading the rows it wanted
105
+ — every time, since a malformed row does not heal on its own.
106
+
107
+ Rows that fail land in ``rejected`` with their original index, so nothing is lost
108
+ silently. A row that is not a mapping at all is rejected too rather than escaping
109
+ as a ``TypeError``: ``Item(**row)`` on a string or ``None`` does not raise
110
+ ``ValidationError``, and a guard that only expects one would still lose the page.
111
+
112
+ The ``page`` envelope is deliberately NOT tolerated. A page whose paging does not
113
+ parse is a broken response, and handing back rows under paging that cannot be
114
+ trusted is worse than failing.
115
+ """
116
+ items: list[_ItemT] = []
117
+ rejected: list[RejectedRow] = []
118
+ for index, row in enumerate(body.get("items") or []):
119
+ if not isinstance(row, Mapping):
120
+ rejected.append(RejectedRow(index=index, raw=row, error=f"expected an object, got {type(row).__name__}"))
121
+ continue
122
+ try:
123
+ items.append(item_type(**row))
124
+ except ValidationError as error:
125
+ rejected.append(RejectedRow(index=index, raw=row, error=str(error)))
126
+ return page_type(page=body.get("page") or {}, items=items, rejected=rejected)
127
+
128
+
80
129
  class _AnnotationWorkflowsEndpoint(BaseDelegateClient):
81
130
  """The annotation workflows, which hang off their own API root.
82
131
 
@@ -237,7 +286,8 @@ class AgencyAnnotationsClient(BaseDelegateClient):
237
286
  nobody else's.
238
287
  """
239
288
  params = {"o": str(organisation_id), "p": str(page), "s": str(size)}
240
- return AnnotationWorkflowsPagedResult(**self._workflows._make_request("GET", "", params=params))
289
+ body = self._workflows._make_request("GET", "", params=params)
290
+ return _parse_page(AnnotationWorkflowsPagedResult, AnnotationWorkflow, body)
241
291
 
242
292
  def bind_workflow(
243
293
  self,
@@ -437,7 +487,8 @@ class AgencyAnnotationsClient(BaseDelegateClient):
437
487
  params["batch_type"] = batch_type
438
488
  if view is not None:
439
489
  params["view"] = view
440
- return AnnotationBatchesPagedResult(**self._make_request("GET", "", params=params))
490
+ body = self._make_request("GET", "", params=params)
491
+ return _parse_page(AnnotationBatchesPagedResult, AnnotationBatch, body)
441
492
 
442
493
  def create_spec(
443
494
  self,
@@ -492,4 +543,185 @@ class AgencyAnnotationsClient(BaseDelegateClient):
492
543
  def list_specs(self, organisation_id: int, *, page: int = 0, size: int = 50) -> AnnotationSpecsPagedResult:
493
544
  """List the org's job specifications (paged; the server's own default size is 10)."""
494
545
  params = {"o": str(organisation_id), "p": str(page), "s": str(size)}
495
- return AnnotationSpecsPagedResult(**self._specs._make_request("GET", "", params=params))
546
+ body = self._specs._make_request("GET", "", params=params)
547
+ return _parse_page(AnnotationSpecsPagedResult, AnnotationSpec, body)
548
+
549
+ def list_jobs(
550
+ self, organisation_id: int, batch_id: str, *, page: int = 0, size: int = 50
551
+ ) -> AnnotationJobsPagedResult:
552
+ """List a batch's jobs (paged) — **summaries only**.
553
+
554
+ Each item carries identity and pipeline position: ``id``, ``state_code``,
555
+ ``workflow_version_id``, the vertex labels and ``audit_data``. The heavy
556
+ payloads — ``vertex_data``, ``connected_vertices``, ``connected_edges``,
557
+ ``delta``, ``data``, ``checklist_state``, ``annotation_data`` — are
558
+ **deliberately absent**: a list page never renders them, and the server's
559
+ deferred join exists precisely to keep those wide rows off the page. Follow
560
+ up with :meth:`get_job` for any of them.
561
+
562
+ There is no server-side "completed" filter and this method does not fake
563
+ one; filter on ``state_code`` (or on the batch's ``status`` against
564
+ :class:`~agency_sdk.delegates.annotations_dto.BatchStatus`) client-side.
565
+
566
+ Args:
567
+ organisation_id: The organisation ID.
568
+ batch_id: The batch whose jobs to list.
569
+ page: Zero-indexed page number.
570
+ size: Page size (the server's own default is 20).
571
+ """
572
+ params = {"o": str(organisation_id), "p": str(page), "s": str(size)}
573
+ body = self._make_request("GET", f"/{batch_id}/jobs", params=params)
574
+ return _parse_page(AnnotationJobsPagedResult, AnnotationJobSummary, body)
575
+
576
+ def get_job(self, organisation_id: int, batch_id: str, job_id: str) -> AnnotationJob:
577
+ """Read one job in full: the graph context, the human edits, and ``revision``.
578
+
579
+ This is the only read that returns ``annotation_data`` (the annotator's
580
+ edits), ``checklist_state``, and the ``vertex_data`` / ``connected_*``
581
+ context the upload attached — see :meth:`list_jobs` for why the list omits
582
+ them. Those columns are opaque blobs whose shape belongs to whichever
583
+ front-end wrote them, so they arrive unvalidated and unreshaped.
584
+
585
+ ``revision`` is worth capturing even when you only want the content:
586
+ approved work is not immutable server-side, so a caller assembling several
587
+ jobs should snapshot each one's revision and re-read afterwards to detect an
588
+ edit that landed underneath it.
589
+
590
+ Note this endpoint takes ``o`` alone — no pagination params.
591
+
592
+ Raises:
593
+ requests.HTTPError: 404 when the job does not exist in that batch.
594
+ """
595
+ params = {"o": str(organisation_id)}
596
+ return AnnotationJob(**self._make_request("GET", f"/{batch_id}/jobs/{job_id}", params=params))
597
+
598
+ def list_job_transitions(
599
+ self, organisation_id: int, batch_id: str, job_id: str, *, page: int = 0, size: int = 50
600
+ ) -> JobTransitionsPagedResult:
601
+ """Read a job's transition ledger (paged) — the approval evidence.
602
+
603
+ Who fired which transition, acting as what role, and under which workflow
604
+ version. It is a separate read from :meth:`get_job` because the ledger is
605
+ append-only and unbounded, and because it carries PHI-capable notes.
606
+
607
+ Two fields matter more than they look:
608
+
609
+ - ``prior_actor_conflict`` marks a transition fired by someone who had
610
+ already acted on this job — the distinct-actor guard was not satisfied.
611
+ Treat it as a stop signal, not a warning.
612
+ - ``workflow_version_id`` is the version **in force when the transition
613
+ fired**, not the job's current one. Bindings move, so only this stamped
614
+ copy makes a past transition attributable to the policy that permitted it.
615
+
616
+ **PHI:** ``note`` is clinician-written free text and may contain patient
617
+ information. Never log, trace, or export it — comand deliberately keeps it
618
+ out of its own access log.
619
+
620
+ Note the query params here are ``organisation`` / ``page`` / ``size``,
621
+ spelled out, unlike every other read on this client. The server binds a
622
+ different query type on this route (``OrganisationQuery``, not
623
+ ``JobListParams``), so the SDK mirrors each endpoint rather than
624
+ normalising: abbreviating here would simply fail to bind.
625
+
626
+ **The server silently clamps ``size`` to 500.** It is the only clamp on the
627
+ annotation service and it reports nothing: ask for 9999 and you get 500 back
628
+ with no signal that your number was ignored. That matters beyond the missing
629
+ rows, because a walk that ends on "I got back fewer than I asked for" reads
630
+ the clamp as the last page — the same failure shape as counting
631
+ ``len(items)`` instead of
632
+ :attr:`~agency_sdk.delegates.annotations_dto.TolerantPage.row_count`, but
633
+ arriving from the server rather than from the parse. Keep ``size`` at or
634
+ below 500 so the number you pass is the number that applies.
635
+
636
+ Args:
637
+ organisation_id: The organisation ID.
638
+ batch_id: The batch the job belongs to.
639
+ job_id: The job whose history to read.
640
+ page: Zero-indexed page number.
641
+ size: Page size. The server's own default is 100 and it **caps this at
642
+ 500 without saying so** — see above.
643
+ """
644
+ params = {"organisation": str(organisation_id), "page": str(page), "size": str(size)}
645
+ body = self._make_request("GET", f"/{batch_id}/jobs/{job_id}/transitions", params=params)
646
+ return _parse_page(JobTransitionsPagedResult, JobTransitionEntry, body)
647
+
648
+ def get_graph(self, organisation_id: int, batch_id: str) -> dict[str, Any]:
649
+ """Read back the graph that was uploaded to this batch, as a raw ``dict``.
650
+
651
+ Deliberately unmodelled: this is the caller's own ``{run_id, vertices,
652
+ edges}`` upload echoed back, and the SDK has no business constraining a
653
+ payload it did not define. Use it as the pristine copy to cross-check
654
+ against each job's ``vertex_data``, which annotators may have edited around.
655
+
656
+ Raises:
657
+ requests.HTTPError: 400 if the stored file does not parse as JSON.
658
+ **500** if the batch row points at an object that is not in the
659
+ store — the control plane does not translate the object store's
660
+ "no such key" into a 404, so a batch whose graph was never
661
+ uploaded, or whose object was lost, is indistinguishable from a
662
+ server fault at this level. (Observed against a live control
663
+ plane: a seeded batch whose ``graph_uri`` had no object behind it
664
+ answered 500 ``SERVICE_ERROR``.) Treat a 500 here as "the graph is
665
+ not retrievable", not as a transient error worth retrying.
666
+ """
667
+ return self._make_request("GET", f"/{batch_id}/graph", params={"o": str(organisation_id)})
668
+
669
+ def list_batch_members(
670
+ self, organisation_id: int, batch_id: str, *, page: int = 0, size: int = 50
671
+ ) -> AnnotationBatchMembersPagedResult:
672
+ """List a batch's members (paged): who may see it, as what, and for how long.
673
+
674
+ Two things this read is good for, and one it is not:
675
+
676
+ - **Membership windows.** Each row carries ``eff_from`` and an ``eff_to``
677
+ that is ``None`` while the membership is still in force.
678
+ - **Seeing a RESTRICTED batch's roster at all.** Confidentiality is enforced
679
+ on the *list*: the server appends ``AND (confidentiality_level NOT IN (...)
680
+ OR EXISTS (active membership))`` to :meth:`list_batches`, so a RESTRICTED
681
+ batch the caller is not an active member of is **invisible** there rather
682
+ than rejected. If a batch you expect is simply missing from a list, check
683
+ membership before suspecting the page parser.
684
+ - **Who held which role, and when** — including the workflow roles. ``role``
685
+ is an open vocabulary: ``"member"`` and ``"admin"`` plus whatever codes
686
+ the batch's workflow declares (``"annotator"``, ``"reviewer"``,
687
+ ``"approver"``, …). This table is the server's record of review
688
+ authority — its foreign key is ``RESTRICT`` so a batch delete cannot
689
+ erase it, and the distinct-actor check resolves against it — so read role
690
+ windows from here rather than inferring them from the first ledger row in
691
+ that role, which only sees people who actually acted.
692
+
693
+ Rows are **role-per-row**: the key is ``(batch_id, user_id, role,
694
+ eff_from)``, so one person appears once per role they hold. A lookup keyed
695
+ on ``user_id`` alone will find several.
696
+
697
+ **PII:** the display fields (``given_name``, ``family_name``, ``known_as``,
698
+ ``email``) name a real person. Do not log or export them casually.
699
+
700
+ Note the wire shape: the endpoint's published OpenAPI annotation says it
701
+ returns ``Vec<AnnotationBatchMember>``, but the handler binds pagination and
702
+ returns a paged result — a caller trusting the spec would unpack a bare
703
+ array and get nothing. Params are the abbreviated ``o`` / ``p`` / ``s``.
704
+
705
+ **This page is measured in people, not rows.** ``size`` caps distinct users;
706
+ the server then returns *every* role row for the users on that page, so a
707
+ page of 4 people can be 9 rows. The envelope reflects that unevenly:
708
+ ``page.total`` counts distinct **people** (matching the paging unit), while
709
+ ``page.size`` comes back as the number of **rows** returned — neither the
710
+ size you asked for nor the people count.
711
+
712
+ Consequently :attr:`~agency_sdk.delegates.annotations_dto.TolerantPage.row_count`
713
+ is the row count here, not the paging unit. It is still safe to end a walk
714
+ on it — ``row_count`` is never less than the number of people, so
715
+ ``row_count < size`` really does mean the last page — but it is not tight,
716
+ and a page that ends exactly on the cap costs one extra empty request. To be
717
+ exact, compare ``len({m.user_id for m in result.items})`` against ``size``.
718
+
719
+ Args:
720
+ organisation_id: The organisation ID.
721
+ batch_id: The batch whose members to list.
722
+ page: Zero-indexed page number — of **people**.
723
+ size: Maximum distinct users per page (the server's own default is 50).
724
+ """
725
+ params = {"o": str(organisation_id), "p": str(page), "s": str(size)}
726
+ body = self._make_request("GET", f"/{batch_id}/members", params=params)
727
+ return _parse_page(AnnotationBatchMembersPagedResult, AnnotationBatchMember, body)