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,344 @@
1
+ """OTLP tracing/logging bootstrap, authenticated via the SDK credentials.
2
+
3
+ Construct via :meth:`agency_sdk.client.AgencyClient.observability`, which binds the
4
+ client's shared :class:`~agency_sdk.credentials.CredentialsSupplier` and defaults
5
+ the OTLP host to the client ``base_url``.
6
+
7
+ Heavy OpenTelemetry/Langfuse imports happen inside the lifecycle methods
8
+ (``init``/``langfuse_client``), never at module import or object construction, so
9
+ this module imports cleanly without the ``[observability]`` extra installed.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import atexit
15
+ import base64
16
+ import contextlib
17
+ import logging
18
+ from collections.abc import Iterator
19
+ from dataclasses import dataclass
20
+ from typing import TYPE_CHECKING, Any
21
+
22
+ from agency_sdk.observability.auth import BearerTokenAuth, make_httpx_bearer_auth
23
+
24
+ if TYPE_CHECKING:
25
+ from agency_sdk.credentials import CredentialsSupplier
26
+ from langfuse import Langfuse
27
+ from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
28
+ from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
29
+ from opentelemetry.sdk._logs import LoggerProvider
30
+ from opentelemetry.sdk._logs.export import LogRecordProcessor
31
+ from opentelemetry.sdk.trace import TracerProvider
32
+ from opentelemetry.sdk.trace.export import SpanProcessor
33
+ from opentelemetry.trace import Span, Tracer
34
+
35
+ # Langfuse's OTLP signal paths; overridable for other OTLP backends.
36
+ DEFAULT_LOGS_PATH = "/api/public/otel/v1/logs"
37
+ DEFAULT_TRACES_PATH = "/api/public/otel/v1/traces"
38
+
39
+ _DEFAULT_HTTP_TIMEOUT = 20.0
40
+
41
+
42
+ @dataclass
43
+ class TelemetryConfig:
44
+ """Telemetry export knobs for :class:`Observability` (everything but identity).
45
+
46
+ Grouped into one object so the bootstrap is constructed from
47
+ ``Observability(credentials, service_name, service_version, config=...)`` rather
48
+ than a long parameter list. ``AgencyClient.observability(...)`` builds this for
49
+ you from its curated keyword arguments.
50
+ """
51
+
52
+ host: str | None = None
53
+ environment: str = "development"
54
+ org_id: str = "2"
55
+ processor: str = "simple"
56
+ logs_path: str = DEFAULT_LOGS_PATH
57
+ traces_path: str = DEFAULT_TRACES_PATH
58
+ logs_endpoint: str | None = None
59
+ traces_endpoint: str | None = None
60
+ extra_headers: str | None = None
61
+ langfuse_public_key: str | None = None
62
+ langfuse_secret_key: str | None = None
63
+ langfuse_host: str | None = None
64
+
65
+
66
+ class Observability:
67
+ """Bootstraps OTLP log + trace export, authenticated via the SDK credentials.
68
+
69
+ The per-request OTLP/Langfuse auth hooks read their bearer token from the
70
+ shared ``CredentialsSupplier``, so one cached token serves both the API client
71
+ and the telemetry exporters. Export behaviour is configured via
72
+ :class:`TelemetryConfig`.
73
+ """
74
+
75
+ def __init__(
76
+ self,
77
+ credentials: CredentialsSupplier,
78
+ service_name: str,
79
+ service_version: str = "unknown-0",
80
+ *,
81
+ config: TelemetryConfig | None = None,
82
+ logger: logging.Logger | None = None,
83
+ ) -> None:
84
+ config = config if config is not None else TelemetryConfig()
85
+ self.credentials = credentials
86
+ self.service_name = service_name
87
+ self.service_version = service_version
88
+ self.config = config
89
+
90
+ # Unpacked for direct access in the hot paths below; the config object is the
91
+ # single source these are derived from.
92
+ self.host = config.host
93
+ self.environment = config.environment
94
+ self.org_id = config.org_id
95
+ self.processor = config.processor
96
+ self.logs_path = config.logs_path
97
+ self.traces_path = config.traces_path
98
+ self.logs_endpoint = config.logs_endpoint
99
+ self.traces_endpoint = config.traces_endpoint
100
+ self.extra_headers = config.extra_headers
101
+ self.langfuse_public_key = config.langfuse_public_key
102
+ self.langfuse_secret_key = config.langfuse_secret_key
103
+ self.langfuse_host = config.langfuse_host or config.host
104
+ self.logger = logger or logging.getLogger(__name__)
105
+
106
+ self._tracer_provider: TracerProvider | None = None
107
+ self._logger_provider: LoggerProvider | None = None
108
+ self._tracer: Tracer | None = None
109
+ self._log_handler: logging.Handler | None = None
110
+
111
+ # -- auth / header / endpoint helpers -------------------------------------
112
+
113
+ def _safe_token(self) -> str | None:
114
+ """Return a fresh bearer token from the shared credentials, or None.
115
+
116
+ Never raises: a transient auth failure degrades to an untraced export
117
+ rather than crashing the exporter, so observability stays best-effort.
118
+ """
119
+ try:
120
+ return self.credentials.bearer_token()
121
+ except Exception as exc: # noqa: BLE001 - observability must not crash the caller
122
+ self.logger.warning("Observability token fetch failed: %s", exc)
123
+ return None
124
+
125
+ def build_headers(self) -> dict[str, str]:
126
+ """Static OTLP headers including the seed Authorization.
127
+
128
+ Precedence: an explicit ``Authorization`` in ``extra_headers`` > a bearer
129
+ token from the shared credentials > Langfuse Basic (base64 of
130
+ ``public:secret``). When credentials are active, the per-request auth hook
131
+ refreshes the header on every export; this static value is only the seed.
132
+ ``x-org-id`` is always set.
133
+ """
134
+ headers: dict[str, str] = {}
135
+
136
+ if self.extra_headers:
137
+ for item in self.extra_headers.split(","):
138
+ if "=" in item:
139
+ key, value = item.split("=", 1)
140
+ headers[key.strip()] = value.strip()
141
+
142
+ if "Authorization" not in headers:
143
+ token = self._safe_token()
144
+ if token:
145
+ headers["Authorization"] = f"Bearer {token}"
146
+
147
+ if "Authorization" not in headers and self.langfuse_public_key and self.langfuse_secret_key:
148
+ auth_b64 = base64.b64encode(
149
+ f"{self.langfuse_public_key}:{self.langfuse_secret_key}".encode("utf-8")
150
+ ).decode("utf-8")
151
+ headers["Authorization"] = f"Bearer {auth_b64}"
152
+
153
+ headers["x-org-id"] = self.org_id
154
+ return headers
155
+
156
+ def _resolve_endpoint(self, explicit: str | None, path: str) -> str | None:
157
+ """An explicit per-signal endpoint wins; else ``host`` + the signal path."""
158
+ if explicit:
159
+ return explicit
160
+ if self.host:
161
+ return self.host if self.host.endswith(path) else self.host.rstrip("/") + path
162
+ return None
163
+
164
+ # -- exporter / processor construction ------------------------------------
165
+
166
+ def _exporter_kwargs(self, endpoint: str | None) -> dict[str, Any]:
167
+ kwargs: dict[str, Any] = {}
168
+ if endpoint:
169
+ kwargs["endpoint"] = endpoint
170
+ headers = self.build_headers()
171
+ if headers:
172
+ kwargs["headers"] = headers
173
+ return kwargs
174
+
175
+ def _attach_dynamic_auth(self, exporter: Any) -> None:
176
+ """Refresh the bearer token on every export for this exporter (Mechanism 2).
177
+
178
+ OTLP HTTP exporters freeze their static headers into a ``requests.Session``;
179
+ ``requests`` calls ``session.auth`` on every request, so routing the token
180
+ through :class:`BearerTokenAuth` keeps a long-running process from sending an
181
+ expired token.
182
+ """
183
+ session = getattr(exporter, "_session", None)
184
+ if session is not None:
185
+ session.auth = BearerTokenAuth(self._safe_token)
186
+
187
+ def make_span_exporter(self) -> OTLPSpanExporter:
188
+ """An OTLP span exporter for the traces endpoint, with refreshing auth."""
189
+ from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
190
+
191
+ endpoint = self._resolve_endpoint(self.traces_endpoint, self.traces_path)
192
+ exporter = OTLPSpanExporter(**self._exporter_kwargs(endpoint))
193
+ self._attach_dynamic_auth(exporter)
194
+ return exporter
195
+
196
+ def make_log_exporter(self) -> OTLPLogExporter:
197
+ """An OTLP log exporter for the logs endpoint, with refreshing auth."""
198
+ from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
199
+
200
+ endpoint = self._resolve_endpoint(self.logs_endpoint, self.logs_path)
201
+ exporter = OTLPLogExporter(**self._exporter_kwargs(endpoint))
202
+ self._attach_dynamic_auth(exporter)
203
+ return exporter
204
+
205
+ def _make_span_processor(self, exporter: Any) -> SpanProcessor:
206
+ from opentelemetry.sdk.trace.export import BatchSpanProcessor, SimpleSpanProcessor
207
+
208
+ if self.processor == "batch":
209
+ return BatchSpanProcessor(exporter)
210
+ return SimpleSpanProcessor(exporter)
211
+
212
+ def _make_log_processor(self, exporter: Any) -> LogRecordProcessor:
213
+ from opentelemetry.sdk._logs.export import BatchLogRecordProcessor, SimpleLogRecordProcessor
214
+
215
+ if self.processor == "batch":
216
+ return BatchLogRecordProcessor(exporter)
217
+ return SimpleLogRecordProcessor(exporter)
218
+
219
+ # -- lifecycle ------------------------------------------------------------
220
+
221
+ @property
222
+ def tracer_provider(self) -> TracerProvider | None:
223
+ return self._tracer_provider
224
+
225
+ def init(self) -> Tracer | None:
226
+ """Configure OTLP log + trace export and return a tracer for manual spans.
227
+
228
+ Builds a real recording ``TracerProvider`` and a ``LoggerProvider`` (both
229
+ held explicitly, not registered globally — correlation is driven by the OTel
230
+ context), bridges stdlib logging to OTLP via ``LoggingInstrumentor`` + a root
231
+ ``LoggingHandler`` so log records carry the active span's trace/span ids, and
232
+ returns the tracer. Returns ``None`` if exporter setup fails so the caller
233
+ keeps running untraced rather than crashing.
234
+ """
235
+ from opentelemetry.instrumentation.logging import LoggingInstrumentor
236
+ from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
237
+ from opentelemetry.sdk.resources import Resource
238
+ from opentelemetry.sdk.trace import TracerProvider
239
+
240
+ resource = Resource.create(
241
+ {
242
+ "service.name": self.service_name,
243
+ "service.version": self.service_version,
244
+ "deployment.environment": self.environment,
245
+ }
246
+ )
247
+
248
+ # Build exporters and providers first; any failure leaves us fully untraced
249
+ # with no global side effects (no instrumentation, no root handler).
250
+ try:
251
+ log_exporter = self.make_log_exporter()
252
+ span_exporter = self.make_span_exporter()
253
+ # shutdown_on_exit=False: the providers' own atexit hooks would fire
254
+ # alongside (and after) ours, re-shutting them down. We own the lifecycle
255
+ # via the single idempotent self.shutdown registered below.
256
+ logger_provider = LoggerProvider(resource=resource, shutdown_on_exit=False)
257
+ logger_provider.add_log_record_processor(self._make_log_processor(log_exporter))
258
+ tracer_provider = TracerProvider(resource=resource, shutdown_on_exit=False)
259
+ tracer_provider.add_span_processor(self._make_span_processor(span_exporter))
260
+ except Exception as exc: # noqa: BLE001 - observability must not crash the caller
261
+ self.logger.warning("Failed to initialize OTLP exporters: %s", exc)
262
+ return None
263
+
264
+ self._logger_provider = logger_provider
265
+ self._tracer_provider = tracer_provider
266
+ # Drive shutdown through the (idempotent) instance method, not the raw
267
+ # providers, so an explicit shutdown() plus this atexit hook never close a
268
+ # provider twice.
269
+ atexit.register(self.shutdown)
270
+
271
+ # LoggingInstrumentor injects trace/span ids into stdlib LogRecords; the
272
+ # LoggingHandler exports those records to the LoggerProvider. Both read the
273
+ # active span from the OTel context at emit time (so a span must be active).
274
+ LoggingInstrumentor().instrument()
275
+ handler = LoggingHandler(level=logging.NOTSET, logger_provider=logger_provider)
276
+ logging.getLogger().addHandler(handler)
277
+ self._log_handler = handler
278
+
279
+ self._tracer = tracer_provider.get_tracer(self.service_name)
280
+ return self._tracer
281
+
282
+ @contextlib.contextmanager
283
+ def agent_run(self, name: str, **attributes: Any) -> Iterator[Span | None]:
284
+ """Open a recording root span for an agent run (Mechanism 5).
285
+
286
+ Encodes the "open a root span first" rule so logs and child spans created
287
+ inside the block correlate under one trace. Degrades to a no-op yielding
288
+ ``None`` when tracing is off (``init`` not called or returned ``None``), so
289
+ the same ``with`` block runs untraced rather than crashing.
290
+ """
291
+ if self._tracer is None:
292
+ yield None
293
+ return
294
+ with self._tracer.start_as_current_span(name) as span:
295
+ for key, value in attributes.items():
296
+ span.set_attribute(key, value)
297
+ yield span
298
+
299
+ def langfuse_client(self) -> Langfuse | None:
300
+ """Construct a Langfuse client authenticated like the exporters (or None).
301
+
302
+ Returns ``None`` when the project keys or the ``langfuse`` package are
303
+ absent. Otherwise both the Langfuse transport and its span exporter are
304
+ routed through the shared refreshing bearer token, so prompt management /
305
+ scoring authenticate with the same credentials as the OTLP exporters.
306
+ """
307
+ if not (self.langfuse_public_key and self.langfuse_secret_key):
308
+ return None
309
+ try:
310
+ import httpx
311
+ from langfuse import Langfuse
312
+ except Exception as exc: # noqa: BLE001 - missing optional package degrades to None
313
+ self.logger.warning("Langfuse client unavailable: %s", exc)
314
+ return None
315
+
316
+ httpx_client = httpx.Client(
317
+ timeout=_DEFAULT_HTTP_TIMEOUT,
318
+ auth=make_httpx_bearer_auth(self._safe_token),
319
+ )
320
+ return Langfuse(
321
+ public_key=self.langfuse_public_key,
322
+ secret_key=self.langfuse_secret_key,
323
+ host=self.langfuse_host,
324
+ httpx_client=httpx_client,
325
+ span_exporter=self.make_span_exporter(),
326
+ )
327
+
328
+ def shutdown(self) -> None:
329
+ """Detach the log handler and flush/close both providers.
330
+
331
+ Idempotent: provider references are cleared after the first shutdown, so a
332
+ second explicit call and the atexit hook registered in :meth:`init` are both
333
+ no-ops rather than shutting a provider down twice.
334
+ """
335
+ if self._log_handler is not None:
336
+ logging.getLogger().removeHandler(self._log_handler)
337
+ self._log_handler = None
338
+ if self._logger_provider is not None:
339
+ self._logger_provider.shutdown()
340
+ self._logger_provider = None
341
+ if self._tracer_provider is not None:
342
+ self._tracer_provider.shutdown()
343
+ self._tracer_provider = None
344
+ self._tracer = None
File without changes
@@ -0,0 +1,106 @@
1
+ """Shared offline fixtures for client tests.
2
+
3
+ All unit tests run without network access: `stub_requests` monkeypatches the
4
+ `requests` entry points the SDK uses (`requests.request`, `requests.get`,
5
+ `requests.post`) with a recorder that captures every call and replays queued
6
+ canned responses.
7
+ """
8
+
9
+ from dataclasses import dataclass, field
10
+ from typing import Any
11
+
12
+ import pytest
13
+ import requests
14
+
15
+
16
+ class StubResponse:
17
+ """Minimal stand-in for `requests.Response`."""
18
+
19
+ def __init__(
20
+ self,
21
+ json_data: Any = None,
22
+ status_code: int = 200,
23
+ content_bytes: bytes | None = None,
24
+ text: str | None = None,
25
+ ):
26
+ self.status_code = status_code
27
+ self._json = json_data
28
+ if content_bytes is not None:
29
+ self.content = content_bytes
30
+ elif json_data is not None:
31
+ self.content = b"json" # truthy marker; clients only check truthiness
32
+ else:
33
+ self.content = b""
34
+ self.text = text if text is not None else ""
35
+
36
+ def json(self) -> Any:
37
+ return self._json
38
+
39
+ def raise_for_status(self) -> None:
40
+ if self.status_code >= 400:
41
+ raise requests.HTTPError(f"{self.status_code} error", response=self)
42
+
43
+ def iter_content(self, chunk_size: int = 8192):
44
+ for i in range(0, len(self.content), chunk_size):
45
+ yield self.content[i : i + chunk_size]
46
+
47
+ def iter_lines(self, chunk_size: int = 512, decode_unicode: bool = False, delimiter=None):
48
+ """Line-wise replay of `content` (SSE streaming tests); mirrors requests semantics."""
49
+ data = self.content.decode() if decode_unicode else self.content
50
+ yield from (data.split(delimiter) if delimiter is not None else data.splitlines())
51
+
52
+ def close(self) -> None:
53
+ self.closed = True # streaming clients must close the response; tests assert this
54
+
55
+
56
+ @dataclass
57
+ class CapturedCall:
58
+ method: str
59
+ url: str
60
+ kwargs: dict[str, Any] = field(default_factory=dict)
61
+
62
+
63
+ class RequestRecorder:
64
+ """Captures calls to the requests library and replays queued responses."""
65
+
66
+ def __init__(self):
67
+ self.calls: list[CapturedCall] = []
68
+ self._responses: list[StubResponse] = []
69
+
70
+ def queue(
71
+ self,
72
+ json_data: Any = None,
73
+ status_code: int = 200,
74
+ content_bytes: bytes | None = None,
75
+ text: str | None = None,
76
+ ) -> StubResponse:
77
+ response = StubResponse(json_data=json_data, status_code=status_code, content_bytes=content_bytes, text=text)
78
+ self._responses.append(response)
79
+ return response
80
+
81
+ def __call__(self, method: str, url: str, **kwargs: Any) -> StubResponse:
82
+ self.calls.append(CapturedCall(method=method, url=url, kwargs=kwargs))
83
+ if not self._responses:
84
+ raise AssertionError(f"No stub response queued for {method} {url}")
85
+ return self._responses.pop(0)
86
+
87
+
88
+ class FakeCredentials:
89
+ """Duck-typed CredentialsSupplier returning a static token, no network."""
90
+
91
+ def bearer_token(self) -> str:
92
+ return "test-token"
93
+
94
+
95
+ @pytest.fixture
96
+ def stub_requests(monkeypatch):
97
+ recorder = RequestRecorder()
98
+ monkeypatch.setattr(requests, "request", recorder)
99
+ monkeypatch.setattr(requests, "get", lambda url, **kw: recorder(method="GET", url=url, **kw))
100
+ monkeypatch.setattr(requests, "post", lambda url, **kw: recorder(method="POST", url=url, **kw))
101
+ return recorder
102
+
103
+
104
+ @pytest.fixture
105
+ def fake_credentials():
106
+ return FakeCredentials()