PyPI - embedflow - Versions diffs - 0.1.0__py3-none-any.whl - Mend

embedflow 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (64) hide show

embedflow/__init__.py +25 -0
embedflow/__main__.py +3 -0
embedflow/analysis.py +192 -0
embedflow/cache/__init__.py +4 -0
embedflow/cache/base.py +28 -0
embedflow/cache/persistent_cache.py +198 -0
embedflow/cli.py +1200 -0
embedflow/compatibility/__init__.py +28 -0
embedflow/compatibility/candidate_gap.py +105 -0
embedflow/compatibility/containment.py +17 -0
embedflow/compatibility/evaluate.py +319 -0
embedflow/compatibility/metrics.py +75 -0
embedflow/compatibility/migration_depth.py +67 -0
embedflow/compatibility/probe.py +34 -0
embedflow/compatibility/report.py +102 -0
embedflow/compatibility/t2.py +64 -0
embedflow/config.py +455 -0
embedflow/data/__init__.py +1 -0
embedflow/data/registry/__init__.py +1 -0
embedflow/data/registry/benchmark_profiles.jsonl +3 -0
embedflow/data/registry/checksums.sha256 +4 -0
embedflow/data/registry/migrations.jsonl +15 -0
embedflow/data/registry/registry_manifest.json +16 -0
embedflow/data/registry/research_summaries.json +55 -0
embedflow/data/registry/schema_version.json +5 -0
embedflow/frozen/T2_V1_FROZEN_SPEC.md +71 -0
embedflow/frozen/T2_V1_FROZEN_SPEC.sha256 +1 -0
embedflow/indexes/__init__.py +5 -0
embedflow/indexes/base.py +60 -0
embedflow/indexes/faiss_backend.py +240 -0
embedflow/indexes/qdrant_backend.py +225 -0
embedflow/metrics/__init__.py +3 -0
embedflow/metrics/latency.py +50 -0
embedflow/migration/__init__.py +3 -0
embedflow/migration/compatibility.py +156 -0
embedflow/migration/facade.py +312 -0
embedflow/migration/materializer.py +190 -0
embedflow/migration/planner.py +78 -0
embedflow/migration/state.py +81 -0
embedflow/models/__init__.py +4 -0
embedflow/models/base.py +31 -0
embedflow/models/huggingface.py +226 -0
embedflow/registry/__init__.py +47 -0
embedflow/registry/loader.py +785 -0
embedflow/registry/matcher.py +197 -0
embedflow/registry/schema.py +266 -0
embedflow/runtime.py +115 -0
embedflow/serving/__init__.py +3 -0
embedflow/serving/api.py +161 -0
embedflow/serving/engine.py +222 -0
embedflow/serving/factory.py +3 -0
embedflow/serving/schemas.py +39 -0
embedflow-0.1.0.dist-info/METADATA +210 -0
embedflow-0.1.0.dist-info/RECORD +64 -0
embedflow-0.1.0.dist-info/WHEEL +5 -0
embedflow-0.1.0.dist-info/entry_points.txt +2 -0
embedflow-0.1.0.dist-info/licenses/LICENSE +178 -0
embedflow-0.1.0.dist-info/top_level.txt +2 -0
src/__init__.py +1 -0
src/embed.py +123 -0
src/probe_features.py +24 -0
src/storage.py +51 -0
src/t2_v1.py +21 -0
src/utils.py +53 -0

embedflow/serving/api.py ADDED Viewed

@@ -0,0 +1,161 @@
+import html
+import math
+from typing import Any
+def dashboard_html(title: str = "EmbedFlow") -> str:
+    # Keep this as an ordinary template instead of a Python f-string.  The
+    # dashboard contains JavaScript template literals, and escaping every
+    # JavaScript brace in a f-string made browser failures very easy to hide.
+    escaped_title = html.escape(title, quote=True)
+    return '''<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>__TITLE__</title>
+<style>
+body{font:15px system-ui,sans-serif;background:#0b1020;color:#e8eefc;max-width:1100px;margin:0 auto;padding:28px}
+.card{background:#141d35;border:1px solid #2d3b62;border-radius:14px;padding:18px;margin:12px 0}
+.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:12px}
+.label{color:#9fb0d8;font-size:12px;text-transform:uppercase;letter-spacing:.08em}
+.value{font-size:25px;font-weight:650;margin-top:5px}
+input{width:min(75%,650px);padding:12px;border-radius:8px;border:1px solid #45567f;background:#0b1020;color:white}
+button{padding:12px 18px;border:0;border-radius:8px;background:#6ea8fe;color:#071021;font-weight:700;cursor:pointer}
+button:disabled{opacity:.6;cursor:wait}
+table{width:100%;border-collapse:collapse;margin-top:12px}td,th{padding:8px;border-bottom:1px solid #2d3b62;text-align:left}code{color:#a8d5ff}
+.error{color:#ffb4b4;background:#3a1820;border-color:#7c3343}.muted{color:#9fb0d8}
+</style></head>
+<body><h1>EMBEDFLOW</h1><p>Progressive Embedding Migration</p><div id="status" class="card">Connecting to EmbedFlow…</div>
+<div class="card"><h2>Search</h2><form id="form"><input id="query" placeholder="Ask a question…" autocomplete="off" required><button id="submit" type="submit">Search</button></form><div id="search" class="muted">Enter a query to test source retrieval, target reranking, and progressive caching.</div></div>
+<script>
+const fmt=(x)=>x===undefined||x===null?'—':(typeof x==='number'?x.toFixed(2):x);
+const esc=(x)=>String(x??'').replace(/[&<>"']/g,(c)=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+async function jsonFetch(url, options){
+  const response=await fetch(url, options);
+  const text=await response.text();
+  let data={};
+  try{data=text?JSON.parse(text):{};}catch(_){data={detail:text||response.statusText};}
+  if(!response.ok){
+    const detail=data&&data.detail;
+    const message=Array.isArray(detail)?detail.map((item)=>typeof item==='string'?item:(item.msg||JSON.stringify(item))).join('; '):(detail&&typeof detail==='object'?JSON.stringify(detail):(detail||('HTTP '+response.status)));
+    throw new Error(message);
+  }
+  return data;
+}
+async function refresh(){
+  try{
+    const s=await jsonFetch('/status');
+    const m=s.migration||{},c=s.cache||{},w=s.worker||{},l=s.latency||{};
+    document.querySelector('#status').className='card';
+    document.querySelector('#status').innerHTML=`<div class="grid"><div><div class="label">Source</div><div class="value"><code>${esc(m.source_model||'configured')}</code></div></div><div><div class="label">Target</div><div class="value"><code>${esc(m.target_model||'configured')}</code></div></div><div><div class="label">Diagnostic</div><div class="value">${esc(m.diagnostic)}</div></div><div><div class="label">Candidate depth</div><div class="value">K=${fmt(m.candidate_depth)}</div></div><div><div class="label">Cache progress</div><div class="value">${fmt(c.cached_target_vectors)} / ${fmt(m.corpus_size)} (${fmt(100*(m.cache_fraction||0))}%)</div></div><div><div class="label">Background throughput</div><div class="value">${fmt(w.last_throughput_docs_sec)} docs/s</div></div><div><div class="label">Query p50/p95</div><div class="value">${fmt(l.p50_ms)} / ${fmt(l.p95_ms)} ms</div></div></div><p>Status: <b>${esc(m.status)}</b> · ANN: <b>${esc(m.ann_status)}</b></p>`;
+  }catch(error){
+    document.querySelector('#status').className='card error';
+    document.querySelector('#status').textContent='Unable to load migration status: '+error.message;
+  }
+}
+refresh();
+setInterval(refresh,3000);
+document.querySelector('#form').addEventListener('submit',async(event)=>{
+  event.preventDefault();
+  const input=document.querySelector('#query'),button=document.querySelector('#submit'),out=document.querySelector('#search');
+  const query=input.value.trim(); if(!query)return;
+  button.disabled=true; button.textContent='Searching…'; out.className='muted'; out.textContent='Running source retrieval and target reranking…';
+  try{
+    const x=await jsonFetch('/search',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({query:query,top_k:10})});
+    const migration=x.migration||{}, timing=x.timing_ms||{};
+    out.className='';
+    out.innerHTML=`<p><b>${esc(migration.status)}</b> · ${fmt(timing.total_ms)} ms · cache ${fmt(migration.target_cache_hits)}/${fmt(migration.source_candidates)} · queued ${fmt(migration.async_misses_queued)}</p><table><tr><th>Target rank</th><th>Source rank</th><th>Cached</th><th>Document</th></tr>${(x.results||[]).map((a)=>`<tr><td>${fmt(a.target_rank)}</td><td>${fmt(a.source_rank)}</td><td>${a.target_vector_cached?'yes':'no'}</td><td>${esc(a.text)}</td></tr>`).join('')}</table><p class="muted">Total ${fmt(timing.total_ms)} ms · source encode ${fmt(timing.source_query_encode_ms)} ms · ANN ${fmt(timing.source_ann_ms)} ms · target encode ${fmt(timing.target_query_encode_ms)} ms · scoring ${fmt(timing.target_score_ms)} ms</p>`;
+  }catch(error){
+    out.className='card error'; out.textContent='Search failed: '+error.message+' (check the server terminal for details)';
+  }finally{button.disabled=false;button.textContent='Search';}
+});
+</script></body></html>'''.replace('__TITLE__', escaped_title)
+def create_app(engine: Any):
+    try:
+        from fastapi import FastAPI, HTTPException
+        from fastapi.responses import HTMLResponse
+        from .schemas import PrewarmRequest, SearchRequest, SearchResponse
+    except ImportError as exc:
+        raise RuntimeError("API requires fastapi, uvicorn, and pydantic") from exc
+    app = FastAPI(title="EmbedFlow", version="0.1.0")
+    @app.get("/", response_class=HTMLResponse)
+    def root(): return dashboard_html(engine.cfg.dashboard_title)
+    @app.get("/health")
+    def health(): return {"status": "ok"}
+    @app.get("/status")
+    def status(): return engine.status()
+    @app.get("/plan")
+    def plan(): return engine.plan.to_dict()
+    @app.post("/analyze")
+    def analyze():
+        """Return the persisted finite-tail decision and deployment plan."""
+        return {
+            "diagnostic": engine.plan.diagnostic,
+            "recommended_initial_k": engine.plan.candidate_depth,
+            "ann_status": engine.plan.ann_status,
+            "plan": engine.plan.to_dict(),
+            "probe": engine.probe,
+            "warning": "T2-v1 is an empirical finite-tail diagnostic, not a compatibility guarantee.",
+        }
+    @app.post("/search", response_model=SearchResponse)
+    def search(body: SearchRequest):
+        try:
+            result = engine.search(body.query, body.top_k, body.candidate_depth, body.max_sync_misses)
+            migration = result.get("migration", {})
+            # Keep the detailed nested object and expose the compact fields
+            # shown in the public API example at the top level as well.
+            result.update({
+                "state": migration.get("status"),
+                "candidate_depth": migration.get("candidate_depth"),
+                "cache_hits": migration.get("cache_hits", migration.get("target_cache_hits")),
+                "cache_misses": migration.get("cache_misses", migration.get("target_cache_misses")),
+                "sync_encoded": migration.get("sync_encoded", migration.get("sync_misses_encoded")),
+                "async_queued": migration.get("async_queued", migration.get("async_misses_queued")),
+            })
+            return result
+        except (ValueError, KeyError, RuntimeError, TypeError, OSError) as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        except Exception as exc:  # keep backend/model failures as structured API errors
+            raise HTTPException(status_code=500, detail=f"search backend failure: {exc}") from exc
+    @app.post("/prewarm")
+    def prewarm(body: PrewarmRequest):
+        try:
+            return engine.prewarm(body.document_ids, body.asynchronous)
+        except (ValueError, KeyError, RuntimeError, TypeError, OSError) as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+        except Exception as exc:
+            raise HTTPException(status_code=500, detail=f"prewarm backend failure: {exc}") from exc
+    @app.get("/metrics")
+    def metrics():
+        from ..metrics import aggregate_records, summarize
+        values: list[float] = []
+        for row in engine.records:
+            try:
+                value = float(row.get("total_ms"))
+            except (TypeError, ValueError):
+                continue
+            if math.isfinite(value) and value >= 0:
+                values.append(value)
+        return {
+            "latency": summarize(values) if values else {"count": 0},
+            "stages": aggregate_records(engine.records),
+            "cache": engine.cache.stats(),
+            "queue": engine.worker.stats(),
+        }
+    @app.get("/economics")
+    def economics():
+        from ..cli import economics_for
+        return economics_for(engine.documents.size(), engine.cfg.economics.target_docs_per_second, engine.cfg.economics.gpu_price_per_hour,
+                             engine.cache.stats()["cached_target_vectors"])
+    return app

embedflow/serving/engine.py ADDED Viewed

@@ -0,0 +1,222 @@
+from __future__ import annotations
+import json
+import threading
+import time
+from pathlib import Path
+from typing import Any
+import numpy as np
+from ..cache import SQLiteVectorCache
+from ..metrics import summarize
+from ..migration.materializer import MaterializationWorker
+from ..migration.planner import MigrationPlan, make_plan
+from ..migration.state import DocumentStore, MigrationState
+def _elapsed(start: int) -> float:
+    return (time.perf_counter_ns() - start) / 1_000_000.0
+class MigrationEngine:
+    """Backend-agnostic source retrieval + target reranking serving engine."""
+    def __init__(self, cfg: Any, source_model: Any, target_model: Any, source_index: Any,
+                 target_cache: SQLiteVectorCache, documents: DocumentStore,
+                 target_index: Any | None = None, probe: dict[str, Any] | None = None,
+                 ann_status: str = "UNKNOWN", start_worker: bool = True):
+        self.cfg, self.source_model, self.target_model = cfg, source_model, target_model
+        self.source_index, self.target_index, self.cache, self.documents = source_index, target_index, target_cache, documents
+        self.state = MigrationState(cfg.state_path, cfg)
+        self.probe = probe or {}
+        self.ann_status = ann_status
+        self.plan: MigrationPlan = make_plan(target_model=cfg.target.model, corpus_size=documents.size(),
+            diagnostic=self.probe.get("diagnostic", "UNKNOWN"), recommended_k=self.probe.get("recommended_k"),
+            ann_status=ann_status, cached_target_vectors=target_cache.stats()["cached_target_vectors"],
+            default_k=cfg.migration.candidate_depth, throughput_docs_per_second=cfg.economics.target_docs_per_second,
+            gpu_price_per_hour=cfg.economics.gpu_price_per_hour, source_model=cfg.source.model)
+        queue_path = Path(cfg.cache.path) / "materialization_queue.sqlite3"
+        self.worker = MaterializationWorker(target_model, documents, target_cache, queue_path,
+                                            batch_size=cfg.migration.background_batch_size,
+                                            max_retries=cfg.migration.max_retries, state=self.state)
+        self.records: list[dict[str, Any]] = []
+        telemetry_path = getattr(getattr(cfg, "telemetry", None), "latency_log", None)
+        self.metrics_path = Path(telemetry_path) if telemetry_path else Path(cfg.cache.path) / "latency.jsonl"
+        if self.metrics_path.exists():
+            try:
+                with self.metrics_path.open() as handle:
+                    loaded = [json.loads(line) for line in handle if line.strip()]
+                self.records = [row for row in loaded if isinstance(row, dict)]
+            except (OSError, json.JSONDecodeError):
+                # A malformed metrics tail must not make cached vectors
+                # unusable; fresh measurements continue in a new process.
+                self.records = []
+        self._lock = threading.RLock()
+        self._closed = False
+        self.state.update(status="SERVING", diagnostic=self.plan.diagnostic, ann_status=ann_status,
+                          candidate_depth=self.plan.candidate_depth, corpus_size=documents.size(),
+                          migration_strategy=self.plan.migration_strategy)
+        if start_worker: self.worker.start()
+    def _ensure_open(self) -> None:
+        if self._closed:
+            raise RuntimeError("migration engine is closed")
+    def _record(self, row: dict[str, Any]) -> None:
+        with self._lock:
+            self.records.append(row)
+            self.metrics_path.parent.mkdir(parents=True, exist_ok=True)
+            with self.metrics_path.open("a") as handle:
+                handle.write(json.dumps(row, ensure_ascii=False, default=float) + "\n")
+                handle.flush()
+            self.state.update(queries=int(self.state.snapshot().get("queries", 0)) + 1,
+                              last_latency_ms=row["total_ms"], cache=self.cache.stats(), worker=self.worker.stats())
+    def search(self, query: str, top_k: int = 10, candidate_depth: int | None = None,
+               max_sync_misses: int | None = None) -> dict[str, Any]:
+        self._ensure_open()
+        if not isinstance(query, str) or not query.strip(): raise ValueError("query must be a non-empty string")
+        if isinstance(top_k, bool) or int(top_k) != top_k or int(top_k) < 1:
+            raise ValueError("top_k must be a positive integer")
+        if candidate_depth is not None and (isinstance(candidate_depth, bool) or int(candidate_depth) != candidate_depth or int(candidate_depth) < 1):
+            raise ValueError("candidate_depth must be a positive integer")
+        if max_sync_misses is not None and (isinstance(max_sync_misses, bool) or int(max_sync_misses) != max_sync_misses or int(max_sync_misses) < 0):
+            raise ValueError("max_sync_misses must be a non-negative integer")
+        K = int(candidate_depth or self.plan.candidate_depth or self.cfg.migration.candidate_depth)
+        if K < 1:
+            raise ValueError("candidate_depth must be a positive integer")
+        max_sync = self.cfg.migration.max_sync_misses if max_sync_misses is None else int(max_sync_misses)
+        total_start = time.perf_counter_ns(); row: dict[str, Any] = {"mode": "embedflow", "K": K}
+        t = time.perf_counter_ns(); source_vector = np.asarray(self.source_model.encode_query(query), dtype="float32"); row["source_query_encode_ms"] = _elapsed(t)
+        if source_vector.ndim != 1 or source_vector.shape[0] != int(self.source_model.dimension) or not np.isfinite(source_vector).all():
+            raise ValueError("source query encoder returned an invalid vector")
+        t = time.perf_counter_ns(); candidates = self.source_index.search(source_vector, K); row["source_ann_ms"] = _elapsed(t)
+        candidate_ids = [hit.document_id for hit in candidates]
+        t = time.perf_counter_ns(); target_vector = np.asarray(self.target_model.encode_query(query), dtype="float32"); row["target_query_encode_ms"] = _elapsed(t)
+        if target_vector.ndim != 1 or target_vector.shape[0] != int(self.target_model.dimension) or not np.isfinite(target_vector).all():
+            raise ValueError("target query encoder returned an invalid vector")
+        t = time.perf_counter_ns(); cached = self.cache.get(candidate_ids); row["cache_lookup_ms"] = _elapsed(t)
+        missing = [doc_id for doc_id in candidate_ids if doc_id not in cached]
+        initial_hits = len(cached)
+        sync_ids = missing[:max_sync]
+        if sync_ids:
+            t = time.perf_counter_ns()
+            docs = self.documents.get(sync_ids)
+            vectors = self.target_model.encode_documents([docs[x] for x in sync_ids], batch_size=self.cfg.migration.background_batch_size)
+            self.cache.put(sync_ids, vectors); cached.update({x: np.asarray(v, dtype="float32") for x, v in zip(sync_ids, vectors)})
+            row["synchronous_target_encode_ms"] = _elapsed(t)
+        else: row["synchronous_target_encode_ms"] = 0.0
+        async_ids = [doc_id for doc_id in missing if doc_id not in cached]
+        if async_ids: self.worker.enqueue(async_ids)
+        scored_ids = [doc_id for doc_id in candidate_ids if doc_id in cached]
+        t = time.perf_counter_ns()
+        if scored_ids:
+            scores = {doc_id: float(np.asarray(cached[doc_id], dtype="float32") @ target_vector) for doc_id in scored_ids}
+            candidate_positions = {doc_id: position for position, doc_id in enumerate(candidate_ids)}
+            target_order = sorted(scored_ids, key=lambda x: (-scores[x], candidate_positions[x]))
+        else:
+            scores, target_order = {}, candidate_ids[:]
+        row["target_score_ms"] = _elapsed(t)
+        t = time.perf_counter_ns(); selected = target_order[:max(1, int(top_k))]; row["topk_ms"] = _elapsed(t)
+        target_rank = {doc_id: rank for rank, doc_id in enumerate(target_order, 1)}
+        source_rank = {hit.document_id: hit.source_rank + 1 for hit in candidates}
+        results = []
+        for doc_id in selected:
+            results.append({"id": doc_id, "text": self.documents.get([doc_id])[doc_id], "target_score": scores.get(doc_id),
+                            "source_rank": source_rank.get(doc_id), "target_rank": target_rank.get(doc_id), "target_vector_cached": doc_id in cached})
+        # State describes vectors available for this response, including the
+        # bounded synchronous budget.  ``cache_hits`` remains the persistent
+        # lookup count; callers can use ``sync_encoded`` and
+        # ``target_vectors_available`` to distinguish a cold lookup that was
+        # fully satisfied synchronously from a genuinely partial ranking.
+        available_count = len(scored_ids)
+        if available_count == len(candidate_ids): status = "WARM"
+        elif available_count == 0: status = "COLD"
+        else: status = "PARTIAL"
+        row["total_ms"] = _elapsed(total_start); row.update({"cache_hits": initial_hits, "cache_misses": len(missing),
+            "sync_misses_encoded": len(sync_ids), "async_misses_queued": len(async_ids), "status": status,
+            "target_vectors_available": available_count, "candidate_ids": candidate_ids})
+        self._record(row)
+        timings = {k: float(row[k]) for k in ("source_query_encode_ms", "source_ann_ms", "target_query_encode_ms", "cache_lookup_ms",
+                                               "synchronous_target_encode_ms", "target_score_ms", "topk_ms", "total_ms")}
+        return {"results": results, "migration": {"status": status, "source_candidates": len(candidate_ids), "target_cache_hits": initial_hits,
+                 "target_cache_misses": len(missing), "cache_hit_rate": initial_hits / max(1, len(candidate_ids)),
+                 "target_vectors_available": available_count,
+                 "ranking_cache_hit_rate": available_count / max(1, len(candidate_ids)),
+                 "sync_misses_encoded": len(sync_ids), "async_misses_queued": len(async_ids),
+                 # Short aliases mirror the public REST schema while the
+                 # target_* names remain for backwards compatibility.
+                 "cache_hits": initial_hits, "cache_misses": len(missing),
+                 "sync_encoded": len(sync_ids), "async_queued": len(async_ids),
+                 "candidate_depth": K},
+                "timing_ms": timings}
+    def prewarm(self, document_ids: list[str], asynchronous: bool = False) -> dict[str, Any]:
+        self._ensure_open()
+        ids = list(dict.fromkeys(str(x) for x in document_ids)); missing = [x for x in ids if x not in self.cache.contains(ids)]
+        if asynchronous:
+            queued = self.worker.enqueue(missing); return {"requested": len(ids), "queued": queued, "asynchronous": True}
+        if missing:
+            batch_size = max(1, int(self.cfg.migration.background_batch_size))
+            for start in range(0, len(missing), batch_size):
+                chunk = missing[start:start + batch_size]
+                docs = self.documents.get(chunk)
+                vectors = self.target_model.encode_documents([docs[x] for x in chunk], batch_size=batch_size)
+                self.cache.put(chunk, vectors)
+        return {"requested": len(ids), "materialized": len(missing), "asynchronous": False}
+    def status(self) -> dict[str, Any]:
+        self._ensure_open()
+        cache = self.cache.stats(); worker = self.worker.stats(); data = self.state.snapshot()
+        plan = make_plan(target_model=self.cfg.target.model, corpus_size=self.documents.size(), diagnostic=self.plan.diagnostic,
+                         recommended_k=self.plan.candidate_depth, ann_status=self.ann_status,
+                         cached_target_vectors=cache["cached_target_vectors"], default_k=self.cfg.migration.candidate_depth,
+                         source_model=self.cfg.source.model)
+        values: list[float] = []
+        for row in self.records:
+            try:
+                value = float(row.get("total_ms"))
+            except (TypeError, ValueError):
+                continue
+            if np.isfinite(value) and value >= 0:
+                values.append(value)
+        lat = summarize(values) if values else {"count": 0}
+        return {"migration": plan.to_dict(), "cache": cache, "worker": worker, "state": data, "latency": lat}
+    def close(self, close_models: bool = True, close_indexes: bool = True) -> None:
+        """Stop background work and close resources.
+        ``close_models=False`` is used by the public facade when the caller
+        supplied model instances that it still owns.  Existing CLI callers
+        retain the original behavior through the default.
+        """
+        if self._closed:
+            return
+        try:
+            self.worker.close()
+        finally:
+            try:
+                self.cache.close()
+            finally:
+                try:
+                    # Qdrant owns a file lock/client connection; release both
+                    # source and optional target indexes when the engine owns
+                    # the serving session. In-memory/FAISS implementations are
+                    # no-ops, and identity avoids closing a shared object twice.
+                    if close_indexes:
+                        closed_indexes: set[int] = set()
+                        for index in (self.source_index, self.target_index):
+                            if index is None or id(index) in closed_indexes:
+                                continue
+                            close_index = getattr(index, "close", None)
+                            if callable(close_index):
+                                close_index()
+                            closed_indexes.add(id(index))
+                finally:
+                    if close_models:
+                        try:
+                            self.source_model.close()
+                        finally:
+                            self.target_model.close()
+                    self._closed = True

embedflow/serving/factory.py ADDED Viewed

@@ -0,0 +1,3 @@
+from ..runtime import open_engine
+__all__ = ["open_engine"]

embedflow/serving/schemas.py ADDED Viewed

@@ -0,0 +1,39 @@
+"""Pydantic request/response models for the public REST API."""
+from __future__ import annotations
+from typing import Any
+try:
+    from pydantic import BaseModel, Field
+except ImportError:  # pragma: no cover - imported only when API extras are used
+    BaseModel = object  # type: ignore[misc,assignment]
+    def Field(default: Any = None, **_: Any) -> Any:  # type: ignore[misc]
+        return default
+class SearchRequest(BaseModel):
+    query: str = Field(min_length=1)
+    top_k: int = Field(default=10, ge=1, le=100)
+    candidate_depth: int | None = Field(default=None, ge=1)
+    max_sync_misses: int | None = Field(default=None, ge=0)
+class PrewarmRequest(BaseModel):
+    document_ids: list[str] = Field(default_factory=list)
+    asynchronous: bool = True
+class SearchResponse(BaseModel):
+    results: list[dict[str, Any]]
+    migration: dict[str, Any]
+    timing_ms: dict[str, float]
+    # Flattened aliases make the response convenient for clients while the
+    # nested ``migration`` object remains for backwards compatibility.
+    state: str | None = None
+    candidate_depth: int | None = None
+    cache_hits: int | None = None
+    cache_misses: int | None = None
+    sync_encoded: int | None = None
+    async_queued: int | None = None

embedflow-0.1.0.dist-info/METADATA ADDED Viewed

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: embedflow
+Version: 0.1.0
+Summary: Progressive embedding-model migration over existing vector indexes.
+Author: Arnav Srivastav
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://embedflow.org
+Project-URL: Repository, https://github.com/arnsri33/embedflow
+Project-URL: Documentation, https://github.com/arnsri33/embedflow#readme
+Project-URL: Issues, https://github.com/arnsri33/embedflow/issues
+Keywords: embeddings,vector-search,rag,information-retrieval,faiss,qdrant
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+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: numpy>=1.24
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tqdm>=4.65
+Provides-Extra: faiss
+Requires-Dist: faiss-cpu>=1.8.0; extra == "faiss"
+Provides-Extra: qdrant
+Requires-Dist: qdrant-client>=1.9; extra == "qdrant"
+Provides-Extra: models
+Requires-Dist: huggingface-hub>=0.20; extra == "models"
+Requires-Dist: transformers>=4.45; extra == "models"
+Requires-Dist: sentence-transformers>=3.0; extra == "models"
+Requires-Dist: torch>=2.2; extra == "models"
+Provides-Extra: dashboard
+Requires-Dist: fastapi>=0.100; extra == "dashboard"
+Requires-Dist: uvicorn[standard]>=0.23; extra == "dashboard"
+Requires-Dist: pydantic>=2.0; extra == "dashboard"
+Provides-Extra: all
+Requires-Dist: faiss-cpu>=1.8.0; extra == "all"
+Requires-Dist: qdrant-client>=1.9; extra == "all"
+Requires-Dist: huggingface-hub>=0.20; extra == "all"
+Requires-Dist: transformers>=4.45; extra == "all"
+Requires-Dist: sentence-transformers>=3.0; extra == "all"
+Requires-Dist: torch>=2.2; extra == "all"
+Requires-Dist: fastapi>=0.100; extra == "all"
+Requires-Dist: uvicorn[standard]>=0.23; extra == "all"
+Requires-Dist: pydantic>=2.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Dynamic: license-file
+# EmbedFlow
+**Progressive embedding-model migration over existing vector indexes.**
+EmbedFlow lets a new embedding model serve over candidates from an existing
+vector index while target document vectors are materialized progressively. It
+supports migration analysis, persistent caching, background work, FAISS,
+Qdrant, a CLI, and FastAPI.
+The full project README and architecture diagram are on
+<https://github.com/arnsri33/embedflow>.
+## Install
+```bash
+python -m pip install embedflow
+```
+For FAISS and the dashboard:
+```bash
+python -m pip install "embedflow[faiss,dashboard]"
+```
+Qdrant and model-runtime extras are documented in the
+[installation guide](https://github.com/arnsri33/embedflow/blob/main/docs/installation.md).
+For model-backed analysis, install `embedflow[faiss,models,dashboard]`.
+## Why EmbedFlow?
+Embedding-model upgrades usually mean re-embedding the corpus and building a
+second index before the new model can serve. EmbedFlow tests whether the
+existing retriever can remain useful during that transition.
+Different representation spaces can still preserve useful retrieval
+neighborhoods. EmbedFlow retrieves a bounded source candidate set, scores those
+candidates with the target model, and fills a persistent target-vector cache in
+the background.
+## Try it
+The deterministic demo needs no paid service or model download. From a source
+checkout, run:
+```bash
+./scripts/run_demo.sh
+```
+Open <http://127.0.0.1:8000/>. The first search can be `COLD` or `PARTIAL`;
+repeated traffic becomes `WARM` as target vectors are materialized.
+## Analyze a migration
+```bash
+embedflow analyze \
+  --documents ./documents.jsonl \
+  --index ./legacy.index \
+  --source-model sentence-transformers/all-MiniLM-L6-v2 \
+  --target-model Qwen/Qwen3-Embedding-0.6B \
+  --probe-queries ./probe_queries.jsonl \
+  --device cuda \
+  --output-dir ./analysis
+```
+The report includes the frozen T2-v1 diagnostic (`SAFE`, `EXPAND`, or
+`UNSAFE_OR_UNCERTAIN`), a recommended initial candidate depth, and ANN health.
+`SAFE` is an empirical deployment signal; validate important migrations on the
+target corpus.
+Start progressive serving with:
+```bash
+embedflow serve --config ./analysis/embedflow.analysis.yaml --device cuda
+```
+## Known migration evidence
+EmbedFlow ships a versioned registry of measured results from the research
+study. Matching model contracts provide useful starting depths and show what
+was observed on earlier corpora; a new corpus still receives its own analysis.
+```bash
+embedflow registry list
+embedflow registry show \
+  --source Qwen/Qwen3-Embedding-4B \
+  --target Qwen/Qwen3-Embedding-8B
+```
+Selected core records (nDCG@10, `G(50)`):
+| Source | Target | Evaluation | `G(50)` | Observed depth |
+| --- | --- | --- | ---: | ---: |
+| MiniLM-L6-v2 | Qwen3-8B | BRIGHT, 413K | 0.03665 | — |
+| Qwen3-0.6B | Qwen3-8B | BRIGHT, 413K | 0.01465 | 200 |
+| Qwen3-4B | Qwen3-8B | BRIGHT, 413K | 0.00347 | 20 |
+| MiniLM-L6-v2 | Qwen3-8B | Natural Questions, 1M | 0.03255 | 500 |
+| Qwen3-4B | Qwen3-8B | Natural Questions, 1M | -0.00043 | 20 |
+See the [registry documentation](https://github.com/arnsri33/embedflow/blob/main/docs/registry.md)
+for matching levels, contract fingerprints, and provenance.
+## Research
+For candidate depth `K`, EmbedFlow measures:
+```text
+G(K) = M_T - M_{T|S_K}
+```
+Lower `G(K)` means the source candidate pool recovers more of native target
+retrieval quality. Containment reports neighborhood overlap separately. The
+study includes 63 development settings, frozen BRIGHT validation, and Natural
+Questions scale experiments through 1M documents.
+Read the [concepts](https://github.com/arnsri33/embedflow/blob/main/docs/concepts.md)
+and [methodology](https://github.com/arnsri33/embedflow/blob/main/docs/methodology.md)
+for definitions and reproduction details.
+## Integrations
+| Backend | Status |
+| --- | --- |
+| FAISS | Supported |
+| Qdrant | Supported |
+See the [FAISS guide](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/faiss.md)
+and [Qdrant guide](https://github.com/arnsri33/embedflow/blob/main/docs/integrations/qdrant.md).
+## CLI
+```bash
+embedflow --help
+embedflow analyze --help
+embedflow serve --config ./embedflow.yaml
+embedflow status --config ./embedflow.yaml
+embedflow registry list
+embedflow economics --corpus-size 1000000000 --docs-per-second 106.98 --gpu-price 3.29
+embedflow doctor --config ./embedflow.yaml
+```
+The [CLI reference](https://github.com/arnsri33/embedflow/blob/main/docs/cli.md)
+and [API reference](https://github.com/arnsri33/embedflow/blob/main/docs/api.md)
+cover the remaining commands and endpoints.
+## Status
+EmbedFlow v0.1.0 is an alpha release for research and early real-world
+testing. T2-v1 is an empirical finite-tail diagnostic, partial rankings can
+differ from fully warm target reranking, and ANN fidelity needs a reference
+comparison to audit.
+## Links
+- [GitHub repository](https://github.com/arnsri33/embedflow)
+- [Documentation](https://github.com/arnsri33/embedflow#readme)
+- [License](https://github.com/arnsri33/embedflow/blob/main/LICENSE)