seraph-mcp 0.1.0__tar.gz

seraph_mcp-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+.seraph/
+.seraph_cache/
+*.egg-info/
+dist/
+build/

seraph_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

seraph_mcp-0.1.0/AGENT_SETUP.md

@@ -0,0 +1,45 @@
+# Set up Seraph in this coding agent
+
+Use these instructions when a user asks to install or use Seraph. Seraph is a local MCP server for searching local Git repositories. MCP works across many coding agents, but each agent has its own server registration mechanism.
+
+## Install
+
+Requirements: Git, Python 3.12, and `uv` (the recommended Python tool installer).
+
+If this project is published on PyPI:
+
+```sh
+python -m pip install 'seraph-mcp[mcp]'
+```
+
+If the user provides a Seraph source checkout instead:
+
+```sh
+cd /path/to/seraph
+uv tool install --from '.[mcp]' seraph-mcp
+```
+
+Do not install Seraph into the target project or modify that project's dependencies. The user may choose another install method; preserve their existing environment and report any missing prerequisite clearly.
+
+## Register with the current agent
+
+1. Identify the current agent host and use its documented MCP setup mechanism (built-in setup command, supported CLI, settings UI, or documented config file).
+2. Register a **local stdio** MCP server named `seraph` with command `seraph-mcp` and no fixed repository environment variable.
+3. If `seraph-mcp` is not on the host's PATH, use the absolute executable path returned by `uv tool dir --bin` plus `/seraph-mcp` (macOS/Linux) or the equivalent path for the OS. Alternatively, register `uvx --from 'seraph-mcp[mcp]' seraph-mcp` when the host supports `uvx` and package downloads.
+4. Follow the host's instructions for reloading MCP servers, then confirm the Seraph tools are available. Never claim setup succeeded until the host confirms the server connected.
+
+Do not assume a Codex, Claude, Cursor, VS Code, or other host config format. If the current host has no MCP support, explain that and give the user the relevant alternative instead of writing a guessed config.
+
+## Use it correctly
+
+- Pass `repo` as the absolute path to the local Git checkout **on every tool call**.
+- Use the active workspace path for questions about the current project.
+- If the user asks about a different local project, use that project's path for that call; do not silently keep searching the active workspace.
+- If the intended repository path is unclear, ask which local checkout they mean.
+- Seraph does not upload repository contents. Its SQLite index is created under `<repo>/.seraph/` and is ignored by Git.
+- Search tools index the requested Git version on first use. `index_repository` is available when the user wants indexing to happen explicitly first.
+- The default setup is local BM25 and requires no API key.
+
+## Check setup
+
+Call `index_repository` with the active workspace path, then call `search_code` with a question grounded in that repository and the same `repo` path. Report whether both calls succeeded and where the index was stored.

seraph_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prethiv Sriman D, Akshith Rajesh, Akhilan VTM, Sanjeev TS — Team floppydisk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

seraph_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.5
+Name: seraph-mcp
+Version: 0.1.0
+Summary: Query-adaptive, evolution-aware code retrieval
+License: MIT License
+        
+        Copyright (c) 2026 Prethiv Sriman D, Akshith Rajesh, Akhilan VTM, Sanjeev TS — Team floppydisk
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Requires-Python: <3.13,>=3.12
+Requires-Dist: bm25s>=0.2.6
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pystemmer>=2.2
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: scikit-learn>=1.5
+Requires-Dist: tree-sitter-go>=0.23
+Requires-Dist: tree-sitter-javascript>=0.23
+Requires-Dist: tree-sitter-python>=0.23
+Requires-Dist: tree-sitter-typescript>=0.23
+Requires-Dist: tree-sitter>=0.23
+Provides-Extra: api
+Requires-Dist: google-genai>=1.20; extra == 'api'
+Requires-Dist: openai>=1.40; extra == 'api'
+Provides-Extra: cpu
+Requires-Dist: einops>=0.8; extra == 'cpu'
+Requires-Dist: faiss-cpu>=1.8; extra == 'cpu'
+Requires-Dist: sentence-transformers>=6.1; extra == 'cpu'
+Requires-Dist: torch>=2.4; extra == 'cpu'
+Requires-Dist: transformers>=5.19; extra == 'cpu'
+Provides-Extra: gpu
+Requires-Dist: einops>=0.8; extra == 'gpu'
+Requires-Dist: faiss-cpu>=1.8; extra == 'gpu'
+Requires-Dist: sentence-transformers>=6.1; extra == 'gpu'
+Requires-Dist: torch>=2.4; extra == 'gpu'
+Requires-Dist: transformers>=5.19; extra == 'gpu'
+Provides-Extra: llm
+Requires-Dist: openai>=1.40; extra == 'llm'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Seraph
+
+Local code search and Git-aware code intelligence for coding agents. Seraph indexes a local Git checkout into a SQLite database and exposes search, symbol, dependency, history, and version comparison tools over MCP.
+
+## Install from a checkout
+
+Requires Python 3.12 and Git. With `uv`:
+
+```sh
+uv tool install --from '.[mcp]' seraph
+```
+
+For development directly from this directory:
+
+```sh
+uv sync --extra mcp
+uv run seraph-mcp
+```
+
+The published package install, once released to PyPI, is:
+
+```sh
+python -m pip install 'seraph-mcp[mcp]'
+```
+
+## Agent setup
+
+Give your coding agent [`AGENT_SETUP.md`](AGENT_SETUP.md). It explains how to install Seraph and register its local MCP server for that agent. MCP configuration differs by host, so the agent should use the host's own supported MCP setup mechanism rather than assume one universal config file.
+
+Seraph runs on the user's machine. Each tool accepts `repo`, the absolute path to the local Git checkout to search. The agent should pass the active workspace path on every call; if asked about another checkout, pass that checkout's path. The index is stored at `<repo>/.seraph/index.sqlite` and ignored by Git.
+
+## MCP tools
+
+- `search_code`: retrieve relevant code from the selected checkout.
+- `search_at_version`: retrieve code from a commit, branch, or tag.
+- `search_history`: search indexed Git versions.
+- `find_symbol`: locate a function, class, or method.
+- `find_dependencies`: walk call, import, and inheritance relationships.
+- `compare_versions`: compare symbols, dependencies, and commits.
+- `index_repository`: explicitly index a Git version; searches index automatically when needed.
+
+The default retrieval setup is local and needs no API key. Benchmark/evaluation code and submission assets are intentionally excluded from this slim distribution.
+
+## CLI
+
+```sh
+seraph --repo /path/to/repo index
+seraph --repo /path/to/repo search "where is request authentication checked?"
+seraph --repo /path/to/repo symbol authenticate_request
+seraph --repo /path/to/repo deps authenticate_request
+seraph --repo /path/to/repo compare <old-commit> <new-commit>
+```
+
+## License
+
+See [`LICENSE`](LICENSE).

seraph_mcp-0.1.0/README.md

@@ -0,0 +1,56 @@
+# Seraph
+
+Local code search and Git-aware code intelligence for coding agents. Seraph indexes a local Git checkout into a SQLite database and exposes search, symbol, dependency, history, and version comparison tools over MCP.
+
+## Install from a checkout
+
+Requires Python 3.12 and Git. With `uv`:
+
+```sh
+uv tool install --from '.[mcp]' seraph
+```
+
+For development directly from this directory:
+
+```sh
+uv sync --extra mcp
+uv run seraph-mcp
+```
+
+The published package install, once released to PyPI, is:
+
+```sh
+python -m pip install 'seraph-mcp[mcp]'
+```
+
+## Agent setup
+
+Give your coding agent [`AGENT_SETUP.md`](AGENT_SETUP.md). It explains how to install Seraph and register its local MCP server for that agent. MCP configuration differs by host, so the agent should use the host's own supported MCP setup mechanism rather than assume one universal config file.
+
+Seraph runs on the user's machine. Each tool accepts `repo`, the absolute path to the local Git checkout to search. The agent should pass the active workspace path on every call; if asked about another checkout, pass that checkout's path. The index is stored at `<repo>/.seraph/index.sqlite` and ignored by Git.
+
+## MCP tools
+
+- `search_code`: retrieve relevant code from the selected checkout.
+- `search_at_version`: retrieve code from a commit, branch, or tag.
+- `search_history`: search indexed Git versions.
+- `find_symbol`: locate a function, class, or method.
+- `find_dependencies`: walk call, import, and inheritance relationships.
+- `compare_versions`: compare symbols, dependencies, and commits.
+- `index_repository`: explicitly index a Git version; searches index automatically when needed.
+
+The default retrieval setup is local and needs no API key. Benchmark/evaluation code and submission assets are intentionally excluded from this slim distribution.
+
+## CLI
+
+```sh
+seraph --repo /path/to/repo index
+seraph --repo /path/to/repo search "where is request authentication checked?"
+seraph --repo /path/to/repo symbol authenticate_request
+seraph --repo /path/to/repo deps authenticate_request
+seraph --repo /path/to/repo compare <old-commit> <new-commit>
+```
+
+## License
+
+See [`LICENSE`](LICENSE).

seraph_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[project]
+name = "seraph-mcp"
+version = "0.1.0"
+description = "Query-adaptive, evolution-aware code retrieval"
+readme = "README.md"
+requires-python = ">=3.12,<3.13"
+license = { file = "LICENSE" }
+dependencies = [
+    "numpy>=1.26",
+    "pydantic>=2.7",
+    "pyyaml>=6.0",
+    "scikit-learn>=1.5",
+    "bm25s>=0.2.6",
+    "PyStemmer>=2.2",
+    "tree-sitter>=0.23",
+    "tree-sitter-python>=0.23",
+    "tree-sitter-typescript>=0.23",
+    "tree-sitter-javascript>=0.23",
+    "tree-sitter-go>=0.23",
+]
+
+[project.optional-dependencies]
+cpu = [
+    "torch>=2.4",
+    "transformers>=5.19",
+    "sentence-transformers>=6.1",
+    "faiss-cpu>=1.8",
+    "einops>=0.8",
+]
+gpu = [
+    "torch>=2.4",
+    "transformers>=5.19",
+    "sentence-transformers>=6.1",
+    "faiss-cpu>=1.8",
+    "einops>=0.8",
+]
+llm = ["openai>=1.40"]
+api = [
+    "google-genai>=1.20",
+    "openai>=1.40",
+]
+mcp = ["mcp>=1.2,<2"]
+
+[project.scripts]
+seraph = "seraph.cli:main"
+seraph-mcp = "seraph.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8.2", "ruff>=0.6"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/seraph"]
+
+[tool.uv]
+python-preference = "managed"
+conflicts = [[{ extra = "cpu" }, { extra = "gpu" }]]
+
+[tool.uv.sources]
+torch = [
+    { index = "pytorch-cpu", extra = "cpu" },
+    { index = "pytorch-cu126", extra = "gpu" },
+]
+
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[[tool.uv.index]]
+name = "pytorch-cu126"
+url = "https://download.pytorch.org/whl/cu126"
+explicit = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM"]
+ignore = ["E501", "B008"]
+

seraph_mcp-0.1.0/requirements.txt

@@ -0,0 +1 @@
+.[mcp]

seraph_mcp-0.1.0/src/seraph/__init__.py

@@ -0,0 +1,5 @@
+"""Seraph code intelligence engine."""
+
+from .index import Chunk, IndexStats, SearchHit, VersionedIndex
+
+__all__ = ["Chunk", "IndexStats", "SearchHit", "VersionedIndex"]

seraph_mcp-0.1.0/src/seraph/backends/common.py

@@ -0,0 +1,102 @@
+"""Shared plumbing for API backends: rate limiting, retries, persistent per-item cache."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import re
+import sqlite3
+import threading
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+_RETRYABLE = ("429", "RESOURCE_EXHAUSTED", "503", "UNAVAILABLE", "500", "INTERNAL", "DEADLINE", "timed out")
+
+
+class MissingAPIKeyError(RuntimeError):
+    pass
+
+
+def require_key(env: str) -> str:
+    key = os.environ.get(env)
+    if not key:
+        raise MissingAPIKeyError(
+            f"{env} is not set. Set it (PowerShell: setx {env} <key>, then reopen the terminal) "
+            "or switch this component to a local model in the config."
+        )
+    return key
+
+
+class RateLimiter:
+    """Spaces calls to at most `rpm` per minute."""
+
+    def __init__(self, rpm: float) -> None:
+        self.interval = 60.0 / rpm if rpm > 0 else 0.0
+        self._next = 0.0
+        self._lock = threading.Lock()
+
+    def wait(self) -> None:
+        with self._lock:
+            now = time.monotonic()
+            if now < self._next:
+                time.sleep(self._next - now)
+            self._next = max(now, self._next) + self.interval
+
+
+class QuotaExhaustedError(RuntimeError):
+    """A daily quota is used up; retrying today will not help. Switch keys or wait."""
+
+
+_RETRY_DELAY = re.compile(r"retry(?:Delay)?['\"]?\s*[:=]?\s*['\"]?(\d+(?:\.\d+)?)s", re.I)
+
+
+def with_retries[T](fn: Callable[[], T], attempts: int = 8, base_delay: float = 4.0) -> T:
+    for i in range(attempts):
+        try:
+            return fn()
+        except Exception as e:
+            msg = str(e)
+            if "PerDay" in msg:
+                raise QuotaExhaustedError(f"daily API quota exhausted: {msg[:300]}") from e
+            if i == attempts - 1 or not any(code in msg for code in _RETRYABLE):
+                raise
+            hint = _RETRY_DELAY.search(msg)
+            delay = float(hint.group(1)) + 1 if hint else min(base_delay * 2**i, 120.0)
+            log.warning("API call failed (%s); retrying in %.0fs", msg[:120], delay)
+            time.sleep(delay)
+    raise AssertionError("unreachable")
+
+
+class KVCache:
+    """SQLite key -> bytes store; survives interrupted runs (free-tier daily limits)."""
+
+    def __init__(self, path: str | Path) -> None:
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self._db = sqlite3.connect(path, check_same_thread=False)
+        self._db.execute("CREATE TABLE IF NOT EXISTS kv (k TEXT PRIMARY KEY, v BLOB)")
+        self._db.commit()
+
+    @staticmethod
+    def key(*parts: str) -> str:
+        h = hashlib.sha1()
+        for p in parts:
+            h.update(p.encode())
+            h.update(b"\x00")
+        return h.hexdigest()
+
+    def get_many(self, keys: list[str]) -> dict[str, bytes]:
+        out: dict[str, bytes] = {}
+        for i in range(0, len(keys), 500):
+            chunk = keys[i : i + 500]
+            q = f"SELECT k, v FROM kv WHERE k IN ({','.join('?' * len(chunk))})"
+            out.update(self._db.execute(q, chunk).fetchall())
+        return out
+
+    def put_many(self, items: dict[str, bytes]) -> None:
+        self._db.executemany("INSERT OR REPLACE INTO kv VALUES (?, ?)", items.items())
+        self._db.commit()

seraph_mcp-0.1.0/src/seraph/backends/gemini.py

@@ -0,0 +1,186 @@
+"""Gemini API backends: embeddings and an LLM listwise reranker."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from collections.abc import Sequence
+from pathlib import Path
+
+import numpy as np
+
+from seraph.backends.common import KVCache, RateLimiter, require_key, with_retries
+from seraph.config import ModelSpec
+from seraph.retrieval.reranker import head_tail
+from seraph.retrieval.vectors import normalize
+from seraph.types import ScoredChunk
+
+log = logging.getLogger(__name__)
+
+
+def make_client(api_key_env: str = "GEMINI_API_KEY", client=None):
+    if client is not None:
+        return client
+    from google import genai
+
+    return genai.Client(api_key=require_key(api_key_env))
+
+
+class GeminiEmbedder:
+    """`gemini-embedding-001` with task types; every text is cached individually."""
+
+    def __init__(self, spec: ModelSpec, cache_dir: str | Path, client=None) -> None:
+        o = spec.options
+        self.spec = spec
+        self.name = spec.name
+        self.model = spec.hf_id
+        self.dim = int(o.get("output_dim", 768))
+        self.revision = f"{self.model}-d{self.dim}"
+        self.query_task = o.get("query_task", "CODE_RETRIEVAL_QUERY")
+        self.doc_task = o.get("doc_task", "RETRIEVAL_DOCUMENT")
+        self.batch = int(o.get("batch", 100))
+        self.max_chars = int(o.get("max_chars", 6000))
+        self._client = client
+        self._limiter = RateLimiter(float(o.get("rpm", 90)))
+        self._cache = KVCache(Path(cache_dir) / "api" / f"{spec.name}.sqlite")
+
+    @property
+    def client(self):
+        self._client = make_client(self.spec.options.get("api_key_env", "GEMINI_API_KEY"), self._client)
+        return self._client
+
+    def _call(self, texts: list[str], task: str) -> np.ndarray:
+        from google.genai import types
+
+        def go():
+            self._limiter.wait()
+            resp = self.client.models.embed_content(
+                model=self.model,
+                contents=texts,
+                config=types.EmbedContentConfig(task_type=task, output_dimensionality=self.dim),
+            )
+            return np.array([e.values for e in resp.embeddings], dtype=np.float32)
+
+        return with_retries(go)
+
+    def _encode(self, texts: Sequence[str], task: str, prefix: str) -> np.ndarray:
+        texts = [(prefix + t)[: self.max_chars] or " " for t in texts]
+        keys = [KVCache.key(self.revision, task, t) for t in texts]
+        have = self._cache.get_many(list(set(keys)))
+        missing = sorted({k: t for k, t in zip(keys, texts, strict=True) if k not in have}.items())
+        for i in range(0, len(missing), self.batch):
+            part = missing[i : i + self.batch]
+            vecs = self._call([t for _, t in part], task)
+            new = {k: v.tobytes() for (k, _), v in zip(part, vecs, strict=True)}
+            self._cache.put_many(new)
+            have.update(new)
+            if len(missing) > self.batch:
+                log.info("embedded %d/%d", min(i + self.batch, len(missing)), len(missing))
+        return normalize(np.stack([np.frombuffer(have[k], dtype=np.float32) for k in keys]))
+
+    def encode_queries(self, texts: Sequence[str]) -> np.ndarray:
+        return self._encode(texts, self.query_task, self.spec.query_prefix)
+
+    def encode_documents(self, texts: Sequence[str]) -> np.ndarray:
+        return self._encode(texts, self.doc_task, self.spec.doc_prefix)
+
+
+LISTWISE_PROMPT = """You rank candidate code snippets by how likely each one solves the programming task.
+
+Task:
+{query}
+
+Candidates:
+{candidates}
+
+Return ONLY a JSON array of the candidate numbers, best first, including every candidate once."""
+
+
+class GeminiListwiseReranker:
+    """One Gemini call per query reorders the top-N candidates; results are cached per query+set."""
+
+    def __init__(self, spec: ModelSpec, cache_dir: str | Path, blend: float = 0.0, client=None) -> None:
+        o = spec.options
+        self.spec = spec
+        self.name = spec.name
+        self.model = spec.hf_id
+        self.revision = self.model
+        self.blend = blend
+        self.window = int(o.get("window", 20))
+        self.doc_chars = int(o.get("doc_chars", 1200))
+        self.query_chars = int(o.get("query_chars", 3000))
+        self._client = client
+        self._limiter = RateLimiter(float(o.get("rpm", 14)))
+        self._cache = KVCache(Path(cache_dir) / "api" / f"{spec.name}.sqlite")
+
+    @property
+    def client(self):
+        self._client = make_client(self.spec.options.get("api_key_env", "GEMINI_API_KEY"), self._client)
+        return self._client
+
+    def _prompt(self, query: str, cands: Sequence[ScoredChunk]) -> str:
+        body = "\n\n".join(
+            f"[{i + 1}]\n```\n{head_tail(c.chunk.text, self.doc_chars)}\n```" for i, c in enumerate(cands)
+        )
+        return LISTWISE_PROMPT.format(query=head_tail(query, self.query_chars), candidates=body)
+
+    def _order(self, query: str, cands: Sequence[ScoredChunk]) -> list[int]:
+        key = KVCache.key(self.model, query, *[c.chunk_hash for c in cands])
+        hit = self._cache.get_many([key])
+        if key in hit:
+            return json.loads(hit[key])
+        from google.genai import types
+
+        def go():
+            self._limiter.wait()
+            return self.client.models.generate_content(
+                model=self.model,
+                contents=self._prompt(query, cands),
+                config=types.GenerateContentConfig(temperature=0.0, response_mime_type="application/json"),
+            ).text
+
+        order = parse_order(with_retries(go) or "", len(cands))
+        self._cache.put_many({key: json.dumps(order).encode()})
+        return order
+
+    def rerank_batch(
+        self, queries: Sequence[str], candidates: Sequence[Sequence[ScoredChunk]], top_k: int
+    ) -> list[list[ScoredChunk]]:
+        out = []
+        for q, cands in zip(queries, candidates, strict=True):
+            head, rest = list(cands[: self.window]), list(cands[self.window :])
+            order = self._order(q, head) if head else []
+            n = len(head)
+            ranked = []
+            for rank, idx in enumerate(order):
+                c = head[idx]
+                s = 1.0 - rank / max(n, 1)
+                final = s if self.blend == 0 else (1 - self.blend) * s + self.blend * c.score
+                ranked.append(ScoredChunk(c.chunk, final, {**c.scores, "rerank": s}))
+            ranked.sort(key=lambda x: -x.score)
+            floor = min((r.score for r in ranked), default=0.0)
+            ranked += [ScoredChunk(c.chunk, floor - (j + 1) * 1e-3, c.scores) for j, c in enumerate(rest)]
+            out.append(ranked[:top_k])
+        return out
+
+    def rerank(self, query: str, candidates: Sequence[ScoredChunk], top_k: int) -> list[ScoredChunk]:
+        return self.rerank_batch([query], [candidates], top_k)[0]
+
+
+def parse_order(text: str, n: int) -> list[int]:
+    """Parse a 1-based ranking; drop invalid/duplicate ids and append any the model skipped."""
+    try:
+        raw = json.loads(text)
+        nums = raw if isinstance(raw, list) else raw.get("ranking", [])
+    except (json.JSONDecodeError, AttributeError):
+        nums = re.findall(r"\d+", text)
+    seen: list[int] = []
+    for x in nums:
+        try:
+            i = int(x) - 1
+        except (TypeError, ValueError):
+            continue
+        if 0 <= i < n and i not in seen:
+            seen.append(i)
+    return seen + [i for i in range(n) if i not in seen]