goodmem-deepeval 0.3.0__tar.gz

goodmem_deepeval-0.3.0/.gitignore

@@ -0,0 +1,21 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.pytest_cache/
+.tox/
+.venv/
+.env
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.DS_Store
+.venv/
+.venv-smoke/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+dist/

goodmem_deepeval-0.3.0/CHANGELOG.md

@@ -0,0 +1,171 @@
+# Changelog
+
+## 0.3.0
+
+### Changed
+
+- **Breaking:** renamed to `goodmem-deepeval` (import `goodmem_deepeval`),
+  the goodmem-<framework> naming used by goodmem-adk and
+  goodmem-semantic-kernel. Update imports from `deepeval_goodmem` to
+  `goodmem_deepeval`.
+
+## 0.2.2
+
+Both fixes were reproduced against a live GoodMem server (v1.0.320) on
+0.2.1 and re-measured with the identical probe after the fix.
+
+### Fixed
+
+- **A failed reranker's fallback was reported as reranked, and `min_score`
+  discarded it.** With `reranker_id` set and the reranker failing, the server
+  sends `NOT_FOUND` (naming the reranker) and `RERANKING_FAILED` and still
+  returns the vector-stage hits (`stageName: "retrieve"`, raw scores
+  `-0.785, -0.577, -0.112` live). 0.2.1 decided `score_kind` from
+  configuration, so every hit was `"reranker"`, and `min_score` was applied
+  to vector distances: live, `min_score=0.0` returned **0 of the 3 hits** the
+  server sent, with a warning blaming the reranker's score range. Now the
+  response decides, once the whole stream is in: the hits are reranked only
+  if a reranker was requested and the server reported neither
+  `RERANKING_FAILED` nor a `NOT_FOUND` naming the reranker (`reranker_id` /
+  `rerankerId` in its details, or "reranker" in its message). Fallback hits
+  are `score_kind: "vector"` with their raw scores, `min_score` is not
+  applied to them, and the result stays `partial: true` with its statuses
+  (retrieval status contract Q4a). An unrelated status leaves reranker
+  scores and the threshold as they were; a threshold that empties genuinely
+  reranked hits still warns and names the observed range.
+- **Boolean and float `metadata_filter` values silently matched nothing.**
+  Every value became `text_equals(field, str(value))`, so `{"flag": True}` was
+  sent as `CAST(val('$.flag') AS TEXT) = 'True'`: live, HTTP 200 and **0
+  results** against a memory stored with `flag: true` (`{"flag": False}` the
+  same), and `{"n": 5.0}` sent as `'5.0'` missed a stored `5`, all of which
+  read as "nothing stored". `None` was sent as the text `'None'`. Values are
+  now compared as their own type, ported from langchain-goodmem's filter
+  builder: `bool` as `BOOLEAN` (`true`/`false`, checked before `int`),
+  `int`/`float` as `NUMERIC` (finite, written as plain decimals), `str` as
+  `TEXT` with the same escaping as before. `None` and any other type raise
+  `ValueError` before a request instead of being turned into text. Live,
+  `{"flag": True}`, `{"flag": False}`, `{"n": 5}`, `{"n": 5.0}` and
+  `{"flag": True, "n": 5}` now each return the one matching memory; string
+  filters (including `O'Brien`, `a\\b` and the `x' OR '1'='1` injection) send
+  the same expression as 0.2.1. Field names are checked with a full match, so
+  a trailing newline is refused.
+
+### Tests
+
+- `tests/test_reranker_fallback.py`: 15 offline tests over the captured
+  broken-reranker and reranked streams (reordered, or with one status added
+  or removed), decoded by the real SDK. 10 fail on 0.2.1; the 5 controls
+  (working reranker, unrelated statuses, threshold warning) pass on both.
+- `tests/test_typed_filters.py`: 36 offline tests driving `search()` through
+  the real SDK (the expression on the wire, or a refusal with nothing sent),
+  one of them checking the README's filter table against the builder.
+  23 fail on 0.2.1; the 13 controls
+  (strings and their escaping, control characters, unsafe field names, the
+  empty mapping) pass on both.
+- Two live tests: a missing reranker with `min_score=0.0` keeps its 3
+  vector hits, and boolean/number filters match. Both fail on 0.2.1.
+- 87 offline tests (was 36); 14 live tests (was 12).
+
+## 0.2.1
+
+Documentation only; no code change.
+
+### Fixed
+
+- **README: the headline example did not run.** It built the test case with
+  `to_test_case(result, actual_output=answer)` and then evaluated it with
+  `ContextualRecallMetric`, which requires `expected_output`. Executed as
+  written, `evaluate()` stopped with `MissingTestCaseParamsError: 'expected_output'
+  cannot be None for the 'Contextual Recall' metric` (both the first example
+  and the health-metric example). The example now passes `expected_output`,
+  the health-metric example imports what it uses, and the README says which
+  RAG metrics need a reference answer. Measured: 4/6 README Python blocks ran
+  before, 6/6 after.
+- README: the `search()` return table now lists the `query` key it returns.
+
+### Added
+
+- `tests/test_readme.py` executes every README Python block through the real
+  SDK over the captured-bytes transport and fails if a metric the README
+  passes to `evaluate()` lacks a test-case field it requires. 36 offline
+  tests (was 34).
+
+## 0.2.0
+
+A rewrite. 0.1.0 shipped no DeepEval integration: it was fourteen classes
+wrapping REST endpoints with `httpx`, and `deepeval` was not even a
+dependency. 0.2.0 is what the name promises, built on the official `goodmem`
+SDK.
+
+Every claim below was reproduced against a live GoodMem server (v1.0.320)
+before the fix, and the offline tests replay bytes captured from it.
+
+### Added
+
+- **`GoodMemRetriever`** — `search()` is decorated with
+  `@observe(type="retriever")` and reports `top_k`/embedder through
+  `update_retriever_span`, so a retrieval is a DeepEval retriever span.
+- **`retrieve()`** — returns `list[str]`, the shape `retrieval_context` wants.
+- **`to_test_case()`** — builds an `LLMTestCase` with `retrieval_context`
+  populated and the retrieval's diagnostics in `metadata["goodmem"]`.
+- **`GoodMemRetrievalHealthMetric`** — a real `BaseMetric` that fails a case
+  whose retrieval was degraded, so a broken reranker is its own failure
+  instead of a mysterious drop in someone else's recall number.
+- 34 offline tests over captured server bytes and 12 live tests with verified
+  teardown. 0.1.0 had 0 tests in CI, and no CI.
+
+### Fixed
+
+| Behaviour | 0.1.0 (reproduced live) | 0.2.0 |
+| --- | --- | --- |
+| Retrieval with a broken reranker | `success: true`, `totalResults: 1` — the server sent `NOT_FOUND` **and** `RERANKING_FAILED` and the NDJSON parser had no `status` branch, so both were dropped. The result was an *unreranked* fallback presented as a successful reranked search | `partial: true` with both statuses; the fallback chunks are kept |
+| Retrieval that failed outright | `success: true, totalResults: 0` with a message blaming indexing | Empty `hits`, `partial: true`, statuses, and a warning — never raised |
+| Searching an empty space | **63.8 seconds** (`wait_for_indexing=True`, `max_wait_seconds=60`, `poll_interval=5` → 12 re-POSTs, each re-invoking the LLM when `llm_id` was set) | **0.3 seconds**, one request |
+| Relevance scores | Documented as "Minimum relevance score (0-1)"; live values were `-0.57` (vector) and `0.17` (reranker) | Reported as sent, in the server's order, with `score_kind`; `min_score` is client-side and reranker-only |
+| `metadata_filter` | A raw string pasted into the request. Live, `x' OR '1'='1` subverted the filter and returned a row it should not have | A dict, quoted for the live filter grammar; control characters refused |
+| Any error | `run()` caught **everything** and returned `{"success": false, "error": "Client error '400 Bad Request' … check https://developer.mozilla.org/…"}` as a *string* — the server's actual reason (`Invalid space ID format: not-a-uuid`) was discarded for an MDN link | Errors propagate with the server's message |
+| `update_space(public_read=…)` | HTTP 400 — the field was removed from the API | Gone |
+| Space name collisions | Not checked | Reuse when the embedder matches; a mismatch or an ambiguous name is an error |
+| API key | A plain attribute on every operation object | A private connection; never in `model_dump()`, `repr()` or a trace |
+
+### Migration
+
+The fourteen `GoodMem*` operation classes are gone; they were a REST client,
+and the `goodmem` SDK does that job better.
+
+```python
+# 0.1.0
+from deepeval_goodmem import GoodMemRetrieveMemories
+out = json.loads(GoodMemRetrieveMemories(...).run(query="…", space_ids=sid))
+for r in out["results"]:
+    print(r["chunkText"], r["relevanceScore"])
+
+# 0.2.0
+from deepeval_goodmem import GoodMemRetriever
+result = GoodMemRetriever(space_id=sid).search("…")
+for h in result["hits"]:
+    print(h["chunk_text"], h["score"], h["score_kind"])
+
+# 0.2.0 — for plain API access, use the SDK directly
+from goodmem import Goodmem
+Goodmem(base_url=…, api_key=…).spaces.create(...)
+```
+
+| 0.1.0 | 0.2.0 |
+| --- | --- |
+| `GoodMemRetrieveMemories(...).run(query=, space_ids=)` | `GoodMemRetriever(space_ids=[...]).search(query)` |
+| `out["results"][i]["chunkText"]` | `result["hits"][i]["chunk_text"]` |
+| `out["results"][i]["relevanceScore"]` | `result["hits"][i]["score"]` + `["score_kind"]` |
+| `relevance_threshold=` | `min_score=`, with `reranker_id` set |
+| `metadata_filter="CAST(...)"` | `metadata_filter={"field": "value"}` (or `filter=` for an expression) |
+| `GoodMemCreateSpace` / `GoodMemGetSpace` / … | `goodmem.Goodmem().spaces.*` |
+| `GoodMemCreateMemory` / `GoodMemListMemories` / … | `goodmem.Goodmem().memories.*` |
+
+Prior art: the in-tree integration in the `deepeval-goodmem` fork of upstream
+DeepEval established the `@observe(type="retriever")` + `update_retriever_span`
+shape, the `list[str]` return for `retrieval_context`, and a
+`wait_for_indexing` default of `False`. All three are carried over here.
+
+## 0.1.0
+
+Initial release.

goodmem_deepeval-0.3.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 GoodMem
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

goodmem_deepeval-0.3.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.5
+Name: goodmem-deepeval
+Version: 0.3.0
+Summary: GoodMem retrieval for DeepEval — a traced retriever, LLMTestCase construction, and a retrieval-health metric.
+Project-URL: homepage, https://github.com/PAIR-Systems-Inc/goodmem_deepeval
+Project-URL: source, https://github.com/PAIR-Systems-Inc/goodmem_deepeval
+Project-URL: issues, https://github.com/PAIR-Systems-Inc/goodmem_deepeval/issues
+Author: PAIR Systems
+License-File: LICENSE
+Keywords: deepeval,evaluation,goodmem,llm,rag,retrieval,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: deepeval>=4.0
+Requires-Dist: goodmem>=0.1.34
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy==1.18.2; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff==0.16.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# goodmem-deepeval
+
+GoodMem retrieval for [DeepEval](https://deepeval.com).
+
+Every retrieval is a DeepEval **retriever span**, and a retrieval turns
+directly into an `LLMTestCase` with `retrieval_context` populated — which is
+what `ContextualPrecisionMetric`, `ContextualRecallMetric`,
+`ContextualRelevancyMetric` and `FaithfulnessMetric` actually read.
+
+```bash
+pip install goodmem-deepeval
+```
+
+## Retrieve and evaluate
+
+```python
+from deepeval import evaluate
+from deepeval.metrics import ContextualRelevancyMetric, ContextualRecallMetric
+from goodmem_deepeval import GoodMemRetriever, GoodMemRetrievalHealthMetric
+
+retriever = GoodMemRetriever(space_name="docs", limit=5)   # credentials from the environment
+
+result = retriever.search("how do I rotate an API key?")
+answer = my_llm(result["hits"])                            # your generation step
+expected = "…"                                             # your reference answer
+
+case = retriever.to_test_case(result, actual_output=answer, expected_output=expected)
+
+evaluate([case], [
+    ContextualRelevancyMetric(),
+    ContextualRecallMetric(),
+    GoodMemRetrievalHealthMetric(),
+])
+```
+
+`ContextualRecallMetric` and `ContextualPrecisionMetric` compare against a
+reference answer, so they need `expected_output`; without it DeepEval's
+`evaluate()` raises `MissingTestCaseParamsError`.
+`ContextualRelevancyMetric` and `FaithfulnessMetric` do not.
+
+`search()` is decorated with `@observe(type="retriever")` and reports `top_k`
+and the embedder through `update_retriever_span`, so the call appears as a
+retriever span with its query, latency and results.
+
+If you only need the context, `retrieve()` returns the chunk text directly:
+
+```python
+context = retriever.retrieve("how do I rotate an API key?")   # list[str]
+```
+
+### What `search()` returns
+
+| Key | What it is |
+| --- | --- |
+| `query` | The query, as passed |
+| `hits` | `chunk_id`, `chunk_text`, `memory_id`, `space_id`, `source`, `score`, `score_kind`, `metadata` — in the server's order |
+| `score_kind` | `"vector"` or `"reranker"`: what the server returned, not what was configured. Different scales; see below |
+| `statuses` | Statuses indicating a real problem, `[]` when clean |
+| `partial` | `True` when the server reported a real problem during this retrieval, with or without hits |
+| `abstract_reply` | The server-generated summary, only when `llm_id` is set |
+| `space_ids` | Which spaces were actually searched |
+
+A retrieval that reported a problem and returned nothing is an empty `hits`
+with `partial: True` **and a warning** — never an exception, and never
+indistinguishable from "no matches".
+
+## The health metric
+
+```python
+from deepeval import evaluate
+from deepeval.metrics import ContextualRecallMetric
+from goodmem_deepeval import GoodMemRetrievalHealthMetric
+
+# cases: LLMTestCases built with retriever.to_test_case(...), as above
+evaluate(cases, [ContextualRecallMetric(), GoodMemRetrievalHealthMetric()])
+```
+
+Every other RAG metric scores the *content* that came back, so a broken
+reranker and a thin corpus look identical: both are poor recall.
+`GoodMemRetrievalHealthMetric` reads the diagnostics `to_test_case` puts in
+`metadata["goodmem"]` and scores the retrieval itself — `1.0` clean, `0.0`
+degraded, with the server's status codes in `reason` and `score_breakdown`.
+No LLM, so it costs nothing and never flakes. A test case with no GoodMem
+metadata is skipped rather than failed.
+
+## Scores
+
+GoodMem returns two different things in the same field:
+
+| | Range observed live | Best match is |
+| --- | --- | --- |
+| Vector score | negative, e.g. `-0.57` | the **lowest** number |
+| Reranker score | can also go negative | the **highest** number |
+
+So results keep **the server's order** and are never re-sorted; `score_kind`
+says which scale you have; and `min_score` is applied client-side, only to
+reranker scores. The server's `relevance_threshold` is never sent.
+
+`score_kind` says what the server actually did, not what was configured. When
+`reranker_id` is set but the reranker fails, the server reports
+`RERANKING_FAILED` (and `NOT_FOUND` for a missing reranker) and still returns
+the vector-stage hits. Those hits are `score_kind: "vector"` with their raw
+vector scores, and `min_score` is not applied to them, so a reranker threshold
+cannot discard what the server returned; `partial` is `True` and `statuses`
+carries both codes. (0.2.1 labelled them `"reranker"`, and live, with a
+missing reranker, `min_score=0.0` returned none of the 3 hits the server sent.)
+
+Even with a reranker the scale is **model-dependent**: on the same documents
+Voyage `rerank-2.5` scored `0.27..0.93` and Jina `jina-reranker-v3` scored
+`-0.14..0.43`. A `min_score` tuned for one empties the other, so when a
+threshold removes every hit the retriever warns and names the observed range.
+Calibrate `min_score` for the reranker you use; there is no default.
+
+## Filtering
+
+```python
+retriever = GoodMemRetriever(space_name="docs", metadata_filter={"category": "billing"})
+retriever.search("refunds", metadata_filter={"lang": "en", "archived": False})  # AND-ed per call
+```
+
+Each value is compared as its own type; the Python type picks the cast:
+
+| `metadata_filter` | Sent to the server |
+| --- | --- |
+| `{"category": "billing"}` | `CAST(val('$.category') AS TEXT) = 'billing'` |
+| `{"archived": False}` | `CAST(val('$.archived') AS BOOLEAN) = false` |
+| `{"year": 2026}` | `CAST(val('$.year') AS NUMERIC) = 2026` |
+| `{"score": 2.5}` | `CAST(val('$.score') AS NUMERIC) = 2.5` |
+
+Pass the type your metadata stores. Live (v1.0.320), 0.2.1 sent
+`{"flag": True}` as `AS TEXT = 'True'`, which the server accepts with HTTP 200
+and matches nothing, so a boolean filter looked like "nothing stored"; and
+`{"n": 5.0}` as `'5.0'`, which misses a stored `5`. `AS BOOLEAN` and
+`AS NUMERIC` match both. `None` and any other type (lists, dicts, bytes, NaN,
+infinity) raise `ValueError` before a request rather than being turned into
+text that silently matches nothing.
+
+Text values are quoted for the GoodMem filter grammar (backslash escaping,
+verified against a live server; control characters refused). For anything
+more complex, pass an expression directly with `filter=...`.
+
+## Attaching to a space by name
+
+```python
+GoodMemRetriever(space_name="docs", embedder_id="…")                     # reuse or fail
+GoodMemRetriever(space_name="docs", embedder_id="…", create_space=True)  # or create it
+```
+
+Attach-by-name is idempotent reuse: an existing space whose embedder matches
+is reused; a **different** embedder is an error, because retrieving across
+mismatched embedders returns plausible-looking nonsense. An ambiguous name is
+an error too.
+
+## Credentials
+
+From `GOODMEM_BASE_URL` and `GOODMEM_API_KEY`, or as constructor keywords:
+
+```python
+GoodMemRetriever(space_name="docs", base_url="https://goodmem.example.com",
+                 api_key="gm_…")
+```
+
+`verify_ssl` defaults to on and exists for a local server with a self-signed
+certificate only; no example here turns it off.
+
+They are deliberately **not** model fields, so they cannot reach a
+`model_dump()`, a `repr()` or a trace payload.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check src tests examples && mypy && pytest -m "not integration"
+```
+
+CI runs the same three on Python 3.10–3.13, then builds the sdist and wheel,
+imports the wheel in a clean virtualenv, and fails if a GoodMem API key
+(`gm_` followed by 20 or more lowercase letters or digits) is anywhere in the
+tree.
+
+The offline suite replays NDJSON captured from a live GoodMem server
+(v1.0.320) through the real SDK decoders, so the wire format is never
+invented. The live suite needs a server and is skipped without one:
+
+```bash
+GOODMEM_BASE_URL=… GOODMEM_API_KEY=… GOODMEM_EMBEDDER_ID=… \
+  GOODMEM_RERANKER_ID=… SSL_CERT_FILE=/path/to/local-ca.pem \
+  pytest -m integration
+```
+
+`GOODMEM_RERANKER_ID` is optional — the working-reranker test skips without
+it. For a local server with a self-signed certificate, point `SSL_CERT_FILE`
+at its CA so TLS verification stays on (`GOODMEM_VERIFY_SSL=0` turns it off).
+`GOODMEM_E2E_SPACE_PREFIX` names the temporary test space (default
+`goodmem-deepeval-e2e-`), so its owner is recognisable on a shared server.
+
+There is no default credential anywhere in this repository.
+
+## License
+
+MIT