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
agency_sdk/__init__.py
ADDED
|
File without changes
|
agency_sdk/auth_hooks.py
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
"""Per-request bearer-token auth hooks, shared across the SDK.
|
|
2
|
+
|
|
3
|
+
A static ``Authorization`` header set at client construction goes stale: the
|
|
4
|
+
Keycloak m2m JWT rotates, and long-running clients (OTLP exporters, the gateway
|
|
5
|
+
``openai`` client) freeze whatever was set at build time. Both ``requests`` and
|
|
6
|
+
``httpx`` instead invoke their ``auth`` callable on *every* request, so routing
|
|
7
|
+
the token through these hooks means each request re-reads the (auto-refreshing,
|
|
8
|
+
cached) token and never sends an expired one.
|
|
9
|
+
|
|
10
|
+
Dependency-light on purpose so any consumer can reuse it: only core ``requests``
|
|
11
|
+
at import time; ``httpx`` is imported lazily inside :func:`make_httpx_bearer_auth`
|
|
12
|
+
(it arrives with the ``[observability]`` or ``[openai]`` extras).
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
from typing import TYPE_CHECKING, Any, Callable
|
|
18
|
+
|
|
19
|
+
import requests.auth
|
|
20
|
+
|
|
21
|
+
if TYPE_CHECKING:
|
|
22
|
+
import httpx
|
|
23
|
+
|
|
24
|
+
# A callable returning a fresh bearer token, or None when unavailable.
|
|
25
|
+
TokenSupplier = Callable[[], "str | None"]
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class BearerTokenAuth(requests.auth.AuthBase):
|
|
29
|
+
"""requests per-request auth that stamps a fresh bearer token on every call."""
|
|
30
|
+
|
|
31
|
+
def __init__(self, token_supplier: TokenSupplier) -> None:
|
|
32
|
+
self._token_supplier = token_supplier
|
|
33
|
+
|
|
34
|
+
def __call__(self, request: Any) -> Any:
|
|
35
|
+
token = self._token_supplier()
|
|
36
|
+
if token:
|
|
37
|
+
request.headers["Authorization"] = f"Bearer {token}"
|
|
38
|
+
return request
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def make_httpx_bearer_auth(token_supplier: TokenSupplier) -> "httpx.Auth":
|
|
42
|
+
"""Build an ``httpx.Auth`` mirroring :class:`BearerTokenAuth` (lazy httpx import)."""
|
|
43
|
+
import httpx
|
|
44
|
+
|
|
45
|
+
class _HttpxBearerAuth(httpx.Auth):
|
|
46
|
+
def __init__(self, supplier: TokenSupplier) -> None:
|
|
47
|
+
self._token_supplier = supplier
|
|
48
|
+
|
|
49
|
+
def auth_flow(self, request: Any) -> Any:
|
|
50
|
+
token = self._token_supplier()
|
|
51
|
+
if token:
|
|
52
|
+
request.headers["Authorization"] = f"Bearer {token}"
|
|
53
|
+
yield request
|
|
54
|
+
|
|
55
|
+
return _HttpxBearerAuth(token_supplier)
|
agency_sdk/client.py
ADDED
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
import threading
|
|
2
|
+
from typing import TYPE_CHECKING
|
|
3
|
+
|
|
4
|
+
import requests
|
|
5
|
+
|
|
6
|
+
from agency_sdk.credentials import CredentialsSupplier
|
|
7
|
+
from agency_sdk.delegates.annotations_client import AgencyAnnotationsClient
|
|
8
|
+
from agency_sdk.delegates.datasets_client import AgencyDatasetsClient
|
|
9
|
+
from agency_sdk.delegates.datasource_client import AgencyDatasourceClient
|
|
10
|
+
from agency_sdk.delegates.files_client import AgencyFilesClient
|
|
11
|
+
from agency_sdk.delegates.ontology_client import AgencyOntologyClient
|
|
12
|
+
from agency_sdk.delegates.prompts_client import AgencyPromptsClient
|
|
13
|
+
from agency_sdk.delegates.rules_client import AgencyRulesClient
|
|
14
|
+
from agency_sdk.delegates.session_client import AgencySessionClient
|
|
15
|
+
from agency_sdk.delegates.session_templates_client import AgencySessionTemplatesClient
|
|
16
|
+
from agency_sdk.delegates.session_vault_client import AgencySessionVaultClient
|
|
17
|
+
from agency_sdk.delegates.work_queue_client import AgencyWorkQueueClient
|
|
18
|
+
|
|
19
|
+
if TYPE_CHECKING:
|
|
20
|
+
from agency_sdk.delegates.gateway_client import AgencyGatewayClient
|
|
21
|
+
from agency_sdk.observability import Observability
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class AgencyClient:
|
|
25
|
+
def __init__(
|
|
26
|
+
self,
|
|
27
|
+
token_supplier: CredentialsSupplier,
|
|
28
|
+
base_url: str = "http://localhost:9003",
|
|
29
|
+
):
|
|
30
|
+
self.base_url = base_url.rstrip("/")
|
|
31
|
+
self.token_supplier = token_supplier
|
|
32
|
+
self.dataset_client = AgencyDatasetsClient(token_supplier=token_supplier, base_url=self.base_url)
|
|
33
|
+
self.datasource_client = AgencyDatasourceClient(token_supplier=token_supplier, base_url=self.base_url)
|
|
34
|
+
self.ontology_client = AgencyOntologyClient(token_supplier=token_supplier, base_url=self.base_url)
|
|
35
|
+
self.prompt_client = AgencyPromptsClient(token_supplier=token_supplier, base_url=self.base_url)
|
|
36
|
+
self.rules_client = AgencyRulesClient(token_supplier=token_supplier, base_url=self.base_url)
|
|
37
|
+
self.files_client = AgencyFilesClient(token_supplier=token_supplier, base_url=self.base_url)
|
|
38
|
+
self.session_vault_client = AgencySessionVaultClient(token_supplier=token_supplier, base_url=self.base_url)
|
|
39
|
+
self.work_queue_client = AgencyWorkQueueClient(token_supplier=token_supplier, base_url=self.base_url)
|
|
40
|
+
self.session_client = AgencySessionClient(token_supplier=token_supplier, base_url=self.base_url)
|
|
41
|
+
self.session_templates_client = AgencySessionTemplatesClient(
|
|
42
|
+
token_supplier=token_supplier, base_url=self.base_url
|
|
43
|
+
)
|
|
44
|
+
self.annotations_client = AgencyAnnotationsClient(token_supplier=token_supplier, base_url=self.base_url)
|
|
45
|
+
self._observability: "Observability | None" = None
|
|
46
|
+
self._observability_lock = threading.Lock()
|
|
47
|
+
self._gateway_clients: "dict[tuple[str, str | None, str | None], AgencyGatewayClient]" = {}
|
|
48
|
+
self._gateway_lock = threading.Lock()
|
|
49
|
+
|
|
50
|
+
def prompts(self) -> AgencyPromptsClient:
|
|
51
|
+
return self.prompt_client
|
|
52
|
+
|
|
53
|
+
def dataset(self) -> AgencyDatasetsClient:
|
|
54
|
+
return self.dataset_client
|
|
55
|
+
|
|
56
|
+
def datasource(self) -> AgencyDatasourceClient:
|
|
57
|
+
return self.datasource_client
|
|
58
|
+
|
|
59
|
+
def ontology(self) -> AgencyOntologyClient:
|
|
60
|
+
return self.ontology_client
|
|
61
|
+
|
|
62
|
+
def rules(self) -> AgencyRulesClient:
|
|
63
|
+
return self.rules_client
|
|
64
|
+
|
|
65
|
+
def files(self) -> AgencyFilesClient:
|
|
66
|
+
return self.files_client
|
|
67
|
+
|
|
68
|
+
def session_vault(self) -> AgencySessionVaultClient:
|
|
69
|
+
return self.session_vault_client
|
|
70
|
+
|
|
71
|
+
def work_queues(self) -> AgencyWorkQueueClient:
|
|
72
|
+
return self.work_queue_client
|
|
73
|
+
|
|
74
|
+
def sessions(self) -> AgencySessionClient:
|
|
75
|
+
return self.session_client
|
|
76
|
+
|
|
77
|
+
def session_templates(self) -> AgencySessionTemplatesClient:
|
|
78
|
+
return self.session_templates_client
|
|
79
|
+
|
|
80
|
+
def annotations(self) -> AgencyAnnotationsClient:
|
|
81
|
+
return self.annotations_client
|
|
82
|
+
|
|
83
|
+
def gateway(
|
|
84
|
+
self,
|
|
85
|
+
*,
|
|
86
|
+
org_id: str,
|
|
87
|
+
gateway_base_url: str | None = None,
|
|
88
|
+
environment: str | None = None,
|
|
89
|
+
) -> "AgencyGatewayClient":
|
|
90
|
+
"""Build (or reuse) an OpenAI-compatible LLM gateway client bound to this client.
|
|
91
|
+
|
|
92
|
+
Targets the org's agentgateway Cloud Run host — never this client's
|
|
93
|
+
control-plane ``base_url`` — reusing the shared ``CredentialsSupplier``
|
|
94
|
+
as the gateway Bearer and stamping the ``x-org`` routing header.
|
|
95
|
+
Instances are cached per identity — ``(org_id, gateway_base_url)`` or
|
|
96
|
+
``(org_id, environment)`` — so repeated calls with the same arguments
|
|
97
|
+
return the same instance, while a different org, environment, or URL
|
|
98
|
+
builds its own correctly routed client (never the first caller's).
|
|
99
|
+
|
|
100
|
+
Either give the URL, or give the environment — never both:
|
|
101
|
+
|
|
102
|
+
- ``gateway_base_url`` set: use it directly (``environment`` must be omitted).
|
|
103
|
+
- ``gateway_base_url`` omitted: resolve the URL once per identity from
|
|
104
|
+
``GET /api/agentgateways?o={org_id}`` on the control-plane ``base_url``,
|
|
105
|
+
selecting the ``production`` (default) or ``test`` slot per ``environment``.
|
|
106
|
+
"""
|
|
107
|
+
from agency_sdk.delegates.gateway_client import AgencyGatewayClient
|
|
108
|
+
|
|
109
|
+
if gateway_base_url is not None and environment is not None:
|
|
110
|
+
raise ValueError("environment is only used with URL discovery; omit it when gateway_base_url is given")
|
|
111
|
+
key: tuple[str, str | None, str | None]
|
|
112
|
+
if gateway_base_url is not None:
|
|
113
|
+
key = (org_id, gateway_base_url.rstrip("/"), None)
|
|
114
|
+
else:
|
|
115
|
+
key = (org_id, None, environment or "production")
|
|
116
|
+
gateway = self._gateway_clients.get(key)
|
|
117
|
+
if gateway is None:
|
|
118
|
+
# Double-checked locking, mirroring observability(): one build per
|
|
119
|
+
# identity, repeated/concurrent callers share the same instance.
|
|
120
|
+
with self._gateway_lock:
|
|
121
|
+
gateway = self._gateway_clients.get(key)
|
|
122
|
+
if gateway is None:
|
|
123
|
+
url = gateway_base_url or self._discover_gateway_url(org_id, environment or "production")
|
|
124
|
+
gateway = AgencyGatewayClient(
|
|
125
|
+
token_supplier=self.token_supplier,
|
|
126
|
+
gateway_base_url=url,
|
|
127
|
+
org_id=org_id,
|
|
128
|
+
)
|
|
129
|
+
self._gateway_clients[key] = gateway
|
|
130
|
+
return gateway
|
|
131
|
+
|
|
132
|
+
def _discover_gateway_url(self, org_id: str, environment: str) -> str:
|
|
133
|
+
"""Resolve the gateway URL for ``environment`` from the control plane.
|
|
134
|
+
|
|
135
|
+
Reads the ``production.url`` / ``test.url`` slot of the org's gateway
|
|
136
|
+
status (``AgentGatewayStatusResponse``). Live-verified 2026-07-07: the
|
|
137
|
+
endpoint returns a Page-wrapped ``{"page": ..., "items": [...]}``
|
|
138
|
+
payload (the bare-list branch below is a defensive fallback).
|
|
139
|
+
"""
|
|
140
|
+
from agency_sdk.delegates.gateway_dto import AgentGatewayStatusResponse
|
|
141
|
+
|
|
142
|
+
if environment not in ("production", "test"):
|
|
143
|
+
raise ValueError(f"environment must be 'production' or 'test', got {environment!r}")
|
|
144
|
+
response = requests.get(
|
|
145
|
+
f"{self.base_url}/api/agentgateways",
|
|
146
|
+
headers={"Authorization": f"Bearer {self.token_supplier.bearer_token()}"},
|
|
147
|
+
params={"o": org_id},
|
|
148
|
+
timeout=30,
|
|
149
|
+
)
|
|
150
|
+
response.raise_for_status()
|
|
151
|
+
data = response.json()
|
|
152
|
+
items = data.get("items", []) if isinstance(data, dict) else data
|
|
153
|
+
if not items:
|
|
154
|
+
raise ValueError(f"no agent gateway found for org {org_id}; is the gateway enabled?")
|
|
155
|
+
status = AgentGatewayStatusResponse(**items[0])
|
|
156
|
+
slot = status.production if environment == "production" else status.test
|
|
157
|
+
if slot is None or not slot.url:
|
|
158
|
+
raise ValueError(
|
|
159
|
+
f"agent gateway {environment} URL not available for org {org_id} "
|
|
160
|
+
f"(enabled={status.enabled}); pass gateway_base_url explicitly"
|
|
161
|
+
)
|
|
162
|
+
return slot.url
|
|
163
|
+
|
|
164
|
+
def observability(
|
|
165
|
+
self,
|
|
166
|
+
service_name: str,
|
|
167
|
+
service_version: str = "unknown-0",
|
|
168
|
+
*,
|
|
169
|
+
host: str | None = None,
|
|
170
|
+
environment: str = "development",
|
|
171
|
+
org_id: str = "2",
|
|
172
|
+
processor: str = "simple",
|
|
173
|
+
langfuse_public_key: str | None = None,
|
|
174
|
+
langfuse_secret_key: str | None = None,
|
|
175
|
+
) -> "Observability":
|
|
176
|
+
"""Build (once) the OTLP observability bootstrap bound to this client.
|
|
177
|
+
|
|
178
|
+
Reuses the client's shared ``CredentialsSupplier`` so a single cached
|
|
179
|
+
token serves both the API client and the telemetry exporters, and
|
|
180
|
+
defaults the OTLP/Langfuse host to this client's ``base_url``. Repeated
|
|
181
|
+
calls return the same instance.
|
|
182
|
+
|
|
183
|
+
Requires the optional ``[observability]`` extra; raises
|
|
184
|
+
``ObservabilityNotInstalled`` (an ``ImportError``) with an install hint
|
|
185
|
+
when it is absent.
|
|
186
|
+
"""
|
|
187
|
+
from agency_sdk.observability import Observability, TelemetryConfig, require_observability_deps
|
|
188
|
+
|
|
189
|
+
require_observability_deps()
|
|
190
|
+
observability = self._observability
|
|
191
|
+
if observability is None:
|
|
192
|
+
# Double-checked locking: serialize concurrent first-time builds so a
|
|
193
|
+
# single Observability is constructed and cached (repeated calls return
|
|
194
|
+
# the same instance, even under concurrency).
|
|
195
|
+
with self._observability_lock:
|
|
196
|
+
observability = self._observability
|
|
197
|
+
if observability is None:
|
|
198
|
+
observability = Observability(
|
|
199
|
+
credentials=self.token_supplier,
|
|
200
|
+
service_name=service_name,
|
|
201
|
+
service_version=service_version,
|
|
202
|
+
config=TelemetryConfig(
|
|
203
|
+
host=host or self.base_url,
|
|
204
|
+
environment=environment,
|
|
205
|
+
org_id=org_id,
|
|
206
|
+
processor=processor,
|
|
207
|
+
langfuse_public_key=langfuse_public_key,
|
|
208
|
+
langfuse_secret_key=langfuse_secret_key,
|
|
209
|
+
),
|
|
210
|
+
)
|
|
211
|
+
self._observability = observability
|
|
212
|
+
return observability
|
|
@@ -0,0 +1,54 @@
|
|
|
1
|
+
import time
|
|
2
|
+
|
|
3
|
+
import jwt
|
|
4
|
+
import requests
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
class CredentialsSupplier:
|
|
8
|
+
def __init__(
|
|
9
|
+
self,
|
|
10
|
+
auth_base_url: str,
|
|
11
|
+
client_id: str,
|
|
12
|
+
client_secret: str,
|
|
13
|
+
*,
|
|
14
|
+
refresh_buffer: float = 30.0,
|
|
15
|
+
):
|
|
16
|
+
self.auth_base_url = auth_base_url.rstrip("/")
|
|
17
|
+
self.client_id = client_id
|
|
18
|
+
self.client_secret = client_secret
|
|
19
|
+
# Refresh this many seconds before the real expiry so a token is never
|
|
20
|
+
# used mid-flight. Matters for the observability OTLP per-request auth
|
|
21
|
+
# hook, which re-reads this token on every export in a long-running
|
|
22
|
+
# process.
|
|
23
|
+
self.refresh_buffer = refresh_buffer
|
|
24
|
+
self._cached_token: str | None = None
|
|
25
|
+
|
|
26
|
+
def bearer_token(self) -> str:
|
|
27
|
+
"""Get OAuth2 bearer token using client credentials flow."""
|
|
28
|
+
if self._cached_token and not self._is_token_expired():
|
|
29
|
+
return self._cached_token
|
|
30
|
+
|
|
31
|
+
form_data = {
|
|
32
|
+
"grant_type": "client_credentials",
|
|
33
|
+
"client_id": self.client_id,
|
|
34
|
+
"client_secret": self.client_secret,
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
response = requests.post(self.auth_base_url, data=form_data, timeout=30)
|
|
38
|
+
response.raise_for_status()
|
|
39
|
+
|
|
40
|
+
token_data = response.json()
|
|
41
|
+
token: str = token_data["access_token"]
|
|
42
|
+
self._cached_token = token
|
|
43
|
+
return token
|
|
44
|
+
|
|
45
|
+
def _is_token_expired(self) -> bool:
|
|
46
|
+
"""Check if the cached token is expired."""
|
|
47
|
+
if not self._cached_token:
|
|
48
|
+
return True
|
|
49
|
+
|
|
50
|
+
try:
|
|
51
|
+
decoded = jwt.decode(self._cached_token, options={"verify_signature": False})
|
|
52
|
+
return bool(decoded.get("exp", 0) <= time.time() + self.refresh_buffer)
|
|
53
|
+
except Exception:
|
|
54
|
+
return True
|
|
File without changes
|