ci: pre-build FAISS indices in Docker image to fix ~60 min graph init

Graph initialisation during the docker-eval CI job was taking ~60 minutes
because all 6 FAISS vector indices were rebuilt from scratch at container
startup on every run (HuggingFace CPU inference over the full corpus, or
Google Gemini embedding API exhausting its quota and retrying with 60 s
minimum backoff).

Root cause:
- HybridRetrieverChain.create_hybrid_retriever() takes the slow embed_docs()
  path when faiss_db/<name> does not exist on disk.
- The faiss_data named volume is empty on every CI run (docker compose down
  --volumes is called between jobs), so the indices are never reused.

Fix:
- Add backend/scripts/build_faiss.py: runs RetrieverTools.initialize() with
  EMBEDDINGS_TYPE=HF, FAST_MODE=true, and contextual_rerank=False at Docker
  build time, saving all 6 FAISS indices into the image layer.
- Add a RUN step in the Dockerfile that calls the script after the dataset
  is downloaded. Docker layer caching means the step is skipped on re-runs
  where neither source nor data changed.
- Set ENV EMBEDDINGS_TYPE=HF / HF_EMBEDDINGS=thenlper/gte-large as container
  defaults so runtime matches the pre-built indices (override in .env or via
  docker run -e if a different model is needed).
- Add contextual_rerank: bool = True param to RetrieverTools.initialize() so
  the build script can skip loading the cross-encoder model, keeping the
  Docker build dependency-light.

On first CI run with an empty faiss_data volume Docker copies the pre-built
indices from the image into the volume automatically, so the container finds
faiss_db/<name> at startup and takes the load_db() path instead.  Graph init
drops from ~60 min to a few seconds.

Note: ensure backend/.env (or ci-secret.yaml) sets EMBEDDINGS_TYPE=HF to
match the pre-built indices; using a different model at runtime causes a
vector dimension mismatch.

Signed-off-by: Jack Luar <jluar@precisioninno.com>

Author: luarss

backend/Dockerfile

@@ -27,6 +27,23 @@ RUN git clone https://huggingface.co/datasets/The-OpenROAD-Project/ORAssistant_R
     mv ORAssistant_RAG_Dataset/* data/ && \
     rm -rf ORAssistant_RAG_Dataset
 
+# Build FAISS indices into the image using HuggingFace embeddings (no API quota).
+# At container startup HybridRetrieverChain detects faiss_db/ and loads from disk,
+# reducing graph init from ~60 min to a few seconds.
+# Override these ARGs to build with a different model when needed.
+ARG BUILD_EMBEDDINGS_TYPE=HF
+ARG BUILD_HF_MODEL=thenlper/gte-large
+RUN PYTHONPATH=/ORAssistant-backend \
+    EMBEDDINGS_TYPE=${BUILD_EMBEDDINGS_TYPE} \
+    HF_EMBEDDINGS=${BUILD_HF_MODEL} \
+    FAST_MODE=true \
+    uv run python scripts/build_faiss.py
+
+# Set HF as the default embedding backend so runtime matches the pre-built indices.
+# Override at container runtime (docker run -e / docker-compose environment) if needed.
+ENV EMBEDDINGS_TYPE=HF
+ENV HF_EMBEDDINGS=thenlper/gte-large
+
 EXPOSE 8000
 
 CMD ["uv", "run", "uvicorn", "src.api.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

backend/scripts/build_faiss.py

@@ -0,0 +1,52 @@
+"""
+Pre-build FAISS indices for all retriever chains at Docker image build time.
+
+Run from /ORAssistant-backend (the WORKDIR in the Dockerfile) so that data/ is
+reachable via relative paths.  Uses HuggingFace embeddings by default so no
+external API key or network quota is required during docker build.
+
+The saved indices land in faiss_db/ inside the image.  At container startup,
+HybridRetrieverChain.create_hybrid_retriever() detects existing directories and
+takes the load_db() path instead of re-embedding, dropping init time from ~60 min
+to a few seconds.
+
+EMBEDDINGS_TYPE and HF_EMBEDDINGS are read from the environment so the Dockerfile
+ARG values propagate through cleanly.
+"""
+
+import os
+import sys
+import logging
+
+logging.basicConfig(level="INFO", format="%(levelname)s %(message)s")
+
+if not os.path.isdir("data"):
+    sys.exit("ERROR: run from backend directory — data/ not found")
+
+embeddings_type = os.environ.get("EMBEDDINGS_TYPE", "HF")
+hf_embeddings = os.environ.get("HF_EMBEDDINGS", "thenlper/gte-large")
+fast_mode = os.environ.get("FAST_MODE", "true").lower() == "true"
+
+if embeddings_type != "HF":
+    sys.exit(
+        f"ERROR: build_faiss.py only supports EMBEDDINGS_TYPE=HF, got '{embeddings_type}'"
+    )
+
+embeddings_config = {"type": embeddings_type, "name": hf_embeddings}
+
+logging.info("Pre-building FAISS indices")
+logging.info("  model     : %s", hf_embeddings)
+logging.info("  fast_mode : %s", fast_mode)
+
+from src.agents.retriever_tools import RetrieverTools
+
+tools = RetrieverTools()
+tools.initialize(
+    embeddings_config=embeddings_config,
+    reranking_model_name="",
+    use_cuda=False,
+    fast_mode=fast_mode,
+    contextual_rerank=False,
+)
+
+logging.info("FAISS pre-build complete")

backend/src/agents/retriever_tools.py

@@ -45,6 +45,7 @@ def initialize(
         reranking_model_name: str,
         use_cuda: bool = False,
         fast_mode: bool = False,
+        contextual_rerank: bool = True,
     ) -> None:
         markdown_docs_map = {
             "general": [
@@ -97,7 +98,7 @@ def initialize(
             else markdown_docs_map["general"],
             other_docs_path=[] if fast_mode else ["./data/pdf"],
             weights=[0.6, 0.2, 0.2],
-            contextual_rerank=True,
+            contextual_rerank=contextual_rerank,
             search_k=search_k,
             chunk_size=chunk_size,
         )
@@ -112,7 +113,7 @@ def initialize(
             if fast_mode
             else markdown_docs_map["install"],
             weights=[0.6, 0.2, 0.2],
-            contextual_rerank=True,
+            contextual_rerank=contextual_rerank,
             search_k=search_k,
             chunk_size=chunk_size,
         )
@@ -128,7 +129,7 @@ def initialize(
             else markdown_docs_map["commands"],
             other_docs_path=[] if fast_mode else ["./data/pdf"],
             weights=[0.6, 0.2, 0.2],
-            contextual_rerank=True,
+            contextual_rerank=contextual_rerank,
             search_k=search_k,
             chunk_size=chunk_size,
         )
@@ -143,7 +144,7 @@ def initialize(
             if fast_mode
             else ["./data/html/yosys_docs"],
             weights=[0.6, 0.2, 0.2],
-            contextual_rerank=True,
+            contextual_rerank=contextual_rerank,
             search_k=search_k,
             chunk_size=chunk_size,
         )
@@ -158,7 +159,7 @@ def initialize(
             if fast_mode
             else ["./data/html/klayout_docs"],
             weights=[0.6, 0.2, 0.2],
-            contextual_rerank=True,
+            contextual_rerank=contextual_rerank,
             search_k=search_k,
             chunk_size=chunk_size,
         )
@@ -173,7 +174,7 @@ def initialize(
             if fast_mode
             else markdown_docs_map["errinfo"],
             weights=[0.6, 0.2, 0.2],
-            contextual_rerank=True,
+            contextual_rerank=contextual_rerank,
             search_k=search_k,
             chunk_size=chunk_size,
         )