# Configuration Management in SymbolicAI: A Complete Guide to JSON-Based Settings

> Learn how SymbolicAI manages configuration with its powerful JSON-based settings. Explore the multi-level priority system for debug environment and global user settings.

- Repository: [ExtensityAI/symbolicai](https://github.com/extensityai/symbolicai)
- Tags: how-to-guide
- Published: 2026-03-01

---

**SymbolicAI manages configuration through a hierarchical JSON file system with three priority levels—debug (current directory), environment-specific, and global user settings—centered around the `SymAIConfig` class in [`symai/backend/settings.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/settings.py).**

The `extensityai/symbolicai` repository implements a robust configuration management system that allows developers to customize LLM models, API keys, and engine options across different deployment contexts. This article explores how the framework handles configuration files, prioritizes settings, and provides runtime access to configuration dictionaries.

## The Three-Tier Configuration Hierarchy

SymbolicAI employs a cascading priority system where configuration files are resolved in the following order:

1. **Debug mode (current working directory)** – [`./symai.config.json`](https://github.com/extensityai/symbolicai/blob/main/./symai.config.json) (plus [`symsh/config.json`](https://github.com/extensityai/symbolicai/blob/main/symsh/config.json) and [`symserver/config.json`](https://github.com/extensityai/symbolicai/blob/main/symserver/config.json) for shell and server components). This allows developers to override settings locally without modifying global files.

2. **Python-environment config** – `<python-prefix>/.symai/`. This holds per-environment configurations for virtual environments or Conda environments.

3. **User-home (global) config** – `~/.symai/`. This serves as the fallback for defaults shared across all environments for a user.

The `SymAIConfig` class in [`symai/backend/settings.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/settings.py) encapsulates this resolution logic, checking for file existence in each location and returning the first match found.

## Core Configuration Components

### SymAIConfig: The Configuration Facade

The `SymAIConfig` class serves as the primary interface for all configuration operations in [`symai/backend/settings.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/settings.py). During initialization, it records three base directories:

- `self._debug_dir = Path.cwd()` for the current working directory
- `self._env_config_dir = Path(sys.prefix) / ".symai"` for the Python environment
- `self._home_config_dir = Path.home() / ".symai"` for the user home directory

The `config_dir` property implements priority resolution by checking for [`symai.config.json`](https://github.com/extensityai/symbolicai/blob/main/symai.config.json) in the debug folder first, then falling back to environment or home directories. The `get_config_path()` method builds absolute paths for requested config files, respecting this priority order and an optional `fallback_to_home` flag.

For persistence, `load_config()` reads JSON files, caches paths in `_active_paths`, and returns empty dictionaries for missing files. The `save_config()` method writes JSON data, ensures parent directories exist, and updates the cache. Migration utilities like `migrate_config()` add new fields to existing configurations, while private helpers such as `_canonical_key` and `_remove_legacy_path_keys` prevent stale path keys from lingering in the cache.

### Package Bootstrap in [`symai/__init__.py`](https://github.com/extensityai/symbolicai/blob/main/symai/__init__.py)

When the SymbolicAI package imports, the `_start_symai()` function executes a comprehensive initialization sequence:

1. **Directory creation** – Ensures config directories exist using `mkdir(parents=True, exist_ok=True)`
2. **Default file creation** – Generates [`symsh.config.json`](https://github.com/extensityai/symbolicai/blob/main/symsh.config.json) and [`symserver.config.json`](https://github.com/extensityai/symbolicai/blob/main/symserver.config.json) if missing
3. **Primary config loading** – Loads [`symai.config.json`](https://github.com/extensityai/symbolicai/blob/main/symai.config.json), launching a setup wizard when the file is absent
4. **Post-migration** – Handles field migrations, such as moving `TEXT_TO_SPEECH_ENGINE_API_KEY` to new locations
5. **Engine validation** – Verifies neuro-symbolic engine configuration, falling back to home config or aborting with user-friendly messages if the model is not a built-in Llama/HuggingFace engine and lacks an API key

This bootstrap populates three global dictionaries—`SYMAI_CONFIG`, `SYMSH_CONFIG`, and `SYMSERVER_CONFIG`—making configuration data available throughout the codebase via simple imports:

```python
from symai.backend.settings import SYMAI_CONFIG

```

### Runtime Helpers

The configuration system provides diagnostic utilities for runtime inspection. The `get_active_path(filename)` method returns the exact file path last used to read or write a given config, aiding in debugging configuration source issues. The `display_config()` function leverages the Rich library to render an interactive tree showing all three configuration locations (debug, environment, home) with active paths highlighted, providing immediate visual feedback about which configuration files are currently in effect.

## How Components Access Configuration

Individual engines and high-level components import the shared `SYMAI_CONFIG` dictionary to retrieve settings. For example, the OpenAI-based neuro-symbolic engine in [`symai/backend/engines/neurosymbolic/engine_openai_gptX_chat.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/engines/neurosymbolic/engine_openai_gptX_chat.py) accesses its model and API key as follows:

```python
from symai.backend.settings import SYMAI_CONFIG

model = SYMAI_CONFIG.get("NEUROSYMBOLIC_ENGINE_MODEL")
api_key = SYMAI_CONFIG.get("NEUROSYMBOLIC_ENGINE_API_KEY")

```

Because `SYMAI_CONFIG` populates once at import time, subsequent imports throughout the application see a fully resolved configuration state without additional file I/O.

## Practical Configuration Examples

### Reading and Overriding Settings

Developers can inspect and modify configuration values at runtime using the configuration manager and global dictionary:

```python

# 1️⃣ Import the manager and config dict

from symai.backend.settings import config_manager, SYMAI_CONFIG

# 2️⃣ Read the current model

print("Current neuro-symbolic model:", SYMAI_CONFIG.get("NEUROSYMBOLIC_ENGINE_MODEL"))

# 3️⃣ Override a value for the current session (e.g., switch to a local Llama model)

SYMAI_CONFIG["NEUROSYMBOLIC_ENGINE_MODEL"] = "llama_cpp"
SYMAI_CONFIG["NEUROSYMBOLIC_ENGINE_API_KEY"] = ""   # not needed for local inference

# 4️⃣ Persist the change to the *debug* config (CWD) – useful during experimentation

config_manager.save_config("symai.config.json", SYMAI_CONFIG)
print("Saved new config to:", config_manager.get_active_path("symai.config.json"))

```

### Using the Configuration Inspector

For debugging configuration sources, SymbolicAI provides a visual inspection tool:

```python
from symai import display_config

# Opens an interactive Rich tree showing:

# • Debug config (if present)

# • Environment config

# • Home (global) config

# • Active configuration summary

display_config()

```

## Key Configuration Files

The configuration architecture spans several critical files within the repository:

- **[`symai/backend/settings.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/settings.py)** – Contains the core `SymAIConfig` implementation, including path resolution, JSON load/save operations, and configuration migration logic.

- **[`symai/__init__.py`](https://github.com/extensityai/symbolicai/blob/main/symai/__init__.py)** – Handles package bootstrap, directory creation, default config file generation, setup wizard execution, and population of global configuration dictionaries.

- **[`symai/backend/engines/neurosymbolic/engine_openai_gptX_chat.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/engines/neurosymbolic/engine_openai_gptX_chat.py)** – Demonstrates how neuro-symbolic engines retrieve model and API key settings from `SYMAI_CONFIG`.

- **[`symai/extended/vectordb.py`](https://github.com/extensityai/symbolicai/blob/main/symai/extended/vectordb.py)** – Illustrates how higher-level tools copy the configuration dictionary for internal use.

- **[`symai/utils.py`](https://github.com/extensityai/symbolicai/blob/main/symai/utils.py)** – Provides helper functions such as `UserMessage` for emitting user-visible messages during configuration validation.

## Summary

- SymbolicAI uses a **three-tier hierarchy** for configuration files: debug (current directory), Python environment (`<prefix>/.symai/`), and user home (`~/.symai/`), resolved in that priority order.

- The **`SymAIConfig`** class in [`symai/backend/settings.py`](https://github.com/extensityai/symbolicai/blob/main/symai/backend/settings.py) encapsulates all path resolution, file I/O, and migration logic for JSON configuration files.

- **Global dictionaries** (`SYMAI_CONFIG`, `SYMSH_CONFIG`, `SYMSERVER_CONFIG`) populate at package import time via the bootstrap sequence in [`symai/__init__.py`](https://github.com/extensityai/symbolicai/blob/main/symai/__init__.py), making settings immediately available throughout the codebase.

- Components access settings by importing `SYMAI_CONFIG` and using standard dictionary methods, as demonstrated in the OpenAI engine implementation.

- Runtime utilities like `config_manager.save_config()` and `display_config()` enable dynamic configuration updates and visual debugging of active settings.

## Frequently Asked Questions

### Where does SymbolicAI store its configuration files?

SymbolicAI stores configuration files in three possible locations, checked in priority order: first in the current working directory ([`./symai.config.json`](https://github.com/extensityai/symbolicai/blob/main/./symai.config.json) for debug mode), then in the Python environment directory (`<python-prefix>/.symai/`), and finally in the user home directory (`~/.symai/`). The framework uses the first configuration file it finds in this sequence, allowing local overrides to take precedence over global settings.

### How do I override configuration settings for a single project?

To override settings for a specific project, create a [`symai.config.json`](https://github.com/extensityai/symbolicai/blob/main/symai.config.json) file in your project's root directory (current working directory). This debug-mode configuration automatically takes priority over environment and home directory settings. You can also modify settings at runtime by importing `SYMAI_CONFIG` from `symai.backend.settings`, updating the dictionary values, and calling `config_manager.save_config("symai.config.json", SYMAI_CONFIG)` to persist changes to the local file.

### What happens if the configuration file is missing?

If SymbolicAI cannot find [`symai.config.json`](https://github.com/extensityai/symbolicai/blob/main/symai.config.json) in any of the three hierarchical locations (debug, environment, or home), the bootstrap process in [`symai/__init__.py`](https://github.com/extensityai/symbolicai/blob/main/symai/__init__.py) triggers an interactive setup wizard to create a new configuration file. Additionally, the `load_config()` method in `SymAIConfig` returns an empty dictionary if a requested file does not exist, allowing the system to handle missing configurations gracefully while prompting the user for necessary setup.

### How can I view the currently active configuration?

Use the `display_config()` function imported from the `symai` package to visualize the active configuration hierarchy. This function renders an interactive Rich tree showing all three configuration locations (debug, environment, and home), highlighting which specific files are currently active. For programmatic access, call `config_manager.get_active_path("symai.config.json")` to retrieve the exact file path being used for the main configuration.