gts-agency-python-sdk 0.0.1__py3-none-any.whl

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 (66) hide show
  1. agency_sdk/__init__.py +0 -0
  2. agency_sdk/auth_hooks.py +55 -0
  3. agency_sdk/client.py +212 -0
  4. agency_sdk/credentials.py +54 -0
  5. agency_sdk/delegates/__init__.py +0 -0
  6. agency_sdk/delegates/annotations_client.py +495 -0
  7. agency_sdk/delegates/annotations_dto.py +200 -0
  8. agency_sdk/delegates/base_client.py +126 -0
  9. agency_sdk/delegates/datasets_client.py +109 -0
  10. agency_sdk/delegates/datasets_dto.py +81 -0
  11. agency_sdk/delegates/datasource_client.py +44 -0
  12. agency_sdk/delegates/datasource_dto.py +107 -0
  13. agency_sdk/delegates/files_client.py +184 -0
  14. agency_sdk/delegates/files_dto.py +36 -0
  15. agency_sdk/delegates/gateway_client.py +81 -0
  16. agency_sdk/delegates/gateway_dto.py +37 -0
  17. agency_sdk/delegates/ontology_client.py +203 -0
  18. agency_sdk/delegates/ontology_dto.py +221 -0
  19. agency_sdk/delegates/prompts_client.py +56 -0
  20. agency_sdk/delegates/rules_client.py +33 -0
  21. agency_sdk/delegates/rules_dto.py +108 -0
  22. agency_sdk/delegates/session_client.py +95 -0
  23. agency_sdk/delegates/session_dto.py +94 -0
  24. agency_sdk/delegates/session_templates_client.py +23 -0
  25. agency_sdk/delegates/session_templates_dto.py +27 -0
  26. agency_sdk/delegates/session_vault_client.py +135 -0
  27. agency_sdk/delegates/session_vault_dto.py +75 -0
  28. agency_sdk/delegates/work_queue_client.py +230 -0
  29. agency_sdk/delegates/work_queue_dto.py +127 -0
  30. agency_sdk/domain.py +140 -0
  31. agency_sdk/observability/__init__.py +60 -0
  32. agency_sdk/observability/auth.py +15 -0
  33. agency_sdk/observability/bootstrap.py +344 -0
  34. agency_sdk/test/__init__.py +0 -0
  35. agency_sdk/test/conftest.py +106 -0
  36. agency_sdk/test/test_annotations_client.py +599 -0
  37. agency_sdk/test/test_annotations_dto.py +299 -0
  38. agency_sdk/test/test_base_client.py +153 -0
  39. agency_sdk/test/test_client_facade.py +105 -0
  40. agency_sdk/test/test_credentials.py +67 -0
  41. agency_sdk/test/test_files_client.py +264 -0
  42. agency_sdk/test/test_files_dto.py +93 -0
  43. agency_sdk/test/test_gateway_dto.py +70 -0
  44. agency_sdk/test/test_gateway_facade.py +229 -0
  45. agency_sdk/test/test_gateway_openai.py +76 -0
  46. agency_sdk/test/test_observability_auth.py +125 -0
  47. agency_sdk/test/test_observability_facade_threadsafety.py +50 -0
  48. agency_sdk/test/test_observability_langfuse.py +76 -0
  49. agency_sdk/test/test_observability_packaging.py +78 -0
  50. agency_sdk/test/test_observability_pipeline.py +246 -0
  51. agency_sdk/test/test_ontology_client.py +152 -0
  52. agency_sdk/test/test_ontology_dto.py +158 -0
  53. agency_sdk/test/test_session_client.py +128 -0
  54. agency_sdk/test/test_session_dto.py +75 -0
  55. agency_sdk/test/test_session_templates_client.py +36 -0
  56. agency_sdk/test/test_session_templates_dto.py +45 -0
  57. agency_sdk/test/test_session_vault_client.py +151 -0
  58. agency_sdk/test/test_session_vault_dto.py +27 -0
  59. agency_sdk/test/test_stub_requests.py +39 -0
  60. agency_sdk/test/test_work_queue_client.py +388 -0
  61. agency_sdk/test/test_work_queue_dto.py +233 -0
  62. gts_agency_python_sdk-0.0.1.dist-info/METADATA +221 -0
  63. gts_agency_python_sdk-0.0.1.dist-info/RECORD +66 -0
  64. gts_agency_python_sdk-0.0.1.dist-info/WHEEL +5 -0
  65. gts_agency_python_sdk-0.0.1.dist-info/licenses/LICENSE +201 -0
  66. gts_agency_python_sdk-0.0.1.dist-info/top_level.txt +1 -0
@@ -0,0 +1,299 @@
1
+ """DTO tests for the annotations delegate (graph batches → annotator jobs).
2
+
3
+ JSON transcribed from the gts-comand models (`crates/comand/src/model/annotation.rs`):
4
+ the server serialises every field, so nulls arrive explicitly rather than being
5
+ omitted, and `AnnotationBatchResponse` flattens the batch alongside `viewer_role`.
6
+ """
7
+
8
+ from agency_sdk.delegates.annotations_dto import (
9
+ BATCH_TYPE_GRAPH,
10
+ DEFAULT_JOB_TYPE,
11
+ DEFAULT_TARGET_CLASS,
12
+ AnnotationBatch,
13
+ AnnotationBatchesPagedResult,
14
+ AnnotationBatchResponse,
15
+ AnnotationSpec,
16
+ AnnotationSpecsPagedResult,
17
+ AnnotationWorkflow,
18
+ AnnotationWorkflowsPagedResult,
19
+ BatchStatus,
20
+ BindWorkflowResult,
21
+ CreateBatchResult,
22
+ CreateSpecResult,
23
+ PushGraphResult,
24
+ SpecStatus,
25
+ )
26
+
27
+ #: A batch straight after `create` — DRAFT, no jobs, graph subtype fields still null.
28
+ DRAFT_BATCH_JSON = {
29
+ "id": "7f1d9c62-1f2a-4a51-9a1e-2d0c3f5b8e40",
30
+ "organisation_id": 2,
31
+ "name": "MTUS Knee 2026",
32
+ "description": None,
33
+ "instructions": None,
34
+ "batch_type": "graph",
35
+ "graph_uri": None,
36
+ "graph_run_id": None,
37
+ "target_class": None,
38
+ "context_hops": None,
39
+ "total_jobs": 0,
40
+ "completed_jobs": 0,
41
+ "status": 0,
42
+ "confidentiality_level": "INTERNAL",
43
+ "audit_data": {
44
+ "created_on": "2026-08-03 09:15:00Z",
45
+ "created_by": "901",
46
+ "modified_on": "2026-08-03 09:15:00Z",
47
+ "modified_by": "901",
48
+ },
49
+ }
50
+
51
+ #: The same batch after `upload` — ACTIVE, jobs materialised, subtype fields hydrated.
52
+ ACTIVE_BATCH_JSON = {
53
+ **DRAFT_BATCH_JSON,
54
+ "description": "MTUS knee guideline rules, 2026 revision",
55
+ "instructions": "Confirm each rule against the source PDF page.",
56
+ "graph_uri": "2/annotations/7f1d9c62-1f2a-4a51-9a1e-2d0c3f5b8e40/graph.json",
57
+ "graph_run_id": "run-2026-08-03-a",
58
+ "target_class": "rule",
59
+ "context_hops": 1,
60
+ "total_jobs": 325,
61
+ "status": 1,
62
+ }
63
+
64
+ SPEC_JSON = {
65
+ "id": "3b0e4d11-77c8-4a0b-9f3d-19c2b7d6a015",
66
+ "organisation_id": 2,
67
+ "code": "rule_validation",
68
+ "name": "Rule validation",
69
+ "instructions": "Check the rule text, its evidence level, and its page reference.",
70
+ "checklist": [
71
+ {"id": "text_matches_source", "label": "Rule text matches the source"},
72
+ {"id": "page_reference_correct", "label": "Page reference is correct"},
73
+ ],
74
+ "status": 1,
75
+ "audit_data": {"created_on": "2026-08-03 09:00:00Z", "created_by": "901"},
76
+ }
77
+
78
+
79
+ def test_annotation_batch_deserialises_a_draft_batch():
80
+ batch = AnnotationBatch(**DRAFT_BATCH_JSON)
81
+
82
+ assert batch.id == "7f1d9c62-1f2a-4a51-9a1e-2d0c3f5b8e40"
83
+ assert batch.organisation_id == 2
84
+ assert batch.name == "MTUS Knee 2026"
85
+ assert batch.batch_type == BATCH_TYPE_GRAPH
86
+ assert batch.status == BatchStatus.DRAFT
87
+ assert batch.total_jobs == 0
88
+ assert batch.completed_jobs == 0
89
+ assert batch.confidentiality_level == "INTERNAL"
90
+ assert batch.audit_data == DRAFT_BATCH_JSON["audit_data"]
91
+
92
+
93
+ def test_annotation_batch_tolerates_explicit_nulls_and_missing_optionals():
94
+ from_nulls = AnnotationBatch(**DRAFT_BATCH_JSON)
95
+ from_omitted = AnnotationBatch(
96
+ id="x",
97
+ organisation_id=2,
98
+ name="n",
99
+ batch_type="graph",
100
+ total_jobs=0,
101
+ completed_jobs=0,
102
+ status=0,
103
+ confidentiality_level="INTERNAL",
104
+ )
105
+
106
+ for batch in (from_nulls, from_omitted):
107
+ assert batch.description is None
108
+ assert batch.instructions is None
109
+ assert batch.graph_uri is None
110
+ assert batch.graph_run_id is None
111
+ assert batch.target_class is None
112
+ assert batch.context_hops is None
113
+ assert from_omitted.audit_data is None
114
+
115
+
116
+ def test_annotation_batch_carries_graph_subtype_fields_once_uploaded():
117
+ batch = AnnotationBatch(**ACTIVE_BATCH_JSON)
118
+
119
+ assert batch.status == BatchStatus.ACTIVE
120
+ assert batch.total_jobs == 325
121
+ assert batch.graph_uri == "2/annotations/7f1d9c62-1f2a-4a51-9a1e-2d0c3f5b8e40/graph.json"
122
+ assert batch.graph_run_id == "run-2026-08-03-a"
123
+ assert batch.target_class == DEFAULT_TARGET_CLASS
124
+ assert batch.context_hops == 1
125
+
126
+
127
+ def test_annotation_batch_response_flattens_the_batch_beside_viewer_role():
128
+ response = AnnotationBatchResponse(**{**ACTIVE_BATCH_JSON, "viewer_role": "admin"})
129
+
130
+ assert response.viewer_role == "admin"
131
+ assert response.id == ACTIVE_BATCH_JSON["id"]
132
+ assert response.total_jobs == 325
133
+ assert response.status == BatchStatus.ACTIVE
134
+
135
+
136
+ def test_annotation_batch_response_viewer_role_defaults_to_none():
137
+ response = AnnotationBatchResponse(**ACTIVE_BATCH_JSON)
138
+
139
+ assert response.viewer_role is None
140
+
141
+
142
+ def test_annotation_batches_paged_result_wraps_page_and_items():
143
+ result = AnnotationBatchesPagedResult(
144
+ **{"page": {"page": 0, "size": 10, "total": 2}, "items": [DRAFT_BATCH_JSON, ACTIVE_BATCH_JSON]}
145
+ )
146
+
147
+ assert result.page.total == 2
148
+ assert [b.status for b in result.items] == [BatchStatus.DRAFT, BatchStatus.ACTIVE]
149
+
150
+
151
+ def test_create_batch_result_carries_the_envelope_and_the_lifted_id():
152
+ result = CreateBatchResult(success=True, message="Batch created: 7f1d9c62", id="7f1d9c62")
153
+
154
+ assert result.success is True
155
+ assert result.message == "Batch created: 7f1d9c62"
156
+ assert result.id == "7f1d9c62"
157
+
158
+
159
+ def test_create_spec_result_is_its_own_type_with_the_same_envelope():
160
+ result = CreateSpecResult(success=True, message="Specification created: 3b0e4d11", id="3b0e4d11")
161
+
162
+ assert result.id == "3b0e4d11"
163
+ assert not isinstance(result, CreateBatchResult)
164
+
165
+
166
+ def test_push_graph_result_reports_the_read_back_job_count():
167
+ batch = AnnotationBatchResponse(**ACTIVE_BATCH_JSON)
168
+ result = PushGraphResult(batch_id=batch.id, total_jobs=batch.total_jobs, status=batch.status, batch=batch)
169
+
170
+ assert result.batch_id == ACTIVE_BATCH_JSON["id"]
171
+ assert result.total_jobs == 325
172
+ assert result.status == BatchStatus.ACTIVE
173
+ assert result.batch.graph_run_id == "run-2026-08-03-a"
174
+
175
+
176
+ def test_annotation_spec_deserialises_with_its_checklist():
177
+ spec = AnnotationSpec(**SPEC_JSON)
178
+
179
+ assert spec.code == DEFAULT_JOB_TYPE
180
+ assert spec.name == "Rule validation"
181
+ assert spec.status == SpecStatus.ACTIVE
182
+ assert [item["id"] for item in spec.checklist] == ["text_matches_source", "page_reference_correct"]
183
+
184
+
185
+ def test_annotation_spec_optional_fields_default_to_none():
186
+ spec = AnnotationSpec(id="x", organisation_id=2, code="c", name="n", checklist=[], status=0)
187
+
188
+ assert spec.instructions is None
189
+ assert spec.audit_data is None
190
+ assert spec.status == SpecStatus.DRAFT
191
+
192
+
193
+ def test_annotation_specs_paged_result_wraps_page_and_items():
194
+ result = AnnotationSpecsPagedResult(**{"page": {"page": 0, "size": 10, "total": 1}, "items": [SPEC_JSON]})
195
+
196
+ assert result.page.total == 1
197
+ assert [s.code for s in result.items] == ["rule_validation"]
198
+
199
+
200
+ def test_status_enums_match_the_server_constants():
201
+ assert (BatchStatus.DRAFT, BatchStatus.ACTIVE, BatchStatus.COMPLETED, BatchStatus.ARCHIVED) == (0, 1, 2, 3)
202
+ assert (SpecStatus.DRAFT, SpecStatus.ACTIVE, SpecStatus.ARCHIVED) == (0, 1, 2)
203
+
204
+
205
+ def test_module_constants_document_the_server_defaults():
206
+ assert (BATCH_TYPE_GRAPH, DEFAULT_JOB_TYPE, DEFAULT_TARGET_CLASS) == ("graph", "rule_validation", "rule")
207
+
208
+
209
+ #: A batch as the control plane returns it since the job-counter split (gts-comand eda4f9ca):
210
+ #: `completed_jobs` is gone, replaced by resolved/accepted/rejected. Transcribed from a live
211
+ #: `GET /api/annotations/{id}?o=2`.
212
+ SPLIT_COUNTER_BATCH_JSON = {
213
+ "id": "7324f779-3e61-418e-be3b-2a3faf296a27",
214
+ "organisation_id": 2,
215
+ "name": "DBQ: Knee and Lower Leg — source_text verification",
216
+ "description": "Rebuilt from archived run xval17 with the current producer.",
217
+ "instructions": None,
218
+ "batch_type": "graph",
219
+ "graph_uri": "2/annotations/7324f779-3e61-418e-be3b-2a3faf296a27/graph.json",
220
+ "graph_run_id": "ac4-source-text-probe",
221
+ "target_class": "rule",
222
+ "context_hops": 1,
223
+ "total_jobs": 14,
224
+ "resolved_jobs": 3,
225
+ "accepted_jobs": 2,
226
+ "rejected_jobs": 1,
227
+ "status": 1,
228
+ "confidentiality_level": "INTERNAL",
229
+ "audit_data": {"created_on": "2026-08-21 10:00:00Z", "created_by": "901"},
230
+ }
231
+
232
+ WORKFLOW_JSON = {
233
+ "id": "sys-wf-graph-2",
234
+ "code": "graph_two_step",
235
+ "name": "Graph two-step review",
236
+ "description": "One person annotates, a different person approves.",
237
+ "target_batch_type": "graph",
238
+ "is_system": True,
239
+ "status": "active",
240
+ "current_published_version_id": "sys-wfv-graph-2",
241
+ "draft_version_id": None,
242
+ }
243
+
244
+
245
+ def test_batch_parses_the_split_job_counters():
246
+ batch = AnnotationBatch(**SPLIT_COUNTER_BATCH_JSON)
247
+
248
+ assert batch.total_jobs == 14
249
+ assert batch.resolved_jobs == 3
250
+ assert batch.accepted_jobs == 2
251
+ assert batch.rejected_jobs == 1
252
+ # The pre-split counter simply is not sent any more; it must not be required.
253
+ assert batch.completed_jobs is None
254
+
255
+
256
+ def test_batch_still_parses_a_pre_split_server_payload():
257
+ # One model has to cover both server generations: older control planes send
258
+ # completed_jobs and none of the three new counters.
259
+ batch = AnnotationBatch(**ACTIVE_BATCH_JSON)
260
+
261
+ assert batch.completed_jobs == 0
262
+ assert batch.resolved_jobs is None
263
+ assert batch.accepted_jobs is None
264
+ assert batch.rejected_jobs is None
265
+
266
+
267
+ def test_batch_response_parses_the_live_single_read():
268
+ response = AnnotationBatchResponse(**{**SPLIT_COUNTER_BATCH_JSON, "viewer_role": "admin"})
269
+
270
+ assert response.viewer_role == "admin"
271
+ assert response.accepted_jobs == 2
272
+ assert response.status == BatchStatus.ACTIVE
273
+
274
+
275
+ def test_annotation_workflow_deserialises():
276
+ workflow = AnnotationWorkflow(**WORKFLOW_JSON)
277
+
278
+ assert workflow.id == "sys-wf-graph-2"
279
+ assert workflow.target_batch_type == "graph"
280
+ assert workflow.is_system is True
281
+ assert workflow.status == "active"
282
+ assert workflow.current_published_version_id == "sys-wfv-graph-2"
283
+ assert workflow.draft_version_id is None
284
+
285
+
286
+ def test_annotation_workflows_paged_result_wraps_page_and_items():
287
+ result = AnnotationWorkflowsPagedResult(**{"page": {"page": 0, "size": 50, "total": 1}, "items": [WORKFLOW_JSON]})
288
+
289
+ assert result.page.total == 1
290
+ assert [w.code for w in result.items] == ["graph_two_step"]
291
+
292
+
293
+ def test_bind_workflow_result_carries_the_bound_version_and_regoverned_count():
294
+ result = BindWorkflowResult(
295
+ success=True, message="0 job(s) re-governed", workflow_version_id="sys-wfv-graph-2", jobs_regoverned=0
296
+ )
297
+
298
+ assert result.workflow_version_id == "sys-wfv-graph-2"
299
+ assert result.jobs_regoverned == 0
@@ -0,0 +1,153 @@
1
+ """Wire-contract tests for the shared BaseDelegateClient (PR #5 M3).
2
+
3
+ All delegate clients now inherit this plumbing, so these offline tests pin the
4
+ exact request shape (URL = base_url + api_path + endpoint, bearer header, JSON
5
+ content type, body, params, timeout) and the empty-body handling.
6
+ """
7
+
8
+ import pytest
9
+ import requests
10
+
11
+ from agency_sdk.delegates.base_client import BaseDelegateClient
12
+ from agency_sdk.test.conftest import StubResponse
13
+
14
+
15
+ class _Client(BaseDelegateClient):
16
+ api_path = "/api/widgets"
17
+
18
+
19
+ @pytest.fixture
20
+ def client(fake_credentials):
21
+ return _Client(token_supplier=fake_credentials, base_url="http://cp.test/")
22
+
23
+
24
+ def test_init_rstrips_base_url_and_binds_credentials(client, fake_credentials):
25
+ assert client.base_url == "http://cp.test"
26
+ assert client.token_supplier is fake_credentials
27
+
28
+
29
+ def test_make_request_composes_url_headers_and_body(stub_requests, client):
30
+ stub_requests.queue(json_data={"ok": True})
31
+
32
+ result = client._make_request("POST", "/42", data={"a": 1}, params={"o": "2"})
33
+
34
+ assert result == {"ok": True}
35
+ call = stub_requests.calls[0]
36
+ assert call.method == "POST"
37
+ assert call.url == "http://cp.test/api/widgets/42"
38
+ assert call.kwargs["headers"]["Authorization"] == "Bearer test-token"
39
+ assert call.kwargs["headers"]["Content-Type"] == "application/json"
40
+ assert call.kwargs["json"] == {"a": 1}
41
+ assert call.kwargs["params"] == {"o": "2"}
42
+ assert call.kwargs["timeout"] == 30
43
+
44
+
45
+ def test_make_request_returns_empty_dict_on_no_content(stub_requests, client):
46
+ stub_requests.queue(json_data=None) # content == b"" -> {}
47
+
48
+ assert client._make_request("DELETE", "/9") == {}
49
+
50
+
51
+ def test_request_without_json_content_type_omits_header(stub_requests, client):
52
+ stub_requests.queue(text="raw-export-body")
53
+
54
+ response = client._request("GET", "/export", params={"format": "turtle"}, json_content_type=False)
55
+
56
+ assert response.text == "raw-export-body"
57
+ call = stub_requests.calls[0]
58
+ assert call.url == "http://cp.test/api/widgets/export"
59
+ assert "Content-Type" not in call.kwargs["headers"]
60
+ assert call.kwargs["headers"]["Authorization"] == "Bearer test-token"
61
+
62
+
63
+ class _FlakyTransport:
64
+ """requests.request stand-in: raises `raises` on the first N calls, then succeeds."""
65
+
66
+ def __init__(self, raises: Exception, fail_times: int, response: StubResponse):
67
+ self.raises = raises
68
+ self.fail_times = fail_times
69
+ self.response = response
70
+ self.calls = 0
71
+
72
+ def __call__(self, **kwargs) -> StubResponse:
73
+ self.calls += 1
74
+ if self.calls <= self.fail_times:
75
+ raise self.raises
76
+ return self.response
77
+
78
+
79
+ def test_connection_errors_are_retried_then_succeed(client, monkeypatch):
80
+ sleeps: list[float] = []
81
+ monkeypatch.setattr("agency_sdk.delegates.base_client.time.sleep", lambda s: sleeps.append(s))
82
+ transport = _FlakyTransport(
83
+ requests.ConnectionError("blip"), fail_times=2, response=StubResponse(json_data={"ok": True})
84
+ )
85
+ monkeypatch.setattr(requests, "request", transport)
86
+
87
+ result = client._make_request("GET", "/x")
88
+
89
+ assert result == {"ok": True}
90
+ assert transport.calls == 3 # 2 retries + success
91
+ assert sleeps == [1.0, 2.0] # exponential backoff between the 3 attempts
92
+
93
+
94
+ def test_connection_error_exhausts_retries_and_raises(client, monkeypatch):
95
+ monkeypatch.setattr("agency_sdk.delegates.base_client.time.sleep", lambda s: None)
96
+ transport = _FlakyTransport(requests.ConnectionError("down"), fail_times=99, response=StubResponse())
97
+ monkeypatch.setattr(requests, "request", transport)
98
+
99
+ with pytest.raises(requests.ConnectionError):
100
+ client._make_request("GET", "/x")
101
+
102
+ assert transport.calls == 3 # bounded: initial + 2 retries, then propagate
103
+
104
+
105
+ def test_read_timeout_is_not_retried(client, monkeypatch):
106
+ # A slow server (read timeout) must NOT be retried — retrying would multiply the hang.
107
+ monkeypatch.setattr("agency_sdk.delegates.base_client.time.sleep", lambda s: None)
108
+ transport = _FlakyTransport(requests.ReadTimeout("slow"), fail_times=99, response=StubResponse())
109
+ monkeypatch.setattr(requests, "request", transport)
110
+
111
+ with pytest.raises(requests.ReadTimeout):
112
+ client._make_request("GET", "/x")
113
+
114
+ assert transport.calls == 1 # single attempt, no retry
115
+
116
+
117
+ def test_http_status_errors_are_not_retried(client, stub_requests):
118
+ # 409 (and any 4xx/5xx) is raised by raise_for_status OUTSIDE the retry loop, so a
119
+ # control-flow conflict is never silently re-sent.
120
+ stub_requests.queue(json_data={"message": "conflict"}, status_code=409)
121
+
122
+ with pytest.raises(requests.HTTPError):
123
+ client._make_request("POST", "/x", data={"a": 1})
124
+
125
+ assert len(stub_requests.calls) == 1
126
+
127
+
128
+ def test_post_is_not_auto_retried_on_connection_error(client, monkeypatch):
129
+ # A ConnectionError can be a reset AFTER the server committed, so a non-idempotent
130
+ # POST must be sent exactly once by default — retrying would double-apply it (e.g.
131
+ # corrupt work_queue's 409-as-control-flow by re-hitting the UNIQUE key).
132
+ monkeypatch.setattr("agency_sdk.delegates.base_client.time.sleep", lambda s: None)
133
+ transport = _FlakyTransport(requests.ConnectionError("reset"), fail_times=99, response=StubResponse())
134
+ monkeypatch.setattr(requests, "request", transport)
135
+
136
+ with pytest.raises(requests.ConnectionError):
137
+ client._make_request("POST", "/x", data={"a": 1})
138
+
139
+ assert transport.calls == 1 # exactly once, no retry
140
+
141
+
142
+ def test_write_can_opt_into_retry(client, monkeypatch):
143
+ # An idempotent write (e.g. session update) opts in explicitly with retry=True.
144
+ monkeypatch.setattr("agency_sdk.delegates.base_client.time.sleep", lambda s: None)
145
+ transport = _FlakyTransport(
146
+ requests.ConnectionError("blip"), fail_times=2, response=StubResponse(json_data={"ok": True})
147
+ )
148
+ monkeypatch.setattr(requests, "request", transport)
149
+
150
+ result = client._make_request("POST", "/x", data={"a": 1}, retry=True)
151
+
152
+ assert result == {"ok": True}
153
+ assert transport.calls == 3
@@ -0,0 +1,105 @@
1
+ """Facade tests: AgencyClient composes and exposes the delegate clients."""
2
+
3
+ from agency_sdk.client import AgencyClient
4
+ from agency_sdk.delegates.annotations_client import AgencyAnnotationsClient
5
+ from agency_sdk.delegates.files_client import AgencyFilesClient
6
+ from agency_sdk.delegates.session_client import AgencySessionClient
7
+ from agency_sdk.delegates.session_templates_client import AgencySessionTemplatesClient
8
+ from agency_sdk.delegates.session_vault_client import AgencySessionVaultClient
9
+ from agency_sdk.delegates.work_queue_client import AgencyWorkQueueClient
10
+
11
+
12
+ def test_facade_exposes_files_client(fake_credentials):
13
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test/")
14
+
15
+ files = client.files()
16
+
17
+ assert isinstance(files, AgencyFilesClient)
18
+ assert files.token_supplier is fake_credentials
19
+ assert files.base_url == "http://cp.test"
20
+
21
+
22
+ def test_facade_returns_same_files_instance(fake_credentials):
23
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test")
24
+
25
+ assert client.files() is client.files()
26
+
27
+
28
+ def test_facade_exposes_session_vault_client(fake_credentials):
29
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test/")
30
+
31
+ vault = client.session_vault()
32
+
33
+ assert isinstance(vault, AgencySessionVaultClient)
34
+ assert vault.token_supplier is fake_credentials
35
+ assert vault.base_url == "http://cp.test"
36
+
37
+
38
+ def test_facade_returns_same_session_vault_instance(fake_credentials):
39
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test")
40
+
41
+ assert client.session_vault() is client.session_vault()
42
+
43
+
44
+ def test_facade_exposes_work_queue_client(fake_credentials):
45
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test/")
46
+
47
+ work_queues = client.work_queues()
48
+
49
+ assert isinstance(work_queues, AgencyWorkQueueClient)
50
+ assert work_queues.token_supplier is fake_credentials
51
+ assert work_queues.base_url == "http://cp.test"
52
+
53
+
54
+ def test_facade_returns_same_work_queue_instance(fake_credentials):
55
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test")
56
+
57
+ assert client.work_queues() is client.work_queues()
58
+
59
+
60
+ def test_facade_exposes_session_client(fake_credentials):
61
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test/")
62
+
63
+ sessions = client.sessions()
64
+
65
+ assert isinstance(sessions, AgencySessionClient)
66
+ assert sessions.token_supplier is fake_credentials
67
+ assert sessions.base_url == "http://cp.test"
68
+
69
+
70
+ def test_facade_returns_same_session_instance(fake_credentials):
71
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test")
72
+
73
+ assert client.sessions() is client.sessions()
74
+
75
+
76
+ def test_facade_exposes_session_templates_client(fake_credentials):
77
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test/")
78
+
79
+ templates = client.session_templates()
80
+
81
+ assert isinstance(templates, AgencySessionTemplatesClient)
82
+ assert templates.token_supplier is fake_credentials
83
+ assert templates.base_url == "http://cp.test"
84
+
85
+
86
+ def test_facade_returns_same_session_templates_instance(fake_credentials):
87
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test")
88
+
89
+ assert client.session_templates() is client.session_templates()
90
+
91
+
92
+ def test_facade_exposes_annotations_client(fake_credentials):
93
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test/")
94
+
95
+ annotations = client.annotations()
96
+
97
+ assert isinstance(annotations, AgencyAnnotationsClient)
98
+ assert annotations.token_supplier is fake_credentials
99
+ assert annotations.base_url == "http://cp.test"
100
+
101
+
102
+ def test_facade_returns_same_annotations_instance(fake_credentials):
103
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test")
104
+
105
+ assert client.annotations() is client.annotations()
@@ -0,0 +1,67 @@
1
+ """Tests for CredentialsSupplier, including the observability early-refresh buffer.
2
+
3
+ The buffer makes a token count as expired shortly before its real ``exp`` so the
4
+ observability OTLP per-request hook never stamps a token that expires in transit.
5
+ """
6
+
7
+ import time
8
+
9
+ import jwt
10
+
11
+ from agency_sdk.credentials import CredentialsSupplier
12
+
13
+
14
+ # 32-byte key keeps PyJWT from emitting an InsecureKeyLengthWarning; the value is
15
+ # irrelevant since the SDK decodes without signature verification.
16
+ _TEST_KEY = "x" * 32
17
+
18
+
19
+ def _jwt_expiring_in(seconds: int) -> str:
20
+ return jwt.encode({"exp": int(time.time()) + seconds}, _TEST_KEY, algorithm="HS256")
21
+
22
+
23
+ def test_token_within_refresh_buffer_counts_as_expired():
24
+ cs = CredentialsSupplier("http://auth", "id", "secret", refresh_buffer=30.0)
25
+ cs._cached_token = _jwt_expiring_in(10) # inside the 30s buffer
26
+
27
+ assert cs._is_token_expired() is True
28
+
29
+
30
+ def test_token_beyond_refresh_buffer_is_valid():
31
+ cs = CredentialsSupplier("http://auth", "id", "secret", refresh_buffer=30.0)
32
+ cs._cached_token = _jwt_expiring_in(120) # well beyond the buffer
33
+
34
+ assert cs._is_token_expired() is False
35
+
36
+
37
+ def test_no_cached_token_is_expired():
38
+ cs = CredentialsSupplier("http://auth", "id", "secret")
39
+ assert cs._is_token_expired() is True
40
+
41
+
42
+ def test_default_refresh_buffer_is_applied():
43
+ # exp 5s out should be considered expired under the default (30s) buffer.
44
+ cs = CredentialsSupplier("http://auth", "id", "secret")
45
+ cs._cached_token = _jwt_expiring_in(5)
46
+
47
+ assert cs._is_token_expired() is True
48
+
49
+
50
+ def test_malformed_cached_token_is_treated_as_expired():
51
+ cs = CredentialsSupplier("http://auth", "id", "secret")
52
+ cs._cached_token = "not-a-jwt"
53
+
54
+ assert cs._is_token_expired() is True
55
+
56
+
57
+ def test_bearer_token_fetches_then_caches(stub_requests):
58
+ token = _jwt_expiring_in(3600)
59
+ stub_requests.queue(json_data={"access_token": token})
60
+ cs = CredentialsSupplier("http://auth/token/", "id", "secret")
61
+
62
+ first = cs.bearer_token()
63
+ second = cs.bearer_token() # served from cache; no second response queued
64
+
65
+ assert first == token
66
+ assert second == token
67
+ assert len(stub_requests.calls) == 1