Merge branch 'main' into reranker_impl

VectorInstitute · Oct 30, 2024 · 9885820 · 9885820
2 parents 3507a0f + be22414
commit 9885820
Show file tree

Hide file tree

Showing 3 changed files with 119 additions and 30 deletions.
diff --git a/README.md b/README.md
@@ -117,9 +117,11 @@ Careful while loading embeddings, it uses the OpenAI API, and hence make sure th
 #### Navigate to the UI on the browser
 
 ```bash
-http://localhost:<frontend_port>
+https://localhost:<frontend_port>
 ```
 
+Note that the URL uses `https`, and hence in the browser you will get a warning about the insecure connection. You can ignore it and proceed.
+
 #### In case, you wish to update frontend dependencies, run the following commands in the `ui` directory:
 
 ```bash

diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -1,7 +1,7 @@
 API Reference
 =============
 
-This section provides detailed information about the API endpoints.
+This section provides detailed information about the API endpoints for the Health Recommendation System.
 
 Health Recommendations
 ----------------------
@@ -21,13 +21,42 @@ Health Recommendations
          "radius": 5000
       }
 
-   :<json string query: The user's health-related query
+   :<json string query: The user's health-related query (required)
    :<json number latitude: Optional latitude for location-based search
    :<json number longitude: Optional longitude for location-based search
-   :<json number radius: Optional search radius in meters (default: 5000)
-   :>json string recommendation: Generated recommendation text
-   :>json array services: List of relevant health services
+   :<json number radius: Optional search radius in meters
+
+   **Response Body**
+
+   .. code-block:: json
+
+      {
+         "message": "Based on your query...",
+         "is_emergency": false,
+         "is_out_of_scope": false,
+         "services": [
+            {
+               "id": "service_id",
+               "name": "Service Name",
+               "description": "Service description",
+               "categories": ["category1", "category2"],
+               "address": "123 Health St",
+               "phone_numbers": [{
+                  "number": "+1-123-456-7890",
+                  "type": "Main"
+               }],
+               "website": "https://example.com",
+               "hours": "Monday-Friday 9AM-5PM"
+            }
+         ],
+         "no_services_found": false
+      }
+
+   :>json string message: Generated recommendation text
    :>json boolean is_emergency: Indicates if the query suggests an emergency
+   :>json boolean is_out_of_scope: Indicates if the query is outside service scope
+   :>json array services: List of relevant health services (optional)
+   :>json boolean no_services_found: Indicates if no matching services were found
    :status 200: Recommendation generated successfully
    :status 422: Invalid request parameters
    :status 500: Server error
@@ -45,8 +74,20 @@ Question Generation
 
       GET /questions?query=mental+health+support&recommendation=Based+on+your+query...
 
-   :query string query: The user's original health query
-   :query string recommendation: The previously generated recommendation
+   :query string query: The user's original health query (required)
+   :query string recommendation: The previously generated recommendation (required)
+
+   **Response Body**
+
+   .. code-block:: json
+
+      {
+         "questions": [
+            "Do you prefer in-person or virtual care?",
+            "What type of mental health support are you looking for?"
+         ]
+      }
+
    :>json array questions: List of generated follow-up questions
    :status 200: Questions generated successfully
    :status 400: Invalid query parameters
@@ -75,13 +116,38 @@ Recommendation Refinement
          "recommendation": "Previous recommendation text..."
       }
 
-   :<json object query: The original query object with search parameters
-   :<json array questions: List of follow-up questions
-   :<json array answers: User's answers to the follow-up questions
-   :<json string recommendation: The previous recommendation
-   :>json string recommendation: Refined recommendation text
-   :>json array services: Updated list of relevant services
+   :<json object query: Query object containing:
+   :<json string query.query: The user's health-related query (required)
+   :<json number query.latitude: Optional latitude for location-based search
+   :<json number query.longitude: Optional longitude for location-based search
+   :<json number query.radius: Optional search radius in meters
+   :<json array questions: List of follow-up questions (required)
+   :<json array answers: User's answers to the follow-up questions (required)
+   :<json string recommendation: The previous recommendation (required)
+
+   **Response Body**
+
+   .. code-block:: json
+
+      {
+         "message": "Based on your preferences...",
+         "is_emergency": false,
+         "is_out_of_scope": false,
+         "services": [
+            {
+               "id": "service_id",
+               "name": "Service Name",
+               "description": "Service description"
+            }
+         ],
+         "no_services_found": false
+      }
+
+   :>json string message: Refined recommendation text
    :>json boolean is_emergency: Updated emergency status
+   :>json boolean is_out_of_scope: Updated scope status
+   :>json array services: Updated list of relevant services (optional)
+   :>json boolean no_services_found: Indicates if no matching services were found
    :status 200: Recommendation refined successfully
    :status 422: Invalid request data
    :status 500: Server error
@@ -93,31 +159,42 @@ Service Information
 
    Retrieve all available health services from the database.
 
-   :>json array services: List of all health services with details:
+   **Response Body**
 
    .. code-block:: json
 
-      [{
-         "id": "service_id",
-         "name": "Service Name",
-         "description": "Service description",
-         "categories": ["category1", "category2"],
-         "address": "123 Health St",
-         "phone_numbers": [{
-            "number": "+1-123-456-7890",
-            "type": "Main"
-         }],
-         "website": "https://example.com",
-         "hours": "Monday-Friday 9AM-5PM"
-      }]
-
+      [
+         {
+            "id": "service_id",
+            "name": "Service Name",
+            "description": "Service description",
+            "categories": ["category1", "category2"],
+            "address": "123 Health St",
+            "phone_numbers": [{
+               "number": "+1-123-456-7890",
+               "type": "Main"
+            }],
+            "website": "https://example.com",
+            "hours": "Monday-Friday 9AM-5PM"
+         }
+      ]
+
+   :>json array services: List of all health services
    :status 200: Services retrieved successfully
    :status 500: Server error
 
 .. http:get:: /services/count
 
    Get the total number of available health services.
 
+   **Response Body**
+
+   .. code-block:: json
+
+      {
+         "count": 150
+      }
+
    :>json integer count: Total number of services in the database
    :status 200: Count retrieved successfully
    :status 500: Server error
@@ -132,3 +209,11 @@ All endpoints may return the following error responses:
    {
       "detail": "Error message describing what went wrong"
    }
+
+Common HTTP Status Codes
+------------------------
+
+- ``200 OK``: Request successful
+- ``400 Bad Request``: Invalid parameters
+- ``422 Unprocessable Entity``: Invalid request body
+- ``500 Internal Server Error``: Server-side error
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -125,9 +125,11 @@ Careful while loading embeddings, it uses the OpenAI API, and hence make sure th
 #### Navigate to the UI on the browser
 
 ```bash
-http://localhost:<frontend_port>
+https://localhost:<frontend_port>
 ```
 
+Note that the URL uses `https`, and hence in the browser you will get a warning about the insecure connection. You can ignore it and proceed.
+
 #### In case, you wish to update frontend dependencies, run the following commands in the `ui` directory:
 
 ```bash