PostgreSQL database integration for conversation persistence

backend/.env.example

@@ -22,7 +22,7 @@ GOOGLE_GEMINI=2.0_flash
 
 LLM_TEMP=1
 
-EMBEDDINGS_TYPE=GOOGLE_VERTEXAI
+EMBEDDINGS_TYPE=GOOGLE_GENAI
 GOOGLE_EMBEDDINGS=text-embedding-004
 HF_EMBEDDINGS=thenlper/gte-large
 HF_RERANKER=BAAI/bge-reranker-base
@@ -64,3 +64,10 @@ HEALTHCHECK_INTERVAL=30s
 HEALTHCHECK_TIMEOUT=10s
 HEALTHCHECK_RETRIES=5
 HEALTHCHECK_START_PERIOD=1200s
+
+# PostgreSQL Database Configuration
+POSTGRES_USER=orassistant
+POSTGRES_PASSWORD=password
+POSTGRES_DB=orassistant_db
+POSTGRES_HOST=postgres
+POSTGRES_PORT=5432

backend/Dockerfile

@@ -2,7 +2,18 @@ FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim
 
 WORKDIR /ORAssistant-backend
 
-RUN apt-get update && apt-get install -y pandoc git wget curl git-lfs && git lfs install
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    curl \
+    gcc \
+    git \
+    git-lfs \
+    libpq-dev \
+    pandoc \
+    postgresql-client \
+    wget && \
+    git lfs install && \
+    rm -rf /var/lib/apt/lists/*
 
 RUN pip install uv
 
@@ -16,6 +27,12 @@ RUN git clone https://huggingface.co/datasets/The-OpenROAD-Project/ORAssistant_R
     mv ORAssistant_RAG_Dataset/* data/ && \
     rm -rf ORAssistant_RAG_Dataset
 
+ENV POSTGRES_HOST=postgres \
+    POSTGRES_PORT=5432 \
+    POSTGRES_USER=orassistant \
+    POSTGRES_PASSWORD=password \
+    POSTGRES_DB=orassistant_db
+
 EXPOSE 8000
 
 CMD ["uv", "run", "uvicorn", "src.api.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]

backend/Dockerfile_slim

@@ -3,10 +3,18 @@ FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim
 WORKDIR /ORAssistant-backend
 
 RUN apt-get update && apt-get install -y \
-    pandoc git wget curl \
-    git-lfs
+    build-essential \
+    curl \
+    gcc \
+    git \
+    git-lfs \
+    libpq-dev \
+    pandoc \
+    postgresql-client \
+    wget && \
+    git lfs install && \
+    rm -rf /var/lib/apt/lists/*
 
-RUN git lfs install
 RUN pip install uv
 
 COPY ./pyproject.toml /ORAssistant-backend/pyproject.toml
@@ -21,6 +29,12 @@ RUN git clone https://huggingface.co/datasets/The-OpenROAD-Project/ORAssistant_R
     mv ORAssistant_RAG_Dataset/* data/ && \
     rm -rf ORAssistant_RAG_Dataset
 
+ENV POSTGRES_HOST=postgres \
+    POSTGRES_PORT=5432 \
+    POSTGRES_USER=orassistant \
+    POSTGRES_PASSWORD=password \
+    POSTGRES_DB=orassistant_db
+
 EXPOSE 8000
 
 CMD ["uv", "run", "uvicorn", "src.api.dummy:app", "--host", "0.0.0.0", "--port", "8000"]

backend/main.py

@@ -2,10 +2,13 @@
 import uvicorn
 from dotenv import load_dotenv
 
-from src.api.main import app
-
 load_dotenv()
 
+if os.getenv("USE_CUDA", "false").lower() != "true":
+    os.environ["CUDA_VISIBLE_DEVICES"] = ""
+
+from src.api.main import app  # noqa: E402
+
 
 def main() -> None:
     uvicorn.run(

backend/pyproject.toml

@@ -5,9 +5,11 @@ description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.13"
 dependencies = [
+    "asyncpg>=0.30.0",
     "faiss-cpu==1.12.0",
     "fastapi==0.116.1",
     "fastmcp>=2.12.2",
+    "httpx>=0.28.1",
     "huggingface-hub[cli]==0.34.4",
     "langchain==0.3.27",
     "langchain-community==0.3.27",
@@ -21,15 +23,19 @@ dependencies = [
     "myst-parser==4.0.1",
     "nltk==3.9.1",
     "openai==1.100.2",
+    "psycopg2>=2.9.11",
+    "pydantic>=2.11.7",
     "pypdf==6.0.0",
     "rank-bm25==0.2.2",
+    "rich>=13.7.0",
     "sentence-transformers>=5.1.0",
     "sphinx==8.1.3",
     "sphinx-autobuild==2024.10.3",
     "sphinx-book-theme==1.1.4",
     "sphinx-copybutton==0.5.2",
     "sphinx-external-toc==1.0.1",
     "sphinxcontrib-mermaid==1.0.0",
+    "sqlalchemy>=2.0.43",
     "unstructured==0.18.13",
 ]
 

backend/src/api/api_docs.md

@@ -0,0 +1,170 @@
+# API Documentation
+
+## Conversations Router
+
+Base URL: `/conversations`
+
+### Conversation API 
+
+#### GET /conversations
+
+List all conversations.
+
+**Query Parameters:**
+
+- `skip`: Number of conversations to skip (default: 0)
+- `limit`: Maximum number of conversations to return (default: 100)
+
+**Response:**
+
+```json
+[
+  {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "title": "string",
+    "created_at": "datetime",
+    "updated_at": "datetime"
+  }
+]
+```
+
+**Status Codes:**
+
+- 200: Successful response
+- 422: Validation error
+
+#### GET /conversations/{id}
+
+Get a specific conversation with all messages.
+
+**Path Parameters:**
+
+- `id`: The unique identifier (UUID) of the conversation
+
+**Response:**
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "title": "string",
+  "created_at": "datetime",
+  "updated_at": "datetime",
+  "messages": [
+    {
+      "id": 1,
+      "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
+      "role": "user",
+      "content": "string",
+      "context_sources": null,
+      "tools": null,
+      "created_at": "datetime"
+    },
+    {
+      "id": 2,
+      "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
+      "role": "assistant",
+      "content": "string",
+      "context_sources": {"source": "...", "context": "..."},
+      "tools": ["tool_name"],
+      "created_at": "datetime"
+    }
+  ]
+}
+```
+
+**Status Codes:**
+
+- 200: Successful response
+- 404: Conversation not found
+- 422: Validation error
+
+#### DELETE /conversations/{id}
+
+Delete a conversation and all its messages.
+
+**Path Parameters:**
+
+- `id`: The unique identifier (UUID) of the conversation to delete
+
+**Response:**
+
+No content (204)
+
+**Status Codes:**
+
+- 204: Conversation deleted successfully
+- 404: Conversation not found
+- 422: Validation error
+
+### Chat Endpoints
+
+#### POST /conversations/agent-retriever
+
+Get a response from the agent with conversation context and retrieval.
+
+**Request Body:**
+
+```json
+{
+  "query": "string",
+  "conversation_id": "string (optional)",
+  "list_sources": "boolean (optional)",
+  "list_context": "boolean (optional)"
+}
+```
+
+**Response:**
+
+```json
+{
+  "response": "string",
+  "context_sources": [
+    {
+      "context": "string",
+      "source": "string"
+    }
+  ],
+  "tools": ["string"]
+}
+```
+
+**Status Codes:**
+
+- 200: Successful response
+- 422: Validation error
+- 500: Internal server error
+
+**Parameters:**
+
+- `query`: The user's question or input text
+- `conversation_id`: Optional UUID identifier to maintain conversation continuity (auto-generated if not provided)
+- `list_sources`: Include source URLs in the response
+- `list_context`: Include retrieved context text in the response
+
+#### POST /conversations/agent-retriever/stream
+
+Get a streaming response from the agent.
+
+**Request Body:**
+
+```json
+{
+  "query": "string",
+  "conversation_id": "string (optional)"
+}
+```
+
+**Response:**
+
+Returns a streaming response with `text/event-stream` media type. The stream includes:
+
+- LLM response chunks as they are generated
+- Source URLs at the end of the stream
+
+**Status Codes:**
+
+- 200: Successful streaming response
+- 422: Validation error
+- 500: Internal server error
+
+

backend/src/api/main.py

@@ -1,23 +1,37 @@
 from fastapi import FastAPI
-from .routers import graphs, healthcheck, helpers, ui
+from .routers import healthcheck, helpers, ui, conversations
 from fastapi.middleware.cors import CORSMiddleware
+from contextlib import asynccontextmanager
+from src.database.config import init_database
+import logging
 
-app = FastAPI()
+logger = logging.getLogger(__name__)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Initialize database on startup."""
+    logger.info("Initializing database connection...")
+    init_database()
+    yield
+    logger.info("Shutting down...")
+
+
+app = FastAPI(lifespan=lifespan)
 
-# Add CORS middleware
 app.add_middleware(
     CORSMiddleware,
     allow_origins=[
         "http://localhost:3000",
         "http://127.0.0.1:3000",
-        "http://localhost:8001",  # mock endpoint
+        "http://localhost:8001",
         "http://127.0.0.1:8001",
     ],
     allow_credentials=True,
     allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
     allow_headers=["*"],
 )
 app.include_router(healthcheck.router)
-app.include_router(graphs.router)
 app.include_router(helpers.router)
 app.include_router(ui.router)
+app.include_router(conversations.router)