feat(similarity): add document similarity detection with embeddings and cosine similarity

Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com>

app/api/__init__.py

@@ -19,6 +19,7 @@ from app.api.queue import router as queue_router
 from app.api.saved_searches import router as saved_searches_router
 from app.api.search import router as search_router
 from app.api.settings import router as settings_router
+from app.api.similarity import router as similarity_router
 from app.api.url_upload import router as url_upload_router
 
 # Import all the individual routers
@@ -46,3 +47,4 @@ router.include_router(url_upload_router)
 router.include_router(search_router)
 router.include_router(queue_router)
 router.include_router(saved_searches_router)
+router.include_router(similarity_router)

app/api/similarity.py

@@ -0,0 +1,97 @@
+"""Document similarity API endpoints.
+
+Provides an endpoint to find documents similar to a given file based on
+text embeddings and cosine similarity scoring.
+"""
+
+import logging
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
+from sqlalchemy.orm import Session
+
+from app.auth import require_login
+from app.database import get_db
+from app.models import FileRecord
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+DbSession = Annotated[Session, Depends(get_db)]
+
+
+@router.get("/files/{file_id}/similar")
+@require_login
+def get_similar_documents(
+    request: Request,
+    file_id: int,
+    db: DbSession,
+    limit: int = Query(5, ge=1, le=20, description="Maximum number of similar documents to return"),
+    threshold: float = Query(0.3, ge=0.0, le=1.0, description="Minimum similarity score (0–1)"),
+):
+    """Find documents similar to the specified file.
+
+    Uses text embeddings generated from OCR-extracted text and cosine
+    similarity to rank documents by relevance.  Similarity scores range
+    from 0 (completely different) to 1 (identical content).
+
+    Embeddings are generated on first access and cached for subsequent
+    requests.  Documents without OCR text are excluded.
+
+    Query Parameters:
+        - limit: Maximum results to return (default: 5, max: 20)
+        - threshold: Minimum similarity score to include (default: 0.3)
+
+    Example:
+    ```
+    GET /api/files/42/similar?limit=5&threshold=0.5
+    ```
+
+    Response:
+    ```json
+    {
+      "file_id": 42,
+      "similar_documents": [
+        {
+          "file_id": 15,
+          "original_filename": "Invoice_2026-01.pdf",
+          "document_title": "January Invoice",
+          "similarity_score": 0.8934,
+          "mime_type": "application/pdf",
+          "created_at": "2026-01-15T10:30:00+00:00"
+        }
+      ],
+      "count": 1
+    }
+    ```
+    """
+    # Verify the file exists
+    file_record = db.query(FileRecord).filter(FileRecord.id == file_id).first()
+    if not file_record:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="File not found")
+
+    if not file_record.ocr_text or not file_record.ocr_text.strip():
+        return {
+            "file_id": file_id,
+            "similar_documents": [],
+            "count": 0,
+            "message": "No OCR text available for similarity comparison",
+        }
+
+    try:
+        from app.utils.similarity import find_similar_documents
+
+        similar = find_similar_documents(db, file_id, limit=limit, threshold=threshold)
+
+        return {
+            "file_id": file_id,
+            "similar_documents": similar,
+            "count": len(similar),
+        }
+    except Exception as e:
+        logger.error(f"Error finding similar documents for file {file_id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to compute document similarity",
+        )