gts-agency-python-sdk 0.0.2rc2__tar.gz → 0.0.2rc3__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.2rc2 → gts_agency_python_sdk-0.0.2rc3}/PKG-INFO +36 -4
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/README.md +33 -3
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/adk/__init__.py +43 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/adk/_records.py +169 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/adk/_store.py +421 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/adk/durable.py +404 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/adk/errors.py +62 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/adk/session_service.py +372 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/client.py +6 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/credentials.py +16 -1
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/base_client.py +14 -5
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/session_client.py +50 -1
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/session_dto.py +20 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/delegates/session_hitl_client.py +99 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/delegates/session_hitl_dto.py +39 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/delegates/session_templates_client.py +114 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/delegates/session_vault_client.py +259 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/session_vault_dto.py +18 -1
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/adk_fakes.py +517 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/adk_llm_fakes.py +114 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/adk_proc.py +160 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_adk_docs.py +92 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_adk_durable.py +365 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_adk_hitl.py +360 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_adk_integration.py +242 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_adk_phi_sentinel.py +87 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_adk_session_service.py +450 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_adk_store.py +412 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_base_client.py +27 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_credentials.py +35 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_session_hitl_client.py +128 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_session_lookup_and_register.py +193 -0
- gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_session_vault_versioned.py +180 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/gts_agency_python_sdk.egg-info/PKG-INFO +36 -4
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/gts_agency_python_sdk.egg-info/SOURCES.txt +21 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/gts_agency_python_sdk.egg-info/requires.txt +3 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/pyproject.toml +12 -1
- gts_agency_python_sdk-0.0.2rc2/agency_sdk/delegates/session_templates_client.py +0 -23
- gts_agency_python_sdk-0.0.2rc2/agency_sdk/delegates/session_vault_client.py +0 -135
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/LICENSE +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/auth_hooks.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/annotations_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/annotations_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/datasets_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/datasets_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/datasource_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/datasource_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/files_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/files_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/gateway_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/gateway_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/ontology_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/ontology_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/prompts_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/rules_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/rules_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/session_templates_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/work_queue_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/work_queue_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/domain.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/observability/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/observability/auth.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/observability/bootstrap.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/__init__.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/conftest.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_annotations_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_annotations_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_client_facade.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_datasets_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_files_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_files_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_gateway_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_gateway_facade.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_gateway_openai.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_observability_auth.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_observability_facade_threadsafety.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_observability_langfuse.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_observability_packaging.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_observability_pipeline.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_ontology_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_ontology_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_session_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_session_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_session_templates_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_session_templates_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_session_vault_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_session_vault_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_stub_requests.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_work_queue_client.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_work_queue_dto.py +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/gts_agency_python_sdk.egg-info/dependency_links.txt +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/gts_agency_python_sdk.egg-info/top_level.txt +0 -0
- {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/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.2rc3
|
|
4
4
|
Author-email: Ground Control Systems <engineering@groundcontrolsystems.com>
|
|
5
5
|
Requires-Python: >=3.12
|
|
6
6
|
Description-Content-Type: text/markdown
|
|
@@ -14,6 +14,8 @@ Requires-Dist: opentelemetry-sdk>=1.27.0; extra == "observability"
|
|
|
14
14
|
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0; extra == "observability"
|
|
15
15
|
Requires-Dist: opentelemetry-instrumentation-logging>=0.48b0; extra == "observability"
|
|
16
16
|
Requires-Dist: langfuse>=3.8.1; extra == "observability"
|
|
17
|
+
Provides-Extra: adk
|
|
18
|
+
Requires-Dist: google-adk<3,>=2.11; extra == "adk"
|
|
17
19
|
Provides-Extra: dev
|
|
18
20
|
Requires-Dist: mypy==1.4.1; extra == "dev"
|
|
19
21
|
Requires-Dist: pytest==7.4.0; extra == "dev"
|
|
@@ -45,6 +47,12 @@ Optional OpenTelemetry tracing support (Langfuse backend):
|
|
|
45
47
|
pip install gts-agency-python-sdk[observability]
|
|
46
48
|
```
|
|
47
49
|
|
|
50
|
+
Optional Google ADK 2 support (durable agent sessions on the GTS session vault):
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
pip install gts-agency-python-sdk[adk]
|
|
54
|
+
```
|
|
55
|
+
|
|
48
56
|
## Configuration
|
|
49
57
|
|
|
50
58
|
The examples in this repository use the following environment variables for authentication and configuration:
|
|
@@ -78,13 +86,37 @@ Access each API domain through the facade:
|
|
|
78
86
|
- `client.ontology()` — list ontologies (name → id, optional `kind` filter), export (JSON snapshot, Turtle/OWL, SHACL, package, package-zip), and entity-datasource mappings
|
|
79
87
|
- `client.prompts()` — prompt CRUD via command pattern
|
|
80
88
|
- `client.rules()` — rule listing, detail, execution, and execution history
|
|
81
|
-
- `client.session_vault()` — session-scoped key/value vault for agent state (classification-based encryption, audited reveal)
|
|
89
|
+
- `client.session_vault()` — session-scoped key/value vault for agent state (classification-based encryption, audited reveal); per-key `version`, conditional writes (`if_version` / `if_absent` → `ConditionalWriteFailed`), `prefix` listing and `scope="app"|"user"`
|
|
82
90
|
- `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)
|
|
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`)
|
|
84
|
-
- `client.session_templates()` — list session templates to resolve a template name → id (
|
|
91
|
+
- `client.sessions()` — report progress on a dispatched control-plane session: `attach` to the inherited session then `update` its status/result/events/metrics/labels; also `find_by_correlation_id` and label `search` (the agent inherits the session, never self-registers — no `register`)
|
|
92
|
+
- `client.session_templates()` — list session templates to resolve a template name → id, and `register` a session from a template by name (with labels and an owner claim)
|
|
93
|
+
- `client.session_hitl()` — human-input requests: the agent creates/lists them; a client built with a human's own token `respond`s (first answer wins, service principals refused)
|
|
85
94
|
- `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))
|
|
86
95
|
- `client.gateway(org_id=..., gateway_base_url=...)` — OpenAI-compatible LLM calls routed through the org's agentgateway (shared credentials + `x-org` routing header)
|
|
87
96
|
|
|
97
|
+
### Google ADK 2: `GtsSessionService` quick-start
|
|
98
|
+
|
|
99
|
+
Swap `InMemorySessionService` for the GTS-backed service — a configuration change only — and sessions
|
|
100
|
+
survive restarts and move between workers. `DurableRunner` adds resume-by-correlation-id and human
|
|
101
|
+
input answered in comand. Full guide: [docs/adk_sessions.md](docs/adk_sessions.md).
|
|
102
|
+
|
|
103
|
+
<!-- adk-quickstart -->
|
|
104
|
+
```python
|
|
105
|
+
from google.adk.runners import Runner
|
|
106
|
+
|
|
107
|
+
from agency_sdk.adk import DurableRunner, GtsSessionService
|
|
108
|
+
|
|
109
|
+
session_service = GtsSessionService.from_client(client, organisation_id=2, template_name="adk-agent")
|
|
110
|
+
runner = Runner(app=app, session_service=session_service) # was: InMemorySessionService()
|
|
111
|
+
|
|
112
|
+
# Durable runs (the app needs ResumabilityConfig(is_resumable=True)):
|
|
113
|
+
durable = DurableRunner(app=app, session_service=session_service, hitl=client.session_hitl())
|
|
114
|
+
outcome = await durable.run("a-high-entropy-correlation-id", user_id="user-1", message="Review case 42")
|
|
115
|
+
if outcome.status == "awaiting_input":
|
|
116
|
+
# A reviewer answers in comand; a re-dispatched worker later continues the same run:
|
|
117
|
+
outcome = await durable.resume("a-high-entropy-correlation-id", user_id="user-1")
|
|
118
|
+
```
|
|
119
|
+
|
|
88
120
|
### Dataset Write Example
|
|
89
121
|
|
|
90
122
|
`clone_dataset` writes an `.agency/` workspace. `push` uploads the tree's diff against it into the
|
|
@@ -20,6 +20,12 @@ Optional OpenTelemetry tracing support (Langfuse backend):
|
|
|
20
20
|
pip install gts-agency-python-sdk[observability]
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
+
Optional Google ADK 2 support (durable agent sessions on the GTS session vault):
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
pip install gts-agency-python-sdk[adk]
|
|
27
|
+
```
|
|
28
|
+
|
|
23
29
|
## Configuration
|
|
24
30
|
|
|
25
31
|
The examples in this repository use the following environment variables for authentication and configuration:
|
|
@@ -53,13 +59,37 @@ Access each API domain through the facade:
|
|
|
53
59
|
- `client.ontology()` — list ontologies (name → id, optional `kind` filter), export (JSON snapshot, Turtle/OWL, SHACL, package, package-zip), and entity-datasource mappings
|
|
54
60
|
- `client.prompts()` — prompt CRUD via command pattern
|
|
55
61
|
- `client.rules()` — rule listing, detail, execution, and execution history
|
|
56
|
-
- `client.session_vault()` — session-scoped key/value vault for agent state (classification-based encryption, audited reveal)
|
|
62
|
+
- `client.session_vault()` — session-scoped key/value vault for agent state (classification-based encryption, audited reveal); per-key `version`, conditional writes (`if_version` / `if_absent` → `ConditionalWriteFailed`), `prefix` listing and `scope="app"|"user"`
|
|
57
63
|
- `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
|
-
- `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 (
|
|
64
|
+
- `client.sessions()` — report progress on a dispatched control-plane session: `attach` to the inherited session then `update` its status/result/events/metrics/labels; also `find_by_correlation_id` and label `search` (the agent inherits the session, never self-registers — no `register`)
|
|
65
|
+
- `client.session_templates()` — list session templates to resolve a template name → id, and `register` a session from a template by name (with labels and an owner claim)
|
|
66
|
+
- `client.session_hitl()` — human-input requests: the agent creates/lists them; a client built with a human's own token `respond`s (first answer wins, service principals refused)
|
|
60
67
|
- `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
68
|
- `client.gateway(org_id=..., gateway_base_url=...)` — OpenAI-compatible LLM calls routed through the org's agentgateway (shared credentials + `x-org` routing header)
|
|
62
69
|
|
|
70
|
+
### Google ADK 2: `GtsSessionService` quick-start
|
|
71
|
+
|
|
72
|
+
Swap `InMemorySessionService` for the GTS-backed service — a configuration change only — and sessions
|
|
73
|
+
survive restarts and move between workers. `DurableRunner` adds resume-by-correlation-id and human
|
|
74
|
+
input answered in comand. Full guide: [docs/adk_sessions.md](docs/adk_sessions.md).
|
|
75
|
+
|
|
76
|
+
<!-- adk-quickstart -->
|
|
77
|
+
```python
|
|
78
|
+
from google.adk.runners import Runner
|
|
79
|
+
|
|
80
|
+
from agency_sdk.adk import DurableRunner, GtsSessionService
|
|
81
|
+
|
|
82
|
+
session_service = GtsSessionService.from_client(client, organisation_id=2, template_name="adk-agent")
|
|
83
|
+
runner = Runner(app=app, session_service=session_service) # was: InMemorySessionService()
|
|
84
|
+
|
|
85
|
+
# Durable runs (the app needs ResumabilityConfig(is_resumable=True)):
|
|
86
|
+
durable = DurableRunner(app=app, session_service=session_service, hitl=client.session_hitl())
|
|
87
|
+
outcome = await durable.run("a-high-entropy-correlation-id", user_id="user-1", message="Review case 42")
|
|
88
|
+
if outcome.status == "awaiting_input":
|
|
89
|
+
# A reviewer answers in comand; a re-dispatched worker later continues the same run:
|
|
90
|
+
outcome = await durable.resume("a-high-entropy-correlation-id", user_id="user-1")
|
|
91
|
+
```
|
|
92
|
+
|
|
63
93
|
### Dataset Write Example
|
|
64
94
|
|
|
65
95
|
`clone_dataset` writes an `.agency/` workspace. `push` uploads the tree's diff against it into the
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
"""Google ADK 2 support: durable agent sessions backed by the GTS session vault.
|
|
2
|
+
|
|
3
|
+
``GtsSessionService`` is an ADK ``BaseSessionService`` that persists every session in its GTS session
|
|
4
|
+
vault, so it survives restarts and moves between workers; ``DurableRunner`` adds correlation-id resume
|
|
5
|
+
and pauses for a human answer recorded in comand. Both build on ADK's own resumability rather than
|
|
6
|
+
replacing it. Design and backend contract: ``docs/agent_vault_gap_analysis.md``.
|
|
7
|
+
|
|
8
|
+
Requires the optional extra::
|
|
9
|
+
|
|
10
|
+
pip install gts-agency-python-sdk[adk]
|
|
11
|
+
|
|
12
|
+
``import agency_sdk`` never imports this package (or ADK); only importing ``agency_sdk.adk`` does.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
_INSTALL_HINT = (
|
|
16
|
+
"ADK session support requires the optional dependency group. Install it with:\n"
|
|
17
|
+
" pip install gts-agency-python-sdk[adk]"
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class AdkNotInstalled(ImportError):
|
|
22
|
+
"""Raised when ``agency_sdk.adk`` is imported without the ``[adk]`` extra."""
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
try:
|
|
26
|
+
import google.adk # noqa: F401
|
|
27
|
+
except ImportError as exc: # pragma: no cover - exercised in a subprocess without the extra
|
|
28
|
+
raise AdkNotInstalled(_INSTALL_HINT) from exc
|
|
29
|
+
|
|
30
|
+
from agency_sdk.adk import errors # noqa: E402
|
|
31
|
+
from agency_sdk.adk._store import VaultLimits # noqa: E402
|
|
32
|
+
from agency_sdk.adk.session_service import GtsSessionService, register_gts_session_service # noqa: E402
|
|
33
|
+
from agency_sdk.adk.durable import DurableRunner, RunOutcome # noqa: E402
|
|
34
|
+
|
|
35
|
+
__all__ = [
|
|
36
|
+
"AdkNotInstalled",
|
|
37
|
+
"DurableRunner",
|
|
38
|
+
"RunOutcome",
|
|
39
|
+
"GtsSessionService",
|
|
40
|
+
"VaultLimits",
|
|
41
|
+
"errors",
|
|
42
|
+
"register_gts_session_service",
|
|
43
|
+
]
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
"""Vault key scheme and record codec for ADK sessions (design §Data Architecture).
|
|
2
|
+
|
|
3
|
+
One ADK session is one GTS session; its vault holds:
|
|
4
|
+
|
|
5
|
+
- ``adk.session`` — the **head**: identity, ``revision``, ``event_count``, ``last_event_key`` and the
|
|
6
|
+
session-scoped state. Conditional writes on the head are the only commit point.
|
|
7
|
+
- ``adk.ev.<seq:08d>.<event_id>`` — one immutable record per event, linked to its predecessor by
|
|
8
|
+
``prev_key``. An event is invisible until a head names it, so a CAS loser's event is an unreachable
|
|
9
|
+
orphan rather than corruption.
|
|
10
|
+
- ``adk.failure`` — a write-once failure summary with no payloads.
|
|
11
|
+
- ``adk.state`` under ``scope=app|user`` — ADK ``app:``/``user:`` state, resolved by comand.
|
|
12
|
+
|
|
13
|
+
Events are encoded with ``model_dump_json(by_alias=True)`` (no ``exclude_none``) and decoded with
|
|
14
|
+
``model_validate_json``: ADK's ``val_json_bytes='base64'`` applies only in JSON mode, so validating the
|
|
15
|
+
decoded dict instead would corrupt ``inline_data`` bytes.
|
|
16
|
+
|
|
17
|
+
Records override ``repr``/``str`` so state, ``user_id`` and event content never reach a log by accident.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
from __future__ import annotations
|
|
21
|
+
|
|
22
|
+
import hashlib
|
|
23
|
+
import json
|
|
24
|
+
import time
|
|
25
|
+
from typing import Any
|
|
26
|
+
|
|
27
|
+
from google.adk.events import Event
|
|
28
|
+
from pydantic import BaseModel, ConfigDict, Field, ValidationError
|
|
29
|
+
from pydantic_core import PydanticSerializationError
|
|
30
|
+
|
|
31
|
+
from agency_sdk.adk.errors import CorruptRecord, InvalidState, UnsupportedSchema
|
|
32
|
+
|
|
33
|
+
#: Highest record schema this SDK writes and understands.
|
|
34
|
+
SCHEMA_VERSION = 1
|
|
35
|
+
|
|
36
|
+
HEAD_KEY = "adk.session"
|
|
37
|
+
EVENT_PREFIX = "adk.ev."
|
|
38
|
+
FAILURE_KEY = "adk.failure"
|
|
39
|
+
STATE_KEY = "adk.state"
|
|
40
|
+
|
|
41
|
+
_KEY_CHARS = frozenset("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_.")
|
|
42
|
+
_MAX_ID_IN_KEY = 200
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def event_key(seq: int, event_id: str) -> str:
|
|
46
|
+
"""The vault key of event number ``seq`` (1-based).
|
|
47
|
+
|
|
48
|
+
Zero-padding keeps keys in sequence order under the server's lexicographic listing. An id outside
|
|
49
|
+
the key charset (or too long) is replaced by its SHA-256 so the key stays valid and unique.
|
|
50
|
+
"""
|
|
51
|
+
if not event_id or len(event_id) > _MAX_ID_IN_KEY or not set(event_id) <= _KEY_CHARS:
|
|
52
|
+
event_id = hashlib.sha256(event_id.encode()).hexdigest()
|
|
53
|
+
return f"{EVENT_PREFIX}{seq:08d}.{event_id}"
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
class _Record(BaseModel):
|
|
57
|
+
model_config = ConfigDict(populate_by_name=True, extra="ignore")
|
|
58
|
+
|
|
59
|
+
def _safe_fields(self) -> str:
|
|
60
|
+
return ""
|
|
61
|
+
|
|
62
|
+
def __repr__(self) -> str:
|
|
63
|
+
return f"{type(self).__name__}({self._safe_fields()})"
|
|
64
|
+
|
|
65
|
+
def __str__(self) -> str:
|
|
66
|
+
return repr(self)
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
class SessionHead(_Record):
|
|
70
|
+
"""The session head (``adk.session``). ``user_id`` is PII and ``state`` is PHI-capable."""
|
|
71
|
+
|
|
72
|
+
schema_version: int = Field(default=SCHEMA_VERSION, alias="schema")
|
|
73
|
+
app_name: str
|
|
74
|
+
user_id: str
|
|
75
|
+
correlation_id: str | None = None
|
|
76
|
+
revision: int = 0
|
|
77
|
+
event_count: int = 0
|
|
78
|
+
last_event_key: str | None = None
|
|
79
|
+
last_update_time: float
|
|
80
|
+
state: dict[str, Any] = Field(default_factory=dict)
|
|
81
|
+
#: Set by ``delete_session``: a tombstone, so history is kept for forensics but reads return ``None``.
|
|
82
|
+
deleted: bool = False
|
|
83
|
+
|
|
84
|
+
def _safe_fields(self) -> str:
|
|
85
|
+
return f"revision={self.revision}, event_count={self.event_count}, deleted={self.deleted}"
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
class EventRecord(_Record):
|
|
89
|
+
"""One stored event (``adk.ev.*``)."""
|
|
90
|
+
|
|
91
|
+
seq: int
|
|
92
|
+
prev_key: str | None
|
|
93
|
+
event: dict[str, Any]
|
|
94
|
+
|
|
95
|
+
def _safe_fields(self) -> str:
|
|
96
|
+
return f"seq={self.seq}"
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
class FailureRecord(_Record):
|
|
100
|
+
"""A PHI-free failure summary (``adk.failure``): the exception *type* only, never its message."""
|
|
101
|
+
|
|
102
|
+
error_type: str
|
|
103
|
+
invocation_id: str | None = None
|
|
104
|
+
last_event_key: str | None = None
|
|
105
|
+
revision: int
|
|
106
|
+
at: float = Field(default_factory=time.time)
|
|
107
|
+
|
|
108
|
+
def _safe_fields(self) -> str:
|
|
109
|
+
return f"error_type={self.error_type!r}, revision={self.revision}"
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def to_wire(record: _Record) -> dict[str, Any]:
|
|
113
|
+
"""Serialise a record to the JSON value stored in the vault.
|
|
114
|
+
|
|
115
|
+
Raises:
|
|
116
|
+
InvalidState: The record holds a value that is not JSON-native (for example in session state).
|
|
117
|
+
"""
|
|
118
|
+
try:
|
|
119
|
+
value: dict[str, Any] = json.loads(record.model_dump_json(by_alias=True))
|
|
120
|
+
except PydanticSerializationError:
|
|
121
|
+
raise InvalidState(f"{type(record).__name__} holds a value that is not JSON-serialisable") from None
|
|
122
|
+
return value
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def encode_event(event: Event) -> dict[str, Any]:
|
|
126
|
+
"""Encode an ADK event for storage (JSON mode, by alias, ``None`` fields kept)."""
|
|
127
|
+
value: dict[str, Any] = json.loads(event.model_dump_json(by_alias=True))
|
|
128
|
+
return value
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def decode_event(value: Any) -> Event:
|
|
132
|
+
"""Decode a stored event; any malformed payload is a :class:`CorruptRecord`."""
|
|
133
|
+
try:
|
|
134
|
+
return Event.model_validate_json(json.dumps(value))
|
|
135
|
+
except (ValidationError, TypeError, ValueError) as exc:
|
|
136
|
+
raise CorruptRecord(f"stored event is malformed ({type(exc).__name__})") from None
|
|
137
|
+
|
|
138
|
+
|
|
139
|
+
def _check_schema(value: Any, kind: str) -> dict[str, Any]:
|
|
140
|
+
if not isinstance(value, dict):
|
|
141
|
+
raise CorruptRecord(f"stored {kind} is not an object")
|
|
142
|
+
schema = value.get("schema", SCHEMA_VERSION)
|
|
143
|
+
if isinstance(schema, int) and schema > SCHEMA_VERSION:
|
|
144
|
+
raise UnsupportedSchema(f"stored {kind} uses schema {schema}; this SDK understands up to {SCHEMA_VERSION}")
|
|
145
|
+
return value
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def decode_head(value: Any) -> SessionHead:
|
|
149
|
+
try:
|
|
150
|
+
record: SessionHead = SessionHead.model_validate(_check_schema(value, "session head"))
|
|
151
|
+
return record
|
|
152
|
+
except ValidationError as exc:
|
|
153
|
+
raise CorruptRecord(f"stored session head is malformed ({exc.error_count()} errors)") from None
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def decode_event_record(value: Any) -> EventRecord:
|
|
157
|
+
try:
|
|
158
|
+
record: EventRecord = EventRecord.model_validate(_check_schema(value, "event record"))
|
|
159
|
+
return record
|
|
160
|
+
except ValidationError as exc:
|
|
161
|
+
raise CorruptRecord(f"stored event record is malformed ({exc.error_count()} errors)") from None
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
def decode_failure(value: Any) -> FailureRecord:
|
|
165
|
+
try:
|
|
166
|
+
record: FailureRecord = FailureRecord.model_validate(_check_schema(value, "failure record"))
|
|
167
|
+
return record
|
|
168
|
+
except ValidationError as exc:
|
|
169
|
+
raise CorruptRecord(f"stored failure record is malformed ({exc.error_count()} errors)") from None
|