refactor: rename the application package to docsgpt

The backend import package is now docsgpt, the name it will carry on PyPI;
application was far too generic to install into anyone's site-packages.
git mv plus a mechanical rewrite of every import, dotted string and path
reference: 734 Python files, the compose files, Dockerfile, workflows, docs,
setup scripts, devcontainer, k8s manifests, vscode config, pytest and coverage
config, .gitignore. Behaviour is unchanged.

Kept for one release:
- A top-level application package whose meta-path finder resolves
  application.x.y to the already-imported docsgpt.x.y object, so old imports
  and entry points (celery -A application.app.celery,
  uvicorn application.asgi:asgi_app) keep working with a FutureWarning.
- Celery registers every application.* task name as an alias of its
  docsgpt.* task on start-up, so messages queued by the previous release still
  run. The redbeat key prefix moves to redbeat:docsgpt:v2: so schedule entries
  the previous release wrote are left unread instead of firing twice.

The backend image builds from the repository root (docker build -f
docsgpt/Dockerfile .) so it can ship the alias package; a root .dockerignore
allow-lists docsgpt/ and application/ and keeps caches, local data, .env
files, the sample index files and the Dockerfile out. Compose and the image
workflows point at the new context.

docsgpt/core/db_uri.py

@@ -0,0 +1,89 @@
+"""Normalize user-supplied Postgres URIs for different drivers.
+
+DocsGPT has two Postgres connection strings pointing at potentially
+different databases:
+
+* ``POSTGRES_URI`` feeds SQLAlchemy, which needs the
+  ``postgresql+psycopg://`` dialect prefix to pick the psycopg v3 driver.
+* ``PGVECTOR_CONNECTION_STRING`` feeds ``psycopg.connect()`` directly
+  (via libpq) in ``docsgpt/vectorstore/pgvector.py``. libpq only
+  understands ``postgres://`` and ``postgresql://`` — the SQLAlchemy
+  dialect prefix is an invalid URI from its point of view.
+
+The two fields therefore need opposite normalization so operators don't
+have to know which driver a given field feeds. Each normalizer also
+silently upgrades the legacy ``postgresql+psycopg2://`` prefix since
+psycopg2 is no longer in the project.
+
+This module is deliberately separate from ``docsgpt/core/settings.py``
+so the Settings class stays focused on field declarations, and the
+URI-rewriting logic can be unit-tested without triggering ``.env``
+file loading from importing Settings.
+"""
+
+from __future__ import annotations
+
+
+def _rewrite_uri_prefixes(v, rewrites):
+    """Shared URI prefix rewriter used by both normalizers below.
+
+    Strips whitespace, returns ``None`` for empty / ``"none"`` values,
+    applies the first matching rewrite, and passes unrecognised input
+    through so downstream consumers (SQLAlchemy, libpq) can produce
+    their own error messages rather than us silently eating a
+    misconfiguration.
+    """
+    if v is None:
+        return None
+    if not isinstance(v, str):
+        return v
+    v = v.strip()
+    if not v or v.lower() == "none":
+        return None
+    for prefix, target in rewrites:
+        if v.startswith(prefix):
+            return target + v[len(prefix):]
+    return v
+
+
+# POSTGRES_URI feeds SQLAlchemy, which needs a ``postgresql+psycopg://``
+# dialect prefix to select the psycopg v3 driver. Normalize the
+# operator-friendly forms TOWARD that dialect.
+_POSTGRES_URI_REWRITES = (
+    ("postgresql+psycopg2://", "postgresql+psycopg://"),
+    ("postgresql://", "postgresql+psycopg://"),
+    ("postgres://", "postgresql+psycopg://"),
+)
+
+
+# PGVECTOR_CONNECTION_STRING feeds ``psycopg.connect()`` directly in
+# docsgpt/vectorstore/pgvector.py — NOT SQLAlchemy. libpq only
+# understands ``postgres://`` and ``postgresql://``; the SQLAlchemy
+# dialect prefix is an invalid URI from libpq's point of view. Strip it
+# if the operator accidentally copied their POSTGRES_URI value here.
+_PGVECTOR_CONNECTION_STRING_REWRITES = (
+    ("postgresql+psycopg2://", "postgresql://"),
+    ("postgresql+psycopg://", "postgresql://"),
+)
+
+
+def normalize_postgres_uri(v):
+    """Normalize a user-supplied POSTGRES_URI to the SQLAlchemy psycopg3 form.
+
+    Accepts the forms operators naturally write (``postgres://``,
+    ``postgresql://``) and rewrites them to ``postgresql+psycopg://``.
+    Unknown schemes pass through unchanged so SQLAlchemy can produce its
+    own dialect-not-found error.
+    """
+    return _rewrite_uri_prefixes(v, _POSTGRES_URI_REWRITES)
+
+
+def normalize_pgvector_connection_string(v):
+    """Normalize a user-supplied PGVECTOR_CONNECTION_STRING for libpq.
+
+    Strips the SQLAlchemy dialect prefix if the operator accidentally
+    copied their POSTGRES_URI value here — libpq can't parse it.
+    User-friendly forms (``postgres://``, ``postgresql://``) pass
+    through unchanged since libpq accepts them natively.
+    """
+    return _rewrite_uri_prefixes(v, _PGVECTOR_CONNECTION_STRING_REWRITES)

docsgpt/core/json_schema_utils.py

@@ -0,0 +1,34 @@
+from typing import Any, Dict, Optional
+
+
+class JsonSchemaValidationError(ValueError):
+    """Raised when a JSON schema payload is invalid."""
+
+
+def normalize_json_schema_payload(json_schema: Any) -> Optional[Dict[str, Any]]:
+    """
+    Normalize accepted JSON schema payload shapes to a plain schema object.
+
+    Accepted inputs:
+    - None
+    - A raw schema object with a top-level "type"
+    - A wrapped payload with a top-level "schema" object
+    """
+    if json_schema is None:
+        return None
+
+    if not isinstance(json_schema, dict):
+        raise JsonSchemaValidationError("must be a valid JSON object")
+
+    wrapped_schema = json_schema.get("schema")
+    if wrapped_schema is not None:
+        if not isinstance(wrapped_schema, dict):
+            raise JsonSchemaValidationError('field "schema" must be a valid JSON object')
+        return wrapped_schema
+
+    if "type" not in json_schema:
+        raise JsonSchemaValidationError(
+            'must include either a "type" or "schema" field'
+        )
+
+    return json_schema

docsgpt/core/log_context.py

@@ -0,0 +1,57 @@
+"""Per-activity logging context backed by ``contextvars``.
+
+The ``_ContextFilter`` installed by ``logging_config.setup_logging`` stamps
+every ``LogRecord`` emitted inside a ``bind`` block with the bound keys, so
+they land as first-class attributes on the OTLP log export rather than being
+buried inside formatted message bodies.
+
+A single ``ContextVar`` holds a dict so nested binds reset atomically (LIFO)
+via the token returned by ``bind``.
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from typing import Mapping
+
+
+_CTX_KEYS: frozenset[str] = frozenset(
+    {
+        "activity_id",
+        "parent_activity_id",
+        "user_id",
+        "agent_id",
+        "conversation_id",
+        "endpoint",
+        "model",
+    }
+)
+
+_ctx: ContextVar[Mapping[str, str]] = ContextVar("log_ctx", default={})
+
+
+def bind(**kwargs: object) -> Token:
+    """Overlay the given keys onto the current context.
+
+    Returns a ``Token`` so the caller can ``reset`` in a ``finally`` block.
+    Keys outside :data:`_CTX_KEYS` are silently dropped (so a typo can't
+    stamp a stray field name onto every record), as are ``None`` values
+    (a missing attribute is more useful than the literal string ``"None"``).
+    """
+    overlay = {
+        k: str(v)
+        for k, v in kwargs.items()
+        if k in _CTX_KEYS and v is not None
+    }
+    new = {**_ctx.get(), **overlay}
+    return _ctx.set(new)
+
+
+def reset(token: Token) -> None:
+    """Restore the context to the snapshot captured by the matching ``bind``."""
+    _ctx.reset(token)
+
+
+def snapshot() -> Mapping[str, str]:
+    """Return the current context dict. Treat as read-only; use :func:`bind`."""
+    return _ctx.get()

docsgpt/core/logging_config.py

@@ -0,0 +1,112 @@
+import logging
+import os
+from logging.config import dictConfig
+
+from docsgpt.core.log_context import snapshot as _ctx_snapshot
+
+
+# Loggers with ``propagate=False`` don't share root's handlers, so the
+# context filter has to be installed on their handlers directly.
+_NON_PROPAGATING_LOGGERS: tuple[str, ...] = (
+    "uvicorn",
+    "uvicorn.access",
+    "uvicorn.error",
+    "celery.app.trace",
+    "celery.worker.strategy",
+    "gunicorn.error",
+    "gunicorn.access",
+)
+
+
+class _ContextFilter(logging.Filter):
+    """Stamp the current ``log_context`` snapshot onto every ``LogRecord``.
+
+    Must be installed on **handlers**, not loggers: Python skips logger-level
+    filters when a child logger's record propagates up. The ``hasattr`` guard
+    keeps an explicit ``logger.info(..., extra={...})`` from being overwritten.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        for key, value in _ctx_snapshot().items():
+            if not hasattr(record, key):
+                setattr(record, key, value)
+        return True
+
+
+def _otlp_logs_enabled() -> bool:
+    """Return True when the user has opted in to OTLP log export.
+
+    Gated by the standard OTEL env vars so no project-specific knob is needed:
+    set ``OTEL_LOGS_EXPORTER=otlp`` (and leave ``OTEL_SDK_DISABLED`` unset or
+    false) to flip it on. When false, ``setup_logging`` keeps its original
+    console-only behavior.
+    """
+    exporter = os.getenv("OTEL_LOGS_EXPORTER", "").strip().lower()
+    disabled = os.getenv("OTEL_SDK_DISABLED", "false").strip().lower() == "true"
+    return exporter == "otlp" and not disabled
+
+
+def setup_logging() -> None:
+    """Configure the root logger with a stdout console handler.
+
+    When OTLP log export is enabled, ``opentelemetry-instrument`` attaches a
+    ``LoggingHandler`` to the root logger before this function runs. The
+    ``dictConfig`` call below replaces ``root.handlers`` with the console
+    handler, which would silently drop the OTEL handler. To make OTLP log
+    export work without forcing every contributor to opt in, snapshot the
+    OTEL handlers up front and re-attach them after ``dictConfig``.
+    """
+    preserved_handlers: list[logging.Handler] = []
+    if _otlp_logs_enabled():
+        preserved_handlers = [
+            h
+            for h in logging.getLogger().handlers
+            if h.__class__.__module__.startswith("opentelemetry")
+        ]
+
+    dictConfig({
+        "version": 1,
+        "disable_existing_loggers": False,
+        "formatters": {
+            "default": {
+                "format": "[%(asctime)s] %(levelname)s in %(module)s: %(message)s",
+            }
+        },
+        "handlers": {
+            "console": {
+                "class": "logging.StreamHandler",
+                "stream": "ext://sys.stdout",
+                "formatter": "default",
+            }
+        },
+        "root": {
+            "level": "INFO",
+            "handlers": ["console"],
+        },
+    })
+
+    if preserved_handlers:
+        root = logging.getLogger()
+        for handler in preserved_handlers:
+            if handler not in root.handlers:
+                root.addHandler(handler)
+
+    _install_context_filter()
+
+
+def _install_context_filter() -> None:
+    """Attach :class:`_ContextFilter` to root's handlers + every handler on
+    the known non-propagating loggers. Skipping handlers that already carry
+    one keeps repeat ``setup_logging`` calls from stacking filters.
+    """
+
+    def _has_ctx_filter(handler: logging.Handler) -> bool:
+        return any(isinstance(f, _ContextFilter) for f in handler.filters)
+
+    for handler in logging.getLogger().handlers:
+        if not _has_ctx_filter(handler):
+            handler.addFilter(_ContextFilter())
+    for name in _NON_PROPAGATING_LOGGERS:
+        for handler in logging.getLogger(name).handlers:
+            if not _has_ctx_filter(handler):
+                handler.addFilter(_ContextFilter())

docsgpt/core/model_registry.py

@@ -0,0 +1,389 @@
+"""Layered model registry.
+
+Loads model catalogs from YAML files (built-in + operator-supplied),
+groups them by provider name, then for each registered provider plugin
+calls ``get_models`` to produce the final per-provider model list.
+
+End-user BYOM (per-user model records in Postgres) is layered on top:
+when a lookup arrives with a ``user_id``, the registry consults a
+per-user cache first (loaded from the ``user_custom_models`` table on
+miss) and falls through to the built-in catalog.
+
+Cross-process invalidation: ``ModelRegistry`` is a per-process
+singleton, so a CRUD write only evicts the cache in the process that
+served it. Other gunicorn workers and Celery workers would otherwise
+keep using a deleted/disabled/key-rotated BYOM record indefinitely.
+``invalidate_user`` therefore both drops the local layer *and* bumps a
+Redis-side version counter; other processes notice the bump on their
+next access (after the local TTL window) and reload from Postgres. If
+Redis is unreachable the per-process TTL still bounds staleness — pure
+TTL semantics, no regression.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections import defaultdict
+from typing import Dict, List, Optional, Tuple
+
+from docsgpt.core.model_settings import AvailableModel
+from docsgpt.core.model_yaml import (
+    BUILTIN_MODELS_DIR,
+    ProviderCatalog,
+    load_model_yamls,
+)
+
+logger = logging.getLogger(__name__)
+
+_USER_CACHE_TTL_SECONDS = 60.0
+_USER_VERSION_KEY_PREFIX = "byom:registry_version:"
+
+
+class ModelRegistry:
+    """Singleton registry of available models."""
+
+    _instance: Optional["ModelRegistry"] = None
+    _initialized: bool = False
+
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        if not ModelRegistry._initialized:
+            self.models: Dict[str, AvailableModel] = {}
+            self.default_model_id: Optional[str] = None
+            # Per-user BYOM cache. Each entry is
+            # ``(layer, version_at_load, loaded_at_monotonic)``:
+            #   * ``layer`` — {model_id: AvailableModel}
+            #   * ``version_at_load`` — Redis-side counter snapshot at
+            #     reload time, or ``None`` if Redis was unreachable
+            #   * ``loaded_at_monotonic`` — for TTL bookkeeping
+            # Populated lazily, evicted by TTL + cross-process
+            # invalidation (see ``invalidate_user``).
+            self._user_models: Dict[
+                str,
+                Tuple[Dict[str, AvailableModel], Optional[int], float],
+            ] = {}
+            self._load_models()
+            ModelRegistry._initialized = True
+
+    @classmethod
+    def get_instance(cls) -> "ModelRegistry":
+        return cls()
+
+    @classmethod
+    def reset(cls) -> None:
+        """Clear the singleton. Intended for test fixtures."""
+        cls._instance = None
+        cls._initialized = False
+
+    @classmethod
+    def invalidate_user(cls, user_id: str) -> None:
+        """Drop the cached per-user model layer for ``user_id``.
+
+        Called by the BYOM REST routes after every create/update/delete.
+        Two effects:
+
+        * Local: pop the entry from this process's cache so the next
+          lookup re-reads from Postgres immediately.
+        * Cross-process: ``INCR`` a Redis-side version counter for this
+          user. Other gunicorn/Celery processes notice the counter
+          changed on their next TTL-driven recheck (see
+          ``_user_models_for``) and reload. If Redis is unreachable we
+          log and continue — local invalidation still happened, and
+          peers fall back to TTL-only staleness bounds.
+        """
+        if cls._instance is not None:
+            cls._instance._user_models.pop(user_id, None)
+        try:
+            from docsgpt.cache import get_redis_instance
+
+            client = get_redis_instance()
+            if client is not None:
+                client.incr(_USER_VERSION_KEY_PREFIX + user_id)
+        except Exception as e:
+            logger.warning(
+                "BYOM invalidate: failed to publish version bump for "
+                "user %s (Redis unreachable?): %s",
+                user_id,
+                e,
+            )
+
+    @classmethod
+    def _read_user_version(cls, user_id: str) -> Optional[int]:
+        """Return the Redis-side invalidation counter for ``user_id``.
+
+        ``0`` if the key has never been bumped; ``None`` if Redis is
+        unreachable or the read failed (callers fall back to TTL-only
+        staleness in that case).
+        """
+        try:
+            from docsgpt.cache import get_redis_instance
+
+            client = get_redis_instance()
+            if client is None:
+                return None
+            raw = client.get(_USER_VERSION_KEY_PREFIX + user_id)
+            if raw is None:
+                return 0
+            return int(raw)
+        except Exception:
+            return None
+
+    def _load_models(self) -> None:
+        from pathlib import Path
+
+        from docsgpt.core.settings import settings
+        from docsgpt.llm.providers import ALL_PROVIDERS
+
+        directories = [BUILTIN_MODELS_DIR]
+        operator_dir = getattr(settings, "MODELS_CONFIG_DIR", None)
+        if operator_dir:
+            op_path = Path(operator_dir)
+            if not op_path.exists():
+                logger.warning(
+                    "MODELS_CONFIG_DIR=%s does not exist; no operator "
+                    "model YAMLs will be loaded.",
+                    operator_dir,
+                )
+            elif not op_path.is_dir():
+                logger.warning(
+                    "MODELS_CONFIG_DIR=%s is not a directory; no operator "
+                    "model YAMLs will be loaded.",
+                    operator_dir,
+                )
+            else:
+                directories.append(op_path)
+
+        catalogs = load_model_yamls(directories)
+
+        # Validate every catalog targets a known plugin before doing any
+        # registry work, so an unknown provider name in YAML aborts boot
+        # with a clear error.
+        plugin_names = {p.name for p in ALL_PROVIDERS}
+        for c in catalogs:
+            if c.provider not in plugin_names:
+                raise ValueError(
+                    f"{c.source_path}: YAML declares unknown provider "
+                    f"{c.provider!r}; no Provider plugin is registered "
+                    f"under that name. Known: {sorted(plugin_names)}"
+                )
+
+        catalogs_by_provider: Dict[str, List[ProviderCatalog]] = defaultdict(list)
+        for c in catalogs:
+            catalogs_by_provider[c.provider].append(c)
+
+        self.models.clear()
+        for provider in ALL_PROVIDERS:
+            if not provider.is_enabled(settings):
+                continue
+            for model in provider.get_models(
+                settings, catalogs_by_provider.get(provider.name, [])
+            ):
+                self.models[model.id] = model
+
+        self.default_model_id = self._resolve_default(settings)
+
+        logger.info(
+            "ModelRegistry loaded %d models, default: %s",
+            len(self.models),
+            self.default_model_id,
+        )
+
+    def _resolve_default(self, settings) -> Optional[str]:
+        if settings.LLM_NAME:
+            for name in self._parse_model_names(settings.LLM_NAME):
+                if name in self.models:
+                    return name
+            if settings.LLM_NAME in self.models:
+                return settings.LLM_NAME
+
+        if settings.LLM_PROVIDER and settings.API_KEY:
+            for model_id, model in self.models.items():
+                if model.provider.value == settings.LLM_PROVIDER:
+                    return model_id
+
+        if self.models:
+            return next(iter(self.models.keys()))
+        return None
+
+    @staticmethod
+    def _parse_model_names(llm_name: str) -> List[str]:
+        if not llm_name:
+            return []
+        return [name.strip() for name in llm_name.split(",") if name.strip()]
+
+    # Per-user (BYOM) layer
+
+    def _user_models_for(self, user_id: str) -> Dict[str, AvailableModel]:
+        """Return the user's BYOM models keyed by registry id (UUID).
+
+        Loaded lazily from Postgres on first access; cached subject to
+        a per-process TTL (``_USER_CACHE_TTL_SECONDS``) and a Redis-
+        backed version counter for cross-process invalidation. The TTL
+        bounds staleness even when Redis is unreachable, while the
+        version stamp lets peers refresh without a DB read on the
+        common case (no invalidation since last load). Decryption
+        failures and DB errors yield an empty layer (logged) — the
+        user simply doesn't see their custom models on this request,
+        never a 500.
+        """
+        cached = self._user_models.get(user_id)
+        now = time.monotonic()
+
+        if cached is not None:
+            layer, cached_version, loaded_at = cached
+            if (now - loaded_at) < _USER_CACHE_TTL_SECONDS:
+                return layer
+            # TTL elapsed: peek at the cross-process counter. If it
+            # matches what we saw at load time, no invalidation has
+            # happened — extend the TTL without touching Postgres. If
+            # Redis is unreachable (``current_version is None``) we
+            # fall through to a real reload, which keeps staleness
+            # bounded to the TTL.
+            current_version = self._read_user_version(user_id)
+            if (
+                current_version is not None
+                and cached_version is not None
+                and current_version == cached_version
+            ):
+                self._user_models[user_id] = (layer, cached_version, now)
+                return layer
+
+        # Capture the counter *before* the DB read so a CRUD that lands
+        # mid-reload doesn't get masked: the next access will see a
+        # newer version and reload again.
+        version_before_read = self._read_user_version(user_id)
+
+        layer: Dict[str, AvailableModel] = {}
+        try:
+            from docsgpt.core.model_settings import (
+                ModelCapabilities,
+                ModelProvider,
+            )
+            from docsgpt.storage.db.repositories.user_custom_models import (
+                UserCustomModelsRepository,
+            )
+            from docsgpt.storage.db.session import db_readonly
+
+            with db_readonly() as conn:
+                repo = UserCustomModelsRepository(conn)
+                rows = repo.list_for_user(user_id)
+                for row in rows:
+                    api_key = repo._decrypt_api_key(
+                        row.get("api_key_encrypted", ""), user_id
+                    )
+                    if not api_key:
+                        # SECURITY: do NOT register an unroutable BYOM
+                        # record. If we did, LLMCreator would fall back
+                        # to the caller-passed api_key (settings.API_KEY
+                        # for openai_compatible) and POST it to the
+                        # user-supplied base_url — leaking the instance
+                        # credential to the user's chosen endpoint.
+                        # Most likely cause is ENCRYPTION_SECRET_KEY
+                        # having rotated; user must re-save the model.
+                        logger.warning(
+                            "user_custom_models: skipping model %s for "
+                            "user %s — api_key could not be decrypted "
+                            "(rotated ENCRYPTION_SECRET_KEY?). Re-save "
+                            "the model to recover.",
+                            row.get("id"),
+                            user_id,
+                        )
+                        continue
+                    caps_raw = row.get("capabilities") or {}
+                    # Stored attachments may be aliases (``image``) or
+                    # raw MIME types. Built-in YAML models expand at
+                    # load time; mirror that here so downstream MIME-
+                    # type comparisons (handlers/base.prepare_messages)
+                    # match concrete types like ``image/png`` rather
+                    # than the bare alias.
+                    from docsgpt.core.model_yaml import (
+                        expand_attachments_lenient,
+                    )
+
+                    raw_attachments = caps_raw.get("attachments", []) or []
+                    expanded_attachments = expand_attachments_lenient(
+                        raw_attachments,
+                        f"user_custom_models[user={user_id}, model={row.get('id')}]",
+                    )
+                    caps = ModelCapabilities(
+                        supports_tools=bool(caps_raw.get("supports_tools", False)),
+                        supports_structured_output=bool(
+                            caps_raw.get("supports_structured_output", False)
+                        ),
+                        supports_streaming=bool(
+                            caps_raw.get("supports_streaming", True)
+                        ),
+                        supported_attachment_types=expanded_attachments,
+                        context_window=int(
+                            caps_raw.get("context_window") or 128000
+                        ),
+                        reasoning_effort=caps_raw.get("reasoning_effort"),
+                        api_flavor=caps_raw.get(
+                            "api_flavor", "chat_completions"
+                        ),
+                    )
+                    model_id = str(row["id"])
+                    layer[model_id] = AvailableModel(
+                        id=model_id,
+                        provider=ModelProvider.OPENAI_COMPATIBLE,
+                        display_name=row["display_name"],
+                        description=row.get("description") or "",
+                        capabilities=caps,
+                        enabled=bool(row.get("enabled", True)),
+                        base_url=row["base_url"],
+                        upstream_model_id=row["upstream_model_id"],
+                        source="user",
+                        api_key=api_key,
+                    )
+        except Exception as e:
+            logger.warning(
+                "user_custom_models: failed to load layer for user %s: %s",
+                user_id,
+                e,
+            )
+            layer = {}
+
+        self._user_models[user_id] = (layer, version_before_read, now)
+        return layer
+
+    # Lookup API. ``user_id`` enables the BYOM per-user layer; without
+    # it, callers see only the built-in + operator catalog.
+
+    def get_model(
+        self, model_id: str, user_id: Optional[str] = None
+    ) -> Optional[AvailableModel]:
+        if user_id:
+            user_layer = self._user_models_for(user_id)
+            if model_id in user_layer:
+                return user_layer[model_id]
+        return self.models.get(model_id)
+
+    def get_all_models(
+        self, user_id: Optional[str] = None
+    ) -> List[AvailableModel]:
+        out = list(self.models.values())
+        if user_id:
+            out.extend(self._user_models_for(user_id).values())
+        return out
+
+    def get_enabled_models(
+        self, user_id: Optional[str] = None
+    ) -> List[AvailableModel]:
+        out = [m for m in self.models.values() if m.enabled]
+        if user_id:
+            out.extend(
+                m for m in self._user_models_for(user_id).values() if m.enabled
+            )
+        return out
+
+    def model_exists(
+        self, model_id: str, user_id: Optional[str] = None
+    ) -> bool:
+        if user_id and model_id in self._user_models_for(user_id):
+            return True
+        return model_id in self.models

docsgpt/core/model_settings.py

@@ -0,0 +1,99 @@
+import logging
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# Re-exported here so existing call sites (and tests) that do
+# ``from docsgpt.core.model_settings import ModelRegistry`` keep
+# working. The implementation lives in ``docsgpt/core/model_registry.py``.
+# Imported lazily inside ``__getattr__`` to avoid an import cycle with
+# ``model_yaml`` → ``model_settings`` (this file).
+
+
+class ModelProvider(str, Enum):
+    OPENAI = "openai"
+    OPENAI_COMPATIBLE = "openai_compatible"
+    OPENROUTER = "openrouter"
+    ANTHROPIC = "anthropic"
+    GROQ = "groq"
+    GOOGLE = "google"
+    HUGGINGFACE = "huggingface"
+    LLAMA_CPP = "llama.cpp"
+    DOCSGPT = "docsgpt"
+    NOVITA = "novita"
+
+
+@dataclass
+class ModelCapabilities:
+    supports_tools: bool = False
+    supports_structured_output: bool = False
+    supports_streaming: bool = True
+    supported_attachment_types: List[str] = field(default_factory=list)
+    context_window: int = 128000
+    input_cost_per_token: Optional[float] = None
+    output_cost_per_token: Optional[float] = None
+    # OpenAI reasoning-model effort hint (none/minimal/low/medium/high/xhigh;
+    # the accepted subset is model-dependent). Consumed by OpenAILLM — sent
+    # top-level on Chat Completions and nested under ``reasoning`` on the
+    # Responses path; ignored by providers that don't accept it.
+    reasoning_effort: Optional[str] = None
+    # Which OpenAI wire protocol the model speaks: "chat_completions"
+    # (the default) or "responses" (the /v1/responses endpoint). Set per
+    # model so only models that actually support the Responses API opt in.
+    api_flavor: str = "chat_completions"
+
+
+@dataclass
+class AvailableModel:
+    id: str
+    provider: ModelProvider
+    display_name: str
+    description: str = ""
+    capabilities: ModelCapabilities = field(default_factory=ModelCapabilities)
+    enabled: bool = True
+    base_url: Optional[str] = None
+    # User-facing label distinct from dispatch provider (e.g. mistral
+    # routed through openai_compatible).
+    display_provider: Optional[str] = None
+    # Sent in the API call's ``model`` field; falls back to ``self.id``
+    # for built-ins where id IS the upstream name.
+    upstream_model_id: Optional[str] = None
+    # "builtin" for catalog YAMLs, "user" for BYOM records.
+    source: str = "builtin"
+    # Decrypted/resolved at registry-merge time. Never serialized.
+    api_key: Optional[str] = field(default=None, repr=False, compare=False)
+
+    def to_dict(self) -> Dict:
+        result = {
+            "id": self.id,
+            "provider": self.display_provider or self.provider.value,
+            "display_name": self.display_name,
+            "description": self.description,
+            "supported_attachment_types": self.capabilities.supported_attachment_types,
+            "supports_tools": self.capabilities.supports_tools,
+            "supports_structured_output": self.capabilities.supports_structured_output,
+            "supports_streaming": self.capabilities.supports_streaming,
+            "context_window": self.capabilities.context_window,
+            "api_flavor": self.capabilities.api_flavor,
+            "reasoning_effort": self.capabilities.reasoning_effort,
+            "enabled": self.enabled,
+            "source": self.source,
+        }
+        if self.base_url:
+            result["base_url"] = self.base_url
+        return result
+
+
+def __getattr__(name):
+    """Lazy re-export of ``ModelRegistry`` from ``model_registry.py``.
+
+    Done lazily to avoid an import cycle: ``model_registry`` imports
+    ``model_yaml`` which imports the dataclasses from this file.
+    """
+    if name == "ModelRegistry":
+        from docsgpt.core.model_registry import ModelRegistry as _MR
+
+        return _MR
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

docsgpt/core/model_utils.py

@@ -0,0 +1,183 @@
+from typing import Any, Dict, Optional
+
+from docsgpt.core.model_registry import ModelRegistry
+
+
+def get_api_key_for_provider(provider: str) -> Optional[str]:
+    """Get the appropriate API key for a provider.
+
+    Delegates to the provider plugin's ``get_api_key``. Falls back to the
+    generic ``settings.API_KEY`` for unknown providers.
+    """
+    from docsgpt.core.settings import settings
+    from docsgpt.llm.providers import PROVIDERS_BY_NAME
+
+    plugin = PROVIDERS_BY_NAME.get(provider)
+    if plugin is not None:
+        key = plugin.get_api_key(settings)
+        if key:
+            return key
+    return settings.API_KEY
+
+
+def resolve_dispatch_provider(
+    stored_llm_name: Optional[str],
+    model_id: Optional[str] = None,
+    user_id: Optional[str] = None,
+    fallback: Optional[str] = None,
+) -> Optional[str]:
+    """Resolve a stored provider string to one ``LLMCreator`` can dispatch.
+
+    ``/api/models`` reports ``display_provider`` when a catalog YAML sets one
+    (``foundry``, ``azure_foundry``, ``cloudflare``, …), and clients persist
+    that label as ``llm_name`` on agents and workflow nodes. Those labels are
+    presentation-only: they are absent from ``PROVIDERS_BY_NAME``, so passing
+    one to ``LLMCreator.create_llm`` raises ``No LLM class found for type
+    <label>``. Normalizing here keeps already-stored records working without a
+    migration.
+
+    Resolution order: a stored name that is a real dispatch provider wins;
+    otherwise the model registry decides; otherwise ``fallback``.
+
+    Args:
+        stored_llm_name: Provider string persisted on the record, possibly a
+            display label.
+        model_id: Model whose registry entry knows the true provider.
+        user_id: BYOM-resolution scope for per-user model records.
+        fallback: Used when neither the stored name nor the registry resolves.
+
+    Returns:
+        A dispatchable provider name, or ``fallback`` when nothing resolves.
+    """
+    from docsgpt.llm.providers import PROVIDERS_BY_NAME
+
+    # Return the *canonical* lowercase name. ``LLMCreator`` lowercases before
+    # its own lookup, but ``get_api_key_for_provider`` matches exactly — so a
+    # stored "OpenAI" would pass this guard and then silently fall through to
+    # ``settings.API_KEY``, which is the key leak this function exists to stop.
+    if stored_llm_name and stored_llm_name.lower() in PROVIDERS_BY_NAME:
+        return stored_llm_name.lower()
+    if model_id:
+        resolved = get_provider_from_model_id(model_id, user_id=user_id)
+        if resolved:
+            return resolved
+    if fallback and fallback.lower() in PROVIDERS_BY_NAME:
+        return fallback.lower()
+    return fallback
+
+
+def get_all_available_models(
+    user_id: Optional[str] = None,
+) -> Dict[str, Dict[str, Any]]:
+    """Get all available models with metadata for API response.
+
+    When ``user_id`` is supplied, the user's BYOM custom-model records
+    are merged into the result alongside the built-in catalog.
+    """
+    registry = ModelRegistry.get_instance()
+    return {
+        model.id: model.to_dict()
+        for model in registry.get_enabled_models(user_id=user_id)
+    }
+
+
+def validate_model_id(model_id: str, user_id: Optional[str] = None) -> bool:
+    """Check if a model ID exists in registry.
+
+    ``user_id`` enables resolution of per-user BYOM records (UUIDs).
+    Without it, only built-in catalog ids resolve.
+    """
+    registry = ModelRegistry.get_instance()
+    return registry.model_exists(model_id, user_id=user_id)
+
+
+def get_model_capabilities(
+    model_id: str, user_id: Optional[str] = None
+) -> Optional[Dict[str, Any]]:
+    """Get capabilities for a specific model.
+
+    ``user_id`` enables resolution of per-user BYOM records.
+    """
+    registry = ModelRegistry.get_instance()
+    model = registry.get_model(model_id, user_id=user_id)
+    if model:
+        return {
+            "supported_attachment_types": model.capabilities.supported_attachment_types,
+            "supports_tools": model.capabilities.supports_tools,
+            "supports_structured_output": model.capabilities.supports_structured_output,
+            "context_window": model.capabilities.context_window,
+        }
+    return None
+
+
+def get_default_model_id() -> str:
+    """Get the system default model ID"""
+    registry = ModelRegistry.get_instance()
+    return registry.default_model_id
+
+
+def get_provider_from_model_id(
+    model_id: str, user_id: Optional[str] = None
+) -> Optional[str]:
+    """Get the provider name for a given model_id.
+
+    ``user_id`` enables resolution of per-user BYOM records (UUIDs).
+    Without it, BYOM model ids return ``None`` and the caller falls
+    back to the deployment default.
+    """
+    registry = ModelRegistry.get_instance()
+    model = registry.get_model(model_id, user_id=user_id)
+    if model:
+        return model.provider.value
+    return None
+
+
+def get_token_limit(model_id: str, user_id: Optional[str] = None) -> int:
+    """Get context window (token limit) for a model.
+
+    Returns the model's ``context_window`` or ``DEFAULT_LLM_TOKEN_LIMIT``
+    if not found. ``user_id`` enables resolution of per-user BYOM records.
+    """
+    from docsgpt.core.settings import settings
+
+    registry = ModelRegistry.get_instance()
+    model = registry.get_model(model_id, user_id=user_id)
+    if model:
+        return model.capabilities.context_window
+    return settings.DEFAULT_LLM_TOKEN_LIMIT
+
+
+def get_base_url_for_model(
+    model_id: str, user_id: Optional[str] = None
+) -> Optional[str]:
+    """Get the custom base_url for a specific model if configured.
+
+    Returns ``None`` if no custom base_url is set. ``user_id`` enables
+    resolution of per-user BYOM records.
+    """
+    registry = ModelRegistry.get_instance()
+    model = registry.get_model(model_id, user_id=user_id)
+    if model:
+        return model.base_url
+    return None
+
+
+def get_api_key_for_model(
+    model_id: str, user_id: Optional[str] = None
+) -> Optional[str]:
+    """Resolve the API key to use when invoking ``model_id``.
+
+    Priority:
+      1. The model record's own ``api_key`` (BYOM records and
+         ``openai_compatible`` YAMLs populate this).
+      2. The provider plugin's settings-based key.
+
+    ``user_id`` enables resolution of per-user BYOM records.
+    """
+    registry = ModelRegistry.get_instance()
+    model = registry.get_model(model_id, user_id=user_id)
+    if model is not None and model.api_key:
+        return model.api_key
+    if model is not None:
+        return get_api_key_for_provider(model.provider.value)
+    return None

docsgpt/core/model_yaml.py

@@ -0,0 +1,395 @@
+"""YAML loader for model catalog files under ``docsgpt/core/models/``.
+
+Each ``*.yaml`` file declares one provider's static model catalog. Files
+are validated with Pydantic at load time; any parse, schema, or alias
+error aborts startup with the offending file path in the message.
+
+For most providers, one YAML maps to one catalog. The
+``openai_compatible`` provider is special: each YAML file represents a
+distinct logical endpoint (Mistral, Together, Ollama, ...) with its own
+``api_key_env`` and ``base_url``. The loader returns a flat list so the
+registry can distinguish multiple files with the same ``provider:`` value.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Dict, List, Optional, Sequence
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from docsgpt.core.model_settings import (
+    AvailableModel,
+    ModelCapabilities,
+    ModelProvider,
+)
+
+logger = logging.getLogger(__name__)
+
+BUILTIN_MODELS_DIR = Path(__file__).parent / "models"
+DEFAULTS_FILENAME = "_defaults.yaml"
+
+# Accepted reasoning_effort values across the OpenAI reasoning lineup. This
+# is the union of all models; the set a given model actually accepts is a
+# subset (older o-series take low/medium/high only; GPT-5.5 adds xhigh;
+# none/minimal are GPT-5-era additions). Validated at YAML load so a typo
+# aborts boot rather than surfacing as a provider 400.
+VALID_REASONING_EFFORTS = frozenset(
+    {"none", "minimal", "low", "medium", "high", "xhigh"}
+)
+# Accepted api_flavor values: which OpenAI wire protocol a model speaks.
+VALID_API_FLAVORS = frozenset({"chat_completions", "responses"})
+
+
+class _DefaultsFile(BaseModel):
+    """Schema for ``_defaults.yaml``. Currently just attachment aliases."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    attachment_aliases: Dict[str, List[str]] = Field(default_factory=dict)
+
+
+class _CapabilityFields(BaseModel):
+    """Capability fields shared between provider ``defaults:`` and per-model overrides.
+
+    All fields are optional so a per-model override can selectively replace
+    a single field from the provider-level defaults.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    supports_tools: Optional[bool] = None
+    supports_structured_output: Optional[bool] = None
+    supports_streaming: Optional[bool] = None
+    attachments: Optional[List[str]] = None
+    context_window: Optional[int] = None
+    input_cost_per_token: Optional[float] = None
+    output_cost_per_token: Optional[float] = None
+    reasoning_effort: Optional[str] = None
+    api_flavor: Optional[str] = None
+
+    @field_validator("reasoning_effort")
+    @classmethod
+    def _valid_reasoning_effort(cls, v: Optional[str]) -> Optional[str]:
+        if v is not None and v not in VALID_REASONING_EFFORTS:
+            valid = ", ".join(sorted(VALID_REASONING_EFFORTS))
+            raise ValueError(
+                f"reasoning_effort must be one of [{valid}], got {v!r}"
+            )
+        return v
+
+    @field_validator("api_flavor")
+    @classmethod
+    def _valid_api_flavor(cls, v: Optional[str]) -> Optional[str]:
+        if v is not None and v not in VALID_API_FLAVORS:
+            valid = ", ".join(sorted(VALID_API_FLAVORS))
+            raise ValueError(
+                f"api_flavor must be one of [{valid}], got {v!r}"
+            )
+        return v
+
+
+class _ModelEntry(_CapabilityFields):
+    """Schema for one model row inside a YAML's ``models:`` list."""
+
+    id: str
+    display_name: Optional[str] = None
+    description: str = ""
+    enabled: bool = True
+    base_url: Optional[str] = None
+    upstream_model_id: Optional[str] = None
+    aliases: List[str] = Field(default_factory=list)
+
+    @field_validator("id")
+    @classmethod
+    def _id_nonempty(cls, v: str) -> str:
+        if not v or not v.strip():
+            raise ValueError("model id must be a non-empty string")
+        return v
+
+
+class _ProviderFile(BaseModel):
+    """Schema for one ``<provider>.yaml`` catalog file."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    provider: str
+    defaults: _CapabilityFields = Field(default_factory=_CapabilityFields)
+    models: List[_ModelEntry] = Field(default_factory=list)
+    # openai_compatible metadata. Optional for other providers.
+    display_provider: Optional[str] = None
+    api_key_env: Optional[str] = None
+    base_url: Optional[str] = None
+
+
+class ProviderCatalog(BaseModel):
+    """One YAML file's parsed contents, ready for the registry.
+
+    For most providers, multiple catalogs with the same ``provider`` get
+    merged later by the registry. The ``openai_compatible`` provider is
+    the exception: each catalog is treated as a distinct endpoint, with
+    its own ``api_key_env`` and ``base_url``.
+    """
+
+    provider: str
+    models: List[AvailableModel]
+    source_path: Optional[Path] = None
+    display_provider: Optional[str] = None
+    api_key_env: Optional[str] = None
+    base_url: Optional[str] = None
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+class ModelYAMLError(ValueError):
+    """Raised when a model YAML fails parsing, schema, or alias validation."""
+
+
+def _expand_attachments(
+    attachments: Sequence[str], aliases: Dict[str, List[str]], source: str
+) -> List[str]:
+    """Resolve attachment shorthands (``image``, ``pdf``) to MIME types.
+
+    Raw MIME-typed entries (containing ``/``) pass through unchanged.
+    Unknown aliases raise ``ModelYAMLError``.
+    """
+    expanded: List[str] = []
+    seen: set = set()
+    for entry in attachments:
+        if "/" in entry:
+            if entry not in seen:
+                expanded.append(entry)
+                seen.add(entry)
+            continue
+        if entry not in aliases:
+            valid = ", ".join(sorted(aliases.keys())) or "<none defined>"
+            raise ModelYAMLError(
+                f"{source}: unknown attachment alias '{entry}'. "
+                f"Valid aliases: {valid}. "
+                "(Or use a raw MIME type like 'image/png'.)"
+            )
+        for mime in aliases[entry]:
+            if mime not in seen:
+                expanded.append(mime)
+                seen.add(mime)
+    return expanded
+
+
+def _load_defaults(directory: Path) -> Dict[str, List[str]]:
+    """Load ``_defaults.yaml`` from ``directory`` if it exists."""
+    path = directory / DEFAULTS_FILENAME
+    if not path.exists():
+        return {}
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as e:
+        raise ModelYAMLError(f"{path}: invalid YAML: {e}") from e
+    try:
+        parsed = _DefaultsFile.model_validate(raw)
+    except Exception as e:
+        raise ModelYAMLError(f"{path}: schema error: {e}") from e
+    return parsed.attachment_aliases
+
+
+def _resolve_provider_enum(name: str, source: Path) -> ModelProvider:
+    try:
+        return ModelProvider(name)
+    except ValueError as e:
+        valid = ", ".join(p.value for p in ModelProvider)
+        raise ModelYAMLError(
+            f"{source}: unknown provider '{name}'. Valid: {valid}"
+        ) from e
+
+
+def _build_model(
+    entry: _ModelEntry,
+    defaults: _CapabilityFields,
+    provider: ModelProvider,
+    aliases: Dict[str, List[str]],
+    source: Path,
+    display_provider: Optional[str] = None,
+) -> AvailableModel:
+    """Merge defaults + per-model overrides into a final ``AvailableModel``."""
+
+    def pick(field_name: str, fallback):
+        v = getattr(entry, field_name)
+        if v is not None:
+            return v
+        d = getattr(defaults, field_name)
+        if d is not None:
+            return d
+        return fallback
+
+    raw_attachments = entry.attachments
+    if raw_attachments is None:
+        raw_attachments = defaults.attachments
+    if raw_attachments is None:
+        raw_attachments = []
+    expanded = _expand_attachments(
+        raw_attachments, aliases, f"{source} [model={entry.id}]"
+    )
+
+    caps = ModelCapabilities(
+        supports_tools=pick("supports_tools", False),
+        supports_structured_output=pick("supports_structured_output", False),
+        supports_streaming=pick("supports_streaming", True),
+        supported_attachment_types=expanded,
+        context_window=pick("context_window", 128000),
+        input_cost_per_token=pick("input_cost_per_token", None),
+        output_cost_per_token=pick("output_cost_per_token", None),
+        reasoning_effort=pick("reasoning_effort", None),
+        api_flavor=pick("api_flavor", "chat_completions"),
+    )
+
+    return AvailableModel(
+        id=entry.id,
+        provider=provider,
+        display_name=entry.display_name or entry.id,
+        description=entry.description,
+        capabilities=caps,
+        enabled=entry.enabled,
+        base_url=entry.base_url,
+        upstream_model_id=entry.upstream_model_id,
+        display_provider=display_provider,
+    )
+
+
+def _load_one_yaml(
+    path: Path, aliases: Dict[str, List[str]]
+) -> ProviderCatalog:
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as e:
+        raise ModelYAMLError(f"{path}: invalid YAML: {e}") from e
+    try:
+        parsed = _ProviderFile.model_validate(raw)
+    except Exception as e:
+        raise ModelYAMLError(f"{path}: schema error: {e}") from e
+
+    provider_enum = _resolve_provider_enum(parsed.provider, path)
+    models = [
+        _build_model(
+            entry,
+            parsed.defaults,
+            provider_enum,
+            aliases,
+            path,
+            display_provider=parsed.display_provider,
+        )
+        for entry in parsed.models
+    ]
+
+    return ProviderCatalog(
+        provider=parsed.provider,
+        models=models,
+        source_path=path,
+        display_provider=parsed.display_provider,
+        api_key_env=parsed.api_key_env,
+        base_url=parsed.base_url,
+    )
+
+
+_BUILTIN_ALIASES_CACHE: Optional[Dict[str, List[str]]] = None
+
+
+def builtin_attachment_aliases() -> Dict[str, List[str]]:
+    """Return the built-in attachment alias map from ``_defaults.yaml``.
+
+    Cached after first read so repeat calls are cheap.
+    """
+    global _BUILTIN_ALIASES_CACHE
+    if _BUILTIN_ALIASES_CACHE is None:
+        _BUILTIN_ALIASES_CACHE = _load_defaults(BUILTIN_MODELS_DIR)
+    return _BUILTIN_ALIASES_CACHE
+
+
+def resolve_attachment_alias(alias: str) -> List[str]:
+    """Resolve a single attachment alias (e.g. ``"image"``) to its
+    canonical MIME-type list. Raises ``ModelYAMLError`` if unknown.
+    """
+    aliases = builtin_attachment_aliases()
+    if alias not in aliases:
+        valid = ", ".join(sorted(aliases.keys())) or "<none defined>"
+        raise ModelYAMLError(
+            f"Unknown attachment alias '{alias}'. Valid: {valid}"
+        )
+    return list(aliases[alias])
+
+
+def expand_attachments_lenient(
+    attachments: Sequence[str], source: str
+) -> List[str]:
+    """Expand attachment aliases to MIME types, tolerating unknowns.
+
+    Mirrors ``_expand_attachments`` but logs+skips unknown aliases
+    rather than raising. Used for runtime call sites (BYOM registry
+    load) where an operator-side alias-map edit must not drop the
+    entire user's BYOM layer; the strict raise still happens at the
+    API validation boundary.
+    """
+    aliases = builtin_attachment_aliases()
+    expanded: List[str] = []
+    seen: set = set()
+    for entry in attachments:
+        if "/" in entry:
+            if entry not in seen:
+                expanded.append(entry)
+                seen.add(entry)
+            continue
+        mime_list = aliases.get(entry)
+        if mime_list is None:
+            logger.warning(
+                "%s: skipping unknown attachment alias %r", source, entry,
+            )
+            continue
+        for mime in mime_list:
+            if mime not in seen:
+                expanded.append(mime)
+                seen.add(mime)
+    return expanded
+
+
+def load_model_yamls(directories: Sequence[Path]) -> List[ProviderCatalog]:
+    """Load every ``*.yaml`` file (excluding ``_defaults.yaml``) under each
+    directory in order and return a flat list of catalogs.
+
+    Caller is responsible for merging multiple catalogs that target the
+    same provider plugin. The flat-list shape lets ``openai_compatible``
+    keep each file separate (one logical endpoint per file).
+
+    When the same model ``id`` appears in more than one YAML across the
+    directory list, a warning is logged. Order in the returned list
+    preserves load order, so the registry's "later wins" merge gives the
+    later directory's definition.
+    """
+    catalogs: List[ProviderCatalog] = []
+    seen_ids: Dict[str, Path] = {}
+
+    aliases: Dict[str, List[str]] = {}
+    for d in directories:
+        if not d or not d.exists():
+            continue
+        aliases.update(_load_defaults(d))
+
+    for d in directories:
+        if not d or not d.exists():
+            continue
+        for path in sorted(d.glob("*.yaml")):
+            if path.name == DEFAULTS_FILENAME:
+                continue
+            catalog = _load_one_yaml(path, aliases)
+            catalogs.append(catalog)
+            for m in catalog.models:
+                prior = seen_ids.get(m.id)
+                if prior is not None and prior != path:
+                    logger.warning(
+                        "Model id %r redefined: %s overrides %s (later wins)",
+                        m.id,
+                        path,
+                        prior,
+                    )
+                seen_ids[m.id] = path
+
+    return catalogs

docsgpt/core/models/README.md

@@ -0,0 +1,251 @@
+# Model catalogs
+
+Each `*.yaml` file in this directory declares one provider's model
+catalog. The registry loads every YAML at boot and joins it to the
+matching provider plugin under `docsgpt/llm/providers/`.
+
+To add or edit models, you almost always only touch a YAML here — no
+Python code required.
+
+## Add a model to an existing provider
+
+Open the provider's YAML (e.g. `anthropic.yaml`) and append two lines
+under `models:`:
+
+```yaml
+models:
+  - id: claude-3-7-sonnet
+    display_name: Claude 3.7 Sonnet
+```
+
+Capabilities default to the provider's `defaults:` block. Override
+per-model only when needed:
+
+```yaml
+  - id: claude-3-7-sonnet
+    display_name: Claude 3.7 Sonnet
+    context_window: 500000
+```
+
+Restart the app. The new model appears in `/api/models`.
+
+> The model `id` is what gets stored in agent / workflow records. Once
+> users start picking the model, **don't rename it** — agent and
+> workflow rows reference it as a free-form string and silently fall
+> back to the system default if the id disappears.
+
+## Add an OpenAI-compatible provider (zero Python)
+
+Drop a YAML in this directory (or in your `MODELS_CONFIG_DIR`) that uses
+the `openai_compatible` plugin. Set the env var named in `api_key_env`
+and you're done — no Python, no settings.py edit, no LLMCreator change:
+
+```yaml
+# mistral.yaml
+provider: openai_compatible
+display_provider: mistral             # shown in /api/models response
+api_key_env: MISTRAL_API_KEY          # env var the plugin reads at boot
+base_url: https://api.mistral.ai/v1
+defaults:
+  supports_tools: true
+  context_window: 128000
+models:
+  - id: mistral-large-latest
+    display_name: Mistral Large
+  - id: mistral-small-latest
+    display_name: Mistral Small
+```
+
+`MISTRAL_API_KEY=sk-... ; restart` — Mistral models appear in
+`/api/models` with `provider: "mistral"`. They route through the OpenAI
+wire format (it's `OpenAILLM` under the hood) but with Mistral's
+endpoint and key.
+
+Multiple `openai_compatible` YAMLs coexist: each file is one logical
+endpoint with its own `api_key_env` and `base_url`. Drop in
+`together.yaml`, `fireworks.yaml`, etc. side by side. If an env var
+isn't set, that catalog is silently skipped at boot (logged at INFO) —
+no error.
+
+Working example: `examples/mistral.yaml.example`. Files inside
+`examples/` aren't loaded by the registry; the glob only picks up
+`*.yaml` at the top level.
+
+## Add a provider with its own SDK
+
+For a provider that doesn't speak OpenAI's wire format, add one Python
+file to `docsgpt/llm/providers/<name>.py`:
+
+```python
+from docsgpt.llm.providers.base import Provider
+from docsgpt.llm.my_provider import MyLLM
+
+class MyProvider(Provider):
+    name = "my_provider"
+    llm_class = MyLLM
+
+    def get_api_key(self, settings):
+        return settings.MY_PROVIDER_API_KEY
+```
+
+Register it in `docsgpt/llm/providers/__init__.py` (one line in
+`ALL_PROVIDERS`), add `MY_PROVIDER_API_KEY` to `settings.py`, and create
+`my_provider.yaml` here with the model catalog.
+
+## Schema reference
+
+```yaml
+provider: <string, required>          # matches the Provider plugin's `name`
+
+# openai_compatible only — required for that provider, ignored for others
+display_provider: <string>            # label shown in /api/models response
+api_key_env: <string>                 # name of the env var carrying the key
+base_url: <string>                    # endpoint URL
+
+defaults:                              # optional, applied to every model below
+  supports_tools: bool                 # default false
+  supports_structured_output: bool     # default false
+  supports_streaming: bool             # default true
+  attachments: [<alias-or-mime>, ...]  # default []
+  context_window: int                  # default 128000
+  input_cost_per_token: float          # default null
+  output_cost_per_token: float         # default null
+  reasoning_effort: <string>           # default null; none|minimal|low|medium|high|xhigh (subset is model-dependent)
+  api_flavor: <string>                  # chat_completions (default) or responses
+
+models:                                # required
+  - id: <string, required>             # unique registry key; persisted in agent records
+    display_name: <string>             # default: id
+    description: <string>              # default: ""
+    enabled: bool                      # default true; false hides from /api/models
+    base_url: <string>                 # optional custom endpoint for this model
+    upstream_model_id: <string>        # default: id; the name actually sent to the provider
+    # All `defaults:` fields above can be overridden here per-model.
+```
+
+### Reasoning effort, and one model at multiple efforts
+
+`reasoning_effort` is forwarded to the provider for OpenAI reasoning
+models. Accepted values are `none`, `minimal`, `low`, `medium`, `high`,
+and `xhigh`, but the subset each model accepts varies (older o-series
+take only `low`/`medium`/`high`; GPT-5.5 adds `xhigh`) — check the model
+page. Set it per-model; sending it to a non-reasoning model is rejected
+by the API:
+
+```yaml
+  - id: gpt-5.4-mini
+    display_name: GPT-5.4 Mini
+    reasoning_effort: medium
+```
+
+To expose the *same* upstream model at two efforts, give each entry a
+distinct `id` and point both at one `upstream_model_id`. The `id` is the
+unique registry key (and what's stored in agent records); the
+`upstream_model_id` is the name actually sent to the provider, defaulting
+to `id` when omitted:
+
+```yaml
+  - id: gpt-5.4-mini-low
+    display_name: GPT-5.4 Mini (Low Reasoning)
+    upstream_model_id: gpt-5.4-mini
+    reasoning_effort: low
+  - id: gpt-5.4-mini-high
+    display_name: GPT-5.4 Mini (High Reasoning)
+    upstream_model_id: gpt-5.4-mini
+    reasoning_effort: high
+```
+
+Both call `gpt-5.4-mini` on the wire; token usage is attributed to the
+distinct `id`s, so cost dashboards split by reasoning level.
+
+### Attachment aliases
+
+The `attachments:` list can mix human-readable aliases with raw MIME
+types. Aliases are defined in `_defaults.yaml`:
+
+| Alias | Expands to |
+|---|---|
+| `image` | `image/png`, `image/jpeg`, `image/jpg`, `image/webp`, `image/gif` |
+| `pdf` | `application/pdf` |
+| `audio` | `audio/mpeg`, `audio/wav`, `audio/ogg` |
+
+Use raw MIME types when you need surgical control:
+
+```yaml
+attachments: [image/png, image/webp]   # only these two
+```
+
+## Operator-supplied YAMLs (`MODELS_CONFIG_DIR`)
+
+Set the `MODELS_CONFIG_DIR` env var (or `.env` entry) to a directory
+path. Every `*.yaml` in that directory is loaded **after** the built-in
+catalog under `docsgpt/core/models/`. Operators use this to:
+
+- Add new `openai_compatible` providers (Mistral, Together, Fireworks,
+  Ollama, ...) without forking the repo.
+- Extend an existing provider's catalog with extra models — append
+  models under `provider: anthropic` and they show up alongside the
+  built-ins.
+- Override a built-in model's capabilities — declare the same `id`
+  with different fields (e.g. a higher `context_window`). Later wins;
+  the override is logged as a `WARNING` so you can audit it.
+
+Things you cannot do via `MODELS_CONFIG_DIR`:
+
+- Add a brand-new non-OpenAI provider — that needs a Python plugin
+  under `docsgpt/llm/providers/` (see "Add a provider with its own
+  SDK" above). Operator YAMLs may only target a `provider:` value that
+  already has a registered plugin.
+
+### Example: Docker
+
+Mount your model YAMLs into the container and point the env var at the
+mount path:
+
+```yaml
+# docker-compose.yml
+services:
+  app:
+    image: arc53/docsgpt
+    environment:
+      MODELS_CONFIG_DIR: /etc/docsgpt/models
+      MISTRAL_API_KEY: ${MISTRAL_API_KEY}
+    volumes:
+      - ./my-models:/etc/docsgpt/models:ro
+```
+
+Then `./my-models/mistral.yaml` (the file from
+`examples/mistral.yaml.example`) gets picked up at boot.
+
+### Example: Kubernetes
+
+Mount a `ConfigMap` containing your YAMLs at a known path and set
+`MODELS_CONFIG_DIR` on the deployment. The same `examples/mistral.yaml.example`
+becomes a key in the ConfigMap.
+
+### Misconfiguration
+
+If `MODELS_CONFIG_DIR` is set but the path doesn't exist (or isn't a
+directory), the app logs a `WARNING` at boot and continues with just
+the built-in catalog. The app does *not* fail to start — operators can
+ship config drift without taking down the service — but the warning is
+loud enough to surface in any reasonable log aggregator.
+
+## Validation
+
+YAMLs are parsed with Pydantic at boot. The app fails to start with a
+clear error message if:
+
+- a top-level key is unknown
+- a model is missing `id`
+- an attachment alias isn't defined
+- the `provider:` value isn't registered as a plugin
+
+This is intentional — silent fallbacks would mean users don't notice
+their model picks broke until they hit the API.
+
+## Reserved fields (not yet implemented)
+
+- `aliases:` on a model — old IDs that resolve to this model. Reserved
+  for future renames; the schema accepts the field but it is not yet
+  acted on.

docsgpt/core/models/_defaults.yaml

@@ -0,0 +1,18 @@
+# Global defaults applied across every model YAML in this directory.
+# Keep this file sparse — per-provider `defaults:` blocks are clearer
+# than a deep global default chain. This file is for things that
+# genuinely never vary, like the meaning of "image".
+
+attachment_aliases:
+  image:
+    - image/png
+    - image/jpeg
+    - image/jpg
+    - image/webp
+    - image/gif
+  pdf:
+    - application/pdf
+  audio:
+    - audio/mpeg
+    - audio/wav
+    - audio/ogg

docsgpt/core/models/anthropic.yaml

@@ -0,0 +1,23 @@
+provider: anthropic
+defaults:
+  supports_tools: true
+  attachments: [image, pdf]
+  context_window: 200000
+
+models:
+  - id: claude-opus-4-7
+    display_name: Claude Opus 4.7
+    description: Most capable Claude model for complex reasoning and agentic coding
+    context_window: 1000000
+    supports_structured_output: true
+
+  - id: claude-sonnet-4-6
+    display_name: Claude Sonnet 4.6
+    description: Best balance of speed and intelligence with extended thinking
+    context_window: 1000000
+    supports_structured_output: true
+
+  - id: claude-haiku-4-5
+    display_name: Claude Haiku 4.5
+    description: Fastest Claude model with near-frontier intelligence
+    supports_structured_output: true

docsgpt/core/models/deepseek.yaml

@@ -0,0 +1,18 @@
+provider: openai_compatible
+display_provider: deepseek
+api_key_env: DEEPSEEK_API_KEY
+base_url: https://api.deepseek.com/v1
+
+defaults:
+  supports_tools: true
+  supports_structured_output: true
+  context_window: 1048576
+
+models:
+  - id: deepseek-v4-flash
+    display_name: DeepSeek V4 Flash
+    description: Cost-efficient 1M-context model with hybrid thinking / non-thinking modes, tool calling and FIM completion
+
+  - id: deepseek-v4-pro
+    display_name: DeepSeek V4 Pro
+    description: Frontier 1M-context model with hybrid thinking / non-thinking modes for advanced reasoning and agentic coding

docsgpt/core/models/docsgpt.yaml

@@ -0,0 +1,7 @@
+provider: docsgpt
+
+models:
+  - id: docsgpt-local
+    display_name: DocsGPT Model
+    description: Local model
+    supports_tools: true

docsgpt/core/models/examples/mistral.yaml.example

@@ -0,0 +1,31 @@
+# EXAMPLE — copy this file to ../mistral.yaml (or to your
+# MODELS_CONFIG_DIR) and set MISTRAL_API_KEY in your environment.
+#
+# This is the entire integration. No Python required: the
+# `openai_compatible` plugin reads `api_key_env` and `base_url` from
+# the file and routes calls through the OpenAI wire format.
+#
+# Files in this `examples/` directory are NOT loaded by the registry
+# (the loader globs *.yaml at the top level only).
+
+provider: openai_compatible
+display_provider: mistral             # shown in /api/models response
+api_key_env: MISTRAL_API_KEY          # env var the plugin reads
+base_url: https://api.mistral.ai/v1   # OpenAI-compatible endpoint
+
+defaults:
+  supports_tools: true
+  context_window: 128000
+
+models:
+  - id: mistral-large-latest
+    display_name: Mistral Large
+    description: Top-tier reasoning model
+
+  - id: mistral-small-latest
+    display_name: Mistral Small
+    description: Fast, cost-efficient
+
+  - id: codestral-latest
+    display_name: Codestral
+    description: Code-specialized model

docsgpt/core/models/google.yaml

@@ -0,0 +1,17 @@
+provider: google
+defaults:
+  supports_tools: true
+  supports_structured_output: true
+  attachments: [pdf, image]
+  context_window: 1048576
+
+models:
+  - id: gemini-3.1-pro-preview
+    display_name: Gemini 3.1 Pro (preview)
+    description: Most capable Gemini 3 model with advanced reasoning and agentic coding (preview)
+  - id: gemini-3.5-flash
+    display_name: Gemini 3.5 Flash
+    description: Frontier-class Flash for sustained performance on agentic and coding tasks
+  - id: gemini-3.1-flash-lite
+    display_name: Gemini 3.1 Flash-Lite
+    description: Cost-efficient frontier-class multimodal model for high-throughput workloads

docsgpt/core/models/groq.yaml

@@ -0,0 +1,16 @@
+provider: groq
+defaults:
+  supports_tools: true
+  context_window: 131072
+
+models:
+  - id: openai/gpt-oss-120b
+    display_name: GPT-OSS 120B
+    description: OpenAI's open-weight 120B flagship served on Groq's LPU hardware; strong general reasoning with strict structured output support
+    supports_structured_output: true
+  - id: llama-3.3-70b-versatile
+    display_name: Llama 3.3 70B Versatile
+    description: Meta's Llama 3.3 70B for general-purpose chat with parallel tool use
+  - id: llama-3.1-8b-instant
+    display_name: Llama 3.1 8B Instant
+    description: Small, very low-latency Llama model (~560 tok/s) with parallel tool use

docsgpt/core/models/huggingface.yaml

@@ -0,0 +1,7 @@
+provider: huggingface
+
+models:
+  - id: huggingface-local
+    display_name: Hugging Face Model
+    description: Local Hugging Face model
+    supports_tools: false

docsgpt/core/models/novita.yaml

@@ -0,0 +1,21 @@
+provider: novita
+defaults:
+  supports_tools: true
+  supports_structured_output: true
+
+models:
+  - id: deepseek/deepseek-v4-pro
+    display_name: DeepSeek V4 Pro
+    description: 1.6T MoE (49B active) with 1M context, hybrid CSA/HCA attention, top-tier reasoning and agentic coding
+    context_window: 1048576
+
+  - id: moonshotai/kimi-k2.6
+    display_name: Kimi K2.6
+    description: 1T-parameter open-weight MoE with native vision/video, multi-step tool calling, and agentic long-horizon execution
+    attachments: [image]
+    context_window: 262144
+
+  - id: zai-org/glm-5
+    display_name: GLM-5
+    description: Z.AI 754B-parameter MoE with strong general reasoning, function calling, and structured output
+    context_window: 202800

docsgpt/core/models/openai.yaml

@@ -0,0 +1,20 @@
+provider: openai
+defaults:
+  supports_tools: true
+  supports_structured_output: true
+  attachments: [image]
+  context_window: 400000
+
+models:
+  - id: gpt-5.5
+    display_name: GPT-5.5
+    description: Flagship frontier model for complex reasoning, coding, and agentic work with a 1M-token context window
+    context_window: 1050000
+    api_flavor: responses
+    reasoning_effort: medium
+  - id: gpt-5.4-mini
+    display_name: GPT-5.4 Mini
+    description: Cost-efficient GPT-5.4-class model for high-volume coding, computer use, and subagent workloads
+  - id: gpt-5.4-nano
+    display_name: GPT-5.4 Nano
+    description: Cheapest GPT-5.4-class model, optimized for simple high-volume tasks where speed and cost matter most

docsgpt/core/models/openrouter.yaml

@@ -0,0 +1,25 @@
+provider: openrouter
+defaults:
+  supports_tools: true
+  attachments: [image]
+  context_window: 128000
+
+models:
+  - id: qwen/qwen3-coder:free
+    display_name: Qwen3 Coder (free)
+    description: Free-tier 480B MoE coder model with strong agentic tool use; rate-limited
+    context_window: 262000
+    attachments: []
+
+  - id: deepseek/deepseek-v3.2
+    display_name: DeepSeek V3.2
+    description: Open-weights reasoning model, very low cost (~$0.25 in / $0.38 out per 1M)
+    context_window: 131072
+    attachments: []
+    supports_structured_output: true
+
+  - id: anthropic/claude-sonnet-4.6
+    display_name: Claude Sonnet 4.6 (via OpenRouter)
+    description: Frontier Sonnet-class model with 1M context, vision, and extended thinking
+    context_window: 1000000
+    supports_structured_output: true

docsgpt/core/optional_deps.py

@@ -0,0 +1,79 @@
+"""Optional dependency extras and the one place their install hints come from.
+
+Heavy or niche packages are not installed by default. Each extra maps to a
+pyproject extra and to an exported ``application/requirements-<extra>.txt``,
+so a missing module can always be explained with the exact command to run.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import sys
+from types import ModuleType
+from typing import Dict, Tuple
+
+#: Extra name -> top-level modules it provides. Keep in sync with
+#: ``[project.optional-dependencies]`` in pyproject.toml.
+EXTRAS: Dict[str, Tuple[str, ...]] = {
+    "docling": ("docling", "rapidocr"),
+    "milvus": ("pymilvus",),
+}
+
+_MODULE_TO_EXTRA: Dict[str, str] = {
+    module: extra for extra, modules in EXTRAS.items() for module in modules
+}
+
+
+def install_hint(extra: str) -> str:
+    """Install command for ``extra``, for error messages and logs."""
+    return (
+        f"pip install -r application/requirements-{extra}.txt "
+        f"(or: uv sync --extra {extra}; Docker: --build-arg EXTRAS={extra})"
+    )
+
+
+def extra_for(module: str) -> str | None:
+    """Extra that provides top-level module ``module``, if any."""
+    return _MODULE_TO_EXTRA.get(module.split(".")[0])
+
+
+def is_available(module: str) -> bool:
+    """Whether ``module`` can be imported, without importing it."""
+    root = module.split(".")[0]
+    if root in sys.modules:
+        return sys.modules[root] is not None
+    try:
+        return importlib.util.find_spec(root) is not None
+    except (ImportError, ValueError):
+        return False
+
+
+def missing_message(module: str, purpose: str | None = None) -> str:
+    """Human-readable explanation that ``module`` is absent and how to add it."""
+    extra = extra_for(module)
+    what = f"{module} is not installed"
+    if purpose:
+        what += f" ({purpose})"
+    if extra:
+        return f"{what}. It is part of the optional '{extra}' extra: {install_hint(extra)}"
+    return f"{what}. Install it with: pip install {module}"
+
+
+def require(module: str, purpose: str | None = None) -> ModuleType:
+    """Import ``module`` or raise ``ImportError`` naming the extra to install.
+
+    Args:
+        module: Importable module path, e.g. ``"pymilvus"``.
+        purpose: Short note on what needed it, included in the error.
+
+    Returns:
+        The imported module.
+
+    Raises:
+        ImportError: With the install hint when the module is absent.
+    """
+    try:
+        return importlib.import_module(module)
+    except ImportError as exc:
+        raise ImportError(missing_message(module, purpose)) from exc

docsgpt/core/secret_key.py

@@ -0,0 +1,89 @@
+"""Resolve stable application signing secrets for local and production use."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+
+_SHARED_SECRET_DEPLOYMENTS = {"cloud", "production"}
+
+
+def _read_secret_file(key_path: Path) -> str:
+    """Read and validate a generated local signing secret."""
+    secret = key_path.read_text(encoding="utf-8").strip()
+    if not secret:
+        raise RuntimeError(f"Signing secret file is empty: {key_path}")
+    return secret
+
+
+def _create_secret_file_atomically(key_path: Path) -> str:
+    """Create a complete mode-0600 secret before atomically publishing it."""
+    new_secret = os.urandom(32).hex()
+    descriptor, temporary_name = tempfile.mkstemp(
+        dir=key_path.parent,
+        prefix=f".{key_path.name}.",
+        text=True,
+    )
+    temporary_path = Path(temporary_name)
+    try:
+        if hasattr(os, "fchmod"):
+            os.fchmod(descriptor, 0o600)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as temporary_file:
+            descriptor = -1
+            temporary_file.write(new_secret)
+            temporary_file.flush()
+            os.fsync(temporary_file.fileno())
+
+        try:
+            # A hard link publishes the fully written file without replacing a
+            # secret another process may have won the race to create.
+            os.link(temporary_path, key_path)
+        except FileExistsError:
+            return _read_secret_file(key_path)
+        return new_secret
+    finally:
+        if descriptor >= 0:
+            os.close(descriptor)
+        temporary_path.unlink(missing_ok=True)
+
+
+def resolve_jwt_secret_key(
+    configured_secret: str | None,
+    deployment_type: str | None,
+    key_file: str | Path = ".jwt_secret_key",
+) -> str:
+    """Return a shared configured secret or a stable local-development secret.
+
+    Args:
+        configured_secret: Operator-supplied signing secret.
+        deployment_type: Deployment class, such as ``cloud`` or ``production``.
+        key_file: Local fallback file used outside production deployments.
+
+    Returns:
+        The configured or locally persisted signing secret.
+
+    Raises:
+        RuntimeError: If production lacks a shared secret or local persistence fails.
+    """
+    if configured_secret and configured_secret.strip():
+        return configured_secret
+
+    normalized_deployment = (deployment_type or "").strip().lower()
+    if normalized_deployment in _SHARED_SECRET_DEPLOYMENTS:
+        raise RuntimeError(
+            "JWT_SECRET_KEY must be set to the same strong random value on every "
+            f"{normalized_deployment} API and worker replica"
+        )
+
+    key_path = Path(key_file)
+    try:
+        return _read_secret_file(key_path)
+    except FileNotFoundError:
+        try:
+            return _create_secret_file_atomically(key_path)
+        except Exception as exc:
+            raise RuntimeError(f"Failed to create signing secret: {exc}") from exc
+    except Exception as exc:
+        raise RuntimeError(f"Failed to read signing secret: {exc}") from exc

docsgpt/core/settings.py

@@ -0,0 +1,586 @@
+import os
+from pathlib import Path
+from typing import Optional
+
+from pydantic import AliasChoices, Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+current_dir = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+from docsgpt.core.db_uri import (  # noqa: E402
+    normalize_pgvector_connection_string,
+    normalize_postgres_uri,
+)
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(extra="ignore")
+
+    AUTH_TYPE: Optional[str] = None  # simple_jwt, session_jwt, oidc, or None
+
+    # OIDC SSO (AUTH_TYPE=oidc) — any OpenID Connect IdP with discovery (Authentik, Keycloak, ...)
+    OIDC_ISSUER: Optional[str] = None  # e.g. https://auth.example.com/application/o/docsgpt/
+    OIDC_CLIENT_ID: Optional[str] = None
+    OIDC_CLIENT_SECRET: Optional[str] = None  # optional; PKCE is always used
+    OIDC_SCOPES: str = "openid profile email"
+    OIDC_USER_ID_CLAIM: str = "sub"  # ID-token claim mapped to the DocsGPT user id
+    OIDC_FRONTEND_URL: Optional[str] = None  # browser-facing app origin, e.g. http://localhost:5173
+    OIDC_REDIRECT_URI: Optional[str] = None  # override; default <request host>/api/auth/oidc/callback
+    OIDC_SESSION_LIFETIME_SECONDS: int = 28800  # minted session JWT lifetime (8h)
+    OIDC_PROVIDER_NAME: Optional[str] = None  # sign-in button label, e.g. "Acme SSO"
+    OIDC_ALLOWED_GROUPS: Optional[str] = None  # comma-separated allowlist; unset = any authenticated user
+    OIDC_GROUPS_CLAIM: str = "groups"  # ID-token/userinfo claim carrying group membership
+    OIDC_ADMIN_GROUPS: Optional[str] = None  # comma-separated groups granted admin; unset = no OIDC admin mapping
+
+    # RBAC: persisted admin grants live in user_roles (AUTH_TYPE=oidc only). This is the
+    # only non-DB admin path, for AUTH_TYPE=None self-host. MUST stay False if networked.
+    LOCAL_MODE_ADMIN: bool = False
+
+    # SCIM 2.0 provisioning (IdP-driven user create/deactivate at /scim/v2)
+    SCIM_ENABLED: bool = False
+    SCIM_TOKEN: Optional[str] = None  # bearer token for IdP SCIM clients (required when enabled)
+
+    LLM_PROVIDER: str = "docsgpt"
+    LLM_NAME: Optional[str] = None  # if LLM_PROVIDER is openai, LLM_NAME can be gpt-4 or gpt-3.5-turbo
+    # Legacy model on purpose: an install that never pinned this has vectors from it, and
+    # granite is the same width so a swap would fail silently. New installs get granite from
+    # .env-template; existing ones switch by setting this and running docsgpt.scripts.reembed.
+    EMBEDDINGS_NAME: str = "huggingface_sentence-transformers/all-mpnet-base-v2"
+    EMBEDDINGS_BASE_URL: Optional[str] = None  # Remote embeddings API URL (OpenAI-compatible)
+    EMBEDDINGS_KEY: Optional[str] = None  # api key for embeddings (if using openai, just copy API_KEY)
+    EMBEDDINGS_MAX_INPUT_TOKENS: Optional[int] = None  # truncate each remote embed input to N tokens (overflow lost)
+    EMBEDDINGS_BATCH_SIZE: int = 32  # chunks per store transaction / remote embed request
+    # Documents per local ONNX forward pass. Each pass pads to its longest input, and that
+    # waste grows with the square of chunk length: at 1250 tokens, 32 peaked at 6.6 GB, 1 at 2.9 GB.
+    EMBEDDINGS_MODEL_BATCH_SIZE: int = 1
+    # Intra-op threads for the local ONNX runner; None = every core. It scales sub-linearly,
+    # so several single-threaded workers beat one many-threaded process on the same cores.
+    EMBEDDINGS_THREADS: Optional[int] = None
+    EMBEDDINGS_CACHE_DIR: Optional[str] = None  # where FastEmbed caches model artifacts
+    # Pooling ("cls"/"mean") and L2 normalisation. Read from the model's own repository;
+    # set these only for a repository that declares neither, or to override what it declares.
+    EMBEDDINGS_POOLING: Optional[str] = None
+    EMBEDDINGS_NORMALIZE: Optional[bool] = None
+    # Embed on the worker so the API holds no model (~890 MB), at one broker round trip per
+    # query. Ignored when EMBEDDINGS_BASE_URL is set, which is the better answer for production.
+    EMBEDDINGS_DELEGATE_TO_WORKER: bool = True
+    EMBEDDINGS_QUEUE: str = "embeddings"  # queue the embed task is routed to
+    EMBEDDINGS_DELEGATE_TIMEOUT: int = 60  # seconds to wait for the worker
+    GITHUB_INGEST_MAX_FILE_BYTES: int = 1048576  # skip repo blobs larger than this (0 = no cap)
+    GITHUB_INGEST_MAX_WORKERS: int = 8  # parallel file fetches per GitHub repo ingest
+    # Operator-supplied model YAMLs, loaded after the built-in catalog; later wins on
+    # duplicate model id. See docsgpt/core/models/README.md.
+    MODELS_CONFIG_DIR: Optional[str] = None
+
+    CELERY_BROKER_URL: str = "redis://localhost:6379/0"
+    CELERY_RESULT_BACKEND: str = "redis://localhost:6379/1"
+    # Prefetch=1 caps SIGKILL loss to one task. Visibility timeout must exceed the longest
+    # legitimate task runtime but stay short enough that SIGKILLed tasks redeliver promptly.
+    CELERY_WORKER_PREFETCH_MULTIPLIER: int = 1
+    CELERY_VISIBILITY_TIMEOUT: int = 3600
+    # Recycle a prefork child past this resident size in KB; backstops docling/torch heap growth.
+    # Checked between tasks, so it does not bound the peak within one. 0 disables.
+    CELERY_WORKER_MAX_MEMORY_PER_CHILD: int = 4194304
+    CELERY_WORKER_MAX_TASKS_PER_CHILD: int = 0  # recycle after N tasks; 0 disables
+    # Only consulted when VECTOR_STORE=mongodb or when running scripts/db/backfill.py; user data lives in Postgres.
+    MONGO_URI: Optional[str] = None
+    # User-data Postgres DB.
+    POSTGRES_URI: Optional[str] = None
+    # On startup, apply pending Alembic migrations. Disable if you manage schema out-of-band.
+    AUTO_MIGRATE: bool = True
+    # On startup, create the target Postgres database if missing (needs CREATEDB privilege).
+    AUTO_CREATE_DB: bool = True
+    # On startup, create the pgvector/graph tables and verify the embedding dimension. No Alembic
+    # migration covers the vector DB (it may be a separate cluster); set False to manage it yourself.
+    AUTO_VECTOR_SCHEMA: bool = True
+    LLM_PATH: str = os.path.join(current_dir, "models/docsgpt-7b-f16.gguf")
+    DEFAULT_MAX_HISTORY: int = 150
+    DEFAULT_LLM_TOKEN_LIMIT: int = 128000  # Fallback when model not found in registry
+    RESERVED_TOKENS: dict = {
+        "system_prompt": 500,
+        "current_query": 500,
+        "safety_buffer": 1000,
+    }
+    DEFAULT_AGENT_LIMITS: dict = {
+        "token_limit": 50000,
+        "request_limit": 500,
+    }
+    UPLOAD_FOLDER: str = "inputs"
+    # Request cap is applied by Flask before multipart parsing; the per-file cap also while copying.
+    UPLOAD_MAX_REQUEST_BYTES: int = Field(default=256 * 1024 * 1024, gt=0)
+    UPLOAD_MAX_FILE_BYTES: int = Field(default=100 * 1024 * 1024, gt=0)
+    PARSE_SPEC_MAX_BYTES: int = Field(default=10 * 1024 * 1024, gt=0)
+    # ZIP limits apply cumulatively across nested archives in one extraction.
+    UPLOAD_MAX_ARCHIVE_BYTES: int = Field(default=250 * 1024 * 1024, gt=0)
+    UPLOAD_MAX_ARCHIVE_FILES: int = Field(default=10_000, gt=0)
+    UPLOAD_MAX_ARCHIVE_RATIO: int = Field(default=1000, gt=0)
+    UPLOAD_MAX_ARCHIVE_DEPTH: int = Field(default=3, ge=0)
+    PARSE_PDF_AS_IMAGE: bool = False
+    PARSE_IMAGE_REMOTE: bool = False
+    # Document parser for source ingestion, chat attachments and the
+    # read_document tool. "anydoc" (default): firecrawl-anydoc, a Rust
+    # converter with no ML models — milliseconds per file, ~100 MB peak RSS.
+    # "docling": the layout/table-model pipeline (optional install; needed
+    # for read_document's structured output and the docling OCR backend).
+    # Files anydoc cannot convert (scanned PDFs, malformed input) fall back to
+    # docling when it is installed, otherwise to the native OCR parsers (OCR
+    # on) or the legacy parsers. Rollback to the previous behaviour is this
+    # one variable.
+    DOC_PARSER_ENGINE: str = "anydoc"
+    # OCR for scanned PDFs and images. OCR_ENABLED covers source ingestion,
+    # OCR_ATTACHMENTS_ENABLED chat attachments. Which stack performs it is
+    # OCR_BACKEND; which engine, OCR_ENGINE. The DOCLING_OCR_* names are the
+    # pre-2026-09 spellings and stay accepted as aliases.
+    OCR_ENABLED: bool = Field(
+        default=False, validation_alias=AliasChoices("OCR_ENABLED", "DOCLING_OCR_ENABLED")
+    )
+    OCR_ATTACHMENTS_ENABLED: bool = Field(
+        default=False,
+        validation_alias=AliasChoices("OCR_ATTACHMENTS_ENABLED", "DOCLING_OCR_ATTACHMENTS_ENABLED"),
+    )
+    # Which stack runs OCR when it is on:
+    #   auto    — docling when installed, otherwise native.
+    #   docling — the layout-model pipeline (hybrid region OCR, reading order,
+    #             table structure); needs the optional docling extra.
+    #   native  — pypdfium2/Pillow page rendering straight into tesseract or a
+    #             DeepSeek-OCR endpoint (docsgpt/parser/file/ocr_parser.py).
+    #             No ML models in the worker; tables come out as text lines
+    #             under tesseract.
+    OCR_BACKEND: str = "auto"
+    # Pages docling's threaded pipeline buffers in flight; the library
+    # default (100) drives worker RSS to ~3 GB on a mid-size PDF.
+    DOCLING_PIPELINE_QUEUE_MAX_SIZE: int = 2
+    DOCLING_COMPILE_TORCH_MODELS: bool = False
+    DOCLING_TABULAR_MAX_BYTES: int = 2_000_000
+    DOCLING_MARKUP_MAX_BYTES: int = 8_000_000
+    # HTML/XHTML larger than this (bytes) are head-truncated before the
+    # markdownify parser runs (the anydoc engine's HTML path). The tree that
+    # path builds costs ~50x the input — 30 MB of HTML measured at 1.6 GB RSS —
+    # and the upload cap is 100 MB, so the gate is what keeps one upload from
+    # taking the ingest worker down. 0 disables it.
+    MARKUP_MAX_BYTES: int = 8_000_000
+    # Trust-check anydoc's PDF output (docsgpt/parser/file/pdf_trust.py):
+    # flag composite (Type0) fonts without a ToUnicode map, and CJK-declaring
+    # PDFs whose extracted text has almost no CJK — the two classes where
+    # anydoc drops text silently. A flagged file re-parses on the docling
+    # fallback when docling is installed; otherwise the anydoc output is kept
+    # and the document gets extra_info["parse_warnings"]. ~30 ms per scanned MB.
+    PDF_TRUST_CHECK: bool = True
+    # Rewrite dot-leader / whitespace-aligned table runs in anydoc's PDF
+    # markdown into GFM tables (docsgpt/parser/file/tableize.py). Off by
+    # default: it rewrites content on a heuristic (>=3 uniform label+numbers
+    # lines) validated only on a small corpus so far.
+    ANYDOC_TABLEIZE: bool = False
+    # OCR engine used when OCR is on (OCR_ENABLED / OCR_ATTACHMENTS_ENABLED).
+    # Benched 2026-08 on EN/ZH/table/degraded scans (docs/Guides/ocr has the
+    # menu):
+    #   tesseract — recommended: best classic-engine accuracy (perfect EN word
+    #     recall, 0.000 bilingual CER, 100% table cells), ~35 MB, CPU-only.
+    #     Needs the system binary + language packs: an optional install like
+    #     every OCR dependency (build with INSTALL_TESSERACT=true, or apt/brew
+    #     install tesseract-ocr for a local run). Both backends.
+    #   deepseek — DeepSeek-OCR against an Ollama/vLLM endpoint
+    #     (OCR_DEEPSEEK_*). Best table/CJK quality; the worker stays light
+    #     (no layout models) but each page costs seconds on the model server.
+    #     Both backends.
+    #   auto — docling's pick: ocrmac on macOS (excellent), rapidocr on Linux
+    #     (silently shreds some long text lines — avoid as a server default).
+    #   ocrmac | rapidocr — force one of those.
+    # auto/ocrmac/rapidocr exist only inside docling; the native backend runs
+    # tesseract for them. An engine that is not installed degrades (docling:
+    # to "auto") with a warning instead of failing the parse.
+    OCR_ENGINE: str = "tesseract"
+    # Tesseract language packs, "+"-separated (e.g. "eng+chi_sim+deu"). Other
+    # engines keep their own defaults — their language codes differ.
+    OCR_LANGS: str = "eng"
+    OCR_DEEPSEEK_URL: str = "http://localhost:11434/v1/chat/completions"
+    OCR_DEEPSEEK_MODEL: str = "deepseek-ocr:3b"
+    # Seconds allowed per page request to the DeepSeek endpoint, on both
+    # backends (native sends pages one at a time; docling's VLM pipeline
+    # keeps its own concurrency). A 3B model on a laptop needs minutes; a
+    # vLLM GPU deployment, seconds.
+    OCR_DEEPSEEK_TIMEOUT: float = 300.0
+    # Native backend only: resolution at which pages without a text layer are
+    # rendered before OCR. 200 suits tesseract; clamped to 72-600.
+    OCR_RENDER_DPI: int = 200
+    # Chars-per-page floor below which an OCR'd PDF/image parse is treated as an OCR
+    # dropout (long-running docling workers were observed returning zero characters for
+    # every scanned page after a long scanned PDF, with no error) rather than as content.
+    # docling retries once on a fresh full-page-OCR converter; both backends then fail
+    # loudly instead of indexing an empty document. 0 disables the guard.
+    OCR_MIN_CHARS_PER_PAGE: int = Field(
+        default=20, validation_alias=AliasChoices("OCR_MIN_CHARS_PER_PAGE", "DOCLING_OCR_MIN_CHARS_PER_PAGE")
+    )
+    # Read PDF *attachments* via their embedded text layer (pypdfium2) instead
+    # of docling, falling back to docling when there is no text layer to read.
+    # Attachments go into a prompt, so docling's structural markdown earns far
+    # less than the tens of seconds per file it costs; source ingestion is
+    # unaffected and always uses docling, because chunking and retrieval do
+    # depend on that structure.
+    ATTACHMENT_PDF_TEXT_FAST_PATH: bool = True
+    # Median chars per sampled page below which a PDF is treated as a scan and handed to docling.
+    # Measured on real uploads: scans at 0-17 chars/page, text-layer documents at 433-6834.
+    ATTACHMENT_PDF_TEXT_MIN_MEDIAN_CHARS: int = 32
+    ATTACHMENT_TEXT_MAX_BYTES: int = 5_000_000
+    AGENT_IMAGE_MAX_BYTES: int = 5_000_000
+    AGENT_IMAGE_MAX_PIXELS: int = 16_777_216
+    VECTOR_STORE: str = "faiss"  #  "faiss" or "elasticsearch" or "qdrant" or "milvus" or "lancedb" or "pgvector"
+    # Retriever keys an agent may use; must match RetrieverCreator.retrievers registry keys,
+    # NOT the legacy ``classic_rag`` label which never matched the registry.
+    RETRIEVERS_ENABLED: list = ["classic", "default"]
+    # Concurrent per-source searches in one retrieval; the query is embedded once and shared.
+    RETRIEVAL_MAX_PARALLEL_SOURCES: int = 4
+    # Kill-switch for per-source retrieval dispatch; False collapses to a single retriever.
+    PER_SOURCE_RETRIEVAL_ENABLED: bool = True
+    GRAPHRAG_ENABLED: bool = False  # gates graph-aware ingestion/retrieval
+    # Model for ingest-time graph extraction; None reuses LLM_PROVIDER/LLM_NAME.
+    GRAPHRAG_EXTRACTION_MODEL: Optional[str] = None
+    # Hard cap on chunks extracted per source (cost control).
+    GRAPHRAG_MAX_CHUNKS_FOR_EXTRACTION: int = 2000
+    AGENT_NAME: str = "classic"
+    FALLBACK_LLM_PROVIDER: Optional[str] = None  # provider for fallback llm
+    FALLBACK_LLM_NAME: Optional[str] = None  # model name for fallback llm
+    FALLBACK_LLM_API_KEY: Optional[str] = None  # api key for fallback llm
+
+    # Google Drive integration
+    GOOGLE_CLIENT_ID: Optional[str] = None  # Replace with your actual Google OAuth client ID
+    GOOGLE_CLIENT_SECRET: Optional[str] = None  # Replace with your actual Google OAuth client secret
+    CONNECTOR_REDIRECT_BASE_URI: Optional[str] = (
+        "http://127.0.0.1:7091/api/connectors/callback"  ##add redirect url as it is to your provider's console(gcp)
+    )
+
+    # Microsoft Entra ID (Azure AD) integration
+    MICROSOFT_CLIENT_ID: Optional[str] = None  # Azure AD Application (client) ID
+    MICROSOFT_CLIENT_SECRET: Optional[str] = None  # Azure AD Application client secret
+    MICROSOFT_TENANT_ID: Optional[str] = "common"  # Azure AD Tenant ID (or 'common' for multi-tenant)
+    MICROSOFT_AUTHORITY: Optional[str] = None  # e.g., "https://login.microsoftonline.com/{tenant_id}"
+
+    # Confluence Cloud integration
+    CONFLUENCE_CLIENT_ID: Optional[str] = None
+    CONFLUENCE_CLIENT_SECRET: Optional[str] = None
+
+    # GitHub source
+    GITHUB_ACCESS_TOKEN: Optional[str] = None  # PAT token with read repo access
+
+    # LLM Cache
+    CACHE_REDIS_URL: str = "redis://localhost:6379/2"
+
+    API_URL: str = "http://localhost:7091"  # backend url for celery worker
+
+    # Public base URL for user-facing endpoint references in prompts
+    PUBLIC_API_BASE_URL: Optional[str] = None
+    MCP_OAUTH_REDIRECT_URI: Optional[str] = None  # public callback URL for MCP OAuth
+    INTERNAL_KEY: Optional[str] = None  # internal api key for worker-to-backend auth
+
+    API_KEY: Optional[str] = None  # LLM api key (used by LLM_PROVIDER)
+
+    # Provider-specific API keys (for multi-model support)
+    OPENAI_API_KEY: Optional[str] = None
+    ANTHROPIC_API_KEY: Optional[str] = None
+    GOOGLE_API_KEY: Optional[str] = None
+    GROQ_API_KEY: Optional[str] = None
+    HUGGINGFACE_API_KEY: Optional[str] = None
+    OPEN_ROUTER_API_KEY: Optional[str] = None
+    NOVITA_API_KEY: Optional[str] = None
+
+    OPENAI_API_BASE: Optional[str] = None  # azure openai api base url
+    OPENAI_API_VERSION: Optional[str] = None  # azure openai api version
+    AZURE_DEPLOYMENT_NAME: Optional[str] = None  # azure deployment name for answering
+    AZURE_EMBEDDINGS_DEPLOYMENT_NAME: Optional[str] = None  # azure deployment name for embeddings
+    OPENAI_BASE_URL: Optional[str] = None  # openai base url for open ai compatable models
+
+    # elasticsearch
+    ELASTIC_CLOUD_ID: Optional[str] = None  # cloud id for elasticsearch
+    ELASTIC_USERNAME: Optional[str] = None  # username for elasticsearch
+    ELASTIC_PASSWORD: Optional[str] = None  # password for elasticsearch
+    ELASTIC_URL: Optional[str] = None  # url for elasticsearch
+    ELASTIC_INDEX: Optional[str] = "docsgpt"  # index name for elasticsearch
+
+    # Legacy AWS credentials from the retired SageMaker provider. Still read as a deprecated
+    # fallback by S3 storage; do not use for new deployments.
+    SAGEMAKER_REGION: Optional[str] = None
+    SAGEMAKER_ACCESS_KEY: Optional[str] = None
+    SAGEMAKER_SECRET_KEY: Optional[str] = None
+
+    # Qdrant vectorstore config
+    QDRANT_COLLECTION_NAME: Optional[str] = "docsgpt"
+    QDRANT_LOCATION: Optional[str] = None
+    QDRANT_URL: Optional[str] = None
+    QDRANT_PORT: Optional[int] = 6333
+    QDRANT_GRPC_PORT: int = 6334
+    QDRANT_PREFER_GRPC: bool = False
+    QDRANT_HTTPS: Optional[bool] = None
+    QDRANT_API_KEY: Optional[str] = None
+    QDRANT_PREFIX: Optional[str] = None
+    QDRANT_TIMEOUT: Optional[float] = None
+    QDRANT_HOST: Optional[str] = None
+    QDRANT_PATH: Optional[str] = None
+    QDRANT_DISTANCE_FUNC: str = "Cosine"
+
+    # PGVector config. postgres://, postgresql:// and postgresql+psycopg:// are all accepted
+    # and normalized internally for psycopg.connect().
+    PGVECTOR_CONNECTION_STRING: Optional[str] = None
+    PGVECTOR_POOL_MAX_SIZE: int = 8  # per-process pool; 0 = one direct connection per store
+    # IVFFlat probes; None derives sqrt(lists) from the index. Higher = better recall, more scan.
+    PGVECTOR_IVFFLAT_PROBES: Optional[int] = None
+    # Milvus vectorstore config
+    MILVUS_COLLECTION_NAME: Optional[str] = "docsgpt"
+    MILVUS_URI: Optional[str] = "./milvus_local.db"  # milvus lite version as default
+    MILVUS_TOKEN: Optional[str] = ""
+
+    # LanceDB vectorstore config
+    LANCEDB_PATH: str = "./data/lancedb"  # Path where LanceDB stores its local data
+    LANCEDB_TABLE_NAME: Optional[str] = "docsgpts"  # Name of the table to use for storing vectors
+
+    FLASK_DEBUG_MODE: bool = False
+    STORAGE_TYPE: str = "local"  # local or s3
+
+    # S3-compatible object storage (STORAGE_TYPE=s3): AWS S3, MinIO, R2, B2, Spaces, ...
+    # For non-AWS, set S3_ENDPOINT_URL and usually S3_PATH_STYLE=true.
+    S3_BUCKET_NAME: str = "docsgpt-test-bucket"
+    S3_ENDPOINT_URL: Optional[str] = None  # custom endpoint for S3-compatible services; omit for AWS
+    S3_ACCESS_KEY_ID: Optional[str] = None
+    S3_SECRET_ACCESS_KEY: Optional[str] = None
+    S3_REGION: Optional[str] = None  # AWS region; use "auto" for Cloudflare R2
+    S3_PATH_STYLE: bool = False  # path-style addressing (required by most non-AWS services)
+
+    # Anonymous startup version check for security issues.
+    VERSION_CHECK: bool = True
+    URL_STRATEGY: str = "backend"  # backend or s3
+
+    JWT_SECRET_KEY: str = ""
+
+    # Encryption settings
+    ENCRYPTION_SECRET_KEY: str = "default-docsgpt-encryption-key"
+
+    TTS_PROVIDER: str = "google_tts"  # google_tts or elevenlabs
+    ELEVENLABS_API_KEY: Optional[str] = None
+    STT_PROVIDER: str = "openai"  # openai or faster_whisper
+    OPENAI_STT_MODEL: str = "gpt-4o-mini-transcribe"
+    STT_LANGUAGE: Optional[str] = None
+    STT_MAX_FILE_SIZE_MB: int = 50
+    STT_ENABLE_TIMESTAMPS: bool = False
+    STT_ENABLE_DIARIZATION: bool = False
+
+    # Tool pre-fetch settings
+    ENABLE_TOOL_PREFETCH: bool = True
+
+    # True persists Responses API calls server-side so previous_response_id can chain turns.
+    # False keeps them stateless, carrying reasoning across the tool loop as encrypted items.
+    OPENAI_RESPONSES_STORE: bool = False
+    # Cross-turn ``previous_response_id`` chaining (store mode only). The
+    # chained transcript lives on the provider and is invisible to every
+    # local guard, so it is bounded: a turn starts from the local history
+    # when the previous turn's reported prompt already reached the budget
+    # (default: the model's context window) or when the conversation was
+    # compressed after that turn was produced.
+    OPENAI_RESPONSES_CHAIN_ACROSS_TURNS: bool = True
+    OPENAI_RESPONSES_CHAIN_BUDGET_TOKENS: Optional[int] = None
+    # ``truncation: "auto"`` lets the provider drop the oldest input items
+    # instead of failing every request once a chain exceeds the model's window.
+    OPENAI_RESPONSES_TRUNCATION_AUTO: bool = False
+    # Prompt-cache hints on the Responses API: route a user's calls to the
+    # same cache shard (opaque per-user key), and request extended retention
+    # where offered.
+    OPENAI_PROMPT_CACHE_KEY: bool = True
+    OPENAI_PROMPT_CACHE_RETENTION: Optional[str] = None
+    OPENAI_REASONING_SUMMARY: str = "auto"
+
+    # Lets OpenAI-compatible clients identify a logical chat by session header, which
+    # chat-completions itself has no field for.
+    V1_SESSION_TTL_SECONDS: int = 24 * 60 * 60
+    # Optional cheaper model for conversation titles; unset reuses the answer model.
+    TITLE_MODEL_ID: Optional[str] = None
+
+    # Config-free tools on by default in agentless chats. ``scheduler`` is dual-registered in
+    # BUILTIN_AGENT_TOOLS so one synthetic id resolves via defaults or the agent picker.
+    # Add "code_executor" and "artifact_generator" once a sandbox runner is configured — both
+    # execute through it and would fail on every call without one.
+    DEFAULT_CHAT_TOOLS: list = [
+        "memory",
+        "read_webpage",
+        "scheduler",
+    ]
+
+    # Conversation Compression Settings
+    ENABLE_CONVERSATION_COMPRESSION: bool = True
+    COMPRESSION_THRESHOLD_PERCENTAGE: float = 0.8  # Trigger at 80% of context
+    COMPRESSION_MODEL_OVERRIDE: Optional[str] = None  # Use different model for compression
+    COMPRESSION_PROMPT_VERSION: str = "v1.0"  # Track prompt iterations
+    COMPRESSION_MAX_HISTORY_POINTS: int = 3  # Keep only last N compression points to prevent DB bloat
+    # Per-field cap on the verbatim tail kept after a compression point (0 disables).
+    COMPRESSION_RECENT_FIELD_MAX_TOKENS: int = 8000
+    # Cap on one tool result entering the LLM context (0 disables); journal/DB keep it whole.
+    TOOL_RESULT_MAX_TOKENS: int = 20000
+
+    # Agent Guardrails
+    GUARDRAILS_ENABLED: bool = True  # master switch; False disables every stage
+    # Allowlist of GuardrailCreator.checks keys; empty means every registered check.
+    GUARDRAILS_CHECKS_ENABLED: list = []
+    # A GuardrailsConfig fragment every agent inherits and cannot weaken; agents may add
+    # controls or make an action stricter, never looser. "enabled" is required — without it
+    # the floor parses but applies to nothing. Example:
+    # {"enabled": true, "mode": "scan_all",
+    #  "controls": [{"check": "secrets", "stage": "output", "action": "redact"}]}
+    GUARDRAILS_FLOOR: dict = {}
+    # Judge model for the topic/policy checks; None reuses the request's model.
+    GUARDRAILS_JUDGE_MODEL: Optional[str] = None
+    # Persist scanned text alongside guardrail_events. Off by default: pre-redaction text is
+    # exactly the material a PII control exists to keep out of storage.
+    GUARDRAILS_STORE_SCANNED_TEXT: bool = False
+    GUARDRAILS_EVENTS_RETENTION_DAYS: int = Field(default=30, ge=1)
+
+    # Internal SSE push channel (notifications + durable replay journal).
+    # False makes /api/events emit "push_disabled" and return; clients fall back to polling.
+    ENABLE_SSE_PUSH: bool = True
+    # Per-user durable backlog cap in entries; ~24h of replay at typical rates.
+    EVENTS_STREAM_MAXLEN: int = 1000
+    # Bounds uvicorn's shutdown drain (uvicorn_worker doesn't forward --graceful-timeout).
+    # Keep below the gunicorn --timeout (180) watchdog. Used by BoundedDrainUvicornWorker.
+    GRACEFUL_SHUTDOWN_TIMEOUT_SECONDS: int = 30
+    WSGI_THREADPOOL_WORKERS: int = 96
+    SSE_KEEPALIVE_SECONDS: int = Field(default=15, ge=1)
+    # Simultaneous SSE connections per user; each holds a WSGI thread and a Redis pub/sub
+    # connection. 8 covers multi-tab use without one user starving the pool. 0 disables.
+    SSE_MAX_CONCURRENT_PER_USER: int = 8
+    # Backlog entries XRANGE returns per /api/events snapshot. Bounds what one replay moves
+    # from Redis to the wire: a client looping Last-Event-ID reconnects enumerates at most
+    # this many per round-trip, and the budget below bounds total throughput.
+    EVENTS_REPLAY_MAX_PER_REQUEST: int = 200
+    EVENTS_REPLAY_MAX_AGE_HOURS: int = 48
+    # Sliding-window cap on snapshot replays per user; exhausting it returns 429 with the
+    # cursor pinned so the client backs off until the window rolls over.
+    EVENTS_REPLAY_BUDGET_REQUESTS_PER_WINDOW: int = 30
+    EVENTS_REPLAY_BUDGET_WINDOW_SECONDS: int = 60
+
+    # Retention for the message_events journal, enforced by the cleanup_message_events beat
+    # task. Replay only needs streams a client could still be tailing.
+    MESSAGE_EVENTS_RETENTION_DAYS: int = 14
+
+    # Remote Device feature.
+    REMOTE_DEVICE_SESSION_IDLE_SECONDS: int = 60
+    REMOTE_DEVICE_REQUIRE_SIGNATURE: bool = False
+    REMOTE_DEVICE_PAIRING_TTL_SECONDS: int = 600
+    # Redis broker tunables, routing invocations cross-process so a scheduled run reaches the
+    # web-held device session. The queue TTL must exceed the max drain deadline (605s) so a
+    # command for a briefly-offline device isn't evicted before its own drain gives up.
+    REMOTE_DEVICE_CMD_QUEUE_TTL_SECONDS: int = 900
+    REMOTE_DEVICE_INVOCATION_TTL_SECONDS: int = 900
+    REMOTE_DEVICE_OUTPUT_STREAM_MAXLEN: int = 10_000
+
+    # Scheduler (see scheduler.md).
+    SCHEDULE_DISPATCHER_INTERVAL: int = 30
+    SCHEDULE_MIN_INTERVAL: int = 900
+    SCHEDULE_MAX_PER_USER: int = 50
+    SCHEDULE_RUN_TIMEOUT: int = 600
+    SCHEDULE_MISFIRE_GRACE: int = 60
+    SCHEDULE_AUTOPAUSE_FAILURES: int = 3
+    SCHEDULE_ONCE_MAX_HORIZON: int = 31_536_000
+    SCHEDULE_RUN_OUTPUT_RETENTION_DAYS: int = 90
+
+    # Code-execution sandbox. The app is a CLIENT of an always-on runner; defaults are safe so
+    # app import never fails when the sandbox is unconfigured.
+    SANDBOX_BACKEND: str = "jupyter"  # "jupyter" (self-host) | "daytona" (Daytona Cloud)
+    # URL of the Jupyter Kernel Gateway runner (the docsgpt-sandbox service).
+    SANDBOX_GATEWAY_URL: str = "http://localhost:8888"
+    SANDBOX_GATEWAY_AUTH_TOKEN: Optional[str] = None  # gateway auth token, if set
+    # Kernelspec per session. The env-scrubbing "docsgpt-python" spec keeps kernel code from
+    # reading the gateway token or operator secrets from os.environ; the stock "python3" spec
+    # inherits the gateway env verbatim and must not be used with untrusted code.
+    SANDBOX_KERNEL_NAME: str = "docsgpt-python"
+    SANDBOX_MAX_TTL: int = 1200  # hard cap (s) on agent-selectable keep-alive TTL
+    # Concurrent live sessions per process, backend-agnostic; at the cap an LRU-idle session is
+    # evicted. 0 or negative disables the cap.
+    SANDBOX_MAX_SESSIONS: int = 32
+    SANDBOX_EXEC_TIMEOUT: int = 60  # default wall-clock cap (s) per exec call
+    SANDBOX_HTTP_TIMEOUT: int = 10  # fixed cap (s) for REST control calls (create/delete/alive/interrupt)
+    SANDBOX_MAX_OUTPUT_BYTES: int = 8 * 1024 * 1024  # cap on buffered stdout+stderr per exec
+    SANDBOX_MAX_FILE_BYTES: int = 10 * 1024 * 1024  # cap on get_file size routed through stdout
+    SANDBOX_MAX_INPUT_BYTES: int = 25 * 1024 * 1024  # cap on an input document staged into a sandbox session
+    # ``read_document`` parsing on a dedicated Celery ``parsing`` queue (backend parser).
+    DOCUMENT_PARSE_QUEUE: str = "parsing"  # queue the parse_document task is routed to
+    DOCUMENT_PARSE_TIMEOUT: int = 120  # seconds the tool awaits the enqueued parse before degrading
+    # The base timeout is a FLOOR: the window grows with document size, because OCR cost scales
+    # with pages. Without this a large scan is silently dropped at the base window.
+    DOCUMENT_PARSE_TIMEOUT_PER_MB: int = 60  # extra seconds of parse window per MiB of input
+    DOCUMENT_PARSE_TIMEOUT_MAX: int = 900  # absolute ceiling on the size-scaled parse window
+    DOCUMENT_PARSE_MAX_BYTES: int = 0  # cap on a parsed document's bytes (0 = reuse SANDBOX_MAX_INPUT_BYTES)
+    DOCUMENT_MAX_DECOMPRESSED_BYTES: int = 300 * 1024 * 1024
+    DOCUMENT_MAX_ARCHIVE_ENTRIES: int = 10000
+    # Files per node passed natively to the LLM; past the cap they are extracted to text or
+    # dropped, to bound context and cost. Re-uses SANDBOX_MAX_INPUT_BYTES per file.
+    WORKFLOW_NODE_NATIVE_MAX_FILES: int = 5
+    # Documents per node extracted via the parsing worker. Each issues a separate blocking
+    # parse; past the cap they are skipped with a truncation note.
+    WORKFLOW_NODE_EXTRACT_MAX_FILES: int = 5
+    # Wall clock one node may spend on blocking parses, shared across all of them. Without it a
+    # node could serialize WORKFLOW_NODE_EXTRACT_MAX_FILES full windows on a web threadpool slot.
+    WORKFLOW_NODE_EXTRACT_BUDGET_SECONDS: int = 900
+    # A run row is pre-created as ``running``; a disconnect or crash can strand it there. The
+    # beat reaper fails runs still ``running`` past this. Generous so a long run is never cut off.
+    WORKFLOW_RUN_STALE_SECONDS: int = 3600
+    # Runner container caps, consumed by the docsgpt-sandbox compose service, not the app.
+    # These cgroup limits are part of the untrusted-code security boundary.
+    SANDBOX_MEMORY: str = "1g"  # docker mem_limit for the runner container
+    SANDBOX_CPUS: str = "1.0"  # docker cpu quota for the runner container
+    # Daytona Cloud backend (SANDBOX_BACKEND="daytona"). All knobs are optional so app import
+    # never fails when the backend is unused.
+    DAYTONA_API_KEY: Optional[str] = None  # Daytona Cloud API key (secret)
+    DAYTONA_API_URL: Optional[str] = None  # override Daytona API base URL, if self-targeting
+    DAYTONA_TARGET: Optional[str] = None  # Daytona region/target, e.g. "us"
+    DAYTONA_SNAPSHOT: Optional[str] = None  # image for new sandboxes; render libs via scripts/build_daytona_snapshot.py
+    DAYTONA_LANGUAGE: str = "python"  # default runtime language for created sandboxes
+    DAYTONA_AUTO_STOP_INTERVAL: int = 15  # minutes idle before Daytona auto-stops a sandbox (0 disables)
+    DAYTONA_AUTO_DELETE_INTERVAL: int = 60  # minutes after stop before Daytona auto-deletes (-1 disables)
+    DAYTONA_MAX_SANDBOXES: int = 50  # cap on concurrent live Daytona sandboxes (cost-DoS guard)
+    # Per-user artifact quotas, enforced at persistence time. 0 or negative disables a quota.
+    ARTIFACT_MAX_BYTES: int = 50 * 1024 * 1024  # cap on a single stored artifact version's bytes
+    ARTIFACT_MAX_COUNT_PER_USER: int = 5000  # cap on artifacts a user may own
+    ARTIFACT_MAX_TOTAL_BYTES_PER_USER: int = 5 * 1024 * 1024 * 1024  # cap on a user's total stored bytes
+
+    @field_validator("POSTGRES_URI", mode="before")
+    @classmethod
+    def _normalize_postgres_uri_validator(cls, v):
+        return normalize_postgres_uri(v)
+
+    @field_validator("PGVECTOR_CONNECTION_STRING", mode="before")
+    @classmethod
+    def _normalize_pgvector_connection_string_validator(cls, v):
+        return normalize_pgvector_connection_string(v)
+
+    @field_validator(
+        "API_KEY",
+        "OPENAI_API_KEY",
+        "ANTHROPIC_API_KEY",
+        "GOOGLE_API_KEY",
+        "GROQ_API_KEY",
+        "HUGGINGFACE_API_KEY",
+        "NOVITA_API_KEY",
+        "EMBEDDINGS_KEY",
+        "FALLBACK_LLM_API_KEY",
+        "QDRANT_API_KEY",
+        "ELEVENLABS_API_KEY",
+        "INTERNAL_KEY",
+        mode="before",
+    )
+    @classmethod
+    def normalize_api_key(cls, v: Optional[str]) -> Optional[str]:
+        """
+        Normalize API keys: convert 'None', 'none', empty strings,
+        and whitespace-only strings to actual None.
+        Handles Pydantic loading 'None' from .env as string "None".
+        """
+        if v is None:
+            return None
+        if not isinstance(v, str):
+            return v
+        stripped = v.strip()
+        if stripped == "" or stripped.lower() == "none":
+            return None
+        return stripped
+
+
+# Project root is one level above application/
+path = Path(__file__).parent.parent.parent.absolute()
+settings = Settings(_env_file=path.joinpath(".env"), _env_file_encoding="utf-8")

docsgpt/core/shutdown.py

@@ -0,0 +1,28 @@
+"""Process-wide graceful-shutdown flag.
+
+Raised by ``BoundedDrainUvicornWorker`` when a drain starts and polled by the
+SSE/long-poll generators (which run in a2wsgi threads asyncio can't cancel) so
+they return promptly instead of hanging the worker until the ``--timeout``
+watchdog kills it. Standalone module so the worker can import it without the app.
+"""
+
+from __future__ import annotations
+
+import threading
+
+_shutting_down = threading.Event()
+
+
+def begin_shutdown() -> None:
+    """Mark the process as shutting down so streaming generators stop looping."""
+    _shutting_down.set()
+
+
+def is_shutting_down() -> bool:
+    """Return ``True`` once the server has begun a graceful shutdown."""
+    return _shutting_down.is_set()
+
+
+def reset_shutdown() -> None:
+    """Clear the shutdown flag. Intended for tests only."""
+    _shutting_down.clear()

docsgpt/core/url_validation.py

@@ -0,0 +1,183 @@
+"""
+URL validation utilities to prevent SSRF (Server-Side Request Forgery) attacks.
+
+This module provides functions to validate URLs before making HTTP requests,
+blocking access to internal networks, cloud metadata services, and other
+potentially dangerous endpoints.
+"""
+
+import ipaddress
+import socket
+from urllib.parse import urlparse
+from typing import Optional, Set
+
+
+class SSRFError(Exception):
+    """Raised when a URL fails SSRF validation."""
+    pass
+
+
+# Blocked hostnames that should never be accessed
+BLOCKED_HOSTNAMES: Set[str] = {
+    "localhost",
+    "localhost.localdomain",
+    "metadata.google.internal",
+    "metadata",
+}
+
+# Cloud metadata IP addresses (AWS, GCP, Azure, etc.)
+METADATA_IPS: Set[str] = {
+    "169.254.169.254",  # AWS, GCP, Azure metadata
+    "169.254.170.2",    # AWS ECS task metadata
+    "fd00:ec2::254",    # AWS IPv6 metadata
+}
+
+# Allowed schemes for external requests
+ALLOWED_SCHEMES: Set[str] = {"http", "https"}
+
+
+def is_private_ip(ip_str: str) -> bool:
+    """
+    Check if an IP address is private, loopback, or link-local.
+
+    Args:
+        ip_str: IP address as a string
+
+    Returns:
+        True if the IP is private/internal, False otherwise
+    """
+    try:
+        ip = ipaddress.ip_address(ip_str)
+        return (
+            ip.is_private or
+            ip.is_loopback or
+            ip.is_link_local or
+            ip.is_reserved or
+            ip.is_multicast or
+            ip.is_unspecified
+        )
+    except ValueError:
+        # If we can't parse it as an IP, return False
+        return False
+
+
+def is_metadata_ip(ip_str: str) -> bool:
+    """
+    Check if an IP address is a cloud metadata service IP.
+
+    Args:
+        ip_str: IP address as a string
+
+    Returns:
+        True if the IP is a metadata service, False otherwise
+    """
+    return ip_str in METADATA_IPS
+
+
+def resolve_hostname(hostname: str) -> Optional[str]:
+    """
+    Resolve a hostname to an IP address.
+
+    Args:
+        hostname: The hostname to resolve
+
+    Returns:
+        The resolved IP address, or None if resolution fails
+    """
+    try:
+        return socket.gethostbyname(hostname)
+    except socket.gaierror:
+        return None
+
+
+def validate_url(url: str, allow_localhost: bool = False) -> str:
+    """
+    Validate a URL to prevent SSRF attacks.
+
+    This function checks that:
+    1. The URL has an allowed scheme (http or https)
+    2. The hostname is not a blocked hostname
+    3. The resolved IP is not a private/internal IP
+    4. The resolved IP is not a cloud metadata service
+
+    Args:
+        url: The URL to validate
+        allow_localhost: If True, allow localhost connections (for testing only)
+
+    Returns:
+        The validated URL (with scheme added if missing)
+
+    Raises:
+        SSRFError: If the URL fails validation
+    """
+    if not url or not isinstance(url, str):
+        raise SSRFError("No URL was provided.")
+    # Ensure URL has a scheme
+    if not urlparse(url).scheme:
+        url = "http://" + url
+
+    parsed = urlparse(url)
+
+    # Check scheme
+    if parsed.scheme not in ALLOWED_SCHEMES:
+        raise SSRFError(f"URL scheme '{parsed.scheme}' is not allowed. Only HTTP(S) is permitted.")
+
+    hostname = parsed.hostname
+    if not hostname:
+        raise SSRFError("URL must have a valid hostname.")
+
+    hostname_lower = hostname.lower()
+
+    # Check blocked hostnames
+    if hostname_lower in BLOCKED_HOSTNAMES and not allow_localhost:
+        raise SSRFError(f"Access to '{hostname}' is not allowed.")
+
+    # Check if hostname is an IP address directly
+    try:
+        ip = ipaddress.ip_address(hostname)
+        ip_str = str(ip)
+
+        if is_metadata_ip(ip_str):
+            raise SSRFError("Access to cloud metadata services is not allowed.")
+
+        if is_private_ip(ip_str) and not allow_localhost:
+            raise SSRFError("Access to private/internal IP addresses is not allowed.")
+
+        return url
+    except ValueError:
+        # Not an IP address, it's a hostname - resolve it
+        pass
+
+    # Resolve hostname and check the IP
+    resolved_ip = resolve_hostname(hostname)
+    if resolved_ip is None:
+        raise SSRFError(f"Unable to resolve hostname: {hostname}")
+
+    if is_metadata_ip(resolved_ip):
+        raise SSRFError("Access to cloud metadata services is not allowed.")
+
+    if is_private_ip(resolved_ip) and not allow_localhost:
+        raise SSRFError("Access to private/internal networks is not allowed.")
+
+    return url
+
+
+def validate_url_safe(url: str, allow_localhost: bool = False) -> tuple[bool, str, Optional[str]]:
+    """
+    Validate a URL and return a tuple with validation result.
+
+    This is a non-throwing version of validate_url for cases where
+    you want to handle validation failures gracefully.
+
+    Args:
+        url: The URL to validate
+        allow_localhost: If True, allow localhost connections (for testing only)
+
+    Returns:
+        Tuple of (is_valid, validated_url_or_original, error_message_or_none)
+    """
+    try:
+        validated = validate_url(url, allow_localhost)
+        return (True, validated, None)
+    except SSRFError as e:
+        return (False, url, str(e))