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.
- strands_mongodb/__init__.py +76 -0
- strands_mongodb/_client.py +508 -0
- strands_mongodb/_extras.py +39 -0
- strands_mongodb/_filter.py +221 -0
- strands_mongodb/_indexes.py +1314 -0
- strands_mongodb/_pipeline.py +408 -0
- strands_mongodb/_telemetry.py +254 -0
- strands_mongodb/memory_store.py +1282 -0
- strands_mongodb/py.typed +1 -0
- strands_mongodb/storage.py +693 -0
- strands_mongodb/types.py +236 -0
- strands_mongodb/vector_search.py +216 -0
- strands_mongodb-0.1.0.dev1.dist-info/METADATA +1032 -0
- strands_mongodb-0.1.0.dev1.dist-info/RECORD +17 -0
- strands_mongodb-0.1.0.dev1.dist-info/WHEEL +4 -0
- strands_mongodb-0.1.0.dev1.dist-info/licenses/LICENSE +175 -0
- strands_mongodb-0.1.0.dev1.dist-info/licenses/NOTICE +10 -0
|
@@ -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
|