Add targeted comments explaining non-obvious behaviour

- embedder.py: lazy model load rationale, RGB conversion, shared vector space
- main.py: why vec appears twice, ::vector cast, 1-distance score formula
- main_oracle.py: why array.array("f") is required instead of plain list
- main_oracle_indb.py: no embedder import — embedding done inside Oracle SQL
- index_images_oracle.py: same array.array requirement on indexing path

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

oravector-demo/backend/embedder.py

@@ -4,14 +4,19 @@ from PIL import Image
 _model = None
 
 def _get_model():
+    # Lazy load: the CLIP model is ~600 MB and takes several seconds to initialise.
+    # Loading on first call avoids the cost at import time and during indexing warmup.
     global _model
     if _model is None:
         _model = SentenceTransformer("clip-ViT-B-32")
     return _model
 
 def embed_image(path: str) -> list[float]:
+    # CLIP requires RGB — some JPEGs are stored as CMYK or grayscale.
     img = Image.open(path).convert("RGB")
     return _get_model().encode(img).tolist()
 
 def embed_text(text: str) -> list[float]:
+    # Text and images share the same 512-dimensional vector space in CLIP,
+    # so the returned vector is directly comparable to image embeddings.
     return _get_model().encode(text).tolist()

oravector-demo/backend/index_images_oracle.py

@@ -53,6 +53,7 @@ def main():
         if cur.fetchone():
             print(f"[{i}/{len(files)}] Skipping {filename} (already indexed)")
             continue
+        # oracledb requires array.array("f") for VECTOR(512, FLOAT32) — plain list is rejected.
         embedding = array.array("f", embed_image(filepath))
         cur.execute(INSERT, (filename, filepath, embedding))
         conn.commit()

oravector-demo/backend/main_oracle.py

@@ -20,6 +20,8 @@ app.mount("/ui", StaticFiles(directory=os.path.abspath(FRONTEND_DIR), html=True)
 
 @app.get("/search")
 def search(q: str = Query(...), limit: int = Query(12)):
+    # oracledb rejects a plain Python list for a VECTOR column.
+    # array.array("f") produces a typed 32-bit float buffer that matches VECTOR(512, FLOAT32).
     vec = array.array("f", embed_text(q))
     conn = get_connection()
     cur = conn.cursor()

oravector-demo/backend/main_oracle_indb.py

@@ -1,3 +1,5 @@
+# No embedder import — text embedding happens inside Oracle via VECTOR_EMBEDDING(CLIP_TXT).
+# The only value Python passes to the database is the raw query string (:q).
 import os
 from fastapi import FastAPI, Query
 from fastapi.middleware.cors import CORSMiddleware

pgvector-demo/backend/embedder.py

@@ -4,14 +4,19 @@ from PIL import Image
 _model = None
 
 def _get_model():
+    # Lazy load: the CLIP model is ~600 MB and takes several seconds to initialise.
+    # Loading on first call avoids the cost at import time and during indexing warmup.
     global _model
     if _model is None:
         _model = SentenceTransformer("clip-ViT-B-32")
     return _model
 
 def embed_image(path: str) -> list[float]:
+    # CLIP requires RGB — some JPEGs are stored as CMYK or grayscale.
     img = Image.open(path).convert("RGB")
     return _get_model().encode(img).tolist()
 
 def embed_text(text: str) -> list[float]:
+    # Text and images share the same 512-dimensional vector space in CLIP,
+    # so the returned vector is directly comparable to image embeddings.
     return _get_model().encode(text).tolist()

pgvector-demo/backend/main.py

@@ -29,6 +29,9 @@ def search(q: str = Query(...), limit: int = Query(12)):
         ORDER BY embedding <=> %s::vector
         LIMIT %s
         """,
+        # vec appears twice: once for ORDER BY (uses HNSW index), once for the score column.
+        # ::vector cast is required — psycopg2 passes the list as text without it.
+        # 1 - distance converts cosine distance (0=identical) to similarity (1=identical).
         (vec, vec, limit),
     )
     rows = cur.fetchall()