WIP: Merge Dev to Main

.gitignore

@@ -55,7 +55,7 @@ output/
 rag_storage/
 data/
 
-# Runtime-provided entity type prompt profiles (keep sample files only)
+# User cumstomized prompt directory
 prompts/entity_type/
 
 # Evaluation results
@@ -78,14 +78,10 @@ ignore_this.txt
 # temporary test files in project root
 /test_*
 
-# Cline files
+# AI Agent files
 memory-bank
-.claude/CLAUDE.md
 .claude/
 
-# Claude Code
-CLAUDE.md
-
 # Google Jules
 .jules/
 

CLAUDE.md

@@ -1,346 +1 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-LightRAG is a Retrieval-Augmented Generation (RAG) framework that uses graph-based knowledge representation for enhanced information retrieval. The system extracts entities and relationships from documents, builds a knowledge graph, and uses multi-modal retrieval (local, global, hybrid, mix, naive) for queries.
-
-## Core Architecture
-
-### Key Components
-
-- **lightrag.py**: Main orchestrator class (`LightRAG`) that coordinates document insertion, query processing, and storage management. Critical: Always call `await rag.initialize_storages()` after instantiation.
-
-- **operate.py**: Core extraction and query operations including entity/relation extraction, chunking, and multi-mode retrieval logic.
-
-- **base.py**: Abstract base classes for storage backends (`BaseKVStorage`, `BaseVectorStorage`, `BaseGraphStorage`, `BaseDocStatusStorage`).
-
-- **kg/**: Storage implementations (JSON, NetworkX, Neo4j, PostgreSQL, MongoDB, Redis, Milvus, Qdrant, Faiss, Memgraph). Each storage type provides different trade-offs for production vs. development use.
-
-- **llm/**: LLM provider bindings (OpenAI, Ollama, Azure, Gemini, Bedrock, Anthropic, etc.). All use async patterns with caching support.
-
-- **api/**: FastAPI server (`lightrag_server.py`) with REST endpoints and Ollama-compatible API, plus React 19 + TypeScript WebUI.
-
-### Storage Layer
-
-LightRAG uses 4 storage types with pluggable backends:
-- **KV_STORAGE**: LLM response cache, text chunks, document info
-- **VECTOR_STORAGE**: Entity/relation/chunk embeddings
-- **GRAPH_STORAGE**: Entity-relation graph structure
-- **DOC_STATUS_STORAGE**: Document processing status tracking
-
-Workspace isolation is implemented differently per storage type (subdirectories for file-based, prefixes for collections, fields for relational DBs).
-
-### Query Modes
-
-- **local**: Context-dependent retrieval focused on specific entities
-- **global**: Community/summary-based broad knowledge retrieval
-- **hybrid**: Combines local and global
-- **naive**: Direct vector search without graph
-- **mix**: Integrates KG and vector retrieval (recommended with reranker)
-
-## Development Commands
-
-### Setup
-```bash
-# Install core package (development mode)
-uv sync
-source .venv/bin/activate  # Or: .venv\Scripts\activate on Windows
-
-# Install with API support
-uv sync --extra api
-
-# Install specific extras
-uv sync --extra offline-storage  # Storage backends
-uv sync --extra offline-llm      # LLM providers
-uv sync --extra test             # Testing dependencies
-```
-
-### API Server
-```bash
-# Copy and configure environment
-cp env.example .env  # Edit with your LLM/embedding configs
-
-# Build WebUI
-cd lightrag_webui
-bun install --frozen-lockfile
-bun run build
-cd ..
-
-# Run server
-lightrag-server                                           # Production
-uvicorn lightrag.api.lightrag_server:app --reload        # Development
-lightrag-gunicorn                                         # Multi-worker (gunicorn)
-```
-
-### Testing
-```bash
-# Run offline tests (default)
-python -m pytest tests
-
-# Run integration tests (requires external services)
-python -m pytest tests --run-integration
-# Or set: LIGHTRAG_RUN_INTEGRATION=true
-
-# Run specific test file
-python test_graph_storage.py
-
-# Keep artifacts for debugging
-python -m pytest tests --keep-artifacts
-
-# Run with custom workers
-python -m pytest tests --test-workers 4
-```
-
-### Linting
-```bash
-ruff check .
-```
-
-## Key Implementation Patterns
-
-### LightRAG Initialization (Critical)
-
-The most common error is forgetting to initialize storages:
-
-```python
-import asyncio
-from lightrag import LightRAG
-from lightrag.llm.openai import gpt_4o_mini_complete, openai_embed
-
-async def main():
-    rag = LightRAG(
-        working_dir="./rag_storage",
-        llm_model_func=gpt_4o_mini_complete,
-        embedding_func=openai_embed
-    )
-
-    # REQUIRED: Initialize storage backends
-    await rag.initialize_storages()
-
-    # Now safe to use
-    await rag.ainsert("Your text here")
-    result = await rag.aquery("Your question", param=QueryParam(mode="hybrid"))
-
-    # Cleanup
-    await rag.finalize_storages()
-
-asyncio.run(main())
-```
-
-### Custom Embedding Functions
-
-Use `@wrap_embedding_func_with_attrs` decorator and call `.func` when wrapping:
-
-```python
-from lightrag.utils import wrap_embedding_func_with_attrs
-
-@wrap_embedding_func_with_attrs(embedding_dim=1536, max_token_size=8192)
-async def custom_embed(texts: list[str]) -> np.ndarray:
-    # Call underlying function, not wrapped version
-    return await openai_embed.func(texts, model="text-embedding-3-large")
-```
-
-### Storage Configuration
-
-Configure via environment variables or constructor params:
-
-```python
-# Environment-based (recommended for production)
-# See env.example for full list
-
-# Constructor-based
-rag = LightRAG(
-    working_dir="./storage",
-    workspace="project_name",  # For data isolation
-    kv_storage="PGKVStorage",
-    vector_storage="PGVectorStorage",
-    graph_storage="Neo4JStorage",
-    doc_status_storage="PGDocStatusStorage",
-    vector_db_storage_cls_kwargs={
-        "cosine_better_than_threshold": 0.2
-    }
-)
-```
-
-### Document Insertion
-
-```python
-# Single document
-await rag.ainsert("Text content")
-
-# Batch insertion
-await rag.ainsert(["Text 1", "Text 2", ...])
-
-# With custom IDs
-await rag.ainsert("Text", ids=["doc-123"])
-
-# With file paths (for citation)
-await rag.ainsert(["Text 1", "Text 2"], file_paths=["doc1.pdf", "doc2.pdf"])
-
-# Configure batch size
-rag = LightRAG(..., max_parallel_insert=4)  # Default: 2, max recommended: 10
-```
-
-### Query Configuration
-
-```python
-from lightrag import QueryParam
-
-result = await rag.aquery(
-    "Your question",
-    param=QueryParam(
-        mode="mix",                    # Recommended with reranker
-        top_k=60,                      # KG entities/relations to retrieve
-        chunk_top_k=20,                # Text chunks to retrieve
-        max_entity_tokens=6000,
-        max_relation_tokens=8000,
-        max_total_tokens=30000,
-        enable_rerank=True,
-        user_prompt="Additional instructions for LLM",
-        stream=False
-    )
-)
-```
-
-## WebUI Development
-
-### Structure
-- `lightrag_webui/src/`: React components (TypeScript)
-- Uses Vite + Bun build system
-- Tailwind CSS for styling
-- React 19 with functional components and hooks
-
-### Commands
-```bash
-cd lightrag_webui
-bun install --frozen-lockfile  # Install dependencies
-bun run dev                    # Development server (Node + Vite)
-bun run dev:bun                # Development server (Bun native)
-bun run build                  # Production build
-bun run preview                # Preview production build locally
-
-# Linting (ESLint with TypeScript, React hooks, Stylistic rules)
-bun run lint                   # Run ESLint on all *.ts/tsx/js/jsx files
-
-# Testing (Bun built-in test runner)
-bun test                       # Run all tests
-bun test --watch               # Watch mode
-bun test --coverage            # With coverage report
-bun test src/api/lightrag.test.ts  # Run a single test file
-```
-
-### Lint Rules
-ESLint is configured with TypeScript-ESLint, React Hooks plugin, Prettier integration, and `@stylistic` rules:
-- 2-space indentation, single quotes enforced
-- `@typescript-eslint/no-explicit-any` is disabled (allowed)
-
-## Common Issues
-
-### 1. Storage Not Initialized
-**Error**: `AttributeError: __aenter__` or `KeyError: 'history_messages'`
-**Solution**: Always call `await rag.initialize_storages()` after creating LightRAG instance
-
-### 2. Embedding Model Changes
-When switching embedding models, you MUST clear the data directory (except optionally `kv_store_llm_response_cache.json` for LLM cache).
-
-### 3. Nested Embedding Functions
-Cannot wrap already-decorated embedding functions. Use `.func` to access underlying function:
-```python
-# Wrong: EmbeddingFunc(func=openai_embed)
-# Right: EmbeddingFunc(func=openai_embed.func)
-```
-
-### 4. Context Length for Ollama
-Ollama models default to 8k context; LightRAG requires 32k+. Configure via:
-```python
-llm_model_kwargs={"options": {"num_ctx": 32768}}
-```
-
-## Configuration Files
-
-### .env Configuration
-Primary configuration file for API server. Key sections:
-- Server settings (HOST, PORT, CORS)
-- Storage backends (connection strings via environment variables)
-- Query parameters (TOP_K, MAX_TOTAL_TOKENS, etc.)
-- Reranking configuration (RERANK_BINDING, RERANK_MODEL)
-- Authentication (AUTH_ACCOUNTS, LIGHTRAG_API_KEY)
-
-See `env.example` for comprehensive template.
-
-### Workspace Isolation
-Each LightRAG instance can use a `workspace` parameter for data isolation. Implementation varies by storage type:
-- File-based: subdirectories
-- Collection-based: collection name prefixes
-- Relational DB: workspace column filtering
-- Qdrant: payload-based partitioning
-
-## Testing Guidelines
-
-### Test Structure
-- `tests/`: Main test suite (mirrors feature folders)
-- `test_*.py` in root: Specific integration tests
-- Markers: `offline`, `integration`, `requires_db`, `requires_api`
-
-### Running Tests
-```bash
-# Default: runs only offline tests
-pytest tests
-
-# Include integration tests
-pytest tests --run-integration
-
-# Keep test artifacts for debugging
-pytest tests --keep-artifacts
-
-# Configure test workers
-pytest tests --test-workers 4
-```
-
-### Environment Variables for Tests
-Set `LIGHTRAG_*` variables for integration tests:
-- `LIGHTRAG_RUN_INTEGRATION=true`
-- `LIGHTRAG_KEEP_ARTIFACTS=true`
-- `LIGHTRAG_TEST_WORKERS=4`
-- Plus storage-specific connection strings
-
-## Code Style
-
-### Language
-- Comment Language - Use English for comments and documentation
-- Backend Language - Use English for backend code and messages
-- Frontend Internationalization: i18next for multi-language support
-
-### Python
-- Follow PEP 8 with 4-space indentation
-- Use type annotations
-- Prefer dataclasses for state management
-- Use `lightrag.utils.logger` instead of print
-- Async/await patterns throughout
-- Keep storage implementations in `kg/` with consistent base class inheritance
-
-### TypeScript/React
-- Functional components with hooks
-- 2-space indentation
-- PascalCase for components
-- Tailwind utility-first styling
-
-## Important Architectural Notes
-
-### LLM Requirements
-- Minimum 32B parameters recommended
-- 32KB context minimum (64KB recommended)
-- Avoid reasoning models during indexing
-- Stronger models for query stage than indexing stage
-
-### Embedding Models
-- Must be consistent across indexing and querying
-- Recommended: `BAAI/bge-m3`, `text-embedding-3-large`
-- Changing models requires clearing vector storage and recreating with new dimensions
-
-### Reranker Configuration
-- Significantly improves retrieval quality
-- Recommended models: `BAAI/bge-reranker-v2-m3`, Jina rerankers
-- Use "mix" mode when reranker is enabled
+Strictly follow the rules in ./AGENTS.md

Dockerfile

@@ -93,7 +93,7 @@ RUN --mount=type=cache,target=/root/.local/share/uv \
     && /app/.venv/bin/python -m ensurepip --upgrade
 
 # Create persistent data directories AFTER package installation
-RUN mkdir -p /app/data/rag_storage /app/data/inputs /app/data/tiktoken
+RUN mkdir -p /app/data/rag_storage /app/data/inputs /app/data/prompts /app/data/tiktoken
 
 # Copy offline cache into the newly created directory
 COPY --from=builder /app/data/tiktoken /app/data/tiktoken
@@ -102,6 +102,7 @@ COPY --from=builder /app/data/tiktoken /app/data/tiktoken
 ENV TIKTOKEN_CACHE_DIR=/app/data/tiktoken
 ENV WORKING_DIR=/app/data/rag_storage
 ENV INPUT_DIR=/app/data/inputs
+ENV PROMPT_DIR=/app/data/prompts
 
 # Expose API port
 EXPOSE 9621