OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.
Python
"""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