Configuration Loader

Relevant source files

The following files were used as context for generating this wiki page:

• src/config/loader.py
• rust-terminal/src/utils/config.rs
• src/cli.py
• README.md
• rust-terminal/README.md
• AGENT.md

The Configuration Loader system in WIREDUP provides a sophisticated, multi-source, and hierarchical approach to managing application settings across both Python and Rust components. It handles everything from intelligent auto-discovery of configuration directories to deep-merging settings from multiple file formats, environment variables, and local overrides. Sources: src/config/loader.py:1-10, README.md:12-25

The system is designed to support different environments (e.g., development, production) and provides a unified interface for the Auto-Wiring Engine and AI Agents to access validated configuration data. By utilizing a specific load order, it ensures that local development settings or environment-specific variables can safely override defaults without modifying the core codebase. Sources: src/config/loader.py:20-30, AGENT.md:215-230

Python Configuration Architecture

The Python implementation centers on the ConfigLoader class, which manages a merged configuration dictionary. It supports dot-notation access for nested keys and implements a strict priority-based loading sequence. Sources: src/config/loader.py:16-50

Load Order and Priority

The ConfigLoader follows a hierarchical merging strategy where later sources override earlier ones:

1. Default Files: config/default.json or config/default.yaml.
2. Environment Files: config/{env}.json or config/{env}.yaml.
3. Local Overrides: config/local.json or config/local.yaml.
4. Dotenv Files: .env files (e.g., .env.development, .env.local).
5. Environment Variables: Variables prefixed with AI_.
6. CLI Arguments: Passed during runtime via the command line interface.

Sources: src/config/loader.py:23-32, src/cli.py:38-75

Config Discovery Flow

The following diagram illustrates how the ConfigLoader discovers and merges data from disparate sources into the final state.

The discovery process scans for directories named config, configs, or .config relative to the base path. Sources: src/config/loader.py:46-68, src/config/loader.py:101-110

Rust Configuration Management

In the rust-terminal (NexTerm) component, configuration is handled via a Config struct that leverages serde for serialization/deserialization. Unlike the Python side's dynamic dictionary approach, the Rust side uses a strongly-typed schema to ensure performance and safety within the TUI environment. Sources: rust-terminal/src/utils/config.rs:7-17, rust-terminal/Cargo.toml:34-37

Rust Config Schema

Field	Type	Default Value	Description
shell	String	$SHELL or /bin/bash	System shell to execute commands
editor	String	$EDITOR or vim	Default text editor
theme	String	dracula	TUI color scheme
ai_enabled	bool	true	Toggles AI suggestion features
autowire_enabled	bool	true	Toggles Python bridge integration
font_size	u16	14	Terminal font size
show_status_bar	bool	true	Toggles TUI status bar visibility

Sources: rust-terminal/src/utils/config.rs:10-29

File Location and Persistence

The Rust configuration is typically stored in the user's standard config directory (e.g., ~/.config/nexterm/config.toml). The system automatically generates a default config.toml if one is not found during the load() operation. Sources: rust-terminal/src/utils/config.rs:43-68

CLI Configuration Management

The src/cli.py module provides administrative commands to interact with the configuration system. Users can initialize new environments, retrieve specific keys, or export the entire merged configuration for debugging. Sources: src/cli.py:38-45, src/cli.py:155-165

Key CLI Commands

• init: Creates the config/ directory, populates default.json, and generates a .env.example template. Sources: src/cli.py:38-95
• config [KEY]: Retrieves a specific value using dot-notation (e.g., ai-wire config mcp.port). Sources: src/cli.py:155-173
• export-config: Outputs the current merged state in json, yaml, or table format. Sources: src/cli.py:214-239

# Example of dot-notation retrieval in Python
from src.config import get_config

# Accesses merged_config['mcp']['port']
mcp_port = get_config('mcp.port', default=3000)

Sources: src/config/loader.py:82-96, src/config/loader.py:238-240

Technical Implementation Details

Environment Variable Parsing

The Python loader includes logic to automatically convert environment variables into typed data. It attempts to parse values as JSON (for lists/dicts), booleans, integers, or floats before defaulting to strings. Key names like AI_MCP_PORT are converted to lowercase and split by underscores to create nested structures (e.g., config['mcp']['port']). Sources: src/config/loader.py:168-208

Deep Merging Logic

The _deep_merge utility ensures that nested dictionaries are merged recursively rather than being overwritten. This allows a local.json file to override a single nested key in a large configuration object without losing other sibling keys defined in default.json. Sources: src/config/loader.py:210-216

The Configuration Loader serves as the foundational data provider for the entire WIREDUP ecosystem, bridging the gap between static files, environmental context, and runtime requirements. Sources: README.md:65-80, AGENT.md:215-225