
---

# 📚 Database Module Documentation

> **File:** `app/db/database.py`
> This module provides a streamlined way to connect to and manage database sessions for your application.
> It supports both **PostgreSQL** and **SQLite**, with environment-based configuration for flexible deployment.

---

## 1. ⚙️ Configuration

The database connection is controlled using environment variables. If these are not set, the module uses sensible defaults.

### 📌 Environment Variables

| Variable       | Description                           | Default Value                                                                                   | Supported Values     |
| -------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------- |
| `DB_MODE`      | Specifies the type of database to use | `"postgres"`                                                                                    | `postgres`, `sqlite` |
| `DATABASE_URL` | Connection string for the database    | PostgreSQL: `postgresql://user:password@localhost/ai_hub_db`<br>SQLite: `sqlite:///./data/ai_hub.db` | Any SQLAlchemy URI   |

### 💡 Example: Switch to SQLite

```bash
export DB_MODE="sqlite"
```

---

## 2. 🧱 Core Components

This module exposes several key components used to interface with the database.

### `engine`

* A SQLAlchemy **Engine** instance.
* Manages connections, pooling, and execution context.

### `SessionLocal`

* A factory for creating new database **session objects**.
* Typically accessed indirectly through the `get_db` dependency.

### `Base`

* The base class all SQLAlchemy models should inherit from.
* Used to declare table mappings.

### `get_db()`

* A **FastAPI dependency function**.
* Yields a new session per request and ensures it's closed afterward, even in case of errors.

---

## 3. 🚀 Usage with FastAPI

To safely interact with the database in your FastAPI routes, use the `get_db()` dependency.

### ✅ Steps to Use

1. **Import `get_db`:**

   ```python
   from app.db.database import get_db
   ```

2. **Add it as a dependency:**

   ```python
   from fastapi import Depends
   from sqlalchemy.orm import Session
   ```

3. **Inject into your route handler:**

   ```python
   @app.get("/items/")
   def read_items(db: Session = Depends(get_db)):
       return db.query(Item).all()
   ```

This pattern ensures that every request has a dedicated, isolated database session that is properly cleaned up afterward.

---

Here is your fully **formatted and organized** documentation for the SQLAlchemy models in `app/db/models/`, suitable for technical documentation or a README:

---

# 🗂️ Database Models Documentation

This document describes the SQLAlchemy models defined in `app/db/models/`. These classes represent the tables used to store application data, including **chat sessions**, **messages**, and **document metadata** for **Retrieval-Augmented Generation (RAG)**.

All models inherit from the `Base` class, imported from the `database.py` module.

---

## 1. 🗨️ Session Model

Represents a single **conversation** between a user and an AI. It serves as the container for all messages in that session.

### 🔑 Key Fields

| Field         | Data Type | Description                               |
| ------------- | --------- | ----------------------------------------- |
| `id`          | Integer   | Primary key for the session               |
| `user_id`     | String    | Unique identifier of the user             |
| `title`       | String    | Optional AI-generated title               |
| `model_name`  | String    | Name of the LLM used in the session       |
| `created_at`  | DateTime  | Timestamp of when the session was created |
| `is_archived` | Boolean   | Soft-delete/archive flag for the session  |

### 🔗 Relationships

* **`messages`**:
  One-to-many relationship with the **Message** model.
  Deleting a session will also delete all related messages (via `cascade="all, delete-orphan"`).

---

## 2. 💬 Message Model

Stores individual **messages** within a session, including user inputs and AI responses.

### 🔑 Key Fields

| Field                 | Data Type | Description                                                         |
| --------------------- | --------- | ------------------------------------------------------------------- |
| `id`                  | Integer   | Primary key for the message                                         |
| `session_id`          | Integer   | Foreign key linking to the parent session                           |
| `sender`              | String    | Role of the sender (`"user"` or `"assistant"`)                      |
| `content`             | Text      | Full text of the message                                            |
| `created_at`          | DateTime  | Timestamp of message creation                                       |
| `model_response_time` | Integer   | Time (in seconds) taken by the model to generate the response       |
| `token_count`         | Integer   | Number of tokens in the message                                     |
| `message_metadata`    | JSON      | Flexible field for storing unstructured metadata (e.g., tool calls) |

### 🔗 Relationships

* **`session`**:
  Many-to-one relationship with the **Session** model.

---

## 3. 📄 Document Model

Stores **metadata** and **content** of documents ingested into the system for RAG purposes.

### 🔑 Key Fields

| Field        | Data Type | Description                                        |
| ------------ | --------- | -------------------------------------------------- |
| `id`         | Integer   | Primary key for the document                       |
| `title`      | String    | Human-readable title                               |
| `text`       | Text      | Full content of the document                       |
| `source_url` | String    | URL or path where the document was retrieved from  |
| `author`     | String    | Author of the document                             |
| `status`     | String    | Processing status (`"ready"`, `"processing"` etc.) |
| `created_at` | DateTime  | Timestamp of document creation                     |
| `user_id`    | String    | ID of the user who added the document              |

### 🔗 Relationships

* **`vector_metadata`**:
  One-to-one relationship with the **VectorMetadata** model.

---

## 4. 🧠 VectorMetadata Model

Connects documents to their **vector representations** (e.g., FAISS indices) for efficient retrieval in RAG workflows.

### 🔑 Key Fields

| Field             | Data Type | Description                                                |
| ----------------- | --------- | ---------------------------------------------------------- |
| `id`              | Integer   | Primary key for the metadata entry                         |
| `document_id`     | Integer   | Foreign key to the parent **Document** (unique constraint) |
| `faiss_index`     | Integer   | Vector's index in the FAISS store                          |
| `session_id`      | Integer   | Foreign key to the **Session** used in the RAG context     |
| `embedding_model` | String    | Embedding model used to generate the vector                |

### 🔗 Relationships

* **`document`**:
  Many-to-one relationship with the **Document** model

* **`session`**:
  Many-to-one relationship with the **Session** model

---
