Skip to content

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

Python

feat: add chunk level page source (#2015)

Lucas Oliveiraea4703311c40
diff --git a/flows/components/export_docling_document.py b/flows/components/export_docling_document.py
new file mode 100644
index 000000000..727534435
--- /dev/null
+++ b/flows/components/export_docling_document.py
@@ -0,0 +1,183 @@
+from typing import Any
+
+from docling_core.types.doc import ImageRefMode
+
+from lfx.base.data.docling_utils import extract_docling_documents
+from lfx.custom import Component
+from lfx.io import DropdownInput, HandleInput, MessageTextInput, Output, StrInput
+from lfx.schema import Data, DataFrame
+
+
+class ExportDoclingDocumentComponent(Component):
+ display_name: str = "Export DoclingDocument"
+ description: str = "Export DoclingDocument to markdown, html or other formats."
+ documentation = "https://docling-project.github.io/docling/"
+ icon = "Docling"
+ name = "ExportDoclingDocument"
+
+ inputs = [
+ HandleInput(
+ name="data_inputs",
+ display_name="JSON or Table",
+ info="The data with documents to export.",
+ input_types=["Data", "JSON", "DataFrame", "Table"],
+ required=True,
+ ),
+ DropdownInput(
+ name="export_format",
+ display_name="Export format",
+ options=["Markdown", "HTML", "Plaintext", "DocTags"],
+ info="Select the export format to convert the input.",
+ value="Markdown",
+ real_time_refresh=True,
+ ),
+ DropdownInput(
+ name="image_mode",
+ display_name="Image export mode",
+ options=["placeholder", "embedded"],
+ info=(
+ "Specify how images are exported in the output. Placeholder will replace the images with a string, "
+ "whereas Embedded will include them as base64 encoded images."
+ ),
+ value="placeholder",
+ ),
+ StrInput(
+ name="md_image_placeholder",
+ display_name="Image placeholder",
+ info="Specify the image placeholder for markdown exports.",
+ value="<!-- image -->",
+ advanced=True,
+ ),
+ StrInput(
+ name="md_page_break_placeholder",
+ display_name="Page break placeholder",
+ info="Add this placeholder between pages in the markdown output.",
+ value="",
+ advanced=True,
+ ),
+ MessageTextInput(
+ name="doc_key",
+ display_name="Doc Key",
+ info="The key to use for the DoclingDocument column.",
+ value="doc",
+ advanced=True,
+ ),
+ ]
+
+ outputs = [
+ Output(display_name="Exported data", name="data", method="export_document"),
+ Output(display_name="Table", name="dataframe", method="as_dataframe"),
+ ]
+
+ def update_build_config(self, build_config: dict, field_value: Any, field_name: str | None = None) -> dict:
+ if field_name == "export_format" and field_value == "Markdown":
+ build_config["md_image_placeholder"]["show"] = True
+ build_config["md_page_break_placeholder"]["show"] = True
+ build_config["image_mode"]["show"] = True
+ elif field_name == "export_format" and field_value == "HTML":
+ build_config["md_image_placeholder"]["show"] = False
+ build_config["md_page_break_placeholder"]["show"] = False
+ build_config["image_mode"]["show"] = True
+ elif field_name == "export_format" and field_value in {"Plaintext", "DocTags"}:
+ build_config["md_image_placeholder"]["show"] = False
+ build_config["md_page_break_placeholder"]["show"] = False
+ build_config["image_mode"]["show"] = False
+
+ return build_config
+
+ def _base_metadata(self, doc) -> dict:
+ """Build shared metadata from a DoclingDocument."""
+ metadata: dict = {"export_format": self.export_format}
+ if hasattr(doc, "name") and doc.name:
+ metadata["name"] = doc.name
+ if hasattr(doc, "origin") and doc.origin is not None:
+ if hasattr(doc.origin, "filename") and doc.origin.filename:
+ metadata["filename"] = doc.origin.filename
+ if hasattr(doc.origin, "binary_hash") and doc.origin.binary_hash:
+ metadata["document_id"] = str(doc.origin.binary_hash)
+ if hasattr(doc.origin, "mimetype") and doc.origin.mimetype:
+ metadata["mimetype"] = doc.origin.mimetype
+ return metadata
+
+ def _export_per_page_markdown(self, doc, image_mode: ImageRefMode, base_meta: dict) -> list[Data]:
+ """Export one Data chunk per page, tagging each with page=N.
+
+ Uses DoclingDocument.pages (ordered dict of page_no -> PageItem) to
+ iterate pages.
+ """
+ pages_dict = getattr(doc, "pages", None)
+ if not pages_dict:
+ return []
+
+ results: list[Data] = []
+ for page_no in sorted(pages_dict.keys()):
+ try:
+ try:
+ # Try standard page_no first (docling-core 2.x+)
+ page_content = doc.export_to_markdown(
+ image_mode=image_mode,
+ image_placeholder=self.md_image_placeholder,
+ page_no=page_no,
+ )
+ except TypeError:
+ # Fallback to from_page/to_page parameters
+ page_content = doc.export_to_markdown(
+ image_mode=image_mode,
+ image_placeholder=self.md_image_placeholder,
+ from_page=page_no,
+ to_page=page_no,
+ )
+ except Exception:
+ # Any exception from either attempt: fall back to whole-document export
+ return []
+
+ if page_content and page_content.strip():
+ meta = {**base_meta, "page": int(page_no)}
+ results.append(Data(text=page_content, data={"text": page_content, **meta}))
+
+ return results
+
+ def export_document(self) -> list[Data]:
+ documents, warning = extract_docling_documents(self.data_inputs, self.doc_key)
+ if warning:
+ self.status = warning
+
+ results: list[Data] = []
+ try:
+ image_mode = ImageRefMode(self.image_mode)
+ for doc in documents:
+ base_meta = self._base_metadata(doc)
+
+ # For Markdown: attempt per-page export so downstream chunks
+ # carry an accurate page number (used by the chat citation UI).
+ if self.export_format == "Markdown":
+ per_page = self._export_per_page_markdown(doc, image_mode, base_meta)
+ if per_page:
+ results.extend(per_page)
+ continue
+
+ # Fall back to whole-document export (no page granularity)
+ content = doc.export_to_markdown(
+ image_mode=image_mode,
+ image_placeholder=self.md_image_placeholder,
+ page_break_placeholder=self.md_page_break_placeholder,
+ )
+ elif self.export_format == "HTML":
+ content = doc.export_to_html(image_mode=image_mode)
+ elif self.export_format == "Plaintext":
+ content = doc.export_to_text()
+ elif self.export_format == "DocTags":
+ content = doc.export_to_doctags()
+ else:
+ content = ""
+
+ results.append(Data(text=content, data={"text": content, **base_meta}))
+
+ except Exception as e:
+ msg = f"Error exporting DoclingDocument: {e}"
+ raise TypeError(msg) from e
+
+ return results
+
+ def as_dataframe(self) -> DataFrame:
+ return DataFrame(self.export_document())
diff --git a/flows/ingestion_flow.json b/flows/ingestion_flow.json
index 2456116c4..8e18ae6ff 100644
--- a/flows/ingestion_flow.json
+++ b/flows/ingestion_flow.json
@@ -1138,7 +1138,7 @@
"show": true,
"title_case": false,
"type": "code",
- "value": "from typing import Any\n\nfrom docling_core.types.doc import ImageRefMode\n\nfrom lfx.base.data.docling_utils import extract_docling_documents\nfrom lfx.custom import Component\nfrom lfx.io import DropdownInput, HandleInput, MessageTextInput, Output, StrInput\nfrom lfx.schema import Data, DataFrame\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 betweek 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 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 = ImageRefMode(self.image_mode)\n for doc in documents:\n content = \"\"\n if self.export_format == \"Markdown\":\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 )\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\n # Preserve metadata from the 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\n results.append(Data(text=content, data={\"text\": content, **metadata}))\n except Exception as e:\n msg = f\"Error splitting text: {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": "from typing import Any\n\nfrom docling_core.types.doc import ImageRefMode\n\nfrom lfx.base.data.docling_utils import extract_docling_documents\nfrom lfx.custom import Component\nfrom lfx.io import DropdownInput, HandleInput, MessageTextInput, Output, StrInput\nfrom lfx.schema import Data, DataFrame\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 _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: ImageRefMode, 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 )\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 )\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 = ImageRefMode(self.image_mode)\n for doc in documents:\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 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 )\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 DoclingDocument: {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",
@@ -4968,7 +4968,7 @@
"id": "5488df7c-b93f-4f87-a446-b67028bc0813",
"is_component": false,
"last_tested_version": "0.9.6",
- "locked": false,
+ "locked": true,
"name": "OpenSearch Ingestion Flow",
"tags": [
"openai",
@@ -4976,4 +4976,4 @@
"rag",
"q-a"
]
-}
\ No newline at end of file
+}
diff --git a/frontend/app/chat/_components/function-calls/result.tsx b/frontend/app/chat/_components/function-calls/result.tsx
index 8d41c6bf6..958264e41 100644
--- a/frontend/app/chat/_components/function-calls/result.tsx
+++ b/frontend/app/chat/_components/function-calls/result.tsx
@@ -41,23 +41,25 @@ export function FunctionCallResult({ result }: FunctionCallResultProps) {
<div className="mt-1 space-y-2">
{items.map((item, idx) => (
<div key={idx} className="fc-result p-2 bg-muted/30 rounded">
- {item.data?.file_path && (
- <div className="font-medium text-blue-400 mb-1 text-xs">
- πŸ“„ {item.data.file_path || "Unknown file"}
- </div>
- )}
-
- {item.filename && !item.data?.file_path && (
- <div className="font-medium text-blue-400 mb-1 text-xs">
- πŸ“„ {item.filename}
- {item.page && ` (page ${item.page})`}
- {item.score && (
- <span className="ml-2 text-xs text-muted-foreground">
- Score: {item.score.toFixed(3)}
- </span>
- )}
- </div>
- )}
+ {(() => {
+ const displayFilename = item.data?.file_path || item.filename;
+ if (!displayFilename) return null;
+ return (
+ <div className="font-medium text-blue-400 mb-1 text-xs">
+ πŸ“„ {displayFilename}
+ {typeof item.page === "number" && item.page > 0 && (
+ <span className="ml-2 text-xs text-muted-foreground">
+ Page: {item.page}
+ </span>
+ )}
+ {item.score && (
+ <span className="ml-2 text-xs text-muted-foreground">
+ Score: {item.score.toFixed(3)}
+ </span>
+ )}
+ </div>
+ );
+ })()}
{item.data?.text && (
<div className="text-xs text-foreground whitespace-pre-wrap max-h-32 overflow-y-auto">
diff --git a/sdks/python/README.md b/sdks/python/README.md
index 664a81d6b..d3c0b11ad 100644
--- a/sdks/python/README.md
+++ b/sdks/python/README.md
@@ -72,7 +72,8 @@ async for event in await client.chat.create(message="Explain RAG", stream=True):
print(event.delta, end="", flush=True)
elif event.type == "sources":
for source in event.sources:
- print(f"\nSource: {source.filename}")
+ page_info = f" (page {source.page})" if source.page else ""
+ print(f"\nSource: {source.filename}{page_info}")
elif event.type == "done":
chat_id = event.chat_id
```
diff --git a/sdks/typescript/README.md b/sdks/typescript/README.md
index 9526ca923..6488d1f72 100644
--- a/sdks/typescript/README.md
+++ b/sdks/typescript/README.md
@@ -76,7 +76,8 @@ for await (const event of await client.chat.create({
process.stdout.write(event.delta);
} else if (event.type === "sources") {
for (const source of event.sources) {
- console.log(`\nSource: ${source.filename}`);
+ const pageInfo = source.page ? ` (page ${source.page})` : "";
+ console.log(`\nSource: ${source.filename}${pageInfo}`);
}
} else if (event.type === "done") {
chatId = event.chatId;