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,230 @@
1
+ """Client for the work-queue ingestion API (/api/work_queues).
2
+
3
+ Mirrors the Track ① files-inbox ingestion contract (design §5/§6). Work items
4
+ (cards) are claimed exactly-once via external refs under a **queue-scoped** UNIQUE
5
+ key (① ``55f9f1f5``), so on ``create_item`` and ``add_ref`` an HTTP 409 is a normal
6
+ claim-lost outcome — another card in the SAME queue already owns the ref — not an
7
+ error. Both methods catch it and return a typed result carrying the owner's summary;
8
+ every other HTTP error propagates as usual.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import builtins # the `list()` method shadows the builtin, so annotations use builtins.list[...]
14
+ from collections.abc import Mapping, Sequence
15
+ from typing import Any
16
+
17
+ import requests
18
+
19
+ from agency_sdk.delegates.base_client import BaseDelegateClient
20
+ from agency_sdk.delegates.work_queue_dto import (
21
+ AddRefResult,
22
+ CreateItemResult,
23
+ ExistingItemSummary,
24
+ ItemCommandResponse,
25
+ ItemResponse,
26
+ QueuesPagedResult,
27
+ )
28
+
29
+
30
+ #: The ``error.type`` an owner-less "claim contended" 409 carries (the ①-side
31
+ #: ``AppError::Conflict(String)`` fallback). It is the deterministic signal for a
32
+ #: retryable conflict with no owner — never inferred from missing ``details``.
33
+ _CONFLICT_RETRY_TYPE = "CONFLICT_RETRY"
34
+
35
+
36
+ def _parse_conflict(error: requests.HTTPError) -> tuple[dict[str, Any] | None, bool] | None:
37
+ """Parse a 409 from the standard error envelope ``{error: {message, type, details}}``.
38
+
39
+ Returns ``(owner_details, contended)``:
40
+
41
+ - owner conflict → ``(details, False)`` where ``details`` is the owning card's summary.
42
+ - owner-less ``CONFLICT_RETRY`` → ``(None, True)``.
43
+
44
+ Returns ``None`` when it is not a usable conflict — a non-409 status, a body that
45
+ will not parse as JSON, or an envelope 409 that is neither an owner-details conflict
46
+ nor ``CONFLICT_RETRY`` — so the caller re-raises the original ``HTTPError`` rather
47
+ than fabricating a claim-lost result.
48
+ """
49
+ response = error.response
50
+ if response is None or response.status_code != 409:
51
+ return None
52
+ try:
53
+ body = response.json()
54
+ except ValueError: # includes requests.JSONDecodeError (malformed/empty 409 body)
55
+ return None
56
+ if not isinstance(body, dict):
57
+ return None
58
+ error_obj = body.get("error")
59
+ if not isinstance(error_obj, dict):
60
+ return None
61
+ details = error_obj.get("details")
62
+ if isinstance(details, dict) and "work_item_id" in details:
63
+ return details, False
64
+ if error_obj.get("type") == _CONFLICT_RETRY_TYPE:
65
+ return None, True
66
+ return None
67
+
68
+
69
+ class AgencyWorkQueueClient(BaseDelegateClient):
70
+ api_path = "/api/work_queues"
71
+
72
+ def list(self, organisation_id: int, *, page: int = 0, size: int = 50) -> QueuesPagedResult:
73
+ """List the org's work queues (paged), for resolving a queue NAME → id.
74
+
75
+ Name→id matching (and any cache / not-found / duplicate handling) is the
76
+ caller's job; this returns the raw page.
77
+ """
78
+ params = {"o": str(organisation_id), "p": str(page), "s": str(size)}
79
+ return QueuesPagedResult(**self._make_request("GET", "", params=params))
80
+
81
+ def create_item(
82
+ self,
83
+ queue_id: int,
84
+ organisation_id: int,
85
+ *,
86
+ title: str,
87
+ session_template_id: str,
88
+ input_data: dict[str, Any],
89
+ external_refs: Sequence[Mapping[str, str]] | None = None,
90
+ metadata: dict[str, Any] | None = None,
91
+ ) -> CreateItemResult:
92
+ """Create a work item, atomically claiming its external refs.
93
+
94
+ The server inserts the card and its refs in one transaction; a
95
+ duplicate ref rolls the whole transaction back (no card is created)
96
+ and returns 409 with the owning card's summary.
97
+
98
+ Args:
99
+ queue_id: The work queue ID.
100
+ organisation_id: The organisation ID.
101
+ title: Card title.
102
+ session_template_id: Session template dispatched on publish.
103
+ Ingestion items must be template-based (the agent_id branch
104
+ dispatches no session).
105
+ input_data: Arbitrary JSON object stored on the card and passed
106
+ to the dispatched session.
107
+ external_refs: Identity claims, each ``{"ref_type": ...,
108
+ "ref_value": ...}`` (e.g. file_id / content_hash). Unique
109
+ per queue per (ref_type, ref_value).
110
+ metadata: Optional informational JSON (filename, folder, ...).
111
+
112
+ Returns:
113
+ ``created=True`` with the new item; ``created=False`` with
114
+ ``existing`` identifying the card that already owns a ref; or
115
+ ``created=False, contended=True`` (no ``existing``) for the
116
+ owner-less ``CONFLICT_RETRY`` fallback — a transient claim race the
117
+ caller may retry.
118
+ """
119
+ data: dict[str, Any] = {
120
+ "title": title,
121
+ "session_template_id": session_template_id,
122
+ "input_data": input_data,
123
+ }
124
+ if external_refs is not None:
125
+ data["external_refs"] = [dict(ref) for ref in external_refs]
126
+ if metadata is not None:
127
+ data["metadata"] = metadata
128
+ try:
129
+ body = self._make_request("POST", f"/{queue_id}/items", data=data, params={"o": str(organisation_id)})
130
+ except requests.HTTPError as error:
131
+ conflict = _parse_conflict(error)
132
+ if conflict is None:
133
+ raise
134
+ details, contended = conflict
135
+ existing = ExistingItemSummary(**details) if details is not None else None
136
+ return CreateItemResult(created=False, existing=existing, contended=contended)
137
+ return CreateItemResult(created=True, item=ItemResponse(**body))
138
+
139
+ def add_ref(
140
+ self, queue_id: int, item_id: int, organisation_id: int, *, ref_type: str, ref_value: str
141
+ ) -> AddRefResult:
142
+ """Claim an external ref for an existing item (content-layer claim).
143
+
144
+ Returns:
145
+ ``added=True`` when the ref was inserted; ``added=False`` with the
146
+ owning card's id and status when another card already holds the ref
147
+ (HTTP 409); or ``added=False, contended=True`` (no owner) for the
148
+ owner-less ``CONFLICT_RETRY`` fallback (retryable).
149
+ """
150
+ data = {"command": "add_ref", "ref_type": ref_type, "ref_value": ref_value}
151
+ try:
152
+ self._make_request(
153
+ "POST", f"/{queue_id}/items/{item_id}/_command", data=data, params={"o": str(organisation_id)}
154
+ )
155
+ except requests.HTTPError as error:
156
+ conflict = _parse_conflict(error)
157
+ if conflict is None:
158
+ raise
159
+ details, contended = conflict
160
+ if details is not None:
161
+ return AddRefResult(
162
+ added=False, owner_work_item_id=details["work_item_id"], owner_status=details["status"]
163
+ )
164
+ return AddRefResult(added=False, contended=contended)
165
+ return AddRefResult(added=True)
166
+
167
+ def publish_item(self, queue_id: int, item_id: int, organisation_id: int) -> ItemCommandResponse:
168
+ """Publish a backlog item, dispatching its session (injects work_item_id).
169
+
170
+ Returns:
171
+ The command outcome; ``session_id`` identifies the dispatched
172
+ session. Fetch the updated card via get_item if needed.
173
+
174
+ Raises:
175
+ requests.HTTPError: 400 if the item is not backlog+unpublished or
176
+ its input_data is not a JSON object.
177
+ """
178
+ return self.item_command(queue_id, item_id, organisation_id, "publish")
179
+
180
+ def item_command(
181
+ self, queue_id: int, item_id: int, organisation_id: int, command: str, **kwargs: Any
182
+ ) -> ItemCommandResponse:
183
+ """Run an item command (publish / unblock / retry / reprocess).
184
+
185
+ Extra keyword arguments are passed through as flat siblings of
186
+ ``command`` in the request body (e.g. ``feedback=...`` for unblock).
187
+ Commands report their outcome — they do not return the updated item
188
+ (GET it if needed). Unlike create_item/add_ref, a 409 here is a
189
+ genuine error and propagates.
190
+ """
191
+ data = {"command": command, **kwargs}
192
+ body = self._make_request(
193
+ "POST", f"/{queue_id}/items/{item_id}/_command", data=data, params={"o": str(organisation_id)}
194
+ )
195
+ return ItemCommandResponse(**body)
196
+
197
+ def get_item(self, queue_id: int, item_id: int, organisation_id: int) -> ItemResponse:
198
+ """Fetch a single work item."""
199
+ body = self._make_request("GET", f"/{queue_id}/items/{item_id}", params={"o": str(organisation_id)})
200
+ return ItemResponse(**body)
201
+
202
+ def get_items_by_ref(
203
+ self,
204
+ organisation_id: int,
205
+ *,
206
+ queue_id: int | None = None,
207
+ ref_type: str,
208
+ ref_value: str,
209
+ ) -> builtins.list[ItemResponse]:
210
+ """List the items holding an external ref — queue-scoped owner lookup.
211
+
212
+ The dedicated ``_by_ref`` route was merged into the paginated ``/items``: passing
213
+ ``ref_type`` + ``ref_value`` turns ``/items`` into the owner lookup. ``queue_id=None``
214
+ scopes to the whole org (``_``); a queue id scopes to that queue. A given
215
+ ``(ref_type, ref_value)`` may be held by one card **per queue**, so this returns a
216
+ list; an empty list means no card holds the ref.
217
+
218
+ Returns:
219
+ The owning items (possibly empty — a miss is an empty page, not a 404; a genuine
220
+ 404 propagates). Owner count is bounded by one card per queue, so a single large
221
+ page (``s=1000``) returns them all.
222
+ """
223
+ scope = "_" if queue_id is None else str(queue_id)
224
+ params = {"o": str(organisation_id), "ref_type": ref_type, "ref_value": ref_value, "s": "1000"}
225
+ body = self._make_request("GET", f"/{scope}/items", params=params)
226
+ return [ItemResponse(**item) for item in body["items"]]
227
+
228
+ def delete_item(self, queue_id: int, item_id: int, organisation_id: int) -> None:
229
+ """Hard-delete an item — the "full forget": its external refs CASCADE away with it."""
230
+ self._make_request("DELETE", f"/{queue_id}/items/{item_id}", params={"o": str(organisation_id)})
@@ -0,0 +1,127 @@
1
+ """DTOs for the work-queue ingestion API (snake_case, matching the API).
2
+
3
+ Mirrors the Track ① contract (files-inbox-ingestion design §5/§6):
4
+
5
+ - ``ItemResponse`` matches the server's work-queue item DTO
6
+ (gts-agency-control ``work_queue_dto.rs``), which omits nullable fields
7
+ entirely when null — every optional field therefore defaults to ``None``.
8
+ - ``CreateItemResult`` / ``AddRefResult`` wrap the 201-vs-409 outcomes of
9
+ ``create_item`` / ``add_ref``: a 409 is a normal claim-lost outcome carrying
10
+ the owning card's summary, not an error. Note the two 409 bodies differ —
11
+ create's carries ``{work_item_id, status, published}``, add_ref's only
12
+ ``{work_item_id, status}``.
13
+ """
14
+
15
+ from typing import Any
16
+
17
+ from pydantic import BaseModel
18
+
19
+ from agency_sdk.delegates.datasets_dto import Page
20
+
21
+
22
+ class DependencyResponse(BaseModel):
23
+ """A dependency edge as embedded in an item response."""
24
+
25
+ depends_on_item_id: int
26
+ depends_on_title: str
27
+ depends_on_status: str
28
+ created_on: str
29
+
30
+
31
+ class ItemResponse(BaseModel):
32
+ """A work-queue item (card) as returned by the work-queue API."""
33
+
34
+ id: int
35
+ work_queue_id: int
36
+ title: str
37
+ description: str | None = None
38
+ status: str
39
+ published: bool
40
+ priority: int
41
+ session_template_id: str | None = None
42
+ agent_id: str | None = None
43
+ session_id: str | None = None
44
+ assigned_worker_id: str | None = None
45
+ input_data: Any = None
46
+ saved_state: Any = None
47
+ result_data: Any = None
48
+ metadata: Any = None
49
+ dependencies: list[DependencyResponse] | None = None
50
+ started_on: str | None = None
51
+ blocked_on: str | None = None
52
+ unblocked_on: str | None = None
53
+ completed_on: str | None = None
54
+ created_on: str
55
+ modified_on: str
56
+
57
+
58
+ class ItemCommandResponse(BaseModel):
59
+ """Outcome of an item command (publish / unblock / retry / reprocess).
60
+
61
+ The ``_command`` endpoint's established server shape (transcribed from
62
+ ``work_queue_dto.rs``, per design §6.0): commands report what happened —
63
+ they do not return the updated item (GET it if needed). ``session_id`` is
64
+ only present for commands that dispatched a session (e.g. publish).
65
+ """
66
+
67
+ success: bool
68
+ message: str
69
+ session_id: str | None = None
70
+
71
+
72
+ class ExistingItemSummary(BaseModel):
73
+ """The owning card's summary carried in a 409's ``error.details``.
74
+
75
+ ``published`` is optional — the details object may omit it (the SDK reads
76
+ it defensively).
77
+ """
78
+
79
+ work_item_id: int
80
+ status: str
81
+ published: bool | None = None
82
+
83
+
84
+ class CreateItemResult(BaseModel):
85
+ """Outcome of create_item: 201 → created item, 409 → the existing owner.
86
+
87
+ On a 409 the whole server transaction rolled back, so no card was created.
88
+ ``existing`` identifies the card that already owns the external ref (from the
89
+ 409's ``error.details``); ``contended`` is ``True`` for the owner-less
90
+ ``CONFLICT_RETRY`` fallback (a transient claim race — no owner, retryable),
91
+ in which case ``existing`` is ``None``.
92
+ """
93
+
94
+ created: bool
95
+ item: ItemResponse | None = None
96
+ existing: ExistingItemSummary | None = None
97
+ contended: bool = False
98
+
99
+
100
+ class AddRefResult(BaseModel):
101
+ """Outcome of add_ref: 201 → ref added, 409 → another card owns the ref.
102
+
103
+ ``contended`` is ``True`` for the owner-less ``CONFLICT_RETRY`` fallback (no
104
+ owner fields, retryable).
105
+ """
106
+
107
+ added: bool
108
+ owner_work_item_id: int | None = None
109
+ owner_status: str | None = None
110
+ contended: bool = False
111
+
112
+
113
+ class QueueResponse(BaseModel):
114
+ """A work queue as returned by ``GET /api/work_queues`` (for name→id resolution)."""
115
+
116
+ id: int
117
+ name: str
118
+ status: int
119
+ description: str | None = None
120
+ created_on: str
121
+ modified_on: str
122
+ created_by: str | None = None
123
+
124
+
125
+ class QueuesPagedResult(BaseModel):
126
+ page: Page
127
+ items: list[QueueResponse]
agency_sdk/domain.py ADDED
@@ -0,0 +1,140 @@
1
+ import datetime
2
+ from enum import Enum
3
+ from typing import Any
4
+
5
+ from pydantic import BaseModel, Field
6
+
7
+
8
+ class PromptType(Enum):
9
+ MESSAGE = 0
10
+
11
+
12
+ class MessageRole(Enum):
13
+ SYSTEM = "system"
14
+ USER = "user"
15
+ ASSISTANT = "assistant"
16
+
17
+
18
+ class ContentType(Enum):
19
+ TEXT = "text"
20
+
21
+
22
+ class MessageContent(BaseModel):
23
+ role: MessageRole
24
+ content_type: ContentType
25
+ content: str
26
+ parameters: dict[str, Any] | None = None
27
+
28
+
29
+ class PromptCollection(BaseModel):
30
+ system: MessageContent
31
+ messages: list[MessageContent]
32
+
33
+
34
+ class PromptContent(BaseModel):
35
+ type: str = "message"
36
+ message: MessageContent | None = None
37
+ collections: PromptCollection | None = None
38
+
39
+
40
+ class PromptPayload(BaseModel):
41
+ name: str
42
+ description: str | None = None
43
+ type: PromptType | None = PromptType.MESSAGE
44
+ tags: list[str] | None = None
45
+ metadata: dict[str, Any] | None = None
46
+ content: PromptContent
47
+
48
+
49
+ class Pagination(BaseModel):
50
+ page: int
51
+ size: int
52
+
53
+
54
+ class SearchRequest(BaseModel):
55
+ organisation: int
56
+ tags: list[str] | None = None
57
+ pagination: Pagination | None = None
58
+
59
+
60
+ class PromptsCommand(BaseModel):
61
+ command: str
62
+ organisation: int
63
+ payload: PromptPayload | None = None
64
+
65
+
66
+ class CreatePromptCommand(PromptsCommand):
67
+ command: str = "create"
68
+ payload: PromptPayload
69
+
70
+
71
+ class PromptCommand(BaseModel):
72
+ command: str
73
+ organisation: int
74
+ payload: PromptPayload | None = None
75
+
76
+
77
+ class UpdatePromptCommand(PromptCommand):
78
+ command: str = "update"
79
+ payload: PromptPayload
80
+
81
+
82
+ class PublishPromptCommand(PromptCommand):
83
+ command: str = "publish"
84
+ payload: PromptPayload | None = None
85
+
86
+
87
+ class DeletePromptCommand(PromptCommand):
88
+ command: str = "delete"
89
+ payload: PromptPayload | None = None
90
+
91
+
92
+ class Page(BaseModel):
93
+ total: int
94
+ page: int
95
+ size: int
96
+
97
+
98
+ class PromptSummary(BaseModel):
99
+ id: str
100
+ name: str
101
+ description: str
102
+ tags: list[str]
103
+ published_version: int | None = None
104
+ unpublished_version: int | None = None
105
+ modified_on: datetime.datetime
106
+
107
+
108
+ class PromptPagedResult(BaseModel):
109
+ page: Page
110
+ items: list[PromptSummary]
111
+
112
+
113
+ class PromptMessageSpecification(BaseModel):
114
+ role: str | None = None
115
+ content_type: str | None = None
116
+ content: str
117
+ parameters: Any | None = None
118
+
119
+
120
+ class PromptCollectionSpecification(BaseModel):
121
+ system: PromptMessageSpecification
122
+ messages: list[PromptMessageSpecification]
123
+
124
+
125
+ class PromptSpecification(BaseModel):
126
+ type_: str = Field(alias="type")
127
+ message: PromptMessageSpecification | None = None
128
+ collections: PromptCollectionSpecification | None = None
129
+
130
+
131
+ class PromptResponse(BaseModel):
132
+ id: str
133
+ name: str
134
+ description: str
135
+ content: PromptSpecification
136
+ tags: Any
137
+ version: int
138
+ status: int
139
+ metadata: dict[str, Any]
140
+ audit: Any
@@ -0,0 +1,60 @@
1
+ """Optional OpenTelemetry tracing/logging support for the Agency SDK.
2
+
3
+ The heavy OpenTelemetry/Langfuse dependencies live behind the ``[observability]``
4
+ extra and are imported lazily, so importing :mod:`agency_sdk` and constructing
5
+ :class:`agency_sdk.client.AgencyClient` never require them. Enable the feature via
6
+ ``AgencyClient.observability(...)``::
7
+
8
+ client = AgencyClient(token_supplier=creds, base_url="http://localhost:13001")
9
+ obs = client.observability("gts-myagent")
10
+ tracer = obs.init()
11
+ with obs.agent_run("agent.myagent", correlation_id=cid):
12
+ ...
13
+
14
+ Install the extra with::
15
+
16
+ pip install gts-agency-python-sdk[observability]
17
+ """
18
+
19
+ from agency_sdk.observability.auth import BearerTokenAuth, make_httpx_bearer_auth
20
+ from agency_sdk.observability.bootstrap import (
21
+ DEFAULT_LOGS_PATH,
22
+ DEFAULT_TRACES_PATH,
23
+ Observability,
24
+ TelemetryConfig,
25
+ )
26
+
27
+ _INSTALL_HINT = (
28
+ "Observability support requires the optional dependency group. Install it with:\n"
29
+ " pip install gts-agency-python-sdk[observability]"
30
+ )
31
+
32
+
33
+ class ObservabilityNotInstalled(ImportError):
34
+ """Raised when observability is requested but the ``[observability]`` extra is absent."""
35
+
36
+
37
+ def require_observability_deps() -> None:
38
+ """Verify the optional OpenTelemetry deps are importable, else raise a clear error.
39
+
40
+ Called at the ``AgencyClient.observability(...)`` entry point so a missing
41
+ extra fails fast with an actionable message rather than deep inside export.
42
+ """
43
+ try:
44
+ import opentelemetry.sdk # noqa: F401
45
+ import opentelemetry.exporter.otlp.proto.http.trace_exporter # noqa: F401
46
+ import opentelemetry.instrumentation.logging # noqa: F401
47
+ except ImportError as exc:
48
+ raise ObservabilityNotInstalled(_INSTALL_HINT) from exc
49
+
50
+
51
+ __all__ = [
52
+ "Observability",
53
+ "TelemetryConfig",
54
+ "ObservabilityNotInstalled",
55
+ "require_observability_deps",
56
+ "BearerTokenAuth",
57
+ "make_httpx_bearer_auth",
58
+ "DEFAULT_LOGS_PATH",
59
+ "DEFAULT_TRACES_PATH",
60
+ ]
@@ -0,0 +1,15 @@
1
+ """Backward-compatible re-export of the shared bearer-token auth hooks.
2
+
3
+ The canonical implementations now live in :mod:`agency_sdk.auth_hooks` — a core,
4
+ dependency-light module — so non-observability consumers (e.g. the gateway
5
+ client's ``openai`` helpers) can reuse them without importing this optional
6
+ submodule. This module is a thin re-export because the OTLP ``requests``
7
+ exporter (``session.auth = BearerTokenAuth(...)``) and the Langfuse ``httpx``
8
+ client (``make_httpx_bearer_auth(...)``) reference this path.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from agency_sdk.auth_hooks import BearerTokenAuth, TokenSupplier, make_httpx_bearer_auth
14
+
15
+ __all__ = ["BearerTokenAuth", "TokenSupplier", "make_httpx_bearer_auth"]