feat: Implement new backend service for chat session and history management with database integration, API, and UI updates.

lightrag/api/lightrag_server.py

@@ -52,6 +52,7 @@ from lightrag.api.routers.document_routes import (
 from lightrag.api.routers.query_routes import create_query_routes
 from lightrag.api.routers.graph_routes import create_graph_routes
 from lightrag.api.routers.ollama_api import OllamaAPI
+from lightrag.api.routers.history_routes import router as history_router
 
 from lightrag.utils import logger, set_verbose_debug
 from lightrag.kg.shared_storage import (
@@ -405,6 +406,7 @@ def create_app(args):
     }
 
     app = FastAPI(**app_kwargs)
+    app.include_router(history_router)
 
     # Add custom validation error handler for /query/data endpoint
     @app.exception_handler(RequestValidationError)

lightrag/api/routers/history_routes.py

@@ -0,0 +1,75 @@
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+from typing import List, Optional
+from uuid import UUID
+import sys
+import os
+
+# Ensure service module is in path (similar to query_routes.py)
+project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../../"))
+service_dir = os.path.join(project_root, "service")
+if service_dir not in sys.path:
+    sys.path.append(service_dir)
+
+try:
+    from app.core.database import get_db
+    from app.services.history_manager import HistoryManager
+    from app.models.schemas import SessionResponse, SessionCreate, ChatMessageResponse
+    from app.models.models import User
+except ImportError:
+    # Fallback if service not found (shouldn't happen if setup is correct)
+    get_db = None
+    HistoryManager = None
+    SessionResponse = None
+    SessionCreate = None
+    ChatMessageResponse = None
+    User = None
+
+router = APIRouter()
+
+def check_dependencies():
+    if not HistoryManager:
+        raise HTTPException(status_code=503, detail="History service not available")
+
+@router.get("/sessions", response_model=List[SessionResponse], tags=["History"])
+def list_sessions(
+    skip: int = 0, 
+    limit: int = 20, 
+    db: Session = Depends(get_db)
+):
+    check_dependencies()
+    manager = HistoryManager(db)
+    # For now, get default user or create one
+    user = db.query(User).filter(User.username == "default_user").first()
+    if not user:
+        user = User(username="default_user", email="default@example.com")
+        db.add(user)
+        db.commit()
+        db.refresh(user)
+        
+    sessions = manager.list_sessions(user_id=user.id, skip=skip, limit=limit)
+    return sessions
+
+@router.post("/sessions", response_model=SessionResponse, tags=["History"])
+def create_session(
+    session_in: SessionCreate, 
+    db: Session = Depends(get_db)
+):
+    check_dependencies()
+    manager = HistoryManager(db)
+    user = db.query(User).filter(User.username == "default_user").first()
+    if not user:
+        user = User(username="default_user", email="default@example.com")
+        db.add(user)
+        db.commit()
+    
+    return manager.create_session(user_id=user.id, title=session_in.title)
+
+@router.get("/sessions/{session_id}/history", response_model=List[ChatMessageResponse], tags=["History"])
+def get_session_history(
+    session_id: str, 
+    db: Session = Depends(get_db)
+):
+    check_dependencies()
+    manager = HistoryManager(db)
+    return manager.get_session_history(session_id)

lightrag/api/routers/query_routes.py

@@ -9,6 +9,33 @@ from lightrag.base import QueryParam
 from lightrag.api.utils_api import get_combined_auth_dependency
 from lightrag.utils import logger
 from pydantic import BaseModel, Field, field_validator
+import sys
+import os
+import uuid
+import time
+import json
+
+# Add the project root to sys.path to allow importing 'service'
+# Assuming this file is at lightrag/api/routers/query_routes.py
+# We need to go up 3 levels to get to the root
+project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../../"))
+service_dir = os.path.join(project_root, "service")
+if project_root not in sys.path:
+    sys.path.append(project_root)
+if service_dir not in sys.path:
+    sys.path.append(service_dir)
+
+try:
+    from app.core.database import SessionLocal
+    from app.services.history_manager import HistoryManager
+    from app.models.models import User
+except ImportError as e:
+    # Fallback or handle error if service module is not found
+    print(f"Warning: Could not import service module. History logging will be disabled. Error: {e}")
+    SessionLocal = None
+    HistoryManager = None
+    User = None
+
 
 router = APIRouter(tags=["query"])
 
@@ -110,6 +137,11 @@ class QueryRequest(BaseModel):
         description="If True, enables streaming output for real-time responses. Only affects /query/stream endpoint.",
     )
 
+    session_id: Optional[str] = Field(
+        default=None,
+        description="Session ID for conversation history tracking. If not provided, a new session may be created or it will be treated as a one-off query.",
+    )
+
     @field_validator("query", mode="after")
     @classmethod
     def query_strip_after(cls, query: str) -> str:
@@ -134,7 +166,7 @@ class QueryRequest(BaseModel):
         # Use Pydantic's `.model_dump(exclude_none=True)` to remove None values automatically
         # Exclude API-level parameters that don't belong in QueryParam
         request_data = self.model_dump(
-            exclude_none=True, exclude={"query", "include_chunk_content"}
+            exclude_none=True, exclude={"query", "include_chunk_content", "session_id"}
         )
 
         # Ensure `mode` and `stream` are set explicitly
@@ -445,10 +477,79 @@ def create_query_routes(rag, api_key: Optional[str] = None, top_k: int = 60):
                 references = enriched_references
 
             # Return response with or without references based on request
+            final_response = None
             if request.include_references:
-                return QueryResponse(response=response_content, references=references)
+                final_response = QueryResponse(response=response_content, references=references)
             else:
-                return QueryResponse(response=response_content, references=None)
+                final_response = QueryResponse(response=response_content, references=None)
+
+            # --- LOGGING START ---
+            if SessionLocal and HistoryManager:
+                try:
+                    db = SessionLocal()
+                    manager = HistoryManager(db)
+                    
+                    # 1. Get or Create User (Default)
+                    user = db.query(User).filter(User.username == "default_user").first()
+                    if not user:
+                        user = User(username="default_user", email="default@example.com")
+                        db.add(user)
+                        db.commit()
+                        db.refresh(user)
+                    
+                    # 2. Handle Session
+                    session_uuid = None
+                    if request.session_id:
+                        try:
+                            session_uuid = uuid.UUID(request.session_id)
+                            # Verify session exists
+                            if not manager.get_session(session_uuid):
+                                # If provided ID doesn't exist, create it with that ID if possible or just create new
+                                # For simplicity, let's create a new one if it doesn't exist but we can't force ID easily with current manager
+                                # Let's just create a new session if not found or use the provided one if we trust it.
+                                # Actually, manager.create_session generates ID. 
+                                # Let's just create a new session if the provided one is invalid/not found, 
+                                # OR we can just create a new session if session_id is NOT provided.
+                                # If session_id IS provided, we assume it exists. 
+                                pass
+                        except ValueError:
+                            pass
+                    
+                    if not session_uuid:
+                        # Create new session
+                        session = manager.create_session(user_id=user.id, title=request.query[:50])
+                        session_uuid = session.id
+                    
+                    # 3. Log User Message
+                    manager.save_message(
+                        session_id=session_uuid,
+                        role="user",
+                        content=request.query
+                    )
+                    
+                    # 4. Log Assistant Message
+                    ai_msg = manager.save_message(
+                        session_id=session_uuid,
+                        role="assistant",
+                        content=response_content
+                    )
+                    
+                    # 5. Log Citations
+                    if references:
+                        # Convert references to dict format expected by save_citations
+                        # references is a list of ReferenceItem (pydantic) or dicts?
+                        # In the code above: references = data.get("references", []) which are dicts.
+                        # Then enriched_references are also dicts.
+                        manager.save_citations(ai_msg.id, references)
+                        
+                    db.close()
+                except Exception as log_exc:
+                    print(f"Error logging history: {log_exc}")
+                    # Don't fail the request if logging fails
+            # --- LOGGING END ---
+
+            return final_response
+
         except Exception as e:
             logger.error(f"Error processing query: {str(e)}", exc_info=True)
             raise HTTPException(status_code=500, detail=str(e))
@@ -725,8 +826,74 @@ def create_query_routes(rag, api_key: Optional[str] = None, top_k: int = 60):
 
                     yield f"{json.dumps(complete_response)}\n"
 
+            async def stream_generator_wrapper():
+                full_response_content = []
+                final_references = []
+                
+                async for chunk in stream_generator():
+                    yield chunk
+                    # Accumulate data for logging
+                    try:
+                        data = json.loads(chunk)
+                        if "references" in data:
+                            final_references.extend(data["references"])
+                        if "response" in data:
+                            full_response_content.append(data["response"])
+                    except:
+                        pass
+                
+                # --- LOGGING START ---
+                if SessionLocal and HistoryManager:
+                    try:
+                        db = SessionLocal()
+                        manager = HistoryManager(db)
+                        
+                        # 1. Get or Create User
+                        user = db.query(User).filter(User.username == "default_user").first()
+                        if not user:
+                            user = User(username="default_user", email="default@example.com")
+                            db.add(user)
+                            db.commit()
+                            db.refresh(user)
+                        
+                        # 2. Handle Session
+                        session_uuid = None
+                        if request.session_id:
+                            try:
+                                session_uuid = uuid.UUID(request.session_id)
+                            except ValueError:
+                                pass
+                        
+                        if not session_uuid or not manager.get_session(session_uuid):
+                            session = manager.create_session(user_id=user.id, title=request.query[:50])
+                            session_uuid = session.id
+                        
+                        # 3. Log User Message
+                        manager.save_message(
+                            session_id=session_uuid,
+                            role="user",
+                            content=request.query
+                        )
+                        
+                        # 4. Log Assistant Message
+                        full_content = "".join(full_response_content)
+                        ai_msg = manager.save_message(
+                            session_id=session_uuid,
+                            role="assistant",
+                            content=full_content
+                        )
+                        
+                        # 5. Log Citations
+                        if final_references:
+                            manager.save_citations(ai_msg.id, final_references)
+                            
+                        db.close()
+                    except Exception as log_exc:
+                        print(f"Error logging history (stream): {log_exc}")
+                # --- LOGGING END ---
+
             return StreamingResponse(
-                stream_generator(),
+                stream_generator_wrapper(),
                 media_type="application/x-ndjson",
                 headers={
                     "Cache-Control": "no-cache",

lightrag_webui/.env.development

@@ -1,4 +1,4 @@
 # Development environment configuration
 VITE_BACKEND_URL=http://localhost:9621
 VITE_API_PROXY=true
-VITE_API_ENDPOINTS=/api,/documents,/graphs,/graph,/health,/query,/docs,/redoc,/openapi.json,/login,/auth-status,/static
+VITE_API_ENDPOINTS=/api,/documents,/graphs,/graph,/health,/query,/docs,/redoc,/openapi.json,/login,/auth-status,/static,/sessions

lightrag_webui/.tool-versions

@@ -0,0 +1 @@
+bun 1.2.13

lightrag_webui/package.json

@@ -45,6 +45,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "date-fns": "^4.1.0",
     "graphology": "^0.26.0",
     "graphology-generators": "^0.11.2",
     "graphology-layout": "^0.6.1",

lightrag_webui/src/api/lightrag.ts

@@ -1,8 +1,12 @@
-import axios, { AxiosError } from 'axios'
+import {
-import { backendBaseUrl, popularLabelsDefaultLimit, searchLabelsDefaultLimit } from '@/lib/constants'
+  backendBaseUrl,
+  popularLabelsDefaultLimit,
+  searchLabelsDefaultLimit
+} from '@/lib/constants'
 import { errorMessage } from '@/lib/utils'
-import { useSettingsStore } from '@/stores/settings'
 import { navigationService } from '@/services/navigation'
+import { useSettingsStore } from '@/stores/settings'
+import axios, { AxiosError } from 'axios'
 
 // Types
 export type LightragNodeType = {
@@ -137,6 +141,8 @@ export type QueryRequest = {
   user_prompt?: string
   /** Enable reranking for retrieved text chunks. If True but no rerank model is configured, a warning will be issued. Default is True. */
   enable_rerank?: boolean
+  /** Optional session ID for tracking conversation history on the server. */
+  session_id?: string
 }
 
 export type QueryResponse = {
@@ -288,7 +294,7 @@ const axiosInstance = axios.create({
 // Interceptor: add api key and check authentication
 axiosInstance.interceptors.request.use((config) => {
   const apiKey = useSettingsStore.getState().apiKey
-  const token = localStorage.getItem('LIGHTRAG-API-TOKEN');
+  const token = localStorage.getItem('LIGHTRAG-API-TOKEN')
 
   // Always include token if it exists, regardless of path
   if (token) {
@@ -308,13 +314,13 @@ axiosInstance.interceptors.response.use(
       if (error.response?.status === 401) {
         // For login API, throw error directly
         if (error.config?.url?.includes('/login')) {
-          throw error;
+          throw error
         }
         // For other APIs, navigate to login page
-        navigationService.navigateToLogin();
+        navigationService.navigateToLogin()
 
         // return a reject Promise
-        return Promise.reject(new Error('Authentication required'));
+        return Promise.reject(new Error('Authentication required'))
       }
       throw new Error(
         `${error.response.status} ${error.response.statusText}\n${JSON.stringify(
@@ -332,7 +338,9 @@ export const queryGraphs = async (
   maxDepth: number,
   maxNodes: number
 ): Promise<LightragGraphType> => {
-  const response = await axiosInstance.get(`/graphs?label=${encodeURIComponent(label)}&max_depth=${maxDepth}&max_nodes=${maxNodes}`)
+  const response = await axiosInstance.get(
+    `/graphs?label=${encodeURIComponent(label)}&max_depth=${maxDepth}&max_nodes=${maxNodes}`
+  )
   return response.data
 }
 
@@ -341,13 +349,20 @@ export const getGraphLabels = async (): Promise<string[]> => {
   return response.data
 }
 
-export const getPopularLabels = async (limit: number = popularLabelsDefaultLimit): Promise<string[]> => {
+export const getPopularLabels = async (
+  limit: number = popularLabelsDefaultLimit
+): Promise<string[]> => {
   const response = await axiosInstance.get(`/graph/label/popular?limit=${limit}`)
   return response.data
 }
 
-export const searchLabels = async (query: string, limit: number = searchLabelsDefaultLimit): Promise<string[]> => {
+export const searchLabels = async (
-  const response = await axiosInstance.get(`/graph/label/search?q=${encodeURIComponent(query)}&limit=${limit}`)
+  query: string,
+  limit: number = searchLabelsDefaultLimit
+): Promise<string[]> => {
+  const response = await axiosInstance.get(
+    `/graph/label/search?q=${encodeURIComponent(query)}&limit=${limit}`
+  )
   return response.data
 }
 
@@ -395,85 +410,85 @@ export const queryTextStream = async (
   onChunk: (chunk: string) => void,
   onError?: (error: string) => void
 ) => {
-  const apiKey = useSettingsStore.getState().apiKey;
+  const apiKey = useSettingsStore.getState().apiKey
-  const token = localStorage.getItem('LIGHTRAG-API-TOKEN');
+  const token = localStorage.getItem('LIGHTRAG-API-TOKEN')
   const headers: HeadersInit = {
     'Content-Type': 'application/json',
-    'Accept': 'application/x-ndjson',
+    Accept: 'application/x-ndjson'
-  };
+  }
   if (token) {
-    headers['Authorization'] = `Bearer ${token}`;
+    headers['Authorization'] = `Bearer ${token}`
   }
   if (apiKey) {
-    headers['X-API-Key'] = apiKey;
+    headers['X-API-Key'] = apiKey
   }
 
   try {
     const response = await fetch(`${backendBaseUrl}/query/stream`, {
       method: 'POST',
       headers: headers,
-      body: JSON.stringify(request),
+      body: JSON.stringify(request)
-    });
+    })
 
     if (!response.ok) {
       // Handle 401 Unauthorized error specifically
       if (response.status === 401) {
         // For consistency with axios interceptor, navigate to login page
-        navigationService.navigateToLogin();
+        navigationService.navigateToLogin()
 
         // Create a specific authentication error
-        const authError = new Error('Authentication required');
+        const authError = new Error('Authentication required')
-        throw authError;
+        throw authError
       }
 
       // Handle other common HTTP errors with specific messages
-      let errorBody = 'Unknown error';
+      let errorBody = 'Unknown error'
       try {
-        errorBody = await response.text(); // Try to get error details from body
+        errorBody = await response.text() // Try to get error details from body
-      } catch { /* ignore */ }
+      } catch {
+        /* ignore */
+      }
 
       // Format error message similar to axios interceptor for consistency
-      const url = `${backendBaseUrl}/query/stream`;
+      const url = `${backendBaseUrl}/query/stream`
       throw new Error(
-        `${response.status} ${response.statusText}\n${JSON.stringify(
+        `${response.status} ${response.statusText}\n${JSON.stringify({ error: errorBody })}\n${url}`
-          { error: errorBody }
+      )
-        )}\n${url}`
-      );
     }
 
     if (!response.body) {
-      throw new Error('Response body is null');
+      throw new Error('Response body is null')
     }
 
-    const reader = response.body.getReader();
+    const reader = response.body.getReader()
-    const decoder = new TextDecoder();
+    const decoder = new TextDecoder()
-    let buffer = '';
+    let buffer = ''
 
     while (true) {
-      const { done, value } = await reader.read();
+      const { done, value } = await reader.read()
       if (done) {
-        break; // Stream finished
+        break // Stream finished
       }
 
       // Decode the chunk and add to buffer
-      buffer += decoder.decode(value, { stream: true }); // stream: true handles multi-byte chars split across chunks
+      buffer += decoder.decode(value, { stream: true }) // stream: true handles multi-byte chars split across chunks
 
       // Process complete lines (NDJSON)
-      const lines = buffer.split('\n');
+      const lines = buffer.split('\n')
-      buffer = lines.pop() || ''; // Keep potentially incomplete line in buffer
+      buffer = lines.pop() || '' // Keep potentially incomplete line in buffer
 
       for (const line of lines) {
         if (line.trim()) {
           try {
-            const parsed = JSON.parse(line);
+            const parsed = JSON.parse(line)
             if (parsed.response) {
-              onChunk(parsed.response);
+              onChunk(parsed.response)
             } else if (parsed.error && onError) {
-              onError(parsed.error);
+              onError(parsed.error)
             }
           } catch (error) {
-            console.error('Error parsing stream chunk:', line, error);
+            console.error('Error parsing stream chunk:', line, error)
-            if (onError) onError(`Error parsing server response: ${line}`);
+            if (onError) onError(`Error parsing server response: ${line}`)
           }
         }
       }
@@ -482,98 +497,99 @@ export const queryTextStream = async (
     // Process any remaining data in the buffer after the stream ends
     if (buffer.trim()) {
       try {
-        const parsed = JSON.parse(buffer);
+        const parsed = JSON.parse(buffer)
         if (parsed.response) {
-          onChunk(parsed.response);
+          onChunk(parsed.response)
         } else if (parsed.error && onError) {
-          onError(parsed.error);
+          onError(parsed.error)
         }
       } catch (error) {
-        console.error('Error parsing final chunk:', buffer, error);
+        console.error('Error parsing final chunk:', buffer, error)
-        if (onError) onError(`Error parsing final server response: ${buffer}`);
+        if (onError) onError(`Error parsing final server response: ${buffer}`)
       }
     }
-
   } catch (error) {
-    const message = errorMessage(error);
+    const message = errorMessage(error)
 
     // Check if this is an authentication error
     if (message === 'Authentication required') {
       // Already navigated to login page in the response.status === 401 block
-      console.error('Authentication required for stream request');
+      console.error('Authentication required for stream request')
       if (onError) {
-        onError('Authentication required');
+        onError('Authentication required')
       }
-      return; // Exit early, no need for further error handling
+      return // Exit early, no need for further error handling
     }
 
     // Check for specific HTTP error status codes in the error message
-    const statusCodeMatch = message.match(/^(\d{3})\s/);
+    const statusCodeMatch = message.match(/^(\d{3})\s/)
     if (statusCodeMatch) {
-      const statusCode = parseInt(statusCodeMatch[1], 10);
+      const statusCode = parseInt(statusCodeMatch[1], 10)
 
       // Handle specific status codes with user-friendly messages
-      let userMessage = message;
+      let userMessage = message
 
       switch (statusCode) {
         case 403:
-        userMessage = 'You do not have permission to access this resource (403 Forbidden)';
+          userMessage = 'You do not have permission to access this resource (403 Forbidden)'
-        console.error('Permission denied for stream request:', message);
+          console.error('Permission denied for stream request:', message)
-        break;
+          break
         case 404:
-        userMessage = 'The requested resource does not exist (404 Not Found)';
+          userMessage = 'The requested resource does not exist (404 Not Found)'
-        console.error('Resource not found for stream request:', message);
+          console.error('Resource not found for stream request:', message)
-        break;
+          break
         case 429:
-        userMessage = 'Too many requests, please try again later (429 Too Many Requests)';
+          userMessage = 'Too many requests, please try again later (429 Too Many Requests)'
-        console.error('Rate limited for stream request:', message);
+          console.error('Rate limited for stream request:', message)
-        break;
+          break
         case 500:
         case 502:
         case 503:
         case 504:
-        userMessage = `Server error, please try again later (${statusCode})`;
+          userMessage = `Server error, please try again later (${statusCode})`
-        console.error('Server error for stream request:', message);
+          console.error('Server error for stream request:', message)
-        break;
+          break
         default:
-        console.error('Stream request failed with status code:', statusCode, message);
+          console.error('Stream request failed with status code:', statusCode, message)
       }
 
       if (onError) {
-        onError(userMessage);
+        onError(userMessage)
       }
-      return;
+      return
     }
 
     // Handle network errors (like connection refused, timeout, etc.)
-    if (message.includes('NetworkError') ||
+    if (
+      message.includes('NetworkError') ||
       message.includes('Failed to fetch') ||
-        message.includes('Network request failed')) {
+      message.includes('Network request failed')
-      console.error('Network error for stream request:', message);
+    ) {
+      console.error('Network error for stream request:', message)
       if (onError) {
-        onError('Network connection error, please check your internet connection');
+        onError('Network connection error, please check your internet connection')
       }
-      return;
+      return
     }
 
     // Handle JSON parsing errors during stream processing
     if (message.includes('Error parsing') || message.includes('SyntaxError')) {
-      console.error('JSON parsing error in stream:', message);
+      console.error('JSON parsing error in stream:', message)
       if (onError) {
-        onError('Error processing response data');
+        onError('Error processing response data')
       }
-      return;
+      return
     }
 
     // Handle other errors
-    console.error('Unhandled stream error:', message);
+    console.error('Unhandled stream error:', message)
     if (onError) {
-      onError(message);
+      onError(message)
     } else {
-      console.error('No error handler provided for stream error:', message);
+      console.error('No error handler provided for stream error:', message)
     }
   }
-};
+}
 
 export const insertText = async (text: string): Promise<DocActionResponse> => {
   const response = await axiosInstance.post('/documents/text', { text })
@@ -651,54 +667,55 @@ export const getAuthStatus = async (): Promise<AuthStatusResponse> => {
     const response = await axiosInstance.get('/auth-status', {
       timeout: 5000, // 5 second timeout
       headers: {
-        'Accept': 'application/json' // Explicitly request JSON
+        Accept: 'application/json' // Explicitly request JSON
       }
-    });
+    })
 
     // Check if response is HTML (which indicates a redirect or wrong endpoint)
-    const contentType = response.headers['content-type'] || '';
+    const contentType = response.headers['content-type'] || ''
     if (contentType.includes('text/html')) {
-      console.warn('Received HTML response instead of JSON for auth-status endpoint');
+      console.warn('Received HTML response instead of JSON for auth-status endpoint')
       return {
         auth_configured: true,
         auth_mode: 'enabled'
-      };
+      }
     }
 
     // Strict validation of the response data
-    if (response.data &&
+    if (
+      response.data &&
       typeof response.data === 'object' &&
       'auth_configured' in response.data &&
-        typeof response.data.auth_configured === 'boolean') {
+      typeof response.data.auth_configured === 'boolean'
-
+    ) {
       // For unconfigured auth, ensure we have an access token
       if (!response.data.auth_configured) {
         if (response.data.access_token && typeof response.data.access_token === 'string') {
-          return response.data;
+          return response.data
         } else {
-          console.warn('Auth not configured but no valid access token provided');
+          console.warn('Auth not configured but no valid access token provided')
         }
       } else {
         // For configured auth, just return the data
-        return response.data;
+        return response.data
       }
     }
 
     // If response data is invalid but we got a response, log it
-    console.warn('Received invalid auth status response:', response.data);
+    console.warn('Received invalid auth status response:', response.data)
 
     // Default to auth configured if response is invalid
     return {
       auth_configured: true,
       auth_mode: 'enabled'
-    };
+    }
   } catch (error) {
     // If the request fails, assume authentication is configured
-    console.error('Failed to get auth status:', errorMessage(error));
+    console.error('Failed to get auth status:', errorMessage(error))
     return {
       auth_configured: true,
       auth_mode: 'enabled'
-    };
+    }
   }
 }
 
@@ -716,17 +733,17 @@ export const cancelPipeline = async (): Promise<{
 }
 
 export const loginToServer = async (username: string, password: string): Promise<LoginResponse> => {
-  const formData = new FormData();
+  const formData = new FormData()
-  formData.append('username', username);
+  formData.append('username', username)
-  formData.append('password', password);
+  formData.append('password', password)
 
   const response = await axiosInstance.post('/login', formData, {
     headers: {
       'Content-Type': 'multipart/form-data'
     }
-  });
+  })
 
-  return response.data;
+  return response.data
 }
 
 /**
@@ -779,7 +796,9 @@ export const updateRelation = async (
  */
 export const checkEntityNameExists = async (entityName: string): Promise<boolean> => {
   try {
-    const response = await axiosInstance.get(`/graph/entity/exists?name=${encodeURIComponent(entityName)}`)
+    const response = await axiosInstance.get(
+      `/graph/entity/exists?name=${encodeURIComponent(entityName)}`
+    )
     return response.data.exists
   } catch (error) {
     console.error('Error checking entity name:', error)
@@ -797,12 +816,51 @@ export const getTrackStatus = async (trackId: string): Promise<TrackStatusRespon
   return response.data
 }
 
+// History API
+
+export type ChatSession = {
+  id: string
+  title: string
+  created_at: string
+  updated_at: string
+}
+
+export interface ChatHistoryMessage {
+  id: string
+  content: string
+  role: 'user' | 'assistant'
+  created_at: string
+  citations?: Array<{
+    source_doc_id: string
+    file_path: string
+    chunk_content?: string
+    relevance_score?: number
+  }>
+}
+
+export const getSessions = async (): Promise<ChatSession[]> => {
+  const response = await axiosInstance.get('/sessions')
+  return response.data
+}
+
+export const getSessionHistory = async (sessionId: string): Promise<ChatHistoryMessage[]> => {
+  const response = await axiosInstance.get(`/sessions/${sessionId}/history`)
+  return response.data
+}
+
+export const createSession = async (title?: string): Promise<ChatSession> => {
+  const response = await axiosInstance.post('/sessions', { title })
+  return response.data
+}
+
 /**
  * Get documents with pagination support
  * @param request The pagination request parameters
  * @returns Promise with paginated documents response
  */
-export const getDocumentsPaginated = async (request: DocumentsRequest): Promise<PaginatedDocsResponse> => {
+export const getDocumentsPaginated = async (
+  request: DocumentsRequest
+): Promise<PaginatedDocsResponse> => {
   const response = await axiosInstance.post('/documents/paginated', request)
   return response.data
 }
@@ -815,3 +873,4 @@ export const getDocumentStatusCounts = async (): Promise<StatusCountsResponse> =
   const response = await axiosInstance.get('/documents/status_counts')
   return response.data
 }
+

lightrag_webui/src/components/retrieval/SessionManager.tsx

@@ -0,0 +1,91 @@
+import { ChatSession, getSessions } from '@/api/lightrag'
+import Button from '@/components/ui/Button'
+import { ScrollArea } from '@/components/ui/ScrollArea'
+import { cn } from '@/lib/utils'
+import { format } from 'date-fns'
+import { MessageSquareIcon, PlusIcon } from 'lucide-react'
+import { useEffect, useState } from 'react'
+
+interface SessionManagerProps {
+  currentSessionId: string | null
+  onSessionSelect: (sessionId: string) => void
+  onNewSession: () => void
+}
+
+export default function SessionManager({
+  currentSessionId,
+  onSessionSelect,
+  onNewSession
+}: SessionManagerProps) {
+  const [sessions, setSessions] = useState<ChatSession[]>([])
+  const [isLoading, setIsLoading] = useState(false)
+
+  const fetchSessions = async () => {
+    setIsLoading(true)
+    try {
+      const data = await getSessions()
+      setSessions(data)
+    } catch (error) {
+      console.error('Failed to fetch sessions:', error)
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  useEffect(() => {
+    fetchSessions()
+  }, [currentSessionId]) // Refresh list when session changes (e.g. new one created)
+
+  const handleNewSession = async () => {
+    onNewSession()
+  }
+
+  return (
+    <div className="flex flex-col h-full border-r w-64 bg-muted/10">
+      <div className="p-4 border-b">
+        <Button onClick={handleNewSession} className="w-full justify-start gap-2" variant="outline">
+          <PlusIcon className="w-4 h-4" />
+          New Chat
+        </Button>
+      </div>
+      <ScrollArea className="flex-1">
+        <div className="p-2 space-y-1">
+          {sessions.map((session) => (
+            <Button
+              key={session.id}
+              variant={currentSessionId === session.id ? "secondary" : "ghost"}
+              className={cn(
+                "w-full justify-start text-left font-normal h-auto py-3 px-3",
+                currentSessionId === session.id && "bg-muted"
+              )}
+              onClick={() => onSessionSelect(session.id)}
+            >
+              <MessageSquareIcon className="w-4 h-4 mr-2 mt-0.5 shrink-0" />
+              <div className="flex flex-col gap-1 overflow-hidden">
+                <span className="truncate text-sm font-medium">
+                  {session.title || "Untitled Chat"}
+                </span>
+                <span className="text-xs text-muted-foreground">
+                  {(() => {
+                    try {
+                      return session.updated_at 
+                        ? format(new Date(session.updated_at), 'MMM d, HH:mm')
+                        : ''
+                    } catch (e) {
+                      return ''
+                    }
+                  })()}
+                </span>
+              </div>
+            </Button>
+          ))}
+          {sessions.length === 0 && !isLoading && (
+            <div className="text-center text-sm text-muted-foreground p-4">
+              No history yet
+            </div>
+          )}
+        </div>
+      </ScrollArea>
+    </div>
+  )
+}

lightrag_webui/src/features/RetrievalTesting.tsx

@@ -1,19 +1,19 @@
-import Textarea from '@/components/ui/Textarea'
+import type { QueryMode } from '@/api/lightrag'
-import Input from '@/components/ui/Input'
+import { createSession, getSessionHistory, queryText, queryTextStream } from '@/api/lightrag'
-import Button from '@/components/ui/Button'
-import { useCallback, useEffect, useRef, useState } from 'react'
-import { throttle } from '@/lib/utils'
-import { queryText, queryTextStream } from '@/api/lightrag'
-import { errorMessage } from '@/lib/utils'
-import { useSettingsStore } from '@/stores/settings'
-import { useDebounce } from '@/hooks/useDebounce'
-import QuerySettings from '@/components/retrieval/QuerySettings'
 import { ChatMessage, MessageWithError } from '@/components/retrieval/ChatMessage'
-import { EraserIcon, SendIcon, CopyIcon } from 'lucide-react'
+import QuerySettings from '@/components/retrieval/QuerySettings'
+import SessionManager from '@/components/retrieval/SessionManager'
+import Button from '@/components/ui/Button'
+import Input from '@/components/ui/Input'
+import Textarea from '@/components/ui/Textarea'
+import { useDebounce } from '@/hooks/useDebounce'
+import { errorMessage, throttle } from '@/lib/utils'
+import { useSettingsStore } from '@/stores/settings'
+import { copyToClipboard } from '@/utils/clipboard'
+import { CopyIcon, EraserIcon, SendIcon } from 'lucide-react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import { useTranslation } from 'react-i18next'
 import { toast } from 'sonner'
-import { copyToClipboard } from '@/utils/clipboard'
-import type { QueryMode } from '@/api/lightrag'
 
 // Helper function to generate unique IDs with browser compatibility
 const generateUniqueId = () => {
@@ -142,6 +142,52 @@ export default function RetrievalTesting() {
   const [inputError, setInputError] = useState('') // Error message for input
   const inputRef = useRef<HTMLInputElement | HTMLTextAreaElement>(null)
   
+  const [currentSessionId, setCurrentSessionId] = useState<string | null>(null)
+
+  // Scroll to bottom function - restored smooth scrolling with better handling
+  const scrollToBottom = useCallback(() => {
+    // Set flag to indicate this is a programmatic scroll
+    programmaticScrollRef.current = true
+    // Use requestAnimationFrame for better performance
+    requestAnimationFrame(() => {
+      if (messagesEndRef.current) {
+        // Use smooth scrolling for better user experience
+        messagesEndRef.current.scrollIntoView({ behavior: 'auto' })
+      }
+    })
+  }, [])
+
+  const handleSessionSelect = useCallback(async (sessionId: string) => {
+    setCurrentSessionId(sessionId)
+    setIsLoading(true)
+    try {
+      const history = await getSessionHistory(sessionId)
+      // Convert history to messages format
+      const historyMessages: MessageWithError[] = history.map((msg, index) => ({
+        id: msg.id || `hist-${Date.now()}-${index}`,
+        role: msg.role,
+        content: msg.content,
+        mermaidRendered: true, // Assume rendered for history
+        latexRendered: true
+      }))
+      setMessages(historyMessages)
+      useSettingsStore.getState().setRetrievalHistory(historyMessages)
+    } catch (error) {
+      console.error('Failed to load session history:', error)
+      toast.error('Failed to load history')
+    } finally {
+      setIsLoading(false)
+      setTimeout(scrollToBottom, 100)
+    }
+  }, [scrollToBottom])
+
+  const handleNewSession = useCallback(() => {
+    setCurrentSessionId(null)
+    setMessages([])
+    useSettingsStore.getState().setRetrievalHistory([])
+    setInputValue('')
+  }, [])
+
   // Smart switching logic: use Input for single line, Textarea for multi-line
   const hasMultipleLines = inputValue.includes('\n')
 
@@ -159,18 +205,6 @@ export default function RetrievalTesting() {
     })
   }, [])
 
-  // Scroll to bottom function - restored smooth scrolling with better handling
-  const scrollToBottom = useCallback(() => {
-    // Set flag to indicate this is a programmatic scroll
-    programmaticScrollRef.current = true
-    // Use requestAnimationFrame for better performance
-    requestAnimationFrame(() => {
-      if (messagesEndRef.current) {
-        // Use smooth scrolling for better user experience
-        messagesEndRef.current.scrollIntoView({ behavior: 'auto' })
-      }
-    })
-  }, [])
 
   const handleSubmit = useCallback(
     async (e: React.FormEvent) => {
@@ -354,9 +388,24 @@ export default function RetrievalTesting() {
         ? 3
         : configuredHistoryTurns
 
+      // Create session if not exists
+      let sessionId = currentSessionId
+      if (!sessionId) {
+        try {
+          // Create a new session with the first query as title (truncated)
+          const title = actualQuery.slice(0, 30) + (actualQuery.length > 30 ? '...' : '')
+          const newSession = await createSession(title)
+          sessionId = newSession.id
+          setCurrentSessionId(sessionId)
+        } catch (error) {
+          console.error('Failed to create session:', error)
+        }
+      }
+
       const queryParams = {
         ...state.querySettings,
         query: actualQuery,
+        session_id: sessionId || undefined,
         response_type: 'Multiple Paragraphs',
         conversation_history: effectiveHistoryTurns > 0
           ? prevMessages
@@ -685,6 +734,12 @@ export default function RetrievalTesting() {
   }, [t])
 
   return (
+    <div className="flex size-full overflow-hidden">
+      <SessionManager 
+        currentSessionId={currentSessionId}
+        onSessionSelect={handleSessionSelect}
+        onNewSession={handleNewSession}
+      />
       <div className="flex size-full gap-2 px-2 pb-12 overflow-hidden">
       <div className="flex grow flex-col gap-4">
         <div className="relative grow">
@@ -820,5 +875,6 @@ export default function RetrievalTesting() {
       </div>
       <QuerySettings />
       </div>
+    </div>
   )
 }

pyproject.toml

@@ -38,6 +38,12 @@ dependencies = [
     "tenacity",
     "tiktoken",
     "xlsxwriter>=3.1.0",
+    "fastapi",
+    "uvicorn",
+    "sqlalchemy",
+    "psycopg2-binary",
+    "openai",
+    "httpx",
 ]
 
 [project.optional-dependencies]
@@ -92,6 +98,7 @@ api = [
     "pypdf>=6.1.0",                 # PDF processing
     "python-docx>=0.8.11,<2.0.0",  # DOCX processing
     "python-pptx>=0.6.21,<2.0.0",  # PPTX processing
+    "sqlalchemy>=2.0.0,<3.0.0",
 ]
 
 # Advanced document processing engine (optional)

service/app/api/dependencies.py

@@ -0,0 +1,6 @@
+from app.core.database import get_db
+from fastapi import Depends
+from sqlalchemy.orm import Session
+
+def get_db_session(db: Session = Depends(get_db)):
+    return db

service/app/api/routes.py

@@ -0,0 +1,72 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session
+from typing import List
+from uuid import UUID
+
+from app.api.dependencies import get_db
+from app.services.history_manager import HistoryManager
+from app.services.chat_service import ChatService
+from app.models.schemas import (
+    SessionCreate, SessionResponse, ChatMessageRequest, ChatMessageResponse
+)
+
+router = APIRouter()
+
+@router.post("/sessions", response_model=SessionResponse, status_code=status.HTTP_201_CREATED)
+def create_session(session_in: SessionCreate, db: Session = Depends(get_db)):
+    # For now, we assume a default user or handle auth separately.
+    # Using a hardcoded user ID for demonstration if no auth middleware.
+    # In production, get user_id from current_user.
+    import uuid
+    # Placeholder user ID. In real app, ensure user exists.
+    # We might need to create a default user if not exists or require auth.
+    # For this task, we'll create a dummy user if needed or just use a random UUID 
+    # but that might fail FK constraint if user doesn't exist.
+    # Let's assume we need to create a user first or use an existing one.
+    # For simplicity, we'll generate a UUID but this will fail FK.
+    # So we should probably have a "get_or_create_default_user" helper.
+    
+    # Quick fix: Create a default user if table is empty or just use a fixed ID 
+    # and ensure it exists in startup event.
+    # For now, let's just use a fixed UUID and assume the user exists or we create it.
+    # Actually, let's just create a user on the fly for this session if we don't have auth.
+    
+    manager = HistoryManager(db)
+    # Check if we have any user, if not create one.
+    from app.models.models import User
+    user = db.query(User).first()
+    if not user:
+        user = User(username="default_user", email="default@example.com")
+        db.add(user)
+        db.commit()
+        db.refresh(user)
+    
+    session = manager.create_session(
+        user_id=user.id,
+        title=session_in.title,
+        rag_config=session_in.rag_config
+    )
+    return session
+
+@router.get("/sessions", response_model=List[SessionResponse])
+def list_sessions(skip: int = 0, limit: int = 100, db: Session = Depends(get_db)):
+    manager = HistoryManager(db)
+    # Again, need user_id. Using the default user strategy.
+    from app.models.models import User
+    user = db.query(User).first()
+    if not user:
+        return []
+        
+    sessions = manager.list_sessions(user_id=user.id, skip=skip, limit=limit)
+    return sessions
+
+@router.get("/sessions/{session_id}/history")
+def get_session_history(session_id: UUID, db: Session = Depends(get_db)):
+    manager = HistoryManager(db)
+    # This returns context format, might need a different schema for full history display
+    # For now reusing get_conversation_context logic but maybe we want full objects.
+    # Let's just return the raw messages for now or map to a schema.
+    # The requirement said "Get full history".
+    from app.models.models import ChatMessage
+    messages = db.query(ChatMessage).filter(ChatMessage.session_id == session_id).order_by(ChatMessage.created_at.asc()).all()
+    return messages

service/app/core/config.py

@@ -0,0 +1,31 @@
+import os
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    PROJECT_NAME: str = "LightRAG Service Wrapper"
+    API_V1_STR: str = "/api/v1"
+    POSTGRES_HOST: str = os.getenv("POSTGRES_HOST", "localhost")
+    POSTGRES_PORT: str = os.getenv("POSTGRES_PORT", "5432")
+    POSTGRES_USER: str = os.getenv("POSTGRES_USER", "postgres")
+    POSTGRES_PASSWORD: str = os.getenv("POSTGRES_PASSWORD", "password")
+    POSTGRES_DB: str = os.getenv("POSTGRES_DATABASE", "lightrag_db")
+    POSTGRES_MAX_CONNECTIONS: int = os.getenv("POSTGRES_MAX_CONNECTIONS", 12)
+    
+    # Encode credentials to handle special characters
+    from urllib.parse import quote_plus
+    _encoded_user = quote_plus(POSTGRES_USER)
+    _encoded_password = quote_plus(POSTGRES_PASSWORD)
+    
+    DATABASE_URL: str = os.getenv(
+        "DATABASE_URL",
+        f"postgresql://{_encoded_user}:{_encoded_password}@{POSTGRES_HOST}:{POSTGRES_PORT}/{POSTGRES_DB}"
+    )
+    LIGHTRAG_WORKING_DIR: str = os.getenv("LIGHTRAG_WORKING_DIR", "./rag_storage")
+    OPENAI_API_KEY: str = os.getenv("OPENAI_API_KEY", "")
+    AUTH_ACCOUNTS: str = os.getenv("AUTH_ACCOUNTS", "")
+
+    class Config:
+        case_sensitive = True
+
+settings = Settings()

service/app/core/database.py

@@ -0,0 +1,16 @@
+from sqlalchemy import create_engine
+from sqlalchemy.ext.declarative import declarative_base
+from sqlalchemy.orm import sessionmaker
+from app.core.config import settings
+
+engine = create_engine(settings.DATABASE_URL)
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+Base = declarative_base()
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

service/app/models/models.py

@@ -0,0 +1,58 @@
+import uuid
+from sqlalchemy import Column, String, Boolean, DateTime, ForeignKey, Text, Integer, Float, JSON
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import relationship
+from sqlalchemy.sql import func
+from app.core.database import Base
+
+class User(Base):
+    __tablename__ = "users"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    username = Column(String(50), unique=True, nullable=False)
+    email = Column(String(255), unique=True, nullable=False, index=True)
+    full_name = Column(String(100), nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+    is_active = Column(Boolean, default=True)
+
+    sessions = relationship("ChatSession", back_populates="user", cascade="all, delete-orphan")
+
+class ChatSession(Base):
+    __tablename__ = "chat_sessions"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    user_id = Column(UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True)
+    title = Column(String(255), nullable=True)
+    rag_config = Column(JSON, default={})
+    summary = Column(Text, nullable=True)
+    last_message_at = Column(DateTime(timezone=True), server_default=func.now(), index=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    user = relationship("User", back_populates="sessions")
+    messages = relationship("ChatMessage", back_populates="session", cascade="all, delete-orphan")
+
+class ChatMessage(Base):
+    __tablename__ = "chat_messages"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    session_id = Column(UUID(as_uuid=True), ForeignKey("chat_sessions.id", ondelete="CASCADE"), nullable=False)
+    role = Column(String(20), nullable=False) # user, assistant, system
+    content = Column(Text, nullable=False)
+    token_count = Column(Integer, nullable=True)
+    processing_time = Column(Float, nullable=True)
+    created_at = Column(DateTime(timezone=True), server_default=func.now())
+
+    session = relationship("ChatSession", back_populates="messages")
+    citations = relationship("MessageCitation", back_populates="message", cascade="all, delete-orphan")
+
+class MessageCitation(Base):
+    __tablename__ = "message_citations"
+
+    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
+    message_id = Column(UUID(as_uuid=True), ForeignKey("chat_messages.id", ondelete="CASCADE"), nullable=False)
+    source_doc_id = Column(String(255), nullable=False, index=True)
+    file_path = Column(Text, nullable=False)
+    chunk_content = Column(Text, nullable=True)
+    relevance_score = Column(Float, nullable=True)
+
+    message = relationship("ChatMessage", back_populates="citations")

service/app/models/schemas.py

@@ -0,0 +1,42 @@
+from pydantic import BaseModel
+from typing import List, Optional, Dict, Any
+from uuid import UUID
+from datetime import datetime
+
+class SessionCreate(BaseModel):
+    title: Optional[str] = None
+    rag_config: Optional[Dict[str, Any]] = {}
+
+class SessionResponse(BaseModel):
+    id: UUID
+    title: Optional[str]
+    created_at: datetime
+    last_message_at: Optional[datetime]
+
+    class Config:
+        from_attributes = True
+
+class ChatMessageRequest(BaseModel):
+    session_id: UUID
+    content: str
+    mode: Optional[str] = "hybrid"
+    stream: Optional[bool] = False
+
+class Citation(BaseModel):
+    source_doc_id: str
+    file_path: str
+    chunk_content: Optional[str]
+    relevance_score: Optional[float]
+
+    class Config:
+        from_attributes = True
+
+class ChatMessageResponse(BaseModel):
+    id: UUID
+    content: str
+    role: str
+    created_at: datetime
+    citations: List[Citation] = []
+
+    class Config:
+        from_attributes = True

service/app/services/history_manager.py

@@ -0,0 +1,99 @@
+from sqlalchemy.orm import Session
+from app.models.models import ChatMessage, ChatSession, MessageCitation
+from typing import List, Dict, Optional
+import uuid
+
+class HistoryManager:
+    def __init__(self, db: Session):
+        self.db = db
+
+    def get_conversation_context(self, session_id: uuid.UUID, max_tokens: int = 4000) -> List[Dict]:
+        """
+        Retrieves conversation history formatted for LLM context, truncated to fit max_tokens.
+        """
+        # Get latest messages first
+        raw_messages = (
+            self.db.query(ChatMessage)
+            .filter(ChatMessage.session_id == session_id)
+            .order_by(ChatMessage.created_at.desc())
+            .limit(20) # Safe buffer
+            .all()
+        )
+        
+        context = []
+        current_tokens = 0
+        
+        for msg in raw_messages:
+            # Simple token estimation (approx 4 chars per token)
+            msg_tokens = msg.token_count or len(msg.content) // 4
+            if current_tokens + msg_tokens > max_tokens:
+                break
+            
+            context.append({"role": msg.role, "content": msg.content})
+            current_tokens += msg_tokens
+            
+        return list(reversed(context))
+
+    def create_session(self, user_id: uuid.UUID, title: str = None, rag_config: dict = None) -> ChatSession:
+        session = ChatSession(
+            user_id=user_id,
+            title=title,
+            rag_config=rag_config or {}
+        )
+        self.db.add(session)
+        self.db.commit()
+        self.db.refresh(session)
+        return session
+
+    def get_session(self, session_id: uuid.UUID) -> Optional[ChatSession]:
+        return self.db.query(ChatSession).filter(ChatSession.id == session_id).first()
+
+    def list_sessions(self, user_id: uuid.UUID, skip: int = 0, limit: int = 100) -> List[ChatSession]:
+        return (
+            self.db.query(ChatSession)
+            .filter(ChatSession.user_id == user_id)
+            .order_by(ChatSession.last_message_at.desc())
+            .offset(skip)
+            .limit(limit)
+            .all()
+        )
+
+    def save_message(self, session_id: uuid.UUID, role: str, content: str, token_count: int = None, processing_time: float = None) -> ChatMessage:
+        message = ChatMessage(
+            session_id=session_id,
+            role=role,
+            content=content,
+            token_count=token_count,
+            processing_time=processing_time
+        )
+        self.db.add(message)
+        self.db.commit()
+        self.db.refresh(message)
+        
+        # Update session last_message_at
+        session = self.get_session(session_id)
+        if session:
+            session.last_message_at = message.created_at
+            self.db.commit()
+            
+        return message
+
+    def save_citations(self, message_id: uuid.UUID, citations: List[Dict]):
+        for cit in citations:
+            citation = MessageCitation(
+                message_id=message_id,
+                source_doc_id=cit.get("source_doc_id", "unknown"),
+                file_path=cit.get("file_path", "unknown"),
+                chunk_content=cit.get("chunk_content"),
+                relevance_score=cit.get("relevance_score")
+            )
+            self.db.add(citation)
+        self.db.commit()
+
+    def get_session_history(self, session_id: str) -> List[ChatMessage]:
+        return (
+            self.db.query(ChatMessage)
+            .filter(ChatMessage.session_id == session_id)
+            .order_by(ChatMessage.created_at.asc())
+            .all()
+        )

service/app/services/lightrag_wrapper.py

@@ -0,0 +1,80 @@
+import os
+import json
+from typing import Dict, Any
+from lightrag import LightRAG, QueryParam
+from lightrag.llm.openai import gpt_4o_mini_complete
+from app.core.config import settings
+
+class LightRAGWrapper:
+    _instance = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super(LightRAGWrapper, cls).__new__(cls)
+            cls._instance.rag = None
+            cls._instance.initialized = False
+        return cls._instance
+
+    async def initialize(self):
+        """Initialize LightRAG engine"""
+        if self.initialized:
+            return
+
+        if not os.path.exists(settings.LIGHTRAG_WORKING_DIR):
+            os.makedirs(settings.LIGHTRAG_WORKING_DIR)
+            
+        self.rag = LightRAG(
+            working_dir=settings.LIGHTRAG_WORKING_DIR,
+            llm_model_func=gpt_4o_mini_complete,
+            # Add other configurations as needed
+        )
+        # await self.rag.initialize_storages() # Uncomment if needed based on LightRAG version
+        self.initialized = True
+        print("LightRAG Initialized Successfully")
+
+    async def query(self, query_text: str, mode: str = "hybrid") -> Dict[str, Any]:
+        """
+        Execute query against LightRAG.
+        """
+        if not self.rag:
+            await self.initialize()
+
+        param = QueryParam(
+            mode=mode,
+            only_need_context=False,
+            response_type="Multiple Paragraphs" 
+        )
+        
+        # Execute query
+        # Note: Depending on LightRAG version, this might be sync or async. 
+        # Assuming async based on plan.
+        try:
+            result = await self.rag.aquery(query_text, param=param)
+        except AttributeError:
+             # Fallback to sync if aquery not available
+            result = self.rag.query(query_text, param=param)
+        
+        return self._parse_lightrag_response(result)
+
+    def _parse_lightrag_response(self, raw_response: Any) -> Dict[str, Any]:
+        """
+        Parse raw response from LightRAG into a structured format.
+        """
+        # This logic depends heavily on the actual return format of LightRAG.
+        # Assuming it returns a string or a specific object.
+        # For now, we'll assume it returns a string that might contain the answer.
+        # In a real scenario, we'd inspect 'raw_response' type.
+        
+        answer = str(raw_response)
+        references = [] # Placeholder for references extraction logic
+        
+        # If LightRAG returns an object with context, extract it here.
+        # For example:
+        # if isinstance(raw_response, dict):
+        #     answer = raw_response.get("response", "")
+        #     references = raw_response.get("context", [])
+            
+        return {
+            "answer": answer,
+            "references": references
+        }

service/init_db.py

@@ -0,0 +1,64 @@
+import sys
+import os
+import logging
+
+# Add the service directory to sys.path
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+
+from dotenv import load_dotenv
+load_dotenv(os.path.join(os.path.dirname(os.path.abspath(__file__)), "../.env"))
+
+from app.core.database import engine, Base, SessionLocal
+from app.models.models import User, ChatSession, ChatMessage, MessageCitation  # Import models to register them
+from app.core.config import settings
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+def init_db():
+    logger.info("Creating database tables...")
+    try:
+        Base.metadata.create_all(bind=engine)
+        logger.info("Tables created successfully!")
+        
+        # Create default users from AUTH_ACCOUNTS
+        if settings.AUTH_ACCOUNTS:
+            db = SessionLocal()
+            try:
+                accounts = settings.AUTH_ACCOUNTS.split(',')
+                for account in accounts:
+                    if ':' in account:
+                        username, password = account.split(':', 1)
+                        username = username.strip()
+                        # Check if user exists
+                        existing_user = db.query(User).filter(User.username == username).first()
+                        if not existing_user:
+                            logger.info(f"Creating default user: {username}")
+                            # Note: In a real app, password should be hashed. 
+                            # For now, we are just creating the user record. 
+                            # The User model doesn't have a password field in the provided schema, 
+                            # so we might need to add it or just store the user for now.
+                            # Looking at models.py, User has: username, email, full_name. No password.
+                            # I will use username as email for now if email is required.
+                            new_user = User(
+                                username=username,
+                                email=f"{username}@example.com",
+                                full_name=username
+                            )
+                            db.add(new_user)
+                        else:
+                            logger.info(f"User {username} already exists.")
+                db.commit()
+                logger.info("Default users processed.")
+            except Exception as e:
+                logger.error(f"Error creating default users: {e}")
+                db.rollback()
+            finally:
+                db.close()
+                
+    except Exception as e:
+        logger.error(f"Error creating tables: {e}")
+        raise
+
+if __name__ == "__main__":
+    init_db()

service/main.py

@@ -0,0 +1,40 @@
+import uvicorn
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from app.api.routes import router as api_router
+from app.core.config import settings
+from app.core.database import engine, Base
+from app.services.lightrag_wrapper import LightRAGWrapper
+
+# Create tables
+Base.metadata.create_all(bind=engine)
+
+app = FastAPI(
+    title=settings.PROJECT_NAME,
+    openapi_url=f"{settings.API_V1_STR}/openapi.json"
+)
+
+# CORS
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Include Router
+app.include_router(api_router, prefix=settings.API_V1_STR)
+
+@app.on_event("startup")
+async def startup_event():
+    # Initialize LightRAG
+    wrapper = LightRAGWrapper()
+    await wrapper.initialize()
+
+@app.get("/")
+def root():
+    return {"message": "Welcome to LightRAG Service Wrapper"}
+
+if __name__ == "__main__":
+    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

service/requirements.txt

@@ -0,0 +1,9 @@
+fastapi
+uvicorn
+sqlalchemy
+psycopg2-binary
+pydantic
+python-dotenv
+openai
+tenacity
+httpx

service/tests/test_direct_integration.py

@@ -0,0 +1,159 @@
+import sys
+import os
+import asyncio
+import uuid
+from unittest.mock import MagicMock, AsyncMock
+
+# Set SQLite for testing
+db_path = "./test.db"
+if os.path.exists(db_path):
+    os.remove(db_path)
+os.environ["DATABASE_URL"] = f"sqlite:///{db_path}"
+
+# Add project root to path
+project_root = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../"))
+sys.path.append(project_root)
+sys.path.append(os.path.join(project_root, "service"))
+
+# Mocking removed to allow real imports
+
+# Now import the modified router
+from lightrag.api.routers.query_routes import create_query_routes, QueryRequest
+
+# Import service DB to check if records are created
+from app.core.database import SessionLocal, engine, Base
+from app.models.models import ChatMessage, ChatSession
+
+# Create tables
+Base.metadata.create_all(bind=engine)
+
+async def test_direct_integration():
+    print("Testing Direct Integration...")
+    
+    # Mock RAG instance
+    mock_rag = MagicMock()
+    mock_rag.aquery_llm = AsyncMock(return_value={
+        "llm_response": {"content": "This is a mocked response."},
+        "data": {"references": [{"reference_id": "1", "file_path": "doc1.txt"}]}
+    })
+    
+    # Create router (this registers the endpoints but we'll call the function directly for testing)
+    # We need to access the function decorated by @router.post("/query")
+    # Since we can't easily get the route function from the router object without starting FastAPI,
+    # we will inspect the router.routes
+    
+    create_query_routes(mock_rag)
+    
+    from lightrag.api.routers.query_routes import router
+    
+    # Find the query_text function
+    query_route = next(r for r in router.routes if r.path == "/query")
+    query_func = query_route.endpoint
+    
+    # Prepare Request
+    request = QueryRequest(
+        query="Test Query Direct",
+        mode="hybrid",
+        session_id=None # Should create new session
+    )
+    
+    # Call the endpoint function directly
+    print("Calling query_text...")
+    response = await query_func(request)
+    print("Response received:", response)
+    
+    # Verify DB
+    db = SessionLocal()
+    messages = db.query(ChatMessage).all()
+    print(f"Total messages: {len(messages)}")
+    for msg in messages:
+        print(f"Msg: {msg.content} ({msg.role}) at {msg.created_at}")
+    
+    last_message = db.query(ChatMessage).filter(ChatMessage.role == "assistant").order_by(ChatMessage.created_at.desc()).first()
+    
+    if last_message:
+        print(f"Last Assistant Message: {last_message.content}")
+        assert last_message.content == "This is a mocked response."
+        assert last_message.role == "assistant"
+        
+        # Check user message
+        user_msg = db.query(ChatMessage).filter(ChatMessage.session_id == last_message.session_id, ChatMessage.role == "user").first()
+        assert user_msg.content == "Test Query Direct"
+        print("Verification Successful: History logged to DB.")
+    else:
+        print("Verification Failed: No message found in DB.")
+    
+    db.close()
+
+async def test_stream_integration():
+    print("\nTesting Stream Integration...")
+    
+    # Mock RAG instance for streaming
+    mock_rag = MagicMock()
+    
+    # Mock response iterator
+    async def response_iterator():
+        yield "Chunk 1 "
+        yield "Chunk 2"
+    
+    mock_rag.aquery_llm = AsyncMock(return_value={
+        "llm_response": {
+            "is_streaming": True,
+            "response_iterator": response_iterator()
+        },
+        "data": {"references": [{"reference_id": "2", "file_path": "doc2.txt"}]}
+    })
+    
+    from lightrag.api.routers.query_routes import router
+    router.routes = [] # Clear existing routes to avoid conflict
+    create_query_routes(mock_rag)
+    
+    # Find the query_text_stream function
+    stream_route = next(r for r in router.routes if r.path == "/query/stream")
+    stream_func = stream_route.endpoint
+    
+    # Prepare Request
+    request = QueryRequest(
+        query="Test Stream Direct",
+        mode="hybrid",
+        stream=True,
+        session_id=None
+    )
+    
+    # Call the endpoint
+    print("Calling query_text_stream...")
+    response = await stream_func(request)
+    
+    # Consume the stream
+    content = ""
+    async for chunk in response.body_iterator:
+        print(f"Chunk received: {chunk}")
+        content += chunk
+        
+    print("Stream finished.")
+    
+    # Verify DB
+    db = SessionLocal()
+    # Check for the new message
+    # We expect "Chunk 1 Chunk 2" as content
+    # Note: The chunk in body_iterator is NDJSON string, e.g. '{"response": "Chunk 1 "}\n'
+    # But the DB should contain the parsed content.
+    
+    last_message = db.query(ChatMessage).filter(ChatMessage.role == "assistant", ChatMessage.content == "Chunk 1 Chunk 2").first()
+    
+    if last_message:
+        print(f"Stream Message in DB: {last_message.content}")
+        assert last_message.content == "Chunk 1 Chunk 2"
+        print("Verification Successful: Stream History logged to DB.")
+    else:
+        print("Verification Failed: Stream message not found in DB.")
+        # Print all to debug
+        messages = db.query(ChatMessage).all()
+        for msg in messages:
+            print(f"Msg: {msg.content} ({msg.role})")
+            
+    db.close()
+
+if __name__ == "__main__":
+    asyncio.run(test_direct_integration())
+    asyncio.run(test_stream_integration())

service/tests/test_service_flow.py

@@ -0,0 +1,53 @@
+from fastapi.testclient import TestClient
+from main import app
+import uuid
+
+client = TestClient(app)
+
+def test_flow():
+    # 1. Create Session
+    response = client.post("/api/v1/sessions", json={"title": "Test Session"})
+    assert response.status_code == 201
+    session_data = response.json()
+    session_id = session_data["id"]
+    print(f"Created Session: {session_id}")
+
+    # 2. List Sessions
+    response = client.get("/api/v1/sessions")
+    assert response.status_code == 200
+    sessions = response.json()
+    assert len(sessions) > 0
+    print(f"Listed {len(sessions)} sessions")
+
+    # 3. Chat Message (Mocking LightRAG since we don't have it running/installed fully)
+    # Note: This might fail if LightRAGWrapper tries to actually initialize and fails.
+    # We might need to mock LightRAGWrapper in the app.
+    
+    # For this test, we assume the app handles LightRAG initialization failure gracefully 
+    # or we mock it. Since we didn't mock it in main.py, this test might error out 
+    # if LightRAG dependencies are missing.
+    
+    # However, let's try to send a message.
+    try:
+        response = client.post("/api/v1/chat/message", json={
+            "session_id": session_id,
+            "content": "Hello",
+            "mode": "hybrid"
+        })
+        # If it fails due to LightRAG, we catch it.
+        if response.status_code == 200:
+            print("Chat response received")
+            print(response.json())
+        else:
+            print(f"Chat failed with {response.status_code}: {response.text}")
+    except Exception as e:
+        print(f"Chat execution failed: {e}")
+
+    # 4. Get History
+    response = client.get(f"/api/v1/sessions/{session_id}/history")
+    assert response.status_code == 200
+    history = response.json()
+    print(f"History length: {len(history)}")
+
+if __name__ == "__main__":
+    test_flow()

uv.lock

@@ -2589,6 +2589,7 @@ api = [
     { name = "python-pptx" },
     { name = "pytz" },
     { name = "setuptools" },
+    { name = "sqlalchemy" },
     { name = "tenacity" },
     { name = "tiktoken" },
     { name = "uvicorn" },
@@ -2598,13 +2599,49 @@ docling = [
     { name = "docling", marker = "sys_platform != 'darwin'" },
 ]
 evaluation = [
+    { name = "aiofiles" },
+    { name = "aiohttp" },
+    { name = "ascii-colors" },
+    { name = "asyncpg" },
+    { name = "bcrypt" },
+    { name = "configparser" },
     { name = "datasets" },
+    { name = "distro" },
+    { name = "fastapi" },
+    { name = "google-api-core" },
+    { name = "google-genai" },
+    { name = "gunicorn" },
+    { name = "httpcore" },
     { name = "httpx" },
-    { name = "pre-commit" },
+    { name = "jiter" },
-    { name = "pytest" },
+    { name = "json-repair" },
-    { name = "pytest-asyncio" },
+    { name = "nano-vectordb" },
+    { name = "networkx", version = "3.4.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "networkx", version = "3.5", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
+    { name = "numpy" },
+    { name = "openai" },
+    { name = "openpyxl" },
+    { name = "pandas" },
+    { name = "pipmaster" },
+    { name = "psutil" },
+    { name = "pycryptodome" },
+    { name = "pydantic" },
+    { name = "pyjwt" },
+    { name = "pypdf" },
+    { name = "pypinyin" },
+    { name = "python-docx" },
+    { name = "python-dotenv" },
+    { name = "python-jose", extra = ["cryptography"] },
+    { name = "python-multipart" },
+    { name = "python-pptx" },
+    { name = "pytz" },
     { name = "ragas" },
-    { name = "ruff" },
+    { name = "setuptools" },
+    { name = "sqlalchemy" },
+    { name = "tenacity" },
+    { name = "tiktoken" },
+    { name = "uvicorn" },
+    { name = "xlsxwriter" },
 ]
 observability = [
     { name = "langfuse" },
@@ -2656,6 +2693,7 @@ offline = [
     { name = "qdrant-client", version = "1.15.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
     { name = "redis" },
     { name = "setuptools" },
+    { name = "sqlalchemy" },
     { name = "tenacity" },
     { name = "tiktoken" },
     { name = "uvicorn" },
@@ -2691,6 +2729,53 @@ pytest = [
     { name = "pytest-asyncio" },
     { name = "ruff" },
 ]
+test = [
+    { name = "aiofiles" },
+    { name = "aiohttp" },
+    { name = "ascii-colors" },
+    { name = "asyncpg" },
+    { name = "bcrypt" },
+    { name = "configparser" },
+    { name = "distro" },
+    { name = "fastapi" },
+    { name = "google-api-core" },
+    { name = "google-genai" },
+    { name = "gunicorn" },
+    { name = "httpcore" },
+    { name = "httpx" },
+    { name = "jiter" },
+    { name = "json-repair" },
+    { name = "nano-vectordb" },
+    { name = "networkx", version = "3.4.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "networkx", version = "3.5", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11'" },
+    { name = "numpy" },
+    { name = "openai" },
+    { name = "openpyxl" },
+    { name = "pandas" },
+    { name = "pipmaster" },
+    { name = "pre-commit" },
+    { name = "psutil" },
+    { name = "pycryptodome" },
+    { name = "pydantic" },
+    { name = "pyjwt" },
+    { name = "pypdf" },
+    { name = "pypinyin" },
+    { name = "pytest" },
+    { name = "pytest-asyncio" },
+    { name = "python-docx" },
+    { name = "python-dotenv" },
+    { name = "python-jose", extra = ["cryptography"] },
+    { name = "python-multipart" },
+    { name = "python-pptx" },
+    { name = "pytz" },
+    { name = "ruff" },
+    { name = "setuptools" },
+    { name = "sqlalchemy" },
+    { name = "tenacity" },
+    { name = "tiktoken" },
+    { name = "uvicorn" },
+    { name = "xlsxwriter" },
+]
 
 [package.metadata]
 requires-dist = [
@@ -2717,12 +2802,13 @@ requires-dist = [
     { name = "google-genai", marker = "extra == 'offline-llm'", specifier = ">=1.0.0,<2.0.0" },
     { name = "gunicorn", marker = "extra == 'api'" },
     { name = "httpcore", marker = "extra == 'api'" },
-    { name = "httpx", marker = "extra == 'api'" },
+    { name = "httpx", marker = "extra == 'api'", specifier = ">=0.28.1" },
-    { name = "httpx", marker = "extra == 'evaluation'", specifier = ">=0.28.1" },
     { name = "jiter", marker = "extra == 'api'" },
     { name = "json-repair" },
     { name = "json-repair", marker = "extra == 'api'" },
     { name = "langfuse", marker = "extra == 'observability'", specifier = ">=3.8.1" },
+    { name = "lightrag-hku", extras = ["api"], marker = "extra == 'evaluation'" },
+    { name = "lightrag-hku", extras = ["api"], marker = "extra == 'test'" },
     { name = "lightrag-hku", extras = ["api", "offline-llm", "offline-storage"], marker = "extra == 'offline'" },
     { name = "llama-index", marker = "extra == 'offline-llm'", specifier = ">=0.9.0,<1.0.0" },
     { name = "nano-vectordb" },
@@ -2740,8 +2826,8 @@ requires-dist = [
     { name = "pandas", marker = "extra == 'api'", specifier = ">=2.0.0,<2.4.0" },
     { name = "pipmaster" },
     { name = "pipmaster", marker = "extra == 'api'" },
-    { name = "pre-commit", marker = "extra == 'evaluation'" },
     { name = "pre-commit", marker = "extra == 'pytest'" },
+    { name = "pre-commit", marker = "extra == 'test'" },
     { name = "psutil", marker = "extra == 'api'" },
     { name = "pycryptodome", marker = "extra == 'api'", specifier = ">=3.0.0,<4.0.0" },
     { name = "pydantic" },
@@ -2752,10 +2838,10 @@ requires-dist = [
     { name = "pypdf", marker = "extra == 'api'", specifier = ">=6.1.0" },
     { name = "pypinyin" },
     { name = "pypinyin", marker = "extra == 'api'" },
-    { name = "pytest", marker = "extra == 'evaluation'", specifier = ">=8.4.2" },
     { name = "pytest", marker = "extra == 'pytest'", specifier = ">=8.4.2" },
-    { name = "pytest-asyncio", marker = "extra == 'evaluation'", specifier = ">=1.2.0" },
+    { name = "pytest", marker = "extra == 'test'", specifier = ">=8.4.2" },
     { name = "pytest-asyncio", marker = "extra == 'pytest'", specifier = ">=1.2.0" },
+    { name = "pytest-asyncio", marker = "extra == 'test'", specifier = ">=1.2.0" },
     { name = "python-docx", marker = "extra == 'api'", specifier = ">=0.8.11,<2.0.0" },
     { name = "python-dotenv" },
     { name = "python-dotenv", marker = "extra == 'api'" },
@@ -2766,10 +2852,11 @@ requires-dist = [
     { name = "qdrant-client", marker = "extra == 'offline-storage'", specifier = ">=1.11.0,<2.0.0" },
     { name = "ragas", marker = "extra == 'evaluation'", specifier = ">=0.3.7" },
     { name = "redis", marker = "extra == 'offline-storage'", specifier = ">=5.0.0,<8.0.0" },
-    { name = "ruff", marker = "extra == 'evaluation'" },
     { name = "ruff", marker = "extra == 'pytest'" },
+    { name = "ruff", marker = "extra == 'test'" },
     { name = "setuptools" },
     { name = "setuptools", marker = "extra == 'api'" },
+    { name = "sqlalchemy", marker = "extra == 'api'", specifier = ">=2.0.0,<3.0.0" },
     { name = "tenacity" },
     { name = "tenacity", marker = "extra == 'api'" },
     { name = "tiktoken" },
@@ -2780,7 +2867,7 @@ requires-dist = [
     { name = "xlsxwriter", marker = "extra == 'api'", specifier = ">=3.1.0" },
     { name = "zhipuai", marker = "extra == 'offline-llm'", specifier = ">=2.0.0,<3.0.0" },
 ]
-provides-extras = ["pytest", "api", "docling", "offline-storage", "offline-llm", "offline", "evaluation", "observability"]
+provides-extras = ["pytest", "api", "docling", "offline-storage", "offline-llm", "offline", "test", "evaluation", "observability"]
 
 [[package]]
 name = "llama-cloud"