Error in user YAML: (<unknown>): mapping values are not allowed in this context at line 1 column 51

---
description: Empathy Framework - Quick Start Guide: **Get up and running in 5 minutes** --- ## What is Empathy Framework? Empathy Framework is a five-level maturity model fo
---

Empathy Framework - Quick Start Guide

Get up and running in 5 minutes

What is Empathy Framework?

Empathy Framework is a five-level maturity model for AI-human collaboration:

Level 1: Reactive - Respond when asked
Level 2: Guided - Collaborate with clarifying questions
Level 3: Proactive - Act before being asked
Level 4: Anticipatory - Predict future needs
Level 5: Systems - Build structures that prevent entire problem classes

Installation

Prerequisites

Python 3.9+ (3.10+ recommended)
API Key for your LLM provider (optional for core framework)

Install from Source

# Clone the repository (or download your licensed copy)
git clone https://github.com/Deep-Study-AI/empathy.git
cd empathy

# Install with pip
pip install -e .

# Or install with all optional dependencies
pip install -e ".[dev,examples]"

Verify Installation

python -c "from empathy_os import EmpathyOS; print('✓ Empathy Framework installed')"

Quick Start Examples

Example 1: Simplest Usage (No Custom Code)

The easiest way to use Empathy Framework - just interact with it!

import asyncio
import os
from empathy_llm_toolkit.core import EmpathyLLM

async def quick_demo():
    # Create an instance (uses Claude by default)
    llm = EmpathyLLM(
        provider="anthropic",  # or "openai", "local"
        target_level=4,        # Level 4 Anticipatory
        api_key=os.getenv("ANTHROPIC_API_KEY")
    )

    # Just interact - it handles the rest!
    response = await llm.interact(
        user_id="me",
        user_input="Help me build a web API"
    )

    print(f"Assistant: {response['content']}")
    print(f"Level Used: {response['level_used']}")

# Run it
asyncio.run(quick_demo())

Set your API key first:

export ANTHROPIC_API_KEY="your-key-here"
# or
export OPENAI_API_KEY="your-key-here"

Run the example:

python examples/simple_usage.py

Example 2: Understanding the Five Levels

See all five empathy levels in action:

from empathy_os import (
    EmpathyOS,
    Level1Reactive,
    Level2Guided,
    Level3Proactive,
    Level4Anticipatory,
    Level5Systems
)

# Initialize EmpathyOS
empathy = EmpathyOS(
    user_id="quickstart_user",
    target_level=4,
    confidence_threshold=0.75
)

# Level 1: Reactive (waits for request)
level1 = Level1Reactive()
response = level1.respond({"request": "status"})
print(f"Level 1: {response['action']}")  # Provides status

# Level 2: Guided (asks clarifying questions)
level2 = Level2Guided()
response = level2.respond({"request": "improve system"})
print(f"Level 2: {response['action']}")  # Asks for clarification

# Level 3: Proactive (acts before being asked)
level3 = Level3Proactive()
response = level3.respond({"observed_need": "failing_tests"})
print(f"Level 3: {response['action']}")  # Fixes tests proactively

# Level 4: Anticipatory (predicts future needs)
level4 = Level4Anticipatory()
response = level4.respond({
    "current_state": {"compliance": 0.7},
    "trajectory": "declining"
})
print(f"Level 4: {response['predicted_needs']}")  # Predicts problems

# Level 5: Systems (prevents problem classes)
level5 = Level5Systems()
response = level5.respond({
    "problem_class": "documentation_burden",
    "instances": 18
})
print(f"Level 5: {response['system_created']}")  # Builds structure

Run the full demo:

python examples/quickstart.py

Example 3: Multiple LLM Providers

Switch between different AI providers based on your needs:

from empathy_llm_toolkit.core import EmpathyLLM

# Use Claude for complex reasoning (Level 4 Anticipatory)
claude = EmpathyLLM(
    provider="anthropic",
    target_level=4,
    api_key=os.getenv("ANTHROPIC_API_KEY")
)

# Use GPT-4 for fast responses (Level 3 Proactive)
gpt4 = EmpathyLLM(
    provider="openai",
    target_level=3,
    api_key=os.getenv("OPENAI_API_KEY")
)

# Use local Ollama for privacy (Level 2 Guided)
local = EmpathyLLM(
    provider="local",
    target_level=2,
    model="llama2",
    endpoint="http://localhost:11434"
)

Run the multi-LLM demo:

python examples/multi_llm_usage.py

Core Concepts

1. Empathy Levels

Each level builds on the previous:

Level	Name	Description	Use Case
1	Reactive	Responds when asked	Basic Q&A, help requests
2	Guided	Asks clarifying questions	Ambiguous requirements
3	Proactive	Acts before being asked	Automated maintenance
4	Anticipatory	Predicts future needs	Prevent problems
5	Systems	Builds prevention structures	Scale solutions

2. Trust Building

The framework tracks trust between human and AI:

empathy = EmpathyOS(user_id="developer_123")

# Trust starts at 0.5 (neutral)
print(empathy.collaboration_state.trust_level)  # 0.5

# Successful interactions increase trust
empathy.collaboration_state.update_trust("success")
print(empathy.collaboration_state.trust_level)  # 0.6

# Higher trust = more proactive behavior

3. Pattern Library (Level 5)

AI agents share patterns for better collaboration:

from empathy_os import PatternLibrary, Pattern

library = PatternLibrary()

# Agent 1 contributes a pattern
pattern = Pattern(
    id="pat_001",
    agent_id="agent_1",
    pattern_type="sequential",
    name="Post-deployment docs",
    description="Users need help after deployments",
    confidence=0.85
)
library.contribute_pattern("agent_1", pattern)

# Agent 2 queries for relevant patterns
matches = library.query_patterns(
    agent_id="agent_2",
    context={"recent_event": "deployment"},
    min_confidence=0.7
)

# Use the pattern and record outcome
library.record_pattern_outcome("pat_001", success=True)

Project Structure

empathy-framework/
├── src/empathy_os/          # Core framework
│   ├── core.py              # EmpathyOS main class
│   ├── levels.py            # Five empathy levels
│   ├── pattern_library.py   # Pattern sharing (Level 5)
│   ├── feedback_loops.py    # System dynamics
│   └── plugins/             # Plugin architecture
├── empathy_llm_toolkit/     # LLM integration layer
│   ├── core.py              # EmpathyLLM wrapper
│   └── providers.py         # Claude, GPT-4, Ollama, etc.
├── examples/                # Runnable examples
│   ├── simple_usage.py      # Easiest starting point
│   ├── quickstart.py        # Comprehensive demo
│   └── multi_llm_usage.py   # Multiple providers
├── coach_wizards/           # Software development wizards
├── empathy_software_plugin/ # Software domain plugin
└── empathy_healthcare_plugin/ # Healthcare domain plugin

Common Use Cases

1. Code Review Assistant

from empathy_llm_toolkit.core import EmpathyLLM

llm = EmpathyLLM(provider="anthropic", target_level=3)

response = await llm.interact(
    user_id="developer",
    user_input="Review this code for issues",
    context={"code": your_code_here}
)

2. Bug Prediction

from empathy_llm_toolkit.core import EmpathyLLM

llm = EmpathyLLM(provider="anthropic", target_level=4)

response = await llm.interact(
    user_id="qa_team",
    user_input="Predict bugs in next release",
    context={"codebase": recent_changes}
)

3. Documentation Generation

from empathy_llm_toolkit.core import EmpathyLLM

llm = EmpathyLLM(provider="openai", target_level=2)

response = await llm.interact(
    user_id="tech_writer",
    user_input="Generate API documentation",
    context={"code": api_endpoints}
)

Configuration

Environment Variables

# LLM Provider API Keys
export ANTHROPIC_API_KEY="your-anthropic-key"
export OPENAI_API_KEY="your-openai-key"

# Framework Settings (optional)
export EMPATHY_TARGET_LEVEL=4
export EMPATHY_CONFIDENCE_THRESHOLD=0.75
export EMPATHY_LOG_LEVEL=INFO

Configuration File

Create .env in your project root:

# LLM Provider
ANTHROPIC_API_KEY=your-key-here
OPENAI_API_KEY=your-key-here

# Framework Settings
EMPATHY_TARGET_LEVEL=4
EMPATHY_CONFIDENCE_THRESHOLD=0.75
EMPATHY_LOG_LEVEL=INFO

Troubleshooting

Issue: Import Error

Error:

ImportError: No module named 'empathy_os'

Solution:

# Make sure you installed the package
pip install -e .

# Or add to PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:/path/to/empathy-framework"

Issue: API Key Not Found

Error:

ValueError: API key required for Anthropic provider

Solution:

# Set your API key
export ANTHROPIC_API_KEY="your-key-here"

# Or pass it directly
llm = EmpathyLLM(
    provider="anthropic",
    api_key="your-key-here"
)

Issue: Module Dependencies

Error:

ModuleNotFoundError: No module named 'langchain'

Solution:

# Install with all dependencies
pip install -e ".[dev,examples]"

# Or install specific dependencies
pip install langchain langchain-core langgraph

Next Steps

1. Explore Examples

# Run all examples
python examples/simple_usage.py
python examples/quickstart.py
python examples/multi_llm_usage.py
python examples/security_demo.py
python examples/performance_demo.py

2. Read Documentation

README.md - Full project overview
docs/ARCHITECTURE.md - Framework architecture
docs/LEVELS.md - Detailed level explanations
CONTRIBUTING.md - Contributing guidelines

3. Try Advanced Features

Build custom wizards
Create domain-specific plugins
Integrate with your CI/CD pipeline
Use pattern library for AI-AI cooperation

4. Join the Community

GitHub: https://github.com/Deep-Study-AI/empathy
Issues: Report bugs or request features
Discussions: Ask questions and share patterns

Getting Help

Documentation

Full documentation: docs/ directory
API reference: docs/API.md
Examples: examples/ directory

Support

Community Support (Free tier): GitHub Issues
Email Support (Commercial license): patrick.roebuck1955@gmail.com
Documentation: https://github.com/Smart-AI-Memory/empathy

License

Core Framework: Apache 2.0 (open source)
Complete Bundle: Commercial license available
Pricing: $99/developer/year (Free for students, educators, small teams ≤5 employees)

See LICENSE-COMMERCIAL.md for details.

Quick Reference

Installation Commands

pip install -e .                    # Core framework
pip install -e ".[dev]"            # With dev tools
pip install -e ".[examples]"       # With example dependencies
pip install -e ".[dev,examples]"   # Everything

Example Commands

python examples/simple_usage.py      # Easiest start
python examples/quickstart.py        # Full demo
python examples/multi_llm_usage.py   # Multiple providers

Import Statements

# Core framework
from empathy_os import EmpathyOS, Level1Reactive, Level2Guided

# LLM toolkit (easiest)
from empathy_llm_toolkit.core import EmpathyLLM

# Advanced features
from empathy_os import PatternLibrary, FeedbackLoopDetector

Ready to get started? Run your first example:

export ANTHROPIC_API_KEY="your-key"
python examples/simple_usage.py

Questions? Check the full documentation or file an issue.

Uh oh!

FilesExpand file tree

quickstart.md

Latest commit

History

quickstart.md

File metadata and controls

Empathy Framework - Quick Start Guide

What is Empathy Framework?

Installation

Prerequisites

Install from Source

Verify Installation

Quick Start Examples

Example 1: Simplest Usage (No Custom Code)

Example 2: Understanding the Five Levels

Example 3: Multiple LLM Providers

Core Concepts

1. Empathy Levels

2. Trust Building

3. Pattern Library (Level 5)

Project Structure

Common Use Cases

1. Code Review Assistant

2. Bug Prediction

3. Documentation Generation

Configuration

Environment Variables

Configuration File

Troubleshooting

Issue: Import Error

Issue: API Key Not Found

Issue: Module Dependencies

Next Steps

1. Explore Examples

2. Read Documentation

3. Try Advanced Features

4. Join the Community

Getting Help

Documentation

Support

License

Quick Reference

Installation Commands

Example Commands

Import Statements