jev-relevance 0.1.0__tar.gz

jev_relevance-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jev Relevance Contributors
+
+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.

jev_relevance-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: jev-relevance
+Version: 0.1.0
+Summary: Drop-in relevance filter for LangChain RAG retrievers powered by TypeSafe Jev.
+Author: Jev Relevance Contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/saksham-malhotra-27/jev-relevance
+Project-URL: Repository, https://github.com/saksham-malhotra-27/jev-relevance
+Project-URL: Bug Tracker, https://github.com/saksham-malhotra-27/jev-relevance/issues
+Keywords: langchain,rag,retriever,relevance,rerank,classifier,jev,typesafe
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: langchain-core<2,>=1.0
+Requires-Dist: langchain-typesafe<1,>=0.0.1a3
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Dynamic: license-file
+
+# jev-relevance
+
+A drop-in relevance filter for LangChain RAG retrievers, powered by
+[TypeSafe Jev](https://typesafe.ai). Wrap any `BaseRetriever`, and Jev decides
+which retrieved chunks actually answer the query. No chain plumbing, no prompt
+engineering, one (or a few) API calls.
+
+```python
+from jev_relevance import JevRelevanceRetrieverBuilder
+
+retriever = (
+    JevRelevanceRetrieverBuilder()
+    .with_base_retriever(my_vector_retriever)  # any LangChain BaseRetriever
+    .with_top_k(5)
+    .build()
+)
+
+docs = retriever.invoke("What is the capital of France?")
+```
+
+Because `JevRelevanceRetriever` **is a** `BaseRetriever`, you can swap it into an
+existing chain without touching anything else. It returns only the chunks that
+clear the relevance threshold, sorted by Jev score, with the score attached in
+`Document.metadata["relevance"]`.
+
+## Features
+
+- **Drop-in**: subclass of `BaseRetriever`; `astream`, `with_retriever`, agent
+  and chain wiring all keep working.
+- **Two scoring modes**:
+  - `per_chunk` (default): one Jev call per query-passage pair, bounded by
+    `max_concurrency`. Most accurate.
+  - `batched`: every chunk judged in a single request for the "sub-second"
+    latency case (max 32 chunks).
+- **Two providers**: TypeSafe (`typesafe`) and OpenRouter (`openrouter`), plus a
+  factory that lets you register more without touching the core.
+- **fail-open**: on scoring errors you get the unfiltered candidates instead of
+  empty context (configurable).
+- **Zero magic numbers**: every default lives in `constants.py` and every
+  behavior is builder-parameterized.
+
+## Installation
+
+```bash
+pip install jev-relevance
+# or, from this repo:
+python -m venv .venv && .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+Python 3.10+. The library itself only needs `langchain-core` and
+`langchain-typesafe`.
+
+## Providers
+
+| Provider | Default model | Base URL |
+| --- | --- | --- |
+| `typesafe` | `jev-latest` | `https://api.typesafe.ai` |
+| `openrouter` | `~typesafe/jev-latest` | `https://openrouter.ai/api` |
+
+Credentials are **always passed as parameters** — the library never reads env
+vars or `.env` files itself; that's the caller's job. Supply the key (and any
+custom base URL) directly on `ProviderConfig`:
+
+```python
+from jev_relevance import JevRelevanceRetrieverBuilder, ProviderConfig
+
+retriever = (
+    JevRelevanceRetrieverBuilder()
+    .with_base_retriever(my_vector_retriever)
+    .with_provider(
+        ProviderConfig(name="openrouter", api_key=os.environ["OPENROUTER_API_KEY"])
+    )
+    .build()
+)
+```
+
+## Configuration
+
+Everything is available through the builder chain:
+
+| Builder method | Default | Meaning |
+| --- | --- | --- |
+| `.with_question_mode("noul" \| "score")` | `noul` | Noul = binary "answers or not"; score = 0..3 rubric |
+| `.with_threshold(0.5)` | `0.5` | Noul keep-if `score >= threshold` |
+| `.with_score_threshold(2.0)` | `2.0` | Score-mode keep-if `grade >= threshold` |
+| `.with_scoring_mode("per_chunk" \| "batched")` | `per_chunk` | One call per chunk, or one call for all |
+| `.with_top_k(20)` | `20` | Max results returned after filtering |
+| `.with_max_concurrency(8)` | `8` | Concurrent Jev calls in per-chunk mode |
+| `.with_fail_open(True)` | `True` | Return unfiltered candidates on scoring error |
+| `.with_classifier(classifier)` | auto | Inject a ready `TypeSafeClassifier` |
+| `.with_provider(config)` | `typesafe` | Which provider config to build from |
+
+The same values can be passed directly to `JevRelevanceConfig`, which validates
+every field (pydantic) so invalid values fail fast at construction time.
+
+Metadata attached to returned documents:
+
+- `relevance`: the Jev value (noul probability 0..1, or score grade 0..3)
+- `relevance_confidence`: Jev's confidence, score mode only
+
+## Question modes
+
+- **noul** — "Does this passage answer the query?" Binary yes/no probability.
+  The default; best for a strict relevance gate.
+- **score** — "How well does this passage answer the query?" Rubric of 0..3
+  (`Off-topic`, `Tangential`, `Partly answers`, `Fully answers`), plus Jev's
+  confidence.
+
+## Examples
+
+See [`examples/drop_in.py`](examples/drop_in.py) for a runnable swap-in with a
+naive keyword retriever:
+
+```bash
+set TYPESAFE_API_KEY=your-key
+python examples/drop_in.py --provider typesafe
+
+set OPENROUTER_API_KEY=your-key
+python examples/drop_in.py --provider openrouter
+```
+
+## Benchmarks & dashboard
+
+The [jev-relevance-evals](https://github.com/saksham-malhotra-27/jev-relevance-evals)
+companion repo holds the BEIR/NFCorpus benchmark harness and a Streamlit
+dashboard. It scores BM25 candidates three ways on the same frozen pool — plain
+keyword retrieval, the Jev relevance filter (drop-in retriever), and a cheap
+OpenRouter LLM judge — and writes full IR metrics plus per-call cost to JSON.
+On nfcorpus at the default 0.5 threshold, Jev roughly doubles precision at the
+cost of some recall; see the companion repo for the full results tables and
+interactive per-query drill-downs.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest
+```
+
+Tests cover builder validation, provider model-mapping, per-chunk/batched
+scoring, fail-open behavior, and async parity using a mocked classifier — no
+API keys required.

jev_relevance-0.1.0/README.md

@@ -0,0 +1,143 @@
+# jev-relevance
+
+A drop-in relevance filter for LangChain RAG retrievers, powered by
+[TypeSafe Jev](https://typesafe.ai). Wrap any `BaseRetriever`, and Jev decides
+which retrieved chunks actually answer the query. No chain plumbing, no prompt
+engineering, one (or a few) API calls.
+
+```python
+from jev_relevance import JevRelevanceRetrieverBuilder
+
+retriever = (
+    JevRelevanceRetrieverBuilder()
+    .with_base_retriever(my_vector_retriever)  # any LangChain BaseRetriever
+    .with_top_k(5)
+    .build()
+)
+
+docs = retriever.invoke("What is the capital of France?")
+```
+
+Because `JevRelevanceRetriever` **is a** `BaseRetriever`, you can swap it into an
+existing chain without touching anything else. It returns only the chunks that
+clear the relevance threshold, sorted by Jev score, with the score attached in
+`Document.metadata["relevance"]`.
+
+## Features
+
+- **Drop-in**: subclass of `BaseRetriever`; `astream`, `with_retriever`, agent
+  and chain wiring all keep working.
+- **Two scoring modes**:
+  - `per_chunk` (default): one Jev call per query-passage pair, bounded by
+    `max_concurrency`. Most accurate.
+  - `batched`: every chunk judged in a single request for the "sub-second"
+    latency case (max 32 chunks).
+- **Two providers**: TypeSafe (`typesafe`) and OpenRouter (`openrouter`), plus a
+  factory that lets you register more without touching the core.
+- **fail-open**: on scoring errors you get the unfiltered candidates instead of
+  empty context (configurable).
+- **Zero magic numbers**: every default lives in `constants.py` and every
+  behavior is builder-parameterized.
+
+## Installation
+
+```bash
+pip install jev-relevance
+# or, from this repo:
+python -m venv .venv && .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+Python 3.10+. The library itself only needs `langchain-core` and
+`langchain-typesafe`.
+
+## Providers
+
+| Provider | Default model | Base URL |
+| --- | --- | --- |
+| `typesafe` | `jev-latest` | `https://api.typesafe.ai` |
+| `openrouter` | `~typesafe/jev-latest` | `https://openrouter.ai/api` |
+
+Credentials are **always passed as parameters** — the library never reads env
+vars or `.env` files itself; that's the caller's job. Supply the key (and any
+custom base URL) directly on `ProviderConfig`:
+
+```python
+from jev_relevance import JevRelevanceRetrieverBuilder, ProviderConfig
+
+retriever = (
+    JevRelevanceRetrieverBuilder()
+    .with_base_retriever(my_vector_retriever)
+    .with_provider(
+        ProviderConfig(name="openrouter", api_key=os.environ["OPENROUTER_API_KEY"])
+    )
+    .build()
+)
+```
+
+## Configuration
+
+Everything is available through the builder chain:
+
+| Builder method | Default | Meaning |
+| --- | --- | --- |
+| `.with_question_mode("noul" \| "score")` | `noul` | Noul = binary "answers or not"; score = 0..3 rubric |
+| `.with_threshold(0.5)` | `0.5` | Noul keep-if `score >= threshold` |
+| `.with_score_threshold(2.0)` | `2.0` | Score-mode keep-if `grade >= threshold` |
+| `.with_scoring_mode("per_chunk" \| "batched")` | `per_chunk` | One call per chunk, or one call for all |
+| `.with_top_k(20)` | `20` | Max results returned after filtering |
+| `.with_max_concurrency(8)` | `8` | Concurrent Jev calls in per-chunk mode |
+| `.with_fail_open(True)` | `True` | Return unfiltered candidates on scoring error |
+| `.with_classifier(classifier)` | auto | Inject a ready `TypeSafeClassifier` |
+| `.with_provider(config)` | `typesafe` | Which provider config to build from |
+
+The same values can be passed directly to `JevRelevanceConfig`, which validates
+every field (pydantic) so invalid values fail fast at construction time.
+
+Metadata attached to returned documents:
+
+- `relevance`: the Jev value (noul probability 0..1, or score grade 0..3)
+- `relevance_confidence`: Jev's confidence, score mode only
+
+## Question modes
+
+- **noul** — "Does this passage answer the query?" Binary yes/no probability.
+  The default; best for a strict relevance gate.
+- **score** — "How well does this passage answer the query?" Rubric of 0..3
+  (`Off-topic`, `Tangential`, `Partly answers`, `Fully answers`), plus Jev's
+  confidence.
+
+## Examples
+
+See [`examples/drop_in.py`](examples/drop_in.py) for a runnable swap-in with a
+naive keyword retriever:
+
+```bash
+set TYPESAFE_API_KEY=your-key
+python examples/drop_in.py --provider typesafe
+
+set OPENROUTER_API_KEY=your-key
+python examples/drop_in.py --provider openrouter
+```
+
+## Benchmarks & dashboard
+
+The [jev-relevance-evals](https://github.com/saksham-malhotra-27/jev-relevance-evals)
+companion repo holds the BEIR/NFCorpus benchmark harness and a Streamlit
+dashboard. It scores BM25 candidates three ways on the same frozen pool — plain
+keyword retrieval, the Jev relevance filter (drop-in retriever), and a cheap
+OpenRouter LLM judge — and writes full IR metrics plus per-call cost to JSON.
+On nfcorpus at the default 0.5 threshold, Jev roughly doubles precision at the
+cost of some recall; see the companion repo for the full results tables and
+interactive per-query drill-downs.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+python -m pytest
+```
+
+Tests cover builder validation, provider model-mapping, per-chunk/batched
+scoring, fail-open behavior, and async parity using a mocked classifier — no
+API keys required.

jev_relevance-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "jev-relevance"
+version = "0.1.0"
+description = "Drop-in relevance filter for LangChain RAG retrievers powered by TypeSafe Jev."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Jev Relevance Contributors" }]
+keywords = [
+    "langchain",
+    "rag",
+    "retriever",
+    "relevance",
+    "rerank",
+    "classifier",
+    "jev",
+    "typesafe",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "langchain-core>=1.0,<2",
+    "langchain-typesafe>=0.0.1a3,<1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+]
+
+[project.urls]
+Homepage = "https://github.com/saksham-malhotra-27/jev-relevance"
+Repository = "https://github.com/saksham-malhotra-27/jev-relevance"
+"Bug Tracker" = "https://github.com/saksham-malhotra-27/jev-relevance/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+jev_relevance = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+source = ["jev_relevance"]

jev_relevance-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

jev_relevance-0.1.0/src/jev_relevance/__init__.py

@@ -0,0 +1,74 @@
+"""jev-relevance: a drop-in relevance filter for LangChain RAG retrievers.
+
+Wrap any ``BaseRetriever``; Jev scores every candidate in one bounded pass and
+the wrapper returns only the chunks that answer the query, ranked by relevance.
+
+Basic usage (TypeSafe Provider):
+
+    from jev_relevance import JevRelevanceRetrieverBuilder
+
+    retriever = (
+        JevRelevanceRetrieverBuilder()
+        .with_base_retriever(my_vector_retriever)
+        .with_top_k(5)
+        .build()
+    )
+
+OpenRouter Provider (api_key passed as a param):
+
+    from jev_relevance import JevRelevanceRetrieverBuilder
+    from jev_relevance.config import ProviderConfig
+
+    retriever = (
+        JevRelevanceRetrieverBuilder()
+        .with_base_retriever(my_vector_retriever)
+        .with_provider(ProviderConfig(name="openrouter", api_key="sk-..."))
+        .build()
+    )
+"""
+
+from jev_relevance.builder import JevRelevanceRetrieverBuilder
+from jev_relevance.config import (
+    JevRelevanceConfig,
+    ProviderConfig,
+    ProviderName,
+    QuestionMode,
+    ScoringMode,
+)
+from jev_relevance.constants import Provider
+from jev_relevance.provider import ProviderFactory, build_classifier
+from jev_relevance.retriever import JevRelevanceRetriever
+from jev_relevance.scoring import (
+    build_noul_question,
+    build_state,
+)
+from jev_relevance.strategies import (
+    BatchedScorer,
+    DocumentScore,
+    PerChunkScorer,
+    ScoringStrategy,
+    build_scoring_strategy,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "JevRelevanceRetriever",
+    "JevRelevanceRetrieverBuilder",
+    "JevRelevanceConfig",
+    "ProviderConfig",
+    "ProviderFactory",
+    "build_classifier",
+    "build_scoring_strategy",
+    "build_state",
+    "build_noul_question",
+    "DocumentScore",
+    "ScoringStrategy",
+    "PerChunkScorer",
+    "BatchedScorer",
+    "Provider",
+    "ProviderName",
+    "QuestionMode",
+    "ScoringMode",
+    "__version__",
+]

jev_relevance-0.1.0/src/jev_relevance/builder.py

@@ -0,0 +1,184 @@
+"""Fluent builder that assembles a fully-wired :class:`JevRelevanceRetriever`.
+
+The builder owns the composition order:
+
+1. a validated :class:`JevRelevanceConfig` is built (or edited),
+2. a classifier is produced by the provider factory (or supplied directly),
+3. a :class:`ScoringStrategy` wraps the classifier for the chosen scoring mode,
+4. the strategy and config are handed to the retriever, which wraps the caller's
+   ``base_retriever``.
+
+Every knob has a named default from :mod:`jev_relevance.constants`, so the
+zero-argument path ``JevRelevanceRetrieverBuilder().with_base_retriever(...).build()``
+already behaves sensibly.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.retrievers import BaseRetriever
+from langchain_typesafe import TypeSafeClassifier
+
+from jev_relevance.config import JevRelevanceConfig, ProviderConfig
+from jev_relevance.provider import build_classifier
+from jev_relevance.retriever import JevRelevanceRetriever
+from jev_relevance.strategies import build_scoring_strategy
+
+
+class JevRelevanceRetrieverBuilder:
+    """Build :class:`JevRelevanceRetriever` instances from validated settings.
+
+    Examples:
+        >>> builder = (
+        ...     JevRelevanceRetrieverBuilder()
+        ...     .with_base_retriever(my_vector_retriever)
+        ...     .with_top_k(5)
+        ...     .with_threshold(0.6)
+        ... )
+        >>> retriever = builder.build()
+
+        Use OpenRouter as the Jev provider (instead of TypeSafe default). The
+        api_key is a parameter; the library never reads env vars itself:
+
+        >>> from jev_relevance.config import ProviderConfig
+        >>> builder.with_provider(
+        ...     ProviderConfig(name="openrouter", api_key="sk-...")
+        ... )
+    """
+
+    def __init__(self) -> None:
+        self._config: JevRelevanceConfig = JevRelevanceConfig()
+        self._classifier: TypeSafeClassifier | None = None
+        self._classifier_builder: Any | None = None
+        self._base_retriever: BaseRetriever | None = None
+
+    # ------------------------------------------------------------------
+    # Configuration setters (chainable)
+    # ------------------------------------------------------------------
+
+    def with_base_retriever(self, retriever: BaseRetriever) -> "JevRelevanceRetrieverBuilder":
+        """Set the underlying retrieval engine this filter wraps."""
+        if not isinstance(retriever, BaseRetriever):
+            raise TypeError(
+                f"base_retriever must be a BaseRetriever, got {type(retriever).__name__}."
+            )
+        self._base_retriever = retriever
+        return self
+
+    def with_config(self, config: JevRelevanceConfig) -> "JevRelevanceRetrieverBuilder":
+        """Replace the working config with a fully validated one."""
+        if not isinstance(config, JevRelevanceConfig):
+            raise TypeError(
+                f"config must be a JevRelevanceConfig, got {type(config).__name__}."
+            )
+        self._config = config
+        return self
+
+    def with_question_mode(self, question_mode: str) -> "JevRelevanceRetrieverBuilder":
+        """Choose ``"noul"`` (yes/no probability) or ``"score"`` (0..3 rubric)."""
+        self._config = self._config.model_copy(
+            update={"question_mode": question_mode}
+        )
+        return self
+
+    def with_scoring_mode(self, scoring_mode: str) -> "JevRelevanceRetrieverBuilder":
+        """Choose ``"per_chunk"`` (one call per pair) or ``"batched"`` (one call)."""
+        self._config = self._config.model_copy(
+            update={"scoring_mode": scoring_mode}
+        )
+        return self
+
+    def with_threshold(self, threshold: float) -> "JevRelevanceRetrieverBuilder":
+        """Set the noul-mode relevance probability cutoff (0..1)."""
+        self._config = self._config.model_copy(update={"threshold": threshold})
+        return self
+
+    def with_score_threshold(self, score_threshold: float) -> "JevRelevanceRetrieverBuilder":
+        """Set the score-mode grade cutoff (0..3)."""
+        self._config = self._config.model_copy(
+            update={"score_threshold": score_threshold}
+        )
+        return self
+
+    def with_top_k(self, top_k: int | None) -> "JevRelevanceRetrieverBuilder":
+        """Cap how many documents are returned after filtering (``None`` = all)."""
+        self._config = self._config.model_copy(update={"top_k": top_k})
+        return self
+
+    def with_max_concurrency(self, max_concurrency: int) -> "JevRelevanceRetrieverBuilder":
+        """Set maximum in-flight Jev calls in per-chunk mode."""
+        self._config = self._config.model_copy(
+            update={"max_concurrency": max_concurrency}
+        )
+        return self
+
+    def with_fail_open(self, fail_open: bool) -> "JevRelevanceRetrieverBuilder":
+        """Let scoring failures fall back to unfiltered candidates."""
+        self._config = self._config.model_copy(update={"fail_open": fail_open})
+        return self
+
+    # ------------------------------------------------------------------
+    # Classifier wiring (chainable)
+    # ------------------------------------------------------------------
+
+    def with_classifier(
+        self, classifier: TypeSafeClassifier
+    ) -> "JevRelevanceRetrieverBuilder":
+        """Inject an already-constructed classifier (any provider/Typesafe client).
+
+        Use this when you have custom clients, proxies, or want to reuse a
+        long-lived connection pool.
+        """
+        if not isinstance(classifier, TypeSafeClassifier):
+            raise TypeError(
+                f"classifier must be a TypeSafeClassifier, got {type(classifier).__name__}."
+            )
+        self._classifier = classifier
+        return self
+
+    def with_provider(
+        self, provider_config: ProviderConfig
+    ) -> "JevRelevanceRetrieverBuilder":
+        """Build the classifier through the provider factory from ``provider_config``."""
+        if not isinstance(provider_config, ProviderConfig):
+            raise TypeError(
+                f"provider_config must be a ProviderConfig, got "
+                f"{type(provider_config).__name__}."
+            )
+        self._classifier_builder = lambda: build_classifier(provider_config)
+        self._classifier = None
+        return self
+
+    # ------------------------------------------------------------------
+    # Construction
+    # ------------------------------------------------------------------
+
+    def build(self) -> JevRelevanceRetriever:
+        """Assemble and return the configured retriever.
+
+        Raises:
+            ValueError: If no base retriever was set.
+            The classifier is constructed lazily so providers without a present
+            env-var key only fail at build time, not import time.
+        """
+        if self._base_retriever is None:
+            raise ValueError(
+                "Cannot build JevRelevanceRetriever without a base retriever. "
+                "Call with_base_retriever(...) first."
+            )
+        classifier = self._classifier
+        if classifier is None:
+            if self._classifier_builder is not None:
+                classifier = self._classifier_builder()
+            else:
+                classifier = build_classifier(ProviderConfig.for_provider("typesafe"))
+        strategy = build_scoring_strategy(classifier, self._config)
+        return JevRelevanceRetriever(
+            base_retriever=self._base_retriever,
+            config=self._config,
+            strategy=strategy,
+        )
+
+
+__all__ = ["JevRelevanceRetrieverBuilder"]