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.
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/PKG-INFO +5 -2
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/README.md +4 -1
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/client.py +5 -0
- gts_agency_python_sdk-0.0.1rc15/agency_sdk/delegates/annotations_client.py +495 -0
- gts_agency_python_sdk-0.0.1rc15/agency_sdk/delegates/annotations_dto.py +200 -0
- gts_agency_python_sdk-0.0.1rc15/agency_sdk/test/test_annotations_client.py +599 -0
- gts_agency_python_sdk-0.0.1rc15/agency_sdk/test/test_annotations_dto.py +299 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_client_facade.py +17 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/gts_agency_python_sdk.egg-info/PKG-INFO +5 -2
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/gts_agency_python_sdk.egg-info/SOURCES.txt +4 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/pyproject.toml +1 -1
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/LICENSE +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/auth_hooks.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/credentials.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/base_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/datasets_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/datasets_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/datasource_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/datasource_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/files_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/files_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/gateway_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/gateway_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/ontology_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/ontology_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/prompts_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/rules_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/rules_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_templates_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_templates_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_vault_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/session_vault_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/work_queue_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/delegates/work_queue_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/domain.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/observability/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/observability/auth.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/observability/bootstrap.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/conftest.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_base_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_credentials.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_files_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_files_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_gateway_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_gateway_facade.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_gateway_openai.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_observability_auth.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_observability_facade_threadsafety.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_observability_langfuse.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_observability_packaging.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_observability_pipeline.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_templates_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_templates_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_vault_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_session_vault_dto.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_stub_requests.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_work_queue_client.py +0 -0
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/agency_sdk/test/test_work_queue_dto.py +0 -0
- {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
- {gts_agency_python_sdk-0.0.1rc13 → gts_agency_python_sdk-0.0.1rc15}/gts_agency_python_sdk.egg-info/requires.txt +0 -0
- {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
- {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.
|
|
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,
|
|
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,
|
|
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))
|