embedflow 0.1.0__py3-none-any.whl

embedflow/compatibility/__init__.py

@@ -0,0 +1,28 @@
+"""Research-facing compatibility analysis.
+
+The functions in this package are deliberately separate from the serving
+engine.  Analysis with qrels/native target rankings is Mode A (research
+evaluation); serving without a target index is Mode B (finite-tail/T2-v1
+diagnostics).
+"""
+
+from .candidate_gap import CandidateGapCurve, compute_candidate_gap_curve
+from .containment import candidate_containment
+from .evaluate import evaluate_models, evaluate_rankings, evaluate_with_native_rankings
+from .migration_depth import observed_migration_depth, recommend_initial_k
+from .probe import run_finite_pool_probe
+from .t2 import T2Diagnostic, diagnose_t2
+
+__all__ = [
+    "CandidateGapCurve",
+    "T2Diagnostic",
+    "candidate_containment",
+    "compute_candidate_gap_curve",
+    "diagnose_t2",
+    "evaluate_models",
+    "evaluate_rankings",
+    "evaluate_with_native_rankings",
+    "observed_migration_depth",
+    "recommend_initial_k",
+    "run_finite_pool_probe",
+]

embedflow/compatibility/candidate_gap.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import asdict, dataclass
+from typing import Any
+
+import numpy as np
+
+from .containment import candidate_containment
+from .metrics import ndcg, paired_bootstrap
+from .migration_depth import observed_migration_depth
+
+
+@dataclass(frozen=True)
+class CandidateGapCurve:
+    """One point on an evaluated target-quality curve."""
+
+    k: int
+    native_target_quality: float
+    restricted_target_quality: float
+    candidate_gap: float
+    containment: float
+    queries: int
+    gap_ci_low: float | None = None
+    gap_ci_high: float | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def compute_candidate_gap_curve(
+    *,
+    source_rankings: Mapping[str, Sequence[str]],
+    target_scores: Mapping[str, Mapping[str, float]],
+    native_target_rankings: Mapping[str, Sequence[str]],
+    qrels: Mapping[str, Mapping[str, int]],
+    k_values: Sequence[int] = (10, 20, 50, 100, 200, 500),
+    quality_k: int = 10,
+    bootstrap_resamples: int = 0,
+    seed: int = 42,
+) -> list[CandidateGapCurve]:
+    """Compute G(K) and containment from native target evaluation artifacts.
+
+    ``target_scores`` must contain target scores for source candidates only;
+    this function never treats containment as candidate gap.  A native target
+    ranking is required to establish M_T.
+    """
+    if not k_values:
+        raise ValueError("k_values must contain at least one positive depth")
+    normalized_k = []
+    seen_k: set[int] = set()
+    for value in k_values:
+        if isinstance(value, bool) or int(value) != value or int(value) < 1:
+            raise ValueError("k_values must contain positive integers")
+        depth = int(value)
+        if depth in seen_k:
+            raise ValueError(f"duplicate candidate depth K={depth}")
+        seen_k.add(depth); normalized_k.append(depth)
+    if isinstance(quality_k, bool) or int(quality_k) != quality_k or int(quality_k) < 1:
+        raise ValueError("quality_k must be a positive integer")
+    query_ids = [str(q) for q in source_rankings if str(q) in target_scores and str(q) in native_target_rankings and str(q) in qrels]
+    if not query_ids:
+        raise ValueError("no query IDs overlap source rankings, target scores, native rankings, and qrels")
+    points: list[CandidateGapCurve] = []
+    native_values = {qid: ndcg(native_target_rankings[qid], qrels[qid], quality_k) for qid in query_ids}
+    for raw_k in sorted(normalized_k):
+        native_quality = [native_values[qid] for qid in query_ids]
+        restricted_quality: list[float] = []
+        contains: list[float] = []
+        gaps: list[float] = []
+        for qid in query_ids:
+            source = [str(doc_id) for doc_id in source_rankings[qid]]
+            score_map = target_scores[qid]
+            candidates = source[:raw_k]
+            positions: dict[str, int] = {}
+            for position, doc_id in enumerate(source):
+                positions.setdefault(doc_id, position)
+            missing = [doc_id for doc_id in candidates if doc_id not in score_map]
+            if missing:
+                raise ValueError(f"target_scores missing {len(missing)} source candidates for query {qid!r}")
+            if any(not np.isfinite(float(score_map[doc_id])) for doc_id in candidates):
+                raise ValueError(f"target_scores contains non-finite score for query {qid!r}")
+            ranked = sorted(candidates, key=lambda doc_id: (-float(score_map[doc_id]), positions[doc_id]))
+            restricted_quality.append(ndcg(ranked, qrels[qid], quality_k))
+            contains.append(candidate_containment(candidates, native_target_rankings[qid], quality_k))
+            gaps.append(native_values[qid] - restricted_quality[-1])
+        mean_gap = float(np.mean(gaps))
+        low = high = None
+        if bootstrap_resamples:
+            _, low, high = paired_bootstrap(gaps, seed=seed, resamples=bootstrap_resamples)
+        points.append(CandidateGapCurve(
+            k=raw_k,
+            native_target_quality=float(np.mean(native_quality)),
+            restricted_target_quality=float(np.mean(restricted_quality)),
+            candidate_gap=mean_gap,
+            containment=float(np.mean(contains)),
+            queries=len(query_ids),
+            gap_ci_low=low,
+            gap_ci_high=high,
+        ))
+    return points
+
+
+def observed_k_epsilon(curve: Sequence[CandidateGapCurve], epsilon: float = 0.01) -> int | None:
+    return observed_migration_depth([point.to_dict() for point in curve], epsilon=epsilon)

embedflow/compatibility/containment.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+
+def candidate_containment(source_ranked: Sequence[str], target_ranked: Sequence[str], k: int = 10) -> float:
+    """Fraction of the target top-k that appears in the source candidate list."""
+    if isinstance(k, bool) or int(k) != k or int(k) < 1:
+        raise ValueError("k must be a positive integer")
+    k = int(k)
+    target = set(map(str, target_ranked[:k]))
+    return float(len(target & set(map(str, source_ranked))) / len(target)) if target else 0.0
+
+
+def containment_at_k(source_ranked: Sequence[str], target_ranked: Sequence[str], k: int = 10) -> float:
+    """Alias retained for reports and downstream notebooks."""
+    return candidate_containment(source_ranked, target_ranked, k=k)

embedflow/compatibility/evaluate.py

@@ -0,0 +1,319 @@
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Iterable, Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+from ..indexes import FaissIndex, NumpyIndex, QdrantIndex
+from ..migration.state import DocumentStore
+from ..models import EmbeddingModel
+from .candidate_gap import compute_candidate_gap_curve
+from .containment import candidate_containment
+from .metrics import ndcg, recall
+from .report import migration_report
+
+
+def load_queries(path: str | Path) -> list[tuple[str, str]]:
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(path)
+    rows: list[tuple[str, str]] = []
+    seen: set[str] = set()
+    with path.open() as handle:
+        for number, line in enumerate(handle, 1):
+            if not line.strip():
+                continue
+            try:
+                row = json.loads(line)
+            except json.JSONDecodeError as exc:
+                raise ValueError(f"invalid query JSON at {path}:{number}") from exc
+            if not isinstance(row, dict):
+                raise ValueError(f"query row {number} in {path} must be a JSON object")
+            query_id = str(row.get("id", row.get("query_id", number)))
+            text = row.get("text", row.get("query"))
+            if not isinstance(text, str) or not text.strip():
+                raise ValueError(f"query {query_id!r} has no text")
+            if query_id in seen:
+                raise ValueError(f"duplicate query ID {query_id!r} in {path}")
+            seen.add(query_id)
+            rows.append((query_id, text))
+    if not rows:
+        raise ValueError(f"query file is empty: {path}")
+    return rows
+
+
+def load_qrels(path: str | Path) -> dict[str, dict[str, int]]:
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(path)
+    try:
+        raw = json.loads(path.read_text())
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"qrels is not valid JSON: {path}") from exc
+    if not isinstance(raw, dict):
+        raise ValueError("qrels must be a JSON object mapping query IDs to document relevance maps")
+    output: dict[str, dict[str, int]] = {}
+    for query_id, labels in raw.items():
+        if not isinstance(labels, Mapping):
+            raise ValueError(f"qrels for query {query_id!r} must be an object")
+        cleaned: dict[str, int] = {}
+        for document_id, value in labels.items():
+            if isinstance(value, bool):
+                raise ValueError("qrel relevance values must be finite non-negative integers")
+            try:
+                numeric = float(value)
+            except (TypeError, ValueError) as exc:
+                raise ValueError("qrel relevance values must be finite non-negative integers") from exc
+            if not math.isfinite(numeric) or numeric < 0 or int(numeric) != numeric:
+                raise ValueError("qrel relevance values must be finite non-negative integers")
+            cleaned[str(document_id)] = int(numeric)
+        output[str(query_id)] = cleaned
+    return output
+
+
+def _load_index(path: str | Path, backend: str, metric: str, documents: dict[str, str], dimension: int | None = None):
+    if backend == "faiss":
+        try:
+            return FaissIndex.load(path, metric=metric, documents=documents)
+        except RuntimeError as exc:
+            try:
+                return NumpyIndex.load(path, metric=metric, documents=documents)
+            except Exception as fallback_exc:
+                raise exc from fallback_exc
+    if backend == "qdrant":
+        return QdrantIndex.connect(str(path), "embedflow", int(dimension or 0), documents=documents, metric=metric)
+    raise ValueError(f"unsupported index backend: {backend}")
+
+
+def _rank_scores(scores: Mapping[str, float], *, tie_order: Sequence[str]) -> list[str]:
+    return sorted((str(doc_id) for doc_id in scores), key=lambda doc_id: (-float(scores[doc_id]), tie_order.index(doc_id) if doc_id in tie_order else len(tie_order)))
+
+
+def ann_fidelity(source_rankings: Mapping[str, Sequence[str]], reference_rankings: Mapping[str, Sequence[str]], k: int = 100) -> dict[str, Any]:
+    """Compare source ANN rankings with an exact/reference source ranking."""
+    if isinstance(k, bool) or int(k) != k or int(k) < 1:
+        raise ValueError("ANN audit k must be a positive integer")
+    values = []
+    for query_id, ranking in source_rankings.items():
+        reference = reference_rankings.get(query_id)
+        if reference is None:
+            continue
+        values.append(candidate_containment(ranking, reference, k=k))
+    if not values:
+        return {"status": "UNKNOWN", "queries": 0, "note": "No overlapping source/reference rankings were supplied."}
+    mean = float(np.mean(values))
+    return {
+        "status": "PASS" if mean >= 0.95 else "WARNING",
+        "queries": len(values),
+        "k": int(k),
+        "mean_overlap": mean,
+        "note": "Overlap with the supplied exact/reference source retrieval; this is not a T2-v1 measurement.",
+    }
+
+
+def evaluate_rankings(
+    *,
+    source_rankings: Mapping[str, Sequence[str]],
+    native_target_rankings: Mapping[str, Sequence[str]],
+    target_scores: Mapping[str, Mapping[str, float]],
+    qrels: Mapping[str, Mapping[str, int]],
+    source_model: str,
+    target_model: str,
+    corpus_size: int,
+    k_values: Sequence[int] = (10, 20, 50, 100, 200, 500),
+    quality_k: int = 10,
+    epsilon: float = 0.01,
+    bootstrap_resamples: int = 0,
+    seed: int = 42,
+    diagnostic: str | None = None,
+    recommended_k: int | None = None,
+    ann_status: str = "UNKNOWN",
+) -> dict[str, Any]:
+    if not k_values:
+        raise ValueError("k_values must contain at least one positive depth")
+    if len(set(k_values)) != len(k_values) or any(isinstance(k, bool) or int(k) != k or int(k) < 1 for k in k_values):
+        raise ValueError("k_values must contain unique positive integers")
+    if isinstance(quality_k, bool) or int(quality_k) != quality_k or int(quality_k) < 1:
+        raise ValueError("quality_k must be a positive integer")
+    curve = compute_candidate_gap_curve(
+        source_rankings=source_rankings,
+        target_scores=target_scores,
+        native_target_rankings=native_target_rankings,
+        qrels=qrels,
+        k_values=k_values,
+        quality_k=quality_k,
+        bootstrap_resamples=bootstrap_resamples,
+        seed=seed,
+    )
+    shared = [qid for qid in source_rankings if qid in qrels and qid in native_target_rankings]
+    source_quality = [ndcg(source_rankings[qid], qrels[qid], quality_k) for qid in shared]
+    source_recall = [recall(source_rankings[qid], qrels[qid], max(k_values)) for qid in shared]
+    native_quality = [ndcg(native_target_rankings[qid], qrels[qid], quality_k) for qid in shared]
+    result = migration_report(
+        source_model=source_model,
+        target_model=target_model,
+        corpus_size=corpus_size,
+        curve=curve,
+        diagnostic=diagnostic,
+        recommended_k=recommended_k,
+        ann_status=ann_status,
+        epsilon=epsilon,
+        native_target_index_used=True,
+    )
+    result["source_quality"] = {"ndcg_at_k": float(np.mean(source_quality)) if source_quality else 0.0,
+                                 "recall_at_k": float(np.mean(source_recall)) if source_recall else 0.0,
+                                 "k": max(k_values)}
+    result["native_target_quality"] = {"ndcg_at_k": float(np.mean(native_quality)) if native_quality else 0.0, "k": quality_k}
+    result["queries_evaluated"] = len(shared)
+    result["bootstrap_resamples"] = int(bootstrap_resamples)
+    return result
+
+
+def evaluate_models(
+    *,
+    source_model: EmbeddingModel,
+    target_model: EmbeddingModel,
+    source_index: Any,
+    documents: DocumentStore,
+    queries: Iterable[tuple[str, str]],
+    qrels: Mapping[str, Mapping[str, int]],
+    native_target_index: Any | None = None,
+    reference_source_index: Any | None = None,
+    k_values: Sequence[int] = (10, 20, 50, 100, 200, 500),
+    quality_k: int = 10,
+    epsilon: float = 0.01,
+    bootstrap_resamples: int = 0,
+    seed: int = 42,
+    diagnostic: str | None = None,
+    recommended_k: int | None = None,
+) -> dict[str, Any]:
+    """Evaluate Mode A using qrels and optional native/reference indexes.
+
+    If a native target index is omitted, the target model encodes the corpus
+    in-process to establish M_T.  That is correct but potentially expensive;
+    production-scale users should provide a native target index or saved
+    rankings instead.
+    """
+    queries = [(str(qid), str(text)) for qid, text in queries if str(qid) in qrels]
+    if not queries:
+        raise ValueError("no evaluation queries overlap qrels")
+    if source_index.size() < 1:
+        raise ValueError("source index is empty")
+    if not k_values or any(isinstance(k, bool) or int(k) != k or int(k) < 1 for k in k_values):
+        raise ValueError("k_values must contain positive integers")
+    max_k = min(max(int(k) for k in k_values), source_index.size())
+    source_rankings: dict[str, list[str]] = {}
+    source_vectors: dict[str, np.ndarray] = {}
+    target_query_vectors: dict[str, np.ndarray] = {}
+    for query_id, text in queries:
+        source_vector = np.asarray(source_model.encode_query(text), dtype="float32")
+        source_vectors[query_id] = source_vector
+        source_rankings[query_id] = [hit.document_id for hit in source_index.search(source_vector, max_k)]
+        target_query_vectors[query_id] = np.asarray(target_model.encode_query(text), dtype="float32")
+
+    candidate_ids = list(dict.fromkeys(doc_id for ids in source_rankings.values() for doc_id in ids))
+    candidate_texts = documents.get(candidate_ids)
+    candidate_vectors = target_model.encode_documents([candidate_texts[doc_id] for doc_id in candidate_ids], batch_size=32)
+    candidate_vectors = np.asarray(candidate_vectors, dtype="float32")
+    target_scores = {
+        query_id: {doc_id: float(candidate_vectors[index] @ target_query_vectors[query_id]) for index, doc_id in enumerate(candidate_ids)}
+        for query_id in source_rankings
+    }
+
+    native_target_rankings: dict[str, list[str]] = {}
+    if native_target_index is not None:
+        for query_id, _ in queries:
+            native_target_rankings[query_id] = [hit.document_id for hit in native_target_index.search(target_query_vectors[query_id], documents.size())]
+    else:
+        all_ids = list(documents.documents)
+        all_texts = documents.get(all_ids)
+        all_vectors = np.asarray(target_model.encode_documents([all_texts[doc_id] for doc_id in all_ids], batch_size=32), dtype="float32")
+        for query_id, _ in queries:
+            scores = all_vectors @ target_query_vectors[query_id]
+            order = np.lexsort((np.arange(len(all_ids)), -scores))
+            native_target_rankings[query_id] = [all_ids[int(index)] for index in order]
+
+    ann_status = "UNKNOWN"
+    if reference_source_index is not None:
+        reference_rankings = {query_id: [hit.document_id for hit in reference_source_index.search(source_vectors[query_id], max_k)] for query_id, _ in queries}
+        ann_status = ann_fidelity(source_rankings, reference_rankings, k=max_k)["status"]
+    return evaluate_rankings(
+        source_rankings=source_rankings,
+        native_target_rankings=native_target_rankings,
+        target_scores=target_scores,
+        qrels=qrels,
+        source_model=source_model.model_id,
+        target_model=target_model.model_id,
+        corpus_size=documents.size(),
+        k_values=k_values,
+        quality_k=quality_k,
+        epsilon=epsilon,
+        bootstrap_resamples=bootstrap_resamples,
+        seed=seed,
+        diagnostic=diagnostic,
+        recommended_k=recommended_k,
+        ann_status=ann_status,
+    )
+
+
+def evaluate_with_native_rankings(
+    *,
+    source_model: EmbeddingModel,
+    target_model: EmbeddingModel,
+    source_index: Any,
+    documents: DocumentStore,
+    queries: Iterable[tuple[str, str]],
+    native_target_rankings: Mapping[str, Sequence[str]],
+    qrels: Mapping[str, Mapping[str, int]],
+    reference_source_index: Any | None = None,
+    k_values: Sequence[int] = (10, 20, 50, 100, 200, 500),
+    quality_k: int = 10,
+    epsilon: float = 0.01,
+    bootstrap_resamples: int = 0,
+    seed: int = 42,
+    diagnostic: str | None = None,
+    recommended_k: int | None = None,
+) -> dict[str, Any]:
+    """Evaluate against saved native target rankings without a target index."""
+    queries = [(str(qid), str(text)) for qid, text in queries if str(qid) in qrels and str(qid) in native_target_rankings]
+    if not queries:
+        raise ValueError("no evaluation queries overlap qrels and native target rankings")
+    if source_index.size() < 1:
+        raise ValueError("source index is empty")
+    if not k_values or any(isinstance(k, bool) or int(k) != k or int(k) < 1 for k in k_values):
+        raise ValueError("k_values must contain positive integers")
+    max_k = min(max(int(k) for k in k_values), source_index.size())
+    source_rankings: dict[str, list[str]] = {}
+    target_query_vectors: dict[str, np.ndarray] = {}
+    for query_id, text in queries:
+        source_rankings[query_id] = [hit.document_id for hit in source_index.search(source_model.encode_query(text), max_k)]
+        target_query_vectors[query_id] = np.asarray(target_model.encode_query(text), dtype="float32")
+    candidate_ids = list(dict.fromkeys(doc_id for ids in source_rankings.values() for doc_id in ids))
+    candidate_texts = documents.get(candidate_ids)
+    vectors = np.asarray(target_model.encode_documents([candidate_texts[doc_id] for doc_id in candidate_ids], batch_size=32), dtype="float32")
+    target_scores = {qid: {doc_id: float(vectors[i] @ target_query_vectors[qid]) for i, doc_id in enumerate(candidate_ids)} for qid, _ in queries}
+    ann_status = "UNKNOWN"
+    if reference_source_index is not None:
+        reference = {qid: [hit.document_id for hit in reference_source_index.search(source_model.encode_query(text), max_k)] for qid, text in queries}
+        ann_status = ann_fidelity(source_rankings, reference, k=max_k)["status"]
+    return evaluate_rankings(
+        source_rankings=source_rankings,
+        native_target_rankings={qid: list(map(str, native_target_rankings[qid])) for qid, _ in queries},
+        target_scores=target_scores,
+        qrels=qrels,
+        source_model=source_model.model_id,
+        target_model=target_model.model_id,
+        corpus_size=documents.size(),
+        k_values=k_values,
+        quality_k=quality_k,
+        epsilon=epsilon,
+        bootstrap_resamples=bootstrap_resamples,
+        seed=seed,
+        diagnostic=diagnostic,
+        recommended_k=recommended_k,
+        ann_status=ann_status,
+    )

embedflow/compatibility/metrics.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+
+import numpy as np
+
+
+def ndcg(ranked_ids: Sequence[str], qrels: Mapping[str, int], k: int = 10) -> float:
+    """Compute nDCG@k for one query using graded relevance labels."""
+    if isinstance(k, bool) or int(k) != k or int(k) < 1:
+        raise ValueError("k must be a positive integer")
+    if not isinstance(qrels, Mapping):
+        raise TypeError("qrels must be a mapping")
+    clean_qrels: dict[str, int] = {}
+    for doc_id, relevance in qrels.items():
+        try:
+            numeric = float(relevance)
+        except (TypeError, ValueError) as exc:
+            raise ValueError("qrel relevance values must be finite numbers") from exc
+        if not math.isfinite(numeric) or numeric < 0 or int(numeric) != numeric:
+            raise ValueError("qrel relevance values must be finite non-negative integers")
+        clean_qrels[str(doc_id)] = int(numeric)
+    # Retrieval backends should return unique IDs, but malformed sidecars and
+    # user-provided rankings do occur.  Score only the first occurrence so a
+    # duplicate cannot inflate DCG above the ideal ranking.
+    ranked = []
+    seen: set[str] = set()
+    for value in ranked_ids:
+        document_id = str(value)
+        if document_id in seen:
+            continue
+        seen.add(document_id)
+        ranked.append(document_id)
+        if len(ranked) >= int(k):
+            break
+    values = [clean_qrels.get(x, 0) for x in ranked]
+    dcg = sum((2**value - 1) / np.log2(position + 2) for position, value in enumerate(values))
+    ideal = sorted(clean_qrels.values(), reverse=True)[: int(k)]
+    idcg = sum((2**value - 1) / np.log2(position + 2) for position, value in enumerate(ideal))
+    return float(dcg / idcg) if idcg else 0.0
+
+
+def recall(ranked_ids: Sequence[str], qrels: Mapping[str, int], k: int = 100) -> float:
+    if isinstance(k, bool) or int(k) != k or int(k) < 1:
+        raise ValueError("k must be a positive integer")
+    if not isinstance(qrels, Mapping):
+        raise TypeError("qrels must be a mapping")
+    positives = set()
+    for doc_id, relevance in qrels.items():
+        if isinstance(relevance, bool):
+            raise ValueError("qrel relevance values must be finite non-negative numbers")
+        try:
+            numeric = float(relevance)
+        except (TypeError, ValueError) as exc:
+            raise ValueError("qrel relevance values must be finite non-negative numbers") from exc
+        if not math.isfinite(numeric) or numeric < 0:
+            raise ValueError("qrel relevance values must be finite non-negative numbers")
+        if numeric > 0:
+            positives.add(str(doc_id))
+    return float(len(set(map(str, ranked_ids[: int(k)])) & positives) / len(positives)) if positives else 0.0
+
+
+def paired_bootstrap(values: Sequence[float], seed: int = 42, resamples: int = 10_000) -> tuple[float, float, float]:
+    """Return mean and a percentile bootstrap interval for paired query values."""
+    values = np.asarray(list(values), dtype="float64")
+    if values.size == 0:
+        raise ValueError("bootstrap requires at least one value")
+    if isinstance(resamples, bool) or int(resamples) != resamples or int(resamples) < 1:
+        raise ValueError("resamples must be a positive integer")
+    if not np.isfinite(values).all():
+        raise ValueError("bootstrap values must be finite")
+    rng = np.random.default_rng(int(seed))
+    draws = values[rng.integers(0, values.size, size=(int(resamples), values.size))].mean(axis=1)
+    return float(values.mean()), float(np.quantile(draws, 0.025)), float(np.quantile(draws, 0.975))

embedflow/compatibility/migration_depth.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+def observed_migration_depth(gap_curve: Sequence[Mapping[str, Any]], epsilon: float = 0.01) -> int | None:
+    """Return observed K*_epsilon from an evaluated G(K) curve.
+
+    This is only valid when the curve was computed against qrels/native target
+    retrieval.  It must not be used for the no-target-index T2-v1 workflow.
+    """
+    try:
+        epsilon_value = float(epsilon)
+    except (TypeError, ValueError, OverflowError) as exc:
+        raise ValueError("epsilon must be non-negative") from exc
+    if not math.isfinite(epsilon_value) or epsilon_value < 0:
+        raise ValueError("epsilon must be non-negative")
+    seen: set[int] = set()
+    normalized = []
+    for row in gap_curve:
+        try:
+            k = int(row["k"])
+            gap = float(row["candidate_gap"])
+        except (KeyError, TypeError, ValueError) as exc:
+            raise ValueError("gap curve rows require numeric k and candidate_gap") from exc
+        try:
+            k_exact = float(row["k"]) == k
+        except (TypeError, ValueError, OverflowError):
+            k_exact = False
+        if not k_exact or k < 1 or not math.isfinite(gap):
+            raise ValueError("gap curve k must be positive and candidate_gap finite")
+        if k in seen:
+            raise ValueError(f"duplicate candidate depth K={k}")
+        seen.add(k); normalized.append((k, gap))
+    for k, gap in sorted(normalized):
+        if gap <= epsilon_value:
+            return k
+    return None
+
+
+def recommend_initial_k(probe_result: Mapping[str, Any], *, default: int = 50) -> tuple[int, str]:
+    """Name the deployment recommendation without calling it K*.
+
+    T2-v1 has no native target metric and therefore cannot identify an
+    observed migration depth.  The returned label intentionally says
+    ``recommended_initial_k`` rather than ``K*``.
+    """
+    if isinstance(default, bool) or int(default) != default or int(default) < 1:
+        raise ValueError("default candidate depth must be a positive integer")
+    if not isinstance(probe_result, Mapping):
+        raise TypeError("probe_result must be a mapping")
+    diagnostic = str(probe_result.get("diagnostic", "UNSAFE_OR_UNCERTAIN")).upper()
+    raw_suggested = default if probe_result.get("recommended_k") is None else probe_result.get("recommended_k")
+    try:
+        suggested = int(raw_suggested)
+        suggested_exact = float(raw_suggested) == suggested
+    except (TypeError, ValueError, OverflowError):
+        suggested, suggested_exact = 0, False
+    if not suggested_exact or suggested < 1:
+        raise ValueError("recommended candidate depth must be positive")
+    if diagnostic == "SAFE":
+        return suggested, "Finite-tail behavior supports this starting K; validate on production traffic."
+    if diagnostic == "EXPAND":
+        return max(suggested, int(default)), "Expand the source candidate depth and perform manual validation."
+    return max(suggested, int(default)), "Evidence is insufficient; prefer manual validation or a full target backfill."

embedflow/compatibility/probe.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+import numpy as np
+
+
+def run_finite_pool_probe(
+    source_model: Any,
+    target_model: Any,
+    source_index: Any,
+    documents: Any,
+    queries: Iterable[tuple[str, str]],
+    *,
+    kmax: int = 500,
+    seed: int = 42,
+    limit: int | None = None,
+    target_document_vectors: Mapping[str, np.ndarray] | None = None,
+) -> dict[str, Any]:
+    """Run the existing leakage-safe T2-v1 probe implementation."""
+    from ..migration.compatibility import run_probe
+
+    return run_probe(
+        source_model,
+        target_model,
+        source_index,
+        documents,
+        queries,
+        kmax=kmax,
+        seed=seed,
+        limit=limit,
+        target_document_vectors=target_document_vectors,
+    )