Configuration Options in ConfigManager for Multi-Environment Deployments

Semantica's ConfigManager supports multi-environment deployments through a hierarchical configuration system that merges default values, YAML/JSON files, and SEMANTICA_-prefixed environment variables, with type validation enforced via the Config.validate() method.

The Semantica open-source AGI framework centralizes runtime configuration through the ConfigManager class to streamline deployments across development, staging, and production environments. Located in semantica/core/config_manager.py, this module implements a precedence-based merging strategy that allows teams to maintain base configurations in version control while injecting secrets and environment-specific overrides via environment variables. This article examines the available configuration options in ConfigManager for multi-environment deployments, detailing the default sections, override mechanics, and validation logic implemented in the source code.

Core Configuration Sections in ConfigManager

Semantica organizes configuration into distinct sections defined in DEFAULT_CONFIG within semantica/utils/constants.py. These sections provide type-safe defaults for runtime behavior.

Logging Configuration (lines 99-101)

The logging section controls diagnostic output behavior:

• level (str): One of DEBUG, INFO, WARNING, ERROR, or CRITICAL
• format (str): Python log format string for message layout
• file (str): Destination filename for persistent log storage

Processing Configuration (lines 102-103)

The processing section manages concurrency and throughput:

• batch_size (int): Number of items processed per batch operation
• max_workers (int): Thread-pool size for parallel execution
• timeout (int): Abort threshold in seconds for long-running tasks

Quality and Validation (lines 104-106)

The quality section enforces data integrity standards:

• min_confidence (float): Minimum threshold for model prediction acceptance
• max_errors (int): Tolerated validation failures before pipeline termination
• validation_enabled (bool): Toggle for enabling schema validation steps

Security Controls (lines 105-108)

The security section manages access and audit policies:

• encryption_enabled (bool): Toggle for data-at-rest encryption
• access_control_enabled (bool): Enforce Access Control Lists (ACLs)
• audit_logging_enabled (bool): Log security-relevant events for compliance

Provider-Specific Sections

Free-form dictionaries accommodate external service configuration through the _load_from_env method (lines 61-89 in config_manager.py). These sections accept arbitrary key-value pairs for:

• llm_provider: API keys, model names, and endpoint URLs
• embedding_model: Vectorization service parameters
• vector_store: Database connection strings and index settings
• graph_db: Graph database credentials and traversal limits
• pipeline, provenance, custom: User-defined extension points

Multi-Environment Configuration Hierarchy

ConfigManager resolves configuration through a four-level precedence chain implemented in the Config class constructor and load methods:

1. Baseline Defaults: DEFAULT_CONFIG in semantica/utils/constants.py supplies safe defaults for every deployment.

2. File-Based Overrides: manager.load_from_file("config.yaml") merges environment-specific YAML or JSON values over the defaults using the merge_dicts utility from semantica/utils/helpers.py.

3. Environment Variable Overrides: The _load_from_env method (lines 61-89) automatically scans for variables prefixed with SEMANTICA_ and applies them over file-based values.

4. Programmatic Overrides: manager.load_from_dict() or config.set("section.key", value) injects runtime values with the highest priority.

Environment Variable Mapping and Precedence

Environment variables use a double-underscore convention to represent nested dictionary structures. The parser in _load_from_env converts SEMANTICA_<SECTION>__<OPTION> to dot-notation keys.

Mapping examples:

• SEMANTICA_PROCESSING_BATCH_SIZE=512 overrides processing.batch_size
• SEMANTICA_LOGGING_LEVEL=DEBUG overrides logging.level
• SEMANTICA_SECURITY__ENCRYPTION_ENABLED=true overrides security.encryption_enabled (note the double underscore for nesting)

These overrides supersede file-based configuration without modifying committed files, enabling secure secret injection in containerized environments like Docker or Kubernetes.

Configuration Validation and Type Safety

Before activation, Config.validate() (defined in semantica/core/config_manager.py) verifies type correctness, range constraints, and required values. Validation failures raise ConfigurationError with detailed context via config_context=self.to_dict().

Specialized validators include:

• _validate_processing (lines 63-93): Checks batch size positivity and worker limits
• _validate_quality (lines 95-114): Validates confidence scores are between 0.0 and 1.0
• _validate_logging (lines 115-128): Ensures log levels match allowed enumerations

The deep-merge algorithm preserves nested structures during validation, ensuring partial overrides do not corrupt unrelated configuration branches.

Practical Implementation for Multi-Environment Setups

The following workflow demonstrates loading a base configuration, applying environment-specific overlays, injecting runtime secrets, and enabling hot-reloading:

from semantica.core import ConfigManager

# 1. Initialize manager and load base configuration

manager = ConfigManager()
base_cfg = manager.load_from_file("config.yaml")  # Merges with DEFAULT_CONFIG

# 2. Apply production-specific overlay from version control

prod_cfg = manager.load_from_file("config.prod.yaml", validate=False)
merged_cfg = manager.merge_configs(base_cfg, prod_cfg)

# 3. Inject environment variables (e.g., container secrets)

# export SEMANTICA_PROCESSING_BATCH_SIZE=512

# export SEMANTICA_LOGGING_LEVEL=DEBUG

final_cfg = manager.load_from_dict(merged_cfg.to_dict())  # Auto-loads env vars via _load_from_env

# 4. Access nested values using dot notation

batch_size = final_cfg.get("processing.batch_size")  # Returns 512

# 5. Runtime modification for dynamic scaling

final_cfg.set("processing.max_workers", 16)

# 6. Zero-downtime configuration reload

final_cfg = manager.reload()  # Re-reads last file path and re-applies env vars

Summary

• Hierarchical Precedence: Configuration resolves through defaults → files → environment variables → programmatic calls, ensuring flexibility without configuration drift.
• Environment Variable Convention: Use SEMANTICA_SECTION__OPTION format (double underscores for nesting) to override any value without code changes.
• Type Safety: Config.validate() and specialized validators in config_manager.py enforce schema compliance at load time.
• Runtime Adaptability: ConfigManager.reload() enables hot-swapping configurations in long-running processes without service interruption.
• Secure Secret Management: Sensitive values (API keys, passwords) should reside only in environment variables, never in committed YAML files.

Frequently Asked Questions

How do I override nested configuration values using environment variables?

Use the SEMANTICA_ prefix followed by the section name, double underscores for nesting, and the option name in uppercase. For example, SEMANTICA_VECTOR_STORE__HOST=localhost overrides vector_store.host. The _load_from_env method in semantica/core/config_manager.py (lines 61-89) handles this translation automatically during initialization.

What is the precedence order when multiple configuration sources define the same key?

ConfigManager applies values in ascending order of priority: (1) DEFAULT_CONFIG constants, (2) file-based configuration via load_from_file(), (3) environment variables parsed by _load_from_env, and (4) programmatic overrides via load_from_dict() or set(). Later sources always supersede earlier ones for the same key path.

Can I reload configuration at runtime without restarting the application?

Yes. Call manager.reload() on your ConfigManager instance to re-read the last loaded file path and re-parse all SEMANTICA_ prefixed environment variables. This method preserves the existing configuration object reference while updating values, enabling zero-downtime configuration updates in production deployments.

Where are the default configuration values defined in the Semantica codebase?

Default values reside in the DEFAULT_CONFIG dictionary within semantica/utils/constants.py (lines 99-108). This dictionary defines the structure and default values for the logging, processing, quality, and security sections, as well as empty dictionaries for provider-specific extensions like llm_provider and vector_store.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}