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,76 @@
1
+ """Tests for the openai-client factory on AgencyGatewayClient.
2
+
3
+ The gateway hands back STANDARD openai clients wired to the gateway: base_url on
4
+ the gateway host (``/v1``), the ``x-org`` routing header as a default header, and
5
+ an httpx auth hook that stamps a fresh rotating bearer on every request (the
6
+ construction-time ``api_key`` is a placeholder — verified live 2026-07-07 that
7
+ the per-request Authorization override wins). ``openai`` is a core dependency, so
8
+ these tests import it directly (a missing core dep fails the module import).
9
+ """
10
+
11
+ import builtins
12
+
13
+ import httpx
14
+ import openai
15
+
16
+ from agency_sdk.delegates.gateway_client import AgencyGatewayClient
17
+
18
+ import pytest
19
+
20
+
21
+ @pytest.fixture
22
+ def client(fake_credentials):
23
+ return AgencyGatewayClient(
24
+ token_supplier=fake_credentials,
25
+ gateway_base_url="http://gw.test:4000/",
26
+ org_id="2",
27
+ )
28
+
29
+
30
+ def _assert_rotating_auth(httpx_client) -> None:
31
+ """The wired httpx client must stamp a fresh bearer per request via auth_flow."""
32
+ auth = httpx_client.auth
33
+ assert isinstance(auth, httpx.Auth)
34
+ request = httpx.Request("POST", "http://gw.test:4000/v1/chat/completions")
35
+ next(auth.auth_flow(request))
36
+ assert request.headers["Authorization"] == "Bearer test-token" # from FakeCredentials
37
+
38
+
39
+ def test_openai_client_is_wired_to_gateway(client):
40
+ oai = client.openai_client(max_retries=0)
41
+
42
+ assert isinstance(oai, openai.OpenAI)
43
+ assert str(oai.base_url) == "http://gw.test:4000/v1/" # gateway host, /v1 path
44
+ assert oai.default_headers.get("x-org") == "2"
45
+ assert oai.max_retries == 0 # caller kwargs pass through
46
+ _assert_rotating_auth(oai._client)
47
+
48
+
49
+ def test_async_openai_client_is_wired_to_gateway(client):
50
+ aoai = client.async_openai_client()
51
+
52
+ assert isinstance(aoai, openai.AsyncOpenAI)
53
+ assert str(aoai.base_url) == "http://gw.test:4000/v1/"
54
+ assert aoai.default_headers.get("x-org") == "2"
55
+ _assert_rotating_auth(aoai._client)
56
+
57
+
58
+ def test_openai_clients_are_independent_instances(client):
59
+ assert client.openai_client() is not client.openai_client() # no cache: caller owns lifecycle
60
+
61
+
62
+ def test_openai_helper_auth_does_not_import_observability(client, monkeypatch):
63
+ # M1: the gateway's rotating-bearer auth comes from the neutral core module
64
+ # agency_sdk.auth_hooks, NOT the optional observability submodule. Block that
65
+ # submodule entirely and the helper must still build a working auth hook.
66
+ real_import = builtins.__import__
67
+
68
+ def block_observability(name, *args, **kwargs):
69
+ if name.startswith("agency_sdk.observability"):
70
+ raise ImportError(f"observability blocked: {name}")
71
+ return real_import(name, *args, **kwargs)
72
+
73
+ monkeypatch.setattr(builtins, "__import__", block_observability)
74
+
75
+ oai = client.openai_client(max_retries=0) # must not reach into observability
76
+ _assert_rotating_auth(oai._client)
@@ -0,0 +1,125 @@
1
+ """Phase 3: per-request bearer hooks, header precedence, endpoint resolution.
2
+
3
+ All offline. The auth hooks must stamp a *fresh* token on every call (so a
4
+ long-running export never sends an expired one), and ``build_headers`` must
5
+ resolve the Authorization header in the documented precedence order.
6
+ """
7
+
8
+ import base64
9
+
10
+ import pytest
11
+
12
+ from agency_sdk.observability.auth import BearerTokenAuth, make_httpx_bearer_auth
13
+ from agency_sdk.observability.bootstrap import (
14
+ DEFAULT_LOGS_PATH,
15
+ DEFAULT_TRACES_PATH,
16
+ Observability,
17
+ TelemetryConfig,
18
+ )
19
+
20
+
21
+ class _FakeRequest:
22
+ def __init__(self) -> None:
23
+ self.headers: dict[str, str] = {}
24
+
25
+
26
+ class _StaticCreds:
27
+ """Duck-typed CredentialsSupplier; raises to simulate an unavailable token."""
28
+
29
+ def __init__(self, token: str | None) -> None:
30
+ self._token = token
31
+
32
+ def bearer_token(self) -> str:
33
+ if self._token is None:
34
+ raise RuntimeError("no auth configured")
35
+ return self._token
36
+
37
+
38
+ def _obs(creds: object, **kw: object) -> Observability:
39
+ return Observability(creds, "gts-test", config=TelemetryConfig(**kw)) # type: ignore[arg-type]
40
+
41
+
42
+ # -- requests hook ------------------------------------------------------------
43
+
44
+
45
+ def test_requests_bearer_auth_stamps_fresh_token_each_call():
46
+ tokens = iter(["tok-1", "tok-2"])
47
+ auth = BearerTokenAuth(lambda: next(tokens))
48
+
49
+ r1, r2 = _FakeRequest(), _FakeRequest()
50
+ auth(r1)
51
+ auth(r2)
52
+
53
+ assert r1.headers["Authorization"] == "Bearer tok-1"
54
+ assert r2.headers["Authorization"] == "Bearer tok-2"
55
+
56
+
57
+ def test_requests_bearer_auth_skips_when_no_token():
58
+ auth = BearerTokenAuth(lambda: None)
59
+ r = _FakeRequest()
60
+
61
+ auth(r)
62
+
63
+ assert "Authorization" not in r.headers
64
+
65
+
66
+ # -- httpx hook ---------------------------------------------------------------
67
+
68
+
69
+ def test_httpx_bearer_auth_mirrors_requests_hook():
70
+ auth = make_httpx_bearer_auth(lambda: "tok-x")
71
+ req = _FakeRequest()
72
+
73
+ yielded = list(auth.auth_flow(req))
74
+
75
+ assert len(yielded) == 1
76
+ assert yielded[0].headers["Authorization"] == "Bearer tok-x"
77
+
78
+
79
+ # -- header precedence chain --------------------------------------------------
80
+
81
+
82
+ def test_build_headers_uses_bearer_token():
83
+ headers = _obs(_StaticCreds("abc")).build_headers()
84
+ assert headers["Authorization"] == "Bearer abc"
85
+ assert headers["x-org-id"] == "2"
86
+
87
+
88
+ def test_build_headers_explicit_header_wins():
89
+ obs = _obs(_StaticCreds("abc"), extra_headers="Authorization=Bearer explicit,X-Foo=bar")
90
+ headers = obs.build_headers()
91
+ assert headers["Authorization"] == "Bearer explicit"
92
+ assert headers["X-Foo"] == "bar"
93
+
94
+
95
+ def test_build_headers_falls_back_to_langfuse_basic():
96
+ obs = _obs(_StaticCreds(None), langfuse_public_key="pk", langfuse_secret_key="sk")
97
+ headers = obs.build_headers()
98
+ expected = "Bearer " + base64.b64encode(b"pk:sk").decode("utf-8")
99
+ assert headers["Authorization"] == expected
100
+
101
+
102
+ def test_build_headers_org_id_always_set():
103
+ assert _obs(_StaticCreds("abc"), org_id="7").build_headers()["x-org-id"] == "7"
104
+
105
+
106
+ # -- endpoint resolution ------------------------------------------------------
107
+
108
+
109
+ def test_resolve_endpoint_explicit_wins():
110
+ obs = _obs(_StaticCreds("t"), host="http://h:1")
111
+ assert obs._resolve_endpoint("http://explicit/x", DEFAULT_TRACES_PATH) == "http://explicit/x"
112
+
113
+
114
+ def test_resolve_endpoint_host_plus_path():
115
+ obs = _obs(_StaticCreds("t"), host="http://h:1/")
116
+ assert obs._resolve_endpoint(None, DEFAULT_TRACES_PATH) == "http://h:1" + DEFAULT_TRACES_PATH
117
+
118
+
119
+ def test_resolve_endpoint_host_already_has_path():
120
+ obs = _obs(_StaticCreds("t"), host="http://h:1" + DEFAULT_LOGS_PATH)
121
+ assert obs._resolve_endpoint(None, DEFAULT_LOGS_PATH) == "http://h:1" + DEFAULT_LOGS_PATH
122
+
123
+
124
+ def test_resolve_endpoint_none_without_host():
125
+ assert _obs(_StaticCreds("t"), host=None)._resolve_endpoint(None, DEFAULT_TRACES_PATH) is None
@@ -0,0 +1,50 @@
1
+ """Phase 9 / H1: AgencyClient.observability() must be thread-safe.
2
+
3
+ The lazy build is documented to return the same instance on repeated calls. Under
4
+ concurrency the unguarded check-then-set could construct several Observability
5
+ objects (and, once each is init()'d, attach duplicate root log handlers). This
6
+ test forces the race and asserts a single construction.
7
+ """
8
+
9
+ import threading
10
+ import time
11
+
12
+ import agency_sdk.observability as obs_mod
13
+ from agency_sdk.client import AgencyClient
14
+
15
+
16
+ def test_observability_is_thread_safe(monkeypatch, fake_credentials):
17
+ real_cls = obs_mod.Observability
18
+ count = {"n": 0}
19
+ count_lock = threading.Lock()
20
+
21
+ def counting(*args, **kwargs):
22
+ with count_lock:
23
+ count["n"] += 1
24
+ time.sleep(0.01) # widen the race window so an unguarded build builds N times
25
+ return real_cls(*args, **kwargs)
26
+
27
+ monkeypatch.setattr(obs_mod, "Observability", counting)
28
+
29
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test")
30
+
31
+ n_threads = 8
32
+ results: list = []
33
+ results_lock = threading.Lock()
34
+ barrier = threading.Barrier(n_threads)
35
+
36
+ def worker():
37
+ barrier.wait() # release all threads together
38
+ instance = client.observability("gts-x")
39
+ with results_lock:
40
+ results.append(instance)
41
+
42
+ threads = [threading.Thread(target=worker) for _ in range(n_threads)]
43
+ for t in threads:
44
+ t.start()
45
+ for t in threads:
46
+ t.join()
47
+
48
+ assert count["n"] == 1 # constructed exactly once despite concurrent callers
49
+ assert len(results) == n_threads
50
+ assert all(instance is results[0] for instance in results) # all share one instance
@@ -0,0 +1,76 @@
1
+ """Phase 6: the Langfuse client helper.
2
+
3
+ ``langfuse_client()`` returns None when the project keys or the langfuse package
4
+ are absent, and otherwise builds a Langfuse client authenticated through the same
5
+ refreshing bearer hook and the shared OTLP span exporter. The langfuse package is
6
+ stubbed so the test never touches the network.
7
+ """
8
+
9
+ import sys
10
+ import types
11
+
12
+ import httpx
13
+
14
+ from agency_sdk.observability.bootstrap import Observability, TelemetryConfig
15
+
16
+
17
+ class _StaticCreds:
18
+ def bearer_token(self) -> str:
19
+ return "tok"
20
+
21
+
22
+ def test_langfuse_client_none_without_keys():
23
+ obs = Observability(_StaticCreds(), "gts-x", config=TelemetryConfig(host="http://cp.test")) # no langfuse keys
24
+ assert obs.langfuse_client() is None
25
+
26
+
27
+ def test_langfuse_client_none_when_package_missing(monkeypatch):
28
+ monkeypatch.setitem(sys.modules, "langfuse", None) # force ImportError
29
+ obs = Observability(
30
+ _StaticCreds(),
31
+ "gts-x",
32
+ config=TelemetryConfig(
33
+ host="http://cp.test",
34
+ langfuse_public_key="pk",
35
+ langfuse_secret_key="sk",
36
+ ),
37
+ )
38
+ assert obs.langfuse_client() is None
39
+
40
+
41
+ def test_langfuse_client_built_with_bearer_auth_and_span_exporter(monkeypatch):
42
+ captured: dict = {}
43
+
44
+ class FakeLangfuse:
45
+ def __init__(self, **kwargs):
46
+ captured.update(kwargs)
47
+
48
+ fake_module = types.ModuleType("langfuse")
49
+ fake_module.Langfuse = FakeLangfuse # type: ignore[attr-defined]
50
+ monkeypatch.setitem(sys.modules, "langfuse", fake_module)
51
+
52
+ obs = Observability(
53
+ _StaticCreds(),
54
+ "gts-x",
55
+ config=TelemetryConfig(
56
+ host="http://cp.test",
57
+ langfuse_public_key="pk",
58
+ langfuse_secret_key="sk",
59
+ ),
60
+ )
61
+
62
+ client = obs.langfuse_client()
63
+
64
+ assert isinstance(client, FakeLangfuse)
65
+ assert captured["public_key"] == "pk"
66
+ assert captured["secret_key"] == "sk"
67
+ assert captured["host"] == "http://cp.test" # langfuse_host defaults to host
68
+ assert captured["span_exporter"] is not None
69
+
70
+ httpx_client = captured["httpx_client"]
71
+ assert isinstance(httpx_client, httpx.Client)
72
+ # The transport auth is our refreshing bearer hook routed through _safe_token.
73
+ request = type("R", (), {"headers": {}})()
74
+ list(httpx_client._auth.auth_flow(request))
75
+ assert request.headers["Authorization"] == "Bearer tok"
76
+ httpx_client.close()
@@ -0,0 +1,78 @@
1
+ """Phase 2: packaging & lazy-import behaviour for the observability module.
2
+
3
+ These tests guarantee the optional ``[observability]`` extra never leaks into the
4
+ SDK's lean core: importing ``agency_sdk`` and constructing ``AgencyClient`` must
5
+ not pull OpenTelemetry, and requesting observability without the extra installed
6
+ must fail with a clear, actionable message naming the extra.
7
+ """
8
+
9
+ import subprocess
10
+ import sys
11
+ from pathlib import Path
12
+
13
+ import pytest
14
+
15
+ from agency_sdk.client import AgencyClient
16
+
17
+ REPO_ROOT = Path(__file__).resolve().parents[2]
18
+
19
+
20
+ def test_import_agency_sdk_is_lazy_wrt_opentelemetry():
21
+ """Importing the SDK core (in a fresh interpreter) must not import OpenTelemetry."""
22
+ code = (
23
+ "import sys, agency_sdk, agency_sdk.client\n"
24
+ "from agency_sdk.client import AgencyClient\n"
25
+ "leaked = [m for m in sys.modules if m == 'opentelemetry' or m.startswith('opentelemetry.')]\n"
26
+ "assert not leaked, leaked\n"
27
+ "print('OK')\n"
28
+ )
29
+ result = subprocess.run(
30
+ [sys.executable, "-c", code],
31
+ cwd=REPO_ROOT,
32
+ capture_output=True,
33
+ text=True,
34
+ )
35
+ assert result.returncode == 0, result.stderr
36
+ assert result.stdout.strip().endswith("OK")
37
+
38
+
39
+ def test_observability_raises_clear_error_when_extra_missing(monkeypatch, fake_credentials):
40
+ """Without the extra, ``observability()`` raises an ImportError naming the extra."""
41
+ # Force the optional deps to look absent regardless of the dev environment.
42
+ monkeypatch.setitem(sys.modules, "opentelemetry", None)
43
+ monkeypatch.setitem(sys.modules, "opentelemetry.sdk", None)
44
+
45
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test")
46
+
47
+ with pytest.raises(ImportError) as exc_info:
48
+ client.observability("gts-test")
49
+
50
+ message = str(exc_info.value)
51
+ assert "observability" in message.lower()
52
+ assert "pip install" in message
53
+ assert "[observability]" in message
54
+
55
+
56
+ def test_observability_returns_bound_cached_instance(fake_credentials):
57
+ """With deps present, ``observability()`` returns an instance bound to the
58
+ shared credentials, defaulting the host to the client ``base_url``, and caches it."""
59
+ from agency_sdk.observability import Observability
60
+
61
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test/")
62
+
63
+ obs = client.observability("gts-test", "1.2.3")
64
+
65
+ assert isinstance(obs, Observability)
66
+ assert obs.credentials is fake_credentials
67
+ assert obs.service_name == "gts-test"
68
+ assert obs.service_version == "1.2.3"
69
+ assert obs.host == "http://cp.test" # defaults to (rstripped) client base_url
70
+ assert client.observability("gts-test") is obs # idempotent / cached
71
+
72
+
73
+ def test_observability_host_is_overridable(fake_credentials):
74
+ client = AgencyClient(token_supplier=fake_credentials, base_url="http://cp.test")
75
+
76
+ obs = client.observability("gts-test", host="http://otel.other:4318")
77
+
78
+ assert obs.host == "http://otel.other:4318"
@@ -0,0 +1,246 @@
1
+ """Phase 4: telemetry pipeline & log/trace correlation, verified offline.
2
+
3
+ Uses OpenTelemetry in-memory exporters (no network) to assert that ``init()``
4
+ builds real recording providers, that stdlib logs emitted inside an active span
5
+ carry that span's trace id, that the processor is selectable, and that exporter
6
+ failure degrades to ``init() -> None`` without side effects.
7
+ """
8
+
9
+ import logging
10
+
11
+ import pytest
12
+
13
+ from opentelemetry.sdk._logs.export import (
14
+ BatchLogRecordProcessor,
15
+ InMemoryLogExporter,
16
+ SimpleLogRecordProcessor,
17
+ )
18
+ from opentelemetry.sdk.trace.export import BatchSpanProcessor, SimpleSpanProcessor
19
+ from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
20
+
21
+ from agency_sdk.observability.auth import BearerTokenAuth
22
+ from agency_sdk.observability.bootstrap import Observability, TelemetryConfig
23
+
24
+ pytestmark = pytest.mark.filterwarnings("ignore::DeprecationWarning")
25
+
26
+
27
+ class _StaticCreds:
28
+ def bearer_token(self) -> str:
29
+ return "tok"
30
+
31
+
32
+ @pytest.fixture
33
+ def otel_isolation():
34
+ """Undo init()'s global side effects (root handler + LoggingInstrumentor)."""
35
+ root = logging.getLogger()
36
+ handlers_before = list(root.handlers)
37
+ level_before = root.level
38
+ yield
39
+ for handler in list(root.handlers):
40
+ if handler not in handlers_before:
41
+ root.removeHandler(handler)
42
+ root.setLevel(level_before)
43
+ try:
44
+ from opentelemetry.instrumentation.logging import LoggingInstrumentor
45
+
46
+ LoggingInstrumentor().uninstrument()
47
+ except Exception:
48
+ pass
49
+
50
+
51
+ def _obs_with_inmemory(monkeypatch, processor="simple"):
52
+ obs = Observability(_StaticCreds(), "gts-test", config=TelemetryConfig(host="http://cp.test", processor=processor))
53
+ span_exporter = InMemorySpanExporter()
54
+ log_exporter = InMemoryLogExporter()
55
+ monkeypatch.setattr(obs, "make_span_exporter", lambda: span_exporter)
56
+ monkeypatch.setattr(obs, "make_log_exporter", lambda: log_exporter)
57
+ return obs, span_exporter, log_exporter
58
+
59
+
60
+ def test_telemetry_config_defaults_and_unpacking():
61
+ # Default config: untraced-host, simple processor, org "2".
62
+ default = Observability(_StaticCreds(), "gts-x")
63
+ assert default.host is None
64
+ assert default.processor == "simple"
65
+ assert default.org_id == "2"
66
+ assert default.langfuse_host is None
67
+
68
+ # Supplied config is unpacked onto the instance; langfuse_host falls back to host.
69
+ obs = Observability(
70
+ _StaticCreds(),
71
+ "gts-x",
72
+ config=TelemetryConfig(host="http://h:1", processor="batch", org_id="7"),
73
+ )
74
+ assert obs.host == "http://h:1"
75
+ assert obs.processor == "batch"
76
+ assert obs.org_id == "7"
77
+ assert obs.langfuse_host == "http://h:1"
78
+
79
+
80
+ def test_init_builds_recording_providers(monkeypatch, otel_isolation):
81
+ obs, span_exporter, _ = _obs_with_inmemory(monkeypatch)
82
+
83
+ tracer = obs.init()
84
+
85
+ assert tracer is not None
86
+ with tracer.start_as_current_span("root") as span:
87
+ ctx = span.get_span_context()
88
+ assert ctx.trace_id != 0 # real recording provider, valid context
89
+ assert span.is_recording()
90
+ obs.shutdown()
91
+ assert any(s.name == "root" for s in span_exporter.get_finished_spans())
92
+
93
+
94
+ def test_logs_carry_active_span_trace_id(monkeypatch, otel_isolation):
95
+ obs, _, log_exporter = _obs_with_inmemory(monkeypatch)
96
+ tracer = obs.init()
97
+ logging.getLogger().setLevel(logging.DEBUG)
98
+
99
+ with tracer.start_as_current_span("root") as span:
100
+ trace_id = span.get_span_context().trace_id
101
+ logging.getLogger("obs.test.correlation").warning("correlated-line")
102
+
103
+ obs._logger_provider.force_flush()
104
+ matched = [r for r in log_exporter.get_finished_logs() if r.log_record.body == "correlated-line"]
105
+ obs.shutdown()
106
+
107
+ assert matched, "log line was not exported"
108
+ assert matched[0].log_record.trace_id == trace_id
109
+
110
+
111
+ def test_processor_choice_simple_default_and_batch():
112
+ span_exp = InMemorySpanExporter()
113
+ log_exp = InMemoryLogExporter()
114
+
115
+ simple = Observability(_StaticCreds(), "s") # default
116
+ batch = Observability(_StaticCreds(), "s", config=TelemetryConfig(processor="batch"))
117
+
118
+ assert isinstance(simple._make_span_processor(span_exp), SimpleSpanProcessor)
119
+ assert isinstance(simple._make_log_processor(log_exp), SimpleLogRecordProcessor)
120
+
121
+ batch_span = batch._make_span_processor(span_exp)
122
+ batch_log = batch._make_log_processor(log_exp)
123
+ assert isinstance(batch_span, BatchSpanProcessor)
124
+ assert isinstance(batch_log, BatchLogRecordProcessor)
125
+ batch_span.shutdown() # stop the worker threads
126
+ batch_log.shutdown()
127
+
128
+
129
+ def test_make_span_exporter_attaches_refreshing_auth():
130
+ obs = Observability(_StaticCreds(), "gts-test", config=TelemetryConfig(host="http://cp.test"))
131
+
132
+ exporter = obs.make_span_exporter()
133
+
134
+ assert isinstance(exporter._session.auth, BearerTokenAuth)
135
+
136
+
137
+ def test_make_log_exporter_attaches_refreshing_auth():
138
+ obs = Observability(_StaticCreds(), "gts-test", config=TelemetryConfig(host="http://cp.test"))
139
+
140
+ exporter = obs.make_log_exporter()
141
+
142
+ assert isinstance(exporter._session.auth, BearerTokenAuth)
143
+
144
+
145
+ def test_tracer_provider_property_reflects_lifecycle(monkeypatch, otel_isolation):
146
+ obs, _, _ = _obs_with_inmemory(monkeypatch)
147
+
148
+ assert obs.tracer_provider is None
149
+ obs.init()
150
+ assert obs.tracer_provider is not None
151
+ obs.shutdown()
152
+
153
+
154
+ def test_shutdown_is_idempotent(monkeypatch, otel_isolation):
155
+ obs, _, _ = _obs_with_inmemory(monkeypatch)
156
+ obs.init()
157
+ logger_provider, tracer_provider = obs._logger_provider, obs._tracer_provider
158
+ counts = {"log": 0, "trace": 0}
159
+ monkeypatch.setattr(logger_provider, "shutdown", lambda: counts.__setitem__("log", counts["log"] + 1))
160
+ monkeypatch.setattr(tracer_provider, "shutdown", lambda: counts.__setitem__("trace", counts["trace"] + 1))
161
+
162
+ obs.shutdown()
163
+ obs.shutdown() # a second explicit call (and the atexit path) must be a no-op
164
+
165
+ assert counts == {"log": 1, "trace": 1}
166
+ assert obs._logger_provider is None
167
+ assert obs._tracer_provider is None
168
+
169
+
170
+ def test_init_registers_instance_shutdown_with_atexit(monkeypatch, otel_isolation):
171
+ import agency_sdk.observability.bootstrap as bootstrap
172
+
173
+ registered: list = []
174
+ monkeypatch.setattr(bootstrap.atexit, "register", lambda fn, *a, **k: registered.append(fn))
175
+
176
+ obs, _, _ = _obs_with_inmemory(monkeypatch)
177
+ obs.init()
178
+
179
+ # atexit drives the instance shutdown (idempotent), not the raw providers directly.
180
+ assert obs.shutdown in registered
181
+ assert obs._logger_provider.shutdown not in registered
182
+ assert obs._tracer_provider.shutdown not in registered
183
+ obs.shutdown()
184
+
185
+
186
+ def test_init_returns_none_on_exporter_failure(monkeypatch, otel_isolation):
187
+ obs = Observability(_StaticCreds(), "gts-test", config=TelemetryConfig(host="http://cp.test"))
188
+
189
+ def boom():
190
+ raise RuntimeError("exporter down")
191
+
192
+ monkeypatch.setattr(obs, "make_log_exporter", boom)
193
+ handlers_before = list(logging.getLogger().handlers)
194
+
195
+ result = obs.init()
196
+
197
+ assert result is None # graceful degradation, no exception
198
+ # No global side effects when setup fails.
199
+ assert list(logging.getLogger().handlers) == handlers_before
200
+
201
+
202
+ # -- agent_run (Mechanism 5) --------------------------------------------------
203
+
204
+
205
+ def test_agent_run_opens_root_span_with_attributes(monkeypatch, otel_isolation):
206
+ obs, span_exporter, _ = _obs_with_inmemory(monkeypatch)
207
+ obs.init()
208
+
209
+ with obs.agent_run("agent.x", correlation_id="cid-1", team="echo") as span:
210
+ assert span is not None
211
+ assert span.is_recording()
212
+
213
+ obs.shutdown()
214
+ root = next(s for s in span_exporter.get_finished_spans() if s.name == "agent.x")
215
+ assert root.attributes["correlation_id"] == "cid-1"
216
+ assert root.attributes["team"] == "echo"
217
+
218
+
219
+ def test_agent_run_is_nullcontext_when_tracing_off():
220
+ obs = Observability(_StaticCreds(), "gts-x") # init() never called -> no tracer
221
+
222
+ ran = False
223
+ with obs.agent_run("agent.x", k="v") as span:
224
+ assert span is None
225
+ ran = True
226
+
227
+ assert ran # body still executes, untraced
228
+
229
+
230
+ def test_child_spans_and_logs_share_root_trace_id(monkeypatch, otel_isolation):
231
+ obs, _, log_exporter = _obs_with_inmemory(monkeypatch)
232
+ tracer = obs.init()
233
+ logging.getLogger().setLevel(logging.DEBUG)
234
+
235
+ with obs.agent_run("agent.x") as root:
236
+ root_trace_id = root.get_span_context().trace_id
237
+ with tracer.start_as_current_span("child") as child:
238
+ assert child.get_span_context().trace_id == root_trace_id
239
+ logging.getLogger("obs.test.nested").warning("inside-run")
240
+
241
+ obs._logger_provider.force_flush()
242
+ matched = [r for r in log_exporter.get_finished_logs() if r.log_record.body == "inside-run"]
243
+ obs.shutdown()
244
+
245
+ assert matched
246
+ assert matched[0].log_record.trace_id == root_trace_id