Score and return only documents provided

README.md

@@ -102,6 +102,10 @@ The return value is a JSON representation of the `top_k` most similar documents
 
 If `"text"` is not provided, we assume `"uid"`s are valid PMIDs and fetch the title and abstract text before embedding, indexing and searching.
 
+- Notes on optional parameters
+  - `top_k`: A positive integer (default is 10) that limits the search results to this many of the most similar neighbours (articles)
+  - `docs_only`: A boolean (default is false) that instructs the service to return scores for the provided `documents`. If true, top_k is disregarded.
+
 ### Running via Docker
 
 #### Setup

semantic_search/main.py

@@ -132,7 +132,7 @@ def index(request: Request):
 @app.post("/search", tags=["Search"], response_model=List[TopMatch])
 async def search(search: Search):
     """Returns the `top_k` most similar documents to `query` from the provided list of `documents`
-    and the index.
+    and the index. When docs_only is True, returns all `documents` provided, and disregards `top_k`.
     """
     ids = [int(doc.uid) for doc in search.documents]
     texts = [document.text for document in search.documents]
@@ -167,7 +167,7 @@ async def search(search: Search):
     # Can't search for more items than exist in the index
     top_k = min(num_indexed, search.top_k)
 
-    if search.use_docs:
+    if search.docs_only:
         top_k = num_indexed
 
     # Perform the search
@@ -177,7 +177,7 @@ async def search(search: Search):
     top_k_scores = top_k_scores.reshape(-1).tolist()
 
     # Pick out results for the incoming ids in search.documents
-    if search.use_docs:
+    if search.docs_only:
         documents_positions = [top_k_indicies.index(id) for id in ids]
         top_k_indicies = ids
         top_k_scores = [top_k_scores[position] for position in documents_positions]

semantic_search/schemas.py

@@ -20,7 +20,7 @@ class Search(BaseModel):
     query: Document
     documents: List[Document] = []
     top_k: int = Field(10, gt=0, description="top_k must be greater than 0")
-    use_docs: bool = False
+    docs_only: bool = False
 
     class Config:
         schema_extra = {

tests/conftest.py

@@ -66,7 +66,7 @@ def followup_request_with_test() -> Request:
                 "text": "Members of TGFbeta superfamily are found to play important roles in many cellular...",
             },
         ],
-        "use_docs": True,
+        "docs_only": True,
     }
     # We don't actually test scores, so use a dummy value of -1
     response = [