Embedded Qdrant vector store (no external cluster)

.dockerignore

@@ -19,13 +19,16 @@ backend/.venv/
 .ruff_cache/
 
 # Heavy data NOT needed at runtime (offline ingestion inputs + eval outputs).
-# data/duckdb/ and data/bm25_index.pkl are intentionally NOT ignored — the
-# runtime needs them and the Dockerfile COPYs them explicitly.
+# data/duckdb/, data/bm25_index.pkl, and data/qdrant/ (the embedded vector store)
+# are intentionally NOT ignored — the runtime needs them and the Dockerfile COPYs
+# them explicitly.
 data/raw/
 data/processed/
 data/*.json
 data/eval_results_*.json
 data/smoke_results.json
+# The embedded store's runtime lock — never bake it in; Qdrant recreates it.
+data/qdrant/.lock
 
 # Repo meta
 .git/

.gitattributes

@@ -34,3 +34,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 *.duckdb filter=lfs diff=lfs merge=lfs -text
+*.sqlite filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -33,10 +33,14 @@ WORKDIR /app
 COPY --from=builder --chown=appuser:appuser /app/backend /app/backend
 COPY --chown=appuser:appuser data/duckdb /app/data/duckdb
 COPY --chown=appuser:appuser data/bm25_index.pkl /app/data/bm25_index.pkl
+# Embedded Qdrant vector store — baked in like DuckDB/BM25 so the image is fully
+# self-contained (no external cluster to idle-wipe, no QDRANT_URL/KEY secret).
+COPY --chown=appuser:appuser data/qdrant /app/data/qdrant
 
 ENV PATH="/app/backend/.venv/bin:$PATH" \
     PYTHONUNBUFFERED=1 \
     PYTHONIOENCODING=utf-8 \
+    QDRANT_PATH=./data/qdrant \
     PORT=8000
 USER appuser
 EXPOSE 8000

backend/src/finrag/config.py

@@ -11,6 +11,14 @@ class Settings(BaseSettings):
     anthropic_api_key: str | None = None
     gemini_api_key: str | None = None
     cohere_api_key: str
+    # Vector store location. Two mutually exclusive modes:
+    #   • qdrant_path set  → EMBEDDED Qdrant (in-process, on-disk at this path).
+    #     The public deploy uses this: the vector store is baked into the Docker
+    #     image alongside DuckDB + BM25, so there is no external cluster to idle-
+    #     wipe and no QDRANT_URL/KEY secret. Relative paths resolve from REPO_ROOT.
+    #   • qdrant_path empty → REMOTE Qdrant at qdrant_url (local docker-compose in
+    #     dev, or a managed cluster). The original behaviour, unchanged.
+    qdrant_path: str | None = None
     qdrant_url: str = "http://localhost:6333"
     qdrant_api_key: str | None = None
     duckdb_path: str = "./data/duckdb/finrag.duckdb"

backend/src/finrag/ingestion/embed.py

@@ -11,6 +11,7 @@ Idempotent: re-running overwrites existing points by ID (deterministic hash).
 from __future__ import annotations
 
 import json
+import sys
 import time
 from collections.abc import Iterable, Iterator
 from pathlib import Path
@@ -21,7 +22,7 @@ from cohere.errors import TooManyRequestsError
 from qdrant_client import QdrantClient
 from qdrant_client.models import Distance, PointStruct, VectorParams
 
-from finrag.config import settings
+from finrag.config import REPO_ROOT, settings
 from finrag.ingestion.parse import PROCESSED_DIR, Chunk
 
 # ── Constants ─────────────────────────────────────────────────────────────
@@ -48,10 +49,50 @@ COHERE_RETRY_INITIAL_BACKOFF_SECONDS = 30.0
 COHERE_MAX_RETRIES = 5
 
 
+# ── Clients ───────────────────────────────────────────────────────────────
+def make_qdrant_client() -> QdrantClient:
+    """Build the Qdrant client for both ingestion and retrieval.
+
+    Embedded mode (settings.qdrant_path set): an in-process, on-disk Qdrant — no
+    server, nothing external to wipe. This is what the public image ships, with
+    the store baked in next to DuckDB/BM25. Otherwise: a remote client at
+    settings.qdrant_url (dev docker-compose or a managed cluster).
+
+    Note on embedded mode: the on-disk store is locked to a single client per
+    process, so the lru_cached retrieval client (one per FastAPI worker) is the
+    intended access pattern; don't open a second concurrent client on the path.
+    """
+    if settings.qdrant_path:
+        path = Path(settings.qdrant_path)
+        if not path.is_absolute():
+            path = REPO_ROOT / path
+        path.mkdir(parents=True, exist_ok=True)
+        return QdrantClient(path=str(path))
+    return QdrantClient(url=settings.qdrant_url, api_key=settings.qdrant_api_key)
+
+
 # ── Helpers ───────────────────────────────────────────────────────────────
 T = TypeVar("T")
 
 
+def _force_utf8_stdout() -> None:
+    """Make progress output (which uses ↳/⚠ glyphs) safe on any console.
+
+    Windows consoles default to cp1252, which can't encode those characters and
+    raises UnicodeEncodeError mid-run — crashing the upload after the collection
+    is created but before any points land (a silent empty-collection state). The
+    Docker image avoids this via PYTHONIOENCODING=utf-8; this makes a bare local
+    `python -m finrag.ingestion.embed` match it without needing the env var.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(encoding="utf-8")
+            except (ValueError, OSError):  # redirected/non-reconfigurable stream
+                pass
+
+
 def _batched(seq: Iterable[T], n: int) -> Iterator[list[T]]:
     """Yield lists of size `n` from `seq`. Last batch may be shorter."""
     buf: list[T] = []
@@ -149,10 +190,15 @@ def _chunk_to_point(chunk: Chunk, vector: list[float]) -> PointStruct:
 
 
 # ── Core ──────────────────────────────────────────────────────────────────
-def embed_and_upsert(chunks: list[Chunk]) -> int:
-    """Embed all chunks and upsert into Qdrant. Returns count of points written."""
+def embed_and_upsert(chunks: list[Chunk], qdrant: QdrantClient | None = None) -> int:
+    """Embed all chunks and upsert into Qdrant. Returns count of points written.
+
+    Accepts an optional client so the CLI can build one and reuse it for the
+    post-run count — embedded (on-disk) mode locks the store to a single client,
+    so opening a second one would fail.
+    """
     co = cohere.ClientV2(api_key=settings.cohere_api_key)
-    qdrant = QdrantClient(url=settings.qdrant_url, api_key=settings.qdrant_api_key)
+    qdrant = qdrant or make_qdrant_client()
     _ensure_collection(qdrant, COLLECTION_NAME, EMBED_DIM)
 
     qdrant_buf: list[PointStruct] = []
@@ -191,20 +237,24 @@ def embed_and_upsert(chunks: list[Chunk]) -> int:
 
 # ── CLI ───────────────────────────────────────────────────────────────────
 def main() -> None:
+    _force_utf8_stdout()
     chunks = _read_all_chunks(PROCESSED_DIR)
     print(f"Loaded {len(chunks)} chunks from {PROCESSED_DIR}\n")
     if not chunks:
         print("No chunks found. Run `finrag.ingestion.parse` first.")
         return
 
-    written = embed_and_upsert(chunks)
+    qdrant = make_qdrant_client()
+    written = embed_and_upsert(chunks, qdrant=qdrant)
 
-    # Verify final state via Qdrant's own count
-    qdrant = QdrantClient(url=settings.qdrant_url, api_key=settings.qdrant_api_key)
+    # Verify final state via Qdrant's own count (reusing the same client, so
+    # embedded-mode's single-client lock isn't violated).
     info = qdrant.get_collection(COLLECTION_NAME)
+    target = "embedded " + str(settings.qdrant_path) if settings.qdrant_path else settings.qdrant_url
     print(
         f"\nDone. {written} points written this run. "
-        f"Collection '{COLLECTION_NAME}' contains {info.points_count} total."
+        f"Collection '{COLLECTION_NAME}' contains {info.points_count} total "
+        f"({target})."
     )
 
 

backend/src/finrag/retrieval/vector.py

@@ -20,7 +20,7 @@ from qdrant_client.models import (
 )
 
 from finrag.config import settings
-from finrag.ingestion.embed import COHERE_MODEL, COLLECTION_NAME
+from finrag.ingestion.embed import COHERE_MODEL, COLLECTION_NAME, make_qdrant_client
 
 
 # ── Public response model ─────────────────────────────────────────────────
@@ -55,10 +55,10 @@ def get_cohere_client() -> cohere.ClientV2:
 
 @lru_cache(maxsize=1)
 def get_qdrant_client() -> QdrantClient:
-    return QdrantClient(
-        url=settings.qdrant_url,
-        api_key=settings.qdrant_api_key,
-    )
+    # Embedded (on-disk) or remote, decided by settings.qdrant_path — see
+    # make_qdrant_client. lru_cache makes this the single client per worker that
+    # embedded mode requires.
+    return make_qdrant_client()
 
 
 # ── Query embedding ───────────────────────────────────────────────────────

data/qdrant/collection/finrag_chunks/storage.sqlite

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2e17a57ab1ede9a19ed389e0878ea1b011ba1c15b30676e2a563ac2b3493786e
+size 47828992

data/qdrant/meta.json

@@ -0,0 +1 @@
+{"collections": {"finrag_chunks": {"vectors": {"size": 1024, "distance": "Cosine", "hnsw_config": null, "quantization_config": null, "on_disk": null, "datatype": null, "multivector_config": null}, "shard_number": null, "sharding_method": null, "replication_factor": null, "write_consistency_factor": null, "on_disk_payload": null, "hnsw_config": null, "wal_config": null, "optimizers_config": null, "quantization_config": null, "sparse_vectors": null, "strict_mode_config": null, "metadata": null}}, "aliases": {}}