From b7c78177e9d02714a46c328ca99f8820dcb27b18 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 1 Mar 2026 20:46:13 +0000 Subject: [PATCH] docs(similarity): add API documentation and fix template accessibility Co-authored-by: christianlouis <361235+christianlouis@users.noreply.github.com> --- docs/API.md | 44 +++++++++++++++++++++++++++++ frontend/templates/file_detail.html | 17 ++++++----- 2 files changed, 54 insertions(+), 7 deletions(-) diff --git a/docs/API.md b/docs/API.md index 9309aae2..d0f22bdd 100644 --- a/docs/API.md +++ b/docs/API.md @@ -666,6 +666,50 @@ curl -OJ "http:///api/files/123/download?version=original" - `404`: File not found in database or on disk - `400`: Invalid `version` parameter (must be `processed` or `original`) +### Similar Documents + +**GET** `/api/files/{file_id}/similar` + +Find documents similar to the specified file using text embeddings and cosine similarity. Similarity scores range from 0 (completely different) to 1 (identical content). Embeddings are generated from OCR-extracted text and cached for subsequent requests. + +**Parameters**: +- `limit` (optional, default: `5`, max: `20`): Maximum number of similar documents to return +- `threshold` (optional, default: `0.3`, range: `0.0–1.0`): Minimum similarity score to include + +**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 +} +``` + +**Example**: +```bash +# Find top 5 similar documents +curl "http:///api/files/42/similar" + +# Find top 10 documents with at least 50% similarity +curl "http:///api/files/42/similar?limit=10&threshold=0.5" +``` + +**Error Responses**: +- `404`: File not found +- `422`: Invalid query parameters (limit or threshold out of range) +- `500`: Embedding generation failed + +> **Note:** Documents without OCR text are excluded from similarity comparisons. The response includes a `message` field when the target file has no OCR text available. + ### Batch Processing **POST** `/api/processall` diff --git a/frontend/templates/file_detail.html b/frontend/templates/file_detail.html index 8d0e99ff..e57cd92d 100644 --- a/frontend/templates/file_detail.html +++ b/frontend/templates/file_detail.html @@ -981,32 +981,35 @@ } // Build the results HTML - let html = '
'; + let html = '
'; for (const doc of data.similar_documents) { const scorePercent = Math.round(doc.similarity_score * 100); const title = doc.document_title || doc.original_filename || 'Untitled'; const filename = doc.original_filename || 'Unknown'; const createdAt = doc.created_at ? new Date(doc.created_at).toLocaleDateString() : ''; + const scoreLabel = scorePercent >= 80 ? 'High' : scorePercent >= 50 ? 'Medium' : 'Low'; html += ` - -