description: EmpathyOS API reference: The main entry point for the Attune AI. `EmpathyOS` orchestrates empathy level progression,¶

EmpathyOS¶

The main entry point for the Attune AI. EmpathyOS orchestrates empathy level progression, trust management, and interaction handling.

Overview¶

EmpathyOS is the primary class you'll interact with when building empathy-aware AI systems. It handles:

Level Progression: Automatically advances through empathy levels 1-5 based on trust
Trust Management: Tracks collaboration trust with built-in erosion and building rates
Interaction Logic: Routes requests through appropriate empathy level handlers
Pattern Learning: Discovers and applies patterns for improved responses
State Persistence: Saves and restores user collaboration states

Basic Usage¶

from attune import EmpathyOS

# Initialize with Level 4 target
empathy = EmpathyOS(
    user_id="user_123",
    target_level=4,
    confidence_threshold=0.75,
    persistence_enabled=True
)

# Single interaction
response = empathy.interact(
    user_id="user_123",
    user_input="How do I fix this bug?",
    context={"task": "debugging"}
)

print(response.response)  # AI response
print(response.level)     # Current empathy level
print(response.confidence)  # Confidence score

Class Reference¶

Bases: InteractionMixin, EmpathyLevelsMixin, EmpathyHelpersMixin, MemoryInterfaceMixin, SharedLibraryMixin, FeedbackManagementMixin, ShortTermMemoryMixin

Empathy Operating System for AI-Human Collaboration.

Integrates: - 5-level Empathy Maturity Model - Systems Thinking (feedback loops, emergence, leverage points) - Tactical Empathy (Voss) - Emotional Intelligence (Goleman) - Clear Thinking (Naval)

Goal: Enable AI to operate at Levels 3-4 (Proactive/Anticipatory)

Example

Basic usage with empathy levels::

from attune import EmpathyOS

# Create instance targeting Level 4 (Anticipatory)
empathy = EmpathyOS(user_id="developer_123", target_level=4)

# Level 1 - Reactive response
response = empathy.level_1_reactive(
    user_input="How do I optimize database queries?",
    context={"domain": "software"}
)

# Level 2 - Guided with follow-up questions
response = empathy.level_2_guided(
    user_input="I need help with my code",
    context={"task": "debugging"},
    history=[]
)

Memory operations::

# Stash working data (short-term)
empathy.stash("current_task", {"status": "debugging"})

# Retrieve later
task = empathy.retrieve("current_task")

# Persist patterns (long-term)
result = empathy.persist_pattern(
    content="Query optimization technique",
    pattern_type="technique"
)

# Recall patterns
pattern = empathy.recall_pattern(result["pattern_id"])

Methods are organized across mixins for maintainability:

InteractionMixin: interact(), record_success(), get/reset_collaboration_state()
EmpathyLevelsMixin: level_1_reactive() through level_5_systems()
EmpathyHelpersMixin: Private helper methods for empathy levels
MemoryInterfaceMixin: memory property, persist_pattern(), recall_pattern(), stash(), retrieve()
SharedLibraryMixin: async context manager, contribute_pattern(), query_patterns()
FeedbackManagementMixin: monitor_feedback_loops()
ShortTermMemoryMixin: Redis coordination, signals, pattern staging

`init(user_id, target_level=3, confidence_threshold=0.75, logger=None, shared_library=None, short_term_memory=None, access_tier=AccessTier.CONTRIBUTOR, persistence_enabled=True)` ¶

Initialize EmpathyOS

Parameters:

Name	Type	Description	Default
`user_id`	`str`	Unique identifier for user/team	required
`target_level`	`int`	Target empathy level (1-5), default 3 (Proactive)	`3`
`confidence_threshold`	`float`	Minimum confidence for anticipatory actions (0.0-1.0)	`0.75`
`logger`	`Logger \| None`	Optional logger instance for structured logging	`None`
`shared_library`	`PatternLibrary \| None`	Optional shared PatternLibrary for multi-agent collaboration. When provided, enables agents to share discovered patterns, supporting Level 5 (Systems Empathy) distributed memory networks.	`None`
`short_term_memory`	`MemoryBackend \| None`	Optional MemoryBackend for fast, TTL-based working memory. Accepts any backend (FileSessionMemory, Redis, etc.).	`None`
`access_tier`	`AccessTier`	Access tier for this agent (Observer, Contributor, Validator, Steward). Determines what operations the agent can perform on shared memory.	`CONTRIBUTOR`
`persistence_enabled`	`bool`	Whether to enable pattern/state persistence (default: True)	`True`

Key Methods¶

`init()`¶

Initialize a new EmpathyOS instance with configuration.

Parameters: - user_id (str): Unique identifier for the user - target_level (int): Target empathy level (1-5, default: 4) - confidence_threshold (float): Minimum confidence for level advancement (0.0-1.0, default: 0.75) - persistence_enabled (bool): Enable state/pattern persistence (default: True) - trust_building_rate (float): Rate of trust increase on success (default: 0.05) - trust_erosion_rate (float): Rate of trust decrease on failure (default: 0.10)

`interact()`¶

Process a user interaction and return an empathy-aware response.

Parameters: - user_id (str): User identifier - user_input (str): User's input message - context (dict): Additional context for the interaction

Returns: - EmpathyResponse: Response object with message, level, confidence, and predictions

Example:

response = empathy.interact(
    user_id="user_123",
    user_input="I'm deploying to production",
    context={"environment": "production", "time": "friday_afternoon"}
)

if response.level >= 4 and response.predictions:
    print("⚠️  Predictions:")
    for prediction in response.predictions:
        print(f"  • {prediction}")

`record_success()` / `record_failure()`¶

Provide feedback to improve trust tracking and pattern learning.

Parameters: - success (bool): Whether the interaction was successful

Example:

response = empathy.interact(user_id="user_123", user_input="Help me debug this")

# User found the response helpful
empathy.record_success(success=True)
print(f"Trust level: {empathy.get_trust_level():.0%}")

`save_state()` / `load_state()`¶

Persist and restore user collaboration state.

Example:

# Save state after session
empathy.save_state(user_id="user_123", filepath=".empathy/user_123.json")

# Restore state in next session
empathy.load_state(user_id="user_123", filepath=".empathy/user_123.json")

Empathy Levels¶

Level 1: Reactive¶

Basic Q&A responses without proactivity.

Trust Required: 0% - 20%

Characteristics: - Answers direct questions only - No suggestions or predictions - Minimal context awareness

Level 2: Guided¶

Asks clarifying questions to understand intent.

Trust Required: 20% - 40%

Characteristics: - Clarifying questions - Better context understanding - More thorough responses

Level 3: Proactive¶

Suggests improvements and best practices.

Trust Required: 40% - 60%

Characteristics: - Proactive suggestions - Best practice recommendations - Code improvements

Level 4: Anticipatory 🎯¶

Predicts problems before they occur (30-90 day horizon).

Trust Required: 60% - 80%

Characteristics: - Problem prediction - Risk assessment - Anticipatory guidance - "What if" scenarios

Example:

response = empathy.interact(
    user_id="user_123",
    user_input="I'm adding this new API endpoint",
    context={"api_version": "v2", "breaking_change": False}
)

# Level 4 response includes predictions
if response.predictions:
    print(response.predictions)
    # ["This may conflict with v1 authentication flow",
    #  "Consider rate limiting for this endpoint",
    #  "Mobile app may need updates"]

Level 5: Transformative 🚀¶

Reshapes workflows and system architecture (90+ day horizon).

Trust Required: 80% - 100%

Characteristics: - Workflow transformation - Architectural recommendations - Long-term strategic guidance - Cross-system optimization

Trust Management¶

Trust level affects which empathy level is active:

empathy = EmpathyOS(user_id="user_123", target_level=4)

# Start at Level 1 (trust = 0%)
print(empathy.get_current_level())  # 1

# Build trust through successful interactions
for _ in range(10):
    response = empathy.interact(user_id="user_123", user_input="...")
    empathy.record_success(success=True)

print(empathy.get_current_level())  # 3 or 4 (depending on trust)
print(f"Trust: {empathy.get_trust_level():.0%}")  # ~50%

Trust Dynamics: - Starts at 0% - Increases on record_success(True) by trust_building_rate (default: +5%) - Decreases on record_failure() by trust_erosion_rate (default: -10%) - Capped at 100%

Configuration¶

See Configuration API for detailed configuration options.

description: EmpathyOS API reference: The main entry point for the Attune AI. EmpathyOS orchestrates empathy level progression,¶

EmpathyOS¶

Overview¶

Basic Usage¶

Class Reference¶

__init__(user_id, target_level=3, confidence_threshold=0.75, logger=None, shared_library=None, short_term_memory=None, access_tier=AccessTier.CONTRIBUTOR, persistence_enabled=True) ¶

Key Methods¶

__init__()¶

interact()¶

record_success() / record_failure()¶

save_state() / load_state()¶

Empathy Levels¶

Level 1: Reactive¶

Level 2: Guided¶

Level 3: Proactive¶

Level 4: Anticipatory 🎯¶

Level 5: Transformative 🚀¶

Trust Management¶

Configuration¶

See Also¶

description: EmpathyOS API reference: The main entry point for the Attune AI. `EmpathyOS` orchestrates empathy level progression,¶

`init(user_id, target_level=3, confidence_threshold=0.75, logger=None, shared_library=None, short_term_memory=None, access_tier=AccessTier.CONTRIBUTOR, persistence_enabled=True)` ¶

`init()`¶

`interact()`¶

`record_success()` / `record_failure()`¶

`save_state()` / `load_state()`¶