zylon-ai/private-gpt
56.3
Adequate · 25 October 2026
89.5k
lines of production code
Python
primary language
6
measurements over time
What this system is
PrivateGPT is a self-hosted, modular AI application that enables private document ingestion and retrieval-augmented generation (RAG) via a FastAPI-based chat interface. It supports multimodal inputs, tool execution, and streaming responses while leveraging asynchronous workers (Celery and ARQ) for scalable, resumable background processing. The system integrates with various LLM providers and vector stores, offering granular configuration and a local-first UI for interaction.
How it got here
2023 — PrivateGPT v1.0 architecture revamp
15 changes.
This period focused on the comprehensive overhaul of PrivateGPT to version 1.0, introducing a modular architecture with asynchronous task handling via ARQ and Celery for improved scalability. The update replaced synchronous pipelines with a robust dependency injection system, added real-time streaming support, and expanded capabilities for multimodal inputs and tool use. Significant effort was also dedicated to establishing a new configuration system, CI/CD workflows, and extensive test coverage for the new components.
2026 — Background task infrastructure and streaming events
20 changes.
The project significantly expanded its background processing capabilities by introducing ARQ-based resumable chat workers and refactoring Celery for stateful, pluggable task execution. Concurrently, a new event interception framework was implemented to enhance streaming control, providing granular event models, keep-alive mechanisms, and robust filtering for various response modes.
Features
Introduce PrivateGPT Workbench as a lightweight static demo UI
The \ui\ directory now contains the initial implementation of the PrivateGPT Workbench, a single-file static HTML application (\index.html\) designed to demonstrate the PrivateGPT API capabilities. This change adds the core runtime file along with comprehensive documentation (\PRD.md\, \STYLE\_GUIDE.md\, \SOURCE\_OF\_TRUTH.md\) and agent-specific workflow instructions (\AGENTS.md\, \CLAUDE.md\) to guide future development. The UI provides a local-first interface for users to interact with the PrivateGPT API, featuring a sidebar for navigation, a chat interface, and a debugger, while adhering to a specific visual style guide and API contract defined in the Fern-generated OpenAPI schema.
ui · high confidence
Introduces ARQ-based asynchronous worker infrastructure for resumable chat and tool execution
This change adds a new \private\_gpt/arq\ package that implements an asynchronous task queue using the ARQ library backed by Redis. It introduces a \HeartbeatWorker\ with custom lease management to handle job ownership and stale lock recovery, enabling reliable multi-process execution. The infrastructure supports resumable chat sessions by persisting iteration state and tool results in Redis via \RedisChatCheckpointStore\, allowing the system to recover from interruptions. It also includes components for publishing routes, managing worker health checks, and auto-discovering chat and tool tasks, fundamentally shifting the backend from synchronous or Celery-based processing to a more robust, stateful async model.
_private\gpt/components · high confidence
Introduces ARQ-based chat worker with resumable execution and improved health monitoring
Adds a new background task infrastructure using the ARQ library to handle chat operations, enabling resumable chat execution via a Redis-backed checkpoint store that persists iteration state. This change introduces a custom HeartbeatWorker that implements native health recording and reclaimable job ownership to prevent long chats from stalling the worker during condensation, alongside optimized job claiming logic to reduce latency and improve throughput.
_private\gpt/arq · high confidence
Introduces resumable chat and tool execution via background workers
This change adds a new background task infrastructure in \private\_gpt/arq/tasks\ to support resumable chat sessions and asynchronous tool execution. It introduces specific ARQ tasks for starting chat jobs, resuming iterations, handling tool results, and managing tool timeouts, along with a callback mechanism to dispatch tool execution results back to the chat scheduler. This enables the system to pause and resume long-running chat interactions and handle external tool calls without blocking the main thread.
_private\gpt/arq/tasks · high confidence
New PrivateGPT utility and maintenance scripts
This change introduces a suite of new scripts to support the PrivateGPT application. The \auto\_discover\_models.py\ script allows users to automatically detect available LLM and embedding models from remote OpenAI-compatible APIs and generate a corresponding settings profile. The \ingest\_folder.py\ script provides a command-line tool for bulk-ingesting files from a local directory, supporting file watching and the ability to ignore specific files or directories. Additionally, \extract\_openapi.py\ enables exporting the application's OpenAPI specification, \generate\_homebrew\_formula.py\ assists in creating Homebrew installation formulas, \set\_version.py\ automates version updates across project files, \update\_claude\_specs.py\ keeps Anthropic SDK and OpenAPI spec references synchronized, and \worker\_entrypoint\ configures the runtime environment for background workers.
scripts · high confidence
New chat API with streaming, tool use, and structured outputs
The server now exposes a new chat endpoint at POST /v1/messages that supports streaming responses, tool use (including MCP server integration), and structured JSON outputs. Users can configure sampling parameters (temperature, top\_p, seed), enable thinking/reasoning modes, and manage context through system prompts and document mounts. The implementation includes a comprehensive interceptor chain for handling citations, condensation, and tool execution, replacing the previous chat interface.
_private\gpt/server · high confidence
New event interception infrastructure for streaming control
The system introduces a new event interception framework within the events module, allowing for the processing and modification of the streaming event pipeline. This includes a base abstract class for interceptors, a specific implementation to filter Zylon-specific events based on the response mode, and a performance-optimized ping event interceptor that emits keep-alive signals during idle periods to prevent connection timeouts without incurring the overhead of creating a new task for every streamed event.
_private\gpt/events/interceptors · high confidence
New utility modules for concurrency, batching, and token estimation
The \private\_gpt/utils\ package has been expanded with new modules to support the revamped ingestion and chat pipelines. \concurrency.py\ introduces \bounded\_concurrent\_execute\ and \map\_elements\_in\_parallel\ for controlled async task execution with jitter and worker limits. \async\_utils.py\ and \batches.py\ provide helpers for converting sync iterators to async ones and batching both sync and async iterables with optional stop conditions. \retry.py\ wraps the \retry\_async\ library for robust error handling. \tokens.py\ adds \estimate\_token\_count\ to accurately calculate token usage in chat history, considering tools and reasoning effort, while \token.py\ provides logic for calculating maximum token expansion limits. Additional utilities include \eta.py\ for progress reporting, \pool.py\ for object pooling, and \dataframe.py\ for markdown conversion.
_private\gpt/utils · high confidence
PrivateGPT v1 revamp: new architecture, async task handling, and chat enhancements
This release introduces a major architectural overhaul (PrivateGPT v1) that replaces the previous synchronous ingestion pipeline with an asynchronous, worker-based system using Celery and ARQ for improved reliability and scalability. The diff adds new modules for health checks, routing, and task management, enabling users to track ingestion and deletion progress via async task IDs. The chat interface is significantly enhanced with support for multimodal inputs (images, audio, video), document preprocessing, and advanced memory condensation strategies to manage context windows. Additionally, the system now supports configurable system prompts, citation generation, and various LLM integrations including Ollama, Azure OpenAI, and Google Gemini, while introducing new settings for similarity scoring and context window management.
private-gpt · high confidence
PrivateGPT v1.0.0 revamp: new Docker build, settings schema, and CI/CD artifacts
This release introduces the PrivateGPT v1.0.0 architecture, replacing the previous setup with a multi-stage Dockerfile that uses \uv\ for dependency management and supports optional extras (core, ingest, media, tools, database) to minimize image size. The configuration system is overhauled with a new \settings.yaml\ that exposes granular controls for chat engines, retrieval, document parsing (Docling), and vector stores, alongside dedicated \settings-mock.yaml\ and \settings-test.yaml\ profiles. The project also adds a \Makefile\ for standardized development workflows (test, lint, dev, prod-run), a \SECURITY.md\ for private vulnerability reporting, and a \CITATION.cff\ for academic referencing.
(repo-wide) · high confidence
Behavioural changes
Celery infrastructure refactored with configurable backends and stateful worker support
The Celery worker subsystem has been restructured to support pluggable broker and backend configurations (local filesystem, Redis, or RabbitMQ) via new \broker\_config.py\ and \backend\_config.py\ modules, allowing users to select their preferred infrastructure mode. A new \bootsteps.py\ introduces liveness probes and dedicated warm-up/shutdown logic for stateful workers, ensuring models are loaded safely in preforked child processes. The \base.py\ module now provides a \StatefulBackgroundTask\ base class with controlled retry mechanisms and failure tracking, while \callback.py\ and \notify.py\ implement a unified progress notification system that sends structured updates (including fake progress for long-running tasks) and final results to the API. Additionally, \healthcheck.py\ adds a dedicated health endpoint that monitors worker readiness and heartbeat files, and \task\_helper.py\ provides utilities to inspect and revoke specific ingestion or deletion tasks by collection and artifact.
_private\gpt/celery · high confidence
Dedicated Celery task for tool execution
A new Celery task, \private\_gpt.tools.run\, has been introduced to handle tool execution on a dedicated worker. This change moves tool execution out of the main chat flow, allowing for isolated processing, duplicate execution suppression via checkpoint claiming, and structured error handling. Users benefit from improved reliability and separation of concerns when tools are invoked during chat interactions.
_private\gpt/celery/tasks/tools · high confidence
Ingestion pipeline split into separate parse and vector-store tasks
The background ingestion process has been restructured from a single monolithic operation into two distinct Celery tasks: \parse\_task\ and \store\_vectors\_task\. This change allows the system to handle document parsing and vector indexing as separate steps, improving reliability and enabling features like parse-only mode for chat document conversion. The \parse\_task\ now validates and parses files, then automatically dispatches the \store\_vectors\_task\ to handle embedding generation and persistence, while also managing cleanup of temporary files and handling cancellation scenarios.
_private\gpt/celery/tasks/ingestion · high confidence
New event streaming models and interceptors
The event system has been restructured with a new set of Pydantic models in \private\_gpt/events/models\ and a new interceptor pipeline in \private\_gpt/events/interceptors\. Users will now see a richer set of streaming events, including granular content block deltas (text, thinking, citations, JSON input), specific tool result blocks (web search, code execution, MCP), and keepalive pings. The new \PingEventInterceptor\ ensures connections stay alive during idle periods, while the \FilterZylonEventInterceptor\ allows the event stream to be filtered based on the response mode (Zylon vs. Anthropic), ensuring clients only receive relevant content blocks.
_private\gpt/events/models · high confidence
New settings loader with profile-based configuration and environment variable model discovery
The application now uses a new settings loading system that supports multiple configuration profiles (default, override, and custom profiles specified via PGPT\_PROFILES) which are merged in order, allowing users to override default settings via a settings.override.yaml file. The system also introduces dynamic model discovery through environment variables using the PGPT\MODELS\\<MODEL\ID\>\\<PARAMETER\> pattern, enabling users to configure models without editing YAML files. Additionally, YAML configuration files now support environment variable expansion using the ${VAR} or ${VAR:default} syntax.
_private\gpt/settings · high confidence
Private GPT CLI revamped with new command structure and server management
The Private GPT command-line interface has been restructured to provide a more modular and robust user experience. The new CLI introduces distinct commands for managing the application lifecycle: 'serve' starts the HTTP server with support for PID files (enabling integration with systemd/launchd) and auto-reload for development, while 'run' launches connected code agents (such as Claude Code, OpenClaw, or OpenCode) with automatic model selection and interactive paging. A 'worker' command is now available to handle background tasks, but it is strictly gated behind the presence of the Celery library, preventing execution errors when Celery is not installed. The main entry point also includes improved command validation with typo suggestions for unknown commands.
_private\gpt/cli · high confidence
PrivateGPT v1 revamp: new architecture and streaming support
PrivateGPT has been revamped to version 1, introducing a new modular architecture that replaces the previous global state with a structured dependency injection system (using the \injector\ library) and request-scoped context propagation. This change enables robust, isolated worker profiles (chat, tools, full) with eager component loading to improve startup performance. The update also adds comprehensive Server-Sent Events (SSE) support for real-time chat streaming, including a new event model, formatter, and stream manager. Additionally, the application now uses Python's built-in \logging\ module instead of \loguru\, configures a centralized \PGPT\_HOME\ path for local data and caches, and integrates with LlamaIndex 0.10 for document indexing and retrieval.
_private\gpt · high confidence
Test coverage
Added comprehensive test coverage for chat engines and citation processing; Added comprehensive test coverage for core system components; Added comprehensive test coverage for the chat server subsystem; Added test coverage for context propagation, content retrieval, and dependency injection; Added test fixtures for PrivateGPT integration testing; Added tests for Anthropic model schema parity and drift detection; Added tests for Arq worker infrastructure; Added tests for MCP server OAuth token refresh and tool execution; Added tests for chat interceptor reliability and correctness; Added tests for content block serialization, pruning, and MCP token events; Added tests for model capabilities and primitive chunk retrieval; Added tests for server utility functions; Added tests for settings loading and validation; Added tests for skill validation and wrapper directory handling; Added tests for the new artifact ingestion and conversion system; Added tests for the server files API and Anthropic SDK integration; Added unit tests for SSE streaming components.
Dependencies
Initial release of PrivateGPT v1.0.1 with Poetry dependency management
This change introduces the first official release (v1.0.1) of PrivateGPT, migrating the project to use Poetry for dependency management via a new pyproject.toml file. The configuration defines the core application dependencies, including FastAPI, LlamaIndex, and various LLM providers (OpenAI, Anthropic, Mistral), as well as optional extras for document ingestion, vector stores (Qdrant), and database backends (Postgres, MySQL, MSSQL).
(dependencies) · high confidence
Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
How this codebase got here
This is the PUBLIC form of this artifact. Findings are listed in full, but the details of SECURITY findings — which rule fired, in which file, on which line, and how to fix it — are deliberately withheld, and any secret-scanner results are excluded entirely. Where detail is absent here it was REMOVED FOR PUBLICATION; it is not missing from the analysis. The complete artifact is available from the repository owner.
Score
- CAI 63 → 56 (-6.4)
Lenses
- Code Health 62 → 63 (+0.5)
- Architecture 87 → 87 (+0.0)
- Maturity 57 → 55 (-1.6)
- Readiness 75 → 71 (-3.7)
- Security 69 → 70 (+0.9)
- Domain Modelling 100 → 100 (+0.0)
- Accessibility 67 → 48 (-19.2)
- Performance 100 → 100 (+0.0)
Resolved (44)
- AsyncChatEngine._run_iteration (cognitive 24) (private_gpt/components/engines/chat/async_chat_engine.py)
- AsyncChatEngine._run_iteration (cyclomatic 20) (private_gpt/components/engines/chat/async_chat_engine.py)
- Duplicated block (11 lines × 2) (private_gpt/components/engines/chat/async_chat_engine.py)
- Duplicated block (121–122 lines × 2) (private_gpt/components/engines/chat/async_chat_engine.py)
- Duplicated block (12–13 lines × 2) (private_gpt/components/engines/chat/async_chat_engine.py)
- Duplicated block (14 lines × 2) (private_gpt/components/workflows/others/tree_summarize_synthesizer.py)
- Duplicated block (15 lines × 2) (private_gpt/components/engines/chat/async_chat_engine.py)
- Duplicated block (19 lines × 2) (private_gpt/components/engines/chat/async_chat_engine.py)
- Duplicated block (20 lines × 2) (private_gpt/components/workflows/others/tree_summarize_synthesizer.py)
- Duplicated block (24–25 lines × 2) (private_gpt/components/engines/chat/async_chat_engine.py)
- Duplicated block (33 lines × 2) (private_gpt/components/tools/builders/semantic_search_builder.py)
- Duplicated block (7–8 lines × 2) (private_gpt/components/engines/chat/async_chat_engine.py)
- High CVE: [GHSA redacted] (uv.lock)
- High CVE: [GHSA redacted] (uv.lock)
- High CVE: [GHSA redacted] (uv.lock)
- High: security finding (details withheld)
- High: security finding (details withheld)
- High: security finding (details withheld)
- High: security finding (details withheld)
- High: security finding (details withheld)
- …and 24 more
New (50)
- AsyncChatEngine._run_iteration_body (cognitive 24) (private_gpt/components/engines/chat/async_chat_engine.py)
- AsyncChatEngine._run_iteration_body (cyclomatic 20) (private_gpt/components/engines/chat/async_chat_engine.py)
- Critical CVE: [GHSA redacted] (uv.lock)
- Critical vulnerability: [GHSA redacted] (uv.lock)
- Duplicate function names register_task_packages in both arq and celery task registry modules. While they operate on different task queues, the identical naming implies a shared interface contract that doesn't exist (different underlying implementations).
- Duplicate function names across different subsystems (Arq vs Celery) that likely serve similar purposes (exposing health status) but are in separate modules. While technically distinct namespaces, having healthcheck.health in two major backend modules creates confusion for consumers who might expect a unified health interface.
- Duplicated block (10 lines × 2) (private_gpt/components/engines/chat/async_chat_engine.py)
- Duplicated block (10–11 lines × 2) (private_gpt/components/chat/processors/chat_history/documents/document_uploader.py)
- Duplicated block (123–124 lines × 2) (private_gpt/components/engines/chat/async_chat_engine.py)
- Duplicated block (15 lines × 2) (private_gpt/components/tools/builders/semantic_search_builder.py)
- Duplicated block (19–22 lines × 2) (private_gpt/components/engines/chat/async_chat_engine.py)
- Duplicated block (20 lines × 2) (private_gpt/components/engines/chat/async_chat_engine.py)
- Duplicated block (21 lines × 2) (private_gpt/components/workflows/others/tree_summarize_synthesizer.py)
- Duplicated block (23 lines × 3) (private_gpt/components/tools/processors/convert_documents_processor.py)
- Duplicated block (39 lines × 2) (private_gpt/components/tools/builders/semantic_search_builder.py)
- Duplicated block (41 lines × 2) (private_gpt/components/tools/builders/describe_image_tool_builder.py)
- FileTooLong: models/chat_config_models.py (private_gpt/components/chat/models/chat_config_models.py)
- FileTooLong: multimodality/image_handler.py (private_gpt/components/multimodality/image_handler.py)
- High CVE: [GHSA redacted] (uv.lock)
- High vulnerability: [GHSA redacted] (uv.lock)
- …and 30 more
Changes since last survey
- 14 commits — 7 feature/other, 7 fixes
By area
- private_gpt/components — 10 commits
- .github/workflows — 2 commits
- (root) — 1 commit
- private_gpt/server — 1 commit
Notable commits
- fix: fix(chat): Claude Code/OpenCode correctness and /v1/messages latency (prefix cache 48→95%, overhead 2.7→0.3 s) (#2400)
- fix: fix(chat): stop long chats from stalling the chat worker during condensation (#2407)
- fix: fix(citations): keep text after an unclosed bracket (#2414)
- fix: fix(mcp): emit original tool names as display metadata (#2408)
- fix: fix(tools): check {name, artifact_id} refs in knowledge_search and tabular analysis (#2412)
- fix: fix: clarify the system-message misuse error (#2379)
- fix: fix: point update-openapi-spec make target at the actual script path (#2393)
- change: chore(deps): bump astral-sh/setup-uv from 10.2.0 to 10.3.0 (#2410)
- change: ci: pin the third-party actions by commit, declare read-only tokens and stop persisting checkout credentials (#2416)
- change: feat(chat): describe images embedded in attached documents (#2418)
- change: feat(code-execution): clean and bound bash/view output before it reaches the model (#2415)
- change: feat(observability)!: vendor-neutral OpenTelemetry tracing (#2417)
- change: feat: land attachments in the sandbox and let the backend write to the agent workspace (#2404)
- change: perf(ingest): count node tokens in batches instead of one call per node (#2409)
Architecture
- Unchanged — 0 containers · 1 contexts · 0 edges
Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.
Survey your own repository
zylon-ai/private-gpt 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 25 October 2026 at a pinned commit. It is not a live figure and does not change until the project is measured again.
- Measured at commit 0f6a2de226374a7ccc7ac5e739054be8da9929d9 — the exact code this score is about.
- Scored under rubric-2026.10.5 — the same rubric and the same method as every other entry in this index.
- Measured by watchdog.canine.dev using codehealth-analyzer measure-2026.10.6+preprod-d36780c2d857.