Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

fix: Address custom component flow mismatch and add test validation (#2394)

Mike Fortman5656192eacef
diff --git a/.github/workflows/test-backend.yml b/.github/workflows/test-backend.yml
new file mode 100644
index 000000000..9544e8806
--- /dev/null
+++ b/.github/workflows/test-backend.yml
@@ -0,0 +1,62 @@
+name: Test Backend
+
+# Runs the backend unit suite on every PR that could affect it.
+#
+# Until this existed, no workflow ran pytest at all. That is how #2389 shipped a
+# flow whose embedded component code had drifted from its source file:
+# test_flow_embeds_the_same_component_source would have caught it, but never ran.
+#
+# Tests that already fail on main are tracked in tests/unit/known_failures.txt
+# and marked strict xfail, so this job gates on NEW failures while that list is
+# worked down. See the header of that file for the rules.
+
+on:
+ pull_request:
+ paths:
+ - 'src/**'
+ - 'tests/**'
+ - 'custom_components/**'
+ - 'flows/**'
+ - 'config/**'
+ - 'pyproject.toml'
+ - 'uv.lock'
+ - '.github/workflows/test-backend.yml'
+ push:
+ branches:
+ - main
+
+# Cancel in-flight runs on the same ref when a new push lands.
+concurrency:
+ group: test-backend-${{ github.ref }}
+ cancel-in-progress: true
+
+permissions:
+ contents: read
+
+jobs:
+ unit:
+ name: Unit tests
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v7
+
+ - name: Install uv
+ uses: astral-sh/[email protected]
+ with:
+ enable-cache: true
+
+ - name: Set up Python
+ run: uv python install 3.13
+
+ - name: Install dev dependencies
+ run: uv sync --locked --group dev
+
+ - name: Run unit tests
+ env:
+ # Every entry in known_failures.txt must be collected, so a renamed or
+ # mistyped line fails loudly instead of silently protecting nothing.
+ OPENRAG_ENFORCE_KNOWN_FAILURES: '1'
+ run: uv run --locked pytest tests/unit -q --color=yes
diff --git a/custom_components/openrag/docling_remote.py b/custom_components/openrag/docling_remote.py
index 8d16f5c62..522fb10ae 100644
--- a/custom_components/openrag/docling_remote.py
+++ b/custom_components/openrag/docling_remote.py
@@ -9,13 +9,12 @@ from typing import Any
import httpx
from docling_core.types.doc import DoclingDocument
-from pydantic import ValidationError
-
from lfx.base.data import BaseFileComponent
from lfx.inputs import IntInput, NestedDictInput, StrInput, TableInput
from lfx.inputs.inputs import FloatInput
from lfx.schema import Data, dotdict
from lfx.utils.util import transform_localhost_url
+from pydantic import ValidationError
class DoclingRemoteComponent(BaseFileComponent):
@@ -271,7 +270,9 @@ class DoclingRemoteComponent(BaseFileComponent):
elif isinstance(err, str):
err_msg_list.append(err)
- err_details = "; ".join(err_msg_list) if err_msg_list else "Unknown Docling processing error"
+ err_details = (
+ "; ".join(err_msg_list) if err_msg_list else "Unknown Docling processing error"
+ )
msg = f"Docling processing failed: {err_details}"
raise ValueError(msg)
diff --git a/flows/ingestion_flow.json b/flows/ingestion_flow.json
index 3d8598d36..64e97d696 100644
--- a/flows/ingestion_flow.json
+++ b/flows/ingestion_flow.json
@@ -363,7 +363,7 @@
"show": true,
"title_case": false,
"type": "code",
- "value": "from __future__ import annotations\n\nimport base64\nimport json\nimport time\nfrom concurrent.futures import Future, ThreadPoolExecutor\nfrom pathlib import Path # noqa: TC003\nfrom typing import Any\n\nimport httpx\nfrom docling_core.types.doc import DoclingDocument\nfrom pydantic import ValidationError\n\nfrom lfx.base.data import BaseFileComponent\nfrom lfx.inputs import IntInput, NestedDictInput, StrInput, TableInput\nfrom lfx.inputs.inputs import FloatInput\nfrom lfx.schema import Data, dotdict\nfrom lfx.utils.util import transform_localhost_url\n\n\nclass DoclingRemoteComponent(BaseFileComponent):\n display_name = \"Docling Serve\"\n description = (\n \"Uses Docling to process input documents connecting to your instance of Docling Serve.\"\n )\n documentation = \"https://docling-project.github.io/docling/\"\n trace_type = \"tool\"\n icon = \"Docling\"\n name = \"DoclingRemote\"\n\n MAX_500_RETRIES = 5\n\n # https://docling-project.github.io/docling/usage/supported_formats/\n VALID_EXTENSIONS = [\n \"adoc\",\n \"asciidoc\",\n \"asc\",\n \"bmp\",\n \"csv\",\n \"dotx\",\n \"dotm\",\n \"docm\",\n \"docx\",\n \"htm\",\n \"html\",\n \"jpeg\",\n \"jpg\",\n \"json\",\n \"md\",\n \"pdf\",\n \"png\",\n \"potx\",\n \"ppsx\",\n \"pptm\",\n \"potm\",\n \"ppsm\",\n \"pptx\",\n \"tiff\",\n \"txt\",\n \"xls\",\n \"xlsx\",\n \"xhtml\",\n \"xml\",\n \"webp\",\n ]\n\n inputs = [\n *BaseFileComponent.get_base_inputs(),\n StrInput(\n name=\"api_url\",\n display_name=\"Server address\",\n info=\"URL of the Docling Serve instance.\",\n required=True,\n ),\n StrInput(\n name=\"task_id\",\n display_name=\"Task ID\",\n info=(\n \"Optional task ID from a previous Docling Serve upload. \"\n \"If provided, file input is ignored and the component polls for this task's results.\"\n ),\n required=False,\n ),\n IntInput(\n name=\"max_concurrency\",\n display_name=\"Concurrency\",\n info=\"Maximum number of concurrent requests for the server.\",\n advanced=True,\n value=2,\n input_types=[\"Message\"],\n ),\n FloatInput(\n name=\"max_poll_timeout\",\n display_name=\"Maximum poll time\",\n info=\"Maximum waiting time for the document conversion to complete.\",\n advanced=True,\n value=3600,\n input_types=[\"Message\"],\n ),\n TableInput(\n name=\"api_headers\",\n display_name=\"HTTP headers\",\n advanced=True,\n required=False,\n info=(\"Optional headers required for connecting to Docling Serve.\"),\n table_schema=[\n {\n \"name\": \"key\",\n \"display_name\": \"Key\",\n \"type\": \"string\",\n \"description\": \"Key name\",\n },\n {\n \"name\": \"value\",\n \"display_name\": \"Value\",\n \"load_from_db\": True,\n \"type\": \"string\",\n \"description\": \"Value of the header\",\n },\n ],\n value=[],\n real_time_refresh=True,\n input_types=[\"Data\", \"JSON\"],\n ),\n NestedDictInput(\n name=\"docling_serve_opts\",\n display_name=\"Docling options\",\n advanced=True,\n required=False,\n info=(\n \"Optional dictionary of additional options. \"\n \"See https://github.com/docling-project/docling-serve/blob/main/docs/usage.md for more information.\"\n ),\n input_types=[\"Message\"],\n ),\n StrInput(\n name=\"verify_ssl\",\n display_name=\"Verify SSL\",\n info=\"Whether to verify SSL certificates for Docling Serve.\",\n value=\"DOCLING_SERVE_VERIFY_SSL\",\n load_from_db=True,\n required=False,\n advanced=True,\n ),\n ]\n\n outputs = [\n *BaseFileComponent.get_base_outputs(),\n ]\n\n def _process_headers(self) -> dict[str, str]:\n \"\"\"Process the headers input into a valid dictionary.\"\"\"\n if not self.api_headers:\n return {}\n\n component_headers_dict = {}\n # TableInput normalizes to list\n items = self.api_headers if isinstance(self.api_headers, list) else [self.api_headers]\n\n for item in items:\n if not item:\n continue\n\n # Case 1: Data object\n if hasattr(item, \"data\") and isinstance(item.data, dict):\n data = item.data\n if \"key\" in data and \"value\" in data:\n component_headers_dict[str(data[\"key\"])] = str(data[\"value\"])\n else:\n # Fallback: merge all keys from Data object\n for k, v in data.items():\n if k not in (\"text_key\", \"default_value\"):\n component_headers_dict[str(k)] = str(v)\n\n # Case 2: Dictionary (Table row)\n elif isinstance(item, dict):\n if \"key\" in item and \"value\" in item:\n component_headers_dict[str(item[\"key\"])] = str(item[\"value\"])\n else:\n # Fallback: merge all keys\n for k, v in item.items():\n component_headers_dict[str(k)] = str(v)\n\n # Case 3: Message object\n elif hasattr(item, \"text\") and isinstance(item.text, str):\n try:\n parsed = json.loads(item.text)\n if isinstance(parsed, dict):\n for k, v in parsed.items():\n component_headers_dict[str(k)] = str(v)\n except json.JSONDecodeError:\n pass\n\n return component_headers_dict\n\n def update_build_config(\n self, build_config: dotdict, field_value: Any, field_name: str | None = None\n ) -> dotdict:\n if field_name == \"api_headers\":\n if isinstance(field_value, dict):\n # If it's a dict, convert to list of {key, value} pairs for TableInput\n # This handles migration from NestedDictInput to TableInput\n new_value = [{\"key\": k, \"value\": v} for k, v in field_value.items()]\n build_config[\"api_headers\"][\"value\"] = new_value\n return build_config\n if field_value is None:\n build_config[\"api_headers\"][\"value\"] = []\n return build_config\n\n # Default behavior\n return super().update_build_config(build_config, field_value, field_name)\n\n def _poll_and_fetch_result(\n self, client: httpx.Client, base_url: str, task_id: str, file_path: str | None = None\n ) -> Data | None:\n \"\"\"Poll for task completion and fetch the result.\n\n Args:\n client: The HTTP client to use for requests.\n base_url: The base URL of the Docling Serve API.\n task_id: The task ID to poll for.\n file_path: Optional file path to include in the result data.\n\n Returns:\n Data object with the DoclingDocument, or None if processing failed.\n \"\"\"\n http_failures = 0\n retry_status_start = 500\n retry_status_end = 600\n start_wait_time = time.monotonic()\n\n response = client.get(f\"{base_url}/status/poll/{task_id}\")\n response.raise_for_status()\n task = response.json()\n\n while task[\"task_status\"] not in (\"success\", \"failure\"):\n processing_time = time.monotonic() - start_wait_time\n if processing_time >= self.max_poll_timeout:\n msg = (\n f\"Processing time {processing_time=} exceeds the maximum poll timeout {self.max_poll_timeout=}.\"\n \"Please increase the max_poll_timeout parameter or review why the processing \"\n \"takes long on the server.\"\n )\n self.log(msg)\n raise RuntimeError(msg)\n\n time.sleep(2)\n response = client.get(f\"{base_url}/status/poll/{task_id}\")\n\n if retry_status_start <= response.status_code < retry_status_end:\n http_failures += 1\n if http_failures > self.MAX_500_RETRIES:\n self.log(\n f\"The status requests got a http response {response.status_code} too many times.\"\n )\n return None\n continue\n\n task = response.json()\n\n result_resp = client.get(f\"{base_url}/result/{task_id}\")\n result_resp.raise_for_status()\n result = result_resp.json()\n\n if result.get(\"status\") == \"failure\" or result.get(\"errors\"):\n errors = result.get(\"errors\", [])\n err_msg_list = []\n for err in errors:\n if isinstance(err, dict) and \"error_message\" in err:\n err_msg_list.append(err[\"error_message\"])\n elif isinstance(err, str):\n err_msg_list.append(err)\n\n err_details = \"; \".join(err_msg_list) if err_msg_list else \"Unknown Docling processing error\"\n\n msg = f\"Docling processing failed: {err_details}\"\n raise ValueError(msg)\n\n if \"json_content\" not in result[\"document\"] or result[\"document\"][\"json_content\"] is None:\n self.log(\"No JSON DoclingDocument found in the result.\")\n return None\n\n try:\n doc = DoclingDocument.model_validate(result[\"document\"][\"json_content\"])\n data_dict: dict[str, Any] = {\"doc\": doc}\n if file_path:\n data_dict[\"file_path\"] = file_path\n return Data(data=data_dict)\n except ValidationError as e:\n self.log(f\"Error validating the document. {e}\")\n return None\n\n def _get_verify_ssl(self) -> bool:\n \"\"\"Determine whether to verify SSL certificates for Docling Serve.\n\n Returns:\n bool: True if SSL verification should be enforced, False otherwise.\n \"\"\"\n verify = getattr(self, \"verify_ssl\", None)\n if hasattr(verify, \"get_secret_value\"):\n verify = verify.get_secret_value()\n if hasattr(verify, \"text\"):\n verify = verify.text\n if isinstance(verify, bool):\n return verify\n val_str = str(verify or \"\").strip().lower()\n if val_str in (\"false\", \"0\", \"no\"):\n return False\n return True\n\n def _process_task_id(self) -> list[Data]:\n \"\"\"Process an existing task by polling for status and retrieving results.\n\n Returns:\n List containing the result Data object, or empty list if processing failed.\n \"\"\"\n transformed_url = transform_localhost_url(self.api_url)\n base_url = f\"{transformed_url}/v1\"\n\n with httpx.Client(headers=self._process_headers(), verify=self._get_verify_ssl()) as client:\n result = self._poll_and_fetch_result(client, base_url, self.task_id)\n return [result] if result else []\n\n def load_files_base(self) -> list[Data]:\n \"\"\"Load and process files, or poll an existing task if task_id is provided.\n\n Returns:\n list[Data]: Parsed data from the processed files or task.\n \"\"\"\n if self.task_id:\n return self._process_task_id()\n return super().load_files_base()\n\n def process_files(\n self, file_list: list[BaseFileComponent.BaseFile]\n ) -> list[BaseFileComponent.BaseFile]:\n transformed_url = transform_localhost_url(self.api_url)\n base_url = f\"{transformed_url}/v1\"\n\n def _convert_document(\n client: httpx.Client, file_path: Path, options: dict[str, Any]\n ) -> Data | None:\n encoded_doc = base64.b64encode(file_path.read_bytes()).decode()\n payload = {\n \"options\": options,\n \"sources\": [\n {\"kind\": \"file\", \"base64_string\": encoded_doc, \"filename\": file_path.name}\n ],\n }\n\n response = client.post(f\"{base_url}/convert/source/async\", json=payload)\n response.raise_for_status()\n task = response.json()\n\n return self._poll_and_fetch_result(client, base_url, task[\"task_id\"], str(file_path))\n\n docling_options = {\n \"to_formats\": [\"json\"],\n \"image_export_mode\": \"placeholder\",\n **(self.docling_serve_opts or {}),\n }\n\n processed_data: list[Data | None] = [None] * len(file_list)\n with (\n httpx.Client(headers=self._process_headers(), verify=self._get_verify_ssl()) as client,\n ThreadPoolExecutor(max_workers=self.max_concurrency) as executor,\n ):\n futures: list[tuple[int, Future]] = []\n for i, file in enumerate(file_list):\n if file.path is not None:\n futures.append(\n (i, executor.submit(_convert_document, client, file.path, docling_options))\n )\n\n for idx, future in futures:\n try:\n processed_data[idx] = future.result()\n except (httpx.HTTPStatusError, httpx.RequestError, KeyError, ValueError) as exc:\n self.log(f\"Docling remote processing failed: {exc}\")\n raise\n\n return self.rollup_data(file_list, processed_data)\n"
+ "value": "from __future__ import annotations\n\nimport base64\nimport json\nimport time\nfrom concurrent.futures import Future, ThreadPoolExecutor\nfrom pathlib import Path # noqa: TC003\nfrom typing import Any\n\nimport httpx\nfrom docling_core.types.doc import DoclingDocument\nfrom lfx.base.data import BaseFileComponent\nfrom lfx.inputs import IntInput, NestedDictInput, StrInput, TableInput\nfrom lfx.inputs.inputs import FloatInput\nfrom lfx.schema import Data, dotdict\nfrom lfx.utils.util import transform_localhost_url\nfrom pydantic import ValidationError\n\n\nclass DoclingRemoteComponent(BaseFileComponent):\n display_name = \"Docling Serve\"\n description = (\n \"Uses Docling to process input documents connecting to your instance of Docling Serve.\"\n )\n documentation = \"https://docling-project.github.io/docling/\"\n trace_type = \"tool\"\n icon = \"Docling\"\n name = \"DoclingRemote\"\n\n MAX_500_RETRIES = 5\n\n # https://docling-project.github.io/docling/usage/supported_formats/\n VALID_EXTENSIONS = [\n \"adoc\",\n \"asciidoc\",\n \"asc\",\n \"bmp\",\n \"csv\",\n \"dotx\",\n \"dotm\",\n \"docm\",\n \"docx\",\n \"htm\",\n \"html\",\n \"jpeg\",\n \"jpg\",\n \"json\",\n \"md\",\n \"pdf\",\n \"png\",\n \"potx\",\n \"ppsx\",\n \"pptm\",\n \"potm\",\n \"ppsm\",\n \"pptx\",\n \"tiff\",\n \"txt\",\n \"xls\",\n \"xlsx\",\n \"xhtml\",\n \"xml\",\n \"webp\",\n ]\n\n inputs = [\n *BaseFileComponent.get_base_inputs(),\n StrInput(\n name=\"api_url\",\n display_name=\"Server address\",\n info=\"URL of the Docling Serve instance.\",\n required=True,\n ),\n StrInput(\n name=\"task_id\",\n display_name=\"Task ID\",\n info=(\n \"Optional task ID from a previous Docling Serve upload. \"\n \"If provided, file input is ignored and the component polls for this task's results.\"\n ),\n required=False,\n ),\n IntInput(\n name=\"max_concurrency\",\n display_name=\"Concurrency\",\n info=\"Maximum number of concurrent requests for the server.\",\n advanced=True,\n value=2,\n input_types=[\"Message\"],\n ),\n FloatInput(\n name=\"max_poll_timeout\",\n display_name=\"Maximum poll time\",\n info=\"Maximum waiting time for the document conversion to complete.\",\n advanced=True,\n value=3600,\n input_types=[\"Message\"],\n ),\n TableInput(\n name=\"api_headers\",\n display_name=\"HTTP headers\",\n advanced=True,\n required=False,\n info=(\"Optional headers required for connecting to Docling Serve.\"),\n table_schema=[\n {\n \"name\": \"key\",\n \"display_name\": \"Key\",\n \"type\": \"string\",\n \"description\": \"Key name\",\n },\n {\n \"name\": \"value\",\n \"display_name\": \"Value\",\n \"load_from_db\": True,\n \"type\": \"string\",\n \"description\": \"Value of the header\",\n },\n ],\n value=[],\n real_time_refresh=True,\n input_types=[\"Data\", \"JSON\"],\n ),\n NestedDictInput(\n name=\"docling_serve_opts\",\n display_name=\"Docling options\",\n advanced=True,\n required=False,\n info=(\n \"Optional dictionary of additional options. \"\n \"See https://github.com/docling-project/docling-serve/blob/main/docs/usage.md for more information.\"\n ),\n input_types=[\"Message\"],\n ),\n StrInput(\n name=\"verify_ssl\",\n display_name=\"Verify SSL\",\n info=\"Whether to verify SSL certificates for Docling Serve.\",\n value=\"DOCLING_SERVE_VERIFY_SSL\",\n load_from_db=True,\n required=False,\n advanced=True,\n ),\n ]\n\n outputs = [\n *BaseFileComponent.get_base_outputs(),\n ]\n\n def _process_headers(self) -> dict[str, str]:\n \"\"\"Process the headers input into a valid dictionary.\"\"\"\n if not self.api_headers:\n return {}\n\n component_headers_dict = {}\n # TableInput normalizes to list\n items = self.api_headers if isinstance(self.api_headers, list) else [self.api_headers]\n\n for item in items:\n if not item:\n continue\n\n # Case 1: Data object\n if hasattr(item, \"data\") and isinstance(item.data, dict):\n data = item.data\n if \"key\" in data and \"value\" in data:\n component_headers_dict[str(data[\"key\"])] = str(data[\"value\"])\n else:\n # Fallback: merge all keys from Data object\n for k, v in data.items():\n if k not in (\"text_key\", \"default_value\"):\n component_headers_dict[str(k)] = str(v)\n\n # Case 2: Dictionary (Table row)\n elif isinstance(item, dict):\n if \"key\" in item and \"value\" in item:\n component_headers_dict[str(item[\"key\"])] = str(item[\"value\"])\n else:\n # Fallback: merge all keys\n for k, v in item.items():\n component_headers_dict[str(k)] = str(v)\n\n # Case 3: Message object\n elif hasattr(item, \"text\") and isinstance(item.text, str):\n try:\n parsed = json.loads(item.text)\n if isinstance(parsed, dict):\n for k, v in parsed.items():\n component_headers_dict[str(k)] = str(v)\n except json.JSONDecodeError:\n pass\n\n return component_headers_dict\n\n def update_build_config(\n self, build_config: dotdict, field_value: Any, field_name: str | None = None\n ) -> dotdict:\n if field_name == \"api_headers\":\n if isinstance(field_value, dict):\n # If it's a dict, convert to list of {key, value} pairs for TableInput\n # This handles migration from NestedDictInput to TableInput\n new_value = [{\"key\": k, \"value\": v} for k, v in field_value.items()]\n build_config[\"api_headers\"][\"value\"] = new_value\n return build_config\n if field_value is None:\n build_config[\"api_headers\"][\"value\"] = []\n return build_config\n\n # Default behavior\n return super().update_build_config(build_config, field_value, field_name)\n\n def _poll_and_fetch_result(\n self, client: httpx.Client, base_url: str, task_id: str, file_path: str | None = None\n ) -> Data | None:\n \"\"\"Poll for task completion and fetch the result.\n\n Args:\n client: The HTTP client to use for requests.\n base_url: The base URL of the Docling Serve API.\n task_id: The task ID to poll for.\n file_path: Optional file path to include in the result data.\n\n Returns:\n Data object with the DoclingDocument, or None if processing failed.\n \"\"\"\n http_failures = 0\n retry_status_start = 500\n retry_status_end = 600\n start_wait_time = time.monotonic()\n\n response = client.get(f\"{base_url}/status/poll/{task_id}\")\n response.raise_for_status()\n task = response.json()\n\n while task[\"task_status\"] not in (\"success\", \"failure\"):\n processing_time = time.monotonic() - start_wait_time\n if processing_time >= self.max_poll_timeout:\n msg = (\n f\"Processing time {processing_time=} exceeds the maximum poll timeout {self.max_poll_timeout=}.\"\n \"Please increase the max_poll_timeout parameter or review why the processing \"\n \"takes long on the server.\"\n )\n self.log(msg)\n raise RuntimeError(msg)\n\n time.sleep(2)\n response = client.get(f\"{base_url}/status/poll/{task_id}\")\n\n if retry_status_start <= response.status_code < retry_status_end:\n http_failures += 1\n if http_failures > self.MAX_500_RETRIES:\n self.log(\n f\"The status requests got a http response {response.status_code} too many times.\"\n )\n return None\n continue\n\n task = response.json()\n\n result_resp = client.get(f\"{base_url}/result/{task_id}\")\n result_resp.raise_for_status()\n result = result_resp.json()\n\n if result.get(\"status\") == \"failure\" or result.get(\"errors\"):\n errors = result.get(\"errors\", [])\n err_msg_list = []\n for err in errors:\n if isinstance(err, dict) and \"error_message\" in err:\n err_msg_list.append(err[\"error_message\"])\n elif isinstance(err, str):\n err_msg_list.append(err)\n\n err_details = (\n \"; \".join(err_msg_list) if err_msg_list else \"Unknown Docling processing error\"\n )\n\n msg = f\"Docling processing failed: {err_details}\"\n raise ValueError(msg)\n\n if \"json_content\" not in result[\"document\"] or result[\"document\"][\"json_content\"] is None:\n self.log(\"No JSON DoclingDocument found in the result.\")\n return None\n\n try:\n doc = DoclingDocument.model_validate(result[\"document\"][\"json_content\"])\n data_dict: dict[str, Any] = {\"doc\": doc}\n if file_path:\n data_dict[\"file_path\"] = file_path\n return Data(data=data_dict)\n except ValidationError as e:\n self.log(f\"Error validating the document. {e}\")\n return None\n\n def _get_verify_ssl(self) -> bool:\n \"\"\"Determine whether to verify SSL certificates for Docling Serve.\n\n Returns:\n bool: True if SSL verification should be enforced, False otherwise.\n \"\"\"\n verify = getattr(self, \"verify_ssl\", None)\n if hasattr(verify, \"get_secret_value\"):\n verify = verify.get_secret_value()\n if hasattr(verify, \"text\"):\n verify = verify.text\n if isinstance(verify, bool):\n return verify\n val_str = str(verify or \"\").strip().lower()\n if val_str in (\"false\", \"0\", \"no\"):\n return False\n return True\n\n def _process_task_id(self) -> list[Data]:\n \"\"\"Process an existing task by polling for status and retrieving results.\n\n Returns:\n List containing the result Data object, or empty list if processing failed.\n \"\"\"\n transformed_url = transform_localhost_url(self.api_url)\n base_url = f\"{transformed_url}/v1\"\n\n with httpx.Client(headers=self._process_headers(), verify=self._get_verify_ssl()) as client:\n result = self._poll_and_fetch_result(client, base_url, self.task_id)\n return [result] if result else []\n\n def load_files_base(self) -> list[Data]:\n \"\"\"Load and process files, or poll an existing task if task_id is provided.\n\n Returns:\n list[Data]: Parsed data from the processed files or task.\n \"\"\"\n if self.task_id:\n return self._process_task_id()\n return super().load_files_base()\n\n def process_files(\n self, file_list: list[BaseFileComponent.BaseFile]\n ) -> list[BaseFileComponent.BaseFile]:\n transformed_url = transform_localhost_url(self.api_url)\n base_url = f\"{transformed_url}/v1\"\n\n def _convert_document(\n client: httpx.Client, file_path: Path, options: dict[str, Any]\n ) -> Data | None:\n encoded_doc = base64.b64encode(file_path.read_bytes()).decode()\n payload = {\n \"options\": options,\n \"sources\": [\n {\"kind\": \"file\", \"base64_string\": encoded_doc, \"filename\": file_path.name}\n ],\n }\n\n response = client.post(f\"{base_url}/convert/source/async\", json=payload)\n response.raise_for_status()\n task = response.json()\n\n return self._poll_and_fetch_result(client, base_url, task[\"task_id\"], str(file_path))\n\n docling_options = {\n \"to_formats\": [\"json\"],\n \"image_export_mode\": \"placeholder\",\n **(self.docling_serve_opts or {}),\n }\n\n processed_data: list[Data | None] = [None] * len(file_list)\n with (\n httpx.Client(headers=self._process_headers(), verify=self._get_verify_ssl()) as client,\n ThreadPoolExecutor(max_workers=self.max_concurrency) as executor,\n ):\n futures: list[tuple[int, Future]] = []\n for i, file in enumerate(file_list):\n if file.path is not None:\n futures.append(\n (i, executor.submit(_convert_document, client, file.path, docling_options))\n )\n\n for idx, future in futures:\n try:\n processed_data[idx] = future.result()\n except (httpx.HTTPStatusError, httpx.RequestError, KeyError, ValueError) as exc:\n self.log(f\"Docling remote processing failed: {exc}\")\n raise\n\n return self.rollup_data(file_list, processed_data)\n"
},
"delete_server_file_after_processing": {
"_input_type": "BoolInput",
@@ -787,7 +787,7 @@
"show": true,
"title_case": false,
"type": "code",
- "value": "import inspect\nfrom typing import Any\n\nfrom lfx.base.data.docling_utils import coerce_docling_document, extract_docling_documents, get_docling_image_ref_mode\nfrom lfx.custom import Component\nfrom lfx.io import DropdownInput, HandleInput, MessageTextInput, Output, StrInput\nfrom lfx.schema import Data, DataFrame\n\n\ndef traverse_pictures_kwargs(export_fn) -> dict[str, Any]:\n \"\"\"Ask export_to_markdown to serialize text nested under pictures, when it can.\n\n Scanned/image pages come back from Docling with all their OCR text attached\n as children of a PictureItem rather than to the document body. Markdown\n export skips picture children by default, which silently drops every OCR'd\n word and leaves only the image placeholder.\n\n Older docling-core releases have no `traverse_pictures` parameter and raise\n TypeError if it is passed, so probe the signature rather than assume.\n \"\"\"\n try:\n parameters = inspect.signature(export_fn).parameters\n except (TypeError, ValueError):\n # Some callables (C builtins, exotic wrappers) have no inspectable\n # signature. Omitting the flag keeps the old behaviour rather than\n # risking a TypeError that would fail the whole export.\n return {}\n if \"traverse_pictures\" in parameters:\n return {\"traverse_pictures\": True}\n return {}\n\n\nclass ExportDoclingDocumentComponent(Component):\n display_name: str = \"Export DoclingDocument\"\n description: str = \"Export DoclingDocument to markdown, html or other formats.\"\n documentation = \"https://docling-project.github.io/docling/\"\n icon = \"Docling\"\n name = \"ExportDoclingDocument\"\n\n inputs = [\n HandleInput(\n name=\"data_inputs\",\n display_name=\"JSON or Table\",\n info=\"The data with documents to export.\",\n input_types=[\"Data\", \"JSON\", \"DataFrame\", \"Table\"],\n required=True,\n ),\n DropdownInput(\n name=\"export_format\",\n display_name=\"Export format\",\n options=[\"Markdown\", \"HTML\", \"Plaintext\", \"DocTags\"],\n info=\"Select the export format to convert the input.\",\n value=\"Markdown\",\n real_time_refresh=True,\n ),\n DropdownInput(\n name=\"image_mode\",\n display_name=\"Image export mode\",\n options=[\"placeholder\", \"embedded\"],\n info=(\n \"Specify how images are exported in the output. Placeholder will replace the images with a string, \"\n \"whereas Embedded will include them as base64 encoded images.\"\n ),\n value=\"placeholder\",\n ),\n StrInput(\n name=\"md_image_placeholder\",\n display_name=\"Image placeholder\",\n info=\"Specify the image placeholder for markdown exports.\",\n value=\"<!-- image -->\",\n advanced=True,\n ),\n StrInput(\n name=\"md_page_break_placeholder\",\n display_name=\"Page break placeholder\",\n info=\"Add this placeholder between pages in the markdown output.\",\n value=\"\",\n advanced=True,\n ),\n MessageTextInput(\n name=\"doc_key\",\n display_name=\"Doc Key\",\n info=\"The key to use for the DoclingDocument column.\",\n value=\"doc\",\n advanced=True,\n ),\n ]\n\n outputs = [\n Output(display_name=\"Exported data\", name=\"data\", method=\"export_document\"),\n Output(display_name=\"Table\", name=\"dataframe\", method=\"as_dataframe\"),\n ]\n\n def update_build_config(self, build_config: dict, field_value: Any, field_name: str | None = None) -> dict:\n if field_name == \"export_format\" and field_value == \"Markdown\":\n build_config[\"md_image_placeholder\"][\"show\"] = True\n build_config[\"md_page_break_placeholder\"][\"show\"] = True\n build_config[\"image_mode\"][\"show\"] = True\n elif field_name == \"export_format\" and field_value == \"HTML\":\n build_config[\"md_image_placeholder\"][\"show\"] = False\n build_config[\"md_page_break_placeholder\"][\"show\"] = False\n build_config[\"image_mode\"][\"show\"] = True\n elif field_name == \"export_format\" and field_value in {\"Plaintext\", \"DocTags\"}:\n build_config[\"md_image_placeholder\"][\"show\"] = False\n build_config[\"md_page_break_placeholder\"][\"show\"] = False\n build_config[\"image_mode\"][\"show\"] = False\n\n return build_config\n\n def _get_image_mode(self) -> Any:\n return get_docling_image_ref_mode(self.image_mode)\n\n @staticmethod\n def _coerce_exportable_document(doc: Any) -> Any:\n return coerce_docling_document(doc)\n\n\n def _base_metadata(self, doc) -> dict:\n \"\"\"Build shared metadata from a DoclingDocument.\"\"\"\n metadata: dict = {\"export_format\": self.export_format}\n if hasattr(doc, \"name\") and doc.name:\n metadata[\"name\"] = doc.name\n if hasattr(doc, \"origin\") and doc.origin is not None:\n if hasattr(doc.origin, \"filename\") and doc.origin.filename:\n metadata[\"filename\"] = doc.origin.filename\n if hasattr(doc.origin, \"binary_hash\") and doc.origin.binary_hash:\n metadata[\"document_id\"] = str(doc.origin.binary_hash)\n if hasattr(doc.origin, \"mimetype\") and doc.origin.mimetype:\n metadata[\"mimetype\"] = doc.origin.mimetype\n return metadata\n\n def _export_per_page_markdown(self, doc, image_mode: Any, base_meta: dict) -> list[Data]:\n \"\"\"Export one Data chunk per page, tagging each with page=N.\n\n Uses DoclingDocument.pages (ordered dict of page_no -> PageItem) to\n iterate pages.\n \"\"\"\n pages_dict = getattr(doc, \"pages\", None)\n if not pages_dict:\n return []\n\n results: list[Data] = []\n for page_no in sorted(pages_dict.keys()):\n try:\n try:\n # Try standard page_no first (docling-core 2.x+)\n page_content = doc.export_to_markdown(\n image_mode=image_mode,\n image_placeholder=self.md_image_placeholder,\n page_no=page_no,\n **traverse_pictures_kwargs(doc.export_to_markdown),\n )\n except TypeError:\n # Fallback to from_page/to_page parameters\n page_content = doc.export_to_markdown(\n image_mode=image_mode,\n image_placeholder=self.md_image_placeholder,\n from_page=page_no,\n to_page=page_no,\n **traverse_pictures_kwargs(doc.export_to_markdown),\n )\n except Exception:\n # Any exception from either attempt: fall back to whole-document export\n return []\n\n if page_content and page_content.strip():\n meta = {**base_meta, \"page\": int(page_no)}\n results.append(Data(text=page_content, data={\"text\": page_content, **meta}))\n\n return results\n\n def export_document(self) -> list[Data]:\n documents, warning = extract_docling_documents(self.data_inputs, self.doc_key)\n if warning:\n self.status = warning\n\n results: list[Data] = []\n try:\n image_mode = self._get_image_mode()\n for raw_doc in documents:\n doc = self._coerce_exportable_document(raw_doc)\n base_meta = self._base_metadata(doc)\n\n # For Markdown: attempt per-page export so downstream chunks\n # carry an accurate page number (used by the chat citation UI).\n if self.export_format == \"Markdown\":\n per_page = self._export_per_page_markdown(doc, image_mode, base_meta)\n if per_page:\n results.extend(per_page)\n continue\n\n # Fall back to whole-document export (no page granularity)\n try:\n content = doc.export_to_markdown(\n image_mode=image_mode,\n image_placeholder=self.md_image_placeholder,\n page_break_placeholder=self.md_page_break_placeholder,\n **traverse_pictures_kwargs(doc.export_to_markdown),\n )\n except TypeError:\n # Older docling-core versions lack page_break_placeholder\n content = doc.export_to_markdown(\n image_mode=image_mode,\n image_placeholder=self.md_image_placeholder,\n **traverse_pictures_kwargs(doc.export_to_markdown),\n )\n elif self.export_format == \"HTML\":\n content = doc.export_to_html(image_mode=image_mode)\n elif self.export_format == \"Plaintext\":\n content = doc.export_to_text()\n elif self.export_format == \"DocTags\":\n content = doc.export_to_doctags()\n else:\n content = \"\"\n\n results.append(Data(text=content, data={\"text\": content, **base_meta}))\n\n except Exception as e:\n msg = f\"Error exporting document: {e}\"\n raise TypeError(msg) from e\n\n return results\n\n def as_dataframe(self) -> DataFrame:\n return DataFrame(self.export_document())\n"
+ "value": "import inspect\nfrom typing import Any\n\nfrom lfx.base.data.docling_utils import (\n coerce_docling_document,\n extract_docling_documents,\n get_docling_image_ref_mode,\n)\nfrom lfx.custom import Component\nfrom lfx.io import DropdownInput, HandleInput, MessageTextInput, Output, StrInput\nfrom lfx.schema import Data, DataFrame\n\n\ndef traverse_pictures_kwargs(export_fn) -> dict[str, Any]:\n \"\"\"Ask export_to_markdown to serialize text nested under pictures, when it can.\n\n Scanned/image pages come back from Docling with all their OCR text attached\n as children of a PictureItem rather than to the document body. Markdown\n export skips picture children by default, which silently drops every OCR'd\n word and leaves only the image placeholder.\n\n Older docling-core releases have no `traverse_pictures` parameter and raise\n TypeError if it is passed, so probe the signature rather than assume.\n \"\"\"\n try:\n parameters = inspect.signature(export_fn).parameters\n except (TypeError, ValueError):\n # Some callables (C builtins, exotic wrappers) have no inspectable\n # signature. Omitting the flag keeps the old behaviour rather than\n # risking a TypeError that would fail the whole export.\n return {}\n if \"traverse_pictures\" in parameters:\n return {\"traverse_pictures\": True}\n return {}\n\n\nclass ExportDoclingDocumentComponent(Component):\n display_name: str = \"Export DoclingDocument\"\n description: str = \"Export DoclingDocument to markdown, html or other formats.\"\n documentation = \"https://docling-project.github.io/docling/\"\n icon = \"Docling\"\n name = \"ExportDoclingDocument\"\n\n inputs = [\n HandleInput(\n name=\"data_inputs\",\n display_name=\"JSON or Table\",\n info=\"The data with documents to export.\",\n input_types=[\"Data\", \"JSON\", \"DataFrame\", \"Table\"],\n required=True,\n ),\n DropdownInput(\n name=\"export_format\",\n display_name=\"Export format\",\n options=[\"Markdown\", \"HTML\", \"Plaintext\", \"DocTags\"],\n info=\"Select the export format to convert the input.\",\n value=\"Markdown\",\n real_time_refresh=True,\n ),\n DropdownInput(\n name=\"image_mode\",\n display_name=\"Image export mode\",\n options=[\"placeholder\", \"embedded\"],\n info=(\n \"Specify how images are exported in the output. Placeholder will replace the images with a string, \"\n \"whereas Embedded will include them as base64 encoded images.\"\n ),\n value=\"placeholder\",\n ),\n StrInput(\n name=\"md_image_placeholder\",\n display_name=\"Image placeholder\",\n info=\"Specify the image placeholder for markdown exports.\",\n value=\"<!-- image -->\",\n advanced=True,\n ),\n StrInput(\n name=\"md_page_break_placeholder\",\n display_name=\"Page break placeholder\",\n info=\"Add this placeholder between pages in the markdown output.\",\n value=\"\",\n advanced=True,\n ),\n MessageTextInput(\n name=\"doc_key\",\n display_name=\"Doc Key\",\n info=\"The key to use for the DoclingDocument column.\",\n value=\"doc\",\n advanced=True,\n ),\n ]\n\n outputs = [\n Output(display_name=\"Exported data\", name=\"data\", method=\"export_document\"),\n Output(display_name=\"Table\", name=\"dataframe\", method=\"as_dataframe\"),\n ]\n\n def update_build_config(\n self, build_config: dict, field_value: Any, field_name: str | None = None\n ) -> dict:\n if field_name == \"export_format\" and field_value == \"Markdown\":\n build_config[\"md_image_placeholder\"][\"show\"] = True\n build_config[\"md_page_break_placeholder\"][\"show\"] = True\n build_config[\"image_mode\"][\"show\"] = True\n elif field_name == \"export_format\" and field_value == \"HTML\":\n build_config[\"md_image_placeholder\"][\"show\"] = False\n build_config[\"md_page_break_placeholder\"][\"show\"] = False\n build_config[\"image_mode\"][\"show\"] = True\n elif field_name == \"export_format\" and field_value in {\"Plaintext\", \"DocTags\"}:\n build_config[\"md_image_placeholder\"][\"show\"] = False\n build_config[\"md_page_break_placeholder\"][\"show\"] = False\n build_config[\"image_mode\"][\"show\"] = False\n\n return build_config\n\n def _get_image_mode(self) -> Any:\n return get_docling_image_ref_mode(self.image_mode)\n\n @staticmethod\n def _coerce_exportable_document(doc: Any) -> Any:\n return coerce_docling_document(doc)\n\n def _base_metadata(self, doc) -> dict:\n \"\"\"Build shared metadata from a DoclingDocument.\"\"\"\n metadata: dict = {\"export_format\": self.export_format}\n if hasattr(doc, \"name\") and doc.name:\n metadata[\"name\"] = doc.name\n if hasattr(doc, \"origin\") and doc.origin is not None:\n if hasattr(doc.origin, \"filename\") and doc.origin.filename:\n metadata[\"filename\"] = doc.origin.filename\n if hasattr(doc.origin, \"binary_hash\") and doc.origin.binary_hash:\n metadata[\"document_id\"] = str(doc.origin.binary_hash)\n if hasattr(doc.origin, \"mimetype\") and doc.origin.mimetype:\n metadata[\"mimetype\"] = doc.origin.mimetype\n return metadata\n\n def _export_per_page_markdown(self, doc, image_mode: Any, base_meta: dict) -> list[Data]:\n \"\"\"Export one Data chunk per page, tagging each with page=N.\n\n Uses DoclingDocument.pages (ordered dict of page_no -> PageItem) to\n iterate pages.\n \"\"\"\n pages_dict = getattr(doc, \"pages\", None)\n if not pages_dict:\n return []\n\n results: list[Data] = []\n for page_no in sorted(pages_dict.keys()):\n try:\n try:\n # Try standard page_no first (docling-core 2.x+)\n page_content = doc.export_to_markdown(\n image_mode=image_mode,\n image_placeholder=self.md_image_placeholder,\n page_no=page_no,\n **traverse_pictures_kwargs(doc.export_to_markdown),\n )\n except TypeError:\n # Fallback to from_page/to_page parameters\n page_content = doc.export_to_markdown(\n image_mode=image_mode,\n image_placeholder=self.md_image_placeholder,\n from_page=page_no,\n to_page=page_no,\n **traverse_pictures_kwargs(doc.export_to_markdown),\n )\n except Exception:\n # Any exception from either attempt: fall back to whole-document export\n return []\n\n if page_content and page_content.strip():\n meta = {**base_meta, \"page\": int(page_no)}\n results.append(Data(text=page_content, data={\"text\": page_content, **meta}))\n\n return results\n\n def export_document(self) -> list[Data]:\n documents, warning = extract_docling_documents(self.data_inputs, self.doc_key)\n if warning:\n self.status = warning\n\n results: list[Data] = []\n try:\n image_mode = self._get_image_mode()\n for raw_doc in documents:\n doc = self._coerce_exportable_document(raw_doc)\n base_meta = self._base_metadata(doc)\n\n # For Markdown: attempt per-page export so downstream chunks\n # carry an accurate page number (used by the chat citation UI).\n if self.export_format == \"Markdown\":\n per_page = self._export_per_page_markdown(doc, image_mode, base_meta)\n if per_page:\n results.extend(per_page)\n continue\n\n # Fall back to whole-document export (no page granularity)\n try:\n content = doc.export_to_markdown(\n image_mode=image_mode,\n image_placeholder=self.md_image_placeholder,\n page_break_placeholder=self.md_page_break_placeholder,\n **traverse_pictures_kwargs(doc.export_to_markdown),\n )\n except TypeError:\n # Older docling-core versions lack page_break_placeholder\n content = doc.export_to_markdown(\n image_mode=image_mode,\n image_placeholder=self.md_image_placeholder,\n **traverse_pictures_kwargs(doc.export_to_markdown),\n )\n elif self.export_format == \"HTML\":\n content = doc.export_to_html(image_mode=image_mode)\n elif self.export_format == \"Plaintext\":\n content = doc.export_to_text()\n elif self.export_format == \"DocTags\":\n content = doc.export_to_doctags()\n else:\n content = \"\"\n\n results.append(Data(text=content, data={\"text\": content, **base_meta}))\n\n except Exception as e:\n msg = f\"Error exporting document: {e}\"\n raise TypeError(msg) from e\n\n return results\n\n def as_dataframe(self) -> DataFrame:\n return DataFrame(self.export_document())\n"
},
"data_inputs": {
"_input_type": "HandleInput",
diff --git a/tests/unit/conftest.py b/tests/unit/conftest.py
index 88d5848df..643021b1a 100644
--- a/tests/unit/conftest.py
+++ b/tests/unit/conftest.py
@@ -11,6 +11,7 @@ so test fixtures cannot accidentally pollute the dev `data/openrag.db` file.
# guarantees that even if a test imports something that triggers
# `init_engine()` at import time, the engine binds to an in-memory DB.
import os as _os
+
_os.environ.setdefault("DATABASE_URL", "sqlite+aiosqlite:///:memory:")
# Defensive default: pin OPENRAG_RBAC_ENFORCE=true for unit tests so a
@@ -39,8 +40,71 @@ def _reset_db_engine_module_state(monkeypatch):
"""
try:
import db.engine as _engine_mod
+
monkeypatch.setattr(_engine_mod, "_engine", None, raising=False)
monkeypatch.setattr(_engine_mod, "SessionLocal", None, raising=False)
except ImportError:
pass
yield
+
+
+# ---------------------------------------------------------------------------
+# Known failures (see known_failures.txt)
+#
+# CI runs the full unit suite. Tests that already fail on main are listed in
+# known_failures.txt and marked strict xfail here, so a NEW failure turns CI
+# red while the existing ones don't — and a listed test that starts passing
+# also turns CI red, forcing its line to be deleted. The list can only shrink.
+# ---------------------------------------------------------------------------
+
+_KNOWN_FAILURES_FILE = _os.path.join(_os.path.dirname(__file__), "known_failures.txt")
+
+
+def _read_known_failures() -> tuple[set[str], list[str]]:
+ node_ids: set[str] = set()
+ ignored: list[str] = []
+ try:
+ with open(_KNOWN_FAILURES_FILE) as f:
+ for raw in f:
+ line = raw.strip()
+ if not line or line.startswith("#"):
+ continue
+ if line.startswith("ignore:"):
+ ignored.append(line[len("ignore:") :].strip())
+ else:
+ node_ids.add(line)
+ except FileNotFoundError:
+ pass
+ return node_ids, ignored
+
+
+_KNOWN_FAILING_NODE_IDS, _KNOWN_UNIMPORTABLE = _read_known_failures()
+
+# Modules that fail at import cannot be xfailed; skip collecting them.
+collect_ignore = list(_KNOWN_UNIMPORTABLE)
+
+
+def pytest_collection_modifyitems(config, items):
+ collected = set()
+ for item in items:
+ node_id = item.nodeid
+ if node_id in _KNOWN_FAILING_NODE_IDS:
+ collected.add(node_id)
+ item.add_marker(
+ pytest.mark.xfail(
+ strict=True,
+ reason="Known failure on main (tests/unit/known_failures.txt). "
+ "If this now passes, delete its line from that file.",
+ )
+ )
+
+ # In CI the whole suite is collected, so every listed id must exist. A stale
+ # or mistyped entry would otherwise silently stop protecting anything.
+ if _os.environ.get("OPENRAG_ENFORCE_KNOWN_FAILURES") == "1":
+ stale = sorted(_KNOWN_FAILING_NODE_IDS - collected)
+ if stale:
+ raise pytest.UsageError(
+ "tests/unit/known_failures.txt lists tests that were not collected "
+ "(renamed, deleted, or mistyped). Remove or fix these lines:\n "
+ + "\n ".join(stale)
+ )
diff --git a/tests/unit/known_failures.txt b/tests/unit/known_failures.txt
new file mode 100644
index 000000000..930a0faae
--- /dev/null
+++ b/tests/unit/known_failures.txt
@@ -0,0 +1,44 @@
+# Unit tests that already fail on main.
+#
+# CI runs the whole unit suite. Each test listed here is marked strict xfail:
+# - if it still fails, CI stays green;
+# - if it starts PASSING, CI goes red until you delete its line here.
+# So this list can only shrink. Never add a line to get a new failure through CI —
+# fix the test instead.
+#
+# Lines starting with "ignore:" name modules that cannot even be imported. They
+# are skipped at collection, so CI cannot tell when they get fixed; check them by
+# hand when touching agent.py.
+#
+# Baseline taken 2026-09-17 against main, in a clean checkout with no .env.
+
+ignore:test_agent_response.py
+ignore:test_agent_sources.py
+
+tests/unit/api/test_langflow_sync_bug_1587.py::test_explicit_llm_arguments_bypass_fallback
+tests/unit/api/test_model_providers_endpoint.py::test_oss_and_on_prem_still_publish_ollama[on_prem]
+tests/unit/api/test_model_providers_endpoint.py::test_an_override_file_drives_the_payload
+tests/unit/config/test_model_providers_config.py::test_shipped_defaults_keep_ollama_out_of_saas_only
+tests/unit/config/test_model_providers_config.py::test_both_azure_providers_ship_in_every_mode
+tests/unit/enhancements/providers/watsonx/test_onprem.py::test_it_ships_on_prem_and_never_in_saas
+tests/unit/enhancements/providers/watsonx/test_onprem.py::test_its_models_come_from_config_not_ibm_clouds_price_table
+tests/unit/enhancements/providers/watsonx/test_onprem.py::test_the_picker_shows_what_the_cluster_serves
+tests/unit/enhancements/providers/watsonx/test_onprem.py::test_an_unreachable_cluster_keeps_the_configured_fallback
+tests/unit/services/test_model_catalog.py::test_catalog_publishes_azure_ai_where_the_config_enables_it
+tests/unit/services/test_model_catalog.py::test_azure_openai_is_the_row_that_carries_the_gpt_41_family
+tests/unit/services/test_model_catalog.py::test_the_shipped_config_excludes_on_azure_as_well_as_openai
+tests/unit/services/test_skip_os_security_setup_startup.py::test_setup_runs_when_flag_false
+tests/unit/services/test_skip_os_security_setup_startup.py::test_setup_skipped_when_flag_true
+tests/unit/test_agent_sources_fence_stripped.py::test_fence_untrusted_text_escapes_embedded_end_delimiter
+tests/unit/test_openai_compatible_langflow_components.py::test_component_index_sha256_matches_langflow_integrity_check
+tests/unit/test_opensearch_security_setup.py::test_setup_opensearch_security_success
+tests/unit/test_opensearch_security_setup.py::test_setup_opensearch_security_graceful_auth_error
+tests/unit/test_opensearch_security_setup.py::test_setup_opensearch_security_missing_files
+tests/unit/test_settings_async_post_save.py::test_update_settings_retains_background_task_reference
+tests/unit/test_settings_async_post_save.py::test_provider_removal_triggers_mcp_server_update
+tests/unit/test_settings_provider_removal_defaults.py::TestFirstConfiguredLlmProvider::test_skips_unconfigured
+tests/unit/test_settings_provider_removal_defaults.py::TestFirstConfiguredEmbeddingProvider::test_excludes_removed_provider
+tests/unit/test_settings_provider_removal_defaults.py::TestFirstConfiguredEmbeddingProvider::test_anthropic_never_returned
+tests/unit/test_settings_provider_removal_defaults.py::TestProviderRemovalLlmDefault::test_remove_openai_falls_back_to_ollama_empty_model
+tests/unit/test_settings_refresh_endpoint.py::test_refresh_endpoint_requires_auth_in_auth_mode
+tests/unit/test_settings_refresh_endpoint.py::test_refresh_endpoint_returns_expected_http_response_shape
diff --git a/tests/unit/test_custom_components.py b/tests/unit/test_custom_components.py
new file mode 100644
index 000000000..8caef2732
--- /dev/null
+++ b/tests/unit/test_custom_components.py
@@ -0,0 +1,232 @@
+"""Structural checks that apply to every custom Langflow component.
+
+These are deliberately generic: they run over whatever lives in
+``custom_components/openrag/`` rather than naming individual components, so a
+new component is covered the moment it is added.
+
+Two of them exist because of a specific failure mode. ``autofix.ci``
+(`.github/workflows/autofix.ci.yml`) runs ``ruff check --fix`` and
+``ruff format`` on changed files and **pushes the result directly**. A component
+that is not already clean therefore gets rewritten by CI *after* review — and
+since the flow JSON carries its own copy of the component source, which ruff has
+no reason to touch, the two silently diverge. Langflow then compares them as
+text, marks the node outdated, and refuses to build the flow. That is what broke
+onboarding after #2389.
+
+Keeping every component ruff-clean means CI has nothing left to rewrite, so the
+drift cannot be introduced that way in the first place.
+"""
+
+import ast
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+COMPONENT_DIR = REPO_ROOT / "custom_components" / "openrag"
+FLOW_DIR = REPO_ROOT / "flows"
+
+COMPONENT_FILES = sorted(p for p in COMPONENT_DIR.glob("*.py") if p.name != "__init__.py")
+COMPONENT_IDS = [p.name for p in COMPONENT_FILES]
+
+# Matches the flags autofix.ci uses, so this test agrees with what CI would do.
+RUFF_CHECK_ARGS = ["check", "--extend-ignore", "F401"]
+
+
+def _ruff(*args: str) -> subprocess.CompletedProcess:
+ ruff = REPO_ROOT / ".venv" / "bin" / "ruff"
+ if not ruff.exists():
+ pytest.skip("ruff is not installed in this environment")
+ return subprocess.run(
+ [str(ruff), *args], capture_output=True, text=True, cwd=REPO_ROOT, check=False
+ )
+
+
+def _class_defs(tree: ast.Module) -> list[ast.ClassDef]:
+ return [node for node in tree.body if isinstance(node, ast.ClassDef)]
+
+
+def _keyword_value(call: ast.Call, name: str) -> str | None:
+ for kw in call.keywords:
+ if (
+ kw.arg == name
+ and isinstance(kw.value, ast.Constant)
+ and isinstance(kw.value.value, str)
+ ):
+ return kw.value.value
+ return None
+
+
+def _calls_in_class_attr(cls: ast.ClassDef, attr: str) -> list[ast.Call]:
+ """Every call in a class-level list assignment, e.g. ``inputs = [...]``."""
+ calls: list[ast.Call] = []
+ for node in cls.body:
+ if isinstance(node, ast.Assign):
+ targets: list[ast.expr] = node.targets
+ value: ast.expr | None = node.value
+ elif isinstance(node, ast.AnnAssign):
+ targets = [node.target]
+ value = node.value
+ else:
+ continue
+ if not any(isinstance(t, ast.Name) and t.id == attr for t in targets):
+ continue
+ if isinstance(value, (ast.List, ast.Tuple)):
+ calls += [e for e in value.elts if isinstance(e, ast.Call)]
+ return calls
+
+
+def test_there_are_components_to_check():
+ """Guards against the glob silently matching nothing."""
+ assert COMPONENT_FILES, f"No component files found under {COMPONENT_DIR}"
+
+
[email protected]("path", COMPONENT_FILES, ids=COMPONENT_IDS)
+def test_component_source_is_valid_python(path: Path):
+ """A syntax error here ships a component that cannot load at all."""
+ try:
+ ast.parse(path.read_text())
+ except SyntaxError as exc:
+ pytest.fail(f"{path.name} is not valid Python: line {exc.lineno}: {exc.msg}")
+
+
[email protected]("path", COMPONENT_FILES, ids=COMPONENT_IDS)
+def test_component_is_ruff_format_clean(path: Path):
+ """If CI would reformat it, CI will desync the flow's embedded copy."""
+ result = _ruff("format", "--check", str(path.relative_to(REPO_ROOT)))
+ if result.returncode != 0:
+ diff = _ruff("format", "--diff", str(path.relative_to(REPO_ROOT))).stdout
+ pytest.fail(
+ f"{path.name} is not ruff-format clean.\n\n"
+ "autofix.ci runs `ruff format` on changed files and pushes the result, "
+ "which would rewrite this file after review and leave the copy embedded "
+ "in flows/*.json stale — blocking the flow build.\n\n"
+ f"Fix with: ruff format {path.relative_to(REPO_ROOT)}\n"
+ "then regenerate the flow copies (see test_flow_component_sync.py).\n\n"
+ f"{diff}"
+ )
+
+
[email protected]("path", COMPONENT_FILES, ids=COMPONENT_IDS)
+def test_component_is_ruff_check_clean(path: Path):
+ """Same hazard as formatting: `ruff check --fix` also rewrites and pushes."""
+ result = _ruff(*RUFF_CHECK_ARGS, str(path.relative_to(REPO_ROOT)))
+ if result.returncode != 0:
+ pytest.fail(
+ f"{path.name} has ruff lint findings that autofix.ci would fix and push, "
+ "desyncing the copy embedded in flows/*.json.\n\n"
+ f"Fix with: ruff check --fix --extend-ignore F401 {path.relative_to(REPO_ROOT)}\n"
+ "then regenerate the flow copies (see test_flow_component_sync.py).\n\n"
+ f"{result.stdout}"
+ )
+
+
[email protected]("path", COMPONENT_FILES, ids=COMPONENT_IDS)
+def test_component_outputs_reference_real_methods(path: Path):
+ """An Output naming a method that does not exist fails only at runtime."""
+ tree = ast.parse(path.read_text())
+ for cls in _class_defs(tree):
+ methods = {
+ n.name for n in cls.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))
+ }
+ for call in _calls_in_class_attr(cls, "outputs"):
+ method = _keyword_value(call, "method")
+ if method is None:
+ continue
+ assert method in methods, (
+ f"{path.name}: {cls.name} declares an output calling `{method}()`, "
+ f"but that method is not defined on the class. Defined: {sorted(methods)}"
+ )
+
+
[email protected]("path", COMPONENT_FILES, ids=COMPONENT_IDS)
+def test_component_input_names_are_unique(path: Path):
+ """Duplicate input names silently shadow each other in the template."""
+ tree = ast.parse(path.read_text())
+ for cls in _class_defs(tree):
+ names = [
+ name
+ for call in _calls_in_class_attr(cls, "inputs")
+ if (name := _keyword_value(call, "name")) is not None
+ ]
+ duplicates = sorted({n for n in names if names.count(n) > 1})
+ assert not duplicates, (
+ f"{path.name}: {cls.name} declares duplicate input names: {duplicates}"
+ )
+
+
[email protected]("path", COMPONENT_FILES, ids=COMPONENT_IDS)
+def test_component_output_names_are_unique(path: Path):
+ """Duplicate output names make the wrong handle resolve downstream."""
+ tree = ast.parse(path.read_text())
+ for cls in _class_defs(tree):
+ names = [
+ name
+ for call in _calls_in_class_attr(cls, "outputs")
+ if (name := _keyword_value(call, "name")) is not None
+ ]
+ duplicates = sorted({n for n in names if names.count(n) > 1})
+ assert not duplicates, (
+ f"{path.name}: {cls.name} declares duplicate output names: {duplicates}"
+ )
+
+
+def _embedded_code_blocks() -> list[tuple[str, str, str]]:
+ """(flow name, node id, code) for every node in every flow that carries source."""
+ blocks = []
+ for flow_path in sorted(FLOW_DIR.glob("*.json")):
+ flow = json.loads(flow_path.read_text())
+ for node in flow.get("data", {}).get("nodes", []):
+ data = node.get("data", {})
+ code = (data.get("node", {}).get("template", {}).get("code") or {}).get("value")
+ if isinstance(code, str) and code.strip():
+ blocks.append((flow_path.name, data.get("id", "?"), code))
+ return blocks
+
+
+EMBEDDED_CODE = _embedded_code_blocks()
+
+
+def test_flows_carry_embedded_code():
+ """Guards against the discovery above returning nothing."""
+ assert EMBEDDED_CODE, "No embedded component code found in flows/*.json"
+
+
+ ("flow_name", "node_id", "code"),
+ EMBEDDED_CODE,
+ ids=[f"{flow}:{node}" for flow, node, _ in EMBEDDED_CODE],
+)
+def test_embedded_code_is_valid_python(flow_name: str, node_id: str, code: str):
+ """Truncated or corrupted embedded source breaks the flow at build time."""
+ try:
+ ast.parse(code)
+ except SyntaxError as exc:
+ pytest.fail(
+ f"{flow_name} / {node_id} has embedded code that is not valid Python: "
+ f"line {exc.lineno}: {exc.msg}"
+ )
+
+
+ ("flow_name", "node_id", "code"),
+ EMBEDDED_CODE,
+ ids=[f"{flow}:{node}" for flow, node, _ in EMBEDDED_CODE],
+)
+def test_embedded_code_defines_a_class(flow_name: str, node_id: str, code: str):
+ """Every Langflow node's code should define its component class."""
+ tree = ast.parse(code)
+ assert _class_defs(tree), (
+ f"{flow_name} / {node_id} embeds code that defines no class; "
+ "Langflow will not be able to resolve the component."
+ )
+
+
+def test_python_version_matches_the_interpreter_running_these_checks():
+ """ast parsing is version-sensitive; record what validated the sources."""
+ assert sys.version_info >= (3, 11), (
+ "These components use `X | None` syntax in annotations; parse under 3.11+."
+ )
diff --git a/tests/unit/test_flow_component_sync.py b/tests/unit/test_flow_component_sync.py
new file mode 100644
index 000000000..f5eeb7fee
--- /dev/null
+++ b/tests/unit/test_flow_component_sync.py
@@ -0,0 +1,175 @@
+"""Every custom component embedded in a flow must match its source file.
+
+Langflow runs the copy of a component stored inside the flow JSON, not the file
+in ``custom_components/``. It also compares the two to decide whether a node is
+stale: if they differ *as text*, it marks the component outdated and refuses to
+build the flow — which breaks onboarding, with an error that says nothing about
+formatting.
+
+That is not hypothetical. In #2389 a formatter reflowed
+``export_docling_document.py`` (import wrapping, a signature split across lines,
+one blank line) after the flow's copy had been regenerated. The code was
+functionally identical and the flow was blocked anyway.
+
+So this compares every embedded custom component against its file, byte for
+byte, across every flow.
+"""
+
+import difflib
+import hashlib
+import json
+import re
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parents[2]
+COMPONENT_DIR = REPO_ROOT / "custom_components" / "openrag"
+FLOW_DIR = REPO_ROOT / "flows"
+
+# Guards against the discovery below silently finding nothing and the whole
+# suite passing vacuously. Raise this if more components get embedded.
+MINIMUM_EMBEDDED_COMPONENTS = 12
+
+CLASS_RE = re.compile(r"^class\s+(\w+)\s*\(", re.MULTILINE)
+
+
+def _component_sources() -> dict[str, tuple[Path, str]]:
+ """Map each class name defined under custom_components/ to its file."""
+ sources: dict[str, tuple[Path, str]] = {}
+ for path in sorted(COMPONENT_DIR.glob("*.py")):
+ if path.name == "__init__.py":
+ continue
+ text = path.read_text()
+ for class_name in CLASS_RE.findall(text):
+ sources[class_name] = (path, text)
+ return sources
+
+
+def _embedded_components() -> list[tuple[str, str, Path, str, str]]:
+ """Find (flow, node id, source path, embedded code, source text) for each match.
+
+ A flow node is matched to a component file by the class it defines, so nodes
+ holding Langflow's built-in components are skipped rather than compared
+ against something they were never copied from.
+ """
+ sources = _component_sources()
+ found: list[tuple[str, str, Path, str, str]] = []
+
+ for flow_path in sorted(FLOW_DIR.glob("*.json")):
+ flow = json.loads(flow_path.read_text())
+ for node in flow.get("data", {}).get("nodes", []):
+ data = node.get("data", {})
+ code = (data.get("node", {}).get("template", {}).get("code") or {}).get("value")
+ if not isinstance(code, str):
+ continue
+ for class_name in CLASS_RE.findall(code):
+ if class_name in sources:
+ source_path, source_text = sources[class_name]
+ found.append(
+ (flow_path.name, data.get("id", "?"), source_path, code, source_text)
+ )
+ break
+ return found
+
+
+EMBEDDED = _embedded_components()
+
+
+def _regeneration_hint(flow_name: str, node_id: str, source_path: Path) -> str:
+ return (
+ f"\n\nThe flow's copy has drifted from {source_path.relative_to(REPO_ROOT)}.\n"
+ "Langflow will mark this component outdated and refuse to build the flow.\n"
+ "Regenerate the embedded copy:\n\n"
+ " python - <<'EOF'\n"
+ " import json\n"
+ f" path = 'flows/{flow_name}'\n"
+ " flow = json.load(open(path))\n"
+ f" src = open('{source_path.relative_to(REPO_ROOT)}').read()\n"
+ " for node in flow['data']['nodes']:\n"
+ f" if node['data']['id'] == '{node_id}':\n"
+ " node['data']['node']['template']['code']['value'] = src\n"
+ " with open(path, 'w') as f:\n"
+ " json.dump(flow, f, indent=2, ensure_ascii=False)\n"
+ " f.write('\\n')\n"
+ " EOF\n"
+ )
+
+
+def test_discovery_found_the_embedded_components():
+ """A bug in discovery would make every other test here pass for free."""
+ assert len(EMBEDDED) >= MINIMUM_EMBEDDED_COMPONENTS, (
+ f"Only found {len(EMBEDDED)} embedded custom components, expected at least "
+ f"{MINIMUM_EMBEDDED_COMPONENTS}. Either discovery broke or components were "
+ "removed from the flows — check before lowering this number."
+ )
+
+
+ ("flow_name", "node_id", "source_path", "embedded", "source"),
+ EMBEDDED,
+ ids=[f"{flow}:{node}" for flow, node, _, _, _ in EMBEDDED],
+)
+def test_embedded_component_matches_its_source(flow_name, node_id, source_path, embedded, source):
+ """Byte-for-byte, because Langflow compares text and not behaviour."""
+ if embedded == source:
+ return
+
+ diff = "\n".join(
+ difflib.unified_diff(
+ embedded.splitlines(),
+ source.splitlines(),
+ fromfile=f"{flow_name}:{node_id} (embedded)",
+ tofile=str(source_path.relative_to(REPO_ROOT)),
+ lineterm="",
+ n=2,
+ )
+ )
+ pytest.fail(
+ f"{flow_name} / {node_id} does not match its source file."
+ f"{_regeneration_hint(flow_name, node_id, source_path)}\n{diff}"
+ )
+
+
+def test_whitespace_only_drift_is_still_a_failure():
+ """Proves the check would catch the #2389 regression, not just gross edits.
+
+ Without this, a comparison that normalised whitespace would pass this suite
+ while leaving flows blocked in exactly the way that broke onboarding.
+ """
+ flow_name, node_id, source_path, embedded, source = EMBEDDED[0]
+
+ # The real drift was import wrapping, a split signature, and a blank line.
+ # A trailing newline is the smallest whitespace-only change, and unlike
+ # collapsing a blank line it does not depend on how the source is formatted.
+ reformatted = embedded + "\n"
+ assert reformatted != embedded, "expected a whitespace change to alter the text"
+
+ with pytest.raises(pytest.fail.Exception):
+ test_embedded_component_matches_its_source(
+ flow_name, node_id, source_path, reformatted, source
+ )
+
+
+def test_no_two_components_share_a_class_name():
+ """Discovery matches on class name, so duplicates would compare against the wrong file."""
+ seen: dict[str, Path] = {}
+ duplicates = []
+ for path in sorted(COMPONENT_DIR.glob("*.py")):
+ if path.name == "__init__.py":
+ continue
+ for class_name in CLASS_RE.findall(path.read_text()):
+ if class_name in seen:
+ duplicates.append(f"{class_name}: {seen[class_name].name} and {path.name}")
+ seen[class_name] = path
+
+ assert not duplicates, "Class names must be unique for flow matching: " + "; ".join(duplicates)
+
+
+def test_embedded_copies_are_reported_with_stable_hashes():
+ """A quick inventory, so a failure elsewhere is easy to correlate by hash."""
+ hashes = {
+ f"{flow}:{node}": hashlib.sha256(embedded.encode()).hexdigest()[:16]
+ for flow, node, _, embedded, _ in EMBEDDED
+ }
+ assert len(hashes) == len(EMBEDDED)