Skip to content

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

Python
11.6 KB
Raw Blame
"""General helpers for the settings/onboarding endpoints.

Provider-fallback selection, embedding-model conflict detection (used to
warn before removing a provider whose embeddings are still indexed), the
OpenRAG-docs knowledge-filter creator, and a flows-service factory.

Lifted verbatim from the original `src/api/settings.py` (lines 371–480 and
1388–1455). No behavior change.
"""

from datetime import UTC
from typing import Any

from fastapi.responses import JSONResponse

from config.settings import clients, is_no_auth_mode
from utils.logging_config import get_logger

logger = get_logger(__name__)


# Provider names in priority order. LLM supports anthropic; embeddings do not.
_LLM_PROVIDER_NAMES = ("openai", "anthropic", "watsonx", "ollama")
_EMBEDDING_PROVIDER_NAMES = ("openai", "watsonx", "ollama")


def _has_other_configured_provider(config, excluding: str) -> bool:
    """Return True if at least one other provider with embedding support is configured (excluding Anthropic)."""
    providers = config.providers
    for key, value in providers.custom.items():
        if key != excluding and key != "anthropic" and getattr(value, "configured", False):
            return True
    if excluding != "openai" and providers.openai.configured:
        return True
    if excluding != "watsonx" and providers.watsonx.configured:
        return True
    if excluding != "ollama" and providers.ollama.configured:
        return True
    return False


def _configured_provider_names(config, provider_names) -> list:
    """Return the provider names from `provider_names` marked configured in the OpenRAG config."""
    providers = config.providers
    configured = [name for name in provider_names if getattr(providers, name).configured]
    from services.model_catalog import catalog

    entries = {entry["key"]: entry for entry in catalog()["providers"]}
    embedding = tuple(provider_names) == _EMBEDDING_PROVIDER_NAMES
    for provider, value in providers.custom.items():
        entry = entries.get(provider)
        supports_kind = bool(
            entry and (entry["embedding_models"] if embedding else entry["models"])
        )
        if value.configured and supports_kind and provider not in configured:
            configured.append(provider)
    return configured


def _first_configured_llm_provider(config, excluding: str) -> str:
    """Return the first configured LLM provider that isn't `excluding`.

    Only providers this run mode shows are eligible: falling back to one the
    config file hides would leave Settings pointing at a provider whose card
    the user cannot see (see ``config/model_providers.yaml``).
    """
    from config.model_providers import visible_provider_keys

    visible = visible_provider_keys()
    for p in _LLM_PROVIDER_NAMES:
        if p != excluding and p in visible and getattr(config.providers, p).configured:
            return p
    for provider, value in config.providers.custom.items():
        if provider != excluding and provider in visible and value.configured:
            return provider
    return "openai"


def _first_configured_embedding_provider(config, excluding: str) -> str:
    """Return the first configured embedding provider that isn't `excluding`, or "" if none.

    Providers hidden in this run mode are skipped, as in
    ``_first_configured_llm_provider``.
    """
    from config.model_providers import visible_provider_keys

    visible = visible_provider_keys()
    for p in _EMBEDDING_PROVIDER_NAMES:
        if p != excluding and p in visible and getattr(config.providers, p).configured:
            return p
    from services.model_catalog import catalog

    entries = {entry["key"]: entry for entry in catalog()["providers"]}
    for provider, value in config.providers.custom.items():
        if provider != excluding and provider in visible and value.configured:
            entry = entries.get(provider)
            if entry and entry["embedding_models"]:
                return provider
    return ""


def _default_llm_model(provider: str) -> str:
    """Return the static preferred LLM model for a provider.

    OpenAI/Anthropic have stable preferred defaults. Ollama/watsonx model IDs are
    dynamic from the live provider list — return empty so the frontend picks from
    the live list (default flag or first available).
    """
    from config.model_constants import (
        ANTHROPIC_DEFAULT_LANGUAGE_MODEL,
        OPENAI_DEFAULT_LANGUAGE_MODEL,
    )

    return {
        "openai": OPENAI_DEFAULT_LANGUAGE_MODEL,
        "anthropic": ANTHROPIC_DEFAULT_LANGUAGE_MODEL,
        "watsonx": "",
        "ollama": "",
    }.get(provider, "")


def _default_embedding_model(provider: str) -> str:
    """Return a fallback embedding model for `provider` on provider-removal
    reshuffle, or "" if none can be assumed safe.

    No provider gets a hardcoded model name here. A provider name like
    "openai" or "watsonx" doesn't reliably tell you which models are
    actually deployed — it's frequently an internal OpenAI/watsonx-
    compatible gateway with a curated, deployment-specific model subset.
    A hardcoded guess can silently select a model the gateway doesn't
    serve, breaking every ingestion with no clear signal why (see
    incident: hardcoded "text-embedding-3-small" was selected in an
    environment whose gateway only served "text-embedding-3-large").

    Azure is the exception: its model IDs are customer-defined deployment
    names, so removal always leaves the model empty for an explicit user
    choice. For other providers, defer to whatever the deployment declared via
    EMBEDDING_MODEL/EMBEDDING_PROVIDER (see
    ``get_declared_default_embedding_model``). If the deployment hasn't
    declared a default for the provider, return "" and force the admin
    to pick a model the settings UI confirms is actually available.
    """
    # Azure model identifiers are customer-defined deployment names. Even an
    # operator-declared default may belong to a different workspace/resource,
    # so provider removal must leave the choice open for the user.
    if provider == "azure":
        return ""

    from config.embedding_constants import get_declared_default_embedding_model

    return get_declared_default_embedding_model(provider)


async def _affected_embedding_models(
    provider: str,
    session_manager,
    user,
    models_service,
) -> list[dict[str, Any]]:
    """Find embedding models present in the corpus that belong to ``provider``.

    Used to warn users before they remove a provider whose embedding models
    were used to index documents — otherwise semantic search silently breaks
    for those docs. Returns a list of ``{"model": str, "doc_count": int}``.

    Conservative on errors (returns empty list) so infra issues don't block
    provider removal.
    """
    from config.settings import get_index_name
    from services.models_service import ModelsService

    provider_lower = provider.lower()
    if provider_lower == "anthropic":
        # Anthropic doesn't serve embedding models — nothing to warn about.
        return []

    try:
        # Refresh so the registry reflects currently-configured providers
        # before we use it to attribute models.
        await models_service.update_model_registry()
        registry = ModelsService._model_provider_registry

        # Use the admin client so DLS does not scope the aggregation to the
        # requesting user's documents. Provider removal is a global operation
        # that affects all tenants, so we must see every document's embedding
        # model regardless of ownership.
        agg_result = await clients.opensearch.search(
            index=get_index_name(),
            body={
                "size": 0,
                "aggs": {"embedding_models": {"terms": {"field": "embedding_model", "size": 50}}},
            },
            params={"terminate_after": 0},
        )
        buckets = agg_result.get("aggregations", {}).get("embedding_models", {}).get("buckets", [])

        affected: list[dict[str, Any]] = []
        for bucket in buckets:
            model = bucket.get("key")
            if not model:
                continue
            mapped = registry.get(model)
            # Narrow fallback: the watsonx registry bootstrap requires the
            # provider still be configured, so models from an about-to-be-
            # removed watsonx can still be attributed via the "ibm/" prefix.
            if mapped is None and provider_lower == "watsonx" and model.startswith("ibm/"):
                mapped = "watsonx"
            if mapped == provider_lower:
                affected.append({"model": model, "doc_count": bucket.get("doc_count", 0)})
        return affected
    except Exception as e:
        logger.warning(
            "Could not determine affected embedding models for provider removal",
            provider=provider,
            error=str(e),
        )
        return []


def _embedding_conflict_response(
    provider_label: str, provider_key: str, affected: list[dict[str, Any]]
) -> JSONResponse:
    """Shared 409 response when removing a provider whose embedding models are
    still referenced by indexed documents."""
    model_names = [a["model"] for a in affected]
    return JSONResponse(
        {
            "error": (
                f"Removing {provider_label} will disable semantic search on "
                f"documents indexed with: {', '.join(model_names)}. "
                f"Re-ingest affected documents with another embedding model, "
                f"or retry with force_remove=true to proceed anyway."
            ),
            "code": "embedding_provider_in_use",
            "affected_provider": provider_key,
            "affected_models": affected,
        },
        status_code=409,
    )


async def _create_openrag_docs_filter(knowledge_filter_service, session_manager, user):
    """Create the OpenRAG Docs knowledge filter for onboarding"""
    import json
    import uuid
    from datetime import datetime

    if not knowledge_filter_service:
        logger.error("Knowledge filter service not available")
        return None

    # Get JWT token
    jwt_token = user.jwt_token

    # In no-auth mode, set owner to None so filter is visible to all users
    # In auth mode, use the actual user as owner
    if is_no_auth_mode():
        owner_user_id = None
    else:
        owner_user_id = user.user_id

    # Create the filter document
    filter_id = str(uuid.uuid4())
    query_data = json.dumps(
        {
            "query": "",
            "filters": {
                # URL-based docs ingestion produces many source URLs.
                # Filter by connector type to target OpenRAG docs only.
                "data_sources": ["*"],
                "document_types": ["*"],
                "owners": ["*"],
                "connector_types": ["openrag_docs"],
            },
            "limit": 10,
            "scoreThreshold": 0,
            "color": "blue",
            "icon": "book",
        }
    )

    filter_doc = {
        "id": filter_id,
        "name": "OpenRAG Docs",
        "description": "Filter for OpenRAG documentation",
        "query_data": query_data,
        "owner": owner_user_id,
        "allowed_users": [],
        "allowed_groups": [],
        "created_at": datetime.now(UTC).isoformat(),
        "updated_at": datetime.now(UTC).isoformat(),
    }

    result = await knowledge_filter_service.create_knowledge_filter(
        filter_doc, user_id=user.user_id, jwt_token=jwt_token
    )

    if result.get("success"):
        return filter_id
    else:
        logger.error("Failed to create OpenRAG Docs filter", error=result.get("error"))
        return None


def _get_flows_service():
    """Helper function to get flows service instance"""
    from services.flows_service import FlowsService

    return FlowsService()