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
agency_sdk/__init__.py ADDED
File without changes
@@ -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