strands-mongodb 0.1.0.dev1__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.
@@ -0,0 +1,408 @@
1
+ """Aggregation stages for the vector, text and hybrid search tiers.
2
+
3
+ Pure functions over plain dicts: no client and no I/O, so every shape is testable without a deployment.
4
+ That matters because the mistakes this module prevents are shape mistakes a live query can answer with
5
+ wrong results rather than an error.
6
+
7
+ Every search stage comes from ``pymongo_search_utils``' builders. This module adds what they leave to the
8
+ caller:
9
+
10
+ * **One return type.** Every function returns ``list[dict]``, so the tiers compose the same way.
11
+ * **Which builder, and which path.** Both follow ``VectorMode``. The ``autoEmbed`` index declares the
12
+ text field as its vector field, so the AutoEmbeddings query paths at ``content`` and the manual query
13
+ paths at ``embedding``. Crossing them fails with code 8, but only after a round trip.
14
+ * **The score projection.** The vector builders emit no score. The three ``$meta`` names (vector, text,
15
+ fused) are not interchangeable.
16
+ * **The hybrid tier.** :func:`hybrid_stages` wraps the vector and text pipelines in one server-side
17
+ ``$rankFusion`` (MongoDB 8.0+). The library's client-side fusion builders are not used.
18
+ """
19
+
20
+ from __future__ import annotations
21
+
22
+ from typing import TYPE_CHECKING, Any, Final
23
+
24
+ from strands_mongodb._extras import missing_extra
25
+ from strands_mongodb._indexes import CONTENT_FIELD, MAX_NUM_CANDIDATES, VECTOR_FIELD
26
+ from strands_mongodb.types import DEFAULT_OVERSAMPLING_FACTOR
27
+
28
+ try:
29
+ from pymongo_search_utils import (
30
+ autoembedding_vector_search_stage,
31
+ text_search_stage,
32
+ vector_search_stage,
33
+ )
34
+ except ImportError as error: # pragma: no cover - exercised in the extras tier
35
+ missing_extra("memory", error, module=__name__)
36
+
37
+ if TYPE_CHECKING:
38
+ from collections.abc import Mapping
39
+
40
+ from strands_mongodb._indexes import VectorMode
41
+
42
+ __all__ = [
43
+ "FUSION_SCORE_META",
44
+ "MAX_NUM_CANDIDATES",
45
+ "RANK_FUSION_PENALTY",
46
+ "candidate_count",
47
+ "check_candidate_count",
48
+ "check_query_keys",
49
+ "hybrid_stages",
50
+ "text_stages",
51
+ "vector_stages",
52
+ ]
53
+
54
+ RANK_FUSION_PENALTY: Final[int] = 60
55
+ """Rank constant the server applies inside ``$rankFusion``. This package never sends it.
56
+
57
+ It sets the scale of every hybrid score. A fused score is the sum, over the tiers that ranked a document,
58
+ of ``weight / (rank + 60)``. A document first in one tier scores about ``1/61`` (0.016) and one first in
59
+ both about 0.033, while cosine similarity and BM25 land roughly between 0 and 1. A ``min_score`` chosen
60
+ for those scales empties every hybrid result. The config docstring and the README quote this constant.
61
+ """
62
+
63
+ VECTOR_SCORE_META: Final[str] = "vectorSearchScore"
64
+ """``$meta`` name for a ``$vectorSearch`` score. Not interchangeable with the other two."""
65
+
66
+ FUSION_SCORE_META: Final[str] = "score"
67
+ """``$meta`` name for a ``$rankFusion`` score. Not interchangeable with the other two.
68
+
69
+ ``{"$meta": "score"}`` is metadata, not the ``"$score"`` field. ``$rankFusion`` returns documents with no
70
+ score field, so without the ``$set`` appended after it every hybrid result would score ``0.0`` and any
71
+ ``min_score`` would silently empty the result list. Available from MongoDB 8.0, the same floor as the
72
+ stage (:data:`_indexes.RANK_FUSION_MIN_MAJOR`).
73
+ """
74
+
75
+ TEXT_SCORE_META: Final[str] = "searchScore"
76
+ """``$meta`` name for a ``$search`` score. Not interchangeable with the other two.
77
+
78
+ Crossing it with the vector name is not reliably an error. On mongot 8.3.8, asking for it on a
79
+ ``$vectorSearch`` pipeline fails with *"query requires $search score metadata, but it is not available"*.
80
+ On Atlas 8.0.30 the same pipeline succeeds and returns no score field, which ``memory_store`` reads as
81
+ ``0.0``. So these constants are the guard, not the server.
82
+
83
+ The tiers score on different scales, which is why ``_search_type`` travels in the result metadata and
84
+ ``min_score`` is not comparable across tiers.
85
+ """
86
+
87
+ SCORE_FIELD: Final[str] = "score"
88
+ """Field every tier projects its score into, so a reader does not branch on the tier."""
89
+
90
+
91
+ def candidate_count(limit: int, oversampling_factor: int = DEFAULT_OVERSAMPLING_FACTOR) -> int:
92
+ """Derive ``numCandidates`` from a resolved limit and validate it.
93
+
94
+ Derived from the limit so the candidate pool grows with it. ``pymongo_search_utils`` computes the
95
+ same product but does not validate it.
96
+
97
+ Args:
98
+ limit: Resolved result ceiling for this query. Must be positive.
99
+ oversampling_factor: Multiplier turning the limit into a candidate pool.
100
+
101
+ Returns:
102
+ ``limit * oversampling_factor``, guaranteed within ``[1..MAX_NUM_CANDIDATES]``.
103
+
104
+ Raises:
105
+ ValueError: If ``limit`` is not positive, if the factor is not positive, or if the product
106
+ exceeds :data:`MAX_NUM_CANDIDATES`. The message names both numbers, since either can be
107
+ lowered.
108
+ """
109
+ if limit < 1:
110
+ # The server rejects this from a different layer than the `numCandidates` checks: code 7912700
111
+ # on MongoDB 8.0 and 65137 on 9.0.
112
+ raise ValueError(
113
+ f"strands_mongodb: 'limit' is {limit} and a search limit must be at least 1. The server "
114
+ f"rejects a non-positive limit outright."
115
+ )
116
+ if oversampling_factor < 1:
117
+ raise ValueError(
118
+ f"strands_mongodb: 'oversampling_factor' is {oversampling_factor} and must be at least 1. "
119
+ f"A factor below 1 asks the server to consider fewer candidates than the results it must "
120
+ f"return, which is rejected as numCandidates below the limit."
121
+ )
122
+
123
+ candidates = limit * oversampling_factor
124
+ if candidates > MAX_NUM_CANDIDATES:
125
+ raise ValueError(
126
+ f"strands_mongodb: numCandidates would be {candidates}, and the server requires a value "
127
+ f"within bounds [1..{MAX_NUM_CANDIDATES}]. It is derived as limit ({limit}) times "
128
+ f"'oversampling_factor' ({oversampling_factor}), so lower whichever of the two you can "
129
+ f"afford to: the limit costs you results, the factor costs you recall."
130
+ )
131
+ return candidates
132
+
133
+
134
+ def check_candidate_count(*, limit: int, num_candidates: int) -> None:
135
+ """Reject a limit larger than the candidate pool.
136
+
137
+ The server checks this separately from the ``numCandidates`` bounds: ``limit=5`` with
138
+ ``numCandidates=4`` is code 8, *limit should be less than or equal to numCandidates*, and ``limit=5``
139
+ with ``numCandidates=5`` succeeds. :func:`candidate_count` cannot produce a violation today. The check
140
+ keeps the bound enforced if that derivation changes.
141
+
142
+ Args:
143
+ limit: Resolved result ceiling.
144
+ num_candidates: Candidate pool, normally from :func:`candidate_count`.
145
+
146
+ Raises:
147
+ ValueError: If ``limit`` exceeds ``num_candidates``.
148
+ """
149
+ if limit > num_candidates:
150
+ raise ValueError(
151
+ f"strands_mongodb: limit ({limit}) is greater than numCandidates ({num_candidates}), and "
152
+ f"the server requires limit <= numCandidates. Raise 'oversampling_factor' or lower the "
153
+ f"limit."
154
+ )
155
+
156
+
157
+ def vector_stages(
158
+ *,
159
+ mode: VectorMode,
160
+ index_name: str,
161
+ limit: int,
162
+ query_text: str | None = None,
163
+ query_vector: list[float] | None = None,
164
+ query_filter: Mapping[str, Any] | None = None,
165
+ oversampling_factor: int = DEFAULT_OVERSAMPLING_FACTOR,
166
+ score: bool = True,
167
+ ) -> list[dict[str, Any]]:
168
+ """Build the vector tier: one ``$vectorSearch`` plus the score projection it lacks.
169
+
170
+ ``mode`` picks the builder and the ``path``. The ``autoEmbed`` index declares the text field as its
171
+ vector field, because the deployment embeds it. The manual index declares the field the caller writes.
172
+
173
+ There is no ``$limit`` stage. ``$vectorSearch`` carries its own ``limit``, and its ``filter`` is a
174
+ pre-filter, so nothing downstream can shrink the result set below the requested count.
175
+
176
+ Args:
177
+ mode: Resolved vector path, from ``_indexes.vector_mode``.
178
+ index_name: Atlas Vector Search index to query.
179
+ limit: Resolved result ceiling.
180
+ query_text: Natural-language query, on the AutoEmbeddings path only.
181
+ query_vector: Pre-computed embedding, on the manual path only.
182
+ query_filter: Validated MQL pre-filter over declared filterable paths. Omitted from the stage
183
+ when empty.
184
+ oversampling_factor: Multiplier behind ``numCandidates``.
185
+ score: Whether to append the score projection. :func:`hybrid_stages` passes ``False`` because
186
+ ``$rankFusion`` input pipelines may hold only selection stages.
187
+
188
+ Returns:
189
+ The search stage, and the ``$set`` projection when ``score``.
190
+
191
+ Raises:
192
+ ValueError: If the query's shape contradicts ``mode``, if neither or both query fields are
193
+ supplied, or if the derived candidate count is out of bounds.
194
+ """
195
+ _check_query_shape(mode, query_text=query_text, query_vector=query_vector)
196
+
197
+ candidates = candidate_count(limit, oversampling_factor)
198
+ check_candidate_count(limit=limit, num_candidates=candidates)
199
+ # The builders drop a falsy `filter`, so an empty one needs no normalizing here.
200
+ shared: dict[str, Any] = {
201
+ "search_field": CONTENT_FIELD if mode.auto_embed else VECTOR_FIELD,
202
+ "index_name": index_name,
203
+ "top_k": limit,
204
+ "filter": dict(query_filter) if query_filter else None,
205
+ "oversampling_factor": oversampling_factor,
206
+ }
207
+
208
+ if mode.auto_embed:
209
+ # `_check_query_shape` guarantees `query_text`, and `auto_embed` guarantees `mode.model`.
210
+ assert query_text is not None and mode.model is not None
211
+ stage = autoembedding_vector_search_stage(query=query_text, model=mode.model, **shared)
212
+ else:
213
+ assert query_vector is not None
214
+ stage = vector_search_stage(query_vector=query_vector, **shared)
215
+
216
+ return [stage, _score_stage(VECTOR_SCORE_META)] if score else [stage]
217
+
218
+
219
+ def text_stages(
220
+ *,
221
+ query_text: str,
222
+ index_name: str,
223
+ limit: int,
224
+ query_filter: Mapping[str, Any] | None = None,
225
+ score: bool = True,
226
+ ) -> list[dict[str, Any]]:
227
+ """Build the full-text tier, ordered so a filtered query still returns its full count.
228
+
229
+ Every stage comes from ``text_search_stage``, including the ``$limit``.
230
+
231
+ ``$search`` filtering is a post-filter, so the filter ``$match`` must come before ``$limit``. Over 200
232
+ matching documents with 10 in scope, asking for 5, this order returns 5 and an early ``$limit: 5``
233
+ returns 0. No fixed over-fetch ahead of the ``$match`` is safe either: when the filter anti-correlates
234
+ with relevance, every multiplier up to 38x returned nothing, and only the collection size always fills
235
+ the limit.
236
+
237
+ Leaving the stream unbounded until the ``$match`` does not fetch the whole corpus. The aggregation pulls
238
+ from mongot in batches of 101, growing by 1.5x, and stops once ``$limit`` is satisfied, so cost tracks
239
+ how many documents survive the filter. A filter that anti-correlates with relevance can still read to
240
+ the end, the accepted worst case.
241
+
242
+ Args:
243
+ query_text: Natural-language query, scored with BM25 by Lucene's standard analyzer.
244
+ index_name: Atlas Search index to query.
245
+ limit: Resolved result ceiling, applied last.
246
+ query_filter: Validated MQL predicate, applied as a ``$match`` before the limit. Dropped when
247
+ empty.
248
+ score: Whether to include the score projection (the builder's ``include_scores``).
249
+ :func:`hybrid_stages` passes ``False``. The projection sits before ``$limit``, so it is
250
+ dropped by keyword rather than by slicing the list.
251
+
252
+ Returns:
253
+ ``$search``, ``$match`` when there is a filter, ``$set`` when ``score``, then ``$limit``.
254
+ """
255
+ return list(
256
+ text_search_stage(
257
+ query=query_text,
258
+ search_field=CONTENT_FIELD,
259
+ index_name=index_name,
260
+ limit=limit,
261
+ filter=dict(query_filter) if query_filter else None,
262
+ include_scores=score,
263
+ )
264
+ )
265
+
266
+
267
+ def hybrid_stages(
268
+ *,
269
+ mode: VectorMode,
270
+ vector_index_name: str,
271
+ text_index_name: str,
272
+ query_text: str,
273
+ limit: int,
274
+ query_vector: list[float] | None = None,
275
+ query_filter: Mapping[str, Any] | None = None,
276
+ oversampling_factor: int = DEFAULT_OVERSAMPLING_FACTOR,
277
+ ) -> list[dict[str, Any]]:
278
+ """Build the hybrid tier: one ``$rankFusion`` over the vector and text pipelines.
279
+
280
+ The server's ``$rankFusion`` (MongoDB 8.0+) owns the weights, the rank constant, tie-breaking and the
281
+ merge of documents both tiers return, so this package does not implement reciprocal rank fusion itself.
282
+
283
+ Both input pipelines are built with ``score=False``. ``$rankFusion`` ranks by position within each
284
+ input pipeline, and an input pipeline may hold only selection stages, so the server rejects a score
285
+ projection there. No weights are emitted (both default to 1) and no ``scoreDetails``.
286
+
287
+ ``$rankFusion`` returns documents with no score field, so a ``$set`` after it projects the fused score.
288
+ See :data:`RANK_FUSION_PENALTY` for its scale. A final ``$limit`` follows, because the fused list is the
289
+ union of both branches and can hold up to twice ``limit`` documents.
290
+
291
+ Args:
292
+ mode: Resolved vector path, passed through to :func:`vector_stages`.
293
+ vector_index_name: Atlas Vector Search index for the vector branch.
294
+ text_index_name: Atlas Search index for the text branch.
295
+ query_text: Natural-language query. Required, because the text branch has nothing else to search
296
+ with.
297
+ limit: Resolved result ceiling, applied within each branch and again to the fused list.
298
+ query_vector: Pre-computed embedding, on the manual path only.
299
+ query_filter: Validated MQL predicate. Each branch places it where its tier needs it: inside the
300
+ stage for vector, in a ``$match`` for text.
301
+ oversampling_factor: Multiplier behind ``numCandidates`` on the vector branch.
302
+
303
+ Returns:
304
+ Three stages: the ``$rankFusion``, the ``$set`` projecting its fused score, and the ``$limit``.
305
+
306
+ Raises:
307
+ ValueError: Whatever :func:`vector_stages` or :func:`text_stages` raises, unchanged.
308
+ """
309
+ vector = vector_stages(
310
+ mode=mode,
311
+ index_name=vector_index_name,
312
+ limit=limit,
313
+ query_text=query_text if mode.auto_embed else None,
314
+ query_vector=query_vector,
315
+ query_filter=query_filter,
316
+ oversampling_factor=oversampling_factor,
317
+ score=False,
318
+ )
319
+ text = text_stages(
320
+ query_text=query_text, index_name=text_index_name, limit=limit, query_filter=query_filter, score=False
321
+ )
322
+ fusion = {"$rankFusion": {"input": {"pipelines": {"vector": vector, "text": text}}}}
323
+ # The fusion returns the union of both branches, up to twice `limit`.
324
+ return [fusion, _score_stage(FUSION_SCORE_META), {"$limit": limit}]
325
+
326
+
327
+ def _score_stage(meta: str) -> dict[str, Any]:
328
+ """Return the score projection the vector and hybrid tiers need.
329
+
330
+ Args:
331
+ meta: ``$meta`` name for the tier. The names are not interchangeable.
332
+
333
+ Returns:
334
+ A ``$set`` stage writing the score into :data:`SCORE_FIELD`.
335
+ """
336
+ return {"$set": {SCORE_FIELD: {"$meta": meta}}}
337
+
338
+
339
+ def check_query_keys(
340
+ *, query_text: str | None, query_vector: list[float] | None, fusion_possible: bool = False
341
+ ) -> None:
342
+ """Reject the two query shapes no tier can answer. Needs no vector mode.
343
+
344
+ Separate from :func:`_check_query_shape` so the memory store can run it before choosing a tier. The
345
+ mode-dependent check cannot run that early: on a manual-vector store, a ``text`` query is wrong for the
346
+ vector tier but right for the text tier.
347
+
348
+ Args:
349
+ query_text: What the caller put in ``text``, if anything.
350
+ query_vector: What the caller put in ``vector``, if anything.
351
+ fusion_possible: Whether the store's configuration could use both keys: the manual-vector path
352
+ with ``search_type`` at ``auto`` or ``hybrid``, where the fused tier reads ``text`` in one
353
+ input pipeline and ``vector`` in the other. It depends on the config only, so this check runs
354
+ before any round trip. Whether the server can fuse is decided later, by the tier list.
355
+
356
+ Raises:
357
+ ValueError: If both query fields are set where nothing could use both, or if neither is.
358
+ """
359
+ if query_text is not None and query_vector is not None and not fusion_possible:
360
+ raise ValueError(
361
+ "strands_mongodb: the query sets both 'text' and 'vector', and this store has no "
362
+ "interpretation that uses both. Set 'text' to have the deployment embed it, or 'vector' to "
363
+ "supply the embedding yourself. Both together are read only by the hybrid tier on a "
364
+ "manual-vector store, where each key feeds one half of the fusion."
365
+ )
366
+ if query_text is None and query_vector is None:
367
+ raise ValueError(
368
+ "strands_mongodb: the query sets neither 'text' nor 'vector'. MongoDBSearchQuery marks "
369
+ "every field optional because the valid combinations are not expressible as a TypedDict, "
370
+ "so exactly one of the two has to be present."
371
+ )
372
+
373
+
374
+ def _check_query_shape(mode: VectorMode, *, query_text: str | None, query_vector: list[float] | None) -> None:
375
+ """Reject a query whose shape contradicts the configured vector path.
376
+
377
+ An AutoEmbeddings-shaped stage against a manual index fails with code 8, ``queryVector must be
378
+ present``. The reverse is untested, because an ``autoEmbed`` index needs a registered embedding model.
379
+ Both are rejected here, where the message can name the config key that chose the path.
380
+
381
+ Args:
382
+ mode: Resolved vector path.
383
+ query_text: What the caller put in ``text``, if anything.
384
+ query_vector: What the caller put in ``vector``, if anything.
385
+
386
+ Raises:
387
+ ValueError: If both query fields are set, if neither is, or if the one that is set belongs to
388
+ the other path.
389
+ """
390
+ check_query_keys(query_text=query_text, query_vector=query_vector)
391
+
392
+ if mode.auto_embed and query_vector is not None:
393
+ raise ValueError(
394
+ "strands_mongodb: the query supplies 'vector', but this store is on the Atlas "
395
+ "AutoEmbeddings path, whose index declares the text field as its vector field and holds no "
396
+ "caller-supplied embeddings. That path is selected by 'embedding_model', and also by "
397
+ "setting none of the vector keys at all, which is why this can surprise a caller who set "
398
+ "nothing. Query with 'text' instead, or set 'embedding_dimensions' and 'similarity' in "
399
+ "MongoDBConfig to select the manual path. Switching paths means recreating the vector "
400
+ "index, since the two index different fields."
401
+ )
402
+ if not mode.auto_embed and query_text is not None:
403
+ raise ValueError(
404
+ "strands_mongodb: the query supplies 'text', but 'embedding_dimensions' and 'similarity' "
405
+ "in MongoDBConfig select the manual-vector path, where the deployment does not embed and "
406
+ "this package does not either. Supply 'vector' with an embedding you computed, or remove "
407
+ "both config keys to use Atlas AutoEmbeddings."
408
+ )
@@ -0,0 +1,254 @@
1
+ """OpenTelemetry spans and structured log fields for both stores. The only module that imports OpenTelemetry.
2
+
3
+ The package configures no provider, exporter or sampling. The tracer is looked up on every call, so a
4
+ provider installed after import still gets spans, and with none installed the no-op tracer costs a
5
+ function call.
6
+
7
+ Only allow-listed attributes are recorded. No span carries caller data: keys, content, metadata, query
8
+ text, filter values, scope or memory ids. ``traced`` reads the store instance, never the
9
+ call's arguments. ``span``, ``annotate`` and ``event`` accept only names in ``Attribute``, checked by
10
+ ``mypy`` and again at runtime, where an unknown name is dropped rather than raised so a telemetry typo
11
+ never fails a write.
12
+
13
+ Exceptions are recorded as a status and a type name, never a message. Raised messages name the key and
14
+ the namespace, and spans are exported to third parties.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import contextlib
20
+ import functools
21
+ import logging
22
+ from typing import TYPE_CHECKING, Any, Final, Literal, ParamSpec, TypeVar, get_args
23
+
24
+ from strands_mongodb import __version__
25
+ from strands_mongodb._extras import missing_extra
26
+
27
+ # Both runtime extras bring `opentelemetry-api`, so this fires only on a bare install.
28
+ try:
29
+ from opentelemetry import trace
30
+ from opentelemetry.trace import SpanKind, Status, StatusCode
31
+ except ImportError as error: # pragma: no cover - exercised in a subprocess
32
+ missing_extra("storage", error, module=__name__)
33
+
34
+ if TYPE_CHECKING:
35
+ from collections.abc import Callable, Coroutine, Iterator, Mapping
36
+
37
+ from opentelemetry.util.types import AttributeValue
38
+
39
+ __all__ = ["Attribute", "EventName", "LogEvent", "SpanName", "annotate", "event", "event_extra", "span", "traced"]
40
+
41
+ logger = logging.getLogger(__name__)
42
+
43
+ _P = ParamSpec("_P")
44
+ _R = TypeVar("_R")
45
+
46
+ #: Every attribute name the package may set, one per row of the README's attribute table.
47
+ Attribute = Literal[
48
+ "strands_mongodb.store_name",
49
+ "strands_mongodb.search.requested",
50
+ "strands_mongodb.search.tier",
51
+ "strands_mongodb.search.tiers",
52
+ "strands_mongodb.result_count",
53
+ "strands_mongodb.deleted_count",
54
+ "strands_mongodb.found",
55
+ "strands_mongodb.duplicate",
56
+ "strands_mongodb.database",
57
+ "strands_mongodb.collection",
58
+ "strands_mongodb.client.injected",
59
+ "strands_mongodb.indexes.mode",
60
+ "strands_mongodb.indexes.created",
61
+ "strands_mongodb.indexes.outcome",
62
+ "strands_mongodb.indexes.probe",
63
+ ]
64
+
65
+ #: Every span opened by ``span`` rather than by ``traced``: index work, as a child of the operation that needed it.
66
+ SpanName = Literal[
67
+ "strands_mongodb.indexes.ensure",
68
+ "strands_mongodb.indexes.probe",
69
+ "strands_mongodb.indexes.wait",
70
+ ]
71
+
72
+ #: The ``strands_mongodb_event`` value of every log record the package emits, one per message.
73
+ LogEvent = Literal[
74
+ "retry_writes_disabled",
75
+ "attribution_not_visible",
76
+ "closed_loop_client_dropped",
77
+ "reserved_key_collision",
78
+ "no_search_setup",
79
+ "tier_unavailable",
80
+ "tier_building",
81
+ "below_vector",
82
+ "bound_declined_fusion",
83
+ "score_bound_applied",
84
+ "creating_indexes",
85
+ "creating_search_index",
86
+ "search_index_status",
87
+ "attribute_dropped",
88
+ ]
89
+
90
+ #: Every span event the package may add.
91
+ EventName = Literal["strands_mongodb.client.acquired"]
92
+
93
+ _ALLOWED: Final[frozenset[str]] = frozenset(get_args(Attribute))
94
+
95
+
96
+ def traced(
97
+ surface: Literal["storage", "memory"], operation: str
98
+ ) -> Callable[[Callable[_P, Coroutine[Any, Any, _R]]], Callable[_P, Coroutine[Any, Any, _R]]]:
99
+ """Record one ``INTERNAL`` span named ``strands_mongodb.<surface>.<operation>`` around a store method.
100
+
101
+ Apply it outermost, above ``_reporting``, so the span sees the ``StorageError`` the caller sees rather
102
+ than the driver error underneath.
103
+
104
+ Args:
105
+ surface: ``storage`` or ``memory``. A memory span also records the store's name.
106
+ operation: The public method's name.
107
+
108
+ Returns:
109
+ A decorator for an async method whose ``self`` has ``_database_name`` and ``_collection_name``.
110
+
111
+ Raises:
112
+ Exception: Whatever the decorated method raises, re-raised as the same object after the span is
113
+ marked. The decorator raises nothing of its own.
114
+ """
115
+ name = f"strands_mongodb.{surface}.{operation}"
116
+
117
+ def decorate(method: Callable[_P, Coroutine[Any, Any, _R]]) -> Callable[_P, Coroutine[Any, Any, _R]]:
118
+ @functools.wraps(method)
119
+ async def tracing(*args: _P.args, **kwargs: _P.kwargs) -> _R:
120
+ # A local because mypy rejects indexing `ParamSpec` args. Only `self` is read: the call's
121
+ # arguments carry caller data.
122
+ positional: tuple[Any, ...] = args
123
+ tracer = trace.get_tracer("strands_mongodb", __version__)
124
+ with tracer.start_as_current_span(
125
+ name,
126
+ kind=SpanKind.INTERNAL,
127
+ attributes=_base(positional[0], surface),
128
+ record_exception=False,
129
+ set_status_on_exception=False,
130
+ ) as span:
131
+ try:
132
+ return await method(*args, **kwargs)
133
+ except Exception as error:
134
+ # Not `BaseException`: a cancelled call is not a store failure, so its status stays unset.
135
+ _mark(span, error)
136
+ raise
137
+
138
+ # On the wrapper, not in a registry, so a test can list a store class's spans without its own.
139
+ tracing.__dict__["strands_mongodb_span"] = name
140
+ return tracing
141
+
142
+ return decorate
143
+
144
+
145
+ @contextlib.contextmanager
146
+ def span(name: SpanName, attributes: Mapping[Attribute, AttributeValue]) -> Iterator[None]:
147
+ """Open an ``INTERNAL`` child span under the current one, for work a store operation causes.
148
+
149
+ Same rules as ``traced``: the tracer is looked up on entry, attributes pass through the allow-list, and
150
+ an exception is recorded as a status and a type name, then re-raised unchanged. Inside it, ``annotate``
151
+ sets attributes on this span rather than the operation's.
152
+
153
+ Args:
154
+ name: An index span name.
155
+ attributes: Its starting attributes, usually the namespace and the mode or probe.
156
+
157
+ Yields:
158
+ Nothing. The span is current for the body of the ``with``.
159
+
160
+ Raises:
161
+ Exception: Whatever the body raises, re-raised as the same object after the span is marked. The
162
+ context manager raises nothing of its own.
163
+ """
164
+ kept: dict[str, AttributeValue] = {key: value for key, value in attributes.items() if _allowed(key)}
165
+ tracer = trace.get_tracer("strands_mongodb", __version__)
166
+ with tracer.start_as_current_span(
167
+ name,
168
+ kind=SpanKind.INTERNAL,
169
+ attributes=kept,
170
+ record_exception=False,
171
+ set_status_on_exception=False,
172
+ ) as current:
173
+ try:
174
+ yield
175
+ except Exception as error:
176
+ _mark(current, error)
177
+ raise
178
+
179
+
180
+ def event_extra(event: LogEvent, *, namespace: str | None = None, tier: str | None = None) -> dict[str, str]:
181
+ """Build the ``extra`` mapping for one log record, so a JSON formatter can index it without parsing.
182
+
183
+ Keys are prefixed ``strands_mongodb_`` because ``logging`` raises ``KeyError`` for an ``extra`` key
184
+ that collides with a ``LogRecord`` attribute such as ``name``. A field that does not apply is omitted
185
+ rather than set to ``None``.
186
+
187
+ Args:
188
+ event: The record's stable name.
189
+ namespace: ``<database>.<collection>``, where the record concerns one.
190
+ tier: The search tier, where the record concerns one.
191
+
192
+ Returns:
193
+ The mapping to pass as ``extra``.
194
+ """
195
+ extra: dict[str, str] = {"strands_mongodb_event": event}
196
+ if namespace is not None:
197
+ extra["strands_mongodb_namespace"] = namespace
198
+ if tier is not None:
199
+ extra["strands_mongodb_tier"] = tier
200
+ return extra
201
+
202
+
203
+ def annotate(name: Attribute, value: AttributeValue) -> None:
204
+ """Set an outcome attribute on the current span, which inside a store method is the operation's own.
205
+
206
+ A no-op under the no-op tracer, so call sites need no conditionals.
207
+
208
+ Args:
209
+ name: An allow-listed attribute name.
210
+ value: A count, flag, tier name or configuration value. Never anything the caller supplied.
211
+ """
212
+ if _allowed(name):
213
+ trace.get_current_span().set_attribute(name, value)
214
+
215
+
216
+ def event(name: EventName, attributes: Mapping[Attribute, AttributeValue]) -> None:
217
+ """Add an event to the current span, keeping only allow-listed attributes.
218
+
219
+ Args:
220
+ name: The event name.
221
+ attributes: The event's attributes.
222
+ """
223
+ kept: dict[str, AttributeValue] = {key: value for key, value in attributes.items() if _allowed(key)}
224
+ trace.get_current_span().add_event(name, kept)
225
+
226
+
227
+ def _allowed(name: str) -> bool:
228
+ """Whether ``name`` is on the allow-list, logging at ``DEBUG`` when it is not."""
229
+ if name in _ALLOWED:
230
+ return True
231
+ logger.debug(
232
+ "strands_mongodb: dropped span attribute %r, which is not on the allow-list",
233
+ name,
234
+ extra=event_extra("attribute_dropped"),
235
+ )
236
+ return False
237
+
238
+
239
+ def _mark(current: trace.Span, error: Exception) -> None:
240
+ """Record a failure as ``ERROR`` with the class name, and ``error.type``, never the message."""
241
+ kind = type(error)
242
+ current.set_status(Status(StatusCode.ERROR, kind.__name__))
243
+ current.set_attribute("error.type", f"{kind.__module__}.{kind.__qualname__}")
244
+
245
+
246
+ def _base(instance: Any, surface: str) -> dict[str, AttributeValue]:
247
+ """The attributes every span carries, read off the store and never off the call."""
248
+ attributes: dict[str, AttributeValue] = {
249
+ "strands_mongodb.database": instance._database_name,
250
+ "strands_mongodb.collection": instance._collection_name,
251
+ }
252
+ if surface == "memory":
253
+ attributes["strands_mongodb.store_name"] = instance.name
254
+ return attributes