### Start UI Application

Source: https://github.com/bupt-gamma/pathrag/blob/main/README.md

This bash command navigates to the UI directory and starts the React application using npm.

```bash
# Navigate to the UI directory
cd ui

# Install dependencies (first time only)
npm install

# Start the UI
npm start
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Install the necessary Node.js packages for the frontend using npm.

```bash
npm install
```

--------------------------------

### Install Frontend Dependencies

Source: https://github.com/bupt-gamma/pathrag/blob/main/README.md

This command installs the necessary dependencies for the frontend React application.

```bash
# Navigate to the frontend directory
cd ui

# Install dependencies
npm install
```

--------------------------------

### Start Backend Server

Source: https://github.com/bupt-gamma/pathrag/blob/main/README.md

This command starts the backend API server using the main Python script.

```bash
python main.py
```

--------------------------------

### Build Frontend Application

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Commands to install dependencies and build the frontend application for deployment.

```bash
cd pathrag-ui
npm install
npm run build
```

--------------------------------

### Install Python Dependencies

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Install all required Python packages using pip from the requirements.txt file.

```bash
pip install -r requirements.txt
```

--------------------------------

### Start PathRAG API Server using uvicorn module syntax

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

If your application is structured as a Python module, use the module syntax with uvicorn to start the server.

```bash
# If your app is in a module structure
uvicorn pathrag.main:app --host 0.0.0.0 --port 8000
```

--------------------------------

### Start PathRAG API Server (Recommended)

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Execute the start-api script to run the backend server. Ensure the script has execute permissions on Unix-like systems.

```bash
# On Unix/Linux/macOS
chmod +x start-api.sh
./start-api.sh

# On Windows
start-api.bat
```

--------------------------------

### Start API Script (Windows)

Source: https://github.com/bupt-gamma/pathrag/blob/main/README.md

This batch script is used to start the backend API on Windows systems.

```batch
# Run the API
start-api.bat
```

--------------------------------

### Start API Script (Unix/Linux/macOS)

Source: https://github.com/bupt-gamma/pathrag/blob/main/README.md

This bash script is used to set up and run the backend API on Unix-like systems. It makes the script executable and then runs it.

```bash
# Make the script executable (first time only)
chmod +x start-api.sh

# Run the API
./start-api.sh
```

--------------------------------

### Run Frontend Development Server

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Start the frontend development server to view and interact with the UI locally. The application will be accessible at http://localhost:3000.

```bash
npm start
```

--------------------------------

### Docker Compose with Secrets

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Example docker-compose.yml configuration demonstrating the use of Docker secrets for sensitive environment variables like API keys and JWT secrets in a production setup.

```yaml
version: '3.8'

services:
  backend:
    # ... other settings as above
    secrets:
      - jwt_secret
      - openai_api_key
    environment:
      - SECRET_KEY_FILE=/run/secrets/jwt_secret
      - OPENAI_API_KEY_FILE=/run/secrets/openai_api_key
      # ... other environment variables

secrets:
  jwt_secret:
    file: ./secrets/jwt_secret.txt
  openai_api_key:
    file: ./secrets/openai_api_key.txt
```

--------------------------------

### Run PathRAG with Hypercorn

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Deploy the application using Hypercorn, an alternative ASGI server. Ensure Hypercorn is installed before running.

```bash
pip install hypercorn

# Run with Hypercorn
hypercorn main:app --bind 0.0.0.0:8000 --workers 4
```

--------------------------------

### RAGRunner Utility - Multi-Backend Configuration

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Demonstrates the setup and usage of the RAGRunner utility with different backend configurations.

```APIDOC
## RAGRunner Utility

### Multi-Backend RAGRunner

Use the RAGRunner utility class for simplified setup with multiple backend configurations.

```python
import os
import asyncio
from PathRAG.RAGRunner import RAGRunner

# Configure for different backends: hf / vllm / ollama / ms / local
backend = "ollama"
working_dir = "./rag_runner_data"

runner = RAGRunner(
    backend=backend,
    working_dir=working_dir,
    llm_model_name="qwen3:0.6b",
    embedding_model_name="bge-large",
    llm_model_max_token_size=8192,
    llm_model_kwargs={
        "host": "http://localhost:11434",
        "options": {"num_ctx": 8192},
        "timeout": 300,
    } if backend == "ollama" else {},
    embedding_dim=1024,
    embedding_max_token_size=5000,
)

# Insert document
with open("document.txt", "r", encoding="utf-8") as f:
    runner.insert_text(f.read())

# Query with hybrid mode
question = "What are the key concepts in this document?"
answer = runner.query(question, mode="hybrid")
print(f"Question: {question}")
print(f"Answer: {answer}")
```

### Description
This code snippet shows how to initialize and use the `RAGRunner` class from the `PathRAG` library. It demonstrates configuring the runner for different language model backends (e.g., Ollama), specifying model names, token sizes, and backend-specific keyword arguments. It also includes steps for inserting text content from a file and performing a hybrid query to retrieve information.

### Parameters
- **backend** (string) - The RAG backend to use (e.g., "hf", "vllm", "ollama", "ms", "local").
- **working_dir** (string) - The directory for storing RAG runner data.
- **llm_model_name** (string) - The name of the language model to use.
- **embedding_model_name** (string) - The name of the embedding model to use.
- **llm_model_max_token_size** (integer) - The maximum token size for the language model.
- **llm_model_kwargs** (dict) - Additional keyword arguments for the language model (backend-specific).
- **embedding_dim** (integer) - The dimension of the embedding vectors.
- **embedding_max_token_size** (integer) - The maximum token size for embeddings.

### Usage
1. Initialize `RAGRunner` with desired backend and model configurations.
2. Insert text content using `runner.insert_text()`.
3. Query the knowledge base using `runner.query()` with a specified mode (e.g., "hybrid").
```

--------------------------------

### vLLM Integration for PathRAG

Source: https://github.com/bupt-gamma/pathrag/blob/main/examples.txt

Configure PathRAG to use vLLM for LLM inference and embeddings. This setup assumes vLLM is installed and configured.

```python
rag = PathRAG(
    working_dir=WORKING_DIR,
    llm_model_func=vllm_model_complete,
    llm_model_name="./modelscope/Qwen3-0.6B",
    embedding_func=EmbeddingFunc(
        embedding_dim=384, 
        max_token_size=5000,
        func=lambda texts: vllm_embedding(
            texts,
            tokenizer=AutoTokenizer.from_pretrained(
                "./modelscope/all-MiniLM-L6-v2"
            ),
            embed_model=AutoModel.from_pretrained(
                "./modelscope/all-MiniLM-L6-v2"
            ),
        ),
    ),
)
```

--------------------------------

### Start PathRAG API Server using main.py

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Run the application directly using the main.py script. Environment variables can be used to override default settings.

```bash
# Basic start with default settings
python main.py

# With environment variables override
HOST=127.0.0.1 PORT=8080 DEBUG=true python main.py
```

--------------------------------

### Run Docker Compose

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Command to start the services defined in the docker-compose.yml file in detached mode.

```bash
# Basic run
docker-compose up -d
```

--------------------------------

### Systemd Service Management Commands

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Commands to manage the systemd service for PathRAG, including reloading the daemon, enabling the service to start on boot, starting, checking status, and viewing logs.

```bash
# Reload systemd to recognize the new service
sudo systemctl daemon-reload

# Enable the service to start on boot
sudo systemctl enable pathrag

# Start the service
sudo systemctl start pathrag

# Check the status
sudo systemctl status pathrag

# View logs
sudo journalctl -u pathrag -f
```

--------------------------------

### Configure PathRAG with vLLM Backend

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Configure PathRAG with vLLM for high-performance LLM inference. Ensure vLLM is installed and models are accessible locally.

```python
from PathRAG import PathRAG
from PathRAG.llm import vllm_model_complete, vllm_embedding
from PathRAG.utils import EmbeddingFunc
from transformers import AutoTokenizer, AutoModel

rag = PathRAG(
    working_dir="./vllm_data",
    llm_model_func=vllm_model_complete,
    llm_model_name="./models/Qwen3-0.6B",
    embedding_func=EmbeddingFunc(
        embedding_dim=384,
        max_token_size=5000,
        func=lambda texts: vllm_embedding(
            texts,
            tokenizer=AutoTokenizer.from_pretrained("./models/all-MiniLM-L6-v2"),
            embed_model=AutoModel.from_pretrained("./models/all-MiniLM-L6-v2"),
        ),
    ),
)
```

--------------------------------

### Nginx Configuration for PathRAG

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Example Nginx configuration to serve the frontend static files, handle API requests, and set cache headers for static assets.

```nginx
server {
    listen 80;
    server_name your-domain.com;

    root /path/to/pathrag-ui/build;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /static/ {
        expires 1y;
        add_header Cache-Control "public, max-age=31536000";
    }

    location /api/ {
        proxy_pass http://localhost:8000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

--------------------------------

### Start PathRAG API Server using uvicorn

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Control the ASGI server directly with uvicorn. Options include enabling auto-reloading, setting log levels, and configuring SSL/TLS for HTTPS.

```bash
# Basic start
uvicorn main:app --host 0.0.0.0 --port 8000

# With reload for development (auto-restart on file changes)
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# With log level configuration
uvicorn main:app --host 0.0.0.0 --port 8000 --log-level debug

# With SSL/TLS for HTTPS (requires key and cert files)
uvicorn main:app --host 0.0.0.0 --port 8443 --ssl-keyfile ./key.pem --ssl-certfile ./cert.pem
```

--------------------------------

### Knowledge Graph - Get Full Graph

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Retrieve the entire knowledge graph, including all nodes and edges. Useful for visualization purposes. Requires authentication.

```bash
curl -X GET "http://localhost:8000/knowledge-graph/" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Chat Threads - List All Threads

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Get all chat threads for the authenticated user.

```APIDOC
## GET /chats/threads

### Description
Get all chat threads for the authenticated user.

### Method
GET

### Endpoint
/chats/threads

### Request Example
```bash
curl -X GET "http://localhost:8000/chats/threads" \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **threads** (array) - A list of chat thread objects.
  - **id** (integer) - The unique identifier for the chat thread.
  - **uuid** (string) - The universally unique identifier for the chat thread.
  - **user_id** (integer) - The ID of the user who created the thread.
  - **title** (string) - The title of the chat thread.
  - **created_at** (string) - The timestamp when the thread was created (ISO 8601 format).
  - **updated_at** (string) - The timestamp when the thread was last updated (ISO 8601 format).

#### Response Example
```json
{
  "threads": [
    {
      "id": 1,
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": 1,
      "title": "Research Discussion",
      "created_at": "2024-01-15T10:35:00.000Z",
      "updated_at": "2024-01-15T10:40:00.000Z"
    }
  ]
}
```
```

--------------------------------

### Knowledge Graph - Get Full Graph

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Retrieve the complete knowledge graph with all nodes and edges for visualization.

```APIDOC
## GET /knowledge-graph/

### Description
Retrieve the complete knowledge graph with all nodes and edges for visualization.

### Method
GET

### Endpoint
/knowledge-graph/

### Request Example
```bash
curl -X GET "http://localhost:8000/knowledge-graph/" \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **nodes** (array) - A list of nodes in the knowledge graph.
  - **id** (string) - The unique identifier for the node.
  - **label** (string) - The display label for the node.
  - **type** (string) - The type of the node (e.g., "PERSON", "ORGANIZATION").
  - **description** (string) - A brief description of the node.
- **edges** (array) - A list of edges connecting nodes in the knowledge graph.
  - **source** (string) - The ID of the source node for the edge.
  - **target** (string) - The ID of the target node for the edge.
  - **label** (string) - The label describing the relationship.
  - **weight** (float) - The weight of the edge.

#### Response Example
```json
{
  "nodes": [
    {
      "id": "\"ALBERT EINSTEIN\"",
      "label": "\"ALBERT EINSTEIN\"",
      "type": "PERSON",
      "description": "Physicist who developed the theory of relativity"
    },
    {
      "id": "\"PRINCETON UNIVERSITY\"",
      "label": "\"PRINCETON UNIVERSITY\"",
      "type": "ORGANIZATION",
      "description": "Research university in New Jersey"
    }
  ],
  "edges": [
    {
      "source": "\"ALBERT EINSTEIN\"",
      "target": "\"PRINCETON UNIVERSITY\"",
      "label": "worked at",
      "weight": 1.0
    }
  ]
}
```
```

--------------------------------

### Ollama Integration for PathRAG

Source: https://github.com/bupt-gamma/pathrag/blob/main/examples.txt

Integrate PathRAG with Ollama for LLM and embedding services. This example shows how to configure Ollama host, model names, and embedding dimensions using environment variables.

```python
rag = PathRAG(
        working_dir=WORKING_DIR,
        llm_model_func=ollama_model_complete,
        llm_model_name=os.getenv("LLM_MODEL", "qwen3:0.6b"),
        llm_model_max_token_size=8192,
        llm_model_kwargs={
            "host": os.getenv("LLM_BINDING_HOST", "http://localhost:11434"),
            "options": {"num_ctx": 8192},
            "timeout": int(os.getenv("TIMEOUT", "300")),
        },
        embedding_func=EmbeddingFunc(
            embedding_dim=int(os.getenv("EMBEDDING_DIM", "1024")),
            max_token_size=int(os.getenv("MAX_EMBED_TOKENS", "8192")),
            func=lambda texts: ollama_embedding(
                texts,
                embed_model=os.getenv("EMBEDDING_MODEL", "bge-large"),
                host=os.getenv("EMBEDDING_BINDING_HOST", "http://localhost:11434"),
            ),
        ),
    )
```

--------------------------------

### Run Docker Compose with Environment Variable Override

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Use this command to start the application with Docker Compose, overriding the SECRET_KEY environment variable with a randomly generated 32-byte hex string.

```bash
SECRET_KEY=$(openssl rand -hex 32) docker-compose up -d
```

--------------------------------

### Authentication - Get Current User

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Retrieve information about the currently authenticated user. Requires a valid Bearer token in the Authorization header.

```bash
curl -X GET "http://localhost:8000/users/me" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### ModelScope Integration for PathRAG

Source: https://github.com/bupt-gamma/pathrag/blob/main/examples.txt

Integrate PathRAG with ModelScope for LLM and embedding functionalities. This example uses a specific sentence embedding model from ModelScope.

```python
tokenizer = ms.AutoTokenizer.from_pretrained(
    "iic/nlp_corom_sentence-embedding_english-base",
    trust_remote_code=True
)
model = ms.AutoModel.from_pretrained(
    "iic/nlp_corom_sentence-embedding_english-base",
    trust_remote_code=True
).to("cuda" if torch.cuda.is_available() else "cpu").eval()
rag = PathRAG(
    working_dir=WORKING_DIR,
    llm_model_func=ms_model_complete,
    llm_model_name="Qwen/Qwen3-0.6B",
    embedding_func=EmbeddingFunc(
        embedding_dim=768,  # corom 模型输出维度
        max_token_size=5000,
        func=lambda texts: ms_embedding(
            texts,
            tokenizer,
            model, 
        ),
    ),
)
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Set up a Python virtual environment using venv. Activation commands differ for Windows and macOS/Linux.

```bash
# Using venv
python -m venv .venv

# Activate on Windows
.venv\Scripts\activate

# Activate on macOS/Linux
source .venv/bin/activate
```

--------------------------------

### Clone Repository and Set Up Virtual Environment

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Clone the PathRAG repository and set up a Python virtual environment for dependency management.

```bash
git clone <repository-url>
cd pathrag

python -m venv .venv
source .venv/bin/activate

pip install -r requirements.txt
```

--------------------------------

### Documents - Get Document Status

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Check the processing status of an uploaded document.

```APIDOC
## GET /documents/{document_id}/status

### Description
Check the processing status of an uploaded document.

### Method
GET

### Endpoint
/documents/{document_id}/status

### Parameters
#### Path Parameters
- **document_id** (integer) - Required - The ID of the document to check the status for.

### Request Example
```bash
curl -X GET "http://localhost:8000/documents/1/status" \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the document.
- **user_id** (integer) - The ID of the user who uploaded the document.
- **filename** (string) - The name of the uploaded file.
- **status** (string) - The current processing status of the document (e.g., "completed", "failed").
- **processed_at** (string or null) - The timestamp when the document processing was completed (ISO 8601 format).
- **error_message** (string or null) - Details about any error that occurred during processing.

#### Response Example
```json
{
  "id": 1,
  "user_id": 1,
  "filename": "research_paper.pdf",
  "status": "completed",
  "processed_at": "2024-01-15T10:32:00.000Z",
  "error_message": null
}
```
```

--------------------------------

### Navigate to Frontend Directory

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Change the current directory to the frontend application folder.

```bash
cd pathrag-ui
```

--------------------------------

### Authentication - Get Current User

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Retrieve the currently authenticated user's information.

```APIDOC
## GET /users/me

### Description
Retrieve the currently authenticated user's information.

### Method
GET

### Endpoint
/users/me

### Request Example
```bash
curl -X GET "http://localhost:8000/users/me" \
  -H "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
- **id** (integer) - The user's unique identifier.
- **username** (string) - The user's username.
- **email** (string) - The user's email address.
- **created_at** (string) - The timestamp when the user was created (ISO 8601 format).
- **theme** (string or null) - The user's preferred theme, if set.

#### Response Example
```json
{
  "id": 1,
  "username": "user1",
  "email": "user1@example.com",
  "created_at": "2024-01-01T00:00:00.000Z",
  "theme": "blue"
}
```
```

--------------------------------

### Build Frontend for Production

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Generate optimized production-ready build files for the frontend application. These files will be placed in the 'build' directory.

```bash
npm run build
```

--------------------------------

### Neo4j Integration - Get Subgraph

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Retrieves a subgraph from Neo4j containing specified entities and their relationships.

```APIDOC
## POST /documents/subgraph

### Description
Retrieve a subgraph containing specified entities and their relationships.

### Method
POST

### Endpoint
/documents/subgraph

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **entity_list** (array of strings) - Required - A list of entity names to include in the subgraph.
- **neo4j_uri** (string) - Required - The Neo4j connection URI (e.g., bolt://localhost:7687).
- **neo4j_username** (string) - Required - The Neo4j username.
- **neo4j_password** (string) - Required - The Neo4j password.
- **neo4j_database** (string) - Required - The Neo4j database name.

### Request Example
```bash
curl -X POST "http://localhost:8000/documents/subgraph" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d 
  '{
    "entity_list": ["Albert Einstein", "Princeton University", "Theory of Relativity"],
    "neo4j_uri": "bolt://localhost:7687",
    "neo4j_username": "neo4j",
    "neo4j_password": "password123",
    "neo4j_database": "neo4j"
  }'
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the subgraph was retrieved successfully.
- **message** (string) - A message confirming the subgraph retrieval.
- **nodes** (array) - A list of nodes in the subgraph.
- **relationships** (array) - A list of relationships in the subgraph.
- **nodes_count** (integer) - The total number of nodes in the subgraph.
- **relationships_count** (integer) - The total number of relationships in the subgraph.

#### Response Example
```json
{
  "success": true,
  "message": "Subgraph retrieved successfully with 3 nodes and 2 relationships.",
  "nodes": [...],
  "relationships": [...],
  "nodes_count": 3,
  "relationships_count": 2
}
```
```

--------------------------------

### Register New User via REST API

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Register a new user account by sending a POST request with username, email, and password in JSON format to the /register endpoint.

```bash
curl -X POST "http://localhost:8000/register" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "newuser",
    "email": "newuser@example.com",
    "password": "SecurePass@456"
  }'

# Response:
# {
#   "id": 4,
#   "username": "newuser",
#   "email": "newuser@example.com",
# }
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Create a .env file in the root directory to configure application settings, database, API keys, and other parameters. Ensure this file is not committed to version control.

```dotenv
# JWT Settings (Required)
SECRET_KEY=your_secret_key_here  # Use a strong random string, e.g., openssl rand -hex 32
ACCESS_TOKEN_EXPIRE_MINUTES=30   # Token expiration time in minutes

# Database Settings (Optional - defaults to SQLite)
DATABASE_URL=sqlite:///./pathrag.db  # SQLite database path

# Application Settings (Required)
WORKING_DIR=./data                   # Directory for storing PathRAG data
UPLOAD_DIR=./uploads                 # Directory for storing uploaded documents

# Azure OpenAI Settings (Required if using Azure OpenAI)
AZURE_OPENAI_API_VERSION=2023-05-15
AZURE_OPENAI_DEPLOYMENT=gpt-4o       # Your Azure OpenAI deployment name
AZURE_OPENAI_API_KEY=your_azure_key  # Your Azure OpenAI API key
AZURE_OPENAI_ENDPOINT=https://your-resource-name.openai.azure.com

AZURE_EMBEDDING_DEPLOYMENT=text-embedding-3-large  # Your Azure embedding model deployment
AZURE_EMBEDDING_API_VERSION=2023-05-15

# OpenAI Settings (Required if using OpenAI directly instead of Azure)
OPENAI_API_KEY=your_openai_key       # Your OpenAI API key
OPENAI_API_BASE=https://api.openai.com/v1

# PathRAG Settings (Optional - advanced configuration)
CHUNK_SIZE=1200                      # Size of text chunks for processing
CHUNK_OVERLAP=100                    # Overlap between chunks
MAX_TOKENS=32768                     # Maximum tokens for LLM context
TEMPERATURE=0.7                      # LLM temperature setting
TOP_K=40                             # Number of top results to retrieve

# CORS Settings (Optional - for production)
CORS_ORIGINS=http://localhost:3000,https://your-domain.com  # Allowed origins
```

--------------------------------

### Documents - Get Document Status

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Check the processing status of an uploaded document using its ID. Requires the document ID and authentication.

```bash
curl -X GET "http://localhost:8000/documents/1/status" \
  -H "Authorization: Bearer $TOKEN"
```

--------------------------------

### Backend Dockerfile

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Dockerfile for building the backend Python application. Includes system dependencies, Python dependencies, code copying, and running the application with uvicorn.

```dockerfile
FROM python:3.9-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PORT=8000

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Create necessary directories
RUN mkdir -p data uploads

# Expose port
EXPOSE 8000

# Run the application with uvicorn
CMD uvicorn main:app --host 0.0.0.0 --port ${PORT} --workers ${WORKERS:-1} --log-level ${LOG_LEVEL:-info}
```

--------------------------------

### Copy and Edit Environment File

Source: https://github.com/bupt-gamma/pathrag/blob/main/README.md

This command copies the sample environment file to .env, which should then be edited with specific settings. Key variables for JWT, directories, database, server, and AI models are listed.

```bash
cp sample.env .env
# Edit .env with your preferred text editor
```

--------------------------------

### Initialize and Query PathRAG with OpenAI

Source: https://github.com/bupt-gamma/pathrag/blob/main/README.md

Use this snippet to initialize PathRAG with OpenAI models and perform a hybrid query. Ensure your OpenAI API key is set as an environment variable and a 'text.txt' file is prepared.

```python
import os
from PathRAG import PathRAG, QueryParam
from PathRAG.llm import gpt_4o_mini_complete

WORKING_DIR = "./your_working_dir"
api_key="your_api_key"
os.environ["OPENAI_API_KEY"] = api_key
base_url="https://api.openai.com/v1"
os.environ["OPENAI_API_BASE"]=base_url


if not os.path.exists(WORKING_DIR):
    os.mkdir(WORKING_DIR)

rag = PathRAG(
    working_dir=WORKING_DIR,
    llm_model_func=gpt_4o_mini_complete,  
)

data_file="./text.txt"
question="your_question"
with open(data_file) as f:
    rag.insert(f.read())

print(rag.query(question, param=QueryParam(mode="hybrid")))
```

--------------------------------

### Production-Ready Backend Dockerfile (Multi-stage Build)

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

A multi-stage Dockerfile for the backend application, optimizing for production by using a builder stage for wheels and a clean final stage.

```dockerfile
# Build stage
FROM python:3.9-slim AS builder

WORKDIR /app

# Install build dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip wheel --no-cache-dir --no-deps --wheel-dir /app/wheels -r requirements.txt

# Final stage
FROM python:3.9-slim

WORKDIR /app

# Set environment variables
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PORT=8000

# Install runtime dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq5 \
    && rm -rf /var/lib/apt/lists/*

# Copy wheels from builder stage
COPY --from=builder /app/wheels /wheels
RUN pip install --no-cache /wheels/*

# Copy application code
COPY . .

# Create necessary directories
RUN mkdir -p data uploads

# Create non-root user for security
RUN adduser --disabled-password --gecos "" appuser
RUN chown -R appuser:appuser /app
USER appuser

# Expose port
EXPOSE 8000

# Run the application with uvicorn
CMD uvicorn main:app --host 0.0.0.0 --port ${PORT} --workers ${WORKERS:-1} --log-level ${LOG_LEVEL:-info}
```

--------------------------------

### Initialize PathRAG Instance

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Instantiate PathRAG with specified LLM and embedding functions. Ensure environment variables for API keys and base URLs are set. The working directory is created if it doesn't exist.

```python
import os
from PathRAG import PathRAG, QueryParam
from PathRAG.llm import gpt_4o_mini_complete, openai_embedding

# Set environment variables
os.environ["OPENAI_API_KEY"] = "sk-your-api-key"
os.environ["OPENAI_API_BASE"] = "https://api.openai.com/v1"

WORKING_DIR = "./pathrag_data"
os.makedirs(WORKING_DIR, exist_ok=True)

# Initialize PathRAG with OpenAI
rag = PathRAG(
    working_dir=WORKING_DIR,
    llm_model_func=gpt_4o_mini_complete,
    llm_model_name="gpt-4o-mini",
    llm_model_max_token_size=32768,
    embedding_func=openai_embedding,
    chunk_token_size=1200,
    chunk_overlap_token_size=100,
    enable_llm_cache=True
)
```

--------------------------------

### Frontend Dockerfile

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Dockerfile for building and serving the frontend application using Node.js for build and Nginx for serving static files.

```dockerfile
FROM node:16-alpine as build

WORKDIR /app

COPY package*.json ./
RUN npm install

COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/build /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80

CMD ["nginx", "-g", "daemon off;"]
```

--------------------------------

### Hugging Face Model Integration for PathRAG

Source: https://github.com/bupt-gamma/pathrag/blob/main/examples.txt

Configure PathRAG to use Hugging Face models for LLM completion and embeddings. Ensure the necessary Hugging Face libraries are installed.

```python
rag = PathRAG(
    working_dir=WORKING_DIR,
    llm_model_func=hf_model_complete,
    llm_model_name="Qwen/Qwen3-0.6B",
    embedding_func=EmbeddingFunc(
        embedding_dim=384, 
        max_token_size=5000,
        func=lambda texts: hf_embedding(
            texts,
            tokenizer=AutoTokenizer.from_pretrained(
                "sentence-transformers/all-MiniLM-L6-v2"
            ),
            embed_model=AutoModel.from_pretrained(
                "sentence-transformers/all-MiniLM-L6-v2"
            ),
        ),
    ),
)
```

--------------------------------

### RAGRunner Initialization and Usage

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Initializes and uses the RAGRunner for document insertion and querying with different backend configurations. Supports multiple LLM providers and embedding models.

```python
import os
import asyncio
from PathRAG.RAGRunner import RAGRunner

# Configure for different backends: hf / vllm / ollama / ms / local
backend = "ollama"
working_dir = "./rag_runner_data"

runner = RAGRunner(
    backend=backend,
    working_dir=working_dir,
    llm_model_name="qwen3:0.6b",
    embedding_model_name="bge-large",
    llm_model_max_token_size=8192,
    llm_model_kwargs={
        "host": "http://localhost:11434",
        "options": {"num_ctx": 8192},
        "timeout": 300,
    } if backend == "ollama" else {},
    embedding_dim=1024,
    embedding_max_token_size=5000,
)

# Insert document
with open("document.txt", "r", encoding="utf-8") as f:
    runner.insert_text(f.read())

# Query with hybrid mode
question = "What are the key concepts in this document?"
answer = runner.query(question, mode="hybrid")
print(f"Question: {question}")
print(f"Answer: {answer}")
```

--------------------------------

### Initialize and Query PathRAG with Different Model Sources

Source: https://github.com/bupt-gamma/pathrag/blob/main/README.md

This snippet demonstrates initializing RAGRunner with models from various sources like Hugging Face, Ollama, ModelScope, or local files. Configure `backend`, `llm_model_name`, `embedding_model_name`, and optionally `llm_model_kwargs` for Ollama.

```python
import os
import asyncio
import torch
from PathRAG.RAGRunner import RAGRunner
if __name__ == "__main__":
	backend = "your_model_source" # hf / vllm / ollama / ms / local
	working_dir = f"your_working_dir" 
	llm_model_name = "Qwen/Qwen3-0.6B" # model name or path of model
	embedding_model_name = "iic/nlp_corom_sentence-embedding_english-base" # embedding model name or path ofembedding model
	# ollama additional parameters
	llm_model_kwargs = {
	"host": "http://localhost:11434",
	"options": {"num_ctx": 8192},
	"timeout": 300,
	} if backend == "ollama" else {}
	
	runner = RAGRunner(
		backend=backend,
		working_dir=working_dir,
		llm_model_name=llm_model_name,
		embedding_model_name=embedding_model_name,
		llm_model_max_token_size=8192,
		llm_model_kwargs=llm_model_kwargs,
		embedding_dim=768,
		embedding_max_token_size=5000,
	)
	data_file = "your_data_file"
	question = "your_question"
	with open(data_file, "r", encoding="utf-8") as f:
		runner.insert_text(f.read())
	answer = runner.query(question, mode="hybrid")
	print("question:", question)
	print("answer:", answer)
```

--------------------------------

### Run PathRAG with Gunicorn and Uvicorn Workers

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Deploy the application using Gunicorn with Uvicorn workers, suitable for Unix/Linux systems. Adjust worker count and timeouts for optimal performance.

```bash
pip install gunicorn

# Basic run with 4 worker processes
gunicorn -w 4 -k uvicorn.workers.UvicornWorker main:app

# With bind address configuration
gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 main:app

# With timeout and worker configuration
gunicorn -w 4 -k uvicorn.workers.UvicornWorker --timeout 120 --graceful-timeout 60 main:app

# With SSL/TLS for HTTPS
gunicorn -w 4 -k uvicorn.workers.UvicornWorker --keyfile ./key.pem --certfile ./cert.pem main:app
```

--------------------------------

### Systemd Service Configuration for Gunicorn

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Set up a systemd service file to manage the PathRAG application when using Gunicorn with Uvicorn workers. This ensures automatic startup and restarts.

```ini
[Unit]
Description=PathRAG API
After=network.target

[Service]
User=your_user
Group=your_group
WorkingDirectory=/path/to/pathrag
Environment="PATH=/path/to/pathrag/.venv/bin"
EnvironmentFile=/path/to/pathrag/.env
ExecStart=/path/to/pathrag/.venv/bin/gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 --timeout 120 main:app
Restart=always
RestartSec=5
StartLimitIntervalSec=0

# Security options
PrivateTmp=true
ProtectSystem=full
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Configure PathRAG with HuggingFace Backend

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Configure PathRAG to use HuggingFace transformers models for LLM and embedding functions. Requires transformers library and pre-trained models.

```python
from PathRAG import PathRAG
from PathRAG.llm import hf_model_complete, hf_embedding
from PathRAG.utils import EmbeddingFunc
from transformers import AutoTokenizer, AutoModel

rag = PathRAG(
    working_dir="./hf_data",
    llm_model_func=hf_model_complete,
    llm_model_name="Qwen/Qwen3-0.6B",
    embedding_func=EmbeddingFunc(
        embedding_dim=384,
        max_token_size=5000,
        func=lambda texts: hf_embedding(
            texts,
            tokenizer=AutoTokenizer.from_pretrained("sentence-transformers/all-MiniLM-L6-v2"),
            embed_model=AutoModel.from_pretrained("sentence-transformers/all-MiniLM-L6-v2"),
        ),
    ),
)
```

--------------------------------

### Backend Project Structure

Source: https://github.com/bupt-gamma/pathrag/blob/main/README.md

Overview of the backend directory structure for the PathRAG application, detailing modules for authentication, features, and models.

```tree
/api
  /auth - Authentication module
    - jwt_handler.py - JWT token handling
    - routes.py - Authentication endpoints
    - schemas.py - Authentication data models
  /features - Feature modules
    /users - User management
    /chats - Chat functionality
    /documents - Document management
    /knowledge_graph - Knowledge graph functionality
/models - Database models
  - database.py - SQLite database setup and models
main.py - Main application entry point
```

--------------------------------

### Configure PathRAG with Ollama Backend

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Configure PathRAG to use locally-hosted Ollama models for LLM and embeddings. Ensure Ollama is running and accessible at the specified host.

```python
import os
from PathRAG import PathRAG, QueryParam
from PathRAG.llm import ollama_model_complete, ollama_embedding
from PathRAG.utils import EmbeddingFunc

rag = PathRAG(
    working_dir="./ollama_data",
    llm_model_func=ollama_model_complete,
    llm_model_name="qwen3:0.6b",
    llm_model_max_token_size=8192,
    llm_model_kwargs={
        "host": "http://localhost:11434",
        "options": {"num_ctx": 8192},
        "timeout": 300,
    },
    embedding_func=EmbeddingFunc(
        embedding_dim=1024,
        max_token_size=8192,
        func=lambda texts: ollama_embedding(
            texts,
            embed_model="bge-large",
            host="http://localhost:11434",
        ),
    ),
)

# Query using Ollama backend
response = asyncio.run(rag.aquery("What is PathRAG?", param=QueryParam(mode="hybrid")))
```

--------------------------------

### Authenticate User via REST API (Login)

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Authenticate a user by sending POST request with username and password to the /token endpoint. The response contains a JWT access token.

```bash
# Login with form data
curl -X POST "http://localhost:8000/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=user1&password=Pass@123"

# Response:
# {
#   "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
#   "token_type": "bearer"
# }

# Store token for subsequent requests
export TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Clone PathRAG Repository

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Clone the PathRAG repository and navigate into the project directory.

```bash
git clone <repository-url>
cd pathrag
```

--------------------------------

### Local Model Integration for PathRAG

Source: https://github.com/bupt-gamma/pathrag/blob/main/examples.txt

Set up PathRAG to utilize local LLM and embedding models. This requires specifying the local path to the model files.

```python
rag = PathRAG(
    working_dir=WORKING_DIR,
    llm_model_func=local_model_complete,
    llm_model_name="./modelscope/Qwen3-0.6B",
    embedding_func=EmbeddingFunc(
        embedding_dim=384,
        max_token_size=5000,
        func=lambda texts: local_embedding(
            texts,
            tokenizer=AutoTokenizer.from_pretrained("./modelscope/all-MiniLM-L6-v2"),
            embed_model=AutoModel.from_pretrained("./modelscope/all-MiniLM-L6-v2"),
        ),
    ),
)
```

--------------------------------

### Systemd Service Configuration for Uvicorn

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Configure a systemd service for running PathRAG directly with Uvicorn. This provides robust process management and automatic restarts.

```ini
[Unit]
Description=PathRAG API
After=network.target

[Service]
User=your_user
Group=your_group
WorkingDirectory=/path/to/pathrag
Environment="PATH=/path/to/pathrag/.venv/bin"
EnvironmentFile=/path/to/pathrag/.env
ExecStart=/path/to/pathrag/.venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
Restart=always
RestartSec=5
StartLimitIntervalSec=0

# Security options
PrivateTmp=true
ProtectSystem=full
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Chat Threads - Create Thread

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Create a new chat thread. The request body must be JSON and include a 'title' for the thread. Requires authentication.

```bash
curl -X POST "http://localhost:8000/chats/threads" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Research Discussion"}'
```

--------------------------------

### Run PathRAG with Uvicorn Directly

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Run the application directly with Uvicorn in production mode. This method is platform-independent and can be managed by process managers like Supervisor or PM2.

```bash
# Production mode (no auto-reload)
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

# With process manager like Supervisor or PM2
# Example supervisor config:
# [program:pathrag]
# command=/path/to/venv/bin/uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
# directory=/path/to/pathrag
# user=www-data
# autostart=true
# autorestart=true
```

--------------------------------

### Insert Custom Knowledge Graph

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Insert pre-defined entities and relationships into the knowledge graph. Ensure the custom_kg dictionary is correctly structured with 'chunks', 'entities', and 'relationships'.

```python
import asyncio

custom_kg = {
    "chunks": [
        {
            "content": "Machine learning is a subset of artificial intelligence.",
            "source_id": "ml_intro_001"
        }
    ],
    "entities": [
        {
            "entity_name": "Machine Learning",
            "entity_type": "CONCEPT",
            "description": "A subset of AI focusing on learning from data",
            "source_id": "ml_intro_001"
        },
        {
            "entity_name": "Artificial Intelligence",
            "entity_type": "CONCEPT",
            "description": "The simulation of human intelligence by machines",
            "source_id": "ml_intro_001"
        }
    ],
    "relationships": [
        {
            "src_id": "Machine Learning",
            "tgt_id": "Artificial Intelligence",
            "description": "Machine Learning is a subset of Artificial Intelligence",
            "keywords": "subset, part of, belongs to",
            "weight": 1.0,
            "source_id": "ml_intro_001"
        }
    ]
}

asyncio.run(rag.ainsert_custom_kg(custom_kg))
```

--------------------------------

### Production Environment Variables Configuration

Source: https://github.com/bupt-gamma/pathrag/blob/main/INSTALLATION.md

Configure production-specific environment variables in a .env file. Consider using a secrets management service for enhanced security.

```dotenv
SECRET_KEY=your_very_strong_production_secret_key
ACCESS_TOKEN_EXPIRE_MINUTES=60

DATABASE_URL=sqlite:///./pathrag_prod.db

CORS_ORIGINS=https://your-production-domain.com

WORKING_DIR=/var/lib/pathrag/data
UPLOAD_DIR=/var/lib/pathrag/uploads
```

--------------------------------

### Upload Document to Neo4j

Source: https://context7.com/bupt-gamma/pathrag/llms.txt

Uploads a document to Neo4j for knowledge graph operations. Requires authentication and specifies Neo4j connection details.

```bash
curl -X POST "http://localhost:8000/documents/neo4j_upload" \
  -H "Authorization: Bearer $TOKEN" \
  -F "uri=bolt://localhost:7687" \
  -F "username=neo4j" \
  -F "password=password123" \
  -F "database=neo4j" \
  -F "file=@document.pdf"
```