From 8171235f3528cc1256db94b7207d4c743f14ee48 Mon Sep 17 00:00:00 2001 From: Saifeddine ALOUI Date: Fri, 24 Jan 2025 13:37:43 +0100 Subject: [PATCH] Added docstrings to lightrag_server.py Added docstrings to lightrag_server.py --- lightrag/api/lightrag_server.py | 91 ++++++++++++++++++++++++++++++++- 1 file changed, 89 insertions(+), 2 deletions(-) diff --git a/lightrag/api/lightrag_server.py b/lightrag/api/lightrag_server.py index ffa65464..6da0a283 100644 --- a/lightrag/api/lightrag_server.py +++ b/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"""