feat: Add Dynamic Configuration to ChatProfiles (#2401)

## Changes:
- Audio.enabled and MCP.enabled now must be explicitly enabled. Before
it was inferred if on_audio_chunk and on_mcp_connect existed. This
enables selective enablement by ChatProfile now.
- Documentation Update PR: Chainlit/docs#256

## ✅ Backend Implementation Complete
- ChainlitConfigOverrides class in config.py - allows specifying UI,
features, and project overrides
- ChatProfile.config_overrides field - stores profile-specific
configuration overrides
- /project/settings endpoint enhancement - applies config overrides
based on the chat_profile parameter
- Proper serialization - removes config_overrides from profiles sent to
frontend (they're applied server-side)
- Pydantic dataclass rebuild - fixes forward reference issues

## ✅ Frontend Implementation Complete
- Enhanced useConfig hook - includes chat_profile parameter in API calls
- Automatic re-fetching - clears config when chat profile changes to
trigger re-fetch with new profile-specific settings

## 🎯 How It Works
- Default state: Frontend calls /project/settings?language=en-US → gets
base configuration
- Profile selection: User selects "vision-assistant" → chatProfileState
updates
- Config refresh: Frontend clears config and calls
/project/settings?language=en-US&chat_profile=vision-assistant
- Server merges: Backend finds vision-assistant profile, applies its
config_overrides to base config
- Frontend receives: Merged configuration with vision-assistant's UI
name, file upload settings, etc.

## Other:
- Added "UP007" to ruff ignore because it was flagging these when using
Optional[str] which is valid.
<img width="474" height="147" alt="image"
src="https://github.com/user-attachments/assets/cfbcf0d6-68e6-4bc6-aeee-539014a52b2d"
/>


Fixes #1502

---------

Co-authored-by: Aleksandr Vishniakov <[email protected]>

Author: hayescode

backend/chainlit/__init__.py

@@ -121,6 +121,7 @@ def acall(self):
         "instrument_openai": "chainlit.openai",
         "instrument_mistralai": "chainlit.mistralai",
         "SemanticKernelFilter": "chainlit.semantic_kernel",
+        "server": "chainlit.server",
     }
 )
 

backend/chainlit/config.py

@@ -17,9 +17,7 @@
 )
 
 import tomli
-from dataclasses_json import DataClassJsonMixin
-from pydantic import Field
-from pydantic.dataclasses import dataclass
+from pydantic import BaseModel, ConfigDict, Field
 from starlette.datastructures import Headers
 
 from chainlit.data.base import BaseDataLayer
@@ -119,9 +117,15 @@
     max_size_mb = 500
 
 [features.audio]
+    # Enable audio features
+    enabled = false
     # Sample rate of the audio
     sample_rate = 24000
 
+[features.mcp]
+    # Enable Model Context Protocol (MCP) features
+    enabled = false
+
 [features.mcp.sse]
     enabled = true
 
@@ -207,8 +211,7 @@
 DEFAULT_ROOT_PATH = ""
 
 
-@dataclass()
-class RunSettings:
+class RunSettings(BaseModel):
     # Name of the module (python file) used in the run command
     module_name: Optional[str] = None
     host: str = DEFAULT_HOST
@@ -223,64 +226,54 @@ class RunSettings:
     ci: bool = False
 
 
-@dataclass()
-class PaletteOptions(DataClassJsonMixin):
+class PaletteOptions(BaseModel):
     main: Optional[str] = ""
     light: Optional[str] = ""
     dark: Optional[str] = ""
 
 
-@dataclass()
-class TextOptions(DataClassJsonMixin):
+class TextOptions(BaseModel):
     primary: Optional[str] = ""
     secondary: Optional[str] = ""
 
 
-@dataclass()
-class Palette(DataClassJsonMixin):
+class Palette(BaseModel):
     primary: Optional[PaletteOptions] = None
     background: Optional[str] = ""
     paper: Optional[str] = ""
     text: Optional[TextOptions] = None
 
 
-@dataclass
-class SpontaneousFileUploadFeature(DataClassJsonMixin):
+class SpontaneousFileUploadFeature(BaseModel):
     enabled: Optional[bool] = None
     accept: Optional[Union[List[str], Dict[str, List[str]]]] = None
     max_files: Optional[int] = None
     max_size_mb: Optional[int] = None
 
 
-@dataclass
-class AudioFeature(DataClassJsonMixin):
+class AudioFeature(BaseModel):
     sample_rate: int = 24000
     enabled: bool = False
 
 
-@dataclass
-class McpSseFeature(DataClassJsonMixin):
+class McpSseFeature(BaseModel):
     enabled: bool = True
 
 
-@dataclass
-class McpStreamableHttpFeature(DataClassJsonMixin):
+class McpStreamableHttpFeature(BaseModel):
     enabled: bool = True
 
 
-@dataclass
-class McpStdioFeature(DataClassJsonMixin):
+class McpStdioFeature(BaseModel):
     enabled: bool = True
     allowed_executables: Optional[list[str]] = None
 
 
-@dataclass
-class SlackFeature(DataClassJsonMixin):
+class SlackFeature(BaseModel):
     reaction_on_message_received: bool = False
 
 
-@dataclass
-class McpFeature(DataClassJsonMixin):
+class McpFeature(BaseModel):
     enabled: bool = False
     sse: McpSseFeature = Field(default_factory=McpSseFeature)
     streamable_http: McpStreamableHttpFeature = Field(
@@ -289,8 +282,7 @@ class McpFeature(DataClassJsonMixin):
     stdio: McpStdioFeature = Field(default_factory=McpStdioFeature)
 
 
-@dataclass()
-class FeaturesSettings(DataClassJsonMixin):
+class FeaturesSettings(BaseModel):
     spontaneous_file_upload: Optional[SpontaneousFileUploadFeature] = None
     audio: Optional[AudioFeature] = Field(default_factory=AudioFeature)
     mcp: McpFeature = Field(default_factory=McpFeature)
@@ -302,16 +294,14 @@ class FeaturesSettings(DataClassJsonMixin):
     edit_message: bool = True
 
 
-@dataclass
-class HeaderLink(DataClassJsonMixin):
+class HeaderLink(BaseModel):
     name: str
     icon_url: str
     url: str
     display_name: Optional[str] = None
 
 
-@dataclass()
-class UISettings(DataClassJsonMixin):
+class UISettings(BaseModel):
     name: str
     description: str = ""
     cot: Literal["hidden", "tool_call", "full"] = "full"
@@ -344,8 +334,7 @@ class UISettings(DataClassJsonMixin):
     header_links: Optional[List[HeaderLink]] = None
 
 
-@dataclass()
-class CodeSettings:
+class CodeSettings(BaseModel):
     # App action functions
     action_callbacks: Dict[str, Callable[["Action"], Any]]
 
@@ -393,8 +382,7 @@ class CodeSettings:
     data_layer: Optional[Callable[[], BaseDataLayer]] = None
 
 
-@dataclass()
-class ProjectSettings(DataClassJsonMixin):
+class ProjectSettings(BaseModel):
     allow_origins: List[str] = Field(default_factory=lambda: ["*"])
     # Socket.io client transports option
     transports: Optional[List[str]] = None
@@ -411,10 +399,21 @@ class ProjectSettings(DataClassJsonMixin):
     cache: bool = False
 
 
-@dataclass()
-class ChainlitConfig:
+class ChainlitConfigOverrides(BaseModel):
+    """Configuration overrides that can be applied to specific chat profiles."""
+
+    ui: Optional[UISettings] = None
+    features: Optional[FeaturesSettings] = None
+    project: Optional[ProjectSettings] = None
+
+
+class ChainlitConfig(BaseModel):
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True, revalidate_instances="always"
+    )
+
     # Directory where the Chainlit project is located
-    root = APP_ROOT
+    root: str = APP_ROOT
     # Chainlit server URL. Used only for cloud features
     chainlit_server: str
     run: RunSettings
@@ -510,7 +509,7 @@ def load_module(target: str, force_refresh: bool = False):
         site_package_dirs = site.getsitepackages()
 
         # Clear the modules related to the app from sys.modules
-        for module_name, module in list(sys.modules.items()):
+        for module_name, module in sys.modules.items():
             if (
                 hasattr(module, "__file__")
                 and module.__file__

backend/chainlit/server.py

@@ -48,6 +48,7 @@
     DEFAULT_HOST,
     FILES_DIRECTORY,
     PACKAGE_ROOT,
+    ChainlitConfig,
     config,
     load_module,
     public_dir,
@@ -777,42 +778,64 @@ async def project_settings(
     language: str = Query(
         default="en-US", description="Language code", pattern=_language_pattern
     ),
+    chat_profile: Optional[str] = Query(
+        default=None, description="Current chat profile name"
+    ),
 ):
     """Return project settings. This is called by the UI before the establishing the websocket connection."""
 
     # Load the markdown file based on the provided language
-
     markdown = get_markdown_str(config.root, language)
 
     profiles = []
     if config.code.set_chat_profiles:
         chat_profiles = await config.code.set_chat_profiles(current_user)
         if chat_profiles:
-            profiles = [p.to_dict() for p in chat_profiles]
+            # Custom serialization to handle ChainlitConfigOverrides
+            for p in chat_profiles:
+                profile_dict = p.to_dict()
+                # Remove config_overrides from the serialized profile since it's used server-side only
+                if "config_overrides" in profile_dict:
+                    del profile_dict["config_overrides"]
+                profiles.append(profile_dict)
 
     starters = []
     if config.code.set_starters:
         starters = await config.code.set_starters(current_user)
         if starters:
             starters = [s.to_dict() for s in starters]
 
-    if config.code.on_audio_chunk:
-        config.features.audio.enabled = True
-
-    if config.code.on_mcp_connect:
-        config.features.mcp.enabled = True
-
     debug_url = None
     data_layer = get_data_layer()
 
     if data_layer and config.run.debug:
         debug_url = await data_layer.build_debug_url()
 
+    config_with_overrides = config
+
+    # Apply profile-specific configuration overrides
+    if chat_profile and config.code.set_chat_profiles:
+        # Find the current chat profile and apply overrides
+        chat_profiles = await config.code.set_chat_profiles(current_user)
+        if chat_profiles:
+            current_profile = next(
+                (p for p in chat_profiles if p.name == chat_profile), None
+            )
+            if current_profile and current_profile.config_overrides:
+                config_with_overrides = ChainlitConfig.model_validate(
+                    config.model_copy(
+                        update=current_profile.config_overrides.model_dump(
+                            exclude_none=True
+                        ),
+                        deep=True,
+                    )
+                )
+
     return JSONResponse(
         content={
-            "ui": config.ui.to_dict(),
-            "features": config.features.to_dict(),
-            "userEnv": config.project.user_env,
+            "ui": config_with_overrides.ui.model_dump(),
+            "features": config_with_overrides.features.model_dump(),
+            "userEnv": config_with_overrides.project.user_env,
             "dataPersistence": get_data_layer() is not None,
             "threadResumable": bool(config.code.on_chat_resume),
             "markdown": markdown,
@@ -1148,7 +1171,7 @@ async def connect_mcp(
                 status_code=401,
             )
 
-    mcp_enabled = config.code.on_mcp_connect is not None
+    mcp_enabled = config.features.mcp.enabled
     if mcp_enabled:
         if payload.name in session.mcp_sessions:
             old_client_session, old_exit_stack = session.mcp_sessions[payload.name]

backend/chainlit/socket.py

@@ -326,7 +326,7 @@ async def audio_start(sid):
     session = WebsocketSession.require(sid)
 
     context = init_ws_context(session)
-    if config.code.on_audio_start:
+    if config.features.audio.enabled:
         connected = bool(await config.code.on_audio_start())
         connection_state = "on" if connected else "off"
         await context.emitter.update_audio_connection(connection_state)
@@ -339,7 +339,7 @@ async def audio_chunk(sid, payload: InputAudioChunkPayload):
 
     init_ws_context(session)
 
-    if config.code.on_audio_chunk:
+    if config.features.audio.enabled:
         asyncio.create_task(config.code.on_audio_chunk(InputAudioChunk(**payload)))
 
 
@@ -355,7 +355,7 @@ async def audio_end(sid):
             session.has_first_interaction = True
             asyncio.create_task(context.emitter.init_thread("audio"))
 
-        if config.code.on_audio_end:
+        if config.features.audio.enabled:
             await config.code.on_audio_end()
 
     except asyncio.CancelledError:

backend/chainlit/types.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from enum import Enum
 from pathlib import Path
 from typing import (
@@ -36,8 +38,8 @@ class ThreadDict(TypedDict):
     userIdentifier: Optional[str]
     tags: Optional[List[str]]
     metadata: Optional[Dict]
-    steps: List["StepDict"]
-    elements: Optional[List["ElementDict"]]
+    steps: List[StepDict]
+    elements: Optional[List[ElementDict]]
 
 
 class Pagination(BaseModel):
@@ -46,9 +48,9 @@ class Pagination(BaseModel):
 
 
 class ThreadFilter(BaseModel):
-    feedback: Optional[Literal[0, 1]] = None
-    userId: Optional[str] = None
-    search: Optional[str] = None
+    feedback: Literal[0, 1] | None = None
+    userId: str | None = None
+    search: str | None = None
 
 
 @dataclass
@@ -65,7 +67,7 @@ def to_dict(self):
         }
 
     @classmethod
-    def from_dict(cls, page_info_dict: Dict) -> "PageInfo":
+    def from_dict(cls, page_info_dict: Dict) -> PageInfo:
         hasNextPage = page_info_dict.get("hasNextPage", False)
         startCursor = page_info_dict.get("startCursor", None)
         endCursor = page_info_dict.get("endCursor", None)
@@ -100,7 +102,7 @@ def to_dict(self):
     @classmethod
     def from_dict(
         cls, paginated_response_dict: Dict, the_class: HasFromDict[T]
-    ) -> "PaginatedResponse[T]":
+    ) -> PaginatedResponse[T]:
         pageInfo = PageInfo.from_dict(paginated_response_dict.get("pageInfo", {}))
 
         data = [the_class.from_dict(d) for d in paginated_response_dict.get("data", [])]
@@ -159,7 +161,7 @@ class FileDict(TypedDict):
 
 
 class MessagePayload(TypedDict):
-    message: "StepDict"
+    message: StepDict
     fileReferences: Optional[List[FileReference]]
 
 
@@ -251,7 +253,7 @@ class ConnectStreamableHttpMCPRequest(BaseModel):
     name: str
     url: str
     # Optional HTTP headers to forward to the MCP transport (e.g. Authorization)
-    headers: Optional[Dict[str, str]] = None
+    headers: Dict[str, str] | None = None
 
 
 ConnectMCPRequest = Union[
@@ -293,6 +295,7 @@ class ChatProfile(DataClassJsonMixin):
     icon: Optional[str] = None
     default: bool = False
     starters: Optional[List[Starter]] = None
+    config_overrides: Any = None
 
 
 FeedbackStrategy = Literal["BINARY"]