Skip to content

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

Python
24.8 KB
Raw Blame
"""Langflow synchronization helpers for settings/onboarding flows.

Pushes the latest user config (provider creds, model selection, system
prompt, docling toggles, chunk sizes, MCP server URLs) into Langflow
flows and global variables. Also exposes `reapply_all_settings`, called
from `services/startup_orchestrator.py` when flow-reset detection
triggers a full re-sync.

Lifted verbatim from the original `src/api/settings.py` (lines 46,
1458–1684, 1725–1770). No behavior change.
"""

import asyncio

from api.settings.helpers import (
    _EMBEDDING_PROVIDER_NAMES,
    _LLM_PROVIDER_NAMES,
    _configured_provider_names,
    _get_flows_service,
)
from config import settings
from config.settings import clients, get_openrag_config
from services.docling_service import get_docling_preset_configs
from utils.logging_config import get_logger

logger = get_logger(__name__)

# Strong refs to in-flight async post-save sync tasks so they aren't
# garbage-collected mid-flight when the originating request returns.
_background_tasks: set[asyncio.Task] = set()

LANGFLOW_CREDENTIAL_GLOBAL_VARIABLES = frozenset(
    {
        "JWT",
        "OPENAI_API_KEY",
        "OPENRAG_LLM_TOKEN",
        "OPENRAG_INGEST_TOKEN",
        "OPENSEARCH_PASSWORD",
    }
)

LANGFLOW_GENERIC_GLOBAL_VARIABLES = frozenset(
    {
        "DOCLING_SERVE_URL",
        "DOCLING_SERVE_VERIFY_SSL",
        "DOCLING_TASK_ID",
        "FILESIZE",
        "MIMETYPE",
        "OPENRAG-QUERY-FILTER",
        "OPENRAG_INGEST_BATCH_SIZE",
        "OPENRAG_INGEST_RUN_ID",
        "OPENRAG_INGEST_URL",
        "OPENRAG_LLM_BASE_URL",
        "OPENSEARCH_INDEX_NAME",
        "OPENSEARCH_URL",
        "SELECTED_EMBEDDING_MODEL",
        "SELECTED_EMBEDDING_PROVIDER",
        "SELECTED_EMBEDDING_MODEL_PROVIDER",
        "SELECTED_LANGUAGE_MODEL",
        "SELECTED_LANGUAGE_MODEL_PROVIDER",
    }
)


def _langflow_global_variable_type(name: str) -> str:
    if name in LANGFLOW_GENERIC_GLOBAL_VARIABLES:
        return "Generic"
    return "Credential"


async def _upsert_langflow_global_variable(name: str, value: str, modify: bool = True):
    await clients._create_langflow_global_variable(
        name,
        value,
        modify=modify,
        variable_type=_langflow_global_variable_type(name),
    )


def _string_value(value) -> str:
    return "" if value is None else str(value)


def _required_generic_global_values(config) -> dict[str, str]:
    knowledge = getattr(config, "knowledge", None)
    agent = getattr(config, "agent", None)

    return {
        "DOCLING_SERVE_URL": settings.get_langflow_docling_url(),
        "DOCLING_SERVE_VERIFY_SSL": str(settings.DOCLING_SERVE_VERIFY_SSL).lower(),
        "DOCLING_TASK_ID": "None",
        "FILESIZE": "0",
        "MIMETYPE": "None",
        "OPENRAG-QUERY-FILTER": "{}",
        "OPENRAG_INGEST_BATCH_SIZE": "100",
        "OPENRAG_INGEST_RUN_ID": "OPENRAG_INGEST_RUN_ID",
        "OPENRAG_INGEST_TOKEN": "OPENRAG_INGEST_TOKEN",
        "OPENRAG_INGEST_URL": "OPENRAG_INGEST_URL",
        "OPENRAG_LLM_BASE_URL": settings.get_langflow_llm_base_url(),
        "OPENSEARCH_INDEX_NAME": _string_value(getattr(knowledge, "index_name", None))
        or "documents",
        "OPENSEARCH_URL": settings.get_langflow_opensearch_url(),
        "SELECTED_EMBEDDING_MODEL": _string_value(getattr(knowledge, "embedding_model", None))
        or "text-embedding-3-small",
        "SELECTED_EMBEDDING_PROVIDER": _string_value(getattr(knowledge, "embedding_provider", None))
        or "openai",
        # Legacy agent-flow compatibility; this is the proxy client, not the
        # upstream provider. Remove with that flow template in a future major release.
        "SELECTED_EMBEDDING_MODEL_PROVIDER": "OpenAI",
        "SELECTED_LANGUAGE_MODEL": _string_value(getattr(agent, "llm_model", None))
        or "gpt-4o-mini",
        "SELECTED_LANGUAGE_MODEL_PROVIDER": "OpenAI",
    }


# Credential names that must exist so load_from_db fields resolve.
# Langflow treats an empty Credential value as missing
# (`"{name} variable not found."`). Keep a non-empty placeholder; runtime
# headers overwrite it with the hop token on each Langflow run.
LANGFLOW_RUNTIME_CREDENTIAL_PLACEHOLDERS = frozenset(
    {
        "OPENRAG_LLM_TOKEN",
    }
)
LANGFLOW_RUNTIME_CREDENTIAL_PLACEHOLDER_VALUE = "None"


async def ensure_required_langflow_global_variables(config=None):
    """Ensure plain-string globals are Generic and remove any Apply To (default_fields) fields.

    Credential placeholders stay non-empty so Langflow can resolve load_from_db fields.
    """
    config = config or get_openrag_config()
    required_values = _required_generic_global_values(config)

    existing_by_name = {}
    try:
        response = await clients.langflow_request("GET", "/api/v1/variables/")
        if response.status_code == 200:
            existing_variables = response.json()
            existing_by_name = {v.get("name"): v for v in existing_variables if v.get("name")}
        else:
            logger.warning(
                "Could not fetch Langflow variables at startup",
                status_code=response.status_code,
            )
            return
    except Exception as e:
        logger.warning("Could not fetch Langflow variables at startup", error=str(e))
        return

    # Update or fix existing variables in a single operation per variable
    for name, var in existing_by_name.items():
        try:
            var_id = var.get("id")
            if not var_id:
                continue

            is_generic = name in LANGFLOW_GENERIC_GLOBAL_VARIABLES
            target_type = "Generic" if is_generic else var.get("type", "Credential")

            curr_type = var.get("type")
            curr_val = var.get("value", "")
            has_default_fields = bool(var.get("default_fields"))

            target_val = _string_value(required_values.get(name)) if is_generic else curr_val

            # Langflow rejects an empty value with 400 "Variable value cannot be
            # empty". Optional providers (Ollama, watsonx) resolve to "" when
            # unconfigured, so keep whatever Langflow already holds instead of
            # pushing a value it will refuse. This matters most in the type
            # migration below: the DELETE has already landed by then, so a
            # refused recreate would drop the variable entirely.
            sync_value = is_generic and bool(target_val)
            if not sync_value:
                target_val = curr_val

            if curr_type != target_type:
                if not target_val:
                    # The retained value (see sync_value above) is also empty: the
                    # DELETE below would succeed but the recreate POST would send ""
                    # and get rejected, dropping the variable entirely. Defer the
                    # type migration until the variable actually has a value.
                    logger.debug(
                        "Deferring Langflow global variable type migration until configured",
                        variable_name=name,
                        old_type=curr_type,
                        new_type=target_type,
                    )
                    continue

                logger.info(
                    "Migrating Langflow global variable type",
                    variable_name=name,
                    old_type=curr_type,
                    new_type=target_type,
                )
                del_resp = await clients.langflow_request("DELETE", f"/api/v1/variables/{var_id}")
                if not (200 <= del_resp.status_code < 300):
                    raise RuntimeError(
                        f"Failed to delete Langflow global variable {name!r}: status_code={del_resp.status_code}"
                    )
                recreate_payload = {
                    "name": name,
                    "value": target_val,
                    "default_fields": [],
                    "type": target_type,
                }
                recreate_resp = await clients.langflow_request(
                    "POST", "/api/v1/variables/", json=recreate_payload
                )
                if not (200 <= recreate_resp.status_code < 300):
                    raise RuntimeError(
                        f"Failed to recreate Langflow global variable {name!r}: status_code={recreate_resp.status_code}"
                    )
            elif has_default_fields or (sync_value and curr_val != target_val):
                logger.info(
                    "Updating Langflow global variable", variable_name=name, variable_id=var_id
                )
                patch_payload = {
                    "id": var_id,
                    "name": name,
                    "default_fields": [],
                    "type": target_type,
                }
                if sync_value:
                    patch_payload["value"] = target_val
                patch_resp = await clients.langflow_request(
                    "PATCH",
                    f"/api/v1/variables/{var_id}",
                    json=patch_payload,
                    idempotent=True,
                )
                if not (200 <= patch_resp.status_code < 300):
                    raise RuntimeError(
                        f"Failed to patch Langflow global variable {name!r}: status_code={patch_resp.status_code}"
                    )
        except Exception as e:
            logger.warning(
                "Failed to update Langflow global variable", variable_name=name, error=str(e)
            )

    # Create missing generic variables
    for name in sorted(LANGFLOW_GENERIC_GLOBAL_VARIABLES):
        if name not in existing_by_name:
            try:
                target_val = _string_value(required_values.get(name, ""))
                if not target_val:
                    # Langflow rejects an empty value with 400. Variables sourced
                    # from an unconfigured optional provider (OLLAMA_BASE_URL,
                    # WATSONX_PROJECT_ID, WATSONX_URL) have nothing to set yet;
                    # they are created once that provider is configured.
                    logger.debug(
                        "Skipping Langflow global variable with no configured value",
                        variable_name=name,
                    )
                    continue
                await _upsert_langflow_global_variable(name, target_val)
            except Exception as e:
                logger.warning(
                    "Failed to create Langflow global variable", variable_name=name, error=str(e)
                )

    # Non-fatal like every other Langflow call in this function: a transient
    # failure here must not take down a startup path that never raised before.
    for name in sorted(LANGFLOW_RUNTIME_CREDENTIAL_PLACEHOLDERS):
        try:
            await _upsert_langflow_global_variable(
                name, LANGFLOW_RUNTIME_CREDENTIAL_PLACEHOLDER_VALUE
            )
        except Exception as e:
            logger.warning(
                "Failed to create Langflow credential placeholder",
                variable_name=name,
                error=str(e),
            )

    try:
        await _update_mcp_server_urls(config)
    except Exception as e:
        logger.warning(
            "Failed to update MCP servers after ensuring global variables",
            error=str(e),
        )


async def _update_langflow_global_variables(config, flows_service=None):
    """Push model selection and the LLM proxy URL into Langflow. No provider secrets."""
    errors: list[str] = []

    async def _safe_upsert(name: str, value: str):
        try:
            await _upsert_langflow_global_variable(name, value)
            logger.info("Set global variable in Langflow", variable_name=name)
        except Exception as e:
            logger.warning(
                "Failed to set global variable in Langflow", variable_name=name, error=str(e)
            )
            errors.append(f"{name}: {e}")

    await _safe_upsert("OPENRAG_LLM_BASE_URL", settings.get_langflow_llm_base_url())

    # Every model runs through the OpenAI-compatible LLM proxy, so the provider
    # is always "OpenAI" here and no provider secret is pushed to Langflow.
    knowledge = getattr(config, "knowledge", None)
    if getattr(knowledge, "embedding_model", None):
        await _safe_upsert("SELECTED_EMBEDDING_MODEL", config.knowledge.embedding_model)
    await _safe_upsert(
        "SELECTED_EMBEDDING_PROVIDER",
        getattr(knowledge, "embedding_provider", None) or "openai",
    )
    # Kept for the legacy agent-flow header template. It selects Langflow's
    # OpenAI-compatible proxy client; remove in a future major release.
    await _safe_upsert("SELECTED_EMBEDDING_MODEL_PROVIDER", "OpenAI")

    agent = getattr(config, "agent", None)
    if getattr(agent, "llm_model", None):
        await _safe_upsert("SELECTED_LANGUAGE_MODEL", config.agent.llm_model)
    await _safe_upsert("SELECTED_LANGUAGE_MODEL_PROVIDER", "OpenAI")

    # Runtime headers overwrite these with the hop token on each Langflow run;
    # they only need to exist and stay non-empty so load_from_db can resolve them.
    for name in sorted(LANGFLOW_RUNTIME_CREDENTIAL_PLACEHOLDERS):
        await _safe_upsert(name, LANGFLOW_RUNTIME_CREDENTIAL_PLACEHOLDER_VALUE)

    if errors:
        raise RuntimeError(f"Failed to update Langflow global variable(s): {', '.join(errors)}")


async def _run_async_post_save_langflow_updates(
    session_manager,
    update_mcp_servers: bool,
    update_model_values: bool = False,
    models_service=None,
    update_llm: bool = True,
    update_embedding: bool = True,
    update_global_variables: bool = False,
) -> None:
    """Apply post-save Langflow synchronization asynchronously."""
    try:
        current_config = get_openrag_config()
        flows_service = _get_flows_service()

        # Refresh model registry so get_litellm_model_name(strict=True) sees the
        # updated provider list — force_remove skips _affected_embedding_models which
        # is the usual registry refresh trigger.
        if models_service is not None:
            await models_service.update_model_registry()

        # Update global variables only when provider credentials or endpoints change
        if update_global_variables:
            await _update_langflow_global_variables(current_config, flows_service=flows_service)

        # Update LLM client credentials when embedding selection changes
        if update_mcp_servers:
            await _update_mcp_server_urls(
                current_config, session_manager, flows_service=flows_service
            )

        # Update model values if provider/model changed (including removals/fallbacks)
        if update_model_values:
            await _update_langflow_model_values(
                current_config,
                flows_service,
                llm_model=current_config.agent.llm_model if update_llm else None,
                llm_provider=current_config.agent.llm_provider if update_llm else None,
                embedding_model=current_config.knowledge.embedding_model
                if update_embedding
                else None,
                embedding_provider=current_config.knowledge.embedding_provider
                if update_embedding
                else None,
            )

        logger.info("Completed asynchronous Langflow post-save sync")
    except Exception as e:
        # Do not fail user request if async sync fails; keep parity with existing behavior.
        logger.error(f"Failed to update Langflow settings asynchronously: {str(e)}")


async def _update_mcp_server_urls(config, session_manager=None, flows_service=None):
    """Update MCP server URLs (patch localhost and convert to streamable HTTP)."""
    try:
        from services.langflow_mcp_service import LangflowMCPService

        mcp_service = LangflowMCPService()
        result = await mcp_service.update_all_mcp_server_urls()
        logger.info("Updated MCP server URLs after settings change", **result)

    except Exception as mcp_error:
        logger.warning(f"Failed to update MCP server URLs after settings change: {str(mcp_error)}")
        # Don't fail the entire settings update if MCP update fails


async def _upsert_selected_model_variable(name: str, value: str | None) -> None:
    """Push a required SELECTED_* global variable to Langflow.

    Flows no longer carry per-provider embedding/LLM nodes for
    `change_langflow_model_value` to patch — they use the single
    OpenAI-compatible component that reads its model from this global variable.
    That makes this the only channel by which a model change reaches a flow, so
    it has to follow every model change, not just credential changes.
    """
    if not value:
        return
    await _upsert_langflow_global_variable(name, value)
    logger.info("Set global variable in Langflow", variable_name=name)


async def _update_langflow_model_values(
    config,
    flows_service,
    llm_model=None,
    llm_provider=None,
    embedding_model=None,
    embedding_provider=None,
):
    """Update model values across Langflow flows for all configured providers"""
    try:
        if llm_model or llm_provider:
            effective_llm_provider = (llm_provider or config.agent.llm_provider).lower()
            if llm_provider and llm_provider.lower() != config.agent.llm_provider.lower():
                effective_llm_model = llm_model  # do not fall back; force caller to specify
            else:
                effective_llm_model = llm_model or config.agent.llm_model
            await _upsert_selected_model_variable("SELECTED_LANGUAGE_MODEL", effective_llm_model)
            result = await flows_service.change_langflow_model_value(
                effective_llm_provider, llm_model=effective_llm_model, force_llm_update=True
            )

            logger.info(
                f"Successfully updated Langflow flows for LLM provider {effective_llm_provider}",
                result=result,
            )

        if embedding_model or embedding_provider:
            configured_embedding_provider = config.knowledge.embedding_provider or "openai"
            effective_embedding_provider = (
                embedding_provider or configured_embedding_provider
            ).lower()
            if (
                embedding_provider
                and embedding_provider.lower() != configured_embedding_provider.lower()
            ):
                effective_embedding_model = (
                    embedding_model  # do not fall back; force caller to specify
                )
            else:
                effective_embedding_model = embedding_model or config.knowledge.embedding_model
            await _upsert_selected_model_variable(
                "SELECTED_EMBEDDING_MODEL", effective_embedding_model
            )
            await _upsert_selected_model_variable(
                "SELECTED_EMBEDDING_PROVIDER", effective_embedding_provider
            )
            result = await flows_service.change_langflow_model_value(
                effective_embedding_provider,
                embedding_model=effective_embedding_model,
                force_embedding_update=True,
            )

            logger.info(
                f"Successfully updated Langflow flows for embedding provider {effective_embedding_provider}",
                result=result,
            )

        if not (embedding_model or embedding_provider or llm_model or llm_provider):
            # 1. Update ALL configured LLM providers.
            # Regression fix (#1587): the no-argument fallback used by
            # reapply_all_settings previously only reapplied embedding providers,
            # leaving LLM model values unset whenever flows were reset.
            llm_providers = _configured_provider_names(config, _LLM_PROVIDER_NAMES)

            current_llm_provider = config.agent.llm_provider.lower()
            for provider in llm_providers:
                # Use configured model for current provider, or None (first available) for others
                provider_llm_model = (
                    config.agent.llm_model if provider == current_llm_provider else None
                )
                await flows_service.change_langflow_model_value(
                    provider, llm_model=provider_llm_model, force_llm_update=True
                )
                logger.info(f"Successfully updated Langflow flows for LLM provider {provider}")

            # 2. Update ALL configured embedding providers
            embedding_providers = _configured_provider_names(config, _EMBEDDING_PROVIDER_NAMES)

            current_embedding_provider = (config.knowledge.embedding_provider or "openai").lower()
            for provider in embedding_providers:
                # Use configured model for current provider, or None (first available) for others
                embedding_model = (
                    config.knowledge.embedding_model
                    if provider == current_embedding_provider
                    else None
                )
                await flows_service.change_langflow_model_value(
                    provider, embedding_model=embedding_model, force_embedding_update=True
                )
                logger.info(
                    f"Successfully updated Langflow flows for embedding provider {provider}"
                )
    except Exception as e:
        logger.error(f"Failed to update Langflow model values: {str(e)}")
        raise


async def _update_langflow_system_prompt(config, flows_service):
    """Update system prompt in chat flow"""
    try:
        await flows_service.update_chat_flow_system_prompt(config.agent.system_prompt)
        logger.info("Successfully updated chat flow system prompt")
    except Exception as e:
        logger.error(f"Failed to update chat flow system prompt: {str(e)}")
        raise


async def _update_langflow_docling_settings(config, flows_service):
    """Update docling settings in ingest flow"""
    try:
        preset_config = get_docling_preset_configs(
            table_structure=config.knowledge.table_structure,
            ocr=config.knowledge.ocr,
            picture_descriptions=config.knowledge.picture_descriptions,
            ocr_languages=config.knowledge.ocr_languages,
        )
        await flows_service.update_flow_docling_preset("custom", preset_config)
        logger.info("Successfully updated docling settings in ingest flow")
    except Exception as e:
        logger.error(f"Failed to update docling settings: {str(e)}")
        raise


async def _update_langflow_chunk_settings(config, flows_service):
    """Update chunk size and overlap in ingest flow"""
    try:
        await flows_service.update_ingest_flow_chunk_size(config.knowledge.chunk_size)
        logger.info(f"Successfully updated ingest flow chunk size to {config.knowledge.chunk_size}")

        await flows_service.update_ingest_flow_chunk_overlap(config.knowledge.chunk_overlap)
        logger.info(
            f"Successfully updated ingest flow chunk overlap to {config.knowledge.chunk_overlap}"
        )
    except Exception as e:
        logger.error(f"Failed to update chunk settings: {str(e)}")
        raise


async def reapply_all_settings(session_manager=None):
    """
    Reapply all current configuration settings to Langflow flows and global variables.
    This is called when flows are detected to have been reset.
    """
    try:
        config = get_openrag_config()
        flows_service = _get_flows_service()

        logger.info("Reapplying all settings to Langflow flows and global variables")

        # Update MCP server URLs (patch localhost and convert to streamable HTTP)
        await _update_mcp_server_urls(config, session_manager, flows_service=flows_service)

        # Update all Langflow settings using helper functions
        try:
            await _update_langflow_global_variables(config, flows_service=flows_service)
        except Exception as e:
            logger.error(f"Failed to update Langflow global variables: {str(e)}")
            # Continue with other updates even if global variables fail

        try:
            await _update_langflow_model_values(config, flows_service)
        except Exception as e:
            logger.error(f"Failed to update Langflow model values: {str(e)}")

        try:
            await _update_langflow_system_prompt(config, flows_service)
        except Exception as e:
            logger.error(f"Failed to update Langflow system prompt: {str(e)}")

        try:
            await _update_langflow_docling_settings(config, flows_service)
        except Exception as e:
            logger.error(f"Failed to update Langflow docling settings: {str(e)}")

        try:
            await _update_langflow_chunk_settings(config, flows_service)
        except Exception as e:
            logger.error(f"Failed to update Langflow chunk settings: {str(e)}")

        try:
            await flows_service.enable_mcp_none_for_url_ingest_flow()
        except Exception as e:
            logger.error(f"Failed to configure unauthenticated MCP for URL ingest flow: {str(e)}")

        logger.info("Successfully reapplied all settings to Langflow flows")

    except Exception as e:
        logger.error(f"Failed to reapply settings: {str(e)}")
        raise