UI

Author: Ariel Vernaza

.gitignore

@@ -59,3 +59,8 @@ logs/
 
 # Docker local (optional; uncomment if you want to ignore)
 # docker-compose.override.yml
+
+# Frontend (built in Docker; no local node)
+frontend/node_modules
+frontend/dist
+frontend/package-lock.json

Dockerfile

@@ -6,18 +6,14 @@ FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS builder
 
 WORKDIR /app
 
-# Set to 1 to install Sentence Transformers in the image (large: ~2GB+ for torch). Default 0 = small image, use cohere:// for ingest-pdf.
-ARG INSTALL_TRANSFORMER=0
-# Set to 1 to add Image embedder (CLIP/ViT). Requires INSTALL_TRANSFORMER or separate install.
+# Set to 1 to add Image embedder (CLIP/ViT). Default 0 = no image embedder.
 ARG INSTALL_EMBEDDING_EXTRAS=0
 
-# Install deps from lockfile (reproducible). PDF extra for POST /libraries/{id}/ingest-pdf.
+# Install deps: pdf (ingest-pdf) + embedding-transformer (Sentence Transformers) so UI works with Cohere or Transformer.
 COPY pyproject.toml uv.lock ./
 COPY app ./app
-RUN uv sync --frozen --no-dev --extra pdf
+RUN uv sync --frozen --no-dev --extra pdf --extra embedding-transformer
 
-# Optional: Sentence Transformers (torch) for embedding_transformer:// without Cohere. Build with: --build-arg INSTALL_TRANSFORMER=1
-RUN if [ "$INSTALL_TRANSFORMER" = "1" ]; then uv sync --no-dev --extra embedding-transformer; fi
 # Optional: Image embedder (CLIP/ViT)
 RUN if [ "$INSTALL_EMBEDDING_EXTRAS" = "1" ]; then uv sync --no-dev --extra embedding-image; fi
 

README.md

@@ -415,11 +415,14 @@ The project is **container-first** and uses **Compose** to build and run (Docker
 From the project root (use `podman` or `docker` as you have):
 
 ```bash
-# Start (builds the image if needed and runs the service)
+# Start API + UI (builds images if needed; nothing runs on the host except containers)
 podman compose up
 # or: docker compose up
 ```
 
+- **API:** http://localhost:8000 — **UI:** http://localhost:3000  
+The UI (React) runs in its own container and shows the full pipeline: create library → ingest PDF → build index → search by text. Styling is inspired by Qdrant. The UI is built and served from Docker; no local Node/npm required.
+
 In **another terminal** test the API:
 
 ```bash
@@ -454,7 +457,7 @@ podman build --target test -t vector-db-api-test .
 podman run --rm vector-db-api-test
 ```
 
-The **default API image** includes only the `pdf` extra (small image). Use `embedder=cohere://` for ingest-pdf (set `COHERE_API_KEY` in `.env`). To include **Sentence Transformers** in the API image (larger, ~2GB+ for torch): `podman build --build-arg INSTALL_TRANSFORMER=1 -t vector-db-api .`. To add the **Image embedder**: `--build-arg INSTALL_EMBEDDING_EXTRAS=1`.
+The **default API image** includes the `pdf` and **embedding-transformer** extras (pypdf + Sentence Transformers), so the UI can use Cohere or Sentence Transformers for ingest and search. Image is larger (~2GB for torch). Optional: add Image embedder with `--build-arg INSTALL_EMBEDDING_EXTRAS=1`.
 
 ### Local development (optional)
 
@@ -490,6 +493,7 @@ The API is REST-style. All IDs are UUIDs. Base URL when running locally: `http:/
 | DELETE | `/libraries/{library_id}/documents/{document_id}/chunks/{chunk_id}` | Delete chunk |
 | POST   | `/libraries/{library_id}/index` | Build or rebuild vector index |
 | POST   | `/libraries/{library_id}/search` | k-NN search by embedding |
+| POST   | `/libraries/{library_id}/search/by-query` | k-NN search by text (server embeds query) |
 
 ### Status codes
 

app/api/schemas.py

@@ -71,10 +71,12 @@ class SearchRequest(BaseModel):
 
 
 class SearchResultItem(BaseModel):
-    """One nearest-neighbor result: chunk id and L2 distance to the query."""
+    """One nearest-neighbor result: chunk id, distance, and optional chunk text/name (for by-query)."""
 
     chunk_id: UUID = Field(..., description="Chunk UUID.")
     distance: float = Field(..., description="L2 (Euclidean) distance to the query vector.")
+    text: str | None = Field(default=None, description="Chunk text (included by search/by-query).")
+    name: str | None = Field(default=None, description="Chunk name (included by search/by-query).")
 
 
 class SearchResponse(BaseModel):
@@ -85,6 +87,17 @@ class SearchResponse(BaseModel):
     )
 
 
+class SearchByQueryRequest(BaseModel):
+    """Request body for POST /libraries/{id}/search-by-query. Text query; server embeds it then runs k-NN."""
+
+    query: str = Field(..., min_length=1, description="Search query text.")
+    k: int = Field(default=5, ge=1, le=100, description="Number of nearest neighbors to return.")
+    embedder: str = Field(
+        default="cohere://",
+        description="Embedder URI (must match the one used when indexing).",
+    )
+
+
 class IngestPdfResponse(BaseModel):
     """Response for POST /libraries/{id}/ingest-pdf. Created document and chunks."""
 

app/api/search.py

@@ -9,10 +9,16 @@
 
 from uuid import UUID
 
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter, Depends, HTTPException, status
 
 from app.api.deps import AppServices, get_services
-from app.api.schemas import SearchRequest, SearchResponse, SearchResultItem
+from app.api.schemas import (
+    SearchByQueryRequest,
+    SearchRequest,
+    SearchResponse,
+    SearchResultItem,
+)
+from app.core.embedding.registry import get_embedder
 
 router = APIRouter(prefix="/libraries/{library_id}/search", tags=["search"])
 
@@ -29,3 +35,31 @@ def search(
     return SearchResponse(
         results=[SearchResultItem(chunk_id=uid, distance=dist) for uid, dist in results],
     )
+
+
+@router.post("/by-query", response_model=SearchResponse)
+def search_by_query(
+    library_id: UUID,
+    body: SearchByQueryRequest,
+    services: AppServices = Depends(get_services),
+) -> SearchResponse:
+    """Run k-NN search by text: embed the query, return k nearest chunks with text/name for display."""
+    try:
+        embedder = get_embedder(body.embedder)
+        query_embedding = embedder.embed_queries([body.query])[0]
+    except ValueError as e:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(e)) from e
+    with services.lock.read_lock():
+        results = services.search.search(library_id, query_embedding, body.k)
+        out = []
+        for chunk_id, dist in results:
+            chunk = services.chunk.get(chunk_id)
+            out.append(
+                SearchResultItem(
+                    chunk_id=chunk_id,
+                    distance=dist,
+                    text=chunk.text,
+                    name=chunk.name,
+                )
+            )
+    return SearchResponse(results=out)

app/core/embedding/transformer.py

@@ -46,14 +46,14 @@ def __init__(
     def _get_model(self) -> object:
         """Load model on first use to avoid startup cost when embedder is not used."""
         if self._model is None:
-            # Use HF token from env so Hub uses it (avoids "unauthenticated requests" warning)
+            # Use HF token from env if valid; invalid token must not break the flow (fall back to unauthenticated).
             hf_token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
             if hf_token:
                 try:
                     from huggingface_hub import login
 
                     login(token=hf_token)
-                except ImportError:
+                except Exception:
                     pass
             try:
                 from transformers.utils import logging as tf_logging
@@ -64,7 +64,16 @@ def _get_model(self) -> object:
             SentenceTransformer, _ = _lazy_import()
             # Suppress LOAD REPORT and other loading output (logging + print)
             with redirect_stdout(io.StringIO()), redirect_stderr(io.StringIO()):
-                self._model = SentenceTransformer(self._model_name, device=self._device)
+                try:
+                    self._model = SentenceTransformer(self._model_name, device=self._device)
+                except Exception as e:
+                    err_msg = str(e).lower()
+                    if "invalid" in err_msg and "token" in err_msg:
+                        os.environ.pop("HF_TOKEN", None)
+                        os.environ.pop("HUGGING_FACE_HUB_TOKEN", None)
+                        self._model = SentenceTransformer(self._model_name, device=self._device)
+                    else:
+                        raise
         return self._model
 
     @property

app/main.py

@@ -8,6 +8,7 @@
 """
 
 from fastapi import FastAPI, Request, status
+from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import JSONResponse
 
 from app.api import (
@@ -29,6 +30,14 @@
     version="0.1.0",
 )
 
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=False,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
 app.include_router(libraries_router)
 app.include_router(documents_router)
 app.include_router(chunks_router)

docker-compose.yml

@@ -1,8 +1,7 @@
-# Run the Vector DB API in an isolated container.
-# Use: docker compose up  OR  podman compose up
+# Run the Vector DB API and UI in containers. Nothing runs on the host.
+# Use: podman compose up  OR  docker compose up
 
-# Default API image is small (pdf only). For ingest-pdf use embedder=cohere:// and COHERE_API_KEY.
-# To include Sentence Transformers (larger image): podman compose build --build-arg INSTALL_TRANSFORMER=1
+# Default API image includes pdf + Sentence Transformers (Cohere and Transformer work in UI).
 services:
   api:
     build: .
@@ -23,6 +22,20 @@ services:
       retries: 3
       start_period: 5s
 
+  ui:
+    build:
+      context: ./frontend
+      dockerfile: Dockerfile
+      args:
+        VITE_API_URL: ${VITE_API_URL:-http://localhost:8000}
+    image: vector-db-ui:latest
+    container_name: vector-db-ui
+    ports:
+      - "3000:80"
+    depends_on:
+      api:
+        condition: service_healthy
+
   # Lint (Ruff) and tests using the test image. Mounts source so you lint/tests current code.
   # Build: docker compose build lint   OR  podman compose build lint
   # Lint:  docker compose run --rm lint   OR  podman compose run --rm lint

frontend/.dockerignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+.git
+*.log
+.env*
+.DS_Store

frontend/Dockerfile

@@ -0,0 +1,23 @@
+# Stage 1: build React app (runs only inside Docker, never on host)
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+
+# API URL the browser will use (default: same host, API on port 8000)
+ARG VITE_API_URL=http://localhost:8000
+ENV VITE_API_URL=$VITE_API_URL
+
+COPY package.json ./
+RUN npm install
+
+COPY . .
+RUN npm run build
+
+# Stage 2: serve static files with nginx
+FROM nginx:alpine
+
+RUN rm /usr/share/nginx/html/* || true
+COPY --from=builder /app/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]