Skip to content

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

Python

feat: Add multi lang support for OCR (#2393)

Mike Fortman0696d363cdb0
diff --git a/frontend/app/api/mutations/useUpdateSettingsMutation.ts b/frontend/app/api/mutations/useUpdateSettingsMutation.ts
index 2c136274a..edfb749a5 100644
--- a/frontend/app/api/mutations/useUpdateSettingsMutation.ts
+++ b/frontend/app/api/mutations/useUpdateSettingsMutation.ts
@@ -18,6 +18,7 @@ export interface UpdateSettingsRequest {
chunk_overlap?: number;
table_structure?: boolean;
ocr?: boolean;
+ ocr_languages?: string[];
picture_descriptions?: boolean;
disable_ingest_with_langflow?: boolean;
embedding_model?: string;
diff --git a/frontend/app/api/queries/useGetSettingsQuery.ts b/frontend/app/api/queries/useGetSettingsQuery.ts
index 6600f33c9..462b9f6e2 100644
--- a/frontend/app/api/queries/useGetSettingsQuery.ts
+++ b/frontend/app/api/queries/useGetSettingsQuery.ts
@@ -19,6 +19,7 @@ export interface KnowledgeSettings {
chunk_overlap?: number;
table_structure?: boolean;
ocr?: boolean;
+ ocr_languages?: string[];
picture_descriptions?: boolean;
disable_ingest_with_langflow?: boolean;
vlm_enabled?: boolean;
diff --git a/frontend/app/settings/_components/ingest-settings-section.test.tsx b/frontend/app/settings/_components/ingest-settings-section.test.tsx
index 7bf10d04d..eee720a1d 100644
--- a/frontend/app/settings/_components/ingest-settings-section.test.tsx
+++ b/frontend/app/settings/_components/ingest-settings-section.test.tsx
@@ -10,6 +10,7 @@ import {
fireEvent,
renderWithProviders,
screen,
+ userEvent,
waitFor,
} from "@/test-utils/render";
@@ -374,3 +375,67 @@ describe("IngestSettingsSection", () => {
});
});
});
+
+describe("IngestSettingsSection OCR languages", () => {
+ it("shows English last when an existing selection was saved English-first", async () => {
+ renderWithProviders(<IngestSettingsSection />, {
+ providers: ["tooltip", "auth", "brand", "unsavedChanges"],
+ handlers: [
+ http.get("/api/settings", () =>
+ HttpResponse.json(
+ makeSettings({
+ knowledge: { ocr: true, ocr_languages: ["en", "ja"] },
+ }),
+ ),
+ ),
+ http.get("/api/models/catalog", () =>
+ HttpResponse.json({ providers: [] }),
+ ),
+ http.get("/api/models/providers", () => HttpResponse.json({})),
+ ],
+ });
+
+ await userEvent.click(
+ await screen.findByRole("button", { name: /advanced ocr settings/i }),
+ );
+ expect(await screen.findByText("Japanese, English")).toBeInTheDocument();
+ expect(
+ screen.getByRole("button", { name: /save ingest settings/i }),
+ ).toBeDisabled();
+ });
+
+ it("saves a newly added Japanese selection before English", async () => {
+ const save = vi.fn(() => HttpResponse.json({}));
+ renderWithProviders(<IngestSettingsSection />, {
+ providers: ["tooltip", "auth", "brand", "unsavedChanges"],
+ handlers: [
+ http.get("/api/settings", () =>
+ HttpResponse.json(
+ makeSettings({ knowledge: { ocr: true, ocr_languages: ["en"] } }),
+ ),
+ ),
+ http.get("/api/models/catalog", () =>
+ HttpResponse.json({ providers: [] }),
+ ),
+ http.get("/api/models/providers", () => HttpResponse.json({})),
+ http.post("/api/settings", async ({ request }) => {
+ const body = await request.json();
+ expect(body).toMatchObject({ ocr_languages: ["ja", "en"] });
+ return save();
+ }),
+ ],
+ });
+
+ await userEvent.click(
+ await screen.findByRole("button", { name: /advanced ocr settings/i }),
+ );
+ await userEvent.click(await screen.findByText("English"));
+ await userEvent.click(await screen.findByText("Japanese"));
+ expect(await screen.findByText("Japanese, English")).toBeInTheDocument();
+
+ await userEvent.click(
+ screen.getByRole("button", { name: /save ingest settings/i }),
+ );
+ expect(save).toHaveBeenCalledOnce();
+ });
+});
diff --git a/frontend/app/settings/_components/ingest-settings-section.tsx b/frontend/app/settings/_components/ingest-settings-section.tsx
index 84799571c..a46313dc3 100644
--- a/frontend/app/settings/_components/ingest-settings-section.tsx
+++ b/frontend/app/settings/_components/ingest-settings-section.tsx
@@ -45,6 +45,7 @@ import {
import { Input } from "@/components/ui/input";
import { NumberInput } from "@/components/ui/inputs/number-input";
import { Label } from "@/components/ui/label";
+import { MultiSelect } from "@/components/ui/multi-select";
import {
Select,
SelectContent,
@@ -58,7 +59,11 @@ import { useAuth } from "@/contexts/auth-context";
import { useIsCloudBrand } from "@/contexts/brand-context";
import { useRegisterDirty } from "@/contexts/unsaved-changes-context";
import { trackButton } from "@/lib/analytics";
-import { DEFAULT_KNOWLEDGE_SETTINGS } from "@/lib/constants";
+import {
+ DEFAULT_KNOWLEDGE_SETTINGS,
+ OCR_LANGUAGE_OPTIONS,
+} from "@/lib/constants";
+import { allowedLanguages, englishLast } from "@/lib/ocr-languages";
import { resolveLangflowEditUrl } from "@/lib/url-utils";
import { cn } from "@/lib/utils";
import { useUpdateSettingsMutation } from "../../api/mutations/useUpdateSettingsMutation";
@@ -87,6 +92,9 @@ export function IngestSettingsSection() {
});
const [tableStructure, setTableStructure] = useState<boolean>(true);
const [ocr, setOcr] = useState<boolean>(false);
+ const [ocrLanguages, setOcrLanguages] = useState<string[]>([
+ ...DEFAULT_KNOWLEDGE_SETTINGS.ocr_languages,
+ ]);
const [pictureDescriptions, setPictureDescriptions] =
useState<boolean>(false);
const [disableIngestWithLangflow, setDisableIngestWithLangflow] =
@@ -342,6 +350,8 @@ export function IngestSettingsSection() {
if (k.chunk_overlap !== undefined) setChunkOverlap(k.chunk_overlap);
if (k.table_structure !== undefined) setTableStructure(k.table_structure);
if (k.ocr !== undefined) setOcr(k.ocr);
+ if (k.ocr_languages !== undefined && k.ocr_languages.length > 0)
+ setOcrLanguages(englishLast(k.ocr_languages));
if (k.picture_descriptions !== undefined)
setPictureDescriptions(k.picture_descriptions);
if (k.disable_ingest_with_langflow !== undefined)
@@ -364,6 +374,7 @@ export function IngestSettingsSection() {
}, [settings.knowledge]);
const [vlmOpen, setVlmOpen] = useState(false);
+ const [ocrOpen, setOcrOpen] = useState(false);
const autoSelectedVlm = useRef(false);
useEffect(() => {
@@ -436,11 +447,26 @@ export function IngestSettingsSection() {
vlmWatsonxApiVersion !==
(k?.vlm_watsonx_api_version ?? vlmWatsonxApiVersion));
+ // easyocr loads one recognition model per job, so a selection that mixes
+ // scripts fails at ingest time on Linux even though it works on a macOS host.
+ // Disable the incompatible rows rather than hide them, so the reason is visible.
+ const ocrLanguageOptions = useMemo(() => {
+ const allowed = new Set(allowedLanguages(ocrLanguages));
+ return OCR_LANGUAGE_OPTIONS.map((option) => ({
+ value: option.value,
+ label: option.label,
+ disabled: !allowed.has(option.value),
+ hint: allowed.has(option.value) ? undefined : "not combinable",
+ }));
+ }, [ocrLanguages]);
+
const knowledgeIngestDirty =
chunkSize !== (k?.chunk_size ?? chunkSize) ||
chunkOverlap !== (k?.chunk_overlap ?? chunkOverlap) ||
tableStructure !== (k?.table_structure ?? tableStructure) ||
ocr !== (k?.ocr ?? ocr) ||
+ ocrLanguages.join(",") !==
+ englishLast(k?.ocr_languages ?? ocrLanguages).join(",") ||
pictureDescriptions !== (k?.picture_descriptions ?? pictureDescriptions) ||
disableIngestWithLangflow !==
(k?.disable_ingest_with_langflow ?? disableIngestWithLangflow) ||
@@ -511,6 +537,7 @@ export function IngestSettingsSection() {
chunk_overlap: chunkOverlap,
table_structure: tableStructure,
ocr,
+ ocr_languages: ocrLanguages,
picture_descriptions: pictureDescriptions,
disable_ingest_with_langflow: disableIngestWithLangflow,
...vlmPayload,
@@ -546,6 +573,7 @@ export function IngestSettingsSection() {
chunk_overlap: chunkOverlap,
table_structure: tableStructure,
ocr,
+ ocr_languages: ocrLanguages,
picture_descriptions: pictureDescriptions,
disable_ingest_with_langflow: disableIngestWithLangflow,
...vlmPayload,
@@ -604,6 +632,7 @@ export function IngestSettingsSection() {
setChunkOverlap(DEFAULT_KNOWLEDGE_SETTINGS.chunk_overlap);
setTableStructure(DEFAULT_KNOWLEDGE_SETTINGS.table_structure);
setOcr(DEFAULT_KNOWLEDGE_SETTINGS.ocr);
+ setOcrLanguages([...DEFAULT_KNOWLEDGE_SETTINGS.ocr_languages]);
setPictureDescriptions(DEFAULT_KNOWLEDGE_SETTINGS.picture_descriptions);
setDisableIngestWithLangflow(false);
setUserEdited(false);
@@ -884,26 +913,81 @@ export function IngestSettingsSection() {
}}
/>
</div>
- <div className="flex items-center justify-between py-3 border-b border-border">
- <div className="flex-1">
- <Label
- htmlFor="ocr"
- className="text-base font-medium cursor-pointer pb-3"
- >
- OCR
- </Label>
- <div className="text-sm text-muted-foreground">
- Extracts text from images/PDFs. Ingest is slower when enabled.
+ <div className="border-b border-border">
+ <div className="flex items-center justify-between py-3">
+ <div className="flex-1">
+ <Label
+ htmlFor="ocr"
+ className="text-base font-medium cursor-pointer pb-3"
+ >
+ OCR
+ </Label>
+ <div className="text-sm text-muted-foreground">
+ Extracts text from images/PDFs. Ingest is slower when
+ enabled.
+ </div>
</div>
+ <Switch
+ id="ocr"
+ checked={ocr}
+ onCheckedChange={(v) => {
+ setUserEdited(true);
+ setOcr(v);
+ }}
+ />
</div>
- <Switch
- id="ocr"
- checked={ocr}
- onCheckedChange={(v) => {
- setUserEdited(true);
- setOcr(v);
- }}
- />
+ <Collapsible
+ open={ocrOpen}
+ onOpenChange={setOcrOpen}
+ className={cn(
+ "pl-4 pb-3 transition-all duration-200",
+ !ocr && "opacity-50",
+ )}
+ >
+ <CollapsibleTrigger className="flex w-full items-center justify-between py-2 text-sm font-medium text-foreground hover:text-foreground/80">
+ Advanced OCR Settings
+ <ChevronDown
+ className={cn(
+ "h-4 w-4 mr-4 text-muted-foreground transition-transform duration-200",
+ ocrOpen && "rotate-180",
+ )}
+ />
+ </CollapsibleTrigger>
+ <CollapsibleContent className="pt-4 space-y-6">
+ <div className="space-y-2">
+ <LabelWrapper
+ id="ocr-languages"
+ label="OCR languages"
+ helperText="Languages are prioritized in this order; English stays last when combined with others"
+ disabled={!ocr}
+ flex
+ >
+ <MultiSelect
+ options={ocrLanguageOptions}
+ value={ocrLanguages}
+ onValueChange={(v) => {
+ setUserEdited(true);
+ // An empty selection would make docling fall back to its
+ // English-only default without saying so; keep English.
+ setOcrLanguages(
+ englishLast(v.length > 0 ? v : ["en"]),
+ );
+ }}
+ showAllOption={false}
+ placeholder="Select languages..."
+ searchPlaceholder="Search languages..."
+ className="w-64"
+ inlineLabelLimit={2}
+ disabled={!ocr}
+ />
+ </LabelWrapper>
+ <p className="text-sm text-muted-foreground">
+ Most languages can only be combined with English, so
+ incompatible options are disabled once you choose one.
+ </p>
+ </div>
+ </CollapsibleContent>
+ </Collapsible>
</div>
<div className="flex items-center justify-between py-3">
<div className="flex-1">
@@ -933,7 +1017,7 @@ export function IngestSettingsSection() {
open={vlmOpen}
onOpenChange={setVlmOpen}
className={cn(
- "mt-4 px-4 transition-all duration-200",
+ "mt-4 pl-4 transition-all duration-200",
!pictureDescriptions && "opacity-50",
)}
>
@@ -941,7 +1025,7 @@ export function IngestSettingsSection() {
Advanced Vision Model (VLM) Settings
<ChevronDown
className={cn(
- "h-4 w-4 text-muted-foreground transition-transform duration-200",
+ "h-4 w-4 mr-4 text-muted-foreground transition-transform duration-200",
vlmOpen && "rotate-180",
)}
/>
diff --git a/frontend/components/ui/multi-select.tsx b/frontend/components/ui/multi-select.tsx
index 0d51bdcc5..6b1d77528 100644
--- a/frontend/components/ui/multi-select.tsx
+++ b/frontend/components/ui/multi-select.tsx
@@ -22,6 +22,10 @@ interface Option {
value: string;
label: string;
count?: number;
+ /** Renders the row unselectable. Selecting it is a no-op. */
+ disabled?: boolean;
+ /** Short reason shown beside a disabled row, e.g. why it is unavailable. */
+ hint?: string;
}
interface MultiSelectProps {
@@ -34,6 +38,12 @@ interface MultiSelectProps {
searchPlaceholder?: string;
showAllOption?: boolean;
allOptionLabel?: string;
+ disabled?: boolean;
+ /**
+ * Name the selected options on the trigger while at most this many are
+ * chosen, instead of showing a bare count. 0 always shows the count.
+ */
+ inlineLabelLimit?: number;
}
export function MultiSelect({
@@ -46,6 +56,8 @@ export function MultiSelect({
searchPlaceholder = "Search options...",
showAllOption = true,
allOptionLabel = "All",
+ disabled = false,
+ inlineLabelLimit = 0,
}: MultiSelectProps) {
const [open, setOpen] = React.useState(false);
const [searchValue, setSearchValue] = React.useState("");
@@ -61,6 +73,9 @@ export function MultiSelect({
);
const handleSelect = (optionValue: string) => {
+ if (options.find((option) => option.value === optionValue)?.disabled) {
+ return;
+ }
if (optionValue === "*") {
// Toggle "All" selection
if (isAllSelected) {
@@ -95,6 +110,18 @@ export function MultiSelect({
return placeholder;
}
+ // A short selection reads better named than counted: "English, Japanese"
+ // says what OCR will run, "2 languages" makes you open the dropdown.
+ if (safeValue.length <= inlineLabelLimit) {
+ return safeValue
+ .map(
+ (selected) =>
+ options.find((option) => option.value === selected)?.label ??
+ selected,
+ )
+ .join(", ");
+ }
+
// Extract the noun from placeholder (e.g., "Select data sources..." -> "data sources")
const noun = placeholder
.toLowerCase()
@@ -109,6 +136,7 @@ export function MultiSelect({
<Button
variant="outline"
role="combobox"
+ disabled={disabled}
aria-expanded={open}
aria-controls={listboxId}
className={cn("w-full justify-between h-8 py-0 text-left", className)}
@@ -152,11 +180,22 @@ export function MultiSelect({
<CommandItem
key={option.value}
onSelect={() => handleSelect(option.value)}
- className="cursor-pointer"
+ disabled={option.disabled}
+ aria-disabled={option.disabled}
+ className={cn(
+ option.disabled
+ ? "cursor-not-allowed opacity-50"
+ : "cursor-pointer",
+ )}
>
<span className="flex-1 truncate min-w-0">
{option.label}
</span>
+ {option.hint && (
+ <span className="text-xs text-muted-foreground ml-2 shrink-0">
+ {option.hint}
+ </span>
+ )}
{option.count !== undefined && (
<span className="text-xs text-muted-foreground bg-muted/50 px-1.5 py-0.5 rounded ml-2">
{option.count}
diff --git a/frontend/lib/constants.ts b/frontend/lib/constants.ts
index 1cb4a3a2a..faabc6bd4 100644
--- a/frontend/lib/constants.ts
+++ b/frontend/lib/constants.ts
@@ -23,9 +23,34 @@ export const DEFAULT_KNOWLEDGE_SETTINGS = {
chunk_overlap: 200,
table_structure: true,
ocr: false,
+ ocr_languages: ["en"] as string[],
picture_descriptions: false,
} as const;
+/**
+ * OCR languages OpenRAG can request. The codes are engine-neutral; the backend
+ * translates them to whichever OCR engine the host runs (ocrmac on macOS,
+ * easyocr elsewhere). Leaving this at English only means non-Latin text is
+ * silently skipped during ingest.
+ */
+export const OCR_LANGUAGE_OPTIONS = [
+ { value: "en", label: "English" },
+ { value: "ja", label: "Japanese" },
+ { value: "ko", label: "Korean" },
+ { value: "zh-Hans", label: "Chinese (Simplified)" },
+ { value: "zh-Hant", label: "Chinese (Traditional)" },
+ { value: "fr", label: "French" },
+ { value: "de", label: "German" },
+ { value: "es", label: "Spanish" },
+ { value: "it", label: "Italian" },
+ { value: "pt", label: "Portuguese" },
+ { value: "ru", label: "Russian" },
+ { value: "uk", label: "Ukrainian" },
+ { value: "th", label: "Thai" },
+ { value: "vi", label: "Vietnamese" },
+ { value: "ar", label: "Arabic" },
+] as const;
+
/**
* UI Constants
*/
diff --git a/frontend/lib/ocr-languages.test.ts b/frontend/lib/ocr-languages.test.ts
new file mode 100644
index 000000000..d3b3de951
--- /dev/null
+++ b/frontend/lib/ocr-languages.test.ts
@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+import {
+ allowedLanguages,
+ englishLast,
+ isSelectionValid,
+} from "@/lib/ocr-languages";
+
+describe("englishLast", () => {
+ it("moves the default English selection behind a newly chosen language", () => {
+ expect(englishLast(["en", "ja"])).toEqual(["ja", "en"]);
+ });
+
+ it("preserves the relative priority of other languages", () => {
+ expect(englishLast(["en", "ru", "uk"])).toEqual(["ru", "uk", "en"]);
+ });
+
+ it("leaves English-only and non-English selections unchanged", () => {
+ expect(englishLast(["en"])).toEqual(["en"]);
+ expect(englishLast(["ja"])).toEqual(["ja"]);
+ });
+});
+
+describe("allowedLanguages", () => {
+ it("allows every curated language when nothing is selected", () => {
+ expect(allowedLanguages([])).toEqual(
+ expect.arrayContaining(["en", "ja", "ru", "fr", "ar"]),
+ );
+ });
+
+ it("allows every curated language when only English is selected", () => {
+ // English is universal, so it must never narrow the choices.
+ expect(allowedLanguages(["en"])).toEqual(
+ expect.arrayContaining(["ja", "ru", "fr", "ar", "th"]),
+ );
+ });
+
+ it("narrows to English once a restricted language is selected", () => {
+ // easyocr loads one recognition model per job: Japanese pairs only with English.
+ expect(allowedLanguages(["ja"]).sort()).toEqual(["en", "ja"]);
+ });
+
+ it("keeps the rest of the family available for Cyrillic", () => {
+ expect(allowedLanguages(["ru"]).sort()).toEqual(["en", "ru", "uk"]);
+ });
+
+ it("allows Latin languages to combine freely", () => {
+ expect(allowedLanguages(["fr", "de"]).sort()).toEqual([
+ "de",
+ "en",
+ "es",
+ "fr",
+ "it",
+ "pt",
+ "vi",
+ ]);
+ });
+
+ it("does not offer Latin languages alongside Cyrillic", () => {
+ expect(allowedLanguages(["uk"])).not.toContain("fr");
+ });
+
+ it("treats an unknown pass-through code as unconstrained", () => {
+ // Operators may type raw engine codes; the picker must not reason about them.
+ expect(allowedLanguages(["hi"])).toEqual(
+ expect.arrayContaining(["ja", "fr", "ru"]),
+ );
+ });
+});
+
+describe("isSelectionValid", () => {
+ it("accepts a single family plus English", () => {
+ expect(isSelectionValid(["en", "ja"])).toBe(true);
+ expect(isSelectionValid(["ru", "uk", "en"])).toBe(true);
+ expect(isSelectionValid(["fr", "de", "pt"])).toBe(true);
+ });
+
+ it("rejects two restricted languages", () => {
+ expect(isSelectionValid(["ja", "ko"])).toBe(false);
+ });
+
+ it("rejects mixing scripts", () => {
+ expect(isSelectionValid(["ru", "fr"])).toBe(false);
+ });
+
+ it("accepts English alone", () => {
+ expect(isSelectionValid(["en"])).toBe(true);
+ });
+});
diff --git a/frontend/lib/ocr-languages.ts b/frontend/lib/ocr-languages.ts
new file mode 100644
index 000000000..197867489
--- /dev/null
+++ b/frontend/lib/ocr-languages.ts
@@ -0,0 +1,81 @@
+/**
+ * OCR language compatibility rules.
+ *
+ * easyocr loads a single recognition model per job and rejects any language
+ * outside it — `lang_list=["ja","ko"]` raises "Japanese is only compatible with
+ * English". ocrmac (Apple Vision) has no such constraint, but OpenRAG picks the
+ * engine from the host OS, so a selection made on a macOS dev machine has to
+ * stay valid in a Linux container. We therefore apply easyocr's stricter rules
+ * everywhere.
+ *
+ * The rule: all selected non-English languages must belong to one family.
+ * English is universal and combines with anything.
+ */
+
+/** Language that pairs with any other, on every engine. */
+const UNIVERSAL = "en";
+
+/**
+ * Curated languages grouped by the recognition model that serves them.
+ * Mirrors easyocr's model selection (easyocr/easyocr.py) restricted to the
+ * languages ocrmac also supports.
+ */
+export const OCR_LANGUAGE_FAMILIES: Record<string, readonly string[]> = {
+ latin: ["fr", "de", "es", "it", "pt", "vi"],
+ cyrillic: ["ru", "uk"],
+ arabic: ["ar"],
+ japanese: ["ja"],
+ korean: ["ko"],
+ chinese_simplified: ["zh-Hans"],
+ chinese_traditional: ["zh-Hant"],
+ thai: ["th"],
+};
+
+const CURATED = [UNIVERSAL, ...Object.values(OCR_LANGUAGE_FAMILIES).flat()];
+
+/** Keep English as the fallback when another OCR language is selected. */
+export function englishLast(languages: string[]): string[] {
+ const prioritized = languages.filter((language) => language !== UNIVERSAL);
+ if (languages.includes(UNIVERSAL)) prioritized.push(UNIVERSAL);
+ return prioritized;
+}
+
+function familyOf(language: string): string | undefined {
+ return Object.keys(OCR_LANGUAGE_FAMILIES).find((family) =>
+ OCR_LANGUAGE_FAMILIES[family].includes(language),
+ );
+}
+
+/**
+ * Families represented in a selection, ignoring English and any raw engine code
+ * the picker does not know about. Pass-through codes are deliberately not
+ * constrained: an operator typing `hi` knows which engine they are targeting.
+ */
+function familiesIn(selected: string[]): string[] {
+ const families = selected
+ .filter((language) => language !== UNIVERSAL)
+ .map(familyOf)
+ .filter((family): family is string => family !== undefined);
+ return [...new Set(families)];
+}
+
+/**
+ * Languages that may still be chosen given the current selection. Always
+ * includes what is already selected, so a selection never renders as invalid
+ * against its own options.
+ */
+export function allowedLanguages(selected: string[]): string[] {
+ const families = familiesIn(selected);
+ if (families.length === 0) return [...CURATED];
+
+ const allowed = new Set([UNIVERSAL, ...selected]);
+ for (const family of families) {
+ for (const language of OCR_LANGUAGE_FAMILIES[family]) allowed.add(language);
+ }
+ return [...allowed];
+}
+
+/** True when the selection draws its non-English languages from one family. */
+export function isSelectionValid(selected: string[]): boolean {
+ return familiesIn(selected).length <= 1;
+}
diff --git a/src/api/settings/endpoints.py b/src/api/settings/endpoints.py
index 67803c511..2cd99dc3f 100644
--- a/src/api/settings/endpoints.py
+++ b/src/api/settings/endpoints.py
@@ -351,6 +351,7 @@ async def get_settings(
chunk_overlap=knowledge_config.chunk_overlap,
table_structure=knowledge_config.table_structure,
ocr=knowledge_config.ocr,
+ ocr_languages=knowledge_config.ocr_languages,
picture_descriptions=knowledge_config.picture_descriptions,
index_name=knowledge_config.index_name,
disable_ingest_with_langflow=knowledge_config.disable_ingest_with_langflow,
@@ -733,6 +734,20 @@ async def update_settings(
except Exception as e:
logger.error(f"Failed to update docling settings in flow: {str(e)}")
+ if body.ocr_languages is not None:
+ working_config.knowledge.ocr_languages = body.ocr_languages
+ config_updated = True
+ await TelemetryClient.send_event(
+ Category.SETTINGS_OPERATIONS, MessageId.ORB_SETTINGS_DOCLING_UPDATED
+ )
+
+ # Also update the flow with the new docling settings
+ try:
+ flows_service = _get_flows_service()
+ await _update_langflow_docling_settings(working_config, flows_service)
+ except Exception as e:
+ logger.error(f"Failed to update docling settings in flow: {str(e)}")
+
if body.picture_descriptions is not None:
working_config.knowledge.picture_descriptions = body.picture_descriptions
config_updated = True
@@ -1995,8 +2010,13 @@ async def update_docling_preset(
),
}
- # Get the preset configuration
- preset_config_dict = get_docling_preset_configs(**settings_toggles)
+ # Get the preset configuration. OCR languages are not part of this legacy
+ # preset API, so carry the configured ones through rather than dropping
+ # them from the flow's docling options.
+ preset_config_dict = get_docling_preset_configs(
+ **settings_toggles,
+ ocr_languages=get_openrag_config().knowledge.ocr_languages,
+ )
preset_config = DoclingConfig(**preset_config_dict)
# Use the helper function to update the flow
diff --git a/src/api/settings/langflow_sync.py b/src/api/settings/langflow_sync.py
index 1bea2b3ab..91dec1b29 100644
--- a/src/api/settings/langflow_sync.py
+++ b/src/api/settings/langflow_sync.py
@@ -518,6 +518,7 @@ async def _update_langflow_docling_settings(config, flows_service):
table_structure=config.knowledge.table_structure,
ocr=config.knowledge.ocr,
picture_descriptions=config.knowledge.picture_descriptions,
+ ocr_languages=config.knowledge.ocr_languages,
)
await flows_service.update_flow_docling_preset("custom", preset_config)
logger.info("Successfully updated docling settings in ingest flow")
diff --git a/src/api/settings/models.py b/src/api/settings/models.py
index 8a61cc9e1..07caff86c 100644
--- a/src/api/settings/models.py
+++ b/src/api/settings/models.py
@@ -11,6 +11,26 @@ from pydantic import BaseModel, Field, field_validator
from services.docling_service import DoclingConfig
+# OCR languages grouped by the recognition model that serves them. English is
+# universal and therefore absent: it combines with every family. Mirrors
+# frontend/lib/ocr-languages.ts.
+OCR_LANGUAGE_FAMILIES = {
+ "fr": "latin",
+ "de": "latin",
+ "es": "latin",
+ "it": "latin",
+ "pt": "latin",
+ "vi": "latin",
+ "ru": "cyrillic",
+ "uk": "cyrillic",
+ "ar": "arabic",
+ "ja": "japanese",
+ "ko": "korean",
+ "zh-Hans": "chinese_simplified",
+ "zh-Hant": "chinese_traditional",
+ "th": "thai",
+}
+
class SettingsUpdateBody(BaseModel):
llm_model: str | None = Field(None, min_length=1)
@@ -20,6 +40,7 @@ class SettingsUpdateBody(BaseModel):
chunk_overlap: int | None = Field(None, ge=0)
table_structure: bool | None = None
ocr: bool | None = None
+ ocr_languages: list[str] | None = None
picture_descriptions: bool | None = None
disable_ingest_with_langflow: bool | None = None
vlm_enabled: bool | None = None
@@ -59,6 +80,44 @@ class SettingsUpdateBody(BaseModel):
# the backend returns 409 and the frontend prompts the user.
force_remove: bool | None = False
+ @field_validator("ocr_languages")
+ @classmethod
+ def _validate_ocr_languages(cls, value: list[str] | None) -> list[str] | None:
+ """Reject blank entries and combinations no OCR engine can serve.
+
+ An empty list is accepted and clears the override: no ocr_lang is sent
+ to docling, so the engine default applies.
+
+ Mirrors the picker's rules (frontend/lib/ocr-languages.ts) so the API
+ cannot be driven into a state the UI prevents. Duplicated on purpose:
+ the two run in different languages and are tested independently.
+ """
+ if value is None:
+ return None
+ if not value:
+ return []
+ cleaned = [language.strip() for language in value]
+ if any(not language for language in cleaned):
+ raise ValueError("ocr_languages must not contain blank entries")
+
+ # easyocr loads a single recognition model per job and rejects anything
+ # outside it. Unknown codes are the operator's pass-through escape
+ # hatch and are deliberately not constrained.
+ families = {
+ OCR_LANGUAGE_FAMILIES[language]
+ for language in cleaned
+ if language in OCR_LANGUAGE_FAMILIES
+ }
+ if len(families) > 1:
+ raise ValueError(
+ "ocr_languages mixes scripts that no single OCR model can serve "
+ f"({', '.join(sorted(families))}); combine one script with English"
+ )
+ # Keep English last in the persisted list, matching OCR priority on macOS.
+ return [language for language in cleaned if language != "en"] + (
+ ["en"] if "en" in cleaned else []
+ )
+
class OnboardingBody(BaseModel):
llm_provider: str | None = Field(None, min_length=1)
@@ -203,6 +262,7 @@ class KnowledgeConfig(BaseModel):
chunk_overlap: int | None
table_structure: bool | None
ocr: bool | None
+ ocr_languages: list[str] | None = None
picture_descriptions: bool | None
index_name: str | None
disable_ingest_with_langflow: bool | None
diff --git a/src/config/config_manager.py b/src/config/config_manager.py
index b2d565c3d..3259a475b 100644
--- a/src/config/config_manager.py
+++ b/src/config/config_manager.py
@@ -476,6 +476,10 @@ class KnowledgeConfig:
chunk_overlap: int = 200
table_structure: bool = True
ocr: bool = False
+ # Neutral OCR language codes (ISO 639-1, plus zh-Hans/zh-Hant), translated to
+ # engine-specific codes in services.docling_service. Empty means "engine
+ # default", which is English-only on macOS.
+ ocr_languages: list[str] = field(default_factory=lambda: ["en"])
picture_descriptions: bool = False
index_name: str = "documents" # OpenSearch index name
disable_ingest_with_langflow: bool = False
diff --git a/src/services/docling_service.py b/src/services/docling_service.py
index fd2106b07..bdf89a0ec 100644
--- a/src/services/docling_service.py
+++ b/src/services/docling_service.py
@@ -8,7 +8,7 @@ from typing import Any
from urllib.parse import urlparse
import httpx
-from pydantic import BaseModel
+from pydantic import BaseModel, computed_field
from config.settings import (
DOCLING_ERROR_DETAIL_MAX_LENGTH,
@@ -24,12 +24,26 @@ logger = get_logger(__name__)
class DoclingConfig(BaseModel):
+ """Only used to shape the legacy /settings/docling-preset response.
+
+ The actual Docling Serve request payload is built from a plain dict
+ (see get_docling_preset_configs), so this model doesn't need to match
+ Docling Serve's field names.
+ """
+
do_ocr: bool
- ocr_engine: str
+ ocr_preset: str
+ ocr_lang: list[str] | None = None
do_table_structure: bool
do_picture_classification: bool
do_picture_description: bool
+ @computed_field # type: ignore[prop-decorator]
+ @property
+ def ocr_engine(self) -> str:
+ """Deprecated alias for ocr_preset, kept for legacy API callers."""
+ return self.ocr_preset
+
class DoclingServeError(Exception):
"""Raised when docling-serve conversion fails."""
@@ -58,20 +72,82 @@ class DoclingStatusSnapshot:
raw: dict | None = None
+# OCR language codes are engine-specific: ocrmac (Apple Vision) takes BCP-47
+# tags, easyocr takes its own short codes. OpenRAG stores neutral codes in
+# KnowledgeConfig so one config survives moving between a macOS host and a
+# Linux container, and they are translated per engine at request time.
+OCR_LANGUAGE_CODES: dict[str, dict[str, str]] = {
+ "ocrmac": {
+ "en": "en-US",
+ "ja": "ja-JP",
+ "ko": "ko-KR",
+ "zh-Hans": "zh-Hans",
+ "zh-Hant": "zh-Hant",
+ "fr": "fr-FR",
+ "de": "de-DE",
+ "es": "es-ES",
+ "it": "it-IT",
+ "pt": "pt-BR",
+ "ru": "ru-RU",
+ "uk": "uk-UA",
+ "th": "th-TH",
+ "vi": "vi-VN",
+ "ar": "ar-SA",
+ },
+ "easyocr": {
+ "en": "en",
+ "ja": "ja",
+ "ko": "ko",
+ "zh-Hans": "ch_sim",
+ "zh-Hant": "ch_tra",
+ "fr": "fr",
+ "de": "de",
+ "es": "es",
+ "it": "it",
+ "pt": "pt",
+ "ru": "ru",
+ "uk": "uk",
+ "th": "th",
+ "vi": "vi",
+ "ar": "ar",
+ },
+}
+
+
+def resolve_ocr_languages(engine: str, languages: list[str]) -> list[str]:
+ """Translate OpenRAG's neutral OCR language codes into engine-specific ones.
+
+ Unrecognized codes pass through untouched so an operator can name an engine
+ code OpenRAG does not know about rather than have it silently dropped.
+ """
+ mapping = OCR_LANGUAGE_CODES.get(engine, {})
+ # Apple Vision treats earlier languages as higher priority. Keep English as
+ # the fallback so adding another language does not suppress its script.
+ prioritized = [language for language in languages if language != "en"]
+ if "en" in languages:
+ prioritized.append("en")
+ return [mapping.get(language, language) for language in prioritized]
+
+
def get_docling_preset_configs(
- table_structure=False, ocr=False, picture_descriptions=False
+ table_structure=False, ocr=False, picture_descriptions=False, ocr_languages=None
) -> dict[str, Any]:
"""Get docling preset configurations based on toggle settings"""
is_macos = platform.system() == "Darwin"
+ engine = "ocrmac" if is_macos else "easyocr"
config = {
"do_ocr": ocr,
- "ocr_engine": "ocrmac" if is_macos else "easyocr",
+ # ocr_preset is the supported replacement for deprecated ocr_engine.
+ "ocr_preset": engine,
"do_table_structure": table_structure,
"do_picture_classification": picture_descriptions,
"do_picture_description": picture_descriptions,
}
+ if ocr_languages:
+ config["ocr_lang"] = resolve_ocr_languages(engine, ocr_languages)
+
return config
@@ -218,6 +294,7 @@ class DoclingService:
table_structure=knowledge_config.table_structure,
ocr=is_ocr_enabled,
picture_descriptions=is_pic_desc_enabled,
+ ocr_languages=knowledge_config.ocr_languages,
)
image_export_mode = "embedded" if preview_mode else "placeholder"
diff --git a/tests/unit/api/test_settings_endpoints.py b/tests/unit/api/test_settings_endpoints.py
index c375fe5f7..95a9f107a 100644
--- a/tests/unit/api/test_settings_endpoints.py
+++ b/tests/unit/api/test_settings_endpoints.py
@@ -408,6 +408,52 @@ def test_settings_update_body_rejects_malformed_vlm_provider(provider):
SettingsUpdateBody(vlm_provider=provider)
+def test_settings_body_accepts_ocr_languages():
+ """OCR languages are settable through the settings API."""
+ body = SettingsUpdateBody(ocr_languages=["en", "ja"])
+
+ assert body.ocr_languages == ["ja", "en"]
+
+
+def test_settings_body_rejects_blank_ocr_language():
+ """A blank code would be forwarded to docling and silently break OCR."""
+ with pytest.raises(ValidationError):
+ SettingsUpdateBody(ocr_languages=["en", " "])
+
+
+def test_settings_body_accepts_empty_ocr_language_list():
+ """An empty list clears the override so docling uses the engine default."""
+ assert SettingsUpdateBody(ocr_languages=[]).ocr_languages == []
+
+
+def test_settings_body_accepts_one_family_plus_english():
+ """A selection drawn from a single recognition-model family is valid."""
+ assert SettingsUpdateBody(ocr_languages=["en", "ja"]).ocr_languages == ["ja", "en"]
+ assert SettingsUpdateBody(ocr_languages=["ru", "uk"]).ocr_languages == ["ru", "uk"]
+ assert SettingsUpdateBody(ocr_languages=["fr", "de", "pt"]).ocr_languages == [
+ "fr",
+ "de",
+ "pt",
+ ]
+
+
+def test_settings_body_rejects_two_restricted_ocr_languages():
+ """easyocr cannot serve Japanese and Korean from one recognition model."""
+ with pytest.raises(ValidationError):
+ SettingsUpdateBody(ocr_languages=["ja", "ko"])
+
+
+def test_settings_body_rejects_mixed_scripts():
+ """Cyrillic and Latin need different easyocr models."""
+ with pytest.raises(ValidationError):
+ SettingsUpdateBody(ocr_languages=["ru", "fr"])
+
+
+def test_settings_body_allows_unknown_passthrough_codes():
+ """Raw engine codes are the operator's escape hatch; do not second-guess them."""
+ assert SettingsUpdateBody(ocr_languages=["hi", "mr"]).ocr_languages == ["hi", "mr"]
+
+
@pytest.mark.asyncio
async def test_update_settings_persists_case_insensitive_removal_only_request():
from api.settings.endpoints import update_settings
diff --git a/tests/unit/api/test_settings_ocr_languages.py b/tests/unit/api/test_settings_ocr_languages.py
new file mode 100644
index 000000000..15e0634e2
--- /dev/null
+++ b/tests/unit/api/test_settings_ocr_languages.py
@@ -0,0 +1,70 @@
+"""OCR language settings round-trip through the settings endpoint."""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from api.settings.endpoints import update_settings
+from api.settings.models import SettingsUpdateBody
+from config.config_manager import OpenRAGConfig
+
+
+def _edited_config() -> OpenRAGConfig:
+ config = OpenRAGConfig.from_dict({})
+ config.edited = True
+ return config
+
+
+async def test_update_settings_persists_ocr_languages():
+ """Saving OCR languages stores them on the knowledge config."""
+ current = _edited_config()
+ saved = {}
+
+ def capture(config):
+ saved["config"] = config
+ return True
+
+ with (
+ patch("api.settings.endpoints.get_openrag_config", return_value=current),
+ patch("api.settings.endpoints.config_manager.save_config_file", side_effect=capture),
+ patch("api.settings.endpoints._get_flows_service", return_value=MagicMock()),
+ patch("api.settings.endpoints._update_langflow_docling_settings", new=AsyncMock()),
+ patch("api.settings.endpoints.TelemetryClient.send_event", new=AsyncMock()),
+ patch("api.settings.endpoints.provider_health_cache", MagicMock()),
+ ):
+ await update_settings(
+ body=SettingsUpdateBody(ocr_languages=["en", "ja"]),
+ session_manager=AsyncMock(),
+ user=MagicMock(),
+ models_service=MagicMock(),
+ rbac=MagicMock(),
+ )
+
+ assert saved["config"].knowledge.ocr_languages == ["ja", "en"]
+
+
+async def test_docling_preset_endpoint_keeps_configured_ocr_languages():
+ """The legacy preset endpoint must not wipe OCR languages from the ingest flow."""
+ from api.settings import DoclingPresetBody, update_docling_preset
+
+ current = _edited_config()
+ current.knowledge.ocr_languages = ["en", "ja"]
+
+ flows_service = MagicMock()
+ flows_service.update_flow_docling_preset = AsyncMock()
+
+ with (
+ patch("api.settings.endpoints.get_openrag_config", return_value=current),
+ patch("api.settings.endpoints._get_flows_service", return_value=flows_service),
+ patch("services.docling_service.platform.system", return_value="Darwin"),
+ ):
+ await update_docling_preset(
+ body=DoclingPresetBody(ocr=True),
+ session_manager=AsyncMock(),
+ user=MagicMock(),
+ )
+
+ _, opts = flows_service.update_flow_docling_preset.call_args.args
+ assert opts["ocr_lang"] == ["ja-JP", "en-US"]
diff --git a/tests/unit/test_docling_service.py b/tests/unit/test_docling_service.py
index 6d3d303c9..091393dd6 100644
--- a/tests/unit/test_docling_service.py
+++ b/tests/unit/test_docling_service.py
@@ -261,13 +261,56 @@ async def test_build_docling_options_preview_mode_embeds_page_images(docling_ser
assert options["include_images"] is True
+async def test_build_docling_options_sends_configured_ocr_languages(docling_service):
+ """OCR languages from KnowledgeConfig reach docling as engine-specific codes."""
+ mock_config = MagicMock()
+ mock_config.knowledge.table_structure = False
+ mock_config.knowledge.ocr = True
+ mock_config.knowledge.ocr_languages = ["en", "ja"]
+ mock_config.knowledge.picture_descriptions = False
+ mock_config.knowledge.vlm_enabled = False
+
+ with (
+ patch("services.docling_service.get_openrag_config", return_value=mock_config),
+ patch("services.docling_service.platform.system", return_value="Darwin"),
+ ):
+ options = await docling_service._build_docling_options_async()
+
+ assert options["ocr_lang"] == ["ja-JP", "en-US"]
+
+
+async def test_upload_sends_ocr_lang_as_repeated_form_fields(docling_service, mock_httpx_client):
+ """httpx encodes a list form value as repeated parts; docling needs that shape."""
+ mock_config = MagicMock()
+ mock_config.knowledge.table_structure = False
+ mock_config.knowledge.ocr = True
+ mock_config.knowledge.ocr_languages = ["en", "ja"]
+ mock_config.knowledge.picture_descriptions = False
+ mock_config.knowledge.vlm_enabled = False
+
+ mock_httpx_client.post.return_value = _make_response(200, {"task_id": "t1"})
+
+ with (
+ patch("services.docling_service.get_openrag_config", return_value=mock_config),
+ patch("services.docling_service.platform.system", return_value="Darwin"),
+ ):
+ await docling_service.upload_to_docling_direct_async("doc.pdf", b"data")
+
+ sent = mock_httpx_client.post.call_args.kwargs["data"]
+ assert sent["ocr_lang"] == ["ja-JP", "en-US"]
+ assert sent["ocr_preset"] == "ocrmac"
+ assert "ocr_engine" not in sent
+
+
def test_preset_configs_macos():
"""Uses ocrmac engine on macOS."""
from services.docling_service import get_docling_preset_configs
with patch("services.docling_service.platform.system", return_value="Darwin"):
preset = get_docling_preset_configs(ocr=True)
- assert preset["ocr_engine"] == "ocrmac"
+ assert preset["ocr_preset"] == "ocrmac"
def test_preset_configs_linux():
@@ -276,7 +319,57 @@ def test_preset_configs_linux():
with patch("services.docling_service.platform.system", return_value="Linux"):
preset = get_docling_preset_configs(ocr=True)
- assert preset["ocr_engine"] == "easyocr"
+ assert preset["ocr_preset"] == "easyocr"
+
+
+def test_preset_configs_never_sends_deprecated_ocr_engine():
+ """Use the supported preset field rather than the deprecated engine field."""
+ from services.docling_service import get_docling_preset_configs
+
+ with patch("services.docling_service.platform.system", return_value="Darwin"):
+ preset = get_docling_preset_configs(ocr=True, ocr_languages=["ja", "en"])
+
+ assert "ocr_engine" not in preset
+
+
+def test_preset_configs_maps_languages_to_ocrmac_codes():
+ """ocrmac wants BCP-47 tags, not the neutral codes stored in config."""
+ from services.docling_service import get_docling_preset_configs
+
+ with patch("services.docling_service.platform.system", return_value="Darwin"):
+ preset = get_docling_preset_configs(ocr=True, ocr_languages=["ja", "en", "vi"])
+
+ assert preset["ocr_lang"] == ["ja-JP", "vi-VN", "en-US"]
+
+
+def test_preset_configs_maps_languages_to_easyocr_codes():
+ """easyocr wants short codes, and its own spelling for Chinese."""
+ from services.docling_service import get_docling_preset_configs
+
+ with patch("services.docling_service.platform.system", return_value="Linux"):
+ preset = get_docling_preset_configs(ocr=True, ocr_languages=["ja", "zh-Hans"])
+
+ assert preset["ocr_lang"] == ["ja", "ch_sim"]
+
+
+def test_preset_configs_passes_through_unknown_language_codes():
+ """An engine code the map does not know is forwarded rather than dropped."""
+ from services.docling_service import get_docling_preset_configs
+
+ with patch("services.docling_service.platform.system", return_value="Linux"):
+ preset = get_docling_preset_configs(ocr=True, ocr_languages=["bn"])
+
+ assert preset["ocr_lang"] == ["bn"]
+
+
+def test_preset_configs_omits_ocr_lang_when_no_languages_configured():
+ """Empty config must not send an empty list that would override engine defaults."""
+ from services.docling_service import get_docling_preset_configs
+
+ with patch("services.docling_service.platform.system", return_value="Darwin"):
+ preset = get_docling_preset_configs(ocr=True, ocr_languages=[])
+
+ assert "ocr_lang" not in preset
def test_init_default_url():
@@ -470,3 +563,29 @@ async def test_build_vlm_options_azure_ai_requires_credentials(docling_service):
with patch("services.docling_service.get_openrag_config", return_value=mock_config):
with pytest.raises(DoclingServeError, match="Azure AI Foundry provider is not"):
await docling_service._build_docling_options_async()
+
+
+def test_docling_config_model_accepts_preset_output():
+ """DoclingConfig validates the dict get_docling_preset_configs produces."""
+ from services.docling_service import DoclingConfig, get_docling_preset_configs
+
+ with patch("services.docling_service.platform.system", return_value="Darwin"):
+ preset = get_docling_preset_configs(ocr=True, ocr_languages=["en", "ja"])
+
+ config = DoclingConfig(**preset)
+
+ assert config.ocr_preset == "ocrmac"
+ assert config.ocr_lang == ["ja-JP", "en-US"]
+
+
+def test_preset_configs_maps_arabic_per_engine():
+ """Arabic is in the curated set; ocrmac and easyocr spell it differently."""
+ from services.docling_service import get_docling_preset_configs
+
+ with patch("services.docling_service.platform.system", return_value="Darwin"):
+ mac = get_docling_preset_configs(ocr=True, ocr_languages=["ar"])
+ with patch("services.docling_service.platform.system", return_value="Linux"):
+ linux = get_docling_preset_configs(ocr=True, ocr_languages=["ar"])
+
+ assert mac["ocr_lang"] == ["ar-SA"]
+ assert linux["ocr_lang"] == ["ar"]
diff --git a/tests/unit/test_langflow_docling_ocr_sync.py b/tests/unit/test_langflow_docling_ocr_sync.py
new file mode 100644
index 000000000..760fbcfe3
--- /dev/null
+++ b/tests/unit/test_langflow_docling_ocr_sync.py
@@ -0,0 +1,27 @@
+"""Docling OCR settings pushed into the Langflow ingest flow."""
+
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from api.settings.langflow_sync import _update_langflow_docling_settings
+
+
+async def test_langflow_sync_includes_ocr_languages():
+ """The ingest flow's docling_serve_opts must carry the configured OCR languages."""
+ config = MagicMock()
+ config.knowledge.table_structure = False
+ config.knowledge.ocr = True
+ config.knowledge.ocr_languages = ["en", "ja"]
+ config.knowledge.picture_descriptions = False
+
+ flows_service = MagicMock()
+ flows_service.update_flow_docling_preset = AsyncMock()
+
+ with patch("services.docling_service.platform.system", return_value="Linux"):
+ await _update_langflow_docling_settings(config, flows_service)
+
+ _, opts = flows_service.update_flow_docling_preset.call_args.args
+ assert opts["ocr_lang"] == ["ja", "en"]
+ assert opts["ocr_preset"] == "easyocr"