RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
fix(sdk-documents): restore document API contracts (#21741)
Sbaaoui Idriss96ab55dfc945
diff --git a/internal/service/document/document_crud.go b/internal/service/document/document_crud.goindex 3550fbbeaf..3db512b3a2 100644--- a/internal/service/document/document_crud.go+++ b/internal/service/document/document_crud.go@@ -81,9 +81,6 @@ func (s *DocumentService) DownloadDocument(ctx context.Context, datasetID, docIDif err != nil {return nil, err}- if len(data) == 0 {- return nil, fmt.Errorf("this document is empty")- }fileName := ""if doc.Name != nil {diff --git a/internal/service/document/document_dataset_update.go b/internal/service/document/document_dataset_update.goindex 88790f3f5e..653f71f662 100644--- a/internal/service/document/document_dataset_update.go+++ b/internal/service/document/document_dataset_update.go@@ -13,6 +13,7 @@ import ("ragflow/internal/common""ragflow/internal/dao"+ "ragflow/internal/engine""ragflow/internal/entity"componentpkg "ragflow/internal/ingestion/component"pipelinepkg "ragflow/internal/ingestion/pipeline"@@ -584,6 +585,15 @@ func (s *DocumentService) updateDocumentNameOnly(ctx context.Context, doc *entittitleTks, _ := tok.Tokenize(newName)titleSmTks, _ := tok.FineGrainedTokenize(titleTks)indexName := fmt.Sprintf("ragflow_%s", kb.TenantID)+ if doc.ChunkNum == 0 && engine.Type(s.docEngine) == engine.EngineElasticsearch {+ exists, err := s.docEngine.ChunkStoreExists(ctx, indexName, doc.KbID)+ if err != nil {+ return err+ }+ if !exists {+ return nil+ }+ }return s.docEngine.UpdateChunks(ctx,map[string]interface{}{"doc_id": doc.ID},diff --git a/internal/service/document/document_test.go b/internal/service/document/document_test.goindex 1db5fd3ca1..040af5f923 100644--- a/internal/service/document/document_test.go+++ b/internal/service/document/document_test.go@@ -5407,3 +5407,74 @@ func TestFileDeleteRemovesLinkedDocument(t *testing.T) {t.Fatal("document should have been deleted but still exists")}}++func TestDownloadEmptyDocumentAndMissingBlob(t *testing.T) {+ db := setupServiceTestDB(t)+ pushServiceDB(t, db)+ store := useFakeStorage(t)+ insertTestPreviewDoc(t, db, store, "empty-doc", "kb-empty", "")+ svc := testDocumentService(t)+ got, err := svc.DownloadDocument(t.Context(), "kb-empty", "empty-doc")+ if err != nil || got == nil || len(got.Data) != 0 {+ t.Fatalf("empty download = %#v, %v", got, err)+ }+ clear(store.objects)+ if _, err := svc.DownloadDocument(t.Context(), "kb-empty", "empty-doc"); err == nil {+ t.Fatal("missing blob must fail")+ }+}++type renameStoreEngine struct {+ fakeChatDocEngine+ exists bool+ storeErr error+ err error+ updates int+}++func (e *renameStoreEngine) GetType() string { return "elasticsearch" }+func (e *renameStoreEngine) ChunkStoreExists(context.Context, string, string) (bool, error) {+ return e.exists, e.storeErr+}+func (e *renameStoreEngine) UpdateChunks(context.Context, map[string]interface{}, map[string]interface{}, string, string) error {+ e.updates+++ return e.err+}+func TestRenameDocumentChunkStore(t *testing.T) {+ for _, tc := range []struct {+ chunks int64+ exists bool+ storeErr error+ name string+ err error+ updates int+ }{+ {name: "unparsed"}, {name: "zero count indexed", exists: true, updates: 1}, {name: "store error", storeErr: errors.New("store unavailable")}, {name: "parsed", chunks: 1, updates: 1}, {name: "engine error", chunks: 1, err: errors.New("unavailable"), updates: 1},+ } {+ t.Run(tc.name, func(t *testing.T) {+ db := setupServiceTestDB(t)+ pushServiceDB(t, db)+ insertTestKB(t, "kb-1", "tenant-1", 1, 0, 0)+ insertNamedTestDoc(t, "doc-1", "kb-1", "old.txt", 0, tc.chunks)+ svc := testDocumentService(t)+ engine := &renameStoreEngine{err: tc.err, exists: tc.exists, storeErr: tc.storeErr}+ svc.docEngine = engine+ doc, err := svc.documentDAO.GetByID(t.Context(), db, "doc-1")+ if err != nil {+ t.Fatal(err)+ }+ kb, err := dao.NewKnowledgebaseDAO().GetByID(t.Context(), db, "kb-1")+ if err != nil {+ t.Fatal(err)+ }+ err = svc.updateDocumentNameOnly(t.Context(), doc, kb, "new.txt")+ wantErr := tc.err+ if tc.storeErr != nil {+ wantErr = tc.storeErr+ }+ if !errors.Is(err, wantErr) || engine.updates != tc.updates {+ t.Fatalf("rename error=%v updates=%d", err, engine.updates)+ }+ })+ }+}diff --git a/sdk/python/ragflow_sdk/modules/dataset.py b/sdk/python/ragflow_sdk/modules/dataset.pyindex e54427cf37..8b8f750d5d 100644--- a/sdk/python/ragflow_sdk/modules/dataset.py+++ b/sdk/python/ragflow_sdk/modules/dataset.py@@ -1,5 +1,5 @@#-# Copyright 2025 The InfiniFlow Authors. All Rights Reserved.+# Copyright 2026 The InfiniFlow Authors. All Rights Reserved.## Licensed under the Apache License, Version 2.0 (the "License");# you may not use this file except in compliance with the License.@@ -127,6 +127,7 @@ class DataSet(Base):import timeterminal_states = {"DONE", "FAIL", "CANCEL"}+ ingestion_terminal_states = {"COMPLETED": "DONE", "FAILED": "FAIL", "STOPPED": "CANCEL"}interval_sec = 1pending = set(document_ids)finished = []@@ -136,7 +137,11 @@ class DataSet(Base):if not docs:raise RuntimeError(f"Document {doc_id} not found while waiting for parsing to finish")doc = docs[0]- if isinstance(doc.run, str) and doc.run.upper() in terminal_states:+ status = ingestion_terminal_states.get(doc.ingestion_status)+ if status:+ finished.append((doc_id, status, doc.chunk_count, doc.token_count))+ pending.discard(doc_id)+ elif isinstance(doc.run, str) and doc.run.upper() in terminal_states:finished.append((doc_id, doc.run, doc.chunk_count, doc.token_count))pending.discard(doc_id)elif float(doc.progress or 0.0) >= 1.0:diff --git a/sdk/python/ragflow_sdk/modules/document.py b/sdk/python/ragflow_sdk/modules/document.pyindex c5141f5b49..d52cba6386 100644--- a/sdk/python/ragflow_sdk/modules/document.py+++ b/sdk/python/ragflow_sdk/modules/document.py@@ -1,5 +1,5 @@#-# Copyright 2025 The InfiniFlow Authors. All Rights Reserved.+# Copyright 2026 The InfiniFlow Authors. All Rights Reserved.## Licensed under the Apache License, Version 2.0 (the "License");# you may not use this file except in compliance with the License.@@ -44,6 +44,7 @@ class Document(Base):self.progress_msg = ""self.process_begin_at = Noneself.process_duration = 0.0+ self.ingestion_status = ""self.run = "0"self.status = "1"self.meta_fields = {}diff --git a/test/testcases/test_sdk_api/test_file_management_within_dataset/test_download_document.py b/test/testcases/test_sdk_api/test_file_management_within_dataset/test_download_document.pyindex 13b5ecd39d..088390c98b 100644--- a/test/testcases/test_sdk_api/test_file_management_within_dataset/test_download_document.py+++ b/test/testcases/test_sdk_api/test_file_management_within_dataset/test_download_document.py@@ -141,13 +141,6 @@ def test_file_type_validation(add_dataset_func, generate_test_files, request):@pytest.mark.integrationclass TestDocumentDownload:@pytest.mark.p3- @pytest.mark.skip(- reason=(- "Go DocumentService.DownloadDocument rejects zero-byte blobs in "- "internal/service/document/document_crud.go; upload is supported "- "by test/api/document_api_test.go::TestRESTDocumentUploadPersistenceAndNames."- )- )def test_download_empty_uploaded_file(self, add_dataset_func):dataset = add_dataset_funcdocuments = dataset.upload_documents([{"display_name": "empty.txt", "blob": b""}])diff --git a/test/testcases/test_sdk_api/test_file_management_within_dataset/test_parse_documents.py b/test/testcases/test_sdk_api/test_file_management_within_dataset/test_parse_documents.pyindex 01eb0ed9a5..3013c482e5 100644--- a/test/testcases/test_sdk_api/test_file_management_within_dataset/test_parse_documents.py+++ b/test/testcases/test_sdk_api/test_file_management_within_dataset/test_parse_documents.py@@ -322,30 +322,8 @@ def test_terminal_status_from_previous_parse_run_is_not_reused(monkeypatch):"ingestion_status, progress, expected_status",[("COMPLETED", 1.0, "DONE"),- pytest.param(- "FAILED",- -1.0,- "FAIL",- marks=pytest.mark.skip(- reason=(- "Go document-list handler internal/handler/document.go:mapDocumentListItem "- "returns ingestion_status, which sdk/python/ragflow_sdk/modules/document.py:Document.__init__ "- "drops; DataSet._get_documents_status then polls forever for failed tasks."- )- ),- ),- pytest.param(- "STOPPED",- 0.0,- "CANCEL",- marks=pytest.mark.skip(- reason=(- "Go document-list handler internal/handler/document.go:mapDocumentListItem "- "returns ingestion_status, which sdk/python/ragflow_sdk/modules/document.py:Document.__init__ "- "drops; DataSet._get_documents_status then polls forever for cancelled tasks."- )- ),- ),+ ("FAILED", -1.0, "FAIL"),+ ("STOPPED", 0.0, "CANCEL"),],)def test_parse_documents_returns_documented_terminal_status(monkeypatch, ingestion_status, progress, expected_status):diff --git a/test/testcases/test_sdk_api/test_file_management_within_dataset/test_update_document.py b/test/testcases/test_sdk_api/test_file_management_within_dataset/test_update_document.pyindex fe9be941c5..8134ff2287 100644--- a/test/testcases/test_sdk_api/test_file_management_within_dataset/test_update_document.py+++ b/test/testcases/test_sdk_api/test_file_management_within_dataset/test_update_document.py@@ -14,34 +14,27 @@# limitations under the License.#-import osfrom unittest.mock import Mockimport pytestfrom ragflow_sdk import Document-_unindexed_rename = pytest.mark.skipif(- os.getenv("RAGFLOW_SDK_DOC_ENGINE", os.getenv("DOC_ENGINE")) == "elasticsearch",- reason="Go updateDocumentNameOnly updates chunks for an unparsed document without an Elasticsearch index (document_dataset_update.go:587; elasticsearch/chunk.go:353)",-)--@pytest.mark.integrationclass TestDocumentsUpdated:@pytest.mark.p1@pytest.mark.parametrize("name, expected_message",[- pytest.param("new_name.txt", "", marks=_unindexed_rename),- pytest.param(f"{'a' * 251}.txt", "", marks=_unindexed_rename),+ ("new_name.txt", ""),+ (f"{'a' * 251}.txt", ""),(0, "Field: <name> - Message: <Input should be a valid string> - Value: <0>"),(None, "Field: <name> - Message: <Input should be a valid string> - Value: <None>"),("", "the extension of file can't be changed"),("ragflow_test_upload_0", "the extension of file can't be changed"),("ragflow_test_upload_1.txt", "duplicated document name in the same dataset"),("RAGFLOW_TEST_UPLOAD_1.TXT", "duplicated document name in the same dataset"),- pytest.param("RAGFLOW_TEST_UPLOAD_0.TXT", "", marks=_unindexed_rename),+ ("RAGFLOW_TEST_UPLOAD_0.TXT", ""),],)def test_name(self, add_documents, name, expected_message):