{"repo": "bupt-gamma/pathrag", "files": {"README.md": {"32567bfc93605b8393996d5fa9ccdc0edbb865b2": {"t": 1785674436.0745544, "n": 20488, "h": "4f5b058ed2c03bc1", "c": "# PathRAG - Knowledge Graph-based RAG System\n\nThis PathRAG Demo App is a comprehensive knowledge graph-based Retrieval-Augmented Generation (RAG) system that combines document processing, chat functionality, and knowledge graph visualization in a single application.\n\n## What is PathRAG?\n\nPathRAG (Path-based Retrieval Augmented Generation) is an advanced approach to knowledge retrieval and generation that combines the power of knowledge graphs with large language models (LLMs).\n\n### Core Concepts\n\n#### Knowledge Graph Integration\nPathRAG builds and maintains a knowledge graph from your documents, where:\n- **Nodes** represent entities (people, organizations, concepts, locations, etc.)\n- **Edges** represent relationships between these entities\n- **Properties** store additional information about entities and relationships\n\n#### Path-based Retrieval\nUnlike traditional RAG systems that rely solely on vector similarity:\n1. PathRAG identifies relevant paths through the knowledge graph\n2. These paths provide contextual connections between entities\n3. The system can follow logical relationships to find information not directly mentioned\n\n#### Hybrid Search\nPathRAG combines multiple search strategies:\n- **Vector search** for semantic similarity\n- **Graph traversal** for relationship-based connections\n- **Entity-centric retrieval** for focused information about specific entities\n\n#### Advantages Over Traditional RAG\n- **Relational understanding**: Captures relationships between concepts, not just similarity\n- **Explainability**: Provides clear paths showing how information is connected\n- **Reduced hallucinations**: Grounds responses in explicit knowledge connections\n- **Complex reasoning**: Can answer multi-hop questions requiring several logical steps\n\n### How PathRAG Works\n\n1. **Document Processing**:\n   - Documents are chunked into manageable pieces\n   - Entities and relationships are extracted using NLP techniques\n   - A knowledge graph is constructed connecting these entities\n\n2. **Query Processing**:\n   - User queries are analyzed to identify key entities and intents\n   - The system identifies relevant paths in the knowledge graph\n   - Both vector similarity and graph structure are used to retrieve information\n\n3. **Response Generation**:\n   - Retrieved context from multiple paths is synthesized\n   - The LLM generates responses grounded in this structured knowledge\n   - Responses include information from across the knowledge graph\n\n## Features\n\n### Core Functionality\n- **Document Management**: Upload, process, and manage documents (PDF, DOCX, MD, TXT, HTML, etc.)\n- **Chat Interface**: Thread-based chat system with context-aware responses\n- **Knowledge Graph**: Visualize and query the knowledge graph built from your documents\n- **User Management**: User authentication and personalization\n\n### Technical Features\n- **React Frontend**: Modern UI built with React and RSuite components\n- **FastAPI Backend**: High-performance Python API with async support\n- **SQLite Database**: Lightweight database for storing user data, chat threads, and document metadata\n- **Thread-Based Chat**: Persistent chat threads with unique IDs\n- **Document Processing**: Automatic extraction of text and entities from various document formats\n- **Knowledge Graph Visualization**: Interactive visualization using D3.js\n- **Theme Customization**: Customizable UI themes (blue, red, violet)\n- **Automatic Document Reloading**: System checks document status every 15 seconds and automatically reloads when processing completes\n\n## Tech Stack\n\n### Backend\n- **FastAPI**: Modern, fast web framework for building APIs\n- **SQLite**: Lightweight database for storing users, chats, and documents\n- **JWT**: JSON Web Tokens for authentication\n- **PathRAG**: Path-based Retrieval Augmented Generation for knowledge graph and chat functionality\n- **NetworkX**: Graph data structure and algorithms (for development/demo)\n- **NanoVectorDB**: Local file-based vector storage (for development/demo)\n\n### Frontend\n- **React**: JavaScript library for building user interfaces\n- **RSuite**: UI component library with responsive design\n- **D3.js**: Data visualization library for knowledge graph\n- **React Router**: Navigation and routing\n- **Axios**: HTTP client for API requests\n- **React Dropzone**: Drag-and-drop file upload\n- **Font Awesome**: Icon library\n\n## Project Structure\n\n### Backend\n```\n/api\n  /auth - Authentication module\n    - jwt_handler.py - JWT token handling\n    - routes.py - Authentication endpoints\n    - schemas.py - Authentication data models\n  /features - Feature modules\n    /users - User management\n    /chats - Chat functionality\n    /documents - Document management\n    /knowledge_graph - Knowledge graph functionality\n/models - Database models\n  - database.py - SQLite database setup and models\nmain.py - Main application entry point\n```\n\n### Frontend\n```\n/pathrag-ui\n  /public - Static files\n  /src\n    /components - Reusable components\n      /auth - Authentication components\n      /chat - Chat components\n      /documents - Document components\n      /knowledge-graph - Knowledge graph components\n    /context - React context providers\n    /pages - Application pages\n    /services - API services\n    /utils - Utility functions\n    App.js - Main application component\n    index.js - Application entry point\n```\n\n## Setup Instructions\n\n### Prerequisites\n- Python 3.8+\n- Node.js 14+\n- npm or yarn\n\n### Quick Start (Recommended)\n#### Command Line (Without GUI)\nPython Version: Python 3.10.18\n```bash\ncd PathRAG\npip install -e .\n```\n- Use OpenAI API key\n- You can quickly experience this project in the `v1_test.py` file.\n- Set OpenAI API key in environment if using OpenAI models: `api_key=\"sk-...\".` in the `v1_test.py` and `llm.py` file.\n- Prepare your retrieval document \"text.txt\".\n- Use the following Python snippet in the `v1_test.py` file to initialize PathRAG and perform queries.\n  \n```python\nimport os\nfrom PathRAG import PathRAG, QueryParam\nfrom PathRAG.llm import gpt_4o_mini_complete\n\nWORKING_DIR = \"./your_working_dir\"\napi_key=\"your_api_key\"\nos.environ[\"OPENAI_API_KEY\"] = api_key\nbase_url=\"https://api.openai.com/v1\"\nos.environ[\"OPENAI_API_BASE\"]=base_url\n\n\nif not os.path.exists(WORKING_DIR):\n    os.mkdir(WORKING_DIR)\n\nrag = PathRAG(\n    working_dir=WORKING_DIR,\n    llm_model_func=gpt_4o_mini_complete,  \n)\n\ndata_file=\"./text.txt\"\nquestion=\"your_question\"\nwith open(data_file) as f:\n    rag.insert(f.read())\n\nprint(rag.query(question, param=QueryParam(mode=\"hybrid\")))\n```\n##### Quick Start with models from different sources\n- You can use the model from huggingface, ollama, modelscope, local and vllm.\n- You can quickly experience this project in the `rag_test.py` file.\n- Select your model source—— hf / vllm / ollama / ms / local.\n- Prepare your llm_model，embedding_model and  retrieval document \"your data file\" . \n- Use the following Python snippet in the `rag_test.py` file to use models from different sources.\n- Detailed examples can be referred to `examples.txt`.\n\n```Python\nimport os\nimport asyncio\nimport torch\nfrom PathRAG.RAGRunner import RAGRunner\nif __name__ == \"__main__\":\n\tbackend = \"your_model_source\" # hf / vllm / ollama / ms / local\n\tworking_dir = f\"your_working_dir\" \n\tllm_model_name = \"Qwen/Qwen3-0.6B\" # model name or path of model\n\tembedding_model_name = \"iic/nlp_corom_sentence-embedding_english-base\" # embedding model name or path ofembedding model\n\t# ollama additional parameters\n\tllm_model_kwargs = {\n\t\"host\": \"http://localhost:11434\",\n\t\"options\": {\"num_ctx\": 8192},\n\t\"timeout\": 300,\n\t} if backend == \"ollama\" else {}\n\t\n\trunner = RAGRunner(\n\t\tbackend=backend,\n\t\tworking_dir=working_dir,\n\t\tllm_model_name=llm_model_name,\n\t\tembedding_model_name=embedding_model_name,\n\t\tllm_model_max_token_size=8192,\n\t\tllm_model_kwargs=llm_model_kwargs,\n\t\tembedding_dim=768,\n\t\tembedding_max_token_size=5000,\n\t)\n\tdata_file = \"your_data_file\"\n\tquestion = \"your_question\"\n\twith open(data_file, \"r\", encoding=\"utf-8\") as f:\n\t\trunner.insert_text(f.read())\n\tanswer = runner.query(question, mode=\"hybrid\")\n\tprint(\"question:\", question)\n\tprint(\"answer:\", answer)\n```\n\n##### Parameter modification\nYou can adjust the relevant parameters in the `base.py` and `operate.py` files.\n- You can change the hyperparameter `top_k` in `base.py`, where `top_k` represents the number of nodes retrieved\n- You can change the hyperparameters `alpha` and `threshold` in `operate.py`, where `alpha` represents the decay rate of information propagation along the edges, and `threshold` is the pruning threshold.\n##### Batch Insert\n```python\nimport os\nfolder_path = \"your_folder_path\"  \n\ntxt_files = [f for f in os.listdir(folder_path) if f.endswith(\".txt\")]\nfor file_name in txt_files:\n    file_path = os.path.join(folder_path, file_name)\n    with open(file_path, \"r\", encoding=\"utf-8\") as file:\n        rag.insert(file.read())\n```\n\n#### Evaluation\n\n##### Dataset\nThe dataset used in PathRAG can be downloaded from [TommyChien/UltraDomain](https://huggingface.co/datasets/TommyChien/UltraDomain).\n##### Eval Metrics\n<details>\n<summary> Prompt </summary>\n  \n```python\nYou will evaluate two answers to the same question based on five criteria: **Comprehensiveness**, **Diversity**, **logicality**, **Coherence**, **Relevance**.\n\n- **Comprehensiveness**: How much detail does the answer provide to cover all aspects and details of the question?\n- **Diversity**: How varied and rich is the answer in providing different perspectives and insights on the question?\n- **logicality**: How logically does the answer respond to all parts of the question?\n- **Coherence**: How well does the answer maintain internal logical connections between its parts, ensuring a smooth and consistent structure?\n- **Relevance**: How relevant is the answer to the question, staying focused and addressing the intended topic or issue?\n\nFor each criterion, choose the better answer (either Answer 1 or Answer 2) and explain why.\n\nHere is the question:\n{query}\n\nHere are the two answers:\n**Answer 1:**\n{answer1}\n\n**Answer 2:**\n{answer2}\n\nEvaluate both answers using the five criteria listed above and provide detailed explanations for each criterion.\n\nOutput your evaluation in the following JSON format:\n{{\n  \"Comprehensiveness\": {{\n    \"Winner\": \"[Answer 1 or Answer 2]\",\n    \"Explanation\": \"[Provide explanation here]\"\n  }},\n  \"Diversity\": {{\n    \"Winner\": \"[Answer 1 or Answer 2]\",\n    \"Explanation\": \"[Provide explanation here]\"\n  }},\n  \"logicality\": {{\n    \"Winner\": \"[Answer 1 or Answer 2]\",\n    \"Explanation\": \"[Provide explanation here]\"\n  }},\n  \"Coherence\": {{\n    \"Winner\": \"[Answer 1 or Answer 2]\",\n    \"Explanation\": \"[Provide explanation here]\"\n  }},\n  \"Relevance\": {{\n    \"Winner\": \"[Answer 1 or Answer 2]\",\n    \"Explanation\": \"[Provide explanation here]\"\n  }}\n}}\n```\n</details>\n\n#### With GUI\n##### Starting the API\n\nUse our start script to set up and run the API:\n\n**For Unix/Linux/macOS:**\n```bash\n# Make the script executable (first time only)\nchmod +x start-api.sh\n\n# Run the API\n./start-api.sh\n```\n\n**For Windows:**\n```bash\n# Run the API\nstart-api.bat\n```\n\nThese scripts will:\n1. Create a Python virtual environment named `.venv` if it doesn't exist\n2. Install all backend dependencies\n3. Start the backend API on port 8000\n\nThe API will be available at:\n- Backend API: http://localhost:8000\n- API Documentation: http://localhost:8000/docs\n\n##### Starting the UI\n\nNavigate to the UI directory and start the React application:\n\n```bash\n# Navigate to the UI directory\ncd ui\n\n# Install dependencies (first time only)\nnpm install\n\n# Start the UI\nnpm start\n```\n\nThe UI will be available at:\n- Frontend UI: http://localhost:3000\n\n### Manual Setup\n\nIf you prefer to set up and run the components separately, follow these instructions:\n\n#### Backend Setup\n1. Create and activate a virtual environment:\n   ```bash\n   # Create virtual environment\n   python -m venv .venv\n\n   # Activate on Windows\n   .venv\\Scripts\\activate\n\n   # Activate on macOS/Linux\n   source .venv/bin/activate\n   ```\n\n2. Install Python dependencies:\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. Configure environment variables:\n   Copy the sample environment file and modify it with your settings:\n   ```bash\n   cp sample.env .env\n   # Edit .env with your preferred text editor\n   ```\n\n   Key environment variables include:\n   ```\n   # JWT Authentication\n   SECRET_KEY=your_secret_key_here  # Generate with: openssl rand -hex 32\n   ACCESS_TOKEN_EXPIRE_MINUTES=30\n\n   # Application Directories\n   WORKING_DIR=./data\n   UPLOAD_DIR=./uploads\n\n   # Database Configuration\n   DATABASE_URL=sqlite:///./pathrag.db\n\n   # Server Configuration\n   HOST=0.0.0.0\n   PORT=8000\n   DEBUG=False\n   LOG_LEVEL=info\n   CORS_ORIGINS=http://localhost:3000\n\n   # AI Model Settings (choose one option)\n   # Option 1: Azure OpenAI\n   AZURE_OPENAI_API_KEY=your_azure_key\n   AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com\n   AZURE_OPENAI_DEPLOYMENT=gpt-4o\n   AZURE_OPENAI_API_VERSION=2023-05-15\n   AZURE_EMBEDDING_DEPLOYMENT=text-embedding-3-large\n\n   # Option 2: OpenAI direct\n   OPENAI_API_KEY=your_openai_key\n   OPENAI_API_BASE=https://api.openai.com/v1\n\n   # PathRAG Configuration\n   CHUNK_SIZE=1200\n   CHUNK_OVERLAP=100\n   MAX_TOKENS=32768\n   TEMPERATURE=0.7\n   TOP_K=40\n   ```\n\n   See [INSTALLATION.md](INSTALLATION.md) for detailed environment variable configuration and [sample.env](sample.env) for a complete example.\n\n4. Start the backend server:\n   ```bash\n   python main.py\n   ```\n\n   The API will be available at http://localhost:8000\n\n   For more advanced options, see [INSTALLATION.md](INSTALLATION.md).\n\n5. API Documentation:\n   - Swagger UI: http://localhost:8000/docs\n   - ReDoc: http://localhost:8000/redoc\n\n#### Frontend Setup\n1. Navigate to the frontend directory:\n   ```bash\n   cd ui\n   ```\n\n2. Install dependencies:\n   ```bash\n   npm install\n   ```\n\n3. Start the development server:\n   ```bash\n   npm start\n   ```\n\n   The application will be available at http://localhost:3000\n\n## Usage\n\n### Authentication\n- Use the default credentials to log in:\n  - Username: user1, Password: Pass@123\n  - Username: user2, Password: Pass@123\n  - Username: user3, Password: Pass@123\n- Or register a new account using the registration form\n\n### Chat Threads\n1. Navigate to the Chat page\n2. Click \"New Chat\" to start a new thread\n3. Type your message in the input field\n4. Press Enter or click the send button\n5. View the AI response\n6. Your chat threads are saved and can be accessed from the sidebar\n7. Each thread has a unique ID and maintains its own conversation history\n8. Thread titles are automatically updated based on the first message\n\n### Knowledge Graph\n1. Navigate to the Knowledge Graph page\n2. Enter a query in the search field to filter the graph\n3. Interact with the graph by dragging nodes\n4. Zoom in/out using the mouse wheel\n5. Click on nodes to see entity details\n\n### Document Management\n1. Navigate to the Documents page\n2. Click \"Upload Document\" button\n3. Drag and drop a file or click to select a file\n4. Monitor the upload progress\n5. The system automatically checks document status every 15 seconds\n6. When processing completes, the system automatically reloads the PathRAG instance\n7. You can also manually reload the PathRAG instance by clicking the \"Reload Documents\" button\n8. View the uploaded documents in the list with their processing status\n\n## Data Models\n\n### User\n- `id`: Integer (Primary Key)\n- `username`: String (Unique)\n- `email`: String (Unique)\n- `hashed_password`: String\n- `created_at`: DateTime\n- `theme`: String (Default: \"blue\")\n\n### Thread\n- `id`: Integer (Primary Key)\n- `uuid`: String (Unique)\n- `user_id`: Integer (Foreign Key to User)\n- `title`: String\n- `created_at`: DateTime\n- `updated_at`: DateTime\n- `is_deleted`: Boolean (Default: False)\n\n### Chat\n- `id`: Integer (Primary Key)\n- `user_id`: Integer (Foreign Key to User)\n- `thread_id`: Integer (Foreign Key to Thread)\n- `role`: String ('user' or 'system')\n- `message`: Text\n- `created_at`: DateTime\n\n### Document\n- `id`: Integer (Primary Key)\n- `user_id`: Integer (Foreign Key to User)\n- `filename`: String\n- `content_type`: String\n- `file_path`: String\n- `file_size`: Integer\n- `uploaded_at`: DateTime\n- `status`: String\n- `processed_at`: DateTime (Nullable)\n- `error_message`: Text (Nullable)\n\n## API Endpoints\n\n### Authentication\n- `POST /token`: Login and get access token\n- `POST /register`: Register a new user\n- `GET /users/me`: Get current user information\n\n### Users\n- `GET /users/`: Get all users\n- `POST /users/theme`: Update user theme\n\n### Chat Threads\n- `GET /chats/threads`: Get all chat threads\n- `POST /chats/threads`: Create a new chat thread\n- `GET /chats/threads/{thread_uuid}`: Get a specific thread with all its chats\n- `PUT /chats/threads/{thread_uuid}`: Update a thread's title\n- `DELETE /chats/threads/{thread_uuid}`: Mark a thread as deleted\n\n### Chats\n- `GET /chats/`: Get all chats\n- `GET /chats/recent`: Get the 5 most recent chat threads\n- `POST /chats/chat/{thread_uuid}`: Create a new chat message in a thread\n\n### Documents\n- `GET /documents/`: Get all documents\n- `POST /documents/upload`: Upload a document\n- `GET /documents/{document_id}`: Get a specific document\n- `GET /documents/{document_id}/status`: Get document processing status\n- `POST /documents/reload`: Reload the PathRAG instance to recognize new documents\n\n### Knowledge Graph\n- `GET /knowledge-graph/`: Get the knowledge graph\n- `POST /knowledge-graph/query`: Query the knowledge graph\n\n## Storage Options\n\n### Demo/Development (Default)\n- **Vector Storage**: NanoVectorDB (local file-based vector store)\n- **Graph Storage**: NetworkX (local in-memory graph)\n- **Key-Value Storage**: JsonKVStorage (local file-based storage)\n\n> **Note**: These storage options are suitable for demonstration and development purposes only. They are not recommended for production use with large datasets or high traffic.\n\n### Production Options\nFor production environments, consider using these alternatives:\n- **Vector Databases**: PostgreSQL (pgvector), Pinecone, DataStax, Azure Cognitive Search, Azure SQL(Preview)\n- **Graph Databases**: Neo4j, ArangoDB, Apache AGE (PostgreSQL extension), CosmosDB, Azure SQL\n- **Document Databases**: MongoDB, Cassandra, CosmosDB\n\n## License\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Use Cases\n\nPathRAG is particularly effective for:\n\n### Knowledge-Intensive Applications\n- **Research assistance**: Connecting findings across multiple papers and sources\n- **Legal document analysis**: Identifying relationships between cases, statutes, and legal concepts\n- **Medical knowledge systems**: Connecting symptoms, conditions, treatments, and research\n\n### Complex Information Retrieval\n- **Multi-hop question answering**: \"What treatments were developed based on research by scientists who studied under Marie Curie?\"\n- **Contextual understanding**: Understanding how different parts of a document relate to each other\n- **Exploratory research**: Discovering unexpected connections between concepts\n\n### Enterprise Knowledge Management\n- **Corporate knowledge bases**: Connecting information across departments and documents\n- **Compliance and regulation**: Tracking relationships between policies, regulations, and procedures\n- **Institutional memory**: Preserving and accessing organizational knowledge\n\n## Limitations and Considerations\n\n- **Knowledge graph quality**: The system's effectiveness depends on the quality of entity and relationship extraction\n- **Computational complexity**: Graph operations can be more resource-intensive than simple vector searches\n- **Domain specificity**: May require domain-specific entity extraction for specialized fields\n- **Storage limitations**: The default storage options (NanoVectorDB, NetworkX) are not suitable for large-scale production use\n\n## Authors & Contributors\n\n### PathRAG Core Logic Research Team\n- Boyu Chen¹, Zirui Guo², Zidan Yang¹, Yuluo Chen¹, Junze Chen¹, Zhenghao Liu³, Chuan Shi¹, Cheng Yang¹\n  1. Beijing University of Posts and Telecommunications\n  2. University of Hong Kong\n  3. Northeastern University\n\n  Contact: chenbys4@bupt.edu.cn, yangcheng@bupt.edu.cn\n\n### Demo Application Contributor\n- Robert Dennyson, Solution Architect, UK\n- Contact: robertdennyson@live.in\n\n## Acknowledgements\n- PathRAG for the knowledge graph and retrieval augmented generation capabilities\n- RSuite for the UI components\n- D3.js for the knowledge graph visualization\n"}}}}