Configuration¶

Configuration management for Attune AI. Configure via direct instantiation, YAML/JSON files, or environment variables.

Overview¶

The configuration system provides flexible options for customizing Attune AI behavior:

Direct instantiation: Pass parameters to AttuneConfig()
YAML/JSON files: Load from attune.config.yml or attune.config.json
Environment variables: Use ATTUNE_* prefixed variables (EMPATHY_* also accepted for backward compatibility)
Validation: Automatic validation on load with helpful error messages

Quick Start¶

Direct Configuration¶

from attune import AttuneConfig

config = AttuneConfig(
    user_id="user_123",
    confidence_threshold=0.75,
    persistence_enabled=True,
)

YAML Configuration¶

Create attune.config.yml:

user_id: "user_123"
confidence_threshold: 0.75
persistence_enabled: true
persistence_backend: "sqlite"
persistence_path: "./attune_data"
metrics_enabled: true

Load it:

from attune import load_config

config = load_config(filepath="attune.config.yml")

Environment Variables¶

export ATTUNE_USER_ID="user_123"
export ATTUNE_CONFIDENCE_THRESHOLD=0.75

from attune import load_config

# Automatically loads from environment
config = load_config(use_env=True)

Class Reference¶

Configuration for an Attune instance

Can be loaded from: - YAML file (.attune.yml, attune.config.yml) - JSON file (.attune.json, attune.config.json) - Environment variables (ATTUNE_*) - Direct instantiation

`__post_init__()` ¶

Post-initialization validation.

`repr()` ¶

String representation

`from_dict(data)` `classmethod` ¶

Create an AttuneConfig from a dictionary, ignoring unknown fields.

`from_env(prefix='ATTUNE_')` `classmethod` ¶

Load configuration from environment variables.

Environment variables can be prefixed with ATTUNE_ (preferred) or EMPATHY_ (deprecated, still accepted). ATTUNE_ takes precedence.

Example

ATTUNE_USER_ID=alice ATTUNE_TARGET_LEVEL=4 ATTUNE_CONFIDENCE_THRESHOLD=0.8

Parameters:

Name	Type	Description	Default
`prefix`	`str`	Environment variable prefix (default: "ATTUNE_")	`'ATTUNE_'`

Returns:

Type	Description
`AttuneConfig`	AttuneConfig instance

Example

os.environ["ATTUNE_USER_ID"] = "alice" config = AttuneConfig.from_env() print(config.user_id) # "alice"

`from_file(filepath=None)` `classmethod` ¶

Automatically detect and load configuration from file

Looks for configuration files in this order: 1. Provided filepath 2. .empathy.yml 3. .empathy.yaml 4. .attune.yml 5. .attune.yaml 6. attune.config.yml 7. attune.config.yaml 8. .empathy.json 9. .attune.json 10. attune.config.json

Parameters:

Name	Type	Description	Default
`filepath`	`str \| None`	Optional explicit path to config file	`None`

Returns:

Type	Description
`AttuneConfig`	AttuneConfig instance, or default if no file found

Example

config = AttuneConfig.from_file() # Auto-detect config = AttuneConfig.from_file("my-config.yml")

`from_json(filepath)` `classmethod` ¶

Load configuration from JSON file

Parameters:

Name	Type	Description	Default
`filepath`	`str`	Path to JSON configuration file	required

Returns:

Type	Description
`AttuneConfig`	AttuneConfig instance

Example

config = AttuneConfig.from_json("attune.config.json")

Note

Unknown fields in the JSON file are silently ignored.

`from_yaml(filepath)` `classmethod` ¶

Load configuration from YAML file

Parameters:

Name	Type	Description	Default
`filepath`	`str`	Path to YAML configuration file	required

Returns:

Type	Description
`AttuneConfig`	AttuneConfig instance

Raises:

Type	Description
`ImportError`	If PyYAML is not installed
`FileNotFoundError`	If file doesn't exist

Example

config = AttuneConfig.from_yaml("attune.config.yml")

Note

Unknown fields in the YAML file are silently ignored. This allows config files to contain settings for other components (e.g., model_preferences, workflows) without breaking AttuneConfig loading.

`merge(other)` ¶

Merge with another configuration (other takes precedence)

Parameters:

Name	Type	Description	Default
`other`	`AttuneConfig`	Configuration to merge	required

Returns:

Type	Description
`AttuneConfig`	New merged configuration

Example

base = AttuneConfig(user_id="alice") override = AttuneConfig(target_level=5) merged = base.merge(override)

`to_dict()` ¶

Convert configuration to dictionary

`to_json(filepath, indent=2)` ¶

Save configuration to JSON file

Parameters:

Name	Type	Description	Default
`filepath`	`str`	Path to save JSON file	required
`indent`	`int`	JSON indentation (default: 2)	`2`

Example

config = AttuneConfig(user_id="alice", target_level=4) config.to_json("my-config.json")

`to_yaml(filepath)` ¶

Save configuration to YAML file

Parameters:

Name	Type	Description	Default
`filepath`	`str`	Path to save YAML file	required

Example

config = AttuneConfig(user_id="alice", target_level=4) config.to_yaml("my-config.yml")

`update(**kwargs)` ¶

Update configuration fields

Parameters:

Name	Type	Description	Default
`**kwargs`	`Any`	Fields to update	`{}`

Example

config = AttuneConfig() config.update(user_id="bob", target_level=5)

`validate()` ¶

Validate configuration values

Returns:

Type	Description
`bool`	True if valid, raises ValueError if invalid

Raises:

Type	Description
`ValueError`	If configuration is invalid

Configuration Options¶

Core Settings¶

`user_id` (str, default: "default_user")¶

Unique identifier for the user or system.

Example:

from attune import AttuneConfig

config = AttuneConfig(user_id="user_123")

`confidence_threshold` (float, default: 0.75)¶

Minimum confidence score (0.0-1.0) required for predictions and suggestions.

Higher values = More conservative (fewer, higher-quality predictions). Lower values = More aggressive (more predictions, potentially lower quality).

Example:

from attune import AttuneConfig

# Conservative: Only high-confidence predictions
config = AttuneConfig(confidence_threshold=0.85)

# Aggressive: More predictions, accept lower confidence
config = AttuneConfig(confidence_threshold=0.60)

Trust Settings¶

`trust_building_rate` (float, default: 0.05)¶

How much trust increases on successful interactions (0.0-1.0).

Example:

from attune import AttuneConfig

# Fast trust building (+10% per success)
config = AttuneConfig(trust_building_rate=0.10)

# Slow trust building (+2% per success)
config = AttuneConfig(trust_building_rate=0.02)

`trust_erosion_rate` (float, default: 0.10)¶

How much trust decreases on failed interactions (0.0-1.0).

Example:

from attune import AttuneConfig

# Forgiving: Small trust loss on failure
config = AttuneConfig(trust_erosion_rate=0.05)

# Strict: Large trust loss on failure
config = AttuneConfig(trust_erosion_rate=0.20)

Persistence Settings¶

`persistence_enabled` (bool, default: True)¶

Enable saving patterns, metrics, and state to disk.

Example:

from attune import AttuneConfig

# Production: Enable persistence
config = AttuneConfig(persistence_enabled=True)

# Testing: Disable persistence
config = AttuneConfig(persistence_enabled=False)

`persistence_backend` (str, default: "sqlite")¶

Storage backend for persistence.

Options:

"sqlite" - SQLite database (local development)
"postgresql" - PostgreSQL (production)
"json" - JSON files (backup/export)

Example:

from attune import AttuneConfig

# Local development
config = AttuneConfig(persistence_backend="sqlite")

# Production
config = AttuneConfig(
    persistence_backend="postgresql",
    persistence_path="postgresql://user:pass@localhost/attune",
)

`persistence_path` (str, default: "./attune_data")¶

Path for storing persistence data.

Example:

from attune import AttuneConfig

# Default location
config = AttuneConfig(persistence_path="./attune_data")

# Custom location
config = AttuneConfig(persistence_path="/var/lib/attune")

Metrics Settings¶

`metrics_enabled` (bool, default: True)¶

Enable metrics collection for monitoring and analytics.

Example:

from attune import AttuneConfig

config = AttuneConfig(metrics_enabled=True)

`metrics_path` (str, default: "./metrics.db")¶

Path for storing metrics data.

Example:

from attune import AttuneConfig

config = AttuneConfig(metrics_path="/var/lib/attune/metrics.db")

Pattern Library Settings¶

`pattern_library_enabled` (bool, default: True)¶

Enable pattern discovery and learning.

Example:

from attune import AttuneConfig

# Disable for simple use cases
config = AttuneConfig(pattern_library_enabled=False)

`pattern_sharing` (bool, default: True)¶

Enable pattern sharing across multiple agents.

Example:

from attune import AttuneConfig

# Disable pattern sharing
config = AttuneConfig(pattern_sharing=False)

`pattern_confidence_threshold` (float, default: 0.3)¶

Minimum confidence for applying learned patterns.

Example:

from attune import AttuneConfig

config = AttuneConfig(pattern_confidence_threshold=0.80)

Configuration Methods¶

`load_config()`¶

Load configuration from file or environment.

from attune import load_config

# Load from YAML file
config = load_config(filepath="attune.config.yml")

# Load from JSON file
config = load_config(filepath="attune.config.json")

# Load from environment variables
config = load_config(use_env=True)

# Load from file with environment overrides
config = load_config(filepath="attune.config.yml", use_env=True)

`to_yaml()` / `to_json()`¶

Save configuration to file.

from attune import AttuneConfig

config = AttuneConfig(user_id="user_123")

# Save as YAML
config.to_yaml("attune.config.yml")

# Save as JSON
config.to_json("attune.config.json")

`validate()`¶

Validate configuration values.

from attune import AttuneConfig

config = AttuneConfig(user_id="user_123")

try:
    config.validate()
    print("Configuration valid")
except ValueError as e:
    print(f"Configuration invalid: {e}")

Configuration Patterns¶

Development Configuration¶

# attune.dev.yml
user_id: "dev_user"
confidence_threshold: 0.70
persistence_enabled: true
persistence_backend: "sqlite"
persistence_path: "./attune_data"
metrics_enabled: true

Production Configuration¶

# attune.prod.yml
user_id: "prod_system"
confidence_threshold: 0.80
persistence_enabled: true
persistence_backend: "postgresql"
persistence_path: "postgresql://user:pass@db.example.com/attune"
metrics_enabled: true
metrics_path: "postgresql://user:pass@db.example.com/metrics"

# Stricter trust and pattern thresholds
trust_erosion_rate: 0.15
pattern_confidence_threshold: 0.85

Testing Configuration¶

from attune import AttuneConfig

# For unit tests
config = AttuneConfig(
    user_id="test_user",
    persistence_enabled=False,  # Don't save during tests
    metrics_enabled=False,      # Don't collect metrics during tests
)

Environment Variable Reference¶

All configuration options can be set via environment variables with the ATTUNE_ prefix (EMPATHY_ prefix is also accepted for backward compatibility):

# Core settings
export ATTUNE_USER_ID="user_123"
export ATTUNE_CONFIDENCE_THRESHOLD=0.75

# Trust settings
export ATTUNE_TRUST_BUILDING_RATE=0.05
export ATTUNE_TRUST_EROSION_RATE=0.10

# Persistence settings
export ATTUNE_PERSISTENCE_ENABLED=true
export ATTUNE_PERSISTENCE_BACKEND=sqlite
export ATTUNE_PERSISTENCE_PATH=./attune_data

# Metrics settings
export ATTUNE_METRICS_ENABLED=true
export ATTUNE_METRICS_PATH=./metrics.db

# Pattern library settings
export ATTUNE_PATTERN_LIBRARY_ENABLED=true
export ATTUNE_PATTERN_SHARING=true
export ATTUNE_PATTERN_CONFIDENCE_THRESHOLD=0.30

Configuration¶

Overview¶

Quick Start¶

Direct Configuration¶

YAML Configuration¶

Environment Variables¶

Class Reference¶

__post_init__() ¶

__repr__() ¶

from_dict(data) classmethod ¶

from_env(prefix='ATTUNE_') classmethod ¶

from_file(filepath=None) classmethod ¶

from_json(filepath) classmethod ¶

from_yaml(filepath) classmethod ¶

merge(other) ¶

to_dict() ¶

to_json(filepath, indent=2) ¶

to_yaml(filepath) ¶

update(**kwargs) ¶

validate() ¶

Configuration Options¶

Core Settings¶

user_id (str, default: "default_user")¶

confidence_threshold (float, default: 0.75)¶

Trust Settings¶

trust_building_rate (float, default: 0.05)¶

trust_erosion_rate (float, default: 0.10)¶

Persistence Settings¶

persistence_enabled (bool, default: True)¶

persistence_backend (str, default: "sqlite")¶

persistence_path (str, default: "./attune_data")¶

Metrics Settings¶

metrics_enabled (bool, default: True)¶

metrics_path (str, default: "./metrics.db")¶

Pattern Library Settings¶

pattern_library_enabled (bool, default: True)¶

pattern_sharing (bool, default: True)¶

pattern_confidence_threshold (float, default: 0.3)¶

Configuration Methods¶

load_config()¶

to_yaml() / to_json()¶

validate()¶

Configuration Patterns¶

Development Configuration¶

Production Configuration¶

Testing Configuration¶

Environment Variable Reference¶

See Also¶

`__post_init__()` ¶

`repr()` ¶

`from_dict(data)` `classmethod` ¶

`from_env(prefix='ATTUNE_')` `classmethod` ¶

`from_file(filepath=None)` `classmethod` ¶

`from_json(filepath)` `classmethod` ¶

`from_yaml(filepath)` `classmethod` ¶

`merge(other)` ¶

`to_dict()` ¶

`to_json(filepath, indent=2)` ¶

`to_yaml(filepath)` ¶

`update(**kwargs)` ¶

`validate()` ¶

`user_id` (str, default: "default_user")¶

`confidence_threshold` (float, default: 0.75)¶

`trust_building_rate` (float, default: 0.05)¶

`trust_erosion_rate` (float, default: 0.10)¶

`persistence_enabled` (bool, default: True)¶

`persistence_backend` (str, default: "sqlite")¶

`persistence_path` (str, default: "./attune_data")¶

`metrics_enabled` (bool, default: True)¶

`metrics_path` (str, default: "./metrics.db")¶

`pattern_library_enabled` (bool, default: True)¶

`pattern_sharing` (bool, default: True)¶

`pattern_confidence_threshold` (float, default: 0.3)¶

`load_config()`¶

`to_yaml()` / `to_json()`¶

`validate()`¶