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

Semantica AGI uses a layered configuration system where 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. 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 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 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

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 demonstrates this structure:

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.

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

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

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

Accessing Nested Values Safely

# 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: Contains ConfigManager and Config classes handling load, merge, and validation logic.
• semantica/utils/constants.py: Defines DEFAULT_CONFIG with all system defaults.
• cookbook/introduction/config.yaml: Reference example showing documented configuration options.
• semantica/cli.py: Implements the interactive wizard that generates ~/.semantica/config.yaml.
• 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 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.
• 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.

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