HKUDS/LightRAG
47.2
Weak · 14 November 2026
177.2k
lines of production code
Python
with TypeScript
5
measurements over time
What this system is
Features
Add Apple Container orchestrator support for local development
The setup scripts now support running the LightRAG storage stack on macOS using Apple's native \container\ CLI instead of Docker Compose. This new \apple-container.sh\ script manages the full stack (Postgres, Neo4j, Milvus, MinIO, etcd, and LightRAG) on Apple Silicon, handling service discovery via IP addresses and implementing explicit health-wait loops to compensate for the lack of Compose features like \depends\_on\ and DNS in the Apple \container\ environment. The setup wizard includes a new storage orchestrator option to select this mode, and the underlying library files (\file\_ops.sh\, \validation.sh\, \prompts.sh\) have been refactored to support the new configuration and validation flows.
scripts/setup · high confidence
Add Docker Compose templates for vector stores, databases, and vLLM services
The setup wizard now includes dedicated Docker Compose templates for a broader range of infrastructure components. This adds support for Memgraph and Neo4j graph databases, MongoDB Atlas Local, and OpenSearch (including its dashboards service). It also introduces templates for Milvus and Qdrant vector stores, with specific variants for GPU acceleration using the NVIDIA runtime. Additionally, new templates are provided for vLLM embedding and reranking services, offering both CPU and GPU configurations, alongside standard Redis and PostgreSQL (with pgvector/AGE) database templates. These templates standardize service configuration, health checks, and port mappings for the interactive setup process.
scripts/setup/templates · high confidence
Add KubeBlocks-based database deployment scripts and configuration
This change introduces a new set of shell scripts and Helm value files in the \k8s-deploy/databases\ directory to manage database infrastructure using KubeBlocks. Users can now configure which databases to enable (PostgreSQL, Redis, Elasticsearch, Qdrant, Neo4j, MongoDB) via \00-config.sh\, then run \01-prepare.sh\ to install the KubeBlocks platform and addons, \02-install-database.sh\ to deploy the selected database clusters, and \03-uninstall-database.sh\ / \04-cleanup.sh\ to remove them. The scripts handle dependency checks, Helm repository management, and waiting for pods to become ready, with default configurations provided in per-database \values.yaml\ files (e.g., PostgreSQL 16.4.0 in replication mode, Neo4j 5.26.5).
k8s-deploy/databases · high confidence
Add MinerU external parser integration
Introduces the MinerU parser engine to LightRAG, enabling the system to download, cache, and parse documents using the MinerU service (both official cloud and self-hosted modes). The integration includes a raw client for handling the upload-poll-download workflow, an IR builder that converts MinerU's content list into LightRAG's intermediate representation (preserving tables, images, and equations), and a parser adapter that wires these components together.
lightrag/parser/external/mineru · high confidence
Add custom GitHub icon component
A new reusable GitHub icon component has been added to the UI library, allowing the application to display a consistent, custom-designed GitHub logo instead of relying on external assets or generic icons.
_lightrag\webui/src/components/icons · high confidence
Add foundational UI component library
Introduces a new set of reusable UI components for the WebUI, including Alert, AlertDialog, AsyncSearch, AsyncSelect, Badge, Button, Card, Checkbox, Command, Dialog, EmptyCard, FileUploader, Input, NumberInput, PaginationControls, Popover, Progress, and ScrollArea. These components provide the building blocks for the interface, featuring support for async data fetching, file uploads with progress tracking, pagination, and accessible dialog/popover interactions.
_lightrag\webui/src/components/ui · high confidence
Added tab visibility management context
The application now includes a new React context (\TabVisibilityProvider\) and associated types/hooks to manage the visibility state of UI tabs (documents, knowledge-graph, retrieval). This change introduces a mechanism to track which tabs are currently visible and provides utilities to toggle their visibility, supporting dynamic tab management within the WebUI.
_lightrag\webui/src/contexts · high confidence
Automated dependency installation and test permissions for Claude Code sessions
Claude Code sessions now automatically install backend (Python via uv) and WebUI (via bun) dependencies upon start, ensuring the development environment is ready for testing and linting without manual setup. Additionally, the configuration grants explicit permission to run the project's test script, enabling scripted test execution directly within the session.
.claude · high confidence
Customer-defined branding and legal content via customization bundles
The WebUI now supports fully customizable branding and legal text through deployment-specific bundles. Users can define the deployment title, a custom copyright line displayed at the page footer, and Markdown content for the welcome page, login blurb, and user agreements. The system enforces a strict atomicity rule: for any given locale, the UI displays content entirely from the active bundle or entirely from frontend defaults, preventing mixed or partial states. A new consent gate on the login page respects bundle declarations, and the rendering engine uses a dedicated Markdown tier that safely strips HTML to ensure security while supporting GFM syntax.
_lightrag\webui/src/components/customization · high confidence
Expanded demo ecosystem with new visualization, multi-agent, and storage examples
The examples directory now includes a broader set of demonstration scripts to help users get started with LightRAG. New additions include graph visualization tools using Pyvis (\graph\_visual\_with\_html.py\) and Neo4j (\graph\_visual\_with\_neo4j.py\), as well as a script to visualize graphs stored in OpenSearch (\graph\_visual\_with\_opensearch.py\). The library now supports multi-agent workflows via an AG2 demo (\lightrag\_ag2\_multiagent\_demo.py\) and allows users to insert pre-defined knowledge graphs directly (\insert\_custom\_kg.py\). Additionally, new demos have been added for Google Gemini (including workspace isolation and PostgreSQL-backed storage), Azure OpenAI, and OpenAI-compatible endpoints, providing more options for LLM and storage backends.
examples · high confidence
Expanded unofficial sample demos and cache migration tool
The examples/unofficial-sample directory now includes a broader set of integration demos and a new utility script. New demos demonstrate LightRAG integration with Amazon Bedrock, Cloudflare Workers AI, Hugging Face Transformers, NVIDIA NIM, LM Deploy, and LlamaIndex (via both OpenAI and LiteLLM providers, including an Opik observability variant). A new demo also showcases a multi-storage architecture using Redis for KV storage, Neo4j for graph storage, and Milvus for vector storage. Additionally, a new script, copy\_llm\_cache\_to\_another\_storage.py, is provided to migrate LLM response caches between JSON and PostgreSQL storage, handling the conversion between hierarchical and flattened key structures.
examples/unofficial-sample · high confidence
Graph property editing, entity merging, and layout performance improvements
Users can now edit entity and relationship properties directly in the graph view via a new PropertyEditDialog, with support for merging duplicate entities through a MergeDialog that appears after a successful rename. The graph layout engine has been significantly optimized: initial ForceAtlas2 and other worker-based layouts now run in Web Workers with a time budget to keep the UI responsive, and camera state (rotation/zoom) is preserved during layout settling. Additional UX improvements include a new Legend component to visualize node types, a FullScreenControl for the graph panel, and enhanced search functionality with middle-content matching and history management in GraphLabels.
_lightrag\webui/src/components/graph · high confidence
Helm chart introduces StatefulSet mode with write-pinning and ordered startup
The LightRAG Helm chart now supports deploying as a StatefulSet (configurable via \workload.kind\) in addition to the default Deployment. When using StatefulSet, the chart renders a headless Service for stable DNS names and a dedicated 'writer' Service that routes traffic exclusively to pod 0, enabling operators to pin document ingestion to a single instance while other replicas handle reads. It also enforces ordered pod startup (\OrderedReady\) to ensure storage initialization completes before subsequent pods start, and adds support for \imagePullSecrets\ and \envFrom\ configuration. Persistent storage handling adapts to the workload kind, using shared PVCs for Deployments and per-pod \volumeClaimTemplates\ for StatefulSets, with safeguards to retain PVCs during kind switches.
k8s-deploy/lightrag/templates · high confidence
Initial Helm chart release for LightRAG deployment
This change introduces the first official Helm chart (version 0.1.2) for deploying LightRAG on Kubernetes, providing a standardized way to manage the application's lifecycle. The chart defaults to a single-replica Deployment with Recreate update strategy to prevent storage conflicts, but supports switching to a StatefulSet with OrderedReady policy for environments requiring ordered startup of query-only instances. It includes configurable settings for image pull secrets, environment variable injection from external ConfigMaps/Secrets, and pre-configured defaults for PostgreSQL, Neo4J, and Qdrant storage backends.
k8s-deploy/lightrag · high confidence
Introduce Docling external parser integration
Adds a new Docling-based parsing engine to the external parser suite. This includes a raw client to download and extract docling-serve result bundles, a robust cache validation layer that checks source hashes, endpoint signatures, and engine versions to prevent stale or corrupted cache hits, and an IR builder that converts the Docling JSON output into the internal representation. The integration also handles specific edge cases like rejecting non-success JSON envelopes and managing image artifact references.
lightrag/parser/external/docling · high confidence
Introduce LightRAG Sidecar writer infrastructure and chunk provenance backfill
The sidecar module now provides a spec-compliant writer that emits a structured \\\*.parsed/\\ directory (including \\blocks.jsonl\\, \\tables.json\\, \\drawings.json\\, and \\equations.json\\) from an intermediate document representation, handling asset management, ID allocation, and placeholder rendering. Additionally, a new backfill mechanism reconstructs source provenance for F/R/V chunking strategies by mapping chunk character spans back to the original parsed blocks, with graceful degradation for unlocatable chunks.
lightrag/sidecar · high confidence
Introduce RAGAS-based evaluation framework for LightRAG quality assessment
Users can now evaluate the quality of their LightRAG deployments using the RAGAS framework. This new feature adds a dedicated evaluation module (\lightrag/evaluation\) containing a main script (\eval\_rag\_quality.py\) and a Python API (\RAGEvaluator\). The tool measures key metrics including Faithfulness, Answer Relevance, Context Recall, and Context Precision. It supports command-line configuration for custom datasets and RAG endpoints, and allows separate configuration for LLM and embedding models via environment variables. A sample dataset and corresponding documents are included to help users reproduce baseline results.
lightrag/evaluation · high confidence
Introduce structured setup workflow and offline-ready Docker builds
The project now provides a modular, interactive setup workflow via a new Makefile (targets like \make dev\, \make env-base\, \make env-storage\, \make env-server\) and a dedicated setup script, replacing ad-hoc configuration. Docker images are rebuilt with a multi-stage pipeline that uses \uv\ for faster Python dependency resolution and \bun\ for frontend compilation, and they run as a non-root user with pinned Debian bookworm base images for security. Offline deployment is supported through pre-cached tiktoken data and bundled spaCy model wheels, and the repository now includes comprehensive documentation (AGENTS.md, CLAUDE.md) and updated environment examples to guide users through the new configuration flow.
(repo-wide) · high confidence
Introduce unified external parser engine contract with safe caching and extraction
The external parser subsystem now uses a shared \\ExternalParserBase\\ template that standardizes the download, raw-bundle caching, and IR conversion flow for engines like MinerU and Docling. This change adds a unified \\BaseParser\\ contract and engine registry, allowing per-file engine parameters to be passed through the pipeline. It also introduces robust safety guards for external result bundles, including zip-bomb protection (capping entries and uncompressed size) and path-traversal prevention during extraction, along with environment-driven configuration for download timeouts and bundle limits.
lightrag/parser/external · high confidence
Introduces new paragraph-semantic and semantic-vector chunking strategies
The chunking module now supports two new built-in strategies alongside the existing fixed-token and recursive-character methods. The new 'P' (paragraph-semantic) strategy uses a sidecar file of structural blocks to perform heading-aware semantic chunking, preserving table headers and merging small blocks intelligently. The new 'V' (semantic-vector) strategy wraps LangChain's SemanticChunker to split text based on sentence embedding similarity, with added safeguards to bound embedding request sizes and concurrency. These strategies are registered via a new plugin system and can be selected explicitly in document processing options.
lightrag/chunker · high confidence
Native DOCX parser with decompression budget enforcement and numbering fixes
The native DOCX parser is now available as a dedicated engine, introducing a decompression budget (enforced via \zip\_budget.py\) to reject ZIP bomb attacks and bound expansion costs, addressing security advisory [GHSA redacted]. The parser also improves document fidelity by correctly resolving complex automatic numbering formats (including CJK, Roman, and lettered lists) via \numbering\_resolver.py\, handling merged cells and superscript/subscript in tables, and extracting drawing assets with safe path validation. Smart heading discovery and audit logging are supported via optional engine parameters and sidecar files.
lightrag/parser/docx · high confidence
Native Markdown parser engine with secure image handling
Introduces a new native Markdown parser engine for .md and .textpack files that converts markdown content into an intermediate representation, preserving tables, equations, and drawings. The engine includes robust image handling: it supports downloading external images (enabled by default), rasterizes SVGs to PNG, and enforces strict security and resource budgets (SSRF guards, magic-byte validation, per-document byte/request/time limits) to prevent abuse. A per-document cache persists downloaded images to speed up re-parses.
lightrag/parser/markdown · high confidence
New API server infrastructure with pre-body admission control and body limits
The API server now includes a new \lightrag/api\ package that introduces pre-body admission control and request body limits via pure ASGI middleware. This ensures that capacity reservations and size checks happen before the request body is read, preventing resource exhaustion from unauthenticated or oversized uploads. The server also features a new Gunicorn integration with a custom Uvicorn worker that detects orphaned processes, centralized configuration management, and robust authentication with brute-force protection for the login endpoint.
lightrag/api · high confidence
New Helm chart and deployment scripts for LightRAG on Kubernetes
The k8s-deploy area now provides a Helm chart and convenience scripts (install\_lightrag.sh, install\_lightrag\_dev.sh, uninstall\_lightrag.sh) to deploy LightRAG on Kubernetes. The chart supports a lightweight deployment using built-in storage (JsonKVStorage, NanoVectorDBStorage, NetworkXStorage) and a production deployment using external databases (PostgreSQL and Neo4j via KubeBlocks). It enforces a single-writing-instance model by default (Deployment with Recreate strategy) but allows switching to a StatefulSet with OrderedReady startup for additional query-only replicas, provided external databases are used and writes are routed exclusively to pod 0 via a dedicated writer Service. The uninstall scripts retain PersistentVolumeClaims by default to prevent data loss and report the Helm uninstall status correctly.
k8s-deploy · high confidence
New LLM provider bindings and unified error handling
This change introduces dedicated LLM binding modules for Anthropic, Amazon Bedrock, Google Gemini, Hugging Face, Jina, LlamaIndex, LM Deploy, and LoLLMs, alongside a new error classification utility and an Azure OpenAI compatibility shim. The new bindings provide native async support, provider-specific retry logic, and consistent integration with LightRAG's caching and streaming interfaces, while the error utilities standardize the detection of permanent rate-limit errors to prevent unnecessary retries.
lightrag/llm · high confidence
New RAG reproduction pipeline with OpenAI Batch API evaluation
The \reproduce\ directory now includes a complete, runnable pipeline for evaluating RAG systems. It starts with \Step\_0.py\ to extract unique contexts from JSONL datasets, \Step\_1.py\ to insert them into a LightRAG instance, and \Step\_2.py\ to generate evaluation questions using GPT-4o. \Step\_3.py\ runs queries against the RAG system, while \Step\_3\_openai\_compatible.py\ provides an alternative implementation supporting Upstage API models. Finally, \batch\_eval.py\ allows users to compare two RAG systems' answers using the OpenAI Batch API, automating the evaluation process via command-line arguments.
reproduce · high confidence
New UI components for settings, theming, and API key management
This change introduces several new React components in the Web UI: ApiKeyAlert, which displays a modal dialog to input or update the API key when authentication fails; AppSettings, a popover menu allowing users to change the application language (supporting English, Chinese, French, Arabic, Traditional Chinese, Russian, Japanese, German, Ukrainian, Korean, Vietnamese, and Indonesian) and theme (light, dark, or system); ThemeProvider and ThemeToggle, which manage and expose the current theme state and provide a quick-toggle button; LanguageToggle, a button for switching between English and Chinese; ErrorBoundary, which catches render errors in child subtrees and displays a recoverable error message instead of crashing the app; MigrationErrorScreen, which handles errors during the local settings storage migration by offering to reload or continue with lost data; and Root, the simplified entry point wrapping the app in StrictMode.
_lightrag\webui/src/components · high confidence
New WebUI feature modules and comprehensive test coverage
This change introduces several new WebUI feature components and their corresponding regression tests. The DocumentManager now provides a full-featured document list with pagination, status filtering, and deletion capabilities, supported by tests that verify correct row removal during asynchronous deletion operations. A new LoginPage component implements a consent gate that enforces agreement to privacy policies before credential-based sign-in, ensuring the gate remains valid across language switches. The GraphViewer has been updated to support sigma.js v3 with optimized edge rendering and theme-aware settings, while the SiteHeader now displays deployment titles and version information with improved accessibility. Additionally, the RetrievalView component offers an admin query interface with layout tests ensuring consistent spacing across tabs.
_lightrag\webui/src/features · high confidence
New document management dialogs and pipeline status monitoring
The WebUI now includes dedicated dialogs for clearing all documents (ClearDocumentsDialog), deleting selected documents (DeleteDocumentsDialog), and monitoring pipeline progress (PipelineStatusDialog). The clear operation now optionally folds LLM cache deletion into the main request rather than firing a separate call, and the delete dialog offers options to remove associated files and cache. The pipeline status dialog provides real-time monitoring with a 2-second refresh interval, position controls, and the ability to cancel running pipelines. The upload dialog has been enhanced with live file type validation from the backend, duplicate file detection (HTTP 409), and improved error handling for ingestion refusals (400/413/429/503). Comprehensive tests verify the clear dialog's behavior across success, partial success, and failure states.
_lightrag\webui/src/components/documents · high confidence
New library modules for AI content labeling, JWT decoding, language detection, and file type validation
The WebUI now includes dedicated logic in \src/lib\ to handle several core behaviors: \aiContentNotice.ts\ determines whether to display an 'AI-generated' label based on query settings and server verdicts; \base64url.ts\ provides a safe, UTF-8-aware decoder for JWT payloads to prevent identity corruption; \browserLanguage.ts\ manages the language priority chain (explicit choice \> browser preference \> default); \documentTitle.ts\ synchronizes the browser tab title with server configuration; \extensions.ts\ loads the KaTeX mhchem extension; and \fileTypes.ts\ along with \constants.ts\ defines the supported file extensions and parser capabilities for the upload interface. Comprehensive test suites have been added for all these modules.
_lightrag\webui/src/lib · high confidence
New offline maintenance and migration tools for LightRAG
This release introduces a suite of offline CLI and library tools for the \lightrag/tools\ module to help operators manage data integrity and storage backends without re-processing documents. The \*\KG Integrity Repair\\* tool (\kg\_integrity\repair\) audits and repairs missing recovery anchors for documents ingested before recent changes or written via direct KG paths, preventing purge failures. The \\Chunk-Tracking Repair\\* tool (\chunk\_tracking\repair\) removes orphaned entity/relation tracking rows left by crashes. The \\Source-Conflict Repair\\* tool (\source\_conflict\repair\) allows operators to explicitly resolve duplicate source key conflicts by demoting candidates. Storage migration is supported by the \\Graph Storage Migration\\* tool (moving from Apache AGE to plain-table PG) and the \*\LLM Cache Migration\\* tool (migrating extraction/summary caches between KV backends like Redis, PostgreSQL, and MongoDB). Additionally, the \*\VDB Rebuild\\* tool (\rebuild\vdb\) restores consistency between the graph and vector stores, handling embedding model changes and consistency drifts, while the \\LLM Query Cache Cleanup\\* tool (\clean\_llm\_query\cache\) allows selective deletion of query/keyword caches. A \\Diagnostic Tool\\* (\check\_initialization\) is also added to verify that all storage components are correctly initialized.
lightrag/tools · high confidence
New retrieval UI components and unified query handling
The retrieval feature area now includes a shared \MessageList\ component that manages conversation display, auto-scrolling during streaming, and user scroll-intent detection, alongside a \QueryComposer\ for input handling with validation and error feedback. A new \queryInput\ module standardizes query parsing and validation across both the \/webui\ and \/workspace\ entry points, ensuring consistent behavior for mode prefixes and empty queries. The \serializeQueryRequest\ function provides a unified request serializer that handles conversation history expansion and settings mapping, while \streamErrorChunk\ and \streamedContentKey\ improve streaming reliability by preventing duplicate content on errors and fixing scroll-follow issues during long responses.
_lightrag\webui/src/features/retrieval · high confidence
New retrieval UI components with advanced rendering and settings
The WebUI now includes dedicated components for the retrieval interface: ChatMessage renders assistant and user messages with support for Mermaid diagrams, KaTeX math, syntax highlighting, and footnotes, while QuerySettings provides a panel to configure query parameters (mode, prompt history, reset) and displays a scope notice. Mermaid is loaded on-demand to avoid first-load overhead, with robust error handling for load and render failures.
_lightrag\webui/src/components/retrieval · high confidence
New script to centralize version management
A new Python script, set\_version.py, has been added to the release scripts to centralize how version numbers are managed. This tool allows users to update the core package version and optionally the API compatibility version by modifying the \_version.py file directly, automatically stripping leading 'v' characters from the core version if present.
scripts/release · high confidence
New status monitoring UI with detailed server and configuration insights
The WebUI now includes a new status indicator and dialog that provide comprehensive visibility into the server's health and configuration. Users can view detailed storage workspace information, role-based LLM configurations (including extract, keyword, query, vlm, embed, and rerank roles), and real-time queue status for LLM, embedding, and rerank operations. The interface also displays parser routing details for MinerU and Docling, server mode (uvicorn/gunicorn) and worker count, and provider kwargs. A fixed status indicator in the bottom-right corner shows connection status with visual feedback, and clicking it opens a detailed dialog with all this information.
_lightrag\webui/src/components/status · high confidence
New utility hooks for debouncing, dark mode detection, and BFCache restoration
The Web UI introduces several new React hooks to improve stability and user experience. A new \useDebounce\ hook allows components to delay value updates, reducing unnecessary re-renders. \useIsDarkMode\ provides a reactive, single source of truth for the current theme, correctly resolving 'system' mode against OS preferences. \usePageRestoreGeneration\ detects browser back/forward cache (BFCache) restores, enabling consumers to restart stale polling or health checks without relying on \beforeunload\ events. Additionally, \useTheme\ offers a typed context consumer for theme settings, and \useRandomGraph\ is added to support deterministic seed-based graph generation for testing or demo purposes.
_lightrag\webui/src/hooks · high confidence
New utility modules for search history, clipboard, entity normalization, graph safety, and markdown sanitization
Added several new utility modules in lightrag\_webui/src/utils to improve reliability, security, and user experience. SearchHistoryManager introduces persistent, versioned search history with sorting by access time and frequency, plus support for popular label recommendations. A robust clipboard utility (clipboard.ts) provides copy functionality with multiple fallback strategies (Clipboard API, execCommand, manual selection) for broad browser compatibility. Entity name normalization (entityName.ts) ensures consistent entity naming by stripping invalid Unicode, decoding HTML entities, converting full-width characters, and removing outer quotes, with corresponding tests. Graph edge safety helpers (graphEdgeSafety.ts) work around graphology prototype-pollution bugs that could cause crashes or phantom edges when node names collide with JavaScript reserved properties. Markdown sanitization (markdownSanitizeSchema.ts, remarkFootnotes.ts) blocks stored XSS in chat messages by applying a strict allow-list schema while preserving legitimate formatting like KaTeX math and inline footnotes. Query validation (queryValidation.ts) enforces minimum RAG query length with accurate weighting for CJK, Kana, Hangul, and Bopomofo characters.
_lightrag\webui/src/utils · high confidence
New workspace entry for direct RAG querying
A new workspace entry has been added, providing a dedicated interface for asking questions without the admin panel's document or graph navigation. This entry features a slim header with a brand link that displays the deployment description in a tooltip (accessible via keyboard and touch devices), a welcome page for unauthenticated visitors that supports custom branding and copyright lines, and a query view that reuses the shared session and composer components. The workspace maintains its own retrieval history, inherits query settings from the main web UI (with specific clamping), and includes a robust credential probe that automatically detects API key rotations, re-validates credentials on dialog save, and handles stale token replacement when the server's authentication mode changes.
_lightrag\webui/src/features/workspace · high confidence
Opt-in smart heading discovery for DOCX parsing
Users can now enable intelligent heading detection in DOCX files by setting the engine parameter \native(smart\_heading=true)\. This feature uses spaCy to analyze text content, allowing the parser to distinguish actual headings from body text based on linguistic cues (such as sentence structure and entity types) rather than relying solely on document styles. The feature is opt-in to avoid adding spaCy as a hard dependency for all users; it requires installing the \lightrag-hku\[api\]\ extra and downloading the appropriate language models. If the required models are missing, the system will fail fast with a clear error message rather than silently degrading.
_lightrag/parser/docx/smart\heading · high confidence
Support for multi-site deployment via runtime path prefix injection
The WebUI now supports hosting multiple LightRAG instances on a single host behind a reverse proxy without requiring a separate build for each site. Instead of static build-time prefixes, the application resolves its API and WebUI URL prefixes at request time via a \window.\_\_LIGHTRAG\CONFIG\\_\ object injected by the server (or Vite dev server). This allows a single WebUI build to serve any number of sites dynamically. Additionally, a new \workspace.html\ entry point is introduced alongside the main WebUI, enabling a dual-entry infrastructure for workspace-specific queries.
_lightrag\webui · high confidence
Architecture
Refactored API router structure into modular factory functions
The API router definitions have been reorganized from a single monolithic module into distinct, modular files (document\_routes, query\_routes, graph\_routes, ollama\_api, and ui\_customization\_routes). Each router is now constructed via a factory function (e.g., create\_document\routes) rather than as a module-level singleton. This change prevents duplicate route registration and 'Duplicate Operation ID' warnings when the application is initialized multiple times in the same process, such as during testing or multi-worker setups. The routers are no longer re-exported from the main \\init\\_.py, ensuring that each app instance gets its own isolated router configuration.
lightrag/api/routers · high confidence
Unified parser engine registry and debug CLI
The parser layer is restructured around a central engine registry that serves as the single source of truth for parser metadata and dispatch. This enables a unified debug CLI (\\python -m lightrag.parser.cli\\) that can drive any registered engine—including third-party plugins discovered via \\lightrag.parsers\\ entry points—on a single file and output sidecar artifacts directly alongside the source. The change introduces a shared \\BaseParser\\ contract, a synchronous LLM bridge for worker-thread extract hooks, and a cancellation exception hierarchy, while consolidating native and external parser wrappers under \\lightrag/parser/\\.
lightrag/parser · high confidence
Behavioural changes
3121 commits (1352 fixes) modifying lightrag-hku
A change to existing behaviour in lightrag-hku — 3121 commits (1352 fixs), 52 files: “Added search mode and min degree filtering for NetworkX”; “📝 docs(mongo): clarify deferred flush behavior”; “fix(kg): never reload a file set that did not all move together”; and 2739 more (refs \#3745, \#708, \#2472, \#3367, \#3352, …).
lightrag-hku · medium confidence · unverified
4 commits (0 fixes) modifying lightrag/\_\_pycache\_\_
A change to existing behaviour in lightrag/\_\pycache\\_ — 4 commits, 9 files: “first commit”; “update”.
lightrag/\\pycache\\_ · medium confidence · unverified_
Centralized navigation and authentication state management
The Web UI now uses a centralized NavigationService to handle login redirects, token expiration (401 errors), and application state resets. This ensures that when a session expires or a user logs out, the application correctly navigates to the appropriate entry-specific page (e.g., /welcome for workspace, /login for admin) and clears local storage and session state. The service also preserves chat history during logout if the same user logs back in, and prevents the login page from mounting multiple times by centralizing the authentication flow logic.
_lightrag\webui/src/services · high confidence
Enhanced message typing and KaTeX type declarations
The UI now supports richer message states and improved math rendering. New type definitions in \src/types/retrieval.ts\ introduce flags for AI-generated content detection (decided by the query session rather than message shape), thinking states, abort status, and rendering completion for both Mermaid diagrams and LaTeX formulas, ensuring stable keys and preventing flickering during streaming. Additionally, \src/types/katex.d.ts\ adds TypeScript declarations for the KaTeX mhchem and copy-tex extensions, enabling better support for chemical formulas and formula copying in the interface.
_lightrag\webui/src/types · high confidence
Legacy parser engine moved to dedicated module with improved extraction and security fixes
The legacy in-process text extraction logic has been relocated from the API layer into a new \lightrag.parser.legacy\ package, introducing a \LegacyParser\ engine that outputs \raw\ plain text. This change consolidates extraction helpers for PDF, DOCX, PPTX, and XLSX files, ensuring that whitespace-only or empty extractions (e.g., from scanned PDFs) now fail the parse stage instead of silently producing empty documents. It also extends decompression budget protections to PPTX and XLSX files to mitigate zip-bomb vulnerabilities ([GHSA redacted]) and preserves cached formula values in XLSX files by loading workbooks twice. PDF decryption now relies exclusively on the \PDF\_DECRYPT\_PASSWORD\ environment variable. Also in this area: 6 commits (5 fixes) fixing lightrag/parser/legacy.
lightrag/parser/legacy · medium confidence · unverified
LightRAG v1.5.8 release with API version 0347
This update bumps the core version to 1.5.8 and the API version to 0347. It introduces a new \ObservableAddonParams\ class that notifies the runtime when configuration changes occur, and adds bounded in-process scheduling metrics to the \/health\ endpoint for monitoring pipeline performance.
lightrag · high confidence
New storage registry, factory, and cross-process consistency mechanisms
The \lightrag/kg\ module now exposes a centralized \STORAGE\_IMPLEMENTATIONS\ registry and a \get\_storage\_class\ factory in \factory.py\ to resolve and instantiate storage backends (including newly added OpenSearch and Memgraph options) while enforcing required method signatures. To prevent data loss in multi-process environments, \file\_fingerprint.py\ introduces a file-based reload fence that uses \st\_mtime\_ns\ and \st\_size\ to detect peer commits when in-process notifications are missed. Additionally, \write\seq.py\ adds a \\\_write\seq\\_\ nanosecond token to vector storage records to strictly order concurrent writes and prevent stale redo-log replays, and \vector\_space.py\ enforces embedding model and dimension provenance to refuse connections to incompatible vector containers.
lightrag/kg · high confidence
Separate bootstrap logic for workspace and webui entries with cross-tab session handling
The WebUI now initializes two distinct entry points—/webui (admin) and /workspace—each with its own navigation configuration. The /webui entry redirects unauthenticated users to /login and resets the graph state and retrieval history on navigation, while the /workspace entry redirects to /welcome and clears only the workspace-specific retrieval history. Both entries now listen for cross-tab identity changes to reset live sessions and ensure that query settings saved in one tab are re-hydrated in others without requiring a page reload.
_lightrag\webui/src/bootstrap · high confidence
Web UI restructured with dual-entry routing, hash-based navigation, and expanded language support
The Web UI has been restructured to support two distinct entry points—the main application and a dedicated workspace query interface—each with its own router and navigation policy. Routing has shifted to hash-based navigation to allow a single build to serve multiple sites via runtime path prefixes. The application now initializes with a version and authentication check, supports auto-guest mode, and displays a warning if legacy chat history was dropped during a storage migration. Additionally, the UI now includes 12 localized languages (English, Chinese, French, Arabic, Traditional Chinese, Russian, Japanese, German, Ukrainian, Korean, Vietnamese, and Indonesian), improved Markdown rendering with KaTeX extensions, and a new API documentation tab.
_lightrag\webui/src · high confidence
WebUI API layer gains request timeouts, deduplication, and structured error handling
The WebUI API client now enforces strict timeouts on critical requests to prevent the interface from hanging indefinitely: UI customization fetches are bounded by a 5-second limit, and paginated document requests include a configurable timeout that aborts stalled calls and allows retries. To support this, the document listing logic has been refactored to deduplicate concurrent requests for the same parameters, ensuring that only one network call is active per unique query. Additionally, a new \AuthenticationRequiredError\ type has been introduced to cleanly distinguish session termination (401s) from general network failures, allowing the UI to handle login redirects without displaying error bubbles to the user.
_lightrag\webui/src/api · high confidence
Fixes
Fixes to OMML-to-LaTeX conversion for Word equations
The parser for converting Word document equations (OMML) to LaTeX has been fixed to produce valid LaTeX syntax. Specific improvements include correcting how delimiters are paired and scaled, ensuring that separator characters are only folded when they represent plain printing marks, and handling CJK and fullwidth delimiters with appropriate glyphs. Additionally, post-processing rules were added to clean up invalid linear expressions, such as converting specific degree symbols and fractional notations into their correct LaTeX equivalents.
lightrag/parser/docx/omml · high confidence
Test coverage
8 commits adding/updating tests in tests/llm/openai\_responses\_impl; Added comprehensive offline tests for Milvus storage implementation; Added comprehensive test coverage for FaissVectorDBStorage reliability and performance; Added comprehensive test coverage for Neo4j knowledge graph storage; Added comprehensive test coverage for the Docling parser integration; Added comprehensive test coverage for the native DOCX parser; Added comprehensive test coverage for utils module; Added comprehensive test suite for chunking strategies and provenance; Added comprehensive test suite for workspace isolation, path validation, and security sanitization; Added comprehensive tests for NetworkXStorage reliability and correctness; Added comprehensive tests for authentication, rate limiting, and path whitelisting; Added golden tests for native DOCX parsing of mixed content types; Added offline regression tests for the interactive setup wizard and Apple container orchestrator; Added offline test coverage for Redis storage implementation; Added offline tests for Bedrock LLM driver and token usage tracking; Added offline tests for Ollama binding parameter forwarding, token usage, and truncation handling; Added offline unit and real-PostgreSQL smoke tests for PGTableGraphStorage; Added offline unit tests for the MongoDB knowledge graph implementation; Added route-level tests for admission control, document clearing, and query endpoints; Added test automation and golden-file regeneration scripts; Added test coverage for JSON storage implementation; Added test coverage for NanoVectorDBStorage atomic writes, deferred operations, and reload fencing; Added test coverage for PostgreSQL storage implementation; Added test coverage for graph migration, VDB rebuild, and source-conflict repair tools; Added test suite for the native Markdown parser engine; Added tests for API configuration validation and binding behavior; Added tests for Anthropic client cleanup, token usage, and truncation handling; Added tests for Azure OpenAI embedding truncation; Added tests for Hugging Face inference executor stability and correctness; Added tests for LlamaIndex LLM and embedding integration; Added tests for LoLLMs max\_tokens mapping and stream session handling; Added tests for Memgraph storage edge deduplication, read contracts, and graph traversal; Added tests for NVIDIA embedding provider isolation, cleanup, and context handling; Added tests for NoopVectorDBStorage and graph-only workflow; Added tests for OpenAI LLM binding reliability and edge cases; Added tests for Qdrant deferred embedding, migration, and vector space handling; Added tests for RAG quality evaluation and offline retrieval checks; Added tests for Zhipu LLM implementation; Added tests for external parser utilities and engine parameter threading; Added tests for extraction stability, cache integrity, and merge correctness; Added tests for lmdeploy do\_sample, token limits, and truncation handling; Added tests for parser environment variable handling and engine parameter routing; Added unit tests for Gemini LLM implementation; Added unit tests for VoyageAI embedding implementation; Added unit tests for sidecar backfill, writer, and URI utilities; Comprehensive test suite for configuration, query logic, and storage contracts; Expanded API test coverage for security, configuration, and middleware behaviors; Expanded pipeline test coverage for reliability and security fixes; Expanded test coverage for LLM, embedding, and concurrency subsystems; Expanded test coverage for OpenSearch storage backend; Expanded test coverage for knowledge graph storage, scheduling, and pipeline history; New React component testing infrastructure for the WebUI; New tests for settings storage split migration purity and ordering; New tests for store logic and race-condition guards.
Dependencies
Introduce structured dependency management and WebUI project scaffold
The project now uses \pyproject.toml\ as the central configuration for Python dependencies, replacing the previous flat \setup.py\ and \requirements.txt\ files. Dependencies are organized into optional groups (extras) such as \api\, \offline-storage\, \offline-llm\, \test\, \evaluation\, and \observability\, allowing users to install only the components they need (e.g., \pip install lightrag-hku\[offline\]\). This structure is supported by new dedicated requirement files (\requirements-offline.txt\, \requirements-offline-storage.txt\, etc.) for offline deployment scenarios. Additionally, the WebUI is now scaffolded with a \package.json\ file, defining its frontend dependencies (React, Vite, Tailwind, etc.) and build scripts.
(dependencies) · high confidence
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
Score
- CAI 46 → 47 (+1.1)
- Rubric changed (rubric-2026.10.5 → rubric-2026.11.4) — scores are not directly comparable.
Lenses
- Code Health 57 → 54 (-3.0)
- Architecture 68 → 61 (-6.4)
- Maturity 71 → 76 (+4.9)
- Readiness 34 → 34 (+0.0)
- Security 60 → 62 (+1.7)
- Accessibility 49 → 57 (+7.3)
- Performance 85 → 85 (+0.0)
Resolved (126)
- Critical CVE: [GHSA redacted] (uv.lock)
- Critical CVE: [GHSA redacted] (uv.lock)
- Critical CVE: [GHSA redacted] (uv.lock)
- Critical vulnerability: [GHSA redacted] (uv.lock)
- Critical vulnerability: [GHSA redacted] (lightrag_webui/bun.lock)
- Duplicated block (11–12 lines × 2) (lightrag/kg/neo4j_impl.py)
- Duplicated block (12 lines × 2) (examples/lightrag_azure_openai_demo.py)
- Duplicated block (12 lines × 2) (lightrag/parser/docx/numbering_resolver.py)
- Duplicated block (12–14 lines × 2) (lightrag/lightrag.py)
- Duplicated block (13 lines × 2) (lightrag/kg/opensearch_impl.py)
- Duplicated block (13 lines × 2) (lightrag/operate.py)
- Duplicated block (13–15 lines × 2) (lightrag/api/routers/graph_routes.py)
- Duplicated block (15 lines × 2) (lightrag/kg/opensearch_impl.py)
- Duplicated block (15 lines × 2) (lightrag/utils_graph.py)
- Duplicated block (15–18 lines × 2) (lightrag/pipeline.py)
- Duplicated block (21 lines × 2) (lightrag/kg/memgraph_impl.py)
- Duplicated block (22–23 lines × 2) (lightrag/kg/postgres_impl.py)
- Duplicated block (24–26 lines × 2) (lightrag/api/routers/graph_routes.py)
- Duplicated block (25–29 lines × 2) (lightrag/kg/milvus_impl.py)
- Duplicated block (32–35 lines × 2) (lightrag/parser/external/docling/ir_builder.py)
- …and 106 more
New (218)
- Critical CVE: [GHSA redacted] (lightrag_webui/bun.lock)
- Critical CVE: [GHSA redacted] (lightrag_webui/bun.lock)
- DoclingRawClient.init (cognitive 19) (lightrag/parser/external/docling/client.py)
- DoclingRawClient.init (cyclomatic 17) (lightrag/parser/external/docling/client.py)
- Duplicated block (10 lines × 2) (lightrag/llm/openai_responses.py)
- Duplicated block (13 lines × 2) (lightrag/kg/opensearch_impl.py)
- Duplicated block (15–17 lines × 2) (lightrag/api/routers/graph_routes.py)
- Duplicated block (22 lines × 2) (lightrag/api/lightrag_server.py)
- Duplicated block (23–25 lines × 3) (lightrag/utils_graph.py)
- Duplicated block (34–36 lines × 2) (lightrag/utils_graph.py)
- Duplicated block (41 lines × 2) (lightrag/kg/memgraph_impl.py)
- Duplicated block (56–60 lines × 2) (lightrag/utils.py)
- Duplicated block (7 lines × 2) (lightrag/llm/openai.py)
- Edited copies of one member (3 members, 14+ corresponding lines) (lightrag/parser/external/docling/ir_builder.py)
- Edited copies of one member (3 members, 16+ corresponding lines) (lightrag/kg/opensearch_impl.py)
- Edited copies of one member (3 members, 20+ corresponding lines) (examples/lightrag_ollama_demo.py)
- Edited copies of one member (3 members, 21+ corresponding lines) (examples/unofficial-sample/lightrag_llamaindex_direct_demo.py)
- Edited copies of one member (3 members, 22+ corresponding lines) (lightrag/parser/external/_manifest.py)
- Edited copies of one member (3 members, 23+ corresponding lines) (lightrag/kg/opensearch_impl.py)
- Edited copies of one member (3 members, 25+ corresponding lines) (lightrag/kg/postgres_impl.py)
- …and 198 more
Changes since last survey
- 300 commits — 161 feature/other, 139 fixes
By area
- (repo) — 142 commits
- (root) — 38 commits
- lightrag/parser — 17 commits
- lightrag/llm — 11 commits
- lightrag/utils.py — 10 commits
- lightrag_webui/bun.lock — 9 commits
- lightrag/operate.py — 7 commits
- lightrag/kg — 6 commits
- tests/api — 6 commits
- docs/design — 5 commits
- tests/kg — 5 commits
- lightrag/lightrag.py — 4 commits
- lightrag_webui/src — 4 commits
- tests/parser — 4 commits
- .github/workflows — 3 commits
- lightrag/chunker — 3 commits
- tests/llm — 3 commits
- docs/ExploreLightRAG-zh.md — 2 commits
- docs/FileProcessingPipeline-zh.md — 2 commits
- docs/LightRAG-API-Server-zh.md — 2 commits
Notable commits
- fix: Merge branch 'main' into fix-query-answer-postprocess-mangles
- fix: Merge branch 'main' into fix/analyze-drain-on-cancel
- fix: Merge branch 'main' into fix/cancel-stage-children
- fix: Merge branch 'main' into fix/deps-drop-python-jose-pyjwt-cves
- fix: Merge branch 'main' into fix/mm-analyze-bounded-items
- fix: Merge branch 'main' into fix/ollama-embed-connection-retry
- fix: Merge branch 'main' into fix/relation-entity-name-resolution
- fix: Merge branch 'main' into oss/fix-native-cache-encoding-20261018
- fix: Merge origin/main into fix/legacy-docx-content-controls
- fix: Merge origin/main into fix/legacy-docx-content-controls
- fix: Merge pull request #4094 from L4XB/fix/legacy-docx-content-controls
- fix: Merge pull request #4139 from Shizoqua/fix/ollama-embed-connection-retry
- fix: Merge pull request #4144 from Zhuoxi2000/fix-query-answer-postprocess-mangles
- fix: Merge pull request #4161 from dajiaohuang/fix/cancel-stage-children
- fix: Merge pull request #4202 from dakjdakd/fix/empty-final-evidence
- fix: Merge pull request #4206 from dakjdakd/fix/persisted-query-errors
- fix: Merge pull request #4241 from passionworkeer/oss/fix-native-cache-encoding-20261018
- fix: Merge pull request #4245 from magicyuan876/fix/mm-analyze-bounded-items
- fix: Merge pull request #4310 from zzjiho/fix/neo4j-apoc-label-filter
- fix: Merge pull request #4328 from HKUDS/fix/caplog-lightrag-logger-fixture
- …and 280 more
Architecture
- Unchanged — 0 containers · 1 contexts · 0 edges
Written by cca.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
HKUDS/LightRAG was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.
About this page
- The score is its most recent published measurement, taken on 14 November 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 85b4e747ad10fb7f87c38fd0251a23bc97cc9dc0 — the exact code this score is about.
- Scored under rubric-2026.11.4 — the same rubric and the same method as every other entry in this index.
- Measured by Canine Code Analyzer (cca.canine.dev) using cca measure-2026.11.65+preprod-36d4cd83012f.