diff --git a/examples/mx3_public_shim_embeddings_rerank.md b/examples/mx3_public_shim_embeddings_rerank.md new file mode 100644 index 0000000..8d21d78 --- /dev/null +++ b/examples/mx3_public_shim_embeddings_rerank.md @@ -0,0 +1,92 @@ +# MX3 Public Shim Embeddings and Rerank + +MemPalace can optionally route Chroma embeddings and post-retrieval rerank through the public +MX3 shim helpers. + +This path is local by default. It sends the live search query and candidate hits to the configured +shim endpoint, so remote endpoints are blocked unless you explicitly opt in, and any remote +endpoint must use HTTPS. + +Public repo: + +- `https://github.com/grtninja/mx3-public-shim` + +## Hardware required + +This setup requires a MemryX MX3 accelerator in an M.2 slot behind the configured public-shim +endpoint. + +## Install + +```bash +pip install "mx3-public-shim[mempalace] @ git+https://github.com/grtninja/mx3-public-shim.git" +``` + +## Validate before enabling + +Use this path only with a hardware-backed public-shim deployment. + +```bash +python -m mx3_public_shim.doctor +``` + +MemPalace rejects the explicit `cpu_reference` fallback, but you should still validate the +configured endpoint before enabling it: + +- the runtime must expose an embeddings provider +- the selected provider must not be `cpu_reference` +- the endpoint should be the local public shim unless you intentionally opt in to a remote HTTPS + target + +On Windows, a healthy doctor report normally shows: + +- `mx3_linux` unavailable because the direct official Python runtime is Linux-only +- `openai_compat` available and selected for `embeddings` +- `openai_compat` available and selected for `chat` + +That means MemPalace is using the local public-shim OpenAI-compatible surface while the required +hardware lives behind that endpoint. + +## Enable embeddings + rerank in MemPalace + +```bash +export MEMPALACE_EMBEDDING_BACKEND=mx3_public_shim +export MEMPALACE_SEARCH_RERANKER=mx3_public_shim +export MEMPALACE_MX3_PUBLIC_SHIM_BASE_URL=http://127.0.0.1:9000/v1 +export MEMPALACE_MX3_PUBLIC_SHIM_EMBEDDING_MODEL=text-embedding-nomic-embed-text-v1.5 +export MEMPALACE_MX3_PUBLIC_SHIM_PROVIDER_ORDER=mx3_linux,openai_compat +export MEMPALACE_MX3_PUBLIC_SHIM_REQUIRE_HARDWARE=1 +``` + +On Windows, the direct `mx3_linux` provider is not expected to resolve; the normal path is a local +public-shim OpenAI-compatible endpoint that is itself backed by the required hardware. + +If your endpoint requires authentication, also set: + +```bash +export MEMPALACE_MX3_PUBLIC_SHIM_API_KEY=... +``` + +`MEMPALACE_EMBEDDING_BACKEND` and `MEMPALACE_SEARCH_RERANKER` can be enabled independently. Use +both when you want MX3-backed Chroma embeddings plus post-retrieval rerank. + +If you intentionally point `MEMPALACE_MX3_PUBLIC_SHIM_BASE_URL` at a non-localhost endpoint, also +set: + +```bash +export MEMPALACE_MX3_PUBLIC_SHIM_ALLOW_REMOTE=1 +``` + +## Optional example script + +The companion example below demonstrates the narrow Chroma seam directly: + +```bash +python examples/mx3_public_shim_embeddings_rerank.py +``` + +Then search normally: + +```bash +mempalace search "auth decisions" +``` diff --git a/examples/mx3_public_shim_embeddings_rerank.py b/examples/mx3_public_shim_embeddings_rerank.py new file mode 100644 index 0000000..a43ff19 --- /dev/null +++ b/examples/mx3_public_shim_embeddings_rerank.py @@ -0,0 +1,75 @@ +#!/usr/bin/env python3 +"""Example: query a local public-shim embeddings endpoint and pass vectors into Chroma.""" + +from __future__ import annotations + +import json +import os +import tempfile +from pathlib import Path +from urllib import request + +try: + from chromadb import PersistentClient +except ImportError as exc: # pragma: no cover + raise SystemExit("Install chromadb before running this example.") from exc + + +BASE_URL = os.environ.get("MEMPALACE_MX3_PUBLIC_SHIM_BASE_URL", "http://127.0.0.1:9000/v1") +EMBEDDINGS_URL = BASE_URL.rstrip("/") + "/embeddings" +EMBED_MODEL = os.environ.get( + "MEMPALACE_MX3_PUBLIC_SHIM_EMBEDDING_MODEL", + "text-embedding-nomic-embed-text-v1.5", +) + + +def fetch_embeddings(texts: list[str]) -> list[list[float]]: + payload = json.dumps({"model": EMBED_MODEL, "input": texts}).encode("utf-8") + headers = {"Content-Type": "application/json"} + api_key = os.environ.get("MEMPALACE_MX3_PUBLIC_SHIM_API_KEY") + if api_key: + headers["Authorization"] = f"Bearer {api_key}" + req = request.Request( + EMBEDDINGS_URL, + data=payload, + headers=headers, + method="POST", + ) + with request.urlopen(req, timeout=20) as response: + body = json.loads(response.read().decode("utf-8")) + data = body.get("data", []) + if len(data) != len(texts): + raise RuntimeError("Embedding response count did not match input count") + return [row["embedding"] for row in data] + + +def main() -> None: + documents = [ + "A local retrieval queue keeps notes that still need verification.", + "The workstation stores a short MX3 setup checklist for repeatable bring-up.", + "This note is about watering tomatoes in the backyard.", + ] + metadatas = [ + {"wing": "verification"}, + {"wing": "operations"}, + {"wing": "personal"}, + ] + query = "How does the system track notes that still need verification?" + + with tempfile.TemporaryDirectory() as tmpdir: + client = PersistentClient(path=str(Path(tmpdir))) + collection = client.get_or_create_collection("mempalace_drawers") + doc_vectors = fetch_embeddings(documents) + collection.add( + ids=["1", "2", "3"], + documents=documents, + embeddings=doc_vectors, + metadatas=metadatas, + ) + query_vector = fetch_embeddings([query])[0] + result = collection.query(query_embeddings=[query_vector], n_results=3) + print(json.dumps(result, indent=2)) + + +if __name__ == "__main__": + main()