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 for EmpathyOS instance

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

`repr()` ¶

String representation

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

Load configuration from environment variables

Environment variables should be prefixed with EMPATHY_ and match config field names in uppercase.

Example

EMPATHY_USER_ID=alice EMPATHY_TARGET_LEVEL=4 EMPATHY_CONFIDENCE_THRESHOLD=0.8

Parameters:

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

Returns:

Type	Description
`EmpathyConfig`	EmpathyConfig instance

Example

os.environ["EMPATHY_USER_ID"] = "alice" config = EmpathyConfig.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. empathy.config.yml 5. empathy.config.yaml 6. .empathy.json 7. empathy.config.json

Parameters:

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

Returns:

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

Example

config = EmpathyConfig.from_file() # Auto-detect config = EmpathyConfig.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
`EmpathyConfig`	EmpathyConfig instance

Example

config = EmpathyConfig.from_json("empathy.config.json") empathy = EmpathyOS(config=config)

`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
`EmpathyConfig`	EmpathyConfig instance

Raises:

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

Example

config = EmpathyConfig.from_yaml("empathy.config.yml") empathy = EmpathyOS(config=config)

`merge(other)` ¶

Merge with another configuration (other takes precedence)

Parameters:

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

Returns:

Type	Description
`EmpathyConfig`	New merged configuration

Example

base = EmpathyConfig(user_id="alice") override = EmpathyConfig(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 = EmpathyConfig(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 = EmpathyConfig(user_id="alice", target_level=4) config.to_yaml("my-config.yml")

`update(**kwargs)` ¶

Update configuration fields

Parameters:

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

Example

config = EmpathyConfig() 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, 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

Configuration¶

Overview¶

Quick Start¶

Direct Configuration¶

YAML Configuration¶

Environment Variables¶

Class Reference¶

__repr__() ¶

from_env(prefix='EMPATHY_') 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, required)¶

target_level (int, default: 4)¶

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: ".empathy")¶

Metrics Settings¶

metrics_enabled (bool, default: True)¶

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

Pattern Library Settings¶

pattern_library_enabled (bool, default: True)¶

pattern_sharing (bool, default: False)¶

pattern_confidence_threshold (float, default: 0.70)¶

Configuration Methods¶

load_config()¶

to_yaml() / to_json()¶

validate()¶

Configuration Patterns¶

Development Configuration¶

Production Configuration¶

Testing Configuration¶

Environment Variable Reference¶

See Also¶

`repr()` ¶

`from_env(prefix='EMPATHY_')` `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, required)¶

`target_level` (int, default: 4)¶

`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: ".empathy")¶

`metrics_enabled` (bool, default: True)¶

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

`pattern_library_enabled` (bool, default: True)¶

`pattern_sharing` (bool, default: False)¶

`pattern_confidence_threshold` (float, default: 0.70)¶

`load_config()`¶

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

`validate()`¶