# Configuration Options in ConfigManager for Multi-Environment Deployments

> Explore ConfigManager's multi-environment deployment options. Learn how Semantica merges defaults, files, and env vars with type validation for robust configurations.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-21

---

**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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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:

```python
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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`](https://github.com/semantica-agi/semantica/blob/main/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`.