> For the complete documentation index, see [llms.txt](https://axions-organization.gitbook.io/axion-framework/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axions-organization.gitbook.io/axion-framework/basics/yaml-configuration-guide.md).

# YAML Configuration Guide

## **YAML Configuration Guide**

### **Introduction**

The **Axion Framework** utilizes a centralized YAML configuration file (`config.yaml`) to streamline its settings and ensure easy customization. This approach simplifies managing configurations across various environments, such as development, staging, and production.

In this guide, we’ll cover:

* The purpose and structure of the configuration file.
* How to modify and manage settings.
* Best practices for secure management of sensitive data using environment variables.

***

### **Configuration File Structure**

<figure><img src="https://3132812403-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFGYnX4Q9DDFhpyOXKQmr%2Fuploads%2Fz7uNY7bAOZGLP530c8tA%2FIMG_0011.JPG?alt=media&amp;token=a06097c2-15d6-4de0-b47d-acd9396223d9" alt=""><figcaption></figcaption></figure>

Here’s a sample `config.yaml` file, with an explanation of each section:

```yaml
yamlCopy code# General environment settings
environment: development  # Options: development, staging, production

# AI Agent configuration
axion:
  agent:
    id: 1                        # Unique ID for the agent
    role: "manager"              # Agent role (e.g., worker, coordinator)
    max_tasks: 10                # Maximum tasks the agent can handle

# LLM Integration
llm:
  provider: "openai"             # Supported providers: openai, anthropic, ollama
  base_url: "https://api.openai.com"
  model: "gpt-4"
  api_timeout: 10                # API call timeout in seconds
  retry_attempts: 3              # Number of retries for failed requests

# Swarm Intelligence Configuration
swarm:
  redis:
    host: "localhost"            # Redis server hostname
    port: 6379                   # Redis server port
  consensus_threshold: 3         # Minimum votes for swarm consensus

# Blockchain Integration
blockchain:
  solana:
    rpc_url: "https://api.mainnet-beta.solana.com"
    wallet_path: "/path/to/solana-wallet.json"
  ethereum:
    rpc_url: "https://mainnet.infura.io/v3/${ETH_RPC_KEY}"  # Use environment variables for security

# Logging and Debugging
logging:
  level: "INFO"                  # Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
  file: "logs/axion.log"
  rotate_logs: true              # Enable log file rotation
```

***

### **Editing the Configuration File**

#### **Locate and Open `config.yaml`**

You’ll find `config.yaml` in the root directory of your Axion Framework project.

#### **Update Configuration Values**

Modify the file based on your specific environment:

* Example for a production setup:

  ```yaml
  yamlCopy codeenvironment: production
  swarm:
    redis:
      host: "prod-redis.example.com"
      password: "securepassword123"
  ```

#### **Use Environment-Specific Configurations**

It’s a best practice to use separate YAML files for each environment:

* `config.development.yaml`
* `config.staging.yaml`
* `config.production.yaml`

**Dynamic Loading**

Load the appropriate configuration file based on the environment:

```python
pythonCopy codeimport os
env = os.getenv("AXION_ENVIRONMENT", "development")
config_file = f"config.{env}.yaml"
```

***

### **Using Environment Variables**

To manage sensitive data (like API keys and passwords) securely, avoid hardcoding them in your YAML file.

#### **Steps for Secure Key Management**

1. **Add Variables to a `.env` File**

   ```bash
   bashCopy codeAXION_LLM_PROVIDER=anthropic
   AXION_SWARM_REDIS_PASSWORD=securepassword123
   ETH_RPC_KEY=your_infura_project_key
   ```
2. **Reference Variables in `config.yaml`**\
   Use the `${VARIABLE_NAME}` syntax to include them dynamically:

   ```yaml
   yamlCopy codeblockchain:
     ethereum:
       rpc_url: "https://mainnet.infura.io/v3/${ETH_RPC_KEY}"
   ```
3. **Load Environment Variables in Code**\
   Use Python’s `os` module to read environment variables:

   ```python
   pythonCopy codeimport os
   ethereum_rpc = os.getenv("ETH_RPC_KEY")
   ```

***

### **Best Practices**

* **Secure Sensitive Data**\
  Always use environment variables for keys, passwords, and other confidential settings.
* **Environment-Specific YAML Files**\
  Use separate YAML files (`config.development.yaml`, `config.production.yaml`) and load them dynamically.
* **Document Configuration Changes**\
  Ensure any new configuration options are added to project documentation for clarity and collaboration.

***

### **Example Workflow**

1. **Set the Environment**

   ```bash
   bashCopy codeAXION_ENVIRONMENT=production
   ```
2. **Edit the YAML File**\
   Update paths, hostnames, or thresholds specific to your environment.
3. **Run the Framework**

   ```bash
   bashCopy codepython main.py --config=config.production.yaml
   ```

***

### **Common Issues and Solutions**

#### **1. Missing Configuration File**

* **Error**: `FileNotFoundError: config.yaml not found`
* **Solution**: Ensure the `config.yaml` file is in the correct directory, or explicitly specify the file path.

#### **2. Missing Environment Variables**

* **Error**: `API key for openai not found`
* **Solution**: Add the required variables to a `.env` file or set them in your system environment.

#### **3. Invalid YAML Syntax**

* **Error**: `yaml.scanner.ScannerError`
* **Solution**: Validate the YAML file using a linter or an online validator.