Split settings into package and refactor

Split the large src/api/settings.py into a settings package (endpoints, models, helpers, langflow_sync) and added src/api/settings/__init__.py to preserve the original public import surface. Renamed the original file to src/api/settings/endpoints.py and moved Pydantic models and Langflow/provider helper logic into dedicated modules. Updated imports and made numerous small formatting/rewrites (wrapping, logging, minor refactors) without behavioral changes. Also updated pyproject.toml to whitelist common FastAPI call-sites for Ruff/Bugbear and add a mypy override for api.settings.endpoints. Minor tweaks to src/api/router.py (spacing and traceback logging) included.

Author: edwinjosechittilappilly

pyproject.toml

@@ -96,6 +96,26 @@ target-version = "py313"
 select = ["E", "F", "I", "B", "UP"]
 ignore = ["E501"]  # line-length handled by formatter
 
+# FastAPI's idiomatic dependency-injection pattern uses `Depends(...)` and
+# our `require_permission(...)` as call expressions in default-argument
+# position. B008 flags these as bugs ("function call in argument default")
+# but for FastAPI they are by design — the framework introspects them at
+# request time. Whitelist the call sites instead of sprinkling noqa
+# comments across every handler.
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = [
+    "fastapi.Depends",
+    "fastapi.Query",
+    "fastapi.Path",
+    "fastapi.Body",
+    "fastapi.Header",
+    "fastapi.Cookie",
+    "fastapi.File",
+    "fastapi.Form",
+    "fastapi.Security",
+    "dependencies.require_permission",
+]
+
 # `bootstrap` must be the first import in any module that uses it
 # (it loads .env and configures structlog before anything else can
 # read env vars or emit logs). Define it as its own isort section
@@ -120,4 +140,14 @@ ignore_missing_imports = true
 no_strict_optional = true
 warn_unused_ignores = true
 
+# FastAPI handlers in this module declare a Pydantic response model as
+# their return type but legitimately return `JSONResponse(...)` on error
+# paths. The runtime accepts both, but the annotation can't be widened to
+# `SomeResponse | JSONResponse` because FastAPI then tries to derive an
+# OpenAPI schema from the union and fails. Suppress only the resulting
+# return-value mismatches in this one file.
+[[tool.mypy.overrides]]
+module = "api.settings.endpoints"
+disable_error_code = ["return-value"]
+
 

src/api/router.py

@@ -50,6 +50,7 @@ async def upload_ingest_router(
         logger.debug("Routing to traditional OpenRAG upload")
         # Route to traditional upload — just take the first file
         from api.upload import upload as traditional_upload_fn
+
         return await traditional_upload_fn(
             file=file[0] if file else None,
             document_service=document_service,
@@ -154,13 +155,15 @@ async def _langflow_upload_ingest_task(
 
         except Exception:
             from utils.file_utils import safe_unlink
+
             for temp_path in temp_file_paths:
                 safe_unlink(temp_path)
             raise
 
     except Exception as e:
         logger.error("Task-based langflow upload_ingest failed", error=str(e))
         import traceback
+
         logger.error("Full traceback", traceback=traceback.format_exc())
         error_msg = str(e)
         if "AuthenticationException" in error_msg or "access denied" in error_msg.lower():

src/api/settings/__init__.py

@@ -0,0 +1,88 @@
+"""Settings/onboarding endpoint package.
+
+The original `src/api/settings.py` (2081 lines) was split into focused
+submodules. This `__init__.py` preserves the public-import contract every
+external caller relies on:
+
+* `src/app/routes/internal.py` registers each endpoint via
+  `from api import settings; app.add_api_route(..., settings.<name>, ...)`.
+* `src/api/v1/settings.py` imports `SettingsUpdateBody` and (lazily)
+  `update_settings`.
+* `src/services/startup_orchestrator.py` lazily imports
+  `reapply_all_settings` for flow-reset re-sync.
+
+Adding a new endpoint to this package: define it in `endpoints.py`, then
+re-export it here.
+"""
+
+from api.settings.endpoints import (
+    get_settings,
+    onboarding,
+    refresh_openrag_docs,
+    rollback_onboarding,
+    update_docling_preset,
+    update_onboarding_state,
+    update_settings,
+)
+from api.settings.langflow_sync import reapply_all_settings
+from api.settings.models import (
+    AgentConfig,
+    AnthropicProviderConfig,
+    AssistantMessage,
+    DoclingPresetBody,
+    DoclingPresetResponse,
+    IngestionDefaultsConfig,
+    KnowledgeConfig,
+    OllamaProviderConfig,
+    OnboardingBody,
+    OnboardingResponse,
+    OnboardingStateBody,
+    OnboardingStateConfig,
+    OnboardingStateResponse,
+    OpenAIProviderConfig,
+    ProvidersConfig,
+    RefreshOpenRAGDocsResponse,
+    RollbackBody,
+    RollbackResponse,
+    SettingsResponse,
+    SettingsUpdateBody,
+    SettingsUpdateResponse,
+    WatsonXProviderConfig,
+)
+
+__all__ = [
+    # Endpoints
+    "get_settings",
+    "update_settings",
+    "onboarding",
+    "update_onboarding_state",
+    "rollback_onboarding",
+    "update_docling_preset",
+    "refresh_openrag_docs",
+    # Internal orchestrator (called from services/startup_orchestrator.py)
+    "reapply_all_settings",
+    # Pydantic models (some are imported externally; re-export all for parity
+    # with the pre-split flat module's surface)
+    "SettingsUpdateBody",
+    "OnboardingBody",
+    "AssistantMessage",
+    "OnboardingStateBody",
+    "DoclingPresetBody",
+    "OnboardingStateConfig",
+    "OpenAIProviderConfig",
+    "AnthropicProviderConfig",
+    "WatsonXProviderConfig",
+    "OllamaProviderConfig",
+    "ProvidersConfig",
+    "KnowledgeConfig",
+    "AgentConfig",
+    "IngestionDefaultsConfig",
+    "SettingsResponse",
+    "OnboardingResponse",
+    "RefreshOpenRAGDocsResponse",
+    "DoclingPresetResponse",
+    "OnboardingStateResponse",
+    "SettingsUpdateResponse",
+    "RollbackResponse",
+    "RollbackBody",
+]