Added docstrings to lightrag_server.py

lightrag/api/lightrag_server.py

@@ -814,7 +814,23 @@ def create_app(args):
 
     @app.post("/documents/scan", dependencies=[Depends(optional_api_key)])
     async def scan_for_new_documents():
-        """Manually trigger scanning for new documents"""
+        """
+        Manually trigger scanning for new documents in the directory managed by `doc_manager`.
+    
+        This endpoint facilitates manual initiation of a document scan to identify and index new files.
+        It processes all newly detected files, attempts indexing each file, logs any errors that occur,
+        and returns a summary of the operation.
+    
+        Returns:
+            dict: A dictionary containing:
+                - "status" (str): Indicates success or failure of the scanning process.
+                - "indexed_count" (int): The number of successfully indexed documents.
+                - "total_documents" (int): Total number of documents that have been indexed so far.
+    
+        Raises:
+            HTTPException: If an error occurs during the document scanning process, a 500 status
+                           code is returned with details about the exception.
+        """
         try:
             new_files = doc_manager.scan_directory()
             indexed_count = 0
@@ -836,7 +852,27 @@ def create_app(args):
 
     @app.post("/documents/upload", dependencies=[Depends(optional_api_key)])
     async def upload_to_input_dir(file: UploadFile = File(...)):
-        """Upload a file to the input directory"""
+        """
+        Endpoint for uploading a file to the input directory and indexing it.
+    
+        This API endpoint accepts a file through an HTTP POST request, checks if the 
+        uploaded file is of a supported type, saves it in the specified input directory,
+        indexes it for retrieval, and returns a success status with relevant details.
+    
+        Parameters:
+            file (UploadFile): The file to be uploaded. It must have an allowed extension as per
+                               `doc_manager.supported_extensions`.
+    
+        Returns:
+            dict: A dictionary containing the upload status ("success"), 
+                  a message detailing the operation result, and 
+                  the total number of indexed documents.
+    
+        Raises:
+            HTTPException: If the file type is not supported, it raises a 400 Bad Request error.
+                           If any other exception occurs during the file handling or indexing,
+                           it raises a 500 Internal Server Error with details about the exception.
+        """        
         try:
             if not doc_manager.is_supported_file(file.filename):
                 raise HTTPException(
@@ -863,6 +899,25 @@ def create_app(args):
         "/query", response_model=QueryResponse, dependencies=[Depends(optional_api_key)]
     )
     async def query_text(request: QueryRequest):
+        """
+        Handle a POST request at the /query endpoint to process user queries using RAG capabilities.
+    
+        Parameters:
+            request (QueryRequest): A Pydantic model containing the following fields:
+                - query (str): The text of the user's query.
+                - mode (ModeEnum): Optional. Specifies the mode of retrieval augmentation.
+                - stream (bool): Optional. Determines if the response should be streamed.
+                - only_need_context (bool): Optional. If true, returns only the context without further processing.
+    
+        Returns:
+            QueryResponse: A Pydantic model containing the result of the query processing. 
+                           If a string is returned (e.g., cache hit), it's directly returned.
+                           Otherwise, an async generator may be used to build the response.
+    
+        Raises:
+            HTTPException: Raised when an error occurs during the request handling process,
+                           with status code 500 and detail containing the exception message.
+        """        
         try:
             response = await rag.aquery(
                 request.query,
@@ -894,6 +949,16 @@ def create_app(args):
 
     @app.post("/query/stream", dependencies=[Depends(optional_api_key)])
     async def query_text_stream(request: QueryRequest):
+        """
+        This endpoint performs a retrieval-augmented generation (RAG) query and streams the response.
+
+        Args:
+            request (QueryRequest): The request object containing the query parameters.
+            optional_api_key (Optional[str], optional): An optional API key for authentication. Defaults to None.
+
+        Returns:
+            StreamingResponse: A streaming response containing the RAG query results.
+        """        
         try:
             response = await rag.aquery(  # Use aquery instead of query, and add await
                 request.query,
@@ -943,6 +1008,17 @@ def create_app(args):
         dependencies=[Depends(optional_api_key)],
     )
     async def insert_text(request: InsertTextRequest):
+        """
+        Insert text into the Retrieval-Augmented Generation (RAG) system.
+
+        This endpoint allows you to insert text data into the RAG system for later retrieval and use in generating responses.
+
+        Args:
+            request (InsertTextRequest): The request body containing the text to be inserted.
+
+        Returns:
+            InsertResponse: A response object containing the status of the operation, a message, and the number of documents inserted.
+        """        
         try:
             await rag.ainsert(request.text)
             return InsertResponse(
@@ -1176,6 +1252,15 @@ def create_app(args):
         dependencies=[Depends(optional_api_key)],
     )
     async def clear_documents():
+        """
+        Clear all documents from the LightRAG system.
+
+        This endpoint deletes all text chunks, entities vector database, and relationships vector database,
+        effectively clearing all documents from the LightRAG system.
+
+        Returns:
+            InsertResponse: A response object containing the status, message, and the new document count (0 in this case).
+        """
         try:
             rag.text_chunks = []
             rag.entities_vdb = None
@@ -1188,7 +1273,9 @@ def create_app(args):
         except Exception as e:
             raise HTTPException(status_code=500, detail=str(e))
 
+    # -------------------------------------------------
     # Ollama compatible API endpoints
+    # -------------------------------------------------
     @app.get("/api/version")
     async def get_version():
         """Get Ollama version information"""