goodmem-nlweb 0.3.0__tar.gz

goodmem_nlweb-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_nlweb-0.3.0/CHANGELOG.md

@@ -0,0 +1,194 @@
+# Changelog
+
+## 0.3.0
+
+### Changed
+
+Renamed to `goodmem-nlweb` (import `goodmem_nlweb`), the goodmem-<framework>
+naming used by goodmem-adk and goodmem-semantic-kernel. Breaking: update
+imports from `nlweb_goodmem` to `goodmem_nlweb`, and NLWeb provider entries
+from `import_path: nlweb_goodmem` to `import_path: goodmem_nlweb`.
+
+## 0.2.2
+
+### Fixed
+
+**`metadata_filter` values are compared under the cast their type calls
+for.** `search(..., metadata_filter={...})` turned every value into
+`str(value)` and compared it as `TEXT`. GoodMem answers a comparison under the
+wrong cast with HTTP 200 and no results, so a boolean filter looked exactly
+like "nothing stored". Now `bool` is compared as `BOOLEAN` (checked before
+`int`, which it subclasses), `int`/`float` as `NUMERIC` (plain decimals), and
+`str` as `TEXT` with the same escaping as before. `None`, non-finite numbers
+and any other type raise `ValueError` before a request is made.
+
+Measured against a live server (v1.0.320) through `search()`, in a space
+holding `amman` (`{"flag": true, "n": 5, "category": "x"}`), `petra`
+(`{"flag": false, "n": 3, "category": "y"}`) and a memory with neither:
+
+| `metadata_filter` | 0.2.1 sent → matched | 0.2.2 sent → matched |
+| --- | --- | --- |
+| `{"flag": True}` | `CAST(val('$.flag') AS TEXT) = 'True'` → nothing | `CAST(val('$.flag') AS BOOLEAN) = true` → `amman` |
+| `{"flag": False}` | `… AS TEXT) = 'False'` → nothing | `… AS BOOLEAN) = false` → `petra` |
+| `{"n": 5.0}` | `CAST(val('$.n') AS TEXT) = '5.0'` → nothing | `CAST(val('$.n') AS NUMERIC) = 5.0` → `amman` |
+| `{"n": 5}` | `… AS TEXT) = '5'` → `amman` (the text of a stored 5 happens to be `'5'`) | `… AS NUMERIC) = 5` → `amman` |
+| `{"flag": True, "n": 5, "category": "x"}` (as `yaml.safe_load` gives it) | nothing | `amman` |
+| `{"flag": None}` | `… AS TEXT) = 'None'` → nothing | `ValueError`; no request |
+| `{"n": float("nan")}`, `{"tags": ["a", "b"]}` | sent as `'nan'`, `'[\'a\', \'b\']'` (recorded over the mock transport) | `ValueError`; no request |
+| `{"category": "x"}`, `{"quote": "it's"}`, `{"bs": "a\\b"}` | `TEXT`, escaped → `amman` | unchanged |
+| `{"flag": "true"}` (a string) | `… AS TEXT) = 'true'` → nothing | unchanged: a string is text |
+
+The README documents the rule under "Metadata filters", including how a
+filter read from YAML is typed (`true` is a bool, `"true"` a string) and that
+`metadata_filter` is a `search()` argument: a `metadata_filter:` key in the
+provider's NLWeb entry is ignored.
+
+### Tests
+
+- 194 offline tests (was 159). `tests/test_filters.py` (34) drives
+  `search()` through the real SDK over a mock transport and asserts on the
+  filter that reaches the wire, including the README's table, Python example
+  and YAML block; 25 of them fail on 0.2.1 (the other 9 are string, empty and
+  control-character controls that must not change). `tests/test_config.py`
+  adds one test that a `metadata_filter:` key in the provider entry sends no
+  filter.
+- 22 live tests (was 13): the fixture adds a memory with typed metadata, and
+  9 tests filter on it by bool, int, float, text and all three together, and
+  check that `False`, `4`, `"true"` and `"y"` exclude it. On 0.2.1 the bool,
+  float and combined filters fail.
+
+## 0.2.1
+
+### Security
+
+**An id is refused unless it is a UUID, before any request is made.** The
+`goodmem` SDK (0.1.35) builds request paths by interpolating ids unencoded
+(`f"/v1/spaces/{space_id}/memories"`, `f"/v1/memories/{id}"`) and httpx
+resolves dot segments before it sends, so an id could steer a request to a
+different endpoint. Every GoodMem id is a UUID, so one validator,
+`nlweb_goodmem._ids.require_uuid`, accepts a canonical UUID (lowercased, or a
+`uuid.UUID`) and refuses everything else with `ValueError`.
+
+Measured against a local HTTP server that records each request line as it
+arrives (`<U>` is a well-formed UUID):
+
+| Input | 0.2.0 sent | 0.2.1 |
+| --- | --- | --- |
+| `space_id="../spaces/<U>"`, then `get_sites()` | `GET /v1/spaces/<U>/memories` — another space's memories | `ValueError` naming `space_id`; nothing sent |
+| the same, then `GoodMemObjectLookupProvider.get_by_id(url)` | `GET /v1/spaces/<U>/memories?filter=…` | refused; nothing sent |
+| `space_id="<U>#frag"`, then `get_sites()` | `GET /v1/spaces/<U>` — the space record, not its memories | refused; nothing sent |
+| `space_id="<U>?x=1"`, then `get_by_id(url)` | `GET /v1/spaces/<U>?filter=…` | refused; nothing sent |
+| `space_id="../spaces/<U>"`, then `search()` or `upload_documents()` | the value, in the request body | refused; nothing sent |
+| a space id the server returns for `space_name` | used in the path unchecked | checked before every request |
+| a memory id in a batch-create response, polled by `upload_documents(wait=True)` | `"../spaces/<U>"` became `GET /v1/spaces/<U>` | `GoodMemUploadError` carrying the created ids; no poll |
+| `reranker_id` or `embedder_id` that is not a UUID | the value, in the request body | refused; nothing sent |
+
+The same holds for `a/../../spaces/<U>`, `%2e%2e/spaces/<U>`,
+`..%2Fspaces%2F<U>`, `<U>/../../spaces/<U>`, `""`, `" <U>"` and `"<U>\n"`.
+Configured ids are checked when the provider is built, so a bad option fails
+when NLWeb loads it; the space id is checked again right before each request.
+
+`get_by_id(object_id)` is the entry point NLWeb feeds from a web request.
+That id is the item's URL, not a GoodMem id, and it already travelled only
+as an escaped literal inside the `filter` query parameter. It is not
+required to be a UUID; tests now pin that every payload above, and
+`<U>&max_results=500`, leaves the path at `/v1/spaces/<configured>/memories`
+with exactly one query parameter.
+
+### Fixed
+
+- **The documented NLWeb configuration now loads.** The README, the package
+  docstring and `GoodMemRetrievalProvider`'s docstring nested the options
+  under `options:`. nlweb-core 0.7 passes every key beside `import_path` and
+  `class_name` to the constructor, so the provider received one
+  `options={...}` keyword and NLWeb's startup failed with `ValueError:
+  GoodMemRetrievalProvider needs space_id or space_name`. The options now sit
+  beside `class_name`.
+- **The documented entry is named `default`.** It was `goodmem`, but
+  nlweb-core's `ask` handler calls `get_retrieval_provider("default")`; with
+  only a `goodmem` entry that raised `Retrieval provider 'default' is not
+  configured`, and alongside another `default` it was loaded and never used.
+- The README shows the `object_storage` entry for
+  `GoodMemObjectLookupProvider` (NLWeb only enriches results when one named
+  `default` exists), mentions `_env` keys such as `api_key_env`, and says that
+  an empty `embedder_id`/`reranker_id` means "not set".
+
+### Changed
+
+- An empty `space_id` raises `space_id must be a UUID`. With `space_name`
+  also set, 0.2.0 used the empty id instead of resolving the name. An empty
+  `embedder_id` or `reranker_id` still means "not set".
+- An uppercase id is sent lowercased, and a `uuid.UUID` is accepted (0.2.0's
+  `search()` and `upload_documents()` raised on one).
+- 159 offline tests (was 34): 119 in `tests/test_ids.py` drive the real SDK
+  over a socket, and 6 in `tests/test_config.py` load the documented YAML
+  with nlweb-core's own loader. Tests that used placeholder ids (`"emb-1"`, `"bogus"`,
+  `"rr"`, `"not-a-uuid"`, `"other-id"`) now use UUIDs; the broken-reranker
+  test uses the all-zero id its fixture was recorded with.
+
+## 0.2.0
+
+A rewrite. 0.1.0 shipped no NLWeb integration: it was fourteen classes
+wrapping REST endpoints with `httpx`, and `nlweb` was never imported and was
+not a dependency. It was the same template as `deepeval-goodmem` 0.1.0 — after
+normalising names, `_client.py` differed by 16 lines out of 683.
+
+0.2.0 implements NLWeb's actual provider interfaces, on the official `goodmem`
+SDK.
+
+### Added
+
+- **`GoodMemRetrievalProvider`** — a real `nlweb_core.retriever.RetrievalProvider`.
+  Registered purely by configuration (`import_path` / `class_name` / `options`),
+  so it never has to be added to NLWeb's source tree.
+- **Site filtering** — NLWeb's core requirement. Sites are memory metadata,
+  filtered server-side with escaped expressions. One site, several sites
+  (OR-ed), or `"all"`.
+- **`GoodMemObjectLookupProvider`** — `ObjectLookupProvider.get_by_id(url)`,
+  so NLWeb can enrich a result with the full Schema.org object.
+- **`upload_documents()`** and the Schema.org mapping in `nlweb_goodmem._schema`.
+- **`get_sites()`** — the distinct sites present in a space.
+- 34 offline tests over captured server bytes and 13 live tests with verified
+  teardown. 0.1.0 had 10 tests that passed against every defect below, and no
+  workflow ever ran them.
+
+### Fixed
+
+Every defect was reproduced against a live server (v1.0.320) first.
+
+| Behaviour | 0.1.0 | 0.2.0 |
+| --- | --- | --- |
+| Retrieval statuses | The NDJSON parser had branches for boundaries, memories, abstract replies and items — and **none for `status`**. A bogus reranker made the server send three status events; all were dropped and the call reported success | Classified per the retrieval status contract: informational notices ignored, real problems logged, unknown codes surfaced as `UNKNOWN` |
+| A retrieval that failed outright | `success: true, totalResults: 0` with a message blaming indexing | Empty list plus a `UserWarning`; never raised into an `ask` request |
+| Searching when nothing matches | Up to **12 re-POSTs** over 60s (`wait_for_indexing=True`, `poll_interval=5`), re-invoking the LLM each time when `llm_id` was set | One request |
+| Relevance scores | Documented as "0-1"; live values are negative for vector and a different scale for reranker | Not exposed: `RetrievedItem` has no score field, and server order is preserved |
+| `metadata_filter` | A raw string pasted into the request | Escaped; a site containing a quote matches nothing rather than everything |
+| Any error | `run()` caught **everything** and returned `{"success": false, "error": "…check developer.mozilla.org"}` as a string, discarding the server's reason | Errors propagate with the server's message |
+| `update_space(public_read=…)` | HTTP 400 — the field was removed from the API | Gone |
+| Batch ingest | n/a | Per-item `success` is checked: the server returns HTTP 200 even when an item failed |
+| API key | A plain attribute on every operation object | Held on a private connection |
+
+### 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 nlweb_goodmem import GoodMemRetrieveMemories
+out = json.loads(GoodMemRetrieveMemories(...).run(query="…", space_ids=sid))
+
+# 0.2.0 — through NLWeb
+provider = GoodMemRetrievalProvider(space_name="nlweb", base_url=…, api_key=…)
+items = await provider.search("…", "example.com")
+
+# 0.2.0 — for plain API access, use the SDK
+from goodmem import AsyncGoodmem
+await AsyncGoodmem(base_url=…, api_key=…).spaces.create(...)
+```
+
+Python 3.9 is no longer supported; 3.10+ is required.
+
+## 0.1.0
+
+Initial release.

goodmem_nlweb-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_nlweb-0.3.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.5
+Name: goodmem-nlweb
+Version: 0.3.0
+Summary: GoodMem as an NLWeb retrieval provider — Schema.org retrieval, site filtering, and object lookup.
+Project-URL: homepage, https://github.com/PAIR-Systems-Inc/goodmem_nlweb
+Project-URL: source, https://github.com/PAIR-Systems-Inc/goodmem_nlweb
+Project-URL: issues, https://github.com/PAIR-Systems-Inc/goodmem_nlweb/issues
+Author-email: GoodMem <support@goodmem.ai>
+License-File: LICENSE
+Keywords: goodmem,nlweb,rag,retrieval,schema.org,vector-search
+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: goodmem>=0.1.34
+Requires-Dist: nlweb-core>=0.7
+Requires-Dist: typing-extensions>=4.7
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mypy==1.18.2; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff==0.16.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# goodmem-nlweb
+
+GoodMem as an [NLWeb](https://github.com/nlweb-ai/NLWeb) retrieval provider.
+
+```bash
+pip install goodmem-nlweb
+```
+
+## Configure
+
+NLWeb imports a provider by path, so this package never has to be added to
+NLWeb's own source tree:
+
+```yaml
+retrieval:
+  default:
+    import_path: goodmem_nlweb
+    class_name: GoodMemRetrievalProvider
+    base_url: https://localhost:8080
+    api_key: gm_…
+    space_name: nlweb
+```
+
+NLWeb's `ask` handler asks for the retrieval provider named `default`, so
+that is the name to give it. Options sit beside `import_path` and
+`class_name`: NLWeb passes every other key of the entry to the constructor as
+a keyword argument. A key ending in `_env` is read from the environment
+instead, so `api_key_env: GOODMEM_API_KEY` keeps the key out of the file.
+
+It implements `nlweb_core.retriever.RetrievalProvider`, so `search()` returns
+real `RetrievedItem` objects and `close()` releases the client.
+
+`space_id`, `embedder_id` and `reranker_id` must be GoodMem ids, which are
+UUIDs; any other value raises `ValueError` when the provider is built, before
+a request is made. (An empty `embedder_id` or `reranker_id` means "not set";
+an empty `space_id` is refused.) The GoodMem SDK places ids in the URL path
+unencoded, so a value like `../spaces/<id>` would otherwise send the request to
+a different endpoint.
+
+## Sites
+
+NLWeb filters every call by *site*; GoodMem has no such concept. A site is
+stored as memory metadata and filtered **server-side** with GoodMem's filter
+grammar, the same way NLWeb's own Qdrant provider uses a `site` payload field.
+Values are escaped, never interpolated — a site called `x' OR '1'='1` matches
+nothing rather than everything.
+
+```python
+await provider.search("noodle soup", "recipes.example.com")   # one site
+await provider.search("noodle soup", ["a.com", "b.com"])      # OR across sites
+await provider.search("noodle soup", "all")                   # every site
+await provider.search_all_sites("noodle soup")                # same thing
+await provider.get_sites()                                    # ['a.com', 'b.com']
+```
+
+## Metadata filters
+
+`search()` also takes `metadata_filter`, a mapping of metadata field to
+value. Each pair becomes a server-side equality, AND-ed with the others and
+with the site filter. GoodMem stores metadata as JSON and compares it under an
+explicit cast, and a comparison under the wrong cast is accepted and matches
+nothing, so each value is cast by its Python type:
+
+| Value | Compared as | Sent to the server |
+| --- | --- | --- |
+| `str` | text | `CAST(val('$.cuisine') AS TEXT) = 'Malaysian'` |
+| `bool` | boolean | `CAST(val('$.vegetarian') AS BOOLEAN) = true` |
+| `int`, `float` | number | `CAST(val('$.servings') AS NUMERIC) = 4` |
+
+`None`, `nan`, `inf` and any other type (a list, a dict, …) raise
+`ValueError` before a request is made. Text is escaped exactly as a site is.
+
+```python
+await provider.search("noodle soup", "recipes.example.com",
+                      metadata_filter={"vegetarian": True, "servings": 4})
+```
+
+A filter read from YAML (or JSON) keeps the type the loader gives it, so write
+each value the way it is stored: `vegetarian: true` is a boolean, while
+`vegetarian: "true"` is the string `"true"` and matches only a stored string.
+
+```yaml
+vegetarian: true
+servings: 4
+cuisine: Malaysian
+```
+
+`metadata_filter` is an argument to `search()`, not a provider option: NLWeb's
+`ask` handler does not pass one, and a `metadata_filter:` key in the
+provider's YAML entry is ignored.
+
+## Ingesting Schema.org documents
+
+`RetrievalProvider` only reads, so ingestion is a helper rather than part of
+the interface:
+
+```python
+from goodmem_nlweb import GoodMemRetrievalProvider, upload_documents
+
+provider = GoodMemRetrievalProvider(space_name="nlweb", base_url=…, api_key=…)
+await upload_documents(provider, [
+    {"@type": "Recipe", "url": "https://ex.com/r/laksa", "name": "Singapore Laksa",
+     "description": "A coconut curry noodle soup."},
+], site="recipes.example.com")
+```
+
+| NLWeb | GoodMem |
+| --- | --- |
+| `url` | `metadata["url"]` — the item's identity, and what NLWeb dedupes on |
+| `site` | `metadata["site"]` — what every search filters on |
+| `raw_schema_object` | `metadata["schema_json"]` |
+| (text to embed) | the memory's content |
+
+The embedded text is **not** the raw JSON. Embedding a JSON blob buries the
+words a query would match under punctuation and key names, so the text is
+extracted from `name`, `headline`, `description`, `articleBody` and friends,
+and the untouched object is kept alongside for NLWeb to return verbatim.
+
+`upload_documents` inspects every item of the batch response: the server
+returns HTTP 200 even when an item failed, so per-item `success` is the only
+signal. A partial failure raises `GoodMemUploadError` carrying the ids that
+did land.
+
+## Looking objects up by URL
+
+```python
+from goodmem_nlweb import GoodMemObjectLookupProvider
+
+lookup = GoodMemObjectLookupProvider(space_name="nlweb", base_url=…, api_key=…)
+await lookup.get_by_id("https://ex.com/r/laksa")   # the full Schema.org object
+```
+
+Implements `ObjectLookupProvider`, so NLWeb can enrich a truncated search
+result with the complete object without a second datastore. NLWeb does that
+when an `object_storage` provider named `default` is configured:
+
+```yaml
+object_storage:
+  default:
+    import_path: goodmem_nlweb
+    class_name: GoodMemObjectLookupProvider
+    base_url: https://localhost:8080
+    api_key: gm_…
+    space_name: nlweb
+```
+
+The id NLWeb passes here comes from a web request. It is the item's URL, not
+a GoodMem id, so it is not required to be a UUID: it only ever travels as an
+escaped value in the `filter` query parameter, never in the URL path.
+
+## Scores, and why there are none
+
+A GoodMem vector score is a negative inner product — the best match is the
+*lowest* number — and a reranker score is a different scale that also goes
+negative. `RetrievedItem` has no score field, and inventing one would imply a
+comparability that does not hold. Results keep the server's ordering, which is
+authoritative, and are never re-sorted here.
+
+## Degraded retrieval
+
+If the server reports a problem, whatever it did return is still returned and
+the statuses are logged. If it reports a problem *and* returns nothing, the
+result is an empty list plus a `UserWarning` — never an exception, because an
+exception here would take down an `ask` request that could still answer from
+another endpoint. Notices that carry no loss (`FEATURE_DISABLED`,
+`LLM_CAPABILITY_INFERRED`) are ignored; a status code this version does not
+know is reported as `UNKNOWN` rather than dropped.
+
+## Which NLWeb?
+
+This targets **`nlweb-core`** (the pip-installable package with the
+config-driven provider architecture). The `nlweb-ai/NLWeb` reference
+implementation has a different interface (`VectorDBClientInterface`, returning
+`list[list[str]]`) and a hardcoded provider table, so a third-party package
+cannot register with it — that one needs an upstream PR.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+ruff check src tests examples && mypy && pytest -m "not integration"
+```
+
+The offline suite replays NDJSON captured from a live GoodMem server
+(v1.0.320) through the real SDK decoders. The live suite needs a server:
+
+```bash
+GOODMEM_BASE_URL=… GOODMEM_API_KEY=… GOODMEM_EMBEDDER_ID=… \
+  GOODMEM_RERANKER_ID=… GOODMEM_VERIFY_SSL=0 \
+  pytest -m integration
+```
+
+`GOODMEM_RERANKER_ID` is optional — the reranker test skips without it.
+`GOODMEM_VERIFY_SSL=0` is for a local server with a self-signed certificate.
+
+There is no default credential anywhere in this repository.
+
+## License
+
+MIT