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.
Files changed (95) hide show
  1. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/PKG-INFO +36 -4
  2. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/README.md +33 -3
  3. gts_agency_python_sdk-0.0.2rc3/agency_sdk/adk/__init__.py +43 -0
  4. gts_agency_python_sdk-0.0.2rc3/agency_sdk/adk/_records.py +169 -0
  5. gts_agency_python_sdk-0.0.2rc3/agency_sdk/adk/_store.py +421 -0
  6. gts_agency_python_sdk-0.0.2rc3/agency_sdk/adk/durable.py +404 -0
  7. gts_agency_python_sdk-0.0.2rc3/agency_sdk/adk/errors.py +62 -0
  8. gts_agency_python_sdk-0.0.2rc3/agency_sdk/adk/session_service.py +372 -0
  9. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/client.py +6 -0
  10. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/credentials.py +16 -1
  11. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/base_client.py +14 -5
  12. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/session_client.py +50 -1
  13. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/session_dto.py +20 -0
  14. gts_agency_python_sdk-0.0.2rc3/agency_sdk/delegates/session_hitl_client.py +99 -0
  15. gts_agency_python_sdk-0.0.2rc3/agency_sdk/delegates/session_hitl_dto.py +39 -0
  16. gts_agency_python_sdk-0.0.2rc3/agency_sdk/delegates/session_templates_client.py +114 -0
  17. gts_agency_python_sdk-0.0.2rc3/agency_sdk/delegates/session_vault_client.py +259 -0
  18. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/session_vault_dto.py +18 -1
  19. gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/adk_fakes.py +517 -0
  20. gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/adk_llm_fakes.py +114 -0
  21. gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/adk_proc.py +160 -0
  22. gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_adk_docs.py +92 -0
  23. gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_adk_durable.py +365 -0
  24. gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_adk_hitl.py +360 -0
  25. gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_adk_integration.py +242 -0
  26. gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_adk_phi_sentinel.py +87 -0
  27. gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_adk_session_service.py +450 -0
  28. gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_adk_store.py +412 -0
  29. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_base_client.py +27 -0
  30. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_credentials.py +35 -0
  31. gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_session_hitl_client.py +128 -0
  32. gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_session_lookup_and_register.py +193 -0
  33. gts_agency_python_sdk-0.0.2rc3/agency_sdk/test/test_session_vault_versioned.py +180 -0
  34. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/gts_agency_python_sdk.egg-info/PKG-INFO +36 -4
  35. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/gts_agency_python_sdk.egg-info/SOURCES.txt +21 -0
  36. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/gts_agency_python_sdk.egg-info/requires.txt +3 -0
  37. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/pyproject.toml +12 -1
  38. gts_agency_python_sdk-0.0.2rc2/agency_sdk/delegates/session_templates_client.py +0 -23
  39. gts_agency_python_sdk-0.0.2rc2/agency_sdk/delegates/session_vault_client.py +0 -135
  40. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/LICENSE +0 -0
  41. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/__init__.py +0 -0
  42. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/auth_hooks.py +0 -0
  43. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/__init__.py +0 -0
  44. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/annotations_client.py +0 -0
  45. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/annotations_dto.py +0 -0
  46. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/datasets_client.py +0 -0
  47. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/datasets_dto.py +0 -0
  48. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/datasource_client.py +0 -0
  49. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/datasource_dto.py +0 -0
  50. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/files_client.py +0 -0
  51. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/files_dto.py +0 -0
  52. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/gateway_client.py +0 -0
  53. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/gateway_dto.py +0 -0
  54. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/ontology_client.py +0 -0
  55. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/ontology_dto.py +0 -0
  56. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/prompts_client.py +0 -0
  57. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/rules_client.py +0 -0
  58. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/rules_dto.py +0 -0
  59. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/session_templates_dto.py +0 -0
  60. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/work_queue_client.py +0 -0
  61. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/delegates/work_queue_dto.py +0 -0
  62. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/domain.py +0 -0
  63. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/observability/__init__.py +0 -0
  64. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/observability/auth.py +0 -0
  65. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/observability/bootstrap.py +0 -0
  66. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/__init__.py +0 -0
  67. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/conftest.py +0 -0
  68. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_annotations_client.py +0 -0
  69. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_annotations_dto.py +0 -0
  70. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_client_facade.py +0 -0
  71. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_datasets_client.py +0 -0
  72. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_files_client.py +0 -0
  73. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_files_dto.py +0 -0
  74. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_gateway_dto.py +0 -0
  75. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_gateway_facade.py +0 -0
  76. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_gateway_openai.py +0 -0
  77. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_observability_auth.py +0 -0
  78. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_observability_facade_threadsafety.py +0 -0
  79. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_observability_langfuse.py +0 -0
  80. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_observability_packaging.py +0 -0
  81. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_observability_pipeline.py +0 -0
  82. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_ontology_client.py +0 -0
  83. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_ontology_dto.py +0 -0
  84. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_session_client.py +0 -0
  85. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_session_dto.py +0 -0
  86. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_session_templates_client.py +0 -0
  87. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_session_templates_dto.py +0 -0
  88. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_session_vault_client.py +0 -0
  89. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_session_vault_dto.py +0 -0
  90. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_stub_requests.py +0 -0
  91. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_work_queue_client.py +0 -0
  92. {gts_agency_python_sdk-0.0.2rc2 → gts_agency_python_sdk-0.0.2rc3}/agency_sdk/test/test_work_queue_dto.py +0 -0
  93. {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
  94. {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
  95. {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.2rc2
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 (read-only)
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 (read-only)
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