build_index.py

"""
scripts/build_index.py — Precompute and persist TF-IDF index artifacts.

Run this script before deployment (or during Docker build) so the server starts
instantly without building the index from scratch on first request.

Usage:
    python scripts/build_index.py

Output:
    data/tfidf_vectorizer.pkl
    data/tfidf_matrix.pkl

Design rationale:
    Separating index construction from serving is standard MLOps practice.
    It means:
    1. The server's startup time is O(file read) not O(index build).
    2. The index build can be tested and validated independently.
    3. In production, the build step belongs in CI/CD, not in the serving path.

Interview Q: "What would you do if the catalog updates frequently?"
A: Add this script to a nightly CI job. Rebuild and push the pkl files as artifacts.
   The server picks them up on next restart. For near-realtime updates, switch to
   an online learning approach or a managed vector store.
"""

import sys
import os

# Allow running from project root: `python scripts/build_index.py`
sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))

from app.catalog_loader import load_catalog
from app.retrieval import build_index


def main():
    print("Loading catalog...")
    catalog = load_catalog()
    print(f"  {len(catalog)} items loaded.")

    print("Building TF-IDF index...")
    vectorizer, matrix = build_index(catalog)
    print(f"  Vocabulary size: {len(vectorizer.vocabulary_)}")
    print(f"  Matrix shape: {matrix.shape}")

    print("Index artifacts written to data/")
    print("  data/tfidf_vectorizer.pkl")
    print("  data/tfidf_matrix.pkl")
    print("Done.")


if __name__ == "__main__":
    main()