Skip to content

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

Python
99.8 KB
Raw Blame
"""FastAPI endpoint handlers for /settings, /onboarding, /onboarding/state,
/onboarding/rollback, /settings/docling-preset, and /openrag-docs/refresh.

Lifted verbatim from the original `src/api/settings.py`. Models live in
`api.settings.models`; provider/filter helpers in `api.settings.helpers`;
Langflow-sync helpers in `api.settings.langflow_sync`. No behavior change.
"""

import asyncio
import copy
import json

from fastapi import Depends, HTTPException, Request
from fastapi.responses import JSONResponse

from api.provider_validation import (
    get_provider_enhancement,
    sanitize_provider_error_content,
    validate_provider_setup,
)
from api.settings.helpers import (
    _affected_embedding_models,
    _create_openrag_docs_filter,
    _default_embedding_model,
    _default_llm_model,
    _embedding_conflict_response,
    _first_configured_embedding_provider,
    _first_configured_llm_provider,
    _get_flows_service,
    _has_other_configured_provider,
)
from api.settings.langflow_sync import (
    _background_tasks,
    _run_async_post_save_langflow_updates,
    _update_langflow_docling_settings,
    _update_langflow_global_variables,
    _update_langflow_model_values,
    _update_langflow_system_prompt,
    _update_mcp_server_urls,
)
from api.settings.models import (
    AgentConfig,
    AnthropicProviderConfig,
    DoclingPresetBody,
    DoclingPresetResponse,
    GenericProviderConfig,
    IngestionDefaultsConfig,
    KnowledgeConfig,
    OllamaProviderConfig,
    OnboardingBody,
    OnboardingResponse,
    OnboardingStateBody,
    OnboardingStateConfig,
    OnboardingStateResponse,
    OpenAIProviderConfig,
    ProvidersConfig,
    RefreshOpenRAGDocsResponse,
    RollbackBody,
    RollbackResponse,
    SettingsResponse,
    SettingsUpdateBody,
    SettingsUpdateResponse,
    WatsonXProviderConfig,
)
from config.config_manager import (
    ALLOWED_INDEX_NAME_PATTERNS,
    DEFAULT_SYSTEM_PROMPT,
    CredentialTargetChangedError,
    is_permitted_index_name,
)
from config.settings import (
    DEFAULT_DOCS_URL,
    ENVIRONMENT,
    HF_HOME,
    INGEST_SAMPLE_DATA,
    LANGFLOW_CHAT_FLOW_ID,
    LANGFLOW_INGEST_FLOW_ID,
    LANGFLOW_PORT,
    LANGFLOW_PUBLIC_URL,
    LANGFLOW_URL,
    LOCALHOST_URL,
    OPENRAG_INGEST_VIA_CHAT,
    OPENRAG_SHOW_PROVIDER_INGEST_SETTINGS,
    OPENRAG_SHOW_SHARED_UPLOAD_TOGGLE,
    OPENRAG_SHOW_VLM_SETTINGS,
    SEGMENT_WRITE_KEY,
    clients,
    config_manager,
    get_openrag_config,
    is_url_connector_enabled,
    is_workspace_oauth_overrides_enabled,
)
from dependencies import (
    get_chat_service,
    get_current_user,
    get_document_service,
    get_flows_service,
    get_knowledge_filter_service,
    get_langflow_file_service,
    get_models_service,
    get_rbac_service,
    get_session_manager,
    get_task_service,
    require_permission,
)
from services import provider_error_log
from services.docling_service import DoclingConfig, get_docling_preset_configs
from services.model_catalog import secret_field_keys
from services.rbac_service import is_rbac_enforced
from session_manager import User
from utils import provider_health_cache
from utils.langflow_utils import LangflowNotReadyError, wait_for_langflow
from utils.logging_config import get_logger, log_bootstrap_env
from utils.telemetry import Category, MessageId, TelemetryClient
from utils.version_utils import OPENRAG_VERSION

logger = get_logger(__name__)

WATSONX_ONPREM_ONBOARDING_CHUNK_SIZE = 500


def _provider_key(provider: str | None) -> str:
    """Normalize a provider name the way credential storage does.

    `set_credentials` and `credential_values` both key off `strip().lower()`,
    and `llm_provider`/`embedding_provider` no longer have a fixed pattern, so a
    request carrying "Gemini" must still find the credentials submitted under
    "gemini".
    """
    return (provider or "").strip().lower()


def _custom_providers_for_settings(openrag_config) -> dict[str, GenericProviderConfig]:
    """Public provider payloads: never drop a legacy secret when custom slots exist."""

    def payload(
        provider: str,
        *,
        configured: bool,
        credential_values: dict[str, str] | None = None,
        secret_fields: list[str] | None = None,
        stored=None,
    ) -> GenericProviderConfig:
        values = dict(credential_values or {})
        secrets = list(secret_fields or [])
        if stored is not None:
            secret_keys = secret_field_keys(provider)
            values.update(
                {key: value for key, value in stored.credentials.items() if key not in secret_keys}
            )
            secrets.extend(key for key in secret_keys if stored.credentials.get(key))
            configured = configured or stored.configured
        return GenericProviderConfig(
            configured=configured,
            auth_method=getattr(stored, "auth_method", None),
            credential_values={key: value for key, value in values.items() if value},
            secret_fields=list(dict.fromkeys(secrets)),
        )

    providers = {
        "openai": payload(
            "openai",
            configured=openrag_config.providers.openai.configured,
            secret_fields=["api_key"] if openrag_config.providers.openai.api_key else [],
        ),
        "anthropic": payload(
            "anthropic",
            configured=openrag_config.providers.anthropic.configured,
            secret_fields=["api_key"] if openrag_config.providers.anthropic.api_key else [],
        ),
        "watsonx": payload(
            "watsonx",
            configured=openrag_config.providers.watsonx.configured,
            credential_values={
                key: value
                for key, value in {
                    "api_base": openrag_config.providers.watsonx.endpoint,
                    "project_id": openrag_config.providers.watsonx.project_id,
                }.items()
                if value
            },
            secret_fields=["api_key"] if openrag_config.providers.watsonx.api_key else [],
        ),
        "ollama": payload(
            "ollama",
            configured=openrag_config.providers.ollama.configured,
            credential_values={"api_base": openrag_config.providers.ollama.endpoint}
            if openrag_config.providers.ollama.endpoint
            else {},
        ),
    }
    for provider, stored in openrag_config.providers.custom.items():
        previous = providers.get(provider)
        providers[provider] = payload(
            provider,
            configured=previous.configured if previous else stored.configured,
            credential_values=previous.credential_values if previous else {},
            secret_fields=previous.secret_fields if previous else [],
            stored=stored,
        )
    return providers


def _detect_local_vlm_models() -> list[str]:
    from pathlib import Path

    local_models = []
    hf_cache = Path.home() / ".cache" / "huggingface" / "hub"
    if HF_HOME:
        hf_cache = Path(HF_HOME) / "hub"
    if hf_cache.exists():
        for p in hf_cache.glob("models--*"):
            if (
                p.is_dir()
                and ("smolvlm" in p.name.lower() or "granite-docling" in p.name.lower())
                and "mlx" not in p.name.lower()
            ):
                parts = p.name.split("--")
                if len(parts) >= 3:
                    owner = parts[1]
                    model = "--".join(parts[2:])
                    model_id = f"{owner}/{model}"
                    if model_id not in local_models:
                        local_models.append(model_id)
    # Ensure HuggingFaceTB/SmolVLM-256M-Instruct is first if present
    if "HuggingFaceTB/SmolVLM-256M-Instruct" in local_models:
        local_models.remove("HuggingFaceTB/SmolVLM-256M-Instruct")
        local_models.insert(0, "HuggingFaceTB/SmolVLM-256M-Instruct")
    return local_models


async def get_settings(
    request: Request,
    session_manager=Depends(get_session_manager),
    user: User = Depends(get_current_user),
    rbac=Depends(get_rbac_service),
) -> SettingsResponse:
    """Get application settings"""
    try:
        openrag_config = get_openrag_config()

        # Provider configuration is admin-only. Non-admins still get the rest of
        # settings (the UI needs them) but the providers section is redacted.
        show_providers = True
        if is_rbac_enforced():
            uid = user.db_user_id or user.user_id
            show_providers = await rbac.has_permission(uid, "providers:read")

        knowledge_config = openrag_config.knowledge
        agent_config = openrag_config.agent

        # Only expose edit URLs when a public URL is configured
        langflow_edit_url = None
        if LANGFLOW_PUBLIC_URL and LANGFLOW_CHAT_FLOW_ID:
            langflow_edit_url = f"{LANGFLOW_PUBLIC_URL.rstrip('/')}/flow/{LANGFLOW_CHAT_FLOW_ID}"

        langflow_ingest_edit_url = None
        if LANGFLOW_PUBLIC_URL and LANGFLOW_INGEST_FLOW_ID:
            langflow_ingest_edit_url = (
                f"{LANGFLOW_PUBLIC_URL.rstrip('/')}/flow/{LANGFLOW_INGEST_FLOW_ID}"
            )

        ingestion_defaults_obj = None
        # Fetch ingestion flow configuration to get actual component defaults
        if LANGFLOW_INGEST_FLOW_ID and openrag_config.edited:
            try:
                response = await clients.langflow_request(
                    "GET", f"/api/v1/flows/{LANGFLOW_INGEST_FLOW_ID}"
                )
                if response.status_code == 200:
                    flow_data = response.json()

                    # Extract component defaults (ingestion-specific settings only)
                    # Start with configured defaults
                    ingestion_defaults = {
                        "chunkSize": knowledge_config.chunk_size,
                        "chunkOverlap": knowledge_config.chunk_overlap,
                        "separator": "\\n",  # Keep hardcoded for now as it's not in config
                        "embeddingModel": knowledge_config.embedding_model,
                    }

                    if flow_data.get("data", {}).get("nodes"):
                        for node in flow_data["data"]["nodes"]:
                            node_template = node.get("data", {}).get("node", {}).get("template", {})

                            # Split Text component
                            if (
                                node.get("data", {}).get("node", {}).get("display_name")
                                == "Split Text"
                            ):
                                if node_template.get("chunk_size", {}).get("value"):
                                    ingestion_defaults["chunkSize"] = node_template["chunk_size"][
                                        "value"
                                    ]
                                if node_template.get("chunk_overlap", {}).get("value"):
                                    ingestion_defaults["chunkOverlap"] = node_template[
                                        "chunk_overlap"
                                    ]["value"]
                                if node_template.get("separator", {}).get("value"):
                                    ingestion_defaults["separator"] = node_template["separator"][
                                        "value"
                                    ]

                    ingestion_defaults_obj = IngestionDefaultsConfig(**ingestion_defaults)

            except Exception as e:
                logger.warning(f"Failed to fetch ingestion flow defaults: {e}")
                # Continue without ingestion defaults

        return SettingsResponse(
            langflow_url=LANGFLOW_URL,
            flow_id=LANGFLOW_CHAT_FLOW_ID,
            ingest_flow_id=LANGFLOW_INGEST_FLOW_ID,
            langflow_public_url=LANGFLOW_PUBLIC_URL,
            edited=openrag_config.edited,
            onboarding=OnboardingStateConfig(
                current_step=openrag_config.onboarding.current_step,
                assistant_message=openrag_config.onboarding.assistant_message,
                selected_nudge=openrag_config.onboarding.selected_nudge,
                card_steps=openrag_config.onboarding.card_steps,
                upload_steps=openrag_config.onboarding.upload_steps,
                openrag_docs_filter_id=openrag_config.onboarding.openrag_docs_filter_id,
                user_doc_filter_id=openrag_config.onboarding.user_doc_filter_id,
                openrag_docs_ingested_version=openrag_config.onboarding.openrag_docs_ingested_version,
                openrag_docs_remote_signature=openrag_config.onboarding.openrag_docs_remote_signature,
            ),
            providers=ProvidersConfig(
                openai=OpenAIProviderConfig(
                    has_api_key=bool(openrag_config.providers.openai.api_key),
                    configured=openrag_config.providers.openai.configured,
                ),
                anthropic=AnthropicProviderConfig(
                    has_api_key=bool(openrag_config.providers.anthropic.api_key),
                    configured=openrag_config.providers.anthropic.configured,
                ),
                watsonx=WatsonXProviderConfig(
                    has_api_key=bool(openrag_config.providers.watsonx.api_key),
                    endpoint=openrag_config.providers.watsonx.endpoint or None,
                    project_id=openrag_config.providers.watsonx.project_id or None,
                    configured=openrag_config.providers.watsonx.configured,
                ),
                ollama=OllamaProviderConfig(
                    endpoint=openrag_config.providers.ollama.endpoint or None,
                    configured=openrag_config.providers.ollama.configured,
                ),
                custom=_custom_providers_for_settings(openrag_config),
            )
            if show_providers
            else None,
            knowledge=KnowledgeConfig(
                embedding_model=knowledge_config.embedding_model,
                embedding_provider=knowledge_config.embedding_provider,
                chunk_size=knowledge_config.chunk_size,
                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,
                vlm_enabled=knowledge_config.vlm_enabled,
                vlm_provider=knowledge_config.vlm_provider,
                vlm_model=knowledge_config.vlm_model,
                vlm_prompt=knowledge_config.vlm_prompt,
                vlm_response_format=knowledge_config.vlm_response_format,
                vlm_max_tokens=knowledge_config.vlm_max_tokens,
                vlm_concurrency=knowledge_config.vlm_concurrency,
                vlm_timeout=knowledge_config.vlm_timeout,
                vlm_watsonx_api_version=knowledge_config.vlm_watsonx_api_version,
            ),
            agent=AgentConfig(
                llm_model=agent_config.llm_model,
                llm_provider=agent_config.llm_provider,
                system_prompt=agent_config.system_prompt,
                default_system_prompt=DEFAULT_SYSTEM_PROMPT,
            ),
            localhost_url=LOCALHOST_URL,
            langflow_edit_url=langflow_edit_url,
            langflow_ingest_edit_url=langflow_ingest_edit_url,
            ingestion_defaults=ingestion_defaults_obj,
            ingest_via_chat=OPENRAG_INGEST_VIA_CHAT,
            show_provider_ingest_settings=OPENRAG_SHOW_PROVIDER_INGEST_SETTINGS,
            show_vlm_settings=OPENRAG_SHOW_VLM_SETTINGS,
            local_vlm_models=await asyncio.to_thread(_detect_local_vlm_models),
            show_shared_upload_toggle=OPENRAG_SHOW_SHARED_UPLOAD_TOGGLE,
            show_url_connector=is_url_connector_enabled(),
            show_workspace_oauth_overrides=is_workspace_oauth_overrides_enabled(),
            segment_write_key=SEGMENT_WRITE_KEY or None,
            environment=ENVIRONMENT or None,
            langflow_port=str(LANGFLOW_PORT),
        )

    except Exception:
        logger.exception("Failed to retrieve settings")
        return JSONResponse({"error": "Failed to retrieve settings"}, status_code=500)


async def update_settings(
    body: SettingsUpdateBody,
    session_manager=Depends(get_session_manager),
    user: User = Depends(require_permission("config:write")),
    models_service=Depends(get_models_service),
    rbac=Depends(get_rbac_service),
) -> SettingsUpdateResponse:
    """Update settings in configuration"""
    try:
        # Get current configuration
        current_config = get_openrag_config()

        # Check if config is marked as edited
        if not current_config.edited:
            return JSONResponse(
                {"error": "Configuration must be marked as edited before updates are allowed"},
                status_code=403,
            )

        # Validate provider setup if provider-related fields are being updated
        # Do this BEFORE modifying any config
        provider_fields = [
            "llm_provider",
            "embedding_provider",
            "llm_model",
            "embedding_model",
            "openai_api_key",
            "anthropic_api_key",
            "watsonx_api_key",
            "watsonx_endpoint",
            "watsonx_project_id",
            "ollama_endpoint",
            "provider_credentials",
            "provider_credential_removals",
            "remove_provider_config",
        ]
        submitted_credentials = {
            _provider_key(name): values
            for name, values in (body.provider_credentials or {}).items()
        }
        removals_by_provider = {
            _provider_key(name): set(fields)
            for name, fields in (body.provider_credential_removals or {}).items()
        }
        provider_update_keys = set(submitted_credentials) | set(removals_by_provider)
        auth_methods_by_provider = {
            _provider_key(name): method
            for name, method in (body.provider_auth_methods or {}).items()
        }
        should_validate = any(getattr(body, field) is not None for field in provider_fields)

        # Docling VLM settings reuse provider credentials, so they are gated
        # like the Providers page. They don't trigger provider validation.
        vlm_update_fields = [
            "vlm_enabled",
            "vlm_provider",
            "vlm_model",
            "vlm_prompt",
            "vlm_response_format",
            "vlm_max_tokens",
            "vlm_concurrency",
            "vlm_timeout",
            "vlm_watsonx_api_version",
        ]
        vlm_update = any(getattr(body, field) is not None for field in vlm_update_fields)

        # Provider changes are admin-only. The outer gate only requires
        # config:write; require providers:write specifically when any
        # provider field is being touched (defends custom roles too).
        if (
            (should_validate or vlm_update)
            and is_rbac_enforced()
            and hasattr(rbac, "has_permission")
        ):
            uid = user.db_user_id or user.user_id
            if not await rbac.has_permission(uid, "providers:write"):
                await rbac.audit_denied(uid, "providers:write")
                raise HTTPException(
                    status_code=403,
                    detail={"error": "permission_denied", "required": "providers:write"},
                )

        if should_validate:
            try:
                logger.info("Running provider validation before modifying config")

                # A generic provider save normally has no selected model to
                # probe. Azure is the exception: both OpenAI Service and
                # Foundry resource endpoints have a read-only auth probe.
                # Provider enhancements are the other exception: each carries
                # a model-free `lightweight_health_check`, so a bad URL or
                # token is rejected here rather than on the first chat or
                # ingest.
                for provider_key in provider_update_keys:
                    submitted = submitted_credentials.get(provider_key, {})
                    removals = removals_by_provider.get(provider_key, set())
                    auth_method = auth_methods_by_provider.get(provider_key)
                    credentials = current_config.providers.pending_credentials(
                        provider_key, submitted, remove=removals, auth_method=auth_method
                    )
                    if provider_key == "azure":
                        required_by_method = {
                            "api_key": {"api_key"},
                            "entra_token": {"azure_ad_token"},
                            "service_principal": {"tenant_id", "client_id", "client_secret"},
                        }
                        required = required_by_method.get(auth_method or "")
                        if required is None:
                            raise ValueError("Choose an Azure authentication method")
                        missing = sorted(
                            name for name in required | {"api_base"} if not credentials.get(name)
                        )
                        if missing:
                            raise ValueError(f"{', '.join(missing)} is required for Azure OpenAI")
                        await validate_provider_setup(
                            provider=provider_key,
                            api_key=credentials.get("api_key") or credentials.get("azure_ad_token"),
                            endpoint=credentials.get("api_base"),
                            credentials=credentials,
                        )
                    elif get_provider_enhancement(provider_key) is not None:
                        # No model is passed, so the validator runs the
                        # enhancement's lightweight check. It is given the
                        # untranslated pending form because that is the only
                        # one carrying every endpoint the operator entered —
                        # both OpenShift AI `InferenceService` URLs, not the
                        # single one `credentials` was narrowed to.
                        await validate_provider_setup(
                            provider=provider_key,
                            credentials=credentials,
                            stored_credentials=current_config.providers.pending_stored_credentials(
                                provider_key, submitted, remove=removals, auth_method=auth_method
                            ),
                        )

                # Validate LLM provider if being changed
                if body.llm_provider is not None or body.llm_model is not None:
                    llm_provider = (
                        body.llm_provider.strip().lower()
                        if body.llm_provider is not None
                        else current_config.agent.llm_provider
                    )
                    llm_model = (
                        body.llm_model
                        if body.llm_model is not None
                        else current_config.agent.llm_model
                    )

                    # Get the provider config (with any updates from the request)
                    llm_provider_config = current_config.providers.get_provider_config(llm_provider)

                    # Apply any updates from the request
                    api_key = getattr(llm_provider_config, "api_key", None)
                    endpoint = getattr(llm_provider_config, "endpoint", None)
                    project_id = getattr(llm_provider_config, "project_id", None)
                    llm_provider_key = _provider_key(llm_provider)
                    credentials = current_config.providers.pending_credentials(
                        llm_provider_key,
                        submitted_credentials.get(llm_provider_key, {}),
                        remove=removals_by_provider.get(llm_provider_key, set()),
                        auth_method=auth_methods_by_provider.get(llm_provider_key),
                    )
                    api_key = credentials.get("api_key", api_key)
                    endpoint = credentials.get("api_base", endpoint)
                    project_id = credentials.get("project_id", project_id)

                    if (
                        getattr(body, f"{llm_provider}_api_key", None) is not None
                        and getattr(body, f"{llm_provider}_api_key", None).strip()
                    ):
                        api_key = getattr(body, f"{llm_provider}_api_key", None)
                    if getattr(body, f"{llm_provider}_endpoint", None) is not None:
                        endpoint = getattr(body, f"{llm_provider}_endpoint", None)
                    if getattr(body, f"{llm_provider}_project_id", None) is not None:
                        project_id = getattr(body, f"{llm_provider}_project_id", None)

                    await validate_provider_setup(
                        provider=llm_provider,
                        api_key=api_key,
                        llm_model=llm_model,
                        endpoint=endpoint,
                        project_id=project_id,
                        credentials=credentials,
                        stored_credentials=current_config.providers.pending_stored_credentials(
                            llm_provider_key,
                            submitted_credentials.get(llm_provider_key, {}),
                            remove=removals_by_provider.get(llm_provider_key, set()),
                            auth_method=auth_methods_by_provider.get(llm_provider_key),
                        ),
                        # A model the cluster does not serve must fail the
                        # save, not the first chat.
                        verify_model=True,
                    )
                    logger.info(f"LLM provider validation successful for {llm_provider}")

                # Validate embedding provider if being changed
                if body.embedding_provider is not None or body.embedding_model is not None:
                    embedding_provider = (
                        body.embedding_provider.strip().lower()
                        if body.embedding_provider is not None
                        else current_config.knowledge.embedding_provider
                    )
                    embedding_model = (
                        body.embedding_model
                        if body.embedding_model is not None
                        else current_config.knowledge.embedding_model
                    )

                    # Get the provider config (with any updates from the request)
                    embedding_provider_config = current_config.providers.get_provider_config(
                        embedding_provider
                    )

                    # Apply any updates from the request
                    api_key = getattr(embedding_provider_config, "api_key", None)
                    endpoint = getattr(embedding_provider_config, "endpoint", None)
                    project_id = getattr(embedding_provider_config, "project_id", None)
                    embedding_provider_key = _provider_key(embedding_provider)
                    credentials = current_config.providers.pending_credentials(
                        embedding_provider_key,
                        submitted_credentials.get(embedding_provider_key, {}),
                        kind="embedding",
                        remove=removals_by_provider.get(embedding_provider_key, set()),
                        auth_method=auth_methods_by_provider.get(embedding_provider_key),
                    )
                    api_key = credentials.get("api_key", api_key)
                    endpoint = credentials.get("api_base", endpoint)
                    project_id = credentials.get("project_id", project_id)

                    if (
                        getattr(body, f"{embedding_provider}_api_key", None) is not None
                        and getattr(body, f"{embedding_provider}_api_key", None).strip()
                    ):
                        api_key = getattr(body, f"{embedding_provider}_api_key", None)
                    if getattr(body, f"{embedding_provider}_endpoint", None) is not None:
                        endpoint = getattr(body, f"{embedding_provider}_endpoint", None)
                    if getattr(body, f"{embedding_provider}_project_id", None) is not None:
                        project_id = getattr(body, f"{embedding_provider}_project_id", None)

                    await validate_provider_setup(
                        provider=embedding_provider,
                        api_key=api_key,
                        embedding_model=embedding_model,
                        endpoint=endpoint,
                        project_id=project_id,
                        credentials=credentials,
                        stored_credentials=current_config.providers.pending_stored_credentials(
                            embedding_provider_key,
                            submitted_credentials.get(embedding_provider_key, {}),
                            remove=removals_by_provider.get(embedding_provider_key, set()),
                            auth_method=auth_methods_by_provider.get(embedding_provider_key),
                        ),
                        verify_model=True,
                    )
                    logger.info(
                        f"Embedding provider validation successful for {embedding_provider}"
                    )

            except CredentialTargetChangedError as e:
                # Raised before any probe is sent; the message names form
                # labels only, so it is returned as-is rather than run through
                # the provider-error humaniser.
                logger.warning(
                    "Settings update refused: a credential target changed without its secrets",
                    provider=e.provider,
                    fields=list(e.fields),
                )
                return JSONResponse({"error": str(e)}, status_code=400)
            except Exception as e:
                logger.error(f"Provider validation failed: {str(e)}")
                return JSONResponse({"error": sanitize_provider_error_content(e)}, status_code=400)

        # Update configuration
        # Only reached if validation passed or wasn't needed.
        # Stage every mutation on a deep copy so a validation failure partway
        # through (e.g. the index_name or chunk_overlap checks below) can't
        # leave the live cached config half-updated and unsaved.
        working_config = copy.deepcopy(current_config)
        config_updated = False

        # Update agent settings
        if body.llm_model is not None:
            old_model = working_config.agent.llm_model
            working_config.agent.llm_model = body.llm_model
            config_updated = True
            await TelemetryClient.send_event(
                Category.SETTINGS_OPERATIONS, MessageId.ORB_SETTINGS_LLM_MODEL
            )
            logger.info(f"LLM model changed from {old_model} to {body.llm_model}")

        if body.llm_provider is not None:
            old_provider = working_config.agent.llm_provider
            working_config.agent.llm_provider = body.llm_provider
            config_updated = True
            await TelemetryClient.send_event(
                Category.SETTINGS_OPERATIONS, MessageId.ORB_SETTINGS_LLM_PROVIDER
            )
            logger.info(f"LLM provider changed from {old_provider} to {body.llm_provider}")

        if body.system_prompt is not None:
            working_config.agent.system_prompt = body.system_prompt
            config_updated = True
            await TelemetryClient.send_event(
                Category.SETTINGS_OPERATIONS, MessageId.ORB_SETTINGS_SYSTEM_PROMPT
            )

            # Also update the chat flow with the new system prompt
            try:
                flows_service = _get_flows_service()
                await _update_langflow_system_prompt(working_config, flows_service)
            except Exception as e:
                logger.error(f"Failed to update chat flow system prompt: {str(e)}")
                # Don't fail the entire settings update if flow update fails
                # The config will still be saved

        # Update knowledge settings
        if body.embedding_model is not None:
            old_model = working_config.knowledge.embedding_model
            new_embedding_model = body.embedding_model.strip()
            working_config.knowledge.embedding_model = new_embedding_model
            config_updated = True
            await TelemetryClient.send_event(
                Category.SETTINGS_OPERATIONS, MessageId.ORB_SETTINGS_EMBED_MODEL
            )
            logger.info(f"Embedding model changed from {old_model} to {new_embedding_model}")

        if body.embedding_provider is not None:
            old_provider = working_config.knowledge.embedding_provider
            working_config.knowledge.embedding_provider = body.embedding_provider
            config_updated = True
            await TelemetryClient.send_event(
                Category.SETTINGS_OPERATIONS, MessageId.ORB_SETTINGS_EMBED_PROVIDER
            )
            logger.info(
                f"Embedding provider changed from {old_provider} to {body.embedding_provider}"
            )

        if body.table_structure is not None:
            working_config.knowledge.table_structure = body.table_structure
            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.ocr is not None:
            working_config.knowledge.ocr = body.ocr
            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.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
            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.disable_ingest_with_langflow is not None:
            working_config.knowledge.disable_ingest_with_langflow = (
                body.disable_ingest_with_langflow
            )
            config_updated = True
            logger.info(
                f"Disable Langflow ingestion changed to {body.disable_ingest_with_langflow}"
            )

        if body.chunk_size is not None:
            effective_overlap = (
                body.chunk_overlap
                if body.chunk_overlap is not None
                else working_config.knowledge.chunk_overlap
            )
            if effective_overlap >= body.chunk_size:
                raise HTTPException(
                    status_code=422, detail="chunk_overlap must be less than chunk_size"
                )
            working_config.knowledge.chunk_size = body.chunk_size
            config_updated = True
            await TelemetryClient.send_event(
                Category.SETTINGS_OPERATIONS, MessageId.ORB_SETTINGS_CHUNK_UPDATED
            )

            # Also update the ingest flow with the new chunk size
            try:
                flows_service = _get_flows_service()
                await flows_service.update_ingest_flow_chunk_size(body.chunk_size)
                logger.info(f"Successfully updated ingest flow chunk size to {body.chunk_size}")
            except Exception as e:
                logger.error(f"Failed to update ingest flow chunk size: {str(e)}")
                # Don't fail the entire settings update if flow update fails
                # The config will still be saved

        if body.chunk_overlap is not None:
            effective_chunk_size = (
                body.chunk_size
                if body.chunk_size is not None
                else working_config.knowledge.chunk_size
            )
            if body.chunk_overlap >= effective_chunk_size:
                raise HTTPException(
                    status_code=422, detail="chunk_overlap must be less than chunk_size"
                )
            working_config.knowledge.chunk_overlap = body.chunk_overlap
            config_updated = True
            await TelemetryClient.send_event(
                Category.SETTINGS_OPERATIONS, MessageId.ORB_SETTINGS_CHUNK_UPDATED
            )

            # Also update the ingest flow with the new chunk overlap
            try:
                flows_service = _get_flows_service()
                await flows_service.update_ingest_flow_chunk_overlap(body.chunk_overlap)
                logger.info(
                    f"Successfully updated ingest flow chunk overlap to {body.chunk_overlap}"
                )
            except Exception as e:
                logger.error(f"Failed to update ingest flow chunk overlap: {str(e)}")
                # Don't fail the entire settings update if flow update fails
        if body.index_name is not None:
            old_index_name = working_config.knowledge.index_name
            new_index_name = body.index_name.strip()
            if not is_permitted_index_name(new_index_name):
                raise HTTPException(
                    status_code=422,
                    detail=(
                        f"Index name '{new_index_name}' is not permitted. The OpenSearch "
                        "security role only grants search access to indices matching "
                        f"{' or '.join(ALLOWED_INDEX_NAME_PATTERNS)}."
                    ),
                )
            working_config.knowledge.index_name = new_index_name
            config_updated = True
            await TelemetryClient.send_event(
                Category.SETTINGS_OPERATIONS, MessageId.ORB_SETTINGS_INDEX_NAME_UPDATED
            )
            logger.info(f"Index name changed from {old_index_name} to {new_index_name}")

            # Also update global variable with new index name
            try:
                await clients._create_langflow_global_variable(
                    "OPENSEARCH_INDEX_NAME",
                    new_index_name,
                    modify=True,
                    variable_type="Generic",
                )
                logger.info(
                    f"Successfully updated global variable with new index name {new_index_name}"
                )
            except Exception as e:
                logger.error(f"Failed to update global variable with new index name: {str(e)}")
                # Don't fail the entire settings update if flow update fails

                # The config will still be saved

        # Update Docling VLM settings (knowledge.vlm_*). Credentials are reused
        # from the providers config; these fields carry no secrets and are
        # intentionally NOT synced into the Langflow flow JSON.
        if body.vlm_enabled:
            effective_vlm_provider = body.vlm_provider or current_config.knowledge.vlm_provider
            if effective_vlm_provider in ("openai", "watsonx", "anthropic", "azure", "azure_ai"):
                vlm_provider_config = current_config.providers.get_provider_config(
                    effective_vlm_provider
                )
                credentials = current_config.providers.credential_values(effective_vlm_provider)

                # Whether the provider is usable at all is the provider's own
                # question, and `configured` already answers it against that
                # provider's required fields.
                vlm_provider_missing = not vlm_provider_config.configured
                if effective_vlm_provider in ("azure", "azure_ai"):
                    vlm_provider_missing = vlm_provider_missing or not credentials.get(
                        "api_base", ""
                    )
                if effective_vlm_provider == "watsonx":
                    vlm_provider_missing = (
                        vlm_provider_missing
                        or not vlm_provider_config.endpoint
                        or not vlm_provider_config.project_id
                    )
                if vlm_provider_missing:
                    return JSONResponse(
                        {
                            "error": (
                                f"Cannot enable Docling VLM: provider '{effective_vlm_provider}' "
                                "is not configured. Configure it in Settings > Providers first."
                            )
                        },
                        status_code=400,
                    )

                # Separately: docling-serve calls the model endpoint itself,
                # with headers OpenRAG builds for it, and every remote branch
                # in `docling_service` builds an API-key header. So VLM needs a
                # key even where the provider itself can authenticate other
                # ways — Azure OpenAI already accepts a Microsoft Entra token
                # or a service principal for inference.
                #
                # This is a limit of the VLM integration, not of the provider,
                # and it is reported as one. Rolling it into "provider is not
                # configured" above sent operators to re-enter credentials that
                # were already valid, and wrote "an API key is the only way to
                # authenticate" into a gate that has no business saying so.
                # Entra for VLM needs token acquisition, refresh and
                # propagation to docling-serve, and is a separate change.
                api_key = getattr(vlm_provider_config, "api_key", "") or credentials.get(
                    "api_key", ""
                )
                if not api_key:
                    return JSONResponse(
                        {
                            "error": (
                                f"Cannot enable Docling VLM: provider "
                                f"'{effective_vlm_provider}' is configured, but image "
                                "descriptions are sent to the document converter, which "
                                "authenticates with an API key. Add one in "
                                "Settings > Providers, or turn off image descriptions."
                            )
                        },
                        status_code=400,
                    )
            elif effective_vlm_provider == "local":
                # Local provider does not require any credentials
                pass
            elif effective_vlm_provider == "ollama":
                vlm_provider_config = current_config.providers.ollama
                vlm_provider_missing = (
                    not getattr(vlm_provider_config, "endpoint", "")
                    or not vlm_provider_config.configured
                )
                if vlm_provider_missing:
                    return JSONResponse(
                        {
                            "error": (
                                "Cannot enable Docling VLM: provider 'ollama' "
                                "is not configured. Configure it in Settings > Providers first."
                            )
                        },
                        status_code=400,
                    )
            effective_vlm_model = body.vlm_model or current_config.knowledge.vlm_model
            if not effective_vlm_model.strip():
                return JSONResponse(
                    {"error": "Cannot enable Docling VLM: model name is required."},
                    status_code=400,
                )

        for vlm_field in vlm_update_fields:
            value = getattr(body, vlm_field)
            if value is not None:
                setattr(working_config.knowledge, vlm_field, value)
                config_updated = True

        # Update provider-specific settings
        provider_updated = False
        for provider in provider_update_keys:
            removals = removals_by_provider.get(provider, set())
            auth_method = auth_methods_by_provider.get(provider)
            logger.info(
                "Saving provider credentials",
                provider=provider,
                auth_method=auth_method,
                removed=sorted(removals),
            )
            working_config.providers.set_credentials(
                provider,
                submitted_credentials.get(provider, {}),
                auth_method=auth_method,
                remove=removals,
            )
            config_updated = True
            provider_updated = True

        if body.openai_api_key is not None and body.openai_api_key.strip():
            working_config.providers.openai.api_key = body.openai_api_key.strip()
            working_config.providers.openai.configured = True
            config_updated = True
            provider_updated = True

        if body.anthropic_api_key is not None and body.anthropic_api_key.strip():
            working_config.providers.anthropic.api_key = body.anthropic_api_key.strip()
            working_config.providers.anthropic.configured = True
            config_updated = True
            provider_updated = True

        if body.watsonx_api_key is not None and body.watsonx_api_key.strip():
            working_config.providers.watsonx.api_key = body.watsonx_api_key.strip()
            working_config.providers.watsonx.configured = True
            config_updated = True
            provider_updated = True

        if body.watsonx_endpoint is not None:
            working_config.providers.watsonx.endpoint = body.watsonx_endpoint.strip()
            working_config.providers.watsonx.configured = True
            config_updated = True
            provider_updated = True

        if body.watsonx_project_id is not None:
            working_config.providers.watsonx.project_id = body.watsonx_project_id.strip()
            working_config.providers.watsonx.configured = True
            config_updated = True
            provider_updated = True

        if body.ollama_endpoint is not None:
            working_config.providers.ollama.endpoint = body.ollama_endpoint.strip()
            working_config.providers.ollama.configured = True
            config_updated = True
            provider_updated = True

        if body.remove_ollama_config:
            if not _has_other_configured_provider(working_config, "ollama"):
                return JSONResponse(
                    {
                        "error": "Cannot remove Ollama configuration: configure another model provider first."
                    },
                    status_code=400,
                )
            if not body.force_remove:
                affected = await _affected_embedding_models(
                    "ollama", session_manager, user, models_service
                )
                if affected:
                    return _embedding_conflict_response("Ollama", "ollama", affected)
            working_config.providers.ollama.endpoint = ""
            working_config.providers.ollama.configured = False
            if working_config.agent.llm_provider == "ollama":
                fb = _first_configured_llm_provider(working_config, "ollama")
                working_config.agent.llm_provider = fb
                working_config.agent.llm_model = _default_llm_model(fb)
            if working_config.knowledge.embedding_provider == "ollama":
                fb = _first_configured_embedding_provider(working_config, "ollama")
                working_config.knowledge.embedding_provider = fb
                working_config.knowledge.embedding_model = _default_embedding_model(fb)
            config_updated = True
            provider_updated = True

        if body.remove_openai_config:
            if not _has_other_configured_provider(working_config, "openai"):
                return JSONResponse(
                    {
                        "error": "Cannot remove OpenAI configuration: configure another model provider first."
                    },
                    status_code=400,
                )
            if not body.force_remove:
                affected = await _affected_embedding_models(
                    "openai", session_manager, user, models_service
                )
                if affected:
                    return _embedding_conflict_response("OpenAI", "openai", affected)
            working_config.providers.openai.api_key = ""
            working_config.providers.openai.configured = False
            if working_config.agent.llm_provider == "openai":
                fb = _first_configured_llm_provider(working_config, "openai")
                working_config.agent.llm_provider = fb
                working_config.agent.llm_model = _default_llm_model(fb)
            if working_config.knowledge.embedding_provider == "openai":
                fb = _first_configured_embedding_provider(working_config, "openai")
                working_config.knowledge.embedding_provider = fb
                working_config.knowledge.embedding_model = _default_embedding_model(fb)
            config_updated = True
            provider_updated = True

        if body.remove_anthropic_config:
            if not _has_other_configured_provider(working_config, "anthropic"):
                return JSONResponse(
                    {
                        "error": "Cannot remove Anthropic configuration: configure another model provider first."
                    },
                    status_code=400,
                )
            working_config.providers.anthropic.api_key = ""
            working_config.providers.anthropic.configured = False
            if working_config.agent.llm_provider == "anthropic":
                fb = _first_configured_llm_provider(working_config, "anthropic")
                working_config.agent.llm_provider = fb
                working_config.agent.llm_model = _default_llm_model(fb)
            # Anthropic is not a valid embedding provider; no embedding reset needed
            config_updated = True
            provider_updated = True

        if body.remove_watsonx_config:
            if not _has_other_configured_provider(working_config, "watsonx"):
                return JSONResponse(
                    {
                        "error": "Cannot remove IBM watsonx.ai configuration: configure another model provider first."
                    },
                    status_code=400,
                )
            if not body.force_remove:
                affected = await _affected_embedding_models(
                    "watsonx", session_manager, user, models_service
                )
                if affected:
                    return _embedding_conflict_response("IBM watsonx.ai", "watsonx", affected)
            working_config.providers.watsonx.api_key = ""
            working_config.providers.watsonx.endpoint = ""
            working_config.providers.watsonx.project_id = ""
            working_config.providers.watsonx.configured = False
            if working_config.agent.llm_provider == "watsonx":
                fb = _first_configured_llm_provider(working_config, "watsonx")
                working_config.agent.llm_provider = fb
                working_config.agent.llm_model = _default_llm_model(fb)
            if working_config.knowledge.embedding_provider == "watsonx":
                fb = _first_configured_embedding_provider(working_config, "watsonx")
                working_config.knowledge.embedding_provider = fb
                working_config.knowledge.embedding_model = _default_embedding_model(fb)
            config_updated = True
            provider_updated = True

        if body.remove_provider_config:
            provider = body.remove_provider_config.strip().lower()
            if provider in working_config.providers.custom:
                if not _has_other_configured_provider(working_config, provider):
                    return JSONResponse(
                        {
                            "error": (
                                "Cannot remove provider configuration: "
                                "configure another model provider first."
                            )
                        },
                        status_code=400,
                    )
                del working_config.providers.custom[provider]
                if working_config.agent.llm_provider == provider:
                    fallback = _first_configured_llm_provider(working_config, provider)
                    working_config.agent.llm_provider = fallback
                    working_config.agent.llm_model = _default_llm_model(fallback)
                if working_config.knowledge.embedding_provider == provider:
                    fallback = _first_configured_embedding_provider(working_config, provider)
                    working_config.knowledge.embedding_provider = fallback
                    working_config.knowledge.embedding_model = _default_embedding_model(fallback)
                config_updated = True
                provider_updated = True

        if provider_updated:
            await TelemetryClient.send_event(
                Category.SETTINGS_OPERATIONS, MessageId.ORB_SETTINGS_PROVIDER_CREDS
            )

        if not config_updated:
            return JSONResponse({"error": "No valid fields provided for update"}, status_code=400)

        # Save the updated configuration
        if not config_manager.save_config_file(working_config):
            return JSONResponse({"error": "Failed to save configuration"}, status_code=500)

        provider_health_cache.invalidate()
        if should_validate or provider_updated:
            # A recorded failure describes the provider setup that just changed.
            # Real traffic re-raises it if the new setup fails the same way.
            provider_error_log.clear()

        # Refresh patched client immediately so subsequent requests pick up latest config.
        await clients.refresh_patched_client()

        # Run expensive Langflow sync in the background to keep settings updates responsive.
        if should_validate or provider_updated:
            update_llm = (
                body.llm_provider is not None or body.llm_model is not None or provider_updated
            )
            update_embedding = (
                body.embedding_provider is not None
                or body.embedding_model is not None
                or provider_updated
            )
            task = asyncio.create_task(
                _run_async_post_save_langflow_updates(
                    session_manager=session_manager,
                    models_service=models_service if provider_updated else None,
                    update_mcp_servers=(
                        body.embedding_provider is not None
                        or body.embedding_model is not None
                        or provider_updated
                    ),
                    update_model_values=update_llm or update_embedding,
                    update_llm=update_llm,
                    update_embedding=update_embedding,
                    update_global_variables=provider_updated,
                )
            )
            # Keep a strong reference until completion to avoid premature GC cancellation.
            _background_tasks.add(task)
            task.add_done_callback(_background_tasks.discard)

        set_fields = [k for k, v in body.model_dump().items() if v is not None]
        logger.info("Configuration updated successfully", updated_fields=set_fields)
        await TelemetryClient.send_event(
            Category.SETTINGS_OPERATIONS, MessageId.ORB_SETTINGS_UPDATED
        )
        return SettingsUpdateResponse(message="Configuration updated successfully")

    except HTTPException:
        # Preserve intentional client-error status codes (e.g. 422 validation
        # failures) instead of letting the catch-all below flatten them to 500.
        raise
    except CredentialTargetChangedError as e:
        # Normally caught during validation; this covers a save that skipped it.
        # The changes were staged on `working_config`, so nothing was applied.
        logger.warning(
            "Settings update refused: a credential target changed without its secrets",
            provider=e.provider,
            fields=list(e.fields),
        )
        return JSONResponse({"error": str(e)}, status_code=400)
    except Exception:
        logger.exception("Failed to update settings")
        await TelemetryClient.send_event(
            Category.SETTINGS_OPERATIONS, MessageId.ORB_SETTINGS_UPDATE_FAILED
        )
        return JSONResponse({"error": "Failed to update settings"}, status_code=500)


async def onboarding(
    body: OnboardingBody,
    flows_service=Depends(get_flows_service),
    session_manager=Depends(get_session_manager),
    document_service=Depends(get_document_service),
    models_service=Depends(get_models_service),
    task_service=Depends(get_task_service),
    langflow_file_service=Depends(get_langflow_file_service),
    knowledge_filter_service=Depends(get_knowledge_filter_service),
    user: User = Depends(require_permission("config:write")),
) -> OnboardingResponse:
    """Handle onboarding configuration setup"""
    try:
        await TelemetryClient.send_event(Category.ONBOARDING, MessageId.ORB_ONBOARD_START)

        log_bootstrap_env(logger, "onboarding")

        # Onboarding validation can fail before anything is persisted. Work on
        # a copy so rejected credentials or deployment names do not leak into
        # the process-wide cached configuration.
        current_config = copy.deepcopy(get_openrag_config())

        # Warn if config was already edited (onboarding being re-run)
        if current_config.edited:
            logger.warning(
                "Onboarding is being run although configuration was already edited before"
            )

        # Update configuration
        config_updated = False

        # Update agent settings (LLM)
        llm_model_selected = None
        llm_provider_selected = None

        if body.llm_model:
            llm_model_selected = body.llm_model.strip()
            current_config.agent.llm_model = llm_model_selected
            config_updated = True
            await TelemetryClient.send_event(
                Category.ONBOARDING,
                MessageId.ORB_ONBOARD_LLM_MODEL,
                metadata={"llm_model": llm_model_selected},
            )
            logger.info(f"LLM model selected during onboarding: {llm_model_selected}")

        if body.llm_provider:
            llm_provider_selected = body.llm_provider.strip()
            current_config.agent.llm_provider = llm_provider_selected
            config_updated = True
            await TelemetryClient.send_event(
                Category.ONBOARDING,
                MessageId.ORB_ONBOARD_LLM_PROVIDER,
                metadata={"llm_provider": llm_provider_selected},
            )
            logger.info(f"LLM provider selected during onboarding: {llm_provider_selected}")

        # Update knowledge settings (embedding)
        embedding_model_selected = None
        embedding_provider_selected = None
        chunk_size_adjusted_to = None

        if body.embedding_model:
            embedding_model_selected = body.embedding_model.strip()
            current_config.knowledge.embedding_model = embedding_model_selected
            config_updated = True
            await TelemetryClient.send_event(
                Category.ONBOARDING,
                MessageId.ORB_ONBOARD_EMBED_MODEL,
                metadata={"embedding_model": embedding_model_selected},
            )
            logger.info(f"Embedding model selected during onboarding: {embedding_model_selected}")

        if body.embedding_provider:
            embedding_provider_selected = body.embedding_provider.strip()
            current_config.knowledge.embedding_provider = embedding_provider_selected
            config_updated = True
            await TelemetryClient.send_event(
                Category.ONBOARDING,
                MessageId.ORB_ONBOARD_EMBED_PROVIDER,
                metadata={"embedding_provider": embedding_provider_selected},
            )
            logger.info(
                f"Embedding provider selected during onboarding: {embedding_provider_selected}"
            )
            if (
                embedding_provider_selected.lower() == "watsonx_onprem"
                and current_config.knowledge.chunk_size > WATSONX_ONPREM_ONBOARDING_CHUNK_SIZE
            ):
                current_config.knowledge.chunk_size = WATSONX_ONPREM_ONBOARDING_CHUNK_SIZE
                if current_config.knowledge.chunk_overlap >= WATSONX_ONPREM_ONBOARDING_CHUNK_SIZE:
                    current_config.knowledge.chunk_overlap = 200
                chunk_size_adjusted_to = WATSONX_ONPREM_ONBOARDING_CHUNK_SIZE
                logger.info(
                    "Reduced chunk size for watsonx.ai on-prem embedding compatibility",
                    chunk_size=chunk_size_adjusted_to,
                    chunk_overlap=current_config.knowledge.chunk_overlap,
                )

        # Update provider-specific credentials
        if body.openai_api_key:
            current_config.providers.openai.api_key = body.openai_api_key.strip()
            current_config.providers.openai.configured = True
            config_updated = True

        if body.anthropic_api_key:
            current_config.providers.anthropic.api_key = body.anthropic_api_key.strip()
            current_config.providers.anthropic.configured = True
            config_updated = True

        if body.watsonx_api_key:
            current_config.providers.watsonx.api_key = body.watsonx_api_key.strip()
            current_config.providers.watsonx.configured = True
            config_updated = True

        if body.watsonx_endpoint:
            current_config.providers.watsonx.endpoint = body.watsonx_endpoint.strip()
            current_config.providers.watsonx.configured = True
            config_updated = True

        if body.watsonx_project_id:
            current_config.providers.watsonx.project_id = body.watsonx_project_id.strip()
            current_config.providers.watsonx.configured = True
            config_updated = True

        if body.ollama_endpoint:
            current_config.providers.ollama.endpoint = body.ollama_endpoint.strip()
            current_config.providers.ollama.configured = True
            config_updated = True

        submitted_credentials = {
            _provider_key(name): values
            for name, values in (body.provider_credentials or {}).items()
        }
        removals_by_provider = {
            _provider_key(name): set(fields)
            for name, fields in (body.provider_credential_removals or {}).items()
        }
        auth_methods_by_provider = {
            _provider_key(name): method
            for name, method in (body.provider_auth_methods or {}).items()
        }
        for provider in set(submitted_credentials) | set(removals_by_provider):
            removals = removals_by_provider.get(provider, set())
            auth_method = auth_methods_by_provider.get(provider)
            logger.info(
                "Saving provider credentials during onboarding",
                provider=provider,
                auth_method=auth_method,
                removed=sorted(removals),
            )
            try:
                current_config.providers.set_credentials(
                    provider,
                    submitted_credentials.get(provider, {}),
                    auth_method=auth_method,
                    remove=removals,
                )
            except CredentialTargetChangedError as e:
                # Refused before the validation probe below could send the
                # stored secret to the new target; `current_config` is a copy,
                # so nothing was applied.
                logger.warning(
                    "Onboarding refused: a credential target changed without its secrets",
                    provider=e.provider,
                    fields=list(e.fields),
                )
                return JSONResponse({"error": str(e)}, status_code=400)
            config_updated = True

        # Mark providers as configured if they were chosen during onboarding
        # Check LLM provider
        if body.llm_provider:
            llm_provider = body.llm_provider.strip().lower()
            if llm_provider == "openai" and current_config.providers.openai.api_key:
                current_config.providers.openai.configured = True
                logger.info("Marked OpenAI as configured (chosen as LLM provider)")
            elif llm_provider == "anthropic" and current_config.providers.anthropic.api_key:
                current_config.providers.anthropic.configured = True
                logger.info("Marked Anthropic as configured (chosen as LLM provider)")
            elif (
                llm_provider == "watsonx"
                and current_config.providers.watsonx.api_key
                and current_config.providers.watsonx.endpoint
                and current_config.providers.watsonx.project_id
            ):
                current_config.providers.watsonx.configured = True
                logger.info("Marked WatsonX as configured (chosen as LLM provider)")
            elif llm_provider == "ollama" and current_config.providers.ollama.endpoint:
                current_config.providers.ollama.configured = True
                logger.info("Marked Ollama as configured (chosen as LLM provider)")
            elif (
                llm_provider in current_config.providers.custom
                and current_config.providers.custom[llm_provider].credentials
            ):
                current_config.providers.custom[llm_provider].configured = True
                logger.info(f"Marked {llm_provider} as configured (chosen as LLM provider)")

        # Check embedding provider
        if body.embedding_provider:
            embedding_provider = body.embedding_provider.strip().lower()
            if embedding_provider == "openai" and current_config.providers.openai.api_key:
                current_config.providers.openai.configured = True
                logger.info("Marked OpenAI as configured (chosen as embedding provider)")
            elif (
                embedding_provider == "watsonx"
                and current_config.providers.watsonx.api_key
                and current_config.providers.watsonx.endpoint
                and current_config.providers.watsonx.project_id
            ):
                current_config.providers.watsonx.configured = True
                logger.info("Marked WatsonX as configured (chosen as embedding provider)")
            elif embedding_provider == "ollama" and current_config.providers.ollama.endpoint:
                current_config.providers.ollama.configured = True
                logger.info("Marked Ollama as configured (chosen as embedding provider)")
            elif (
                embedding_provider in current_config.providers.custom
                and current_config.providers.custom[embedding_provider].credentials
            ):
                current_config.providers.custom[embedding_provider].configured = True
                logger.info(
                    f"Marked {embedding_provider} as configured (chosen as embedding provider)"
                )

        should_ingest_sample_data = INGEST_SAMPLE_DATA
        if should_ingest_sample_data:
            await TelemetryClient.send_event(Category.ONBOARDING, MessageId.ORB_ONBOARD_SAMPLE_DATA)
            logger.info("Sample data ingestion enabled via environment variable")

        if not config_updated:
            return JSONResponse({"error": "No valid fields provided for update"}, status_code=400)

        # Validate provider setup before initializing OpenSearch index
        # Use full validation with completion tests (test_completion=True) to ensure provider health during onboarding
        try:
            # Validate LLM provider if set
            if body.llm_provider or body.llm_model:
                llm_provider = current_config.agent.llm_provider.lower()
                llm_provider_config = current_config.get_llm_provider_config()

                logger.info(
                    f"Validating LLM provider setup for {llm_provider} (full validation with completion test)"
                )
                await validate_provider_setup(
                    provider=llm_provider,
                    api_key=getattr(llm_provider_config, "api_key", None),
                    llm_model=current_config.agent.llm_model,
                    endpoint=getattr(llm_provider_config, "endpoint", None),
                    project_id=getattr(llm_provider_config, "project_id", None),
                    test_completion=True,  # Full validation with completion test - ensures provider health
                    credentials=current_config.providers.credential_values(llm_provider),
                    stored_credentials=current_config.providers.stored_credentials(llm_provider),
                )
                logger.info(
                    f"LLM provider setup validation completed successfully for {llm_provider}"
                )

            # Validate embedding provider if set
            if body.embedding_provider or body.embedding_model:
                embedding_provider = current_config.knowledge.embedding_provider.lower()
                embedding_provider_config = current_config.get_embedding_provider_config()

                logger.info(
                    f"Validating embedding provider setup for {embedding_provider} (full validation with completion test)"
                )
                await validate_provider_setup(
                    provider=embedding_provider,
                    api_key=getattr(embedding_provider_config, "api_key", None),
                    embedding_model=current_config.knowledge.embedding_model,
                    endpoint=getattr(embedding_provider_config, "endpoint", None),
                    project_id=getattr(embedding_provider_config, "project_id", None),
                    test_completion=True,  # Full validation with completion test - ensures provider health
                    credentials=current_config.providers.credential_values(
                        embedding_provider, kind="embedding"
                    ),
                    stored_credentials=current_config.providers.stored_credentials(
                        embedding_provider
                    ),
                )
                logger.info(
                    f"Embedding provider setup validation completed successfully for {embedding_provider}"
                )
        except Exception as e:
            logger.error(f"Provider validation failed: {str(e)}")
            return JSONResponse(
                {"error": sanitize_provider_error_content(e)},
                status_code=400,
            )

        # Ensure the Langflow service is ready before attempting to configure it
        try:
            await wait_for_langflow()
        except LangflowNotReadyError as e:
            message: str = "Aborted the Langflow service configuration process. The Langflow service is not ready."
            logger.error(message, error=str(e))

            return JSONResponse(
                {"error": message},
                status_code=503,
            )

        # Set Langflow global variables and model values based on provider configuration
        try:
            # Check if any provider-related fields were provided
            provider_fields_provided = any(
                [
                    body.openai_api_key,
                    body.anthropic_api_key,
                    body.watsonx_api_key,
                    body.watsonx_endpoint,
                    body.watsonx_project_id,
                    body.ollama_endpoint,
                    body.provider_credentials,
                ]
            )

            # Update global variables if any provider fields were provided
            # or if existing config has values (for OpenAI/Anthropic that might already be set)
            if (
                provider_fields_provided
                or current_config.providers.openai.api_key != ""
                or current_config.providers.anthropic.api_key != ""
                or current_config.providers.any_configured()
            ):
                await _update_langflow_global_variables(current_config, flows_service=flows_service)

            if body.embedding_provider or body.embedding_model:
                await _update_mcp_server_urls(
                    current_config,
                    session_manager=session_manager,
                    flows_service=flows_service,
                )

            if (
                body.llm_provider
                or body.llm_model
                or body.embedding_provider
                or body.embedding_model
            ):
                await _update_langflow_model_values(
                    current_config,
                    flows_service,
                    embedding_model=body.embedding_model,
                    embedding_provider=body.embedding_provider,
                    llm_model=body.llm_model,
                    llm_provider=body.llm_provider,
                )

        except Exception as e:
            logger.error(
                "Failed to set Langflow global variables and model values",
                error=str(e),
            )
            raise

        task_id = None

        # Initialize the OpenSearch index if embedding model is configured
        if body.embedding_model or body.embedding_provider:
            try:
                from config.settings import clients as app_clients
                from config.settings import (
                    get_openrag_service_token,
                    get_opensearch_username,
                )
                from main import init_index
                from utils.run_mode_utils import (
                    get_run_mode,
                    is_run_mode_on_prem,
                    is_run_mode_saas,
                )

                # Choose the admin identity for index/security setup, by run mode:
                #   saas/on_prem -> platform service token (JWT); admin from its claim
                #   oss          -> OpenSearch basic auth; OpenSearch username as admin
                # The matching client comes from the shared run-mode-aware helper.
                admin_username = None
                if is_run_mode_saas() or is_run_mode_on_prem():
                    service_token = get_openrag_service_token()
                    if not service_token:
                        raise RuntimeError(
                            "OPENRAG_SERVICE_TOKEN is required to determine the "
                            "OpenSearch admin identity during onboarding in "
                            f"{get_run_mode()} mode."
                        )
                    # Prefer the platform service token so onboarding pins the
                    # same admin identity as the startup security bootstrap
                    # (see app/lifespan.py).
                    from auth.ibm_auth import admin_username_from_service_jwt

                    admin_username = admin_username_from_service_jwt(service_token)
                    if not admin_username:
                        raise RuntimeError(
                            "OPENRAG_SERVICE_TOKEN has no 'username' or 'sub' claim; "
                            "cannot determine OpenSearch admin during onboarding"
                        )
                else:
                    admin_username = get_opensearch_username()

                opensearch_client = app_clients.create_index_admin_opensearch_client(
                    user.jwt_token if user else None
                )
                logger.info(
                    "Onboarding OpenSearch setup",
                    admin_username=admin_username,
                )

                logger.info("Initializing OpenSearch index after onboarding configuration")
                await init_index(opensearch_client, admin_username=admin_username)
                logger.info("OpenSearch index initialization completed successfully")
            except Exception:
                logger.exception("Failed to initialize OpenSearch index after onboarding")
                return JSONResponse(
                    {"error": "Failed to initialize OpenSearch index after onboarding"},
                    status_code=500,
                )

            # Handle sample data ingestion if requested
            if should_ingest_sample_data:
                try:
                    # Import the function here to avoid circular imports
                    from config.settings import IBM_AUTH_ENABLED
                    from main import ingest_default_documents_when_ready

                    if not config_manager.save_config_file(current_config):
                        logger.error("Failed to save embedding model to config")
                        return JSONResponse(
                            {"error": "Failed to save configuration"}, status_code=500
                        )

                    provider_health_cache.invalidate()

                    ingestion_jwt = (
                        user.jwt_token if IBM_AUTH_ENABLED and user and user.jwt_token else None
                    )

                    task_id = await ingest_default_documents_when_ready(
                        document_service,
                        models_service,
                        task_service,
                        langflow_file_service,
                        session_manager,
                        jwt_token=ingestion_jwt,
                    )
                    current_config.onboarding.openrag_docs_ingested_version = OPENRAG_VERSION
                    from main import (
                        _get_remote_docs_signature,
                        _should_use_url_default_docs_ingest,
                    )

                    if _should_use_url_default_docs_ingest():
                        current_config.onboarding.openrag_docs_remote_signature = (
                            await _get_remote_docs_signature(DEFAULT_DOCS_URL)
                        )
                    else:
                        current_config.onboarding.openrag_docs_remote_signature = None
                    logger.info("Sample data ingestion completed successfully")

                except Exception as e:
                    logger.error("Failed to complete sample data ingestion", error=str(e))
                    return JSONResponse(
                        {
                            "error": "Failed to ingest sample documents. Please try again or contact support."
                        },
                        status_code=500,
                    )

        if config_manager.save_config_file(current_config):
            provider_health_cache.invalidate()
            provider_error_log.clear()
            set_fields = [k for k, v in body.model_dump(exclude_unset=True).items()]
            logger.info(
                "Onboarding configuration updated successfully",
                updated_fields=set_fields,
            )

            # Mark config as edited and send telemetry with model information
            current_config.edited = True

            # Build metadata with selected models
            onboarding_metadata = {}
            if llm_provider_selected:
                onboarding_metadata["llm_provider"] = llm_provider_selected
            if llm_model_selected:
                onboarding_metadata["llm_model"] = llm_model_selected
            if embedding_provider_selected:
                onboarding_metadata["embedding_provider"] = embedding_provider_selected
            if embedding_model_selected:
                onboarding_metadata["embedding_model"] = embedding_model_selected

            await TelemetryClient.send_event(
                Category.ONBOARDING,
                MessageId.ORB_ONBOARD_CONFIG_EDITED,
                metadata=onboarding_metadata,
            )
            await TelemetryClient.send_event(
                Category.ONBOARDING,
                MessageId.ORB_ONBOARD_COMPLETE,
                metadata=onboarding_metadata,
            )
            logger.info("Configuration marked as edited after onboarding")

        else:
            await TelemetryClient.send_event(Category.ONBOARDING, MessageId.ORB_ONBOARD_FAILED)
            return JSONResponse({"error": "Failed to save configuration"}, status_code=500)

        # Refresh cached patched client so latest credentials take effect immediately
        await clients.refresh_patched_client()

        # Create OpenRAG Docs knowledge filter if sample data was ingested
        # Only create on embedding step to avoid duplicates (both LLM and embedding cards submit with sample_data)
        # Also skip if a filter was already created (e.g. user re-submits the embedding step)
        openrag_docs_filter_id = None
        if (
            should_ingest_sample_data
            and (body.embedding_provider or body.embedding_model)
            and not current_config.onboarding.openrag_docs_filter_id
        ):
            try:
                openrag_docs_filter_id = await _create_openrag_docs_filter(
                    knowledge_filter_service, session_manager, user
                )
                if openrag_docs_filter_id:
                    logger.info(
                        "OpenRAG Docs knowledge filter ready",
                        filter_id=openrag_docs_filter_id,
                    )
                    # Save the filter ID to the config
                    current_config.onboarding.openrag_docs_filter_id = openrag_docs_filter_id
                    if not config_manager.save_config_file(current_config):
                        logger.error("Failed to save openrag_docs_filter_id to config")
            except Exception as e:
                logger.error("Failed to create OpenRAG Docs knowledge filter", error=str(e))
                # Don't fail onboarding if filter creation fails

        return OnboardingResponse(
            message="Onboarding configuration updated successfully",
            edited=True,  # Confirm that config is now marked as edited
            sample_data_ingested=should_ingest_sample_data,
            openrag_docs_filter_id=openrag_docs_filter_id,
            task_id=task_id,
            chunk_size_adjusted_to=chunk_size_adjusted_to,
        )

    except Exception as e:
        logger.error("Failed to update onboarding settings", error=str(e))
        await TelemetryClient.send_event(Category.ONBOARDING, MessageId.ORB_ONBOARD_FAILED)
        return JSONResponse(
            {"error": "Failed to complete onboarding. Please try again or contact support."},
            status_code=500,
        )


async def update_onboarding_state(
    body: OnboardingStateBody,
    user: User = Depends(require_permission("config:write")),
) -> OnboardingStateResponse:
    """Update onboarding state in configuration"""
    try:
        await TelemetryClient.send_event(Category.ONBOARDING, MessageId.ORB_ONBOARD_START)

        # Convert body to dict excluding None values
        body_dict = body.model_dump(exclude_unset=True)

        # Update onboarding state using config manager (a monkey-patch
        # installed by WorkspaceConfigService mirrors this to the SQL
        # workspace_config table fire-and-forget).
        success = config_manager.update_onboarding_state(**body_dict)

        if not success:
            raise HTTPException(status_code=500, detail="Failed to update onboarding state")

        logger.info("[CONFIG] Onboarding state updated", fields=list(body.model_fields_set))

        return OnboardingStateResponse(
            message="Onboarding state updated successfully",
            updated_fields=list(body_dict.keys()),
        )

    except json.JSONDecodeError:
        return JSONResponse({"error": "Invalid JSON in request body"}, status_code=400)
    except Exception as e:
        logger.error(f"Error updating onboarding state: {str(e)}")
        return JSONResponse(
            {"error": "Failed to update onboarding state. Please try again or contact support."},
            status_code=500,
        )


async def rollback_onboarding(
    request: Request,
    body: RollbackBody | None = None,
    session_manager=Depends(get_session_manager),
    task_service=Depends(get_task_service),
    knowledge_filter_service=Depends(get_knowledge_filter_service),
    flows_service=Depends(get_flows_service),
    chat_service=Depends(get_chat_service),
    user: User = Depends(require_permission("config:write")),
) -> RollbackResponse:
    """Rollback onboarding configuration when sample data files fail.

    This will:
    1. Cancel all active tasks
    2. Delete successfully ingested knowledge documents
    3. Reset configuration to allow re-onboarding
    """
    try:
        # Get current configuration
        current_config = get_openrag_config()

        # Only allow rollback if config was marked as edited (onboarding completed)
        if not current_config.edited:
            return JSONResponse(
                {"error": "No onboarding configuration to rollback"}, status_code=400
            )

        logger.warning("[CONFIG] Rolling back onboarding configuration due to file failures")

        # Get all tasks for the user
        all_tasks = task_service.get_all_tasks(user.user_id)

        cancelled_tasks = []
        deleted_files = []

        # Delete knowledge filters created during onboarding
        try:

            async def remove_filter(filter_id: str | None):
                if filter_id and knowledge_filter_service:
                    try:
                        result = await knowledge_filter_service.delete_knowledge_filter(
                            filter_id, user.user_id, user.jwt_token
                        )
                        if result and result.get("success"):
                            logger.info(f"Deleted knowledge filter {filter_id}")
                        else:
                            error_msg = result.get("error") if result else "Unknown error"
                            logger.warning(
                                f"Could not delete knowledge filter {filter_id}: {error_msg}"
                            )
                    except Exception as e:
                        logger.warning(f"Exception deleting knowledge filter {filter_id}: {str(e)}")

            if getattr(current_config.onboarding, "openrag_docs_filter_id", None):
                await remove_filter(current_config.onboarding.openrag_docs_filter_id)
                current_config.onboarding.openrag_docs_filter_id = None

            if getattr(current_config.onboarding, "user_doc_filter_id", None):
                await remove_filter(current_config.onboarding.user_doc_filter_id)
                current_config.onboarding.user_doc_filter_id = None
        except Exception as e:
            logger.error(f"Error while cleaning up knowledge filters: {e}")

        # Cancel all active tasks and collect successfully ingested files
        from session_manager import AnonymousUser

        anonymous_user_id = AnonymousUser().user_id

        for task_data in all_tasks:
            task_id = task_data.get("task_id")
            task_status = task_data.get("status")

            # Cancel active tasks (pending, running, processing)
            if task_status in ["pending", "running", "processing"]:
                try:
                    success = await task_service.cancel_task(user.user_id, task_id)
                    if success:
                        cancelled_tasks.append(task_id)
                        logger.info(f"Cancelled task {task_id}")
                except Exception as e:
                    logger.error(f"Failed to cancel task {task_id}: {str(e)}")

            # Delete all files associated with any task, regardless of whether
            # the task failed or completed, to ensure no partial chunks remain in OpenSearch.
            files = task_data.get("files", {})
            if isinstance(files, dict):
                for file_path, file_info in files.items():
                    if isinstance(file_info, dict):
                        filename = file_info.get("filename") or file_path.split("/")[-1]
                        if filename:
                            try:
                                opensearch_client = session_manager.get_user_opensearch_client(
                                    user.user_id, user.jwt_token
                                )
                                from config.settings import clients, get_index_name
                                from utils.opensearch_delete import (
                                    collect_visible_document_ids,
                                    delete_document_ids,
                                )
                                from utils.opensearch_queries import (
                                    build_owned_filename_query,
                                )

                                index_name = get_index_name()
                                document_ids = await collect_visible_document_ids(
                                    opensearch_client,
                                    index=index_name,
                                    query=build_owned_filename_query(filename, user.user_id),
                                )
                                deleted_count = await delete_document_ids(
                                    clients.opensearch,
                                    index=index_name,
                                    document_ids=document_ids,
                                )
                                if deleted_count > 0:
                                    deleted_files.append(filename)
                                    logger.info(
                                        f"Deleted {deleted_count} chunks for filename {filename}"
                                    )
                            except Exception as e:
                                logger.error(f"Failed to delete documents for {filename}: {str(e)}")

            # Wipe the task completely from memory so the frontend doesn't see it anymore
            for check_user_id in [user.user_id, anonymous_user_id]:
                if (
                    check_user_id in task_service.task_store
                    and task_id in task_service.task_store[check_user_id]
                ):
                    task_service._task_locks.pop(task_id, None)
                    task_service.task_store[check_user_id].pop(task_id, None)
                    logger.info(
                        f"Purged task {task_id} completely from task_store for user {check_user_id}"
                    )

        # 4. Reset Langflow flows to their original state
        reset_flows_count = 0
        for flow_type in ["nudges", "retrieval", "ingest"]:
            try:
                result = await flows_service.reset_langflow_flow(flow_type)
                if result.get("success"):
                    reset_flows_count += 1
                    logger.info(f"Successfully reset {flow_type} flow during rollback")
                else:
                    logger.warning(
                        f"Failed to reset {flow_type} flow during rollback: {result.get('error')}"
                    )
            except Exception as e:
                logger.error(f"Error resetting {flow_type} flow during rollback: {e}")

        # 5. Delete all user conversations
        deleted_conversations_count = 0
        try:
            result = await chat_service.delete_all_user_sessions(user.user_id)
            if result.get("success"):
                deleted_conversations_count = result.get("deleted_count", 0)
                logger.info(f"Deleted {deleted_conversations_count} conversations during rollback")
        except Exception as e:
            logger.error(f"Error deleting conversations during rollback: {e}")

        # Clear embedding provider and model settings
        current_config.knowledge.embedding_provider = "openai"  # Reset to default
        current_config.knowledge.embedding_model = ""
        current_config.onboarding.openrag_docs_ingested_version = None
        current_config.onboarding.openrag_docs_remote_signature = None
        current_config.onboarding.assistant_message = None
        current_config.onboarding.selected_nudge = None
        current_config.onboarding.card_steps = None
        current_config.onboarding.upload_steps = None

        embedding_only = body.embedding_only if body else False

        # Mark config as not edited so user can go through onboarding again
        if not embedding_only:
            current_config.edited = False
            current_config.onboarding.current_step = 0
            # Also clear LLM provider and model settings when doing a full rollback
            current_config.agent.llm_provider = "openai"  # Reset to default
            current_config.agent.llm_model = ""
        else:
            # When rolling back embedding only, we keep edited=True
            # and set current_step to 1 (which is the embedding step)
            current_config.onboarding.current_step = 1

        # Save the rolled back configuration manually
        try:
            import yaml

            config_file = config_manager.config_file

            # Ensure directory exists
            config_file.parent.mkdir(parents=True, exist_ok=True)

            # Save config with current edited state
            with open(config_file, "w") as f:
                yaml.dump(current_config.to_dict(), f, default_flow_style=False, indent=2)

            # Update cached config
            config_manager._config = current_config

            logger.info(
                f"Successfully saved rolled back configuration with edited={current_config.edited}"
            )
        except Exception as e:
            logger.error(f"Failed to save rolled back configuration: {e}")
            return JSONResponse(
                {"error": "Failed to save rolled back configuration"}, status_code=500
            )

        logger.info(
            f"Successfully rolled back onboarding configuration. "
            f"Cancelled {len(cancelled_tasks)} tasks, deleted {len(deleted_files)} files, "
            f"reset {reset_flows_count} flows, deleted {deleted_conversations_count} conversations"
        )
        await TelemetryClient.send_event(Category.ONBOARDING, MessageId.ORB_ONBOARD_ROLLBACK)

        return RollbackResponse(
            message="Onboarding configuration rolled back successfully",
            cancelled_tasks=len(cancelled_tasks),
            deleted_files=len(deleted_files),
            reset_flows=reset_flows_count,
            deleted_conversations=deleted_conversations_count,
        )

    except Exception:
        logger.exception("Failed to rollback onboarding configuration")
        return JSONResponse({"error": "Failed to rollback onboarding"}, status_code=500)


async def update_docling_preset(
    body: DoclingPresetBody,
    session_manager=Depends(get_session_manager),
    user: User = Depends(require_permission("config:write")),
) -> DoclingPresetResponse:
    """Update docling settings in the ingest flow - deprecated endpoint, use /settings instead"""
    try:
        # Support old preset-based API for backwards compatibility
        if body.preset:
            # Map old presets to new toggle settings
            preset_map = {
                "standard": {
                    "table_structure": False,
                    "ocr": False,
                    "picture_descriptions": False,
                },
                "ocr": {
                    "table_structure": False,
                    "ocr": True,
                    "picture_descriptions": False,
                },
                "picture_description": {
                    "table_structure": False,
                    "ocr": True,
                    "picture_descriptions": True,
                },
                "VLM": {
                    "table_structure": False,
                    "ocr": False,
                    "picture_descriptions": False,
                },
            }

            preset = body.preset
            if preset not in preset_map:
                raise HTTPException(
                    status_code=400,
                    detail=f"Invalid preset '{preset}'. Valid presets: {', '.join(preset_map.keys())}",
                )

            settings_toggles = preset_map[preset]
        else:
            # Support new toggle-based API
            settings_toggles = {
                "table_structure": (
                    body.table_structure if body.table_structure is not None else False
                ),
                "ocr": body.ocr if body.ocr is not None else False,
                "picture_descriptions": (
                    body.picture_descriptions if body.picture_descriptions is not None else False
                ),
            }

        # 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
        flows_service = _get_flows_service()
        await flows_service.update_flow_docling_preset("custom", preset_config_dict)

        logger.info("Successfully updated docling settings in ingest flow")

        return DoclingPresetResponse(
            message="Successfully updated docling settings",
            settings=settings_toggles,
            preset_config=preset_config,
        )
    except HTTPException:
        # Preserve intended HTTP status codes (e.g. 400 for an invalid preset)
        raise
    except Exception as e:
        logger.error("Failed to update docling settings", error=str(e))
        raise HTTPException(status_code=500, detail="Failed to update docling settings") from e


async def refresh_openrag_docs(
    document_service=Depends(get_document_service),
    task_service=Depends(get_task_service),
    models_service=Depends(get_models_service),
    langflow_file_service=Depends(get_langflow_file_service),
    session_manager=Depends(get_session_manager),
    user: User = Depends(require_permission("config:write")),
) -> RefreshOpenRAGDocsResponse:
    """Manually refresh OpenRAG docs ingestion on demand."""
    try:
        from main import refresh_default_openrag_docs

        refreshed = await refresh_default_openrag_docs(
            document_service=document_service,
            models_service=models_service,
            task_service=task_service,
            langflow_file_service=langflow_file_service,
            session_manager=session_manager,
            force=True,
            reason="manual",
            jwt_token=user.jwt_token if getattr(user, "jwt_token", None) else None,
        )
        return RefreshOpenRAGDocsResponse(
            message=(
                "OpenRAG docs were refreshed."
                if refreshed
                else "OpenRAG docs refresh was skipped by current configuration."
            ),
            refreshed=refreshed,
        )
    except Exception as e:
        logger.error("Failed to refresh OpenRAG docs on demand", error=str(e))
        raise HTTPException(
            status_code=500,
            detail="Failed to refresh OpenRAG docs. Please try again or contact support.",
        ) from e