Pydantic Settings

General Information

Field	Value
Package Name	pydantic-settings
Manufacturer / Vendor	Pydantic Team (Samuel Colvin, Hasan Ramezani, and contributors)
Software Category	Library
Primary Documentation	Documentation, GitHub, PyPI
Programming Language(s)	Python
License	MIT License
Deployed Version(s)	>=2.12.0 (version-locked at 2.12.0 across services)
Most Recent Available Version	2.12.0
Last Review Date	2026-01-27

Overview

Pydantic Settings is an extension to Pydantic that provides tools for loading application configuration from environment variables, dotenv files, and secrets directories. It enables applications to define type-safe, validated configuration classes that automatically read values from environment sources while maintaining the full power of Pydantic's validation framework. The library supports hierarchical configuration structures, computed properties, and integration with cloud secret managers (AWS Secrets Manager, Azure Key Vault, Google Cloud Secret Manager).

Within the medical device software, Pydantic Settings serves as the configuration management layer powering environment-based configuration across all 60+ microservices. It is integrated throughout the distributed architecture in the following capacities:

• API Gateway configuration: Manages server settings (host, port, workers), JWT authentication parameters (secret key file paths, token expiration, account lockout thresholds), DynamoDB table names, control plane service URLs, and resilience patterns (circuit breaker thresholds, offline fallback, local storage paths)
• Control Plane settings: Configures service metadata, downstream service URLs (Expert Orchestrator, Report Builder), AWS S3 bucket and key paths for artifact storage, and computed derived endpoints
• Expert Orchestrator settings: Manages the expert registry containing 50+ expert microservice URLs mapped to environment variables, HTTP client configuration, and orchestration behavior flags
• Report Builder configuration: Controls debug mode, service information, terminology enrichment paths, and server configuration
• Expert Core base settings: Provides a factory-based Settings class extended by all 50+ expert microservices, managing model name and version, inference device specification (with validation), storage provider selection (S3 vs Azure), AWS/Azure credentials, and model weights handling
• Module-specific settings: Detection and segmentation modules use specialized settings classes for feature flags (enable cropping, visualization mode, mask opacity, contour styling)

Pydantic Settings was selected over alternatives (python-dotenv, environs, dynaconf) due to:

• Seamless integration with the device's existing Pydantic models and validation patterns
• Native support for environment variable prefixing, enabling service-specific configuration namespaces (API_GATEWAY_*, CONTROL_PLANE_*, EXPERT_ORCHESTRATOR_*)
• Type-safe validation with computed fields and model validators for derived configuration
• Factory pattern support for creating prefixed settings classes dynamically at runtime
• Integration with dependency-injector via providers.Configuration().from_pydantic() for container-based dependency management
• MIT license permitting commercial use in medical device software
• Active maintenance by the Pydantic team with regular security updates

Functional Requirements

The following functional capabilities of this SOUP are relied upon by the medical device software.

Requirement ID	Description	Source / Reference
FR-001	Define configuration classes with automatic environment variable loading	BaseSettings class
FR-002	Configure environment variable prefix for namespace isolation	env_prefix in SettingsConfigDict
FR-003	Load configuration from dotenv files with environment variable priority	env_file in SettingsConfigDict
FR-004	Handle case-insensitive environment variable matching	case_sensitive in SettingsConfigDict
FR-005	Ignore unknown environment variables without raising errors	extra="ignore" in SettingsConfigDict
FR-006	Map environment variable names to different field names	validation_alias in Field() definition
FR-007	Support nested configuration with hierarchical settings classes	Nested BaseSettings with Field(default_factory=...)
FR-008	Generate derived configuration values from other settings	@computed_field decorator
FR-009	Perform post-initialization validation and transformation	@model_validator(mode="after") decorator
FR-010	Define field-level validation with annotated types	Annotated with AfterValidator
FR-011	Specify encoding for dotenv file reading	env_file_encoding in SettingsConfigDict
FR-012	Inherit configuration patterns via class inheritance	Python class inheritance from BaseSettings

Performance Requirements

The following performance expectations are relevant to the medical device software.

Requirement ID	Description	Acceptance Criteria
PR-001	Settings instantiation shall complete within acceptable application startup time	Configuration loading completes as part of overall startup (< 1 second)
PR-002	Cached settings access shall return immediately without re-parsing environment	@cache decorator ensures single instantiation per process
PR-003	Computed field evaluation shall not introduce significant overhead	Computed properties resolve within microseconds
PR-004	Dotenv file parsing shall complete efficiently for typical configuration file sizes	File parsing completes within 100ms for standard configuration files

Hardware Requirements

The following hardware dependencies or constraints are imposed by this SOUP component.

Requirement ID	Description	Notes / Limitations
HR-001	x86-64 or ARM64 processor architecture	Pure Python package with pre-built wheels for common platforms
HR-002	Filesystem access for dotenv loading	Requires read access to configuration files when using env_file

Software Requirements

The following software dependencies and environmental assumptions are required by this SOUP component.

Requirement ID	Description	Dependency / Version Constraints
SR-001	Python runtime environment	Python >=3.10
SR-002	Pydantic data validation library	pydantic >=2.7.0 (bundled dependency)
SR-003	python-dotenv for dotenv file support	python-dotenv >=0.21.0 (optional)
SR-004	AWS SDK for Secrets Manager integration	boto3 (optional, via aws-secrets-manager)
SR-005	Azure SDK for Key Vault integration	azure-identity, azure-keyvault-secrets (optional, via azure-key-vault)

Known Anomalies Assessment

This section evaluates publicly reported issues, defects, or security vulnerabilities associated with this SOUP component and their relevance to the medical device software.

No security vulnerabilities have been reported for pydantic-settings in the National Vulnerability Database (NVD), GitHub Security Advisories, or Snyk vulnerability database as of the review date (2026-01-27).

The only related vulnerability is in the parent Pydantic library:

Anomaly Reference	Status	Applicable	Rationale	Reviewed At
CVE-2024-3772 (Pydantic email validation ReDoS)	Fixed	No	This vulnerability affects the parent Pydantic library, not pydantic-settings directly. The device uses Pydantic >=2.12.0 which includes the fix (fixed in 2.4.0). Additionally, pydantic-settings does not perform email validation	2026-01-27

Pydantic Settings is actively maintained by the Pydantic team as part of the Pydantic ecosystem. The project maintains a security policy for coordinated vulnerability disclosure. According to Snyk's security analysis, no known vulnerabilities have been identified in the package itself.

The device's usage pattern minimizes risk exposure:

• Controlled configuration sources: All environment variables are set through controlled deployment infrastructure (container orchestration, CI/CD pipelines); no configuration is loaded from user-provided sources
• No cloud secrets integration: The device does not use AWS Secrets Manager, Azure Key Vault, or Google Cloud Secret Manager integrations; all configuration is loaded from environment variables and validated dotenv files
• Version locking: Requirements lock files pin pydantic-settings to version 2.12.0 across all services, ensuring reproducible deployments
• Namespace isolation: Each microservice uses distinct environment variable prefixes (API_GATEWAY_*, CONTROL_PLANE_*, EXPERT_ORCHESTRATOR_*), preventing configuration cross-contamination
• Type-safe validation: All configuration values are validated against strongly-typed Pydantic models with custom validators, rejecting invalid configuration at startup
• Singleton pattern: Settings are instantiated once per process via @cache decorator, preventing runtime configuration tampering
• File-based secrets: Sensitive values (JWT secret keys) are loaded from mounted secret files rather than environment variables, following container security best practices
• No arbitrary file paths: Dotenv file paths are hardcoded in settings classes; no user-controlled file path injection is possible

Assessment Methodology

The following methodology was used to identify and assess known anomalies:

• Sources consulted:

  • National Vulnerability Database (NVD) search for "pydantic-settings"
  • GitHub Security Advisories for pydantic/pydantic-settings
  • Snyk vulnerability database for pydantic-settings
  • ReversingLabs Spectra Assure vulnerability analysis
  • PyPI package security reports
  • pip-audit and safety dependency vulnerability scanners

• Criteria for determining applicability:

  • Vulnerability must affect deployed version (pydantic-settings 2.12.0)
  • Vulnerability must be exploitable through the device's configuration loading patterns
  • Attack vector must be reachable through controlled deployment infrastructure
  • Input validation, namespace isolation, and singleton patterns must not mitigate the vulnerability

• Risk control measures:

  • Version locking via requirements_lock.txt ensures reproducible, auditable deployments
  • All configuration sources are controlled by infrastructure (no user-provided configuration)
  • Environment variable prefixes prevent cross-service configuration interference
  • Pydantic validators reject malformed configuration at startup
  • Container isolation limits potential impact of any configuration-based exploitation
  • File-based secrets follow principle of least privilege with mounted volumes

Signature meaning

The signatures for the approval process of this document can be found in the verified commits at the repository for the QMS. As a reference, the team members who are expected to participate in this document and their roles in the approval process, as defined in Annex I Responsibility Matrix of the GP-001, are:

• Author: Team members involved
• Reviewer: JD-003, JD-004
• Approver: JD-001