refactor(settings): deprecate SAGEMAKER_* and drop two unused settings

SAGEMAKER_REGION, SAGEMAKER_ACCESS_KEY and SAGEMAKER_SECRET_KEY survive
only as a fallback for the S3_* credentials. They carry
Field(deprecated=...) now, so any read emits a DeprecationWarning naming
the replacement and the generated reference shows the notice. The S3
store is the one sanctioned reader; it silences that warning locally
because it already logs its own operator-facing one when the fallback
is actually used.

DEFAULT_MAX_HISTORY was referenced nowhere. RETRIEVERS_ENABLED was read by
no code at all, while two docs pages described it as an enforced
allow-list; both the setting and those claims are removed.

docs/content/Deploying/DocsGPT-Settings.mdx

@@ -461,7 +461,6 @@ These control how sources are retrieved and whether the advanced RAG features ar
 
 | Setting | Default | Description |
 | --- | --- | --- |
-| `RETRIEVERS_ENABLED` | `["classic", "default"]` | Allow-list of retrievers usable instance-wide. Valid keys: `classic`, `default`, `hybrid`, `graphrag`. A per-source `retriever` must be within this list. |
 | `PER_SOURCE_RETRIEVAL_ENABLED` | `true` | Master switch for per-source retrieval config. When `false`, all sources fall back to the classic retriever regardless of their stored config. |
 | `GRAPHRAG_ENABLED` | `false` | Enable [GraphRAG](/Sources/GraphRAG). Requires `VECTOR_STORE=pgvector`. |
 | `GRAPHRAG_EXTRACTION_MODEL` | unset | Model used for ingest-time graph extraction. Unset reuses the instance default model. |

docs/content/Deploying/Settings-Reference.mdx

@@ -417,12 +417,6 @@ Type `"faiss" | "elasticsearch" | "mongodb" | "qdrant" | "milvus" | "pgvector"`,
 
 Vector store backend.
 
-### `RETRIEVERS_ENABLED`
-
-Type `list`, default `["classic", "default"]`.
-
-Retriever keys an agent may use; must match RetrieverCreator.retrievers registry keys, NOT the legacy classic_rag label which never matched the registry.
-
 ### `RETRIEVAL_MAX_PARALLEL_SOURCES`
 
 Type `int`, default `4`, must be >= 1.
@@ -1015,18 +1009,24 @@ Path-style addressing (required by most non-AWS services).
 
 Type `str`, default unset.
 
+**Deprecated.** Set S3_REGION instead; the SAGEMAKER_* fallback will be removed.
+
 Legacy AWS region from the retired SageMaker provider; deprecated fallback for S3_REGION.
 
 ### `SAGEMAKER_ACCESS_KEY`
 
 Type `str`, default unset.
 
+**Deprecated.** Set S3_ACCESS_KEY_ID instead; the SAGEMAKER_* fallback will be removed.
+
 Legacy AWS access key from the retired SageMaker provider; deprecated fallback for S3_ACCESS_KEY_ID.
 
 ### `SAGEMAKER_SECRET_KEY`
 
 Type `str`, default unset.
 
+**Deprecated.** Set S3_SECRET_ACCESS_KEY instead; the SAGEMAKER_* fallback will be removed.
+
 Legacy AWS secret key from the retired SageMaker provider; deprecated fallback for S3_SECRET_ACCESS_KEY.
 
 
@@ -1271,12 +1271,6 @@ Type `str`, default `classic`.
 
 Default agent type for agentless chats.
 
-### `DEFAULT_MAX_HISTORY`
-
-Type `int`, default `150`.
-
-Default number of history messages kept.
-
 ### `DEFAULT_AGENT_LIMITS`
 
 Type `dict`, default `{"token_limit": 50000, "request_limit": 500}`.

docs/content/Sources/Per-source-configuration.mdx

@@ -115,8 +115,6 @@ Requests are also bounded: `chunks` is clamped to 0–500, and `0` still means
 Keyword search for the **hybrid** retriever is currently implemented only for the **pgvector** vector store. On other stores (FAISS, Qdrant, Milvus, etc.) the keyword half returns nothing, so `hybrid` quietly behaves like `classic` (vector-only).
 </Callout>
 
-Operators can restrict which retrievers are usable instance-wide with the `RETRIEVERS_ENABLED` setting; a per-source `retriever` value must be within that allow-list.
-
 ### Exposure: prefetch vs. agentic tool
 
 `exposure` controls *how* a source's content is delivered to the model:

docsgpt/core/settings/agents.py

@@ -13,7 +13,6 @@ class AgentSettings(SettingsGroup):
     """What an agent may do per turn and how its context is kept within budget."""
 
     AGENT_NAME: str = Field(default="classic", description="Default agent type for agentless chats.")
-    DEFAULT_MAX_HISTORY: int = Field(default=150, description="Default number of history messages kept.")
     DEFAULT_AGENT_LIMITS: dict[str, int] = Field(
         default={"token_limit": 50000, "request_limit": 500},
         description="Per-agent default quotas: tokens and requests.",

docsgpt/core/settings/retrieval.py

@@ -15,13 +15,6 @@ class RetrievalSettings(SettingsGroup):
     VECTOR_STORE: Literal["faiss", "elasticsearch", "mongodb", "qdrant", "milvus", "pgvector"] = Field(
         default="faiss", description="Vector store backend."
     )
-    RETRIEVERS_ENABLED: list[str] = Field(
-        default=["classic", "default"],
-        description=(
-            "Retriever keys an agent may use; must match RetrieverCreator.retrievers registry keys, NOT the "
-            "legacy classic_rag label which never matched the registry."
-        ),
-    )
     RETRIEVAL_MAX_PARALLEL_SOURCES: int = Field(
         default=4,
         ge=1,

docsgpt/core/settings/storage.py

@@ -34,14 +34,17 @@ class StorageSettings(SettingsGroup):
     # Legacy AWS credentials from the retired SageMaker provider.
     SAGEMAKER_REGION: Optional[str] = Field(
         default=None,
+        deprecated="Set S3_REGION instead; the SAGEMAKER_* fallback will be removed.",
         description="Legacy AWS region from the retired SageMaker provider; deprecated fallback for S3_REGION.",
     )
     SAGEMAKER_ACCESS_KEY: Optional[str] = Field(
         default=None,
+        deprecated="Set S3_ACCESS_KEY_ID instead; the SAGEMAKER_* fallback will be removed.",
         description="Legacy AWS access key from the retired SageMaker provider; deprecated fallback for S3_ACCESS_KEY_ID.",
     )
     SAGEMAKER_SECRET_KEY: Optional[str] = Field(
         default=None,
+        deprecated="Set S3_SECRET_ACCESS_KEY instead; the SAGEMAKER_* fallback will be removed.",
         description=(
             "Legacy AWS secret key from the retired SageMaker provider; deprecated fallback for "
             "S3_SECRET_ACCESS_KEY."

docsgpt/storage/s3.py

@@ -4,6 +4,7 @@ import io
 import logging
 import os
 import posixpath
+import warnings
 from typing import BinaryIO, Callable, List, Optional, Tuple
 
 import boto3
@@ -30,9 +31,13 @@ class S3Storage(BaseStorage):
         secret_key = settings.S3_SECRET_ACCESS_KEY
         region = settings.S3_REGION
 
-        legacy_access = getattr(settings, "SAGEMAKER_ACCESS_KEY", None)
-        legacy_secret = getattr(settings, "SAGEMAKER_SECRET_KEY", None)
-        legacy_region = getattr(settings, "SAGEMAKER_REGION", None)
+        # The SAGEMAKER_* fields are marked deprecated on the model and warn on every read;
+        # this is the one sanctioned reader, and it raises its own operator-facing warning.
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            legacy_access = settings.SAGEMAKER_ACCESS_KEY
+            legacy_secret = settings.SAGEMAKER_SECRET_KEY
+            legacy_region = settings.SAGEMAKER_REGION
 
         used_legacy = (
             (not access_key and legacy_access)

tests/core/test_settings.py

@@ -6,6 +6,7 @@ validators from every group applied) and that the generated reference page
 tracks the definitions.
 """
 
+import warnings
 from pathlib import Path
 
 import pytest
@@ -33,10 +34,16 @@ SECRET_FIELDS = (
 @pytest.mark.unit
 class TestComposition:
     def test_every_group_field_is_a_flat_settings_attribute(self):
-        for _, group in SETTINGS_GROUPS:
-            for name in group.model_fields:
-                assert name in Settings.model_fields, name
-                assert hasattr(settings, name), name
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)  # reading a deprecated field warns
+            for _, group in SETTINGS_GROUPS:
+                for name in group.model_fields:
+                    assert name in Settings.model_fields, name
+                    assert hasattr(settings, name), name
+
+    def test_deprecated_fields_warn_on_read(self):
+        with pytest.warns(DeprecationWarning, match="S3_REGION"):
+            _ = Settings(_env_file=None).SAGEMAKER_REGION
 
     def test_no_field_is_defined_in_two_groups(self):
         owners: dict[str, str] = {}