gts-agency-python-sdk 0.0.1rc15__tar.gz → 0.0.2rc1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {gts_agency_python_sdk-0.0.1rc15/gts_agency_python_sdk.egg-info → gts_agency_python_sdk-0.0.2rc1}/PKG-INFO +25 -3
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/README.md +23 -2
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/annotations_client.py +236 -4
- gts_agency_python_sdk-0.0.2rc1/agency_sdk/delegates/annotations_dto.py +460 -0
- gts_agency_python_sdk-0.0.2rc1/agency_sdk/delegates/ontology_client.py +203 -0
- gts_agency_python_sdk-0.0.2rc1/agency_sdk/delegates/ontology_dto.py +221 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_annotations_client.py +418 -1
- gts_agency_python_sdk-0.0.2rc1/agency_sdk/test/test_annotations_dto.py +628 -0
- gts_agency_python_sdk-0.0.2rc1/agency_sdk/test/test_ontology_client.py +152 -0
- gts_agency_python_sdk-0.0.2rc1/agency_sdk/test/test_ontology_dto.py +158 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1/gts_agency_python_sdk.egg-info}/PKG-INFO +25 -3
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/gts_agency_python_sdk.egg-info/SOURCES.txt +2 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/gts_agency_python_sdk.egg-info/requires.txt +1 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/pyproject.toml +6 -2
- gts_agency_python_sdk-0.0.1rc15/agency_sdk/delegates/annotations_dto.py +0 -200
- gts_agency_python_sdk-0.0.1rc15/agency_sdk/delegates/ontology_client.py +0 -102
- gts_agency_python_sdk-0.0.1rc15/agency_sdk/delegates/ontology_dto.py +0 -111
- gts_agency_python_sdk-0.0.1rc15/agency_sdk/test/test_annotations_dto.py +0 -299
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/LICENSE +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/auth_hooks.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/credentials.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/base_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/datasets_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/datasets_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/datasource_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/datasource_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/files_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/files_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/gateway_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/gateway_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/prompts_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/rules_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/rules_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/session_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/session_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/session_templates_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/session_templates_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/session_vault_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/session_vault_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/work_queue_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/delegates/work_queue_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/domain.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/observability/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/observability/auth.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/observability/bootstrap.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/conftest.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_base_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_client_facade.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_credentials.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_files_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_files_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_gateway_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_gateway_facade.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_gateway_openai.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_observability_auth.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_observability_facade_threadsafety.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_observability_langfuse.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_observability_packaging.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_observability_pipeline.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_session_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_session_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_session_templates_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_session_templates_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_session_vault_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_session_vault_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_stub_requests.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_work_queue_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/agency_sdk/test/test_work_queue_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/gts_agency_python_sdk.egg-info/dependency_links.txt +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/gts_agency_python_sdk.egg-info/top_level.txt +0 -0
- {gts_agency_python_sdk-0.0.1rc15 → gts_agency_python_sdk-0.0.2rc1}/setup.cfg +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: gts-agency_python-sdk
|
|
3
|
-
Version: 0.0.
|
|
3
|
+
Version: 0.0.2rc1
|
|
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
|
|
@@ -74,14 +75,14 @@ Access each API domain through the facade:
|
|
|
74
75
|
- `client.dataset()` — datasets CRUD, filesystem traversal, clone
|
|
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()` —
|
|
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
|
|
|
87
88
|
### Rules Example
|
|
@@ -130,6 +131,27 @@ files.download(file_id=file_id, organisation_id=2, target_path="./report.pdf")
|
|
|
130
131
|
See [docs/files_storage_flows.md](docs/files_storage_flows.md) for the full
|
|
131
132
|
upload/download architecture.
|
|
132
133
|
|
|
134
|
+
### Ontology Export Example
|
|
135
|
+
|
|
136
|
+
Agents retrieve a typed JSON snapshot and use its classes, relations, and
|
|
137
|
+
properties to decide how to treat data. Text formats (`turtle`, `shacl`,
|
|
138
|
+
`package`) return `str`; `package-zip` is binary and must go through
|
|
139
|
+
`export_bytes()`.
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
ontology = client.ontology()
|
|
143
|
+
|
|
144
|
+
listed = ontology.list(organisation_id=2)
|
|
145
|
+
ontology_id = next(item.id for item in listed.items if item.name == "claims")
|
|
146
|
+
|
|
147
|
+
snapshot = ontology.export_snapshot(ontology_id=ontology_id, organisation_id=2)
|
|
148
|
+
for entity in snapshot.entities.values():
|
|
149
|
+
print(f"{entity.entity_type}: {entity.label}")
|
|
150
|
+
|
|
151
|
+
turtle = ontology.export(ontology_id=ontology_id, organisation_id=2, export_format="turtle")
|
|
152
|
+
zip_bytes = ontology.export_bytes(ontology_id=ontology_id, organisation_id=2, export_format="package-zip")
|
|
153
|
+
```
|
|
154
|
+
|
|
133
155
|
### Observability Example
|
|
134
156
|
|
|
135
157
|
Opt-in OpenTelemetry tracing + log correlation, shipped to a Langfuse backend and
|
|
@@ -50,14 +50,14 @@ Access each API domain through the facade:
|
|
|
50
50
|
- `client.dataset()` — datasets CRUD, filesystem traversal, clone
|
|
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()` —
|
|
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
63
|
### Rules Example
|
|
@@ -106,6 +106,27 @@ files.download(file_id=file_id, organisation_id=2, target_path="./report.pdf")
|
|
|
106
106
|
See [docs/files_storage_flows.md](docs/files_storage_flows.md) for the full
|
|
107
107
|
upload/download architecture.
|
|
108
108
|
|
|
109
|
+
### Ontology Export Example
|
|
110
|
+
|
|
111
|
+
Agents retrieve a typed JSON snapshot and use its classes, relations, and
|
|
112
|
+
properties to decide how to treat data. Text formats (`turtle`, `shacl`,
|
|
113
|
+
`package`) return `str`; `package-zip` is binary and must go through
|
|
114
|
+
`export_bytes()`.
|
|
115
|
+
|
|
116
|
+
```python
|
|
117
|
+
ontology = client.ontology()
|
|
118
|
+
|
|
119
|
+
listed = ontology.list(organisation_id=2)
|
|
120
|
+
ontology_id = next(item.id for item in listed.items if item.name == "claims")
|
|
121
|
+
|
|
122
|
+
snapshot = ontology.export_snapshot(ontology_id=ontology_id, organisation_id=2)
|
|
123
|
+
for entity in snapshot.entities.values():
|
|
124
|
+
print(f"{entity.entity_type}: {entity.label}")
|
|
125
|
+
|
|
126
|
+
turtle = ontology.export(ontology_id=ontology_id, organisation_id=2, export_format="turtle")
|
|
127
|
+
zip_bytes = ontology.export_bytes(ontology_id=ontology_id, organisation_id=2, export_format="package-zip")
|
|
128
|
+
```
|
|
129
|
+
|
|
109
130
|
### Observability Example
|
|
110
131
|
|
|
111
132
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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)
|