RAGFlow Python SDK#

The RAGFlow Python SDK (ragflow_sdk) is a thin client wrapper around the RAGFlow REST API. Its primary role is to translate JSON API responses into typed Python objects and expose CRUD operations as methods on those objects. The entry point is the RAGFlow class; all module classes (DataSet, Document, Chunk, Chat, Agent, Memory) are instantiated by that class and are not meant to be constructed directly.

Public exports: RAGFlow, DataSet, Chat, Session, Document, Chunk, Agent, Memory 1.

Architecture: RAGFlow → Base → Module Objects#

RAGFlow — HTTP layer#

RAGFlow.__init__ accepts api_key, base_url, and version (default "v1") and constructs self.api_url = f"{base_url}/api/{version}". It attaches a Bearer token Authorization header to every request. The five raw HTTP methods (post, get, delete, put, patch) delegate directly to requests and return raw Response objects.

Base — field mapping and HTTP delegation#

Base is the parent class of every module object. Its constructor stores a reference to the root RAGFlow instance as self.rag, then calls _update_from_dict, which iterates the API response dict and sets each key as an instance attribute. Nested dicts are recursively wrapped in a new Base instance, giving dot-access to nested fields (e.g., dataset.parser_config.chunk_token_num) 2.

Base also re-exposes the five HTTP methods (post, get, rm, put, patch) as thin proxies that delegate back to self.rag 3, so module methods can call self.get(...) without holding a direct reference to requests.

to_json() recursively serializes the object back to a plain dict, skipping rag and callables.

DataSet — field whitelisting pattern#

DataSet extends Base and introduces a field whitelist. In __init__, it explicitly declares every accepted field with a default value:

Before calling super().__init__(), it strips any key from res_dict that is not already in self.__dict__ 4. This whitelist prevents unexpected API fields from leaking into the object. Other modules (e.g., Document, Chunk) do not apply this filter and accept all fields returned by the API.

DataSet contains a nested class DataSet.ParserConfig (itself a Base subclass with no additional logic), used for typed parser configuration when creating datasets via RAGFlow.create_dataset.

Module Object Reference#

All modules live under sdk/python/ragflow_sdk/modules/.

Key Patterns and Gotchas#

API response shape. All RAGFlow API responses carry a code field; 0 means success. Module factory methods check res.get("code") == 0 and raise Exception(res["message"]) on failure 5. Callers should wrap SDK calls in try/except.

Mutable state after update. DataSet.update() calls PUT /datasets/{id} and then calls _update_from_dict on the returned data payload 6, so the in-memory object reflects server state after a successful update.

Synchronous vs. async parsing. DataSet.parse_documents is synchronous: it calls async_parse_documents (POST to /datasets/{id}/chunks) then polls _get_documents_status at 1-second intervals until all documents reach a terminal state (DONE, FAIL, or CANCEL) 7. Use async_parse_documents directly to avoid blocking.

Nested dict → Base coercion. Because _update_from_dict wraps every nested dict in a plain Base, accessing dataset.parser_config.some_field works, but the object has no domain-specific methods — it is a generic attribute bag 2.

Chunk update errors. The Chunk module defines a custom ChunkUpdateError exception (carrying code, message, and details) rather than the generic Exception used elsewhere 8.

Entry Points for Deeper Investigation#

• SDK root: sdk/python/ragflow_sdk/ — package layout and __init__.py exports 1
• HTTP client: ragflow.py — RAGFlow class, all top-level API methods
• Base class: modules/base.py — field mapping, HTTP delegation, serialization
• DataSet: modules/dataset.py — whitelist pattern, document and chunk lifecycle