ragflow AGENTS.md

RAGFlow Instructions

Use this file as the local operating guide for the current codebase. Prefer the code and the current CLAUDE.md over any older convention or remembered project shape.

Core Stance

• Treat legacy code as liability, not as a compatibility target.
• Prefer deletion over shims, deprecated branches, wrapper APIs, and dual-track migration notes.
• If old and new implementations coexist, converge to one path unless an external contract forces compatibility.
• Remove dead tests, commented-out code, stale docs, and "move later" notes instead of preserving them.
• Reduce public surface area when a helper can be made private or internal.
• Keep refactors centered on the owning abstraction, not on adjacent compatibility layers.

Current stack

• Backend: Python 3.13+, Quart-based API server, Peewee ORM, async workers.
• Frontend: React + TypeScript + Vite in web/ (dual-backend Go/Python variant conventions: see web/CLAUDE.md).
• Go: the repository also has a substantial Go module for servers, ingestion, parser/runtime, CLI, and supporting services.
• Runtime services commonly include MySQL/PostgreSQL, Redis, MinIO, and Elasticsearch/Infinity/OpenSearch depending on configuration.

Code Layout to Expect

• api/: Python API server entrypoints, blueprints, services, and database code.
• rag/: ingestion, retrieval, LLM integration, and graph RAG logic.
• deepdoc/: parsing and OCR.
• agent/: workflow canvas, components, tools, and templates.
• cmd/: Go entrypoints. ragflow_main is the main server/admin/ingestor binary surface; ragflow-cli is the CLI entrypoint.
• internal/: main Go application code. Important subtrees:
• internal/agent/: Go agent runtime, canvas execution, components, tool bindings, workflow helpers.
• internal/cli/: CLI parsing, HTTP transport, command execution, response formatting.
• internal/dao/: Go data-access layer and persistence-facing helpers.
• internal/deepdoc/: Go DeepDOC integrations, especially native-backed PDF/DOCX parsing.
• internal/engine/: search/index backends such as Elasticsearch and Infinity.
• internal/entity/: shared Go entities and model definitions.
• internal/handler/: HTTP handlers and route-facing request logic.
• internal/ingestion/: Go ingestion pipeline, canvas adapter, components, wiring, service orchestration.
• internal/ingestion/component/: stage implementations such as file/parser/chunker/tokenizer/extractor.
• internal/ingestion/pipeline/: DSL translation, canvas-driven execution, checkpoints, resume/run logic.
• internal/parser/: parser and chunk libraries used by ingestion and other Go paths.
• internal/parser/parser/: typed parse-result parsers for markdown/html/pdf/docx/xlsx/text and related families.
• internal/parser/chunk/: chunk operator library and DSL/typed execution helpers.
• internal/service/: higher-level business services used by handlers and server flows.
• internal/storage/: storage backends and in-memory test doubles.
• internal/router/: HTTP route registration.
• internal/server/: server bootstrap/config wiring.
• internal/cpp/: C++ sources used by native-backed Go features.
• web/: frontend application.
• docker/: local and production compose files.
• sdk/ and test/: SDK and automated tests.