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.
- agency_sdk/__init__.py +0 -0
- agency_sdk/auth_hooks.py +55 -0
- agency_sdk/client.py +212 -0
- agency_sdk/credentials.py +54 -0
- agency_sdk/delegates/__init__.py +0 -0
- agency_sdk/delegates/annotations_client.py +495 -0
- agency_sdk/delegates/annotations_dto.py +200 -0
- agency_sdk/delegates/base_client.py +126 -0
- agency_sdk/delegates/datasets_client.py +109 -0
- agency_sdk/delegates/datasets_dto.py +81 -0
- agency_sdk/delegates/datasource_client.py +44 -0
- agency_sdk/delegates/datasource_dto.py +107 -0
- agency_sdk/delegates/files_client.py +184 -0
- agency_sdk/delegates/files_dto.py +36 -0
- agency_sdk/delegates/gateway_client.py +81 -0
- agency_sdk/delegates/gateway_dto.py +37 -0
- agency_sdk/delegates/ontology_client.py +203 -0
- agency_sdk/delegates/ontology_dto.py +221 -0
- agency_sdk/delegates/prompts_client.py +56 -0
- agency_sdk/delegates/rules_client.py +33 -0
- agency_sdk/delegates/rules_dto.py +108 -0
- agency_sdk/delegates/session_client.py +95 -0
- agency_sdk/delegates/session_dto.py +94 -0
- agency_sdk/delegates/session_templates_client.py +23 -0
- agency_sdk/delegates/session_templates_dto.py +27 -0
- agency_sdk/delegates/session_vault_client.py +135 -0
- agency_sdk/delegates/session_vault_dto.py +75 -0
- agency_sdk/delegates/work_queue_client.py +230 -0
- agency_sdk/delegates/work_queue_dto.py +127 -0
- agency_sdk/domain.py +140 -0
- agency_sdk/observability/__init__.py +60 -0
- agency_sdk/observability/auth.py +15 -0
- agency_sdk/observability/bootstrap.py +344 -0
- agency_sdk/test/__init__.py +0 -0
- agency_sdk/test/conftest.py +106 -0
- agency_sdk/test/test_annotations_client.py +599 -0
- agency_sdk/test/test_annotations_dto.py +299 -0
- agency_sdk/test/test_base_client.py +153 -0
- agency_sdk/test/test_client_facade.py +105 -0
- agency_sdk/test/test_credentials.py +67 -0
- agency_sdk/test/test_files_client.py +264 -0
- agency_sdk/test/test_files_dto.py +93 -0
- agency_sdk/test/test_gateway_dto.py +70 -0
- agency_sdk/test/test_gateway_facade.py +229 -0
- agency_sdk/test/test_gateway_openai.py +76 -0
- agency_sdk/test/test_observability_auth.py +125 -0
- agency_sdk/test/test_observability_facade_threadsafety.py +50 -0
- agency_sdk/test/test_observability_langfuse.py +76 -0
- agency_sdk/test/test_observability_packaging.py +78 -0
- agency_sdk/test/test_observability_pipeline.py +246 -0
- agency_sdk/test/test_ontology_client.py +152 -0
- agency_sdk/test/test_ontology_dto.py +158 -0
- agency_sdk/test/test_session_client.py +128 -0
- agency_sdk/test/test_session_dto.py +75 -0
- agency_sdk/test/test_session_templates_client.py +36 -0
- agency_sdk/test/test_session_templates_dto.py +45 -0
- agency_sdk/test/test_session_vault_client.py +151 -0
- agency_sdk/test/test_session_vault_dto.py +27 -0
- agency_sdk/test/test_stub_requests.py +39 -0
- agency_sdk/test/test_work_queue_client.py +388 -0
- agency_sdk/test/test_work_queue_dto.py +233 -0
- gts_agency_python_sdk-0.0.1.dist-info/METADATA +221 -0
- gts_agency_python_sdk-0.0.1.dist-info/RECORD +66 -0
- gts_agency_python_sdk-0.0.1.dist-info/WHEEL +5 -0
- gts_agency_python_sdk-0.0.1.dist-info/licenses/LICENSE +201 -0
- gts_agency_python_sdk-0.0.1.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
"""DTO deserialisation tests for the work-queue delegate.
|
|
2
|
+
|
|
3
|
+
ItemResponse JSON samples are transcribed from the server DTO in
|
|
4
|
+
gts-agency-control/src/service/work_queue/work_queue_dto.rs (``ItemResponse``,
|
|
5
|
+
which omits Option fields entirely when null). The 409 conflict bodies follow
|
|
6
|
+
the frozen Track ① contract (files-inbox-ingestion design §2/§5.2): create → 409
|
|
7
|
+
carries ``{work_item_id, status, published}``; add_ref → 409 carries the owner
|
|
8
|
+
``{work_item_id, status}`` only.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from agency_sdk.delegates.work_queue_dto import (
|
|
12
|
+
AddRefResult,
|
|
13
|
+
CreateItemResult,
|
|
14
|
+
DependencyResponse,
|
|
15
|
+
ExistingItemSummary,
|
|
16
|
+
ItemCommandResponse,
|
|
17
|
+
ItemResponse,
|
|
18
|
+
QueueResponse,
|
|
19
|
+
QueuesPagedResult,
|
|
20
|
+
)
|
|
21
|
+
|
|
22
|
+
QUEUE_JSON = {
|
|
23
|
+
"id": 8,
|
|
24
|
+
"name": "Guideline Ingestion",
|
|
25
|
+
"description": "Files-inbox ingestion queue for the guideline agent (org 2)",
|
|
26
|
+
"status": 1,
|
|
27
|
+
"created_on": "2026-07-20T20:47:33Z",
|
|
28
|
+
"created_by": "901",
|
|
29
|
+
"modified_on": "2026-07-20T20:47:33Z",
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
ITEM_JSON = {
|
|
33
|
+
"id": 4711,
|
|
34
|
+
"work_queue_id": 12,
|
|
35
|
+
"title": "Ingest inbox/report.pdf",
|
|
36
|
+
"description": "files-inbox ingestion card",
|
|
37
|
+
"status": "backlog",
|
|
38
|
+
"published": False,
|
|
39
|
+
"priority": 0,
|
|
40
|
+
"session_template_id": "guideline-extraction",
|
|
41
|
+
"session_id": "sess-0001",
|
|
42
|
+
"assigned_worker_id": "worker-7",
|
|
43
|
+
"input_data": {"file_id": "file_550e8400", "path": "inbox/report.pdf"},
|
|
44
|
+
"saved_state": {"checkpoint": 3},
|
|
45
|
+
"result_data": {"notes": 17},
|
|
46
|
+
"metadata": {"filename": "report.pdf", "size_bytes": 12345},
|
|
47
|
+
"started_on": "2026-07-13T12:01:00Z",
|
|
48
|
+
"created_on": "2026-07-13T12:00:00Z",
|
|
49
|
+
"modified_on": "2026-07-13T12:02:00Z",
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
# The server serializes with skip_serializing_if = Option::is_none, so a fresh
|
|
53
|
+
# unpublished card arrives with every nullable field absent, not null.
|
|
54
|
+
MINIMAL_ITEM_JSON = {
|
|
55
|
+
"id": 4712,
|
|
56
|
+
"work_queue_id": 12,
|
|
57
|
+
"title": "Ingest inbox/other.pdf",
|
|
58
|
+
"status": "backlog",
|
|
59
|
+
"published": False,
|
|
60
|
+
"priority": 0,
|
|
61
|
+
"created_on": "2026-07-13T12:00:00Z",
|
|
62
|
+
"modified_on": "2026-07-13T12:00:00Z",
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
CREATE_CONFLICT_JSON = {"work_item_id": 4711, "status": "doing", "published": True}
|
|
66
|
+
|
|
67
|
+
DEPENDENCY_JSON = {
|
|
68
|
+
"depends_on_item_id": 4700,
|
|
69
|
+
"depends_on_title": "Classify folder",
|
|
70
|
+
"depends_on_status": "done",
|
|
71
|
+
"created_on": "2026-07-13T11:00:00Z",
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def test_item_response_deserialises_full_payload():
|
|
76
|
+
item = ItemResponse(**ITEM_JSON)
|
|
77
|
+
|
|
78
|
+
assert item.id == 4711
|
|
79
|
+
assert item.work_queue_id == 12
|
|
80
|
+
assert item.title == "Ingest inbox/report.pdf"
|
|
81
|
+
assert item.description == "files-inbox ingestion card"
|
|
82
|
+
assert item.status == "backlog"
|
|
83
|
+
assert item.published is False
|
|
84
|
+
assert item.priority == 0
|
|
85
|
+
assert item.session_template_id == "guideline-extraction"
|
|
86
|
+
assert item.session_id == "sess-0001"
|
|
87
|
+
assert item.assigned_worker_id == "worker-7"
|
|
88
|
+
assert item.input_data == {"file_id": "file_550e8400", "path": "inbox/report.pdf"}
|
|
89
|
+
assert item.saved_state == {"checkpoint": 3}
|
|
90
|
+
assert item.result_data == {"notes": 17}
|
|
91
|
+
assert item.metadata == {"filename": "report.pdf", "size_bytes": 12345}
|
|
92
|
+
assert item.started_on == "2026-07-13T12:01:00Z"
|
|
93
|
+
assert item.created_on == "2026-07-13T12:00:00Z"
|
|
94
|
+
assert item.modified_on == "2026-07-13T12:02:00Z"
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
def test_item_response_omitted_optional_fields_default_to_none():
|
|
98
|
+
item = ItemResponse(**MINIMAL_ITEM_JSON)
|
|
99
|
+
|
|
100
|
+
assert item.description is None
|
|
101
|
+
assert item.session_template_id is None
|
|
102
|
+
assert item.agent_id is None
|
|
103
|
+
assert item.session_id is None
|
|
104
|
+
assert item.assigned_worker_id is None
|
|
105
|
+
assert item.input_data is None
|
|
106
|
+
assert item.saved_state is None
|
|
107
|
+
assert item.result_data is None
|
|
108
|
+
assert item.metadata is None
|
|
109
|
+
assert item.dependencies is None
|
|
110
|
+
assert item.started_on is None
|
|
111
|
+
assert item.blocked_on is None
|
|
112
|
+
assert item.unblocked_on is None
|
|
113
|
+
assert item.completed_on is None
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def test_item_response_carries_typed_dependencies():
|
|
117
|
+
item = ItemResponse(**{**MINIMAL_ITEM_JSON, "dependencies": [DEPENDENCY_JSON]})
|
|
118
|
+
|
|
119
|
+
assert item.dependencies is not None
|
|
120
|
+
dependency = item.dependencies[0]
|
|
121
|
+
assert isinstance(dependency, DependencyResponse)
|
|
122
|
+
assert dependency.depends_on_item_id == 4700
|
|
123
|
+
assert dependency.depends_on_title == "Classify folder"
|
|
124
|
+
assert dependency.depends_on_status == "done"
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def test_create_item_result_created_wraps_item():
|
|
128
|
+
result = CreateItemResult(created=True, item=ItemResponse(**ITEM_JSON))
|
|
129
|
+
|
|
130
|
+
assert result.created is True
|
|
131
|
+
assert result.item is not None
|
|
132
|
+
assert result.item.id == 4711
|
|
133
|
+
assert result.existing is None
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def test_create_item_result_conflict_carries_existing_summary():
|
|
137
|
+
result = CreateItemResult(created=False, existing=ExistingItemSummary(**CREATE_CONFLICT_JSON))
|
|
138
|
+
|
|
139
|
+
assert result.created is False
|
|
140
|
+
assert result.item is None
|
|
141
|
+
assert result.existing is not None
|
|
142
|
+
assert result.existing.work_item_id == 4711
|
|
143
|
+
assert result.existing.status == "doing"
|
|
144
|
+
assert result.existing.published is True
|
|
145
|
+
|
|
146
|
+
|
|
147
|
+
def test_add_ref_result_added_has_no_owner():
|
|
148
|
+
result = AddRefResult(added=True)
|
|
149
|
+
|
|
150
|
+
assert result.added is True
|
|
151
|
+
assert result.owner_work_item_id is None
|
|
152
|
+
assert result.owner_status is None
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def test_item_command_response_deserialises_with_session_id():
|
|
156
|
+
# The _command endpoint's EXISTING server shape (work_queue_dto.rs ItemCommandResponse),
|
|
157
|
+
# transcribed per design §6.0 — commands do NOT return the updated item.
|
|
158
|
+
response = ItemCommandResponse(
|
|
159
|
+
**{"success": True, "message": "Item published successfully", "session_id": "sess-0001"}
|
|
160
|
+
)
|
|
161
|
+
|
|
162
|
+
assert response.success is True
|
|
163
|
+
assert response.message == "Item published successfully"
|
|
164
|
+
assert response.session_id == "sess-0001"
|
|
165
|
+
|
|
166
|
+
|
|
167
|
+
def test_item_command_response_omits_session_id_when_absent():
|
|
168
|
+
# session_id is skip_serializing_if'd server-side: absent, not null, for non-dispatching commands
|
|
169
|
+
response = ItemCommandResponse(**{"success": True, "message": "Item unblocked"})
|
|
170
|
+
|
|
171
|
+
assert response.success is True
|
|
172
|
+
assert response.session_id is None
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
def test_add_ref_result_conflict_carries_owner_without_published():
|
|
176
|
+
# add_ref's 409 owner summary is {work_item_id, status} — narrower than create's.
|
|
177
|
+
result = AddRefResult(added=False, owner_work_item_id=4711, owner_status="blocked")
|
|
178
|
+
|
|
179
|
+
assert result.added is False
|
|
180
|
+
assert result.owner_work_item_id == 4711
|
|
181
|
+
assert result.owner_status == "blocked"
|
|
182
|
+
assert not hasattr(result, "owner_published")
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
def test_existing_item_summary_published_is_optional():
|
|
186
|
+
# The enveloped error.details may omit `published` (mirrors details.get("published")).
|
|
187
|
+
summary = ExistingItemSummary(work_item_id=4711, status="doing")
|
|
188
|
+
|
|
189
|
+
assert summary.work_item_id == 4711
|
|
190
|
+
assert summary.status == "doing"
|
|
191
|
+
assert summary.published is None
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
def test_create_item_result_contended_defaults_false_and_can_be_set():
|
|
195
|
+
assert CreateItemResult(created=True).contended is False
|
|
196
|
+
|
|
197
|
+
contended = CreateItemResult(created=False, existing=None, contended=True)
|
|
198
|
+
assert contended.contended is True
|
|
199
|
+
assert contended.existing is None
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
def test_add_ref_result_contended_defaults_false_and_can_be_set():
|
|
203
|
+
assert AddRefResult(added=True).contended is False
|
|
204
|
+
|
|
205
|
+
contended = AddRefResult(added=False, contended=True)
|
|
206
|
+
assert contended.contended is True
|
|
207
|
+
assert contended.owner_work_item_id is None
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
def test_queue_response_deserialises_from_server_json():
|
|
211
|
+
queue = QueueResponse(**QUEUE_JSON)
|
|
212
|
+
|
|
213
|
+
assert queue.id == 8
|
|
214
|
+
assert queue.name == "Guideline Ingestion"
|
|
215
|
+
assert queue.status == 1
|
|
216
|
+
assert queue.description == "Files-inbox ingestion queue for the guideline agent (org 2)"
|
|
217
|
+
assert queue.created_on == "2026-07-20T20:47:33Z"
|
|
218
|
+
assert queue.created_by == "901"
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
def test_queue_response_optional_fields_default_to_none():
|
|
222
|
+
queue = QueueResponse(id=9, name="q", status=1, created_on="t", modified_on="t")
|
|
223
|
+
|
|
224
|
+
assert queue.description is None
|
|
225
|
+
assert queue.created_by is None
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
def test_queues_paged_result_wraps_page_and_items():
|
|
229
|
+
result = QueuesPagedResult(**{"page": {"page": 0, "size": 1, "total": 1}, "items": [QUEUE_JSON]})
|
|
230
|
+
|
|
231
|
+
assert result.page.total == 1
|
|
232
|
+
assert [q.id for q in result.items] == [8]
|
|
233
|
+
assert result.items[0].name == "Guideline Ingestion"
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: gts-agency_python-sdk
|
|
3
|
+
Version: 0.0.1
|
|
4
|
+
Author-email: Ground Control Systems <engineering@groundcontrolsystems.com>
|
|
5
|
+
Requires-Python: >=3.12
|
|
6
|
+
Description-Content-Type: text/markdown
|
|
7
|
+
License-File: LICENSE
|
|
8
|
+
Requires-Dist: requests>=2.32.0
|
|
9
|
+
Requires-Dist: pydantic>=2.9.2
|
|
10
|
+
Requires-Dist: pyjwt<3.0.0,>=2.3.0
|
|
11
|
+
Requires-Dist: openai>=1.0.0
|
|
12
|
+
Provides-Extra: observability
|
|
13
|
+
Requires-Dist: opentelemetry-sdk>=1.27.0; extra == "observability"
|
|
14
|
+
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27.0; extra == "observability"
|
|
15
|
+
Requires-Dist: opentelemetry-instrumentation-logging>=0.48b0; extra == "observability"
|
|
16
|
+
Requires-Dist: langfuse>=3.8.1; extra == "observability"
|
|
17
|
+
Provides-Extra: dev
|
|
18
|
+
Requires-Dist: mypy==1.4.1; extra == "dev"
|
|
19
|
+
Requires-Dist: pytest==7.4.0; extra == "dev"
|
|
20
|
+
Requires-Dist: pytest-cov==4.1.0; extra == "dev"
|
|
21
|
+
Requires-Dist: pre-commit==3.8.0; extra == "dev"
|
|
22
|
+
Requires-Dist: black==23.12.1; extra == "dev"
|
|
23
|
+
Dynamic: license-file
|
|
24
|
+
|
|
25
|
+
# Agency Python SDK
|
|
26
|
+
|
|
27
|
+
Python client SDK for the GTS Agency platform. Provides typed HTTP clients for datasets, datasources, files, ontologies, prompts, and rules APIs.
|
|
28
|
+
|
|
29
|
+
## Installation
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
pip install gts-agency-python-sdk
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
For development:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
pip install -e ".[dev]"
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Optional OpenTelemetry tracing support (Langfuse backend):
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
pip install gts-agency-python-sdk[observability]
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Configuration
|
|
48
|
+
|
|
49
|
+
The examples in this repository use the following environment variables for authentication and configuration:
|
|
50
|
+
|
|
51
|
+
- `AGENCY_AUTH_URL`: The OAuth2 token endpoint URL.
|
|
52
|
+
- `AGENCY_API_URL`: The base URL for the Agency API.
|
|
53
|
+
- `AGENCY_ORG_ID`: The organization ID to use for requests.
|
|
54
|
+
- `AGENCY_CLIENT_ID`: Your OAuth2 client ID.
|
|
55
|
+
- `AGENCY_CLIENT_SECRET`: Your OAuth2 client secret.
|
|
56
|
+
|
|
57
|
+
## Usage
|
|
58
|
+
|
|
59
|
+
```python
|
|
60
|
+
from agency_sdk.client import AgencyClient, CredentialsSupplier
|
|
61
|
+
|
|
62
|
+
credentials = CredentialsSupplier(
|
|
63
|
+
auth_base_url="https://auth.example.com",
|
|
64
|
+
client_id="your-client-id",
|
|
65
|
+
client_secret="your-client-secret",
|
|
66
|
+
)
|
|
67
|
+
client = AgencyClient(token_supplier=credentials, base_url="https://api.example.com")
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### Delegate Clients
|
|
71
|
+
|
|
72
|
+
Access each API domain through the facade:
|
|
73
|
+
|
|
74
|
+
- `client.dataset()` — datasets CRUD, filesystem traversal, clone
|
|
75
|
+
- `client.datasource()` — datasource and table introspection
|
|
76
|
+
- `client.files()` — tenant file storage: list, upload, folder management, delete, signed URLs, `gtsf://` URI resolution, streamed download
|
|
77
|
+
- `client.ontology()` — list ontologies (name → id, optional `kind` filter), export (JSON snapshot, Turtle/OWL, SHACL, package, package-zip), and entity-datasource mappings
|
|
78
|
+
- `client.prompts()` — prompt CRUD via command pattern
|
|
79
|
+
- `client.rules()` — rule listing, detail, execution, and execution history
|
|
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, 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
|
+
- `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))
|
|
85
|
+
- `client.gateway(org_id=..., gateway_base_url=...)` — OpenAI-compatible LLM calls routed through the org's agentgateway (shared credentials + `x-org` routing header)
|
|
86
|
+
|
|
87
|
+
### Rules Example
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
from agency_sdk.delegates.rules_dto import ExecuteRequest
|
|
91
|
+
|
|
92
|
+
rules = client.rules()
|
|
93
|
+
|
|
94
|
+
# List rules
|
|
95
|
+
result = rules.list(organisation_id=2)
|
|
96
|
+
for rule in result.items:
|
|
97
|
+
print(f"{rule.name} (status={rule.active_version_status})")
|
|
98
|
+
|
|
99
|
+
# Get rule detail
|
|
100
|
+
detail = rules.get(rule_id="rule-id", organisation_id=2)
|
|
101
|
+
|
|
102
|
+
# Execute a rule
|
|
103
|
+
response = rules.execute(
|
|
104
|
+
rule_id="rule-id",
|
|
105
|
+
request=ExecuteRequest(organisation=2, context={"key": "value"}, trace=True),
|
|
106
|
+
)
|
|
107
|
+
print(f"Result: {response.result}")
|
|
108
|
+
|
|
109
|
+
# List execution history
|
|
110
|
+
executions = rules.list_executions(rule_id="rule-id", organisation_id=2)
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Files Example
|
|
114
|
+
|
|
115
|
+
```python
|
|
116
|
+
files = client.files()
|
|
117
|
+
|
|
118
|
+
# Upload into a folder (multipart; up to 100 MiB per file and per request)
|
|
119
|
+
result = files.upload(organisation_id=2, file_paths=["report.pdf"], path="guidelines")
|
|
120
|
+
file_id = result.uploaded[0].id
|
|
121
|
+
|
|
122
|
+
# Resolve a gtsf:// reference (as found in configurations and rule annotations)
|
|
123
|
+
signed = files.resolve_gtsf_uri(f"gtsf://{file_id}", organisation_id=2)
|
|
124
|
+
print(f"Download until {signed.expires_at}: {signed.signed_url}")
|
|
125
|
+
|
|
126
|
+
# Or download directly (streamed to disk via the signed URL)
|
|
127
|
+
files.download(file_id=file_id, organisation_id=2, target_path="./report.pdf")
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
See [docs/files_storage_flows.md](docs/files_storage_flows.md) for the full
|
|
131
|
+
upload/download architecture.
|
|
132
|
+
|
|
133
|
+
### Ontology Export Example
|
|
134
|
+
|
|
135
|
+
Agents retrieve a typed JSON snapshot and use its classes, relations, and
|
|
136
|
+
properties to decide how to treat data. Text formats (`turtle`, `shacl`,
|
|
137
|
+
`package`) return `str`; `package-zip` is binary and must go through
|
|
138
|
+
`export_bytes()`.
|
|
139
|
+
|
|
140
|
+
```python
|
|
141
|
+
ontology = client.ontology()
|
|
142
|
+
|
|
143
|
+
listed = ontology.list(organisation_id=2)
|
|
144
|
+
ontology_id = next(item.id for item in listed.items if item.name == "claims")
|
|
145
|
+
|
|
146
|
+
snapshot = ontology.export_snapshot(ontology_id=ontology_id, organisation_id=2)
|
|
147
|
+
for entity in snapshot.entities.values():
|
|
148
|
+
print(f"{entity.entity_type}: {entity.label}")
|
|
149
|
+
|
|
150
|
+
turtle = ontology.export(ontology_id=ontology_id, organisation_id=2, export_format="turtle")
|
|
151
|
+
zip_bytes = ontology.export_bytes(ontology_id=ontology_id, organisation_id=2, export_format="package-zip")
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Observability Example
|
|
155
|
+
|
|
156
|
+
Opt-in OpenTelemetry tracing + log correlation, shipped to a Langfuse backend and
|
|
157
|
+
authenticated with the same credentials as the API client. Requires the
|
|
158
|
+
`[observability]` extra.
|
|
159
|
+
|
|
160
|
+
```python
|
|
161
|
+
obs = client.observability("gts-myagent") # reuses credentials; host defaults to base_url
|
|
162
|
+
tracer = obs.init() # exporters live; stdlib logging bridged
|
|
163
|
+
|
|
164
|
+
with obs.agent_run("agent.myagent", correlation_id=cid) as span:
|
|
165
|
+
logger.info("doing work") # stamped with the span's trace id
|
|
166
|
+
result = do_work()
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
See [docs/observability.md](docs/observability.md) for the full setup, the API,
|
|
170
|
+
and migration from a per-agent bootstrap.
|
|
171
|
+
|
|
172
|
+
### Agent Gateway Example
|
|
173
|
+
|
|
174
|
+
LLM calls routed through the org's deployed agentgateway — one m2m credential
|
|
175
|
+
instead of per-provider API keys. The gateway lives on its own host (not the
|
|
176
|
+
control-plane `base_url`); the SDK wires the rotating bearer, the `x-org` routing
|
|
177
|
+
header, and the URL into a standard **`openai`** client and hands it back.
|
|
178
|
+
|
|
179
|
+
```python
|
|
180
|
+
gateway = client.gateway(org_id="2", gateway_base_url="http://localhost:4000")
|
|
181
|
+
|
|
182
|
+
oai = gateway.openai_client() # standard openai.OpenAI, pre-wired to the gateway
|
|
183
|
+
r = oai.chat.completions.create(
|
|
184
|
+
model="biglambda1", # virtual-model name from the org's gateway config
|
|
185
|
+
messages=[{"role": "user", "content": "Summarize this rule ..."}],
|
|
186
|
+
temperature=0.0,
|
|
187
|
+
)
|
|
188
|
+
|
|
189
|
+
# Streaming / tools / structured outputs — plain openai SDK
|
|
190
|
+
for chunk in oai.chat.completions.create(model="biglambda1", messages=[...], stream=True):
|
|
191
|
+
...
|
|
192
|
+
|
|
193
|
+
# Async (e.g. httpx-based agents)
|
|
194
|
+
aoai = gateway.async_openai_client()
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
See [docs/gateway.md](docs/gateway.md) for prod/test URL selection, URL
|
|
198
|
+
discovery, rotation-safe DIY openai wiring, and error semantics.
|
|
199
|
+
|
|
200
|
+
## Examples
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
export AGENCY_AUTH_URL="http://localhost:8080/realms/agency/protocol/openid-connect/token"
|
|
204
|
+
export AGENCY_API_URL="http://localhost:13001"
|
|
205
|
+
export AGENCY_ORG_ID="2"
|
|
206
|
+
export AGENCY_CLIENT_ID="your-client-id"
|
|
207
|
+
export AGENCY_CLIENT_SECRET="your-client-secret"
|
|
208
|
+
|
|
209
|
+
python examples/quick_clone_dataset.py
|
|
210
|
+
python examples/quick_create_prompt.py
|
|
211
|
+
python examples/quick_export_ontology.py
|
|
212
|
+
python examples/quick_execute_rule.py
|
|
213
|
+
python examples/quick_files.py
|
|
214
|
+
python examples/quick_annotations.py
|
|
215
|
+
python examples/quick_observability.py # requires the [observability] extra
|
|
216
|
+
python examples/quick_gateway.py # needs GATEWAY_BASE_URL (+ GATEWAY_MODEL); local gateway on :4000
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
To verify the SDK end to end against the local platform stack
|
|
220
|
+
(`gts-local-environment`), follow [docs/local_e2e.md](docs/local_e2e.md).
|
|
221
|
+
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
agency_sdk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
2
|
+
agency_sdk/auth_hooks.py,sha256=ozTSnOgH_TQtz_8B72BC-Nu8jT3w4lkPNK4S-T1Bp8E,2020
|
|
3
|
+
agency_sdk/client.py,sha256=IBzHToWDRThL77T53sthksFlKUSmxOS6VXRaz4df79I,10093
|
|
4
|
+
agency_sdk/credentials.py,sha256=8ua3hYVoST4Vi2o2UT50bqzRYHYexAZIHpUm_TY_i88,1743
|
|
5
|
+
agency_sdk/domain.py,sha256=ZPkgmB8dg-sU5yc16Jg0fVMDOoO0vQ2qGzCJDaXuO3U,2830
|
|
6
|
+
agency_sdk/delegates/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
7
|
+
agency_sdk/delegates/annotations_client.py,sha256=dgvNtF1d10z2gxC6zRvPU9GSK7GlXR_Gxl5KDPoLEFo,23310
|
|
8
|
+
agency_sdk/delegates/annotations_dto.py,sha256=LubWi60fVKm7NlTWDJ7m7lSKU2oT4gRdul3aMmDkjUw,6471
|
|
9
|
+
agency_sdk/delegates/base_client.py,sha256=aF5NPFN9IrR_-yyMWtz4cKtIqXSjs18bryBtQKprY5o,5239
|
|
10
|
+
agency_sdk/delegates/datasets_client.py,sha256=MaYFsu3ejxgi7kJfK9KG8JQglHZrM4_rvOyisPrpd_c,4145
|
|
11
|
+
agency_sdk/delegates/datasets_dto.py,sha256=YN4BlozCcu90nr0GEZrVi4ef5WpFY8hvVS5hsR9x224,1401
|
|
12
|
+
agency_sdk/delegates/datasource_client.py,sha256=beqQ02UAROXoIkOSA47YR-32BvjaF16kqWpX1Ahba0s,1718
|
|
13
|
+
agency_sdk/delegates/datasource_dto.py,sha256=cbkVJjG9WbqSAT0oOhyeKbyMjvqSHDGQQt3xLFxPX88,2929
|
|
14
|
+
agency_sdk/delegates/files_client.py,sha256=ay73fIxE56bzD1djhiE7HPV4AVtHZRQmYmnfoPjuQG0,7991
|
|
15
|
+
agency_sdk/delegates/files_dto.py,sha256=fgSmaFMNMh9w4n1xtkWiZJLfM0IV0ADmJKSeRYNLKOs,737
|
|
16
|
+
agency_sdk/delegates/gateway_client.py,sha256=_qAoUBBAJbtDAn0rtnHMgZpffEeVj-W-PAKA5tL3-8U,3772
|
|
17
|
+
agency_sdk/delegates/gateway_dto.py,sha256=JpwUxeKdhL_AMvzKHujiEAfVwfnfsK2j9qXudahHd8g,1332
|
|
18
|
+
agency_sdk/delegates/ontology_client.py,sha256=8eYT3vveRSuG1bkuzPPWb-e7KAeBbh0JZ52641QyYgM,7450
|
|
19
|
+
agency_sdk/delegates/ontology_dto.py,sha256=0Zl8tVStPwduQGYbJbpdD1adWgZlXK6hUMq8mInNaO4,6019
|
|
20
|
+
agency_sdk/delegates/prompts_client.py,sha256=7IDaOnmO0oz1cMzSM1dRdCw5kJp0M_G4TalElviLx24,2375
|
|
21
|
+
agency_sdk/delegates/rules_client.py,sha256=rKgyv2IRBNqiQmTVi4OKwwBH0erFgNFtkJN2esF4ikM,1448
|
|
22
|
+
agency_sdk/delegates/rules_dto.py,sha256=kn7_YawTATjFmCTDLTUoYX9mac76-iXLI9epuba7Wnc,2721
|
|
23
|
+
agency_sdk/delegates/session_client.py,sha256=hB5hDRNEIdfTaw2ZdiufbtZarRzUdp5T1CI60zr2OsY,4435
|
|
24
|
+
agency_sdk/delegates/session_dto.py,sha256=P8oK6_Uz4EdPHAEVKWs4IVG5VbEin4WErbs8zjx4zuE,3198
|
|
25
|
+
agency_sdk/delegates/session_templates_client.py,sha256=t_rLdx8VXG-s6lVnVnXzPLxBy2hg1LmE1c5-7o0gn-I,1148
|
|
26
|
+
agency_sdk/delegates/session_templates_dto.py,sha256=zFGTQaGb831HqKVwqeHXlZnx78JAM1kdvLAbA16C9Tc,702
|
|
27
|
+
agency_sdk/delegates/session_vault_client.py,sha256=a-wx1LnV9Kbm865sW1Os72lD_Tp90bO7qjxBmdkTGp0,5496
|
|
28
|
+
agency_sdk/delegates/session_vault_dto.py,sha256=pDdsUTZ0mg8Sx43dxsPWlC2-lR_UXM0rGoZXf-_dVjI,2425
|
|
29
|
+
agency_sdk/delegates/work_queue_client.py,sha256=s3BJm_x9NgCABR6x9Ix1dufnE_wGtnfY0TGLQptH-J4,10305
|
|
30
|
+
agency_sdk/delegates/work_queue_dto.py,sha256=43__2xNmmOVEvkZWlBtxpI5dTU610BfHq9nmcR8ZFvA,3879
|
|
31
|
+
agency_sdk/observability/__init__.py,sha256=5SU-xSOPXIdw15-sjgaT5gkJC9IhM45BnYdr_b1R7KM,2028
|
|
32
|
+
agency_sdk/observability/auth.py,sha256=PfphZuVWcsANUARKpJxX0-7O9iW3wwA2M21ru6UHeN0,726
|
|
33
|
+
agency_sdk/observability/bootstrap.py,sha256=RbNaN6nBRtaG6CgKocDcWBbZmkArd64-9te9xIRy7P0,15072
|
|
34
|
+
agency_sdk/test/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
35
|
+
agency_sdk/test/conftest.py,sha256=Kf7B8UkO9AzvnqT-B1Pcua-vYROz_my0NZBy9dOJx8g,3482
|
|
36
|
+
agency_sdk/test/test_annotations_client.py,sha256=RuQuxQ1_QlkRpJaIymGZw32-40rjXriAZ_7fntP-IL8,25032
|
|
37
|
+
agency_sdk/test/test_annotations_dto.py,sha256=FWBaFK0P9pkQuKpvuHyQp0h7l9o10QkCQ-B6R3bk-A8,10642
|
|
38
|
+
agency_sdk/test/test_base_client.py,sha256=HMnoEDZ_R--eDH8GO0ylMSPFFEptqO0YwTs65OK_L1E,6085
|
|
39
|
+
agency_sdk/test/test_client_facade.py,sha256=CvZ56ed6x52Xn4wtfXr6AdEk7v8HJW4BWCcpPKSE2a0,3940
|
|
40
|
+
agency_sdk/test/test_credentials.py,sha256=JNxaEkQM03ymrAA0nkfrXYDJLrqr4t9t5Hhz_IW-0EU,2177
|
|
41
|
+
agency_sdk/test/test_files_client.py,sha256=S4e9FDSt-dyX9-mDSPV0qmiBlJJC4sZb3yC2qTQDM94,10626
|
|
42
|
+
agency_sdk/test/test_files_dto.py,sha256=RZ5TRdfSLKhPgW4Bixr7qk50Mvq-w0PBSmPZ3bT3EHM,2723
|
|
43
|
+
agency_sdk/test/test_gateway_dto.py,sha256=iK-Xu5Jy_tQZLxCbIISqh5EYH_Fr0ochIMeKGKYCzTY,2418
|
|
44
|
+
agency_sdk/test/test_gateway_facade.py,sha256=93F2NLiFoJij1rPfElL8JmIJ-lsqaXzX94sOjyBSX6M,8886
|
|
45
|
+
agency_sdk/test/test_gateway_openai.py,sha256=_nYHGCFiLdofkV2JgUxA6Q-0vJbG4JkLQRZllVK4z9U,2898
|
|
46
|
+
agency_sdk/test/test_observability_auth.py,sha256=upvgwLekbt89D7V7iB21okD3iJ6kv1grpBX9cssfGXI,3900
|
|
47
|
+
agency_sdk/test/test_observability_facade_threadsafety.py,sha256=E-UU2p_OGOd7yvYG_xWq-LPEVL82y3HmS-LHlRrDkuU,1685
|
|
48
|
+
agency_sdk/test/test_observability_langfuse.py,sha256=ixtfDOPFaQKnpdkiscI5sJjGr0R4zo8wTkesLG1IrVc,2414
|
|
49
|
+
agency_sdk/test/test_observability_packaging.py,sha256=0xjEdNrlFcOWcLHGFVCT8RC8HErtVTmIIib368G_rBg,2998
|
|
50
|
+
agency_sdk/test/test_observability_pipeline.py,sha256=RdfrCG-6uOhiO607bLXmXq1tO29UOPookwmE36CvyfM,8861
|
|
51
|
+
agency_sdk/test/test_ontology_client.py,sha256=54WhAWF4_IpmmVpCrPJ3VNFxFuhL_YB_kV53QYYTwx8,6143
|
|
52
|
+
agency_sdk/test/test_ontology_dto.py,sha256=1Q6Ck3zmW3VqeAACA1F-59DOD2I-BrnvB3ykyj9ZDKw,5446
|
|
53
|
+
agency_sdk/test/test_session_client.py,sha256=0nIcK6obEtWu5lv7gzMTA-RKisMb0nEZ6LvPoWF6PGw,4937
|
|
54
|
+
agency_sdk/test/test_session_dto.py,sha256=wvWiYeZXeSn4iuOv4hFfDk7B0enwBWg2wuOAI8Iuznk,2390
|
|
55
|
+
agency_sdk/test/test_session_templates_client.py,sha256=tu99IgJIK5F1Tjs6WkUA1bv3XWiWY-u_6iOfs-57-DY,1392
|
|
56
|
+
agency_sdk/test/test_session_templates_dto.py,sha256=qhzbQ7dcL5JC_ckBvmJKGlwthmJyzr4j7cM95ejw4u0,1575
|
|
57
|
+
agency_sdk/test/test_session_vault_client.py,sha256=EzxgMtfpn0rT2uQ2EMzEVWg25jxNdV5b3rz5KvOfzjw,5954
|
|
58
|
+
agency_sdk/test/test_session_vault_dto.py,sha256=K_nZCnxMmXAzCIiFCkSLW01MtUeT1L0omEIDh_2fxnM,913
|
|
59
|
+
agency_sdk/test/test_stub_requests.py,sha256=MHB7tSxxgzPfBflRqWnw6h1SCxJhVG0zThzGbRoaO8Y,1428
|
|
60
|
+
agency_sdk/test/test_work_queue_client.py,sha256=IMFUvs7TNRLN0fHq6lp1qIOrIeHnco4imtijZOaPXxc,17787
|
|
61
|
+
agency_sdk/test/test_work_queue_dto.py,sha256=PO1_k_0_y7Gxvevvz9KMxO-iZ8mLypcfx7QHVUIuUMg,8268
|
|
62
|
+
gts_agency_python_sdk-0.0.1.dist-info/licenses/LICENSE,sha256=infX_n3MKk2FGVxIaJ1CxIBNf3-fhofRllBaolLszMA,11355
|
|
63
|
+
gts_agency_python_sdk-0.0.1.dist-info/METADATA,sha256=eXryR5s-ertFSdrMDI7XGOljyLD4bN2big7PNL57MYI,8982
|
|
64
|
+
gts_agency_python_sdk-0.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
|
|
65
|
+
gts_agency_python_sdk-0.0.1.dist-info/top_level.txt,sha256=Q6dKhceE89aR7d3wpJpI7S8JKqHylYjUU-PY7Or1Wws,11
|
|
66
|
+
gts_agency_python_sdk-0.0.1.dist-info/RECORD,,
|