warm-sdk 0.1.3__tar.gz

warm_sdk-0.1.3/.gitignore

@@ -0,0 +1,85 @@
+# Rust
+/target
+/fuzz/Cargo.lock
+/bindings/wasm/Cargo.lock
+/fuzz/target
+/fuzz/corpus
+/fuzz/artifacts
+
+# Node.js
+/node_modules
+package-lock.json
+!interop/w3c/package-lock.json
+!integrations/mcp/tests/package-lock.json
+!integrations/js/package-lock.json
+interop/w3c/node_modules/
+*.node
+!index.js
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Databases (Local dev)
+memory_db/
+*.db
+*.redb
+vectors_data.bin/
+
+# Environment / Private
+.cargo_home/
+.env
+.env.*
+!.env.example
+!.env.sample
+
+# Python
+__pycache__/
+.venv/
+
+# uv script lockfiles written beside the benchmark scripts
+benchmarks/public/*.py.lock
+
+# A build driver that joins an absolute path under the cwd recreates this tree at the repo root
+/Volumes/
+
+# Evidence kept off git: benchmarks/evidence/MANIFEST.json lists the release archives and
+# scripts/fetch_evidence.py restores them to these paths.
+/benchmarks/results/superiority_v2/
+/benchmarks/results/superiority_v3/
+/benchmarks/results/native_harness_v1/
+/benchmarks/results/native_harness_gce_v1/
+/benchmarks/results/ann_extended_diagnostic_v1/
+/benchmarks/results/ann_minimal_diagnostic_v1/
+/benchmarks/results/algebraic_codebook_synthetic.json
+/benchmarks/results/longmemeval_dev_answers_v2.json
+/benchmarks/results/longmemeval_dev_answers_v2b.json
+
+# Golden stores are committed test data.
+!tests/golden/**/vectors_data.bin/
+
+# Documentation build
+/.docs-gen/
+/scripts/docs-api/node_modules/
+/scripts/docs-qa/node_modules/
+/_site/
+!/scripts/docs-qa/package-lock.json
+!/scripts/docs-api/package-lock.json
+# Local embedder model packs are build products (see bindings/embed-models)
+*.hmsemb
+bindings/embed-models/**/packs/
+.warm-local/
+benchmarks/results/research/ann/*.graph
+
+# Historical benchmark inputs are restored locally from benchmarks/evidence/retired-inputs.json.
+/benchmarks/results/metal_sdpa_draft_2026-10-09/isolated/
+/benchmarks/results/metal_sdpa_draft_2026-10-09/dependencies/
+/benchmarks/results/query_aware_graph_v1/sources/
+/benchmarks/results/query_aware_graph_v4/runs/llama/snapshots/
+/benchmarks/results/query_aware_graph_v4/runs/yi/snapshots/
+/benchmarks/results/longmemeval_dev_answers_v1.json
+/benchmarks/results/longmemeval_dev_answers_v3.json
+/benchmarks/results/longmemeval_dev_answers_local30b_v1.json
+
+/_legacy-docs/
+/.hms-local/

warm_sdk-0.1.3/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.5
+Name: warm-sdk
+Version: 0.1.3
+Summary: HTTP client and agent-framework adapters for a WritersLogic Adaptive Retention & Memory service
+Project-URL: Homepage, https://writerslogic.com/warm/
+Project-URL: Documentation, https://writerslogic.com/warm/docs/
+Project-URL: Repository, https://github.com/writerslogic/warm
+Author-email: WritersLogic <david@writerslogic.com>
+License: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: sniffio>=1.3
+Provides-Extra: all
+Requires-Dist: crewai>=0.28.0; extra == 'all'
+Requires-Dist: dspy-ai>=2.4.0; extra == 'all'
+Requires-Dist: embedchain>=0.1.114; extra == 'all'
+Requires-Dist: haystack-ai>=2.0.0; extra == 'all'
+Requires-Dist: langchain-core>=0.1.0; extra == 'all'
+Requires-Dist: llama-index-core>=0.10.0; extra == 'all'
+Requires-Dist: phidata>=2.4.0; extra == 'all'
+Requires-Dist: pydantic-ai>=0.0.14; extra == 'all'
+Requires-Dist: semantic-kernel>=1.39.4; extra == 'all'
+Requires-Dist: smolagents>=1.0.0; extra == 'all'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.28.0; extra == 'crewai'
+Provides-Extra: dspy
+Requires-Dist: dspy-ai>=2.4.0; extra == 'dspy'
+Provides-Extra: embedchain
+Requires-Dist: embedchain>=0.1.114; extra == 'embedchain'
+Provides-Extra: fast
+Requires-Dist: orjson>=3.9; extra == 'fast'
+Provides-Extra: haystack
+Requires-Dist: haystack-ai>=2.0.0; extra == 'haystack'
+Provides-Extra: import-annoy
+Requires-Dist: annoy>=1.17; extra == 'import-annoy'
+Requires-Dist: numpy>=1.26; extra == 'import-annoy'
+Provides-Extra: import-chroma
+Requires-Dist: chromadb>=0.5; extra == 'import-chroma'
+Provides-Extra: import-faiss
+Requires-Dist: faiss-cpu>=1.8; extra == 'import-faiss'
+Requires-Dist: numpy>=1.26; extra == 'import-faiss'
+Provides-Extra: import-files
+Requires-Dist: duckdb>=1.0; extra == 'import-files'
+Requires-Dist: numpy>=1.26; extra == 'import-files'
+Requires-Dist: pyarrow>=15; extra == 'import-files'
+Provides-Extra: import-hnswlib
+Requires-Dist: hnswlib>=0.8; extra == 'import-hnswlib'
+Requires-Dist: numpy>=1.26; extra == 'import-hnswlib'
+Provides-Extra: import-lancedb
+Requires-Dist: lancedb>=0.9; extra == 'import-lancedb'
+Requires-Dist: pyarrow>=15; extra == 'import-lancedb'
+Provides-Extra: import-langchain
+Requires-Dist: faiss-cpu>=1.8; extra == 'import-langchain'
+Requires-Dist: langchain-core>=0.2; extra == 'import-langchain'
+Provides-Extra: import-letta
+Requires-Dist: letta-client>=0.1; extra == 'import-letta'
+Provides-Extra: import-llamaindex
+Requires-Dist: llama-index-core>=0.10; extra == 'import-llamaindex'
+Provides-Extra: import-mem0
+Requires-Dist: mem0ai<0.2,>=0.1; extra == 'import-mem0'
+Provides-Extra: import-milvus
+Requires-Dist: pymilvus>=2.4; extra == 'import-milvus'
+Provides-Extra: import-mongodb
+Requires-Dist: pymongo>=4.6; extra == 'import-mongodb'
+Provides-Extra: import-openai
+Requires-Dist: openai>=1.40; extra == 'import-openai'
+Provides-Extra: import-pgvector
+Requires-Dist: psycopg[binary]>=3.1; extra == 'import-pgvector'
+Provides-Extra: import-pinecone
+Requires-Dist: pinecone>=5; extra == 'import-pinecone'
+Provides-Extra: import-qdrant
+Requires-Dist: qdrant-client>=1.9; extra == 'import-qdrant'
+Provides-Extra: import-redis
+Requires-Dist: redis>=5; extra == 'import-redis'
+Provides-Extra: import-sqlite-vec
+Requires-Dist: sqlite-vec>=0.1.1; extra == 'import-sqlite-vec'
+Provides-Extra: import-zep
+Requires-Dist: zep-cloud>=2; extra == 'import-zep'
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.1.0; extra == 'langchain'
+Provides-Extra: llamaindex
+Requires-Dist: llama-index-core>=0.10.0; extra == 'llamaindex'
+Provides-Extra: phidata
+Requires-Dist: phidata>=2.4.0; extra == 'phidata'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai>=0.0.14; extra == 'pydantic-ai'
+Provides-Extra: semantic-kernel
+Requires-Dist: semantic-kernel>=1.39.4; extra == 'semantic-kernel'
+Provides-Extra: smolagents
+Requires-Dist: smolagents>=1.0.0; extra == 'smolagents'
+Description-Content-Type: text/markdown
+
+<a href="https://writerslogic.com/warm/"><img src="https://raw.githubusercontent.com/writerslogic/warm/main/assets/crystal-halo/crystal-detailed-static.png" width="96" alt="WARM logo" align="left"></a>
+
+# WARM SDK
+
+Python HTTP client and framework adapters for a WARM service.
+
+[Website](https://writerslogic.com/warm/) · [Documentation](https://writerslogic.com/warm/docs/) · [Source](https://github.com/writerslogic/warm) · [License](https://github.com/writerslogic/warm/blob/main/LICENSE)
+
+<br clear="left">
+
+The client talks to `warm-server`, which ships in the WARM repository. The server
+stores vectors you supply and exposes document and query endpoints. See the
+[server guide](https://writerslogic.com/warm/docs/latest/SERVER/) to run it.
+
+## Installation
+
+```bash
+uv add warm-sdk
+```
+
+Framework adapters are optional extras. Install one, or all of them:
+
+```bash
+uv add "warm-sdk[langchain]"
+uv add "warm-sdk[all]"
+```
+
+The earlier standalone `langchain-holographic` distribution is retired. For LangChain, install
+`warm-sdk[langchain]` and import `WarmVectorStore` from
+`writerslogic_warm_sdk.langchain`. This adapter connects to `warm-server`; update the old
+`langchain_holographic` import and its local-store configuration when migrating.
+
+The `fast` extra adds `orjson` for request encoding, which cuts the per-query cost of sending an embedding:
+
+```bash
+uv add "warm-sdk[fast]"
+```
+
+Requires Python 3.10 or newer.
+
+## Quick Start
+
+```python
+from writerslogic_warm_sdk import WarmClient
+
+client = WarmClient(url="http://localhost:8080", api_key="...")
+
+client.add_documents([
+    {"id": "doc-1", "text": "Paris is the capital of France.", "vector": [0.12, -0.03, 0.88], "metadata": {"lang": "en"}},
+])
+
+response = client.query(query_vector=[0.10, -0.01, 0.90], top_k=3, filter={"lang": "en"})
+print(response["matches"])
+client.delete_document("doc-1")
+client.close()
+```
+
+`AsyncWarmClient` has the same methods as coroutines; close it with `await client.aclose()`. Embeddings come from your own model: the SDK sends vectors, it does not compute them.
+
+After bulk ingestion, `client.maintain_document_index()` explicitly builds the server's
+exact dense document index and returns `{"documentIndexTrained": true}` when the
+store is eligible. Smaller or unsupported stores return `false` and use exact scanning.
+Use `await client.maintain_document_index()` with the async client. Rebuild after updates
+or restart; the index is a runtime cache. Searches preserve the existing cosine results,
+and metadata filters continue to apply before ranking. This method requires an
+`warm-server` version exposing `POST /api/v1/index/maintain`.
+
+## Source Evidence
+
+`complete_evidence` packs complete source observations in your retrieval order. Each observation contains a turn handle, session handle, observation time, role, and verbatim text. Supply opaque caller IDs as lowercase SHA-256 hex handles, and keep their association with your original records.
+
+```python
+from hashlib import sha256
+from writerslogic_warm_sdk import complete_evidence, decode_source_packet
+
+def handle(identity):
+    return sha256(identity.encode("utf-8")).hexdigest()
+
+session = handle("session-7")
+candidates = [
+    [(handle("turn-1"), session, "2026-10-13T10:00:00Z", "user",
+      "I have two aquarium tanks.")],
+    [(handle("turn-2"), session, "2026-10-13T10:00:00Z", "assistant",
+      "You mentioned two aquarium tanks.")],
+]
+
+selection = complete_evidence(candidates, selected=[0], budget_bytes=2048)
+observations = decode_source_packet(selection.packet)
+assert observations == [candidates[index] for index in selection.selected]
+```
+
+The indices in `selected` are mandatory; packing raises `ValueError` if they exceed the budget. Additional complete groups fit in candidate order, with shared text and session metadata stored once. Decoding preserves every occurrence, role, observation time, and source text. The budget counts UTF-8 packet bytes; measure reader tokens separately. Packets contain source observations and no inferred answer or event date. These helpers run locally and make no service calls.
+
+## Integrations
+
+| Framework | Extra | Import |
+|-----------|-------|--------|
+| LangChain | `langchain` | `from writerslogic_warm_sdk.langchain import WarmVectorStore` |
+| LlamaIndex | `llamaindex` | `from writerslogic_warm_sdk.llamaindex import WarmVectorStore` |
+| Haystack | `haystack` | `from writerslogic_warm_sdk.haystack import WarmDocumentStore` |
+| Semantic Kernel | `semantic-kernel` | `from writerslogic_warm_sdk.semantic_kernel import WarmMemoryStore` |
+| DSPy | `dspy` | `from writerslogic_warm_sdk.dspy import WarmRM` |
+| CrewAI | `crewai` | `from writerslogic_warm_sdk.crewai import WarmSearchTool` |
+| Embedchain | `embedchain` | `from writerslogic_warm_sdk.embedchain import WarmDB` |
+| Phidata | `phidata` | `from writerslogic_warm_sdk.phidata import WarmVectorDb` |
+| Pydantic AI | `pydantic-ai` | `from writerslogic_warm_sdk.pydantic_ai import get_warm_tool` |
+| SmolAgents | `smolagents` | `from writerslogic_warm_sdk.smolagents import WarmSearchTool` |
+
+## Vector Masking
+
+Passing `zero_trust_key` masks every embedding client-side with a keyed signed permutation (`VectorMask`, scrypt-derived). The server can still rank vectors because inner products and cosine similarity are preserved exactly. This is obfuscation, **not encryption**: the server learns all pairwise similarities, and known plain/masked pairs reveal the key for the coordinates they cover. Pass a per-collection `mask_salt` (at least 16 bytes) shared by all clients of that collection. Masks produced by 0.1.0/0.1.1 are not compatible and were not secure.
+
+## License
+
+Apache-2.0. See the [LICENSE](https://github.com/writerslogic/warm/blob/main/LICENSE).

warm_sdk-0.1.3/README.md

@@ -0,0 +1,115 @@
+<a href="https://writerslogic.com/warm/"><img src="https://raw.githubusercontent.com/writerslogic/warm/main/assets/crystal-halo/crystal-detailed-static.png" width="96" alt="WARM logo" align="left"></a>
+
+# WARM SDK
+
+Python HTTP client and framework adapters for a WARM service.
+
+[Website](https://writerslogic.com/warm/) · [Documentation](https://writerslogic.com/warm/docs/) · [Source](https://github.com/writerslogic/warm) · [License](https://github.com/writerslogic/warm/blob/main/LICENSE)
+
+<br clear="left">
+
+The client talks to `warm-server`, which ships in the WARM repository. The server
+stores vectors you supply and exposes document and query endpoints. See the
+[server guide](https://writerslogic.com/warm/docs/latest/SERVER/) to run it.
+
+## Installation
+
+```bash
+uv add warm-sdk
+```
+
+Framework adapters are optional extras. Install one, or all of them:
+
+```bash
+uv add "warm-sdk[langchain]"
+uv add "warm-sdk[all]"
+```
+
+The earlier standalone `langchain-holographic` distribution is retired. For LangChain, install
+`warm-sdk[langchain]` and import `WarmVectorStore` from
+`writerslogic_warm_sdk.langchain`. This adapter connects to `warm-server`; update the old
+`langchain_holographic` import and its local-store configuration when migrating.
+
+The `fast` extra adds `orjson` for request encoding, which cuts the per-query cost of sending an embedding:
+
+```bash
+uv add "warm-sdk[fast]"
+```
+
+Requires Python 3.10 or newer.
+
+## Quick Start
+
+```python
+from writerslogic_warm_sdk import WarmClient
+
+client = WarmClient(url="http://localhost:8080", api_key="...")
+
+client.add_documents([
+    {"id": "doc-1", "text": "Paris is the capital of France.", "vector": [0.12, -0.03, 0.88], "metadata": {"lang": "en"}},
+])
+
+response = client.query(query_vector=[0.10, -0.01, 0.90], top_k=3, filter={"lang": "en"})
+print(response["matches"])
+client.delete_document("doc-1")
+client.close()
+```
+
+`AsyncWarmClient` has the same methods as coroutines; close it with `await client.aclose()`. Embeddings come from your own model: the SDK sends vectors, it does not compute them.
+
+After bulk ingestion, `client.maintain_document_index()` explicitly builds the server's
+exact dense document index and returns `{"documentIndexTrained": true}` when the
+store is eligible. Smaller or unsupported stores return `false` and use exact scanning.
+Use `await client.maintain_document_index()` with the async client. Rebuild after updates
+or restart; the index is a runtime cache. Searches preserve the existing cosine results,
+and metadata filters continue to apply before ranking. This method requires an
+`warm-server` version exposing `POST /api/v1/index/maintain`.
+
+## Source Evidence
+
+`complete_evidence` packs complete source observations in your retrieval order. Each observation contains a turn handle, session handle, observation time, role, and verbatim text. Supply opaque caller IDs as lowercase SHA-256 hex handles, and keep their association with your original records.
+
+```python
+from hashlib import sha256
+from writerslogic_warm_sdk import complete_evidence, decode_source_packet
+
+def handle(identity):
+    return sha256(identity.encode("utf-8")).hexdigest()
+
+session = handle("session-7")
+candidates = [
+    [(handle("turn-1"), session, "2026-10-13T10:00:00Z", "user",
+      "I have two aquarium tanks.")],
+    [(handle("turn-2"), session, "2026-10-13T10:00:00Z", "assistant",
+      "You mentioned two aquarium tanks.")],
+]
+
+selection = complete_evidence(candidates, selected=[0], budget_bytes=2048)
+observations = decode_source_packet(selection.packet)
+assert observations == [candidates[index] for index in selection.selected]
+```
+
+The indices in `selected` are mandatory; packing raises `ValueError` if they exceed the budget. Additional complete groups fit in candidate order, with shared text and session metadata stored once. Decoding preserves every occurrence, role, observation time, and source text. The budget counts UTF-8 packet bytes; measure reader tokens separately. Packets contain source observations and no inferred answer or event date. These helpers run locally and make no service calls.
+
+## Integrations
+
+| Framework | Extra | Import |
+|-----------|-------|--------|
+| LangChain | `langchain` | `from writerslogic_warm_sdk.langchain import WarmVectorStore` |
+| LlamaIndex | `llamaindex` | `from writerslogic_warm_sdk.llamaindex import WarmVectorStore` |
+| Haystack | `haystack` | `from writerslogic_warm_sdk.haystack import WarmDocumentStore` |
+| Semantic Kernel | `semantic-kernel` | `from writerslogic_warm_sdk.semantic_kernel import WarmMemoryStore` |
+| DSPy | `dspy` | `from writerslogic_warm_sdk.dspy import WarmRM` |
+| CrewAI | `crewai` | `from writerslogic_warm_sdk.crewai import WarmSearchTool` |
+| Embedchain | `embedchain` | `from writerslogic_warm_sdk.embedchain import WarmDB` |
+| Phidata | `phidata` | `from writerslogic_warm_sdk.phidata import WarmVectorDb` |
+| Pydantic AI | `pydantic-ai` | `from writerslogic_warm_sdk.pydantic_ai import get_warm_tool` |
+| SmolAgents | `smolagents` | `from writerslogic_warm_sdk.smolagents import WarmSearchTool` |
+
+## Vector Masking
+
+Passing `zero_trust_key` masks every embedding client-side with a keyed signed permutation (`VectorMask`, scrypt-derived). The server can still rank vectors because inner products and cosine similarity are preserved exactly. This is obfuscation, **not encryption**: the server learns all pairwise similarities, and known plain/masked pairs reveal the key for the coordinates they cover. Pass a per-collection `mask_salt` (at least 16 bytes) shared by all clients of that collection. Masks produced by 0.1.0/0.1.1 are not compatible and were not secure.
+
+## License
+
+Apache-2.0. See the [LICENSE](https://github.com/writerslogic/warm/blob/main/LICENSE).

warm_sdk-0.1.3/benchmarks/client_overhead.py

@@ -0,0 +1,233 @@
+"""Per-call client overhead of the SDK against a local warm-server, paired with raw http.client.
+
+Starts the server binary given by ``--server``, loads ``--rows`` documents, then runs
+``--rounds`` interleaved rounds. Each round times every variant on query, add, replace and
+delete, rotating the variant order between rounds. Variants:
+
+- ``raw``: one persistent ``http.client.HTTPConnection`` with a pre-encoded JSON body.
+- ``sdk``: ``WarmClient`` from the installed package (sync).
+- ``sdk-async``: ``AsyncWarmClient`` awaited sequentially in one event loop.
+
+The SDK is whichever ``writerslogic_warm_sdk`` is importable, so a before/after pair runs this script
+once per SDK build (each in its own environment), interleaving the processes.
+
+Writes a JSON summary with p50/p99 per variant and operation to ``--out``.
+"""
+
+import argparse
+import asyncio
+import http.client
+import importlib.metadata
+import json
+import os
+import platform
+import random
+import statistics
+import subprocess
+import sys
+import tempfile
+import time
+
+API_KEY = "bench-key"
+
+
+def vec(rng, dim):
+    return [rng.uniform(-1.0, 1.0) for _ in range(dim)]
+
+
+def pct(samples, q):
+    s = sorted(samples)
+    return s[min(len(s) - 1, int(q * len(s)))]
+
+
+class Raw:
+    def __init__(self, url):
+        host, port = url.removeprefix("http://").split(":")
+        self.conn = http.client.HTTPConnection(host, int(port))
+        self.headers = {"Content-Type": "application/json", "Authorization": f"Bearer {API_KEY}"}
+
+    def call(self, method, path, body=None):
+        self.conn.request(method, path, body=body, headers=self.headers)
+        res = self.conn.getresponse()
+        data = res.read()
+        if res.status >= 300:
+            raise RuntimeError(f"{res.status} {data[:200]!r}")
+        return data
+
+
+def installed(name):
+    try:
+        return importlib.metadata.version(name)
+    except importlib.metadata.PackageNotFoundError:
+        return None
+
+
+def make_ops(rng, dim, n, tag):
+    """Per-variant inputs: queries, fresh docs to add, the same ids to replace, then delete."""
+    queries = [vec(rng, dim) for _ in range(n["query"])]
+    ids = [f"{tag}-{i}" for i in range(n["write"])]
+    adds = [{"id": i, "text": i, "vector": vec(rng, dim)} for i in ids]
+    reps = [{"id": i, "text": i, "vector": vec(rng, dim)} for i in ids]
+    return queries, adds, reps, ids
+
+
+def time_sync(variant, client, ops, top_k):
+    queries, adds, reps, ids = ops
+    out = {k: [] for k in ("query", "add", "replace", "delete")}
+    clock = time.perf_counter_ns
+    if variant == "raw":
+        for q in queries:
+            t = clock()
+            json.loads(client.call("POST", "/api/v1/query", json.dumps({"query_vector": q, "top_k": top_k})))
+            out["query"].append(clock() - t)
+        for key, docs in (("add", adds), ("replace", reps)):
+            for d in docs:
+                t = clock()
+                client.call("POST", "/api/v1/documents/batch", json.dumps([d]))
+                out[key].append(clock() - t)
+        for i in ids:
+            t = clock()
+            client.call("DELETE", f"/api/v1/documents/{i}")
+            out["delete"].append(clock() - t)
+        return out
+    for q in queries:
+        t = clock()
+        client.query(q, top_k=top_k)
+        out["query"].append(clock() - t)
+    for key, docs in (("add", adds), ("replace", reps)):
+        for d in docs:
+            t = clock()
+            client.add_documents([d])
+            out[key].append(clock() - t)
+    for i in ids:
+        t = clock()
+        client.delete_document(i)
+        out["delete"].append(clock() - t)
+    return out
+
+
+async def time_async(client, ops, top_k):
+    queries, adds, reps, ids = ops
+    out = {k: [] for k in ("query", "add", "replace", "delete")}
+    clock = time.perf_counter_ns
+    for q in queries:
+        t = clock()
+        await client.query(q, top_k=top_k)
+        out["query"].append(clock() - t)
+    for key, docs in (("add", adds), ("replace", reps)):
+        for d in docs:
+            t = clock()
+            await client.add_documents([d])
+            out[key].append(clock() - t)
+    for i in ids:
+        t = clock()
+        await client.delete_document(i)
+        out["delete"].append(clock() - t)
+    return out
+
+
+def start_server(binary, dim, data_dir):
+    env = {**os.environ, "WARM_API_KEY": API_KEY}
+    proc = subprocess.Popen(
+        [binary, "--bind", "127.0.0.1:0", "--input-dim", str(dim), "--data-dir", data_dir],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.DEVNULL,
+        text=True,
+        env=env,
+    )
+    line = proc.stdout.readline().strip()
+    if not line.startswith("warm-server listening on "):
+        proc.terminate()
+        raise RuntimeError(line)
+    return proc, f"http://{line.rsplit(' ', 1)[1]}"
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--server", required=True)
+    ap.add_argument("--label", required=True)
+    ap.add_argument("--rows", type=int, default=10_000)
+    ap.add_argument("--dim", type=int, default=384)
+    ap.add_argument("--top-k", type=int, default=10)
+    ap.add_argument("--queries", type=int, default=2000)
+    ap.add_argument("--writes", type=int, default=500)
+    ap.add_argument("--rounds", type=int, default=3)
+    ap.add_argument("--out", required=True)
+    args = ap.parse_args()
+
+    from writerslogic_warm_sdk import AsyncWarmClient, WarmClient
+
+    impls = {"sdk": (WarmClient, AsyncWarmClient)}
+
+    rng = random.Random(7)
+    n = {"query": args.queries, "write": args.writes}
+    with tempfile.TemporaryDirectory() as data_dir:
+        proc, url = start_server(args.server, args.dim, data_dir)
+        try:
+            raw = Raw(url)
+            for start in range(0, args.rows, 1000):
+                docs = [{"id": f"row-{i}", "text": f"row {i}", "vector": vec(rng, args.dim)} for i in range(start, min(args.rows, start + 1000))]
+                raw.call("POST", "/api/v1/documents/batch", json.dumps(docs))
+            raw.call("POST", "/api/v1/index/maintain", "{}")
+
+            variants = ["raw"] + [v for name in impls for v in (name, f"{name}-async")]
+            samples = {v: {k: [] for k in ("query", "add", "replace", "delete")} for v in variants}
+            clients = {"raw": raw}
+            for name, (sync_cls, _) in impls.items():
+                clients[name] = sync_cls(url, api_key=API_KEY)
+            loop = asyncio.new_event_loop()
+            for name, (_, async_cls) in impls.items():
+                clients[f"{name}-async"] = async_cls(url, api_key=API_KEY)
+
+            # Warm every connection before the first timed call.
+            warm = make_ops(rng, args.dim, {"query": 50, "write": 20}, "warm")
+            for v in variants:
+                if v.endswith("-async"):
+                    loop.run_until_complete(time_async(clients[v], warm, args.top_k))
+                else:
+                    time_sync(v, clients[v], warm, args.top_k)
+                warm = make_ops(rng, args.dim, {"query": 50, "write": 20}, f"warm-{v}")
+
+            # Variants alternate in small blocks with a rotating order, so background load on a
+            # shared machine lands on raw and SDK calls alike and the per-call difference stays paired.
+            blocks = 20
+            block = {"query": max(1, n["query"] // blocks), "write": max(1, n["write"] // blocks)}
+            for r in range(args.rounds):
+                for b in range(blocks):
+                    s = (r + b) % len(variants)
+                    for v in variants[s:] + variants[:s]:
+                        ops = make_ops(rng, args.dim, block, f"r{r}-b{b}-{v}")
+                        if v.endswith("-async"):
+                            got = loop.run_until_complete(time_async(clients[v], ops, args.top_k))
+                        else:
+                            got = time_sync(v, clients[v], ops, args.top_k)
+                        for k, xs in got.items():
+                            samples[v][k].extend(xs)
+        finally:
+            proc.terminate()
+            proc.wait(timeout=30)
+
+    summary = {}
+    for v, ops in samples.items():
+        summary[v] = {}
+        for k, xs in ops.items():
+            p50 = pct(xs, 0.5) / 1e3
+            p99 = pct(xs, 0.99) / 1e3
+            raw50 = pct(samples["raw"][k], 0.5) / 1e3
+            summary[v][k] = {"n": len(xs), "p50_us": round(p50, 1), "p99_us": round(p99, 1), "mean_us": round(statistics.fmean(xs) / 1e3, 1), "p50_over_raw_us": round(p50 - raw50, 1)}
+    result = {
+        "label": args.label,
+        "config": {k: v for k, v in vars(args).items() if k not in ("server", "out", "label")},
+        "python": sys.version.split()[0],
+        "packages": {p: installed(p) for p in ("httpx", "httpcore", "sniffio", "orjson")},
+        "machine": platform.machine(),
+        "load_average": os.getloadavg(),
+        "results": summary,
+    }
+    with open(args.out, "w") as f:
+        json.dump(result, f, indent=2)
+
+
+
+if __name__ == "__main__":
+    main()