Configuration

Configuration management for the Empathy Framework. Configure via direct instantiation, YAML/JSON files, or environment variables.

Overview

The configuration system provides flexible options for customizing Empathy Framework behavior:

• Direct instantiation: Pass parameters to EmpathyConfig() or EmpathyOS()
• YAML/JSON files: Load from empathy.config.yml or empathy.config.json
• Environment variables: Use EMPATHY_* prefixed variables
• Validation: Automatic validation on load with helpful error messages

Quick Start

Direct Configuration

from empathy_os import EmpathyConfig, EmpathyOS

# Option 1: Configure EmpathyOS directly
empathy = EmpathyOS(
    user_id="user_123",
    target_level=4,
    confidence_threshold=0.75,
    persistence_enabled=True
)

# Option 2: Use EmpathyConfig object
config = EmpathyConfig(
    user_id="user_123",
    target_level=4,
    confidence_threshold=0.75
)
empathy = EmpathyOS.from_config(config)

YAML Configuration

Create empathy.config.yml:

user_id: "user_123"
target_level: 4
confidence_threshold: 0.75
persistence_enabled: true
persistence_backend: "sqlite"
persistence_path: ".empathy"
metrics_enabled: true

Load it:

from empathy_os import load_config, EmpathyOS

config = load_config(filepath="empathy.config.yml")
empathy = EmpathyOS.from_config(config)

Environment Variables

export EMPATHY_USER_ID="user_123"
export EMPATHY_TARGET_LEVEL=4
export EMPATHY_CONFIDENCE_THRESHOLD=0.75

from empathy_os import load_config

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

Class Reference

Configuration Options

Core Settings

user_id (str, required)

Unique identifier for the user or system.

Example:

config = EmpathyConfig(user_id="user_123")

target_level (int, default: 4)

Target empathy level (1-5). System will progress toward this level as trust builds.

• 1: Reactive (basic Q&A)
• 2: Guided (asks questions)
• 3: Proactive (suggests improvements)
• 4: Anticipatory (predicts problems) ⭐ Recommended
• 5: Transformative (reshapes workflows)

Example:

config = EmpathyConfig(target_level=4)  # Aim for Level 4

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:

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

# Aggressive: More predictions, accept lower confidence
config = EmpathyConfig(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:

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

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

trust_erosion_rate (float, default: 0.10)

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

Example:

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

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

Persistence Settings

persistence_enabled (bool, default: True)

Enable saving patterns, metrics, and state to disk.

Example:

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

# Testing: Disable persistence
config = EmpathyConfig(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:

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

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

persistence_path (str, default: ".empathy")

Path for storing persistence data.

Example:

# Default location
config = EmpathyConfig(persistence_path=".empathy")

# Custom location
config = EmpathyConfig(persistence_path="/var/lib/empathy")

Metrics Settings

metrics_enabled (bool, default: True)

Enable metrics collection for monitoring and analytics.

Example:

config = EmpathyConfig(metrics_enabled=True)

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

Path for storing metrics data.

Example:

config = EmpathyConfig(metrics_path="/var/lib/empathy/metrics.db")

Pattern Library Settings

pattern_library_enabled (bool, default: True)

Enable pattern discovery and learning.

Example:

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

pattern_sharing (bool, default: False)

Enable pattern sharing across multiple agents (multi-agent coordination).

Example:

# Enable for multi-agent teams
config = EmpathyConfig(
    pattern_sharing=True,
    pattern_library_path="shared_patterns.db"
)

pattern_confidence_threshold (float, default: 0.70)

Minimum confidence for applying learned patterns.

Example:

config = EmpathyConfig(pattern_confidence_threshold=0.80)

Configuration Methods

load_config()

Load configuration from file or environment.

from empathy_os import load_config

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

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

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

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

to_yaml() / to_json()

Save configuration to file.

config = EmpathyConfig(user_id="user_123", target_level=4)

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

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

validate()

Validate configuration values.

config = EmpathyConfig(user_id="user_123", target_level=4)

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

Configuration Patterns

Development Configuration

# empathy.dev.yml
user_id: "dev_user"
target_level: 4
confidence_threshold: 0.70
persistence_enabled: true
persistence_backend: "sqlite"
persistence_path: ".empathy"
metrics_enabled: true

Production Configuration

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

# Security settings
trust_erosion_rate: 0.15  # Stricter trust management
pattern_confidence_threshold: 0.85  # Higher quality patterns

Testing Configuration

# For unit tests
config = EmpathyConfig(
    user_id="test_user",
    target_level=4,
    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 EMPATHY_ prefix:

# Core settings
export EMPATHY_USER_ID="user_123"
export EMPATHY_TARGET_LEVEL=4
export EMPATHY_CONFIDENCE_THRESHOLD=0.75

# Trust settings
export EMPATHY_TRUST_BUILDING_RATE=0.05
export EMPATHY_TRUST_EROSION_RATE=0.10

# Persistence settings
export EMPATHY_PERSISTENCE_ENABLED=true
export EMPATHY_PERSISTENCE_BACKEND=sqlite
export EMPATHY_PERSISTENCE_PATH=.empathy

# Metrics settings
export EMPATHY_METRICS_ENABLED=true
export EMPATHY_METRICS_PATH=.empathy/metrics.db

# Pattern library settings
export EMPATHY_PATTERN_LIBRARY_ENABLED=true
export EMPATHY_PATTERN_SHARING=false
export EMPATHY_PATTERN_CONFIDENCE_THRESHOLD=0.70

See Also

• EmpathyOS API
• Quick Start Guide
• Configuration Examples