# How to Understand Configuration Files in Semantica AGI: A Complete Guide

> Master Semantica AGI configuration files with our complete guide. Learn how constants, YAML, and environment variables work together for seamless setup and control.

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

---

**Semantica AGI uses a layered configuration system where [`semantica/utils/constants.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/constants.py) provides defaults that are overridden by YAML files and `SEMANTICA_` prefixed environment variables, orchestrated by the `ConfigManager` class.**

Semantica AGI configuration files control everything from LLM provider credentials to knowledge graph backends in the `semantica-agi/semantica` repository. Understanding how these settings are loaded, validated, and prioritized is essential for customizing the framework to your deployment environment. This guide explains the architecture of the configuration system, from default constants to runtime overrides.

## Configuration Sources and Precedence

The configuration system resolves settings through a strict hierarchy: **defaults → user file → environment variables**.

### Default Configuration

Built-in defaults are defined as `DEFAULT_CONFIG` in [`semantica/utils/constants.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/constants.py). This dictionary contains sensible defaults for every component, including LLM providers, embedding models, graph backends, and logging levels. These values serve as the fallback when no other source specifies a setting.

### User Configuration Files

You can override defaults by creating a YAML or JSON file. The standard location is `~/.semantica/config.yaml`, though you can point `ConfigManager` to any file path. The repository includes an example at [`cookbook/introduction/config.yaml`](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/config.yaml) demonstrating the expected structure.

### Environment Variables

Variables prefixed with `SEMANTICA_` take highest precedence. The system strips the prefix, converts to lowercase, and transforms double underscores into dots to address nested keys (e.g., `SEMANTICA_KNOWLEDGE_GRAPH__BACKEND` maps to `knowledge_graph.backend`).

## The ConfigManager Architecture

The **ConfigManager** class in [`semantica/core/config_manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/core/config_manager.py) serves as the central orchestrator for loading and merging configuration data.

### Core Components

- **ConfigManager**: Handles file I/O, environment parsing, and merging logic through methods like `load_from_file()`, `merge_configs()`, and `reload()`.
- **Config**: A data class that stores resolved settings and provides helpers such as `get()`, `set()`, and `validate()`.

### Loading a Configuration

```python
from semantica.core import ConfigManager

manager = ConfigManager()
cfg = manager.load_from_file("cookbook/introduction/config.yaml")
batch_size = cfg.get("processing.batch_size", default=32)

```

The `load_from_file()` method automatically triggers validation unless explicitly disabled.

## Configuration File Structure

A typical Semantica AGI configuration file contains three primary sections. The example at [`cookbook/introduction/config.yaml`](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/config.yaml) demonstrates this structure:

```yaml
api_keys:
  openai: your_key_here
  anthropic: your_key_here
embedding:
  provider: openai
  model: text-embedding-3-large
  dimensions: 3072
knowledge_graph:
  backend: networkx
  temporal: true

```

- **api_keys**: Stores credentials for LLM providers. These are used by the CLI wizard and should never be committed to version control.
- **embedding**: Specifies the embedding provider (e.g., `openai`), model name, and output dimensions.
- **knowledge_graph**: Selects the graph backend (`networkx`, `neo4j`, `falkordb`, etc.) and enables temporal provenance tracking when `temporal: true`.

## Environment Variable Overrides

Environment variables provide a mechanism for deployment-specific customization without modifying files. The parsing logic in `ConfigManager._load_from_env` handles type coercion automatically.

```bash
export SEMANTICA_PROCESSING_BATCH_SIZE=64
export SEMANTICA_LOGGING_LEVEL=DEBUG
export SEMANTICA_KNOWLEDGE_GRAPH__BACKEND=neo4j

```

Values are automatically converted to appropriate Python types: `"true"` becomes `True`, `"42"` becomes `42`, and `"3.14"` becomes `3.14`.

## Validation and Error Handling

When a configuration loads, `Config.validate()` enforces schema constraints across key sections:

- **Processing**: `batch_size` and `max_workers` must be positive integers
- **Quality**: `min_confidence` must be a float in the range `[0.0, 1.0]`
- **Logging**: `level` must be one of `DEBUG`, `INFO`, `WARNING`, `ERROR`, or `CRITICAL`

Validation failures raise `ConfigurationError` with detailed context about which constraint failed and the current value that violated it.

## Practical Implementation Examples

### Merging Multiple Configurations

```python
from semantica.core import ConfigManager

mgr = ConfigManager()
base = mgr.load_from_file("config.yaml")
override = mgr.load_from_dict({"embedding": {"model": "text-embedding-ada-002"}})
merged = mgr.merge_configs(base, override)

print(merged.get("embedding.model"))  # Output: text-embedding-ada-002

```

### Dynamic Runtime Updates

```python
cfg.set("logging.level", "DEBUG")
cfg.validate()  # Re-run validation after modification

```

### Accessing Nested Values Safely

```python

# Returns default if path doesn't exist

backend = cfg.get("knowledge_graph.backend", default="networkx")

```

## Key Configuration Files

Understanding these source files provides complete visibility into the configuration lifecycle:

- [`semantica/core/config_manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/core/config_manager.py): Contains `ConfigManager` and `Config` classes handling load, merge, and validation logic.
- [`semantica/utils/constants.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/constants.py): Defines `DEFAULT_CONFIG` with all system defaults.
- [`cookbook/introduction/config.yaml`](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/config.yaml): Reference example showing documented configuration options.
- [`semantica/cli.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/cli.py): Implements the interactive wizard that generates `~/.semantica/config.yaml`.
- [`semantica/utils/helpers.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/helpers.py): Utility functions for nested dictionary access used throughout the config system.

## Summary

- **Semantica AGI configuration** follows a three-tier hierarchy: constants.py defaults, user YAML/JSON files, and `SEMANTICA_` environment variables.
- The **ConfigManager** class in [`semantica/core/config_manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/core/config_manager.py) orchestrates loading with methods like `load_from_file()` and `merge_configs()`.
- Configuration files typically define `api_keys`, `embedding`, and `knowledge_graph` sections as shown in [`cookbook/introduction/config.yaml`](https://github.com/semantica-agi/semantica/blob/main/cookbook/introduction/config.yaml).
- Environment variables use double underscores to represent nested keys (e.g., `SEMANTICA_KNOWLEDGE_GRAPH__BACKEND`).
- All configurations undergo strict validation via `Config.validate()` to ensure type safety and value constraints.

## Frequently Asked Questions

### Where should I place my Semantica AGI configuration file?

Place your configuration file at `~/.semantica/config.yaml` for automatic discovery, or specify a custom path when calling `ConfigManager.load_from_file("path/to/config.yaml")`. The CLI wizard creates the default location automatically when you run the initialization command.

### How do I override a nested configuration value using environment variables?

Use the `SEMANTICA_` prefix followed by the uppercase key path, replacing dots with double underscores. For example, to set `knowledge_graph.backend` to `neo4j`, use `export SEMANTICA_KNOWLEDGE_GRAPH__BACKEND=neo4j`. The parser automatically converts these to the correct nested dictionary structure.

### What happens if my configuration contains invalid values?

The `Config.validate()` method raises a `ConfigurationError` immediately upon loading or manual validation. The error message specifies which parameter failed validation and the invalid value provided, helping you identify whether the issue is in your YAML file or environment variables.

### Can I modify configuration values at runtime after loading?

Yes. Use the `cfg.set("key.path", value)` method on a `Config` instance, then call `cfg.validate()` to ensure the new value meets schema requirements. This is useful for testing different parameters without restarting your application or modifying configuration files.