fix: upgrade docling-serve to v1 apis

[dolfim-ibm]

This PR updates the endpoint usage for the v1 API of the Docling Serve component.

Summary by CodeRabbit

• New Features

  • Asynchronous document conversion with automatic status polling and timeouts for faster, non-blocking workflows.
  • Enhanced result handling that validates outputs before returning them.

• Bug Fixes

  • Improved reliability with better retries on server errors and clearer failure handling.
  • Prevents invalid results from being returned by enforcing stricter validation.

• Chores

  • Updated service configuration to the latest API version.
  • Adjusted document conversion options to align with current server capabilities.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

Migrates Docling Remote component from /v1alpha to /v1, updates payload from file_sources to sources with kind: "file", and replaces synchronous handling with an async task flow: submit, poll status with retries/timeouts, fetch result, validate json_content, construct DoclingDocument, and return Data or None.

Changes

Cohort / File(s)	Summary
Docling API v1 migration + async polling src/backend/base/langflow/components/docling/docling_remote.py	Updated base URL to /v1; payload uses sources with kind: "file"; implemented async conversion: POST /convert/source/async, poll /status/poll/{task_id} with timeout and 5xx retry cap, then GET /result/{task_id}; validate json_content, build DoclingDocument; adjusted docling_options (removed return_as_file).

Sequence Diagram(s)

sequenceDiagram
  participant C as DoclingRemoteComponent
  participant S as Docling Serve API

  rect rgb(240,245,255)
    note over C,S: Submit async conversion request (v1)
    C->>S: POST /v1/convert/source/async<br/>body: { sources: [{ kind:"file", filename, base64_string }], options }
    S-->>C: 202 Accepted + task_id
  end

  loop Poll status (2s interval, max timeout)
    C->>S: GET /v1/status/poll/{task_id}
    alt 5xx from server
      note over C: Retry with max 5xx retries
    else success/failure reported
      opt break on terminal state
      end
    end
  end

  alt task_status == "success"
    C->>S: GET /v1/result/{task_id}
    S-->>C: { json_content, ... }
    note over C: Validate json_content → DoclingDocument.model_validate(...)
    C-->>C: Return Data(document, file_path)
  else task_status == "failure" or timeout
    C-->>C: Log and return None
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

✨ Finishing Touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

• Add @coderabbitai ignore or @coderabbit ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

Status, Documentation and Community

• Visit our Status Page to check the current availability of CodeRabbit.
• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/backend/base/langflow/components/docling/docling_remote.py (1)

171-183: Fix output misalignment: processed_data order can desync from file_list

Appending Nones first and results later breaks index alignment, which likely confuses rollup_data. Preallocate by length and fill by index.

-        processed_data: list[Data | None] = []
+        processed_data: list[Data | None] = [None] * len(file_list)
...
-            for i, file in enumerate(file_list):
-                if file.path is None:
-                    processed_data.append(None)
-                    continue
-
-                futures.append((i, executor.submit(_convert_document, client, file.path, docling_options)))
+            for i, file in enumerate(file_list):
+                if file.path is None:
+                    processed_data[i] = None
+                    continue
+                futures.append((i, executor.submit(_convert_document, client, file.path, docling_options)))
...
-            for _index, future in futures:
+            for _index, future in futures:
                 try:
                     result_data = future.result()
-                    processed_data.append(result_data)
+                    processed_data[_index] = result_data
                 except (httpx.HTTPStatusError, httpx.RequestError, KeyError, ValueError) as exc:
                     self.log(f"Docling remote processing failed: {exc}")
                     raise

Also applies to: 184-192

🧹 Nitpick comments (7)

src/backend/base/langflow/components/docling/docling_remote.py (7)

106-106: Harden base URL join to avoid double slashes

Handles users passing api_url with a trailing slash.

-        base_url = f"{self.api_url}/v1"
+        base_url = f"{self.api_url.rstrip('/')}/v1"

---

136-149: Make polling more robust: handle non-2xx, backoff, and JSON errors

Current loop retries only on 5xx and assumes JSON body; 4xx/invalid JSON will KeyError later. Add raise_for_status for non-retriables and simple backoff.

-                response = client.get(f"{base_url}/status/poll/{task['task_id']}")
-
-                # Check if the status call gets into 5xx errors and retry
-                if retry_status_start <= response.status_code < retry_status_end:
-                    http_failures += 1
-                    if http_failures > self.MAX_500_RETRIES:
-                        self.log(f"The status requests got a http response {response.status_code} too many times.")
-                        return None
-                    continue
-
-                # Update task status
-                task = response.json()
+                response = client.get(f"{base_url}/status/poll/{task['task_id']}")
+                status = response.status_code
+                if retry_status_start <= status < retry_status_end:
+                    http_failures += 1
+                    if http_failures > self.MAX_500_RETRIES:
+                        self.log(f"The status requests got a http response {status} too many times.")
+                        return None
+                    # simple backoff
+                    time.sleep(min(30, 2 ** http_failures))
+                    continue
+                if status == 429:
+                    # rate-limited -> brief backoff
+                    time.sleep(min(30, 2 ** (http_failures or 1)))
+                    continue
+                response.raise_for_status()
+                try:
+                    task = response.json()
+                except ValueError as e:
+                    self.log(f"Invalid JSON from status endpoint: {e}")
+                    return None

---

115-118: Validate initial async task payload defensively

Ensure task_id and task_status exist; otherwise fail fast with a clear log instead of KeyError later.

             response.raise_for_status()
-            task = response.json()
+            task = response.json()
+            if "task_id" not in task or "task_status" not in task:
+                self.log(f"Unexpected response from async submit: {task}")
+                return None

---

150-156: Guard for missing document key in result

Prevents KeyError if the server returns a non-standard payload.

-            result = result_resp.json()
-
-            if "json_content" not in result["document"] or result["document"]["json_content"] is None:
+            result = result_resp.json()
+            if "document" not in result:
+                self.log("No 'document' key in the result payload.")
+                return None
+            if "json_content" not in result["document"] or result["document"]["json_content"] is None:
                 self.log("No JSON DoclingDocument found in the result.")
                 return None

---

173-175: Set HTTP client timeouts

Avoids hangs on network stalls during submit/status/result calls.

-            httpx.Client(headers=self.api_headers) as client,
+            httpx.Client(headers=self.api_headers, timeout=httpx.Timeout(30.0)) as client,

---

105-193: Sync implementation vs async component guidelines

This component uses ThreadPoolExecutor and time.sleep. If the framework expects async components here, consider switching to httpx.AsyncClient and asyncio.sleep, and using asyncio.create_task per the guidelines.

Do you want me to provide an async rewrite of process_files using AsyncClient and preserving concurrency limits?

---

28-58: Extension list parity

Optional: add common aliases like jpg and tif if Docling v1 accepts them; reduces user friction.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 2d5c559 and 1dd26c2.

📒 Files selected for processing (1)

• src/backend/base/langflow/components/docling/docling_remote.py (1 hunks)

🧰 Additional context used

📓 Path-based instructions (3)

src/backend/base/langflow/components/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/backend_development.mdc)

src/backend/base/langflow/components/**/*.py: Add new backend components to the appropriate subdirectory under src/backend/base/langflow/components/
Implement async component methods using async def and await for asynchronous operations
Use asyncio.create_task for background work in async components and ensure proper cleanup on cancellation
Use asyncio.Queue for non-blocking queue operations in async components and handle timeouts appropriately

Files:

• src/backend/base/langflow/components/docling/docling_remote.py

{src/backend/**/*.py,tests/**/*.py,Makefile}

📄 CodeRabbit inference engine (.cursor/rules/backend_development.mdc)

{src/backend/**/*.py,tests/**/*.py,Makefile}: Run make format_backend to format Python code before linting or committing changes
Run make lint to perform linting checks on backend Python code

Files:

• src/backend/base/langflow/components/docling/docling_remote.py

src/backend/**/components/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/icons.mdc)

In your Python component class, set the icon attribute to a string matching the frontend icon mapping exactly (case-sensitive).

Files:

• src/backend/base/langflow/components/docling/docling_remote.py

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (55)

• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 10/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 38/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 37/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 35/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 40/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 36/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 30/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 39/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 32/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 34/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 33/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 31/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 28/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 24/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 27/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 5/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 29/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 26/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 25/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 22/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 21/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 23/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 19/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 17/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 18/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 20/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 16/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 15/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 13/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 14/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 11/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 6/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 9/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 7/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 12/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 8/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 2/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 3/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 4/40
• GitHub Check: Run Frontend Tests / Playwright Tests - Shard 1/40
• GitHub Check: Lint Backend / Run Mypy (3.11)
• GitHub Check: Run Backend Tests / Unit Tests - Python 3.10 - Group 4
• GitHub Check: Lint Backend / Run Mypy (3.12)
• GitHub Check: Lint Backend / Run Mypy (3.10)
• GitHub Check: Lint Backend / Run Mypy (3.13)
• GitHub Check: Run Backend Tests / Unit Tests - Python 3.10 - Group 2
• GitHub Check: Run Backend Tests / Unit Tests - Python 3.10 - Group 3
• GitHub Check: Run Backend Tests / Unit Tests - Python 3.10 - Group 5
• GitHub Check: Run Backend Tests / Unit Tests - Python 3.10 - Group 1
• GitHub Check: Run Backend Tests / Integration Tests - Python 3.10
• GitHub Check: Test Starter Templates
• GitHub Check: Update Starter Projects
• GitHub Check: Run Ruff Check and Format
• GitHub Check: Optimize new Python code in this PR
• GitHub Check: Ruff Style Check (3.13)

🔇 Additional comments (2)

src/backend/base/langflow/components/docling/docling_remote.py (2)

173-175: Confirm httpx.Client thread-safety for shared use

You share one Client across threads. This is typically OK in httpx, but please confirm per your supported version; otherwise create the Client inside each thread task.

---

112-112: Payload shape update to v1 looks correct

sources with kind: "file", base64_string, and filename aligns with the stated v1 change.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[erichare]

This looks great but i think we need to remove some of the workflow changes

[dolfim-ibm]

@erichare should I file a new fresh PR? The only change which should be here is the one in src/backend/base/langflow/components/docling/docling_remote.py.

[dolfim-ibm]

See #9702.

[erichare]

Thank you @dolfim-ibm ! That is kind of what i suspected! I will close this one and approve the other PR. appreciate it :)