Python: Replace Pydantic Settings with TypedDict + load_settings() (#3843)

* Replace Pydantic Settings with TypedDict + load_settings()

- Remove pydantic-settings dependency, add python-dotenv
- Delete _pydantic.py (AFBaseSettings, HTTPsUrl)
- Add _settings.py with generic load_settings() function, SecretString,
  type coercion, and Required field validation (SettingNotFoundError)
- Convert all 13 settings classes from AFBaseSettings subclasses to
  TypedDict definitions with load_settings() calls
- Update all consumers from attribute access to dict access
- Add 20 unit tests for load_settings() covering basic loading, dotenv,
  SecretString, type coercion, and required field validation
- Update all existing tests for new settings patterns

* Fix mypy type errors from settings conversion

- Fix str | None attribute access in responses_client (walrus operator)
- Fix SecretString | None narrowing in bedrock (type: ignore after guard)
- Convert _context_provider.py attribute access to dict access (missed file)
- Fix endpoint type narrowing in search_provider and context_provider
- Fix purview: str | None .rstrip(), int | None defaults, urlparse bytes

* Address PR review: required_fields param, type validation, fixes

- Move required field validation from TypedDict annotations (Required)
  to a required_fields parameter on load_settings(), enabling runtime
  decisions about which fields are required
- Remove Required imports and restore from __future__ import annotations
  in ollama and foundry_local
- Add _check_override_type() for deterministic ServiceInitializationError
  on invalid override types (e.g. dict passed for str field)
- Fix all multi-exception test catches back to single exception type
- Fix Ollama host=None: use .get() so None is passed through to SDK default
- Fix Purview processor: use explicit is-None checks instead of or operator
- Remove unused BaseModel import from openai/_shared.py
- Add 4 new tests (24 total): required_fields param, type validation

* Fix type validation: allow int for float fields

_check_override_type now permits int values for float-typed fields,
matching Python's standard numeric promotion behavior.

* fix: wrap urlparse arg with str() to fix mypy bytes endswith error

python/packages/claude/agent_framework_claude/_agent.py

@@ -21,8 +21,9 @@ from agent_framework import (
     get_logger,
     normalize_messages,
 )
+from agent_framework._settings import load_settings
 from agent_framework._types import normalize_tools
-from agent_framework.exceptions import ServiceException, ServiceInitializationError
+from agent_framework.exceptions import ServiceException
 from claude_agent_sdk import (
     AssistantMessage,
     ClaudeSDKClient,
@@ -34,7 +35,6 @@ from claude_agent_sdk import (
     ClaudeAgentOptions as SDKOptions,
 )
 from claude_agent_sdk.types import StreamEvent, TextBlock
-from pydantic import ValidationError
 
 from ._settings import ClaudeAgentSettings
 
@@ -273,19 +273,18 @@ class ClaudeAgent(BaseAgent, Generic[OptionsT]):
         self._mcp_servers: dict[str, Any] = opts.pop("mcp_servers", None) or {}
 
         # Load settings from environment and options
-        try:
-            self._settings = ClaudeAgentSettings(
-                cli_path=cli_path,
-                model=model,
-                cwd=cwd,
-                permission_mode=permission_mode,
-                max_turns=max_turns,
-                max_budget_usd=max_budget_usd,
-                env_file_path=env_file_path,
-                env_file_encoding=env_file_encoding,
-            )
-        except ValidationError as ex:
-            raise ServiceInitializationError("Failed to create Claude Agent settings.", ex) from ex
+        self._settings = load_settings(
+            ClaudeAgentSettings,
+            env_prefix="CLAUDE_AGENT_",
+            cli_path=cli_path,
+            model=model,
+            cwd=cwd,
+            permission_mode=permission_mode,
+            max_turns=max_turns,
+            max_budget_usd=max_budget_usd,
+            env_file_path=env_file_path,
+            env_file_encoding=env_file_encoding,
+        )
 
         # Separate built-in tools (strings) from custom tools (callables/FunctionTool)
         self._builtin_tools: list[str] = []
@@ -411,18 +410,18 @@ class ClaudeAgent(BaseAgent, Generic[OptionsT]):
             opts["resume"] = resume_session_id
 
         # Apply settings from environment
-        if self._settings.cli_path:
-            opts["cli_path"] = self._settings.cli_path
-        if self._settings.model:
-            opts["model"] = self._settings.model
-        if self._settings.cwd:
-            opts["cwd"] = self._settings.cwd
-        if self._settings.permission_mode:
-            opts["permission_mode"] = self._settings.permission_mode
-        if self._settings.max_turns:
-            opts["max_turns"] = self._settings.max_turns
-        if self._settings.max_budget_usd:
-            opts["max_budget_usd"] = self._settings.max_budget_usd
+        if self._settings["cli_path"]:
+            opts["cli_path"] = self._settings["cli_path"]
+        if self._settings["model"]:
+            opts["model"] = self._settings["model"]
+        if self._settings["cwd"]:
+            opts["cwd"] = self._settings["cwd"]
+        if self._settings["permission_mode"]:
+            opts["permission_mode"] = self._settings["permission_mode"]
+        if self._settings["max_turns"]:
+            opts["max_turns"] = self._settings["max_turns"]
+        if self._settings["max_budget_usd"]:
+            opts["max_budget_usd"] = self._settings["max_budget_usd"]
 
         # Apply default options
         for key, value in self._default_options.items():

python/packages/claude/agent_framework_claude/_settings.py

@@ -1,51 +1,29 @@
 # Copyright (c) Microsoft. All rights reserved.
 
-from typing import ClassVar
-
-from agent_framework._pydantic import AFBaseSettings
+from typing import TypedDict
 
 __all__ = ["ClaudeAgentSettings"]
 
 
-class ClaudeAgentSettings(AFBaseSettings):
+class ClaudeAgentSettings(TypedDict, total=False):
     """Claude Agent settings.
 
     The settings are first loaded from environment variables with the prefix 'CLAUDE_AGENT_'.
     If the environment variables are not found, the settings can be loaded from a .env file
-    with the encoding 'utf-8'. If the settings are not found in the .env file, the settings
-    are ignored; however, validation will fail alerting that the settings are missing.
+    with the encoding 'utf-8'.
 
-    Keyword Args:
+    Keys:
         cli_path: The path to Claude CLI executable.
         model: The model to use (sonnet, opus, haiku).
         cwd: The working directory for Claude CLI.
         permission_mode: Permission mode (default, acceptEdits, plan, bypassPermissions).
         max_turns: Maximum number of conversation turns.
         max_budget_usd: Maximum budget in USD.
-        env_file_path: If provided, the .env settings are read from this file path location.
-        env_file_encoding: The encoding of the .env file, defaults to 'utf-8'.
-
-    Examples:
-        .. code-block:: python
-
-            from agent_framework.anthropic import ClaudeAgentSettings
-
-            # Using environment variables
-            # Set CLAUDE_AGENT_MODEL=sonnet
-            # CLAUDE_AGENT_PERMISSION_MODE=default
-
-            # Or passing parameters directly
-            settings = ClaudeAgentSettings(model="sonnet")
-
-            # Or loading from a .env file
-            settings = ClaudeAgentSettings(env_file_path="path/to/.env")
     """
 
-    env_prefix: ClassVar[str] = "CLAUDE_AGENT_"
-
-    cli_path: str | None = None
-    model: str | None = None
-    cwd: str | None = None
-    permission_mode: str | None = None
-    max_turns: int | None = None
-    max_budget_usd: float | None = None
+    cli_path: str | None
+    model: str | None
+    cwd: str | None
+    permission_mode: str | None
+    max_turns: int | None
+    max_budget_usd: float | None

python/packages/claude/tests/test_claude_agent.py

@@ -5,6 +5,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 from agent_framework import AgentResponseUpdate, AgentThread, Content, Message, tool
+from agent_framework._settings import load_settings
 
 from agent_framework_claude import ClaudeAgent, ClaudeAgentOptions, ClaudeAgentSettings
 from agent_framework_claude._agent import TOOLS_MCP_SERVER_NAME
@@ -15,23 +16,21 @@ from agent_framework_claude._agent import TOOLS_MCP_SERVER_NAME
 class TestClaudeAgentSettings:
     """Tests for ClaudeAgentSettings."""
 
-    def test_env_prefix(self) -> None:
-        """Test that env_prefix is correctly set."""
-        assert ClaudeAgentSettings.env_prefix == "CLAUDE_AGENT_"
-
     def test_default_values(self) -> None:
         """Test default values are None."""
-        settings = ClaudeAgentSettings()
-        assert settings.cli_path is None
-        assert settings.model is None
-        assert settings.cwd is None
-        assert settings.permission_mode is None
-        assert settings.max_turns is None
-        assert settings.max_budget_usd is None
+        settings = load_settings(ClaudeAgentSettings, env_prefix="CLAUDE_AGENT_")
+        assert settings["cli_path"] is None
+        assert settings["model"] is None
+        assert settings["cwd"] is None
+        assert settings["permission_mode"] is None
+        assert settings["max_turns"] is None
+        assert settings["max_budget_usd"] is None
 
     def test_explicit_values(self) -> None:
         """Test explicit values override defaults."""
-        settings = ClaudeAgentSettings(
+        settings = load_settings(
+            ClaudeAgentSettings,
+            env_prefix="CLAUDE_AGENT_",
             cli_path="/usr/local/bin/claude",
             model="sonnet",
             cwd="/home/user/project",
@@ -39,20 +38,20 @@ class TestClaudeAgentSettings:
             max_turns=10,
             max_budget_usd=5.0,
         )
-        assert settings.cli_path == "/usr/local/bin/claude"
-        assert settings.model == "sonnet"
-        assert settings.cwd == "/home/user/project"
-        assert settings.permission_mode == "default"
-        assert settings.max_turns == 10
-        assert settings.max_budget_usd == 5.0
+        assert settings["cli_path"] == "/usr/local/bin/claude"
+        assert settings["model"] == "sonnet"
+        assert settings["cwd"] == "/home/user/project"
+        assert settings["permission_mode"] == "default"
+        assert settings["max_turns"] == 10
+        assert settings["max_budget_usd"] == 5.0
 
     def test_env_variable_loading(self, monkeypatch: pytest.MonkeyPatch) -> None:
         """Test loading from environment variables."""
         monkeypatch.setenv("CLAUDE_AGENT_MODEL", "opus")
         monkeypatch.setenv("CLAUDE_AGENT_MAX_TURNS", "20")
-        settings = ClaudeAgentSettings()
-        assert settings.model == "opus"
-        assert settings.max_turns == 20
+        settings = load_settings(ClaudeAgentSettings, env_prefix="CLAUDE_AGENT_")
+        assert settings["model"] == "opus"
+        assert settings["max_turns"] == 20
 
 
 # region Test ClaudeAgent Initialization
@@ -95,9 +94,9 @@ class TestClaudeAgentInit:
             "max_turns": 10,
         }
         agent = ClaudeAgent(default_options=options)
-        assert agent._settings.model == "sonnet"  # type: ignore[reportPrivateUsage]
-        assert agent._settings.permission_mode == "default"  # type: ignore[reportPrivateUsage]
-        assert agent._settings.max_turns == 10  # type: ignore[reportPrivateUsage]
+        assert agent._settings["model"] == "sonnet"  # type: ignore[reportPrivateUsage]
+        assert agent._settings["permission_mode"] == "default"  # type: ignore[reportPrivateUsage]
+        assert agent._settings["max_turns"] == 10  # type: ignore[reportPrivateUsage]
 
     def test_with_function_tool(self) -> None:
         """Test agent with function tool."""
@@ -620,13 +619,13 @@ class TestClaudeAgentPermissions:
     def test_default_permission_mode(self) -> None:
         """Test default permission mode."""
         agent = ClaudeAgent()
-        assert agent._settings.permission_mode is None  # type: ignore[reportPrivateUsage]
+        assert agent._settings["permission_mode"] is None  # type: ignore[reportPrivateUsage]
 
     def test_permission_mode_from_settings(self, monkeypatch: pytest.MonkeyPatch) -> None:
         """Test permission mode from environment settings."""
         monkeypatch.setenv("CLAUDE_AGENT_PERMISSION_MODE", "acceptEdits")
-        settings = ClaudeAgentSettings()
-        assert settings.permission_mode == "acceptEdits"
+        settings = load_settings(ClaudeAgentSettings, env_prefix="CLAUDE_AGENT_")
+        assert settings["permission_mode"] == "acceptEdits"
 
     def test_permission_mode_in_options(self) -> None:
         """Test permission mode in options."""
@@ -634,7 +633,7 @@ class TestClaudeAgentPermissions:
             "permission_mode": "bypassPermissions",
         }
         agent = ClaudeAgent(default_options=options)
-        assert agent._settings.permission_mode == "bypassPermissions"  # type: ignore[reportPrivateUsage]
+        assert agent._settings["permission_mode"] == "bypassPermissions"  # type: ignore[reportPrivateUsage]
 
 
 # region Test ClaudeAgent Error Handling