Modules

class ragflow_async_sdk.apis.AgentAPI(client: AsyncHTTPClient)

Bases: SessionMixin[AgentSession], BaseAPI

API for managing agents and their sessions.

async ask(agent_id: str, session_id: str, prompt: str, *, stream: bool = False, **kwargs) → AgentCompletionResult | AsyncGenerator[AgentCompletionResult, None]

Ask a question in an agent session.

Parameters:

• agent_id – Agent ID.

• session_id – Session ID.

• prompt – User question.

• stream – Whether to return streaming results (default False).

• **kwargs – Additional parameters such as temperature, top_p, etc.

Returns:

AgentCompletionResult instance if stream=False, or an async generator yielding AgentCompletionResult items if stream=True.

Raises:

• RAGFlowValidationError – If required parameters are missing.

• RAGFlowAPIError – If API request fails.

Examples

# Non-streaming
result = await client.agents.ask(
    agent_id="agent_123",
    session_id="sess_456",
    prompt="Hello AI"
)
print(result.text)

# Streaming
async for chunk in client.agents.ask(
    agent_id="agent_123",
    session_id="sess_456",
    prompt="Hello AI",
    stream=True
):
    print(chunk.text)

async create_agent(title: str, dsl: dict, *, description: str | None = None) → None

Create a new agent. The create_agent method returns None because the server does not provide the created object. Use get_agent to retrieve it if needed.

Parameters:

• title – Agent title.

• dsl – Agent DSL configuration (graph, components, retrieval, etc.).

• description – Optional description of the agent.

Returns:

None.

Raises:

• RAGFlowAPIError – If creation fails.

• RAGFlowResponseError – If agent cannot be retrieved after creation.

async create_session(agent_id: str, *, name: str = 'New session', user_id: str | None = None) → AgentSession

Create a new session under an agent.

Parameters:

• agent_id – Agent ID.

• name – Optional session name.

• user_id – Optional user ID.

Returns:

AgentSession instance.

async delete_agent(agent_id: str) → bool

Delete an agent by ID.

Parameters:

agent_id – Agent ID.

Returns:

True if deletion succeeded, False otherwise.

async delete_sessions(agent_id: str, session_ids: str | list[str] | None = None) → None

Delete one or more agent sessions.

Parameters:

• agent_id – Agent ID.

• session_ids – Single or list of session IDs. If None, delete all sessions.

async get_agent(*, agent_id: str | None = None, title: str | None = None) → Agent | None

Retrieve a single agent by ID or title.

Exactly one of agent_id or title must be provided.

Parameters:

• agent_id – Optional agent ID.

• title – Optional agent title.

Returns:

Agent instance

Raises:

• RAGFlowValidationError – If both or neither of agent_id and title are provided.

• RAGFlowConflictError – If multiple agents match the query.

async get_agent_session(agent_id: str, *, session_id: str | None = None, name: str | None = None) → AgentSession | None

async list_agents(*, page: int = 1, page_size: int = 30, orderby: OrderBy | str = OrderBy.CREATE_TIME, desc: bool = True, agent_id: str | None = None, title: str | None = None) → tuple[list[Agent], int]

List agents with optional filters.

Parameters:

• page – Page number.

• page_size – Number of items per page.

• orderby – Field to sort by.

• desc – Sort descending if True.

• agent_id – Optional filter by agent ID.

• title – Optional filter by agent title.

Returns:

Tuple containing a list of Agent instances and total count.

async list_sessions(agent_id: str, *, page: int = 1, page_size: int = 30, orderby: OrderBy | str = OrderBy.CREATE_TIME, desc: bool = True, name: str | None = None, session_id: str | None = None, user_id: str | None = None) → tuple[list[AgentSession], int]

List sessions for an agent.

Parameters:

• agent_id – Agent ID.

• page – Page number.

• page_size – Number of items per page.

• orderby – Field to sort by.

• desc – Sort descending if True.

• name – Optional session name filter.

• session_id – Optional session ID filter.

• user_id – Optional user ID filter.

Returns:

Tuple containing a list of AgentSession instances and total count.

async update_agent(agent_id: str, *, title: str | None = None, description: str | None = None, dsl: dict[str, Any] | None = None) → None

Update an existing agent.

Parameters:

• agent_id – Agent ID (required).

• title – Optional new title for the agent.

• description – Optional new description.

• dsl – Optional updated canvas DSL object.

Raises:

ValueError – If no fields are provided for update.

async update_session(agent_id: str, session_id: str, *, name: str | None = None, user_id: str | None = None) → None

Update an agent session.

Parameters:

• agent_id – Agent ID.

• session_id – Session ID.

• name – Optional new session name.

• user_id – Optional new user ID.

class ragflow_async_sdk.apis.ChatAPI(client: AsyncHTTPClient)

Bases: SessionMixin[ChatSession], BaseAPI

API for managing chat assistants and their sessions.

async ask(chat_id: str, session_id: str, prompt: str, *, stream: bool = False, **kwargs) → AsyncGenerator[ChatCompletionResult, None] | ChatCompletionResult

Ask a question in a chat session.

Parameters:

• chat_id – Chat assistant ID.

• session_id – Session ID.

• prompt – User question.

• stream – Whether to return streaming results.

• **kwargs – Additional parameters (temperature, top_p, etc.).

Returns:

Either a single ChatCompletionResult or an async generator if streaming.

async create_chat(name: str, *, dataset_ids: list[str] | None = None, avatar: str | None = None, llm: dict[str, Any] | None = None, prompt: dict[str, Any] | None = None) → ChatAssistant

Create a new chat assistant.

Parameters:

• name – Chat assistant name.

• dataset_ids – Optional list of dataset IDs to associate.

• avatar – Optional avatar URL.

• llm – Optional LLM configuration.

• prompt – Optional prompt configuration.

Returns:

ChatAssistant instance.

async create_session(chat_id: str, *, name: str | None = None, user_id: str | None = None) → ChatSession

Create a new session under a chat assistant.

Parameters:

• chat_id – Chat assistant ID.

• name – Optional session name.

• user_id – Optional user ID.

Returns:

ChatSession instance.

async delete_chats(ids: str | list[str] | None = None) → None

Delete chat assistants by ID.

Parameters:

ids – Single or list of chat IDs to delete. If None, deletes all chats.

async delete_sessions(chat_id: str, session_ids: str | list[str] | None = None) → None

Delete one or more chat sessions.

Parameters:

• chat_id – Chat assistant ID.

• session_ids – Single or list of session IDs to delete. If None, delete all.

async get_chat(*, chat_id: str | None = None, name: str | None = None) → ChatAssistant | None

Get a single chat assistant by ID or name.

Exactly one of chat_id or name must be provided.

Parameters:

• chat_id – Chat assistant ID.

• name – Chat assistant name.

Returns:

ChatAssistant instance if found, otherwise None.

Raises:

• RAGFlowValidationError – If parameters are invalid.

• RAGFlowConflictError – If multiple chats match.

async get_chat_session(chat_id: str, *, session_id: str | None = None, name: str | None = None) → ChatSession | None

async list_chats(*, page: int = 1, page_size: int = 30, orderby: OrderBy | str = OrderBy.CREATE_TIME, desc: bool = True, chat_id: str | None = None, name: str | None = None) → tuple[list[ChatAssistant], int]

List chat assistants with optional filters.

Parameters:

• page – Page number.

• page_size – Number of items per page.

• orderby – Field to sort by.

• desc – Sort descending if True.

• chat_id – Optional filter by chat ID.

• name – Optional filter by chat name.

Returns:

Tuple containing a list of ChatAssistant instances and the total count.

async list_sessions(chat_id: str, *, page: int = 1, page_size: int = 30, orderby: OrderBy | str = OrderBy.CREATE_TIME, desc: bool = True, name: str | None = None, session_id: str | None = None, user_id: str | None = None) → tuple[list[ChatSession], int]

List sessions for a chat assistant.

Parameters:

• chat_id – Chat assistant ID.

• page – Page number.

• page_size – Number of items per page.

• orderby – Field to sort by.

• desc – Sort descending if True.

• name – Optional session name filter.

• session_id – Optional session ID filter.

• user_id – Optional user ID filter.

Returns:

Tuple containing a list of ChatSession instances and total count.

async update_chat(chat_id: str, *, name: str | None = None, dataset_ids: list[str] | None = None, avatar: str | None = None, llm: dict[str, Any] | None = None, prompt: dict[str, Any] | None = None) → None

Update an existing chat assistant.

Parameters:

• chat_id – Chat assistant ID.

• name – Optional new name.

• dataset_ids – Optional updated dataset IDs.

• avatar – Optional updated avatar URL.

• llm – Optional updated LLM configuration.

• prompt – Optional updated prompt configuration.

Raises:

ValueError – If no fields are provided for update.

async update_session(chat_id: str, session_id: str, *, name: str | None = None, user_id: str | None = None) → None

Update a chat session.

Parameters:

• chat_id – Chat assistant ID.

• session_id – Session ID.

• name – Optional new session name.

• user_id – Optional new user ID.

class ragflow_async_sdk.apis.ChunkAPI(client: AsyncHTTPClient)

Bases: BaseAPI

API for managing document chunks within datasets.

async add_chunk(dataset_id: str, document_id: str, content: str, important_keywords: list[str] | None = None, questions: list[str] | None = None) → Chunk

Add a new chunk to a specific document.

Parameters:

• dataset_id – Dataset containing the document.

• document_id – Target document ID.

• content – Text content of the chunk.

• important_keywords – Optional list of keywords for chunk importance.

• questions – Optional list of questions associated with the chunk.

Returns:

Added chunk data.

Return type:

Chunk

async delete_chunks(dataset_id: str, document_id: str, *, chunk_ids: str | list[str] | None = None) → None

Delete chunks by ID.

Parameters:

• dataset_id – Dataset containing the document.

• document_id – Document ID.

• chunk_ids – List of chunk IDs to delete. If None, deletes all chunks.

async get_chunk(dataset_id: str, document_id: str, *, chunk_id: str) → Chunk | None

Get a single chunk by ID within a document.

Parameters:

• dataset_id – Dataset ID.

• document_id – Document ID.

• chunk_id – Chunk ID.

Returns:

Chunk instance if found, otherwise None.

Raises:

• RAGFlowValidationError – If required parameters are missing.

• RAGFlowConflictError – If multiple chunks match.

async get_metadata_summary(dataset_id: str) → dict[str, Any]

Retrieve a metadata summary for all documents in a dataset.

Parameters:

dataset_id – Dataset ID.

Returns:

Metadata summary.

Return type:

dict

async list_chunks(dataset_id: str, document_id: str, *, keywords: str | None = None, page: int = 1, page_size: int = 1024, chunk_id: str | None = None) → tuple[list[Chunk], int]

List chunks in a document with optional filters.

Parameters:

• dataset_id – Dataset containing the document.

• document_id – Target document ID.

• keywords – Optional search keywords.

• page – Page number.

• page_size – Number of chunks per page.

• chunk_id – Optional filter by specific chunk ID.

Returns:

Tuple of (list of Chunk objects, total count).

async retrieve_chunks(question: str, *, dataset_ids: str | list[str] | None = None, document_ids: str | list[str] | None = None, page: int = 1, page_size: int = 30, similarity_threshold: float = 0.2, vector_similarity_weight: float = 0.3, top_k: int = 1024, rerank_id: str | None = None, keyword: bool = False, highlight: bool = False, cross_languages: list[str] | None = None, metadata_condition: dict | None = None, use_kg: bool = False, toc_enhance: bool = False) → dict[str, Any]

Retrieve chunks from datasets or documents based on query.

Parameters:

• question – Query string or keywords (required).

• dataset_ids – Dataset IDs to search.

• document_ids – Document IDs to search.

• page – Page number.

• page_size – Chunks per page.

• similarity_threshold – Minimum similarity score.

• vector_similarity_weight – Weight of vector similarity.

• top_k – Number of chunks considered for vector computation.

• rerank_id – Optional rerank model ID.

• keyword – Enable keyword-based matching.

• highlight – Highlight matched terms.

• cross_languages – Target languages for translation.

• metadata_condition – Metadata filter conditions.

• use_kg – Enable knowledge graph multi-hop search.

• toc_enhance – Enable table-of-contents enhanced search.

Returns:

Retrieved chunks, document aggregations, and total count.

Return type:

dict

Raises:

RAGFlowValidationError – If question is empty or dataset/document IDs are missing.

async update_chunk(dataset_id: str, document_id: str, chunk_id: str, *, content: str | None = None, important_keywords: list[str] | None = None, available: bool | None = None) → None

Update content or settings for a specific chunk.

Parameters:

• dataset_id – Dataset containing the document.

• document_id – Document ID.

• chunk_id – Chunk ID to update.

• content – New content for the chunk.

• important_keywords – Updated list of important keywords.

• available – Whether the chunk is available (True/False).

Raises:

RAGFlowValidationError – If no fields are provided to update.

async update_metadata(dataset_id: str, *, selector: dict | None = None, updates: list[dict] | None = None, deletes: list[dict] | None = None) → dict[str, int]

Batch update or delete document-level metadata.

Parameters:

• dataset_id – Dataset ID.

• selector – Optional filter, e.g., {“document_ids”: […], “metadata_condition”: {…}}.

• updates – List of metadata updates, each {“key”: str, “match”: str, “value”: str}.

• deletes – List of metadata deletions, each {“key”: str, “value”: Optional[str]}.

Returns:

{“updated”: int, “matched_docs”: int}

Return type:

dict

Raises:

RAGFlowValidationError – If no updates or deletes are provided.

class ragflow_async_sdk.apis.DatasetAPI(client: AsyncHTTPClient)

Bases: BaseAPI

API for managing datasets asynchronously.

This class provides all operations related to datasets in RAGFlow, including creation, update, deletion, listing, and knowledge graph construction.

Examples

import asyncio
from ragflow_async_sdk import AsyncRAGFlowClient

async def main():
    async with AsyncRAGFlowClient(
        server_url="http://your-ragflow-address",
        api_key="YOUR_API_KEY",
    ) as client:
        # Create a dataset
        dataset = await client.datasets.create_dataset(
            name="MyDataset",
            chunk_method="NAIVE"
        )
        print(dataset.id)

        # List datasets
        datasets, total = await client.datasets.list_datasets(page=1, page_size=10)
        print(total)

asyncio.run(main())

async construct_knowledge_graph(dataset_id: str) → str

Run GraphRAG construction for a dataset.

Parameters:

dataset_id – Target dataset ID.

Returns:

Graphrag task ID.

Raises:

• RAGFlowValidationError – If dataset_id is missing.

• RAGFlowAPIError – If task creation fails or response is invalid.

async construct_raptor(dataset_id: str) → str

Run RAPTOR construction for a dataset.

Parameters:

dataset_id – Target dataset ID.

Returns:

Raptor task ID.

Raises:

• RAGFlowValidationError – If dataset_id is missing.

• RAGFlowAPIError – If task creation fails or response is invalid.

async create_dataset(name: str, *, chunk_method: ChunkMethod | str | None = ChunkMethod.NAIVE, parser_config: dict | None = None, parse_type: str | None = None, pipeline_id: str | None = None, description: str | None = None, avatar: str | None = None, permission: Permission | str = Permission.ME) → Dataset

Create a new dataset.

Parameters:

• name – Dataset name.

• chunk_method – Chunking method, mutually exclusive with parse_type/pipeline_id.

• parser_config – Parser configuration for the dataset.

• parse_type – Parsing type (used with pipeline_id).

• pipeline_id – Pipeline ID (used with parse_type).

• description – Optional description.

• avatar – Optional avatar URL.

• permission – Access permission for the dataset.

Returns:

Instance of the created dataset.

Return type:

Dataset

Raises:

• RAGFlowValidationError – If parameters are invalid.

• RAGFlowAPIError – If creation fails.

Examples

dataset = await client.datasets.create_dataset(
    name="ExampleDataset",
    chunk_method="NAIVE"
)
print(dataset.id)

async delete_datasets(ids: str | list[str] | None = None) → None

Delete datasets by ID.

Parameters:

ids – Dataset IDs to delete. - None: delete all datasets - []: delete none - [id1, id2]: delete specific datasets

Raises:

RAGFlowAPIError – If deletion fails.

async delete_knowledge_graph(dataset_id: str) → None

Delete the knowledge graph of a dataset.

Parameters:

dataset_id – Target dataset ID.

Raises:

• RAGFlowValidationError – If dataset_id is missing.

• RAGFlowAPIError – If deletion fails or response is invalid.

async get_dataset(*, dataset_id: str | None = None, name: str | None = None) → Dataset

Get a single dataset by ID or name.

Exactly one of dataset_id or name must be provided.

Parameters:

• dataset_id – Dataset ID.

• name – Dataset name.

Returns:

Dataset instance.

Raises:

• RAGFlowValidationError – If both or neither parameters are provided.

• RAGFlowConflictError – If multiple datasets match the query.

async get_graphrag_status(dataset_id: str) → TaskStatus

Get the status of knowledge graph construction.

Parameters:

dataset_id – Target dataset ID.

Returns:

TaskStatus instance with progress, messages, and timestamps.

Raises:

• RAGFlowValidationError – If dataset_id is missing.

• RAGFlowAPIError – If status retrieval fails.

async get_knowledge_graph(dataset_id: str) → KnowledgeGraph

Retrieve the knowledge graph of a dataset.

Parameters:

dataset_id – Target dataset ID.

Returns:

KnowledgeGraph instance containing nodes, edges, metadata, and mind map.

Raises:

• RAGFlowValidationError – If dataset_id is not provided.

• RAGFlowAPIError – If retrieval fails.

async get_raptor_status(dataset_id: str) → TaskStatus

Get the status of RAPTOR construction.

Parameters:

dataset_id – Target dataset ID.

Returns:

TaskStatus instance with progress, messages, and timestamps.

Raises:

• RAGFlowValidationError – If dataset_id is missing.

• RAGFlowAPIError – If status retrieval fails.

async list_datasets(*, page: int = 1, page_size: int = 30, order_by: OrderBy | str = OrderBy.CREATE_TIME, desc: bool = True, dataset_id: str | None = None, name: str | None = None) → tuple[list[Dataset], int]

List datasets with optional filters.

Parameters:

• page – Page number.

• page_size – Items per page.

• order_by – Field to order by.

• desc – Descending order if True.

• dataset_id – Optional dataset ID filter.

• name – Optional dataset name filter.

Returns:

A tuple containing a list of Dataset instances and total count.

Return type:

tuple

Raises:

RAGFlowAPIError – If listing fails.

async update_dataset(dataset_id: str, *, name: str | None = None, avatar: str | None = None, description: str | None = None, embedding_model: str | None = None, permission: Permission | str | None = None, pagerank: int | None = None, chunk_method: ChunkMethod | str | None = None, parser_config: dict[str, Any] | None = None) → None

Update dataset fields.

Only provide fields to be updated.

Parameters:

• dataset_id – Target dataset ID.

• name – Optional new name.

• avatar – Optional avatar URL.

• description – Optional description.

• embedding_model – Optional embedding model.

• permission – Optional access permission.

• pagerank – Optional pagerank value.

• chunk_method – Optional chunk method.

• parser_config – Optional parser configuration.

Raises:

• RAGFlowValidationError – If dataset_id is missing or parameters invalid.

• RAGFlowAPIError – If update fails.

class ragflow_async_sdk.apis.DocumentAPI(client: AsyncHTTPClient)

Bases: BaseAPI

API for managing documents.

async delete_documents(dataset_id: str, ids: str | list[str] | None = None) → None

Delete documents by ID in a dataset.

Parameters:

• dataset_id – Dataset ID.

• ids – List of document IDs to delete. If None, deletes all documents.

async download_document(dataset_id: str, document_id: str) → DownloadedFile

Download a document as a DownloadedFile.

Parameters:

• dataset_id – The ID of the dataset containing the document.

• document_id – The ID of the document to download.

Returns:

A dataclass containing:

• filename: Original filename from the server (parsed from Content-Disposition)

• content_type: HTTP Content-Type

• stream: Asynchronous iterator of bytes

Return type:

DownloadedFile

Raises:

RAGFlowAPIError – If the download fails.

async get_document(dataset_id: str, *, document_id: str | None = None, name: str | None = None) → Document

Get a single document by ID or name within a dataset.

Exactly one of document_id or name must be provided.

Parameters:

• dataset_id – Dataset ID.

• document_id – Document ID.

• name – Document name.

Returns:

Document instance if found, otherwise None.

Raises:

• RAGFlowValidationError – If parameters are invalid.

• RAGFlowConflictError – If multiple documents match.

async list_documents(dataset_id: str, *, page: int = 1, page_size: int = 30, order_by: OrderBy | str = OrderBy.CREATE_TIME, desc: bool = True, keywords: str | None = None, document_id: str | None = None, name: str | None = None, create_time_from: int = 0, create_time_to: int = 0, suffix: list[str] | None = None, run: list[str] | None = None, metadata_condition: dict[str, Any] | None = None) → tuple[list[Document], int]

List documents in a dataset with optional filtering.

Parameters:

• dataset_id – Dataset ID.

• page – Page number.

• page_size – Items per page.

• order_by – Field to sort by.

• desc – Whether to sort descending.

• keywords – Search keywords.

• document_id – Filter by specific document ID.

• name – Filter by document name.

• create_time_from – Filter documents created after this timestamp.

• create_time_to – Filter documents created before this timestamp.

• suffix – Filter by file suffixes.

• run – Filter by ingestion run IDs.

• metadata_condition – Filter by metadata conditions.

Returns:

Tuple of (list of Document objects, total count).

async parse_documents(dataset_id: str, document_ids: list[str]) → None

Start parsing specified documents in a dataset.

Parameters:

• dataset_id – Dataset ID.

• document_ids – List of document IDs to parse.

Raises:

RAGFlowValidationError – If dataset_id or document_ids are invalid.

async stop_parsing_documents(dataset_id: str, document_ids: list[str]) → None

Stop parsing specified documents in a dataset.

Parameters:

• dataset_id – Dataset ID.

• document_ids – List of document IDs to stop parsing.

Raises:

RAGFlowValidationError – If dataset_id or document_ids are invalid.

async update_document(dataset_id: str, document_id: str, *, name: str | None = None, meta_fields: dict[str, Any] | None = None, chunk_method: ChunkMethod | str | None = None, parser_config: dict[str, Any] | None = None, enabled: int | None = None) → Document

Update a document’s metadata or parsing configuration.

Only provide the fields you want to update.

Parameters:

• dataset_id – Dataset containing the document.

• document_id – Document ID to update.

• name – New name of the document.

• meta_fields – Metadata fields to update.

• chunk_method – Parsing chunk method (str or ChunkMethod).

• parser_config – Parser configuration if chunk_method is changed.

• enabled – 1 to enable, 0 to disable document.

Returns:

Updated Document instance.

async upload_documents(dataset_id: str, files: list[tuple[str, bytes, str]]) → list[Document]

Upload multiple documents to a dataset.

Parameters:

• dataset_id – Target dataset ID.

• files – List of files to upload, each as (filename, content_bytes, content_type).

Returns:

Tuple containing the list of uploaded documents and the number of documents.

class ragflow_async_sdk.apis.FileAPI(client: AsyncHTTPClient)

Bases: BaseAPI

API for managing files and folders.

async convert_files(file_ids: list[str], kb_ids: list[str]) → list[ConversionResult]

Convert files into knowledge base entries.

Parameters:

• file_ids – List of file IDs to convert.

• kb_ids – List of target knowledge base IDs.

Returns:

List of conversion results (dicts).

Raises:

• RAGFlowValidationError – If parameters are missing.

• RAGFlowAPIError – If conversion fails.

async create_file_or_folder(name: str, type_: FileType | str, parent_id: str | None = None) → Folder | File

Create a new folder or virtual file.

Parameters:

• name – Name of the file or folder.

• type – Type of the object (“FOLDER” or “FILE”).

• parent_id – Optional parent folder ID.

Returns:

Folder instance if type is “FOLDER”, else File instance.

Raises:

• RAGFlowValidationError – If required parameters are missing.

• RAGFlowAPIError – If creation fails.

async delete_files(file_ids: list[str]) → bool

Delete files by their IDs.

Parameters:

file_ids – List of file IDs to delete.

Returns:

True if deletion succeeded, False otherwise.

Raises:

• RAGFlowValidationError – If file_ids is empty.

• RAGFlowAPIError – If deletion fails.

async download_file(file_id: str) → DownloadedFile

Download the content of a file as a DownloadedFile.

Parameters:

file_id – ID of the file to download.

Returns:

contains filename, content_type, and async stream.

Return type:

DownloadedFile

Raises:

• RAGFlowValidationError – If file_id is missing.

• RAGFlowAPIError – If download fails.

async get_all_parent_folders(file_id: str) → list[Folder]

Get all parent folders of a file up to the root.

Parameters:

file_id – ID of the file.

Returns:

List of Folder instances from immediate parent up to root.

Raises:

• RAGFlowValidationError – If file_id is missing.

• RAGFlowAPIError – If request fails.

async get_parent_folder(file_id: str) → Folder

Get the parent folder of a file.

Parameters:

file_id – ID of the file.

Returns:

Folder instance representing the parent folder.

Raises:

• RAGFlowValidationError – If file_id is missing.

• RAGFlowAPIError – If request fails.

async get_root_folder() → Folder

Get the root folder of the file system.

Returns:

Folder instance representing the root folder.

Raises:

RAGFlowAPIError – If request fails.

async list_files(parent_id: str | None = None, keywords: str | None = None, page: int = 1, page_size: int = 15, orderby: OrderBy | str = OrderBy.CREATE_TIME, desc: bool = True) → tuple[ListFilesResult, int]

List files in a folder with optional filtering and pagination.

Parameters:

• parent_id – Optional ID of the parent folder to list files from.

• keywords – Optional search keywords for file names.

• page – Page number for pagination.

• page_size – Number of items per page.

• orderby – Field to order results by.

• desc – Whether to sort in descending order.

Returns:

Tuple of ListFilesResult instance and total file count.

Raises:

RAGFlowAPIError – If listing fails.

async move_files(src_file_ids: list[str], dest_file_id: str) → bool

Move files to a new folder.

Parameters:

• src_file_ids – List of source file IDs to move.

• dest_file_id – Destination folder ID.

Returns:

True if move succeeded, False otherwise.

Raises:

• RAGFlowValidationError – If parameters are missing.

• RAGFlowAPIError – If move operation fails.

async rename_file(file_id: str, name: str) → bool

Rename a file.

Parameters:

• file_id – ID of the file to rename.

• name – New name for the file.

Returns:

True if rename succeeded, False otherwise.

Raises:

• RAGFlowValidationError – If file_id or name is missing.

• RAGFlowAPIError – If renaming fails.

async upload_files(files: list[tuple[str, bytes, str]], parent_id: str | None = None) → list[File]

Upload multiple files to a folder.

Parameters:

• files – List of tuples (filename, content_bytes, content_type).

• parent_id – Optional ID of the parent folder.

Returns:

List of uploaded File objects.

Raises:

• RAGFlowValidationError – If files list is empty or invalid.

• RAGFlowAPIError – If upload fails.

class ragflow_async_sdk.apis.SessionAPI(client: AsyncHTTPClient)

Bases: BaseAPI

async generate_related_questions(agent_id: str, question: str, industry: str) → list[str]

Generate 5-10 alternative questions from the user’s original query.

Parameters:

• agent_id – The ID of the agent.

• question – The original user question.

• industry – The industry/context of the question.

Returns:

List of generated related questions.

Raises:

• RAGFlowAPIError – If API call fails.

• RAGFlowValidationError – If parameters are missing.

class ragflow_async_sdk.apis.SystemAPI(client: AsyncHTTPClient)

Bases: BaseAPI

System-related API endpoints.

async healthz() → SystemHealth

Check the health status of the system.

This endpoint does not require authentication.

Returns:

Parsed system health information.

Return type:

SystemHealth