docs: update documentation to align with current Python API implementation (#19163)

update Python API documentation to align with current API implementation
delete words about RAPTOR & knowledge graph in HTTP API documents

docs/references/python_api_reference.md

@@ -128,10 +128,12 @@ RAGFlow.create_dataset(
     name: str,
     avatar: Optional[str] = None,
     description: Optional[str] = None,
-    embedding_model: Optional[str] = "BAAI/bge-large-zh-v1.5@BAAI",
+    embedding_model: Optional[str] = None,
     permission: str = "me",
     chunk_method: str = "naive",
-    parser_config: DataSet.ParserConfig = None
+    parser_config: Optional[DataSet.ParserConfig] = None,
+    auto_metadata_config: Optional[dict[str, Any]] = None
+
 ) -> DataSet
 ```
 
@@ -154,6 +156,13 @@ Base64 encoding of the avatar. Defaults to `None`
 
 A brief description of the dataset to create. Defaults to `None`.
 
+##### embedding_model: `string | None`
+
+The embedding model to use for the dataset. Defaults to `None`.
+
+##### auto_metadata_config: `dict[str, Any] | None`
+
+The automatic metadata extraction configuration for the dataset. Defaults to `None`.
 
 ##### permission
 
@@ -167,7 +176,7 @@ Specifies who can access the dataset to create. Available options:
 The chunking method of the dataset to create. Available options:
 
 - `"naive"`: General (default)
-- `"manual`: Manual
+- `"manual"`: Manual
 - `"qa"`: Q&A
 - `"table"`: Table
 - `"paper"`: Paper
@@ -178,7 +187,7 @@ The chunking method of the dataset to create. Available options:
 - `"one"`: One
 - `"email"`: Email
 
-##### parser_config
+##### parser_config: `DataSet.ParserConfig | None`
 
 The parser configuration of the dataset. A `ParserConfig` object's attributes vary based on the selected `chunk_method`:
 
@@ -186,7 +195,7 @@ The parser configuration of the dataset. A `ParserConfig` object's attributes va
   `{"chunk_token_num":512,"delimiter":"\\n","html4excel":False,"layout_recognize":True,"raptor":{"use_raptor":False},"parent_child":{"use_parent_child":False,"children_delimiter":"\\n"}}`.
 - `chunk_method`=`"qa"`:
   `{"raptor": {"use_raptor": False}}`
-- `chunk_method`=`"manuel"`:
+- `chunk_method`=`"manual"`:
   `{"raptor": {"use_raptor": False}}`
 - `chunk_method`=`"table"`:
   `None`
@@ -202,8 +211,6 @@ The parser configuration of the dataset. A `ParserConfig` object's attributes va
   `{"raptor": {"use_raptor": False}}`
 - `chunk_method`=`"one"`:
   `None`
-- `chunk_method`=`"knowledge-graph"`:
-  `{"chunk_token_num":128,"delimiter":"\\n","entity_types":["organization","person","location","event","time"]}`
 - `chunk_method`=`"email"`:
   `None`
 
@@ -266,9 +273,9 @@ RAGFlow.list_datasets(
     page_size: int = 30,
     orderby: str = "create_time",
     desc: bool = True,
-    id: str = None,
-    name: str = None,
-    include_parsing_status: bool = False
+    id: str | None = None,
+    ids: list[str] | None = None,
+    name: str | None = None,
 ) -> list[DataSet]
 ```
 
@@ -303,15 +310,9 @@ The ID of the dataset to retrieve. Defaults to `None`.
 
 The name of the dataset to retrieve. Defaults to `None`.
 
-##### include_parsing_status: `bool`
+##### ids: `list[str] | None`
 
-Whether to include document parsing status counts in each returned `DataSet` object. Defaults to `False`. When set to `True`, each `DataSet` object will include the following additional attributes:
-
-- `unstart_count`: `int` Number of documents not yet started parsing.
-- `running_count`: `int` Number of documents currently being parsed.
-- `cancel_count`: `int` Number of documents whose parsing was canceled.
-- `done_count`: `int` Number of documents that have been successfully parsed.
-- `fail_count`: `int` Number of documents whose parsing failed.
+The IDs of the datasets to retrieve. Defaults to `None`. The `id` and `ids` parameters cannot be used together.
 
 #### Returns
 
@@ -334,11 +335,12 @@ dataset = rag_object.list_datasets(id = "id_1")
 print(dataset[0])
 ```
 
-##### List datasets with parsing status
+##### Retrieve datasets by IDs
 
 ```python
-for dataset in rag_object.list_datasets(include_parsing_status=True):
-    print(dataset.done_count, dataset.fail_count, dataset.running_count)
+datasets = rag_object.list_datasets(ids=["id_1", "id_2"])
+for dataset in datasets:
+    print(dataset)
 ```
 
 ---
@@ -429,19 +431,30 @@ Uploads documents to the current dataset.
 
 A list of dictionaries representing the documents to upload, each containing the following keys:
 
-- `"display_name"`: (Optional) The file name to display in the dataset.
-- `"blob"`: (Optional) The binary content of the file to upload.
+- `"display_name"`: `string`, *Required*
+  The file name to display in the dataset.
+- `"blob"`: `bytes`, *Required*
+  The binary content of the file to upload.
 
 #### Returns
 
-- Success: No value is returned.
+- Success: A list of uploaded `Document` objects.
 - Failure: `Exception`
 
 #### Examples
 
 ```python
 dataset = rag_object.create_dataset(name="kb_name")
-dataset.upload_documents([{"display_name": "1.txt", "blob": "<BINARY_CONTENT_OF_THE_DOC>"}, {"display_name": "2.pdf", "blob": "<BINARY_CONTENT_OF_THE_DOC>"}])
+
+with open("1.txt", "rb") as file:
+    documents = dataset.upload_documents([
+        {
+            "display_name": "1.txt",
+            "blob": file.read(),
+        }
+    ])
+
+print(documents[0].id)
 ```
 
 ---
@@ -449,14 +462,14 @@ dataset.upload_documents([{"display_name": "1.txt", "blob": "<BINARY_CONTENT_OF_
 ### Update document
 
 ```python
-Document.update(update_message:dict)
+Document.update(update_message: dict)
 ```
 
 Updates configurations for the current document.
 
 #### Parameters
 
-##### update_message: `dict[str, str|dict[]]`, *Required*
+##### update_message: `dict[str, Any]`, *Required*
 
 A dictionary representing the attributes to update, with the following keys:
 
@@ -464,7 +477,7 @@ A dictionary representing the attributes to update, with the following keys:
 - `"meta_fields"`: `dict[str, Any]` The meta fields of the document.
 - `"chunk_method"`: `string` The parsing method to apply to the document.
   - `"naive"`: General
-  - `"manual`: Manual
+  - `"manual"`: Manual
   - `"qa"`: Q&A
   - `"table"`: Table
   - `"paper"`: Paper
@@ -479,7 +492,7 @@ A dictionary representing the attributes to update, with the following keys:
     `{"chunk_token_num":128,"delimiter":"\\n","html4excel":False,"layout_recognize":True,"raptor":{"use_raptor":False},"parent_child":{"use_parent_child":False,"children_delimiter":"\\n"}}`.
   - `chunk_method`=`"qa"`:
     `{"raptor": {"use_raptor": False}}`
-  - `chunk_method`=`"manuel"`:
+  - `chunk_method`=`"manual"`:
     `{"raptor": {"use_raptor": False}}`
   - `chunk_method`=`"table"`:
     `None`
@@ -495,14 +508,12 @@ A dictionary representing the attributes to update, with the following keys:
     `None`
   - `chunk_method`=`"one"`:
     `None`
-  - `chunk_method`=`"knowledge-graph"`:
-    `{"chunk_token_num":128,"delimiter":"\\n","entity_types":["organization","person","location","event","time"]}`
   - `chunk_method`=`"email"`:
     `None`
 
 #### Returns
 
-- Success: No value is returned.
+- Success: The updated `Document` object.
 - Failure: `Exception`
 
 #### Examples
@@ -515,7 +526,12 @@ dataset = rag_object.list_datasets(id='id')
 dataset = dataset[0]
 doc = dataset.list_documents(id="wdfxb5t547d")
 doc = doc[0]
-doc.update([{"parser_config": {"chunk_token_num": 256}}, {"chunk_method": "manual"}])
+doc.update({
+    "parser_config": {
+        "chunk_token_num": 256,
+    },
+    "chunk_method": "manual",
+})
 ```
 
 ---
@@ -535,15 +551,17 @@ The downloaded document in bytes.
 #### Examples
 
 ```python
+from pathlib import Path
 from ragflow_sdk import RAGFlow
 
-rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
-dataset = rag_object.list_datasets(id="id")
-dataset = dataset[0]
-doc = dataset.list_documents(id="wdfxb5t547d")
-doc = doc[0]
-open("~/ragflow.txt", "wb+").write(doc.download())
-print(doc)
+rag_object = RAGFlow(
+    api_key="<YOUR_API_KEY>",
+    base_url="https://<YOUR_BASE_URL>",
+)
+dataset = rag_object.list_datasets(id="id")[0]
+doc = dataset.list_documents(id="wdfxb5t547d")[0]
+
+Path("~/ragflow.txt").expanduser().write_bytes(doc.download())
 ```
 
 ---
@@ -551,27 +569,37 @@ print(doc)
 ### List documents
 
 ```python
-Dataset.list_documents(
-    id: str = None,
-    keywords: str = None,
+DataSet.list_documents(
+    id: str | None = None,
+    ids: list[str] | None = None,
+    name: str | None = None,
+    keywords: str | None = None,
     page: int = 1,
     page_size: int = 30,
-    order_by: str = "create_time",
+    orderby: str = "create_time",
     desc: bool = True,
     create_time_from: int = 0,
     create_time_to: int = 0
-) -> list[Document]
+)
 ```
 
 Lists documents in the current dataset.
 
 #### Parameters
 
-##### id: `string`
+##### id: `string | None`
 
 The ID of the document to retrieve. Defaults to `None`.
 
-##### keywords: `string`
+##### ids: `list[str] | None`
+
+The IDs of the documents to retrieve. Defaults to `None`. The `id` and `ids` parameters cannot be used together.
+
+##### name: `string | None`
+
+The exact name of the document to retrieve. Defaults to `None`.
+
+##### keywords: `string | None`
 
 The keywords used to match document titles. Defaults to `None`.
 
@@ -634,7 +662,7 @@ A `Document` object contains the following attributes:
     `{"chunk_token_num":128,"delimiter":"\\n","html4excel":False,"layout_recognize":True,"raptor":{"use_raptor":False}}`.
   - `chunk_method`=`"qa"`:
     `{"raptor": {"use_raptor": False}}`
-  - `chunk_method`=`"manuel"`:
+  - `chunk_method`=`"manual"`:
     `{"raptor": {"use_raptor": False}}`
   - `chunk_method`=`"table"`:
     `None`
@@ -656,15 +684,28 @@ A `Document` object contains the following attributes:
 #### Examples
 
 ```python
+from pathlib import Path
 from ragflow_sdk import RAGFlow
 
-rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
+rag_object = RAGFlow(
+    api_key="<YOUR_API_KEY>",
+    base_url="http://<YOUR_BASE_URL>:9380",
+)
 dataset = rag_object.create_dataset(name="kb_1")
 
-filename1 = "~/ragflow.txt"
-blob = open(filename1 , "rb").read()
-dataset.upload_documents([{"name":filename1,"blob":blob}])
-for doc in dataset.list_documents(keywords="rag", page=0, page_size=12):
+file_path = Path("~/ragflow.txt").expanduser()
+dataset.upload_documents([
+    {
+        "display_name": file_path.name,
+        "blob": file_path.read_bytes(),
+    }
+])
+
+for doc in dataset.list_documents(
+    keywords="rag",
+    page=1,
+    page_size=12,
+):
     print(doc)
 ```
 
@@ -1062,7 +1103,21 @@ chunk.update({"content":"sdfx..."})
 ### Retrieve chunks
 
 ```python
-RAGFlow.retrieve(question:str="", dataset_ids:list[str]=None, document_ids=list[str]=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,keyword:bool=False,cross_languages:list[str]=None,metadata_condition: dict=None) -> list[Chunk]
+RAGFlow.retrieve(
+  dataset_ids,
+  document_ids=None,
+  question='',
+  page=1,
+  page_size=30,
+  similarity_threshold=0.2,
+  vector_similarity_weight=0.3,
+  top_k=1024,
+  rerank_id: str | None = None,
+  keyword: bool = False,
+  cross_languages: list[str] | None = None,
+  metadata_condition: dict | None = None,
+  use_kg: bool = False,
+  toc_enhance: bool = False)
 ```
 
 Retrieves chunks from specified datasets.
@@ -1089,7 +1144,7 @@ The starting index for the documents to retrieve. Defaults to `1`.
 
 The maximum number of chunks to retrieve. Defaults to `30`.
 
-##### Similarity_threshold: `float`
+##### similarity_threshold: `float`
 
 The minimum similarity score. Defaults to `0.2`.
 
@@ -1120,6 +1175,14 @@ The languages that should be translated into, in order to achieve keywords retri
 
 filter condition for `meta_fields`.
 
+##### use_kg: `bool`
+
+Whether to enable graph-assisted retrieval for multi-hop queries. Defaults to `False`.
+
+##### toc_enhance: `bool`
+
+Whether to use extracted table-of-contents information during retrieval. Defaults to `False`.
+
 #### Returns
 
 - Success: A list of `Chunk` objects representing the document chunks.
@@ -1330,7 +1393,6 @@ RAGFlow.list_chats(
     name: str | None = None,
     keywords: str | None = None,
     owner_ids: str | list[str] | None = None,
-    parser_id: str | None = None
 ) -> list[Chat]
 ```
 
@@ -1361,6 +1423,8 @@ Indicates whether the retrieved chat assistants should be sorted in descending o
 
 Exact match on chat assistant ID. Defaults to `None`.
 
+##### name: `string | None`
+
 Filters results by the exact name of the chat assistant. Defaults to `None`.
 
 ##### keywords: `string | None`
@@ -1371,12 +1435,6 @@ Performs a case-insensitive fuzzy search against chat assistant names. Defaults
 
 Filters results by one or more owner tenant IDs. Defaults to `None`.
 
-##### parser_id: `string | None`
-
-Filters results by a specific parser type identifier. Defaults to `None`.
-
-If `id` or `name` is specified, exact filtering takes precedence over the fuzzy matching provided by `keywords`.
-
 #### Returns
 
 - Success: A list of `Chat` objects.
@@ -2029,7 +2087,8 @@ print(agent)
 RAGFlow.create_agent(
     title: str,
     dsl: dict,
-    description: str | None = None
+    description: str | None = None,
+    canvas_type: str | None = None
 ) -> None
 ```
 
@@ -2049,6 +2108,10 @@ Specifies the canvas DSL of the agent.
 
 The description of the agent. Defaults to `None`.
 
+##### canvas_type: `string | None`
+
+The canvas type of the agent. Defaults to `None`.
+
 #### Returns
 
 - Success: Nothing.
@@ -2077,7 +2140,8 @@ RAGFlow.update_agent(
     agent_id: str,
     title: str | None = None,
     description: str | None = None,
-    dsl: dict | None = None
+    dsl: dict | None = None,
+    canvas_type: str | None = None,
 ) -> None
 ```
 
@@ -2101,6 +2165,10 @@ Specifies the new canvas DSL of the agent. `None` if you do not want to update t
 
 The new description of the agent. `None` if you do not want to update this.
 
+##### canvas_type: `string | None`
+
+The canvas type of the agent. Defaults to `None`.
+
 #### Returns
 
 - Success: Nothing.
@@ -2161,7 +2229,7 @@ rag_object.delete_agent("58af890a2a8911f0a71a11b922ed82d6")
 ### Create Memory
 
 ```python
-Ragflow.create_memory(
+RAGFlow.create_memory(
     name: str,
     memory_type: list[str],
     embd_id: str,
@@ -2214,7 +2282,7 @@ The name of the chat model to use. For example: `"glm-4-flash@ZHIPU-AI"`
 ```python
 from ragflow_sdk import RAGFlow
 rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
-memory = rag_obj.create_memory("name", ["raw"], "BAAI/bge-large-zh-v1.5@SILICONFLOW", "glm-4-flash@ZHIPU-AI")
+memory = rag_object.create_memory("name", ["raw"], "BAAI/bge-large-zh-v1.5@SILICONFLOW", "glm-4-flash@ZHIPU-AI")
 ```
 
 ---
@@ -2305,9 +2373,9 @@ Configurations to update. Available configurations:
 #### Examples
 
 ```python
-from ragflow_sdk import Ragflow, Memory
+from ragflow_sdk import RAGFlow, Memory
 rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
-memory_obejct = Memory(rag_object, {"id": "your memory_id"})
+memory_object = Memory(rag_object, {"id": "your memory_id"})
 memory_object.update({"name": "New_name"})
 ```
 
@@ -2318,7 +2386,7 @@ memory_object.update({"name": "New_name"})
 ### List Memory
 
 ```python
-Ragflow.list_memory(
+RAGFlow.list_memory(
     page: int = 1,
     page_size: int = 50,
     tenant_id: str | list[str] = None,
@@ -2375,9 +2443,9 @@ Failure: `Exception`
 #### Examples
 
 ```
-from ragflow_sdk import Ragflow, Memory
+from ragflow_sdk import RAGFlow, Memory
 rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
-rag_obejct.list_memory()
+rag_object.list_memory()
 ```
 
 ---
@@ -2405,10 +2473,10 @@ Failure: `Exception`
 #### Examples
 
 ```python
-from ragflow_sdk import Ragflow, Memory
+from ragflow_sdk import RAGFlow, Memory
 rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
-memory_obejct = Memory(rag_object, {"id": "your memory_id"})
-memory_obejct.get_config()
+memory_object = Memory(rag_object, {"id": "your memory_id"})
+memory_object.get_config()
 ```
 
 ---
@@ -2418,7 +2486,7 @@ memory_obejct.get_config()
 ### Delete Memory
 
 ```python
-Ragflow.delete_memory(
+RAGFlow.delete_memory(
     memory_id: str
 ) -> None
 ```
@@ -2440,7 +2508,7 @@ Failure: `Exception`
 #### Examples
 
 ```python
-from ragflow_sdk import Ragflow, Memory
+from ragflow_sdk import RAGFlow, Memory
 rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
 rag_object.delete_memory("your memory_id")
 ```
@@ -2493,10 +2561,10 @@ Failure: `Exception`
 #### Examples
 
 ```python
-from ragflow_sdk import Ragflow, Memory
+from ragflow_sdk import RAGFlow, Memory
 rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
-memory_obejct = Memory(rag_object, {"id": "your memory_id"})
-memory_obejct.list_memory_messages()
+memory_object = Memory(rag_object, {"id": "your memory_id"})
+memory_object.list_memory_messages()
 ```
 
 ---
@@ -2506,7 +2574,7 @@ memory_obejct.list_memory_messages()
 ### Add Message
 
 ```python
-Ragflow.add_message(
+RAGFlow.add_message(
     memory_id: list[str],
     agent_id: str,
     session_id: str,
@@ -2553,7 +2621,7 @@ Failure: `Exception`
 #### Examples
 
 ```python
-from ragflow_sdk import Ragflow, Memory
+from ragflow_sdk import RAGFlow, Memory
 rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
 message_payload = {
     "memory_id": memory_ids,
@@ -2565,7 +2633,7 @@ message_payload = {
 Your agent response here
 """
 }
-client.add_message(**message_payload)
+rag_object.add_message(**message_payload)
 ```
 
 ---
@@ -2595,7 +2663,7 @@ Failure: `Exception`
 #### Examples
 
 ```python
-from ragflow_sdk import Ragflow, Memory
+from ragflow_sdk import RAGFlow, Memory
 rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
 memory_object = Memory(rag_object, {"id": "your memory_id"})
 memory_object.forget_message(message_id)
@@ -2632,7 +2700,7 @@ Failure: `Exception`
 #### Examples
 
 ```python
-from ragflow_sdk import Ragflow, Memory
+from ragflow_sdk import RAGFlow, Memory
 rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
 memory_object = Memory(rag_object, {"id": "your memory_id"})
 memory_object.update_message_status(message_id, True)
@@ -2645,7 +2713,7 @@ memory_object.update_message_status(message_id, True)
 ### Search message
 
 ```python
-Ragflow.search_message(
+RAGFlow.search_message(
     query: str,
     memory_id: list[str],
     agent_id: str=None,
@@ -2706,7 +2774,7 @@ Failure: `Exception`
 #### Examples
 
 ```python
-from ragflow_sdk import Ragflow
+from ragflow_sdk import RAGFlow
 rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
 rag_object.search_message("your question", ["your memory_id"])
 ```
@@ -2718,7 +2786,7 @@ rag_object.search_message("your question", ["your memory_id"])
 ### Get Recent Messages
 
 ```python
-Ragflow.get_recent_messages(
+RAGFlow.get_recent_messages(
     memory_id: list[str],
     agent_id: str=None,
     session_id: str=None,
@@ -2755,7 +2823,7 @@ Failure: `Exception`
 #### Examples
 
 ```python
-from ragflow_sdk import Ragflow
+from ragflow_sdk import RAGFlow
 rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
 rag_object.get_recent_messages(["your memory_id"])
 ```
@@ -2785,7 +2853,7 @@ Failure: `Exception`
 #### Examples
 
 ```python
-from ragflow_sdk import Ragflow
+from ragflow_sdk import RAGFlow,Memory
 rag_object = RAGFlow(api_key="<YOUR_API_KEY>", base_url="http://<YOUR_BASE_URL>:9380")
 memory_object = Memory(rag_object, {"id": "your memory_id"})
 memory_object.get_message_content(message_id)