Empathy Framework - Frequently Asked Questions (FAQ)¶

Last Updated: December 2025 Version: 3.1.0

Table of Contents¶

General Questions
Wizards
Smart Routing and Intelligence
Technical Questions
Licensing and Pricing
Integration and Usage
Long-Term Memory
Security and Privacy
Support and Community

General Questions¶

What is the Empathy Framework?¶

The Empathy Framework is an open-source system for building AI applications that progress from simple reactive responses (Level 1) to anticipatory problem prevention (Level 4) and cross-domain systems thinking (Level 5). It wraps any LLM (Claude, GPT-4, local models) with progressive empathy levels that build trust over time.

Unlike traditional AI tools that simply answer questions, the Empathy Framework learns your patterns, predicts future needs, and prevents problems before they occur.

What makes Level 5 Systems Empathy unique?¶

Level 5 Systems Empathy is the world's first AI framework that can:

Learn patterns in one domain (e.g., healthcare handoff protocols)
Store them in long-term memory (built-in pattern storage)
Apply them cross-domain (e.g., predict software deployment failures)
Prevent failures before they happen (using trajectory analysis)

No other AI framework can transfer safety patterns across domains like this. It's the difference between a tool that finds bugs and a system that prevents entire classes of failures.

How does it differ from SonarQube, CodeClimate, or similar tools?¶

Feature	Traditional Tools	Empathy Framework
Analysis	Static rules, same for everyone	Adaptive, learns your patterns
Prediction	Find current bugs	Predict future issues 30-90 days ahead
Scope	Single domain (security OR performance)	16+ wizards across all domains
Intelligence	Pre-defined rules	LLM-powered reasoning
Learning	No learning capability	Learns from your codebase and feedback
Cost	$15-500/month per seat	Free forever (Fair Source 0.9)

Bottom line: SonarQube finds bugs you've already written. Empathy Framework predicts bugs you're about to write and prevents them.

What's the difference between Fair Source and open source?¶

The Empathy Framework uses Fair Source 0.9 license - it's fully open source, not Fair Source.

Fair Source 0.9: Completely free forever, no usage limits, commercial use allowed
Fair Source: Typically has usage limits or restrictions on commercial use

We chose Fair Source 0.9 because we want maximum adoption and community contribution. There are no hidden fees or usage caps.

Is this production-ready?¶

Yes! The Empathy Framework is production-ready and includes:

Comprehensive test suite with 80%+ coverage (2,200+ tests)
Battle-tested on real codebases
Used in production by multiple teams
Enterprise support available ($99/developer/year)
Regular security updates and patches

That said, like any software, you should: - Test thoroughly in your environment - Start with non-critical systems - Monitor performance and accuracy - Provide feedback to improve the framework

Wizards¶

What are Empathy Wizards?¶

Wizards are specialized AI assistants for specific domains and tasks. Unlike generic chatbots, each wizard has:

Domain expertise - Deep knowledge of industry patterns and regulations
Built-in security - PII scrubbing, secrets detection, audit logging
Level 4 predictions - Anticipates problems before they happen
Structured outputs - Consistent, actionable results

What wizards are available?¶

44 wizards across 3 categories:

Category	Count	Examples
Domain Wizards	16	Healthcare, Finance, Legal, Education, HR, Retail
Software Wizards	16	Debugging, Security, Performance, API, Testing, Database
AI Wizards	12	Agent Orchestration, RAG Pattern, Prompt Engineering

How do I choose the right wizard?¶

Ask yourself:

What domain am I working in? → Use a Domain Wizard (Healthcare, Finance, etc.)
What code task am I doing? → Use a Software Wizard (Debugging, Security, etc.)
Am I building an AI system? → Use an AI Wizard (Agent Orchestration, RAG, etc.)

What inputs do wizards need?¶

All wizards accept a consistent input structure:

result = await wizard.process(
    user_input="Your question or content",  # Required
    user_id="your_id",                       # Required
    context={}                               # Optional context
)

Domain Wizards: Text content to analyze (documents, emails, records)

Software Wizards: Code to analyze (with file_path and language)

AI Wizards: System description or architecture questions

What outputs do wizards return?¶

All wizards return structured results:

{
    "success": True,
    "output": "Human-readable summary",
    "analysis": {
        "issues": [...],         # Current problems found
        "predictions": [...],    # Future problems predicted
        "recommendations": [...] # Suggested actions
    }
}

Can I use wizards without an API key?¶

Software Wizards: Yes - rule-based analysis runs locally without LLM

Domain & AI Wizards: Require LLM API key (Anthropic or OpenAI)

Local Models: All wizards work with Ollama for completely offline use

How do I test wizards?¶

# Run the wizard test suite
python tests/test_wizard_outputs.py

# Output saved to tests/wizard_outputs/
# - Individual JSON files per wizard
# - Summary report in markdown

Which wizards are most reliable?¶

Most tested (high confidence): - Healthcare Wizard - Extensively validated for HIPAA compliance - Security Wizard - Validated against OWASP patterns - Debugging Wizard - Tested with common bug patterns

Newer (improving): - Agent Orchestration Wizard - AI Performance Wizard - RAG Pattern Wizard

All wizards undergo continuous testing. Run pytest tests/ to see current status.

How do I create a custom wizard?¶

from empathy_llm_toolkit.wizards import BaseWizard, WizardConfig

class MyWizard(BaseWizard):
    def __init__(self, llm):
        config = WizardConfig(
            name="my_industry",
            domain="custom",
            enable_security=True
        )
        super().__init__(llm, config)

    async def process(self, user_input: str, user_id: str):
        # Your custom logic here
        return await self.llm.interact(user_id, user_input)

See Creating Custom Wizards for full documentation.

Smart Routing and Intelligence¶

What is the Smart Router?¶

The Smart Router automatically dispatches your natural language requests to the appropriate wizard(s). Instead of knowing which wizard to use, just describe what you need:

from empathy_os.routing import SmartRouter

router = SmartRouter()
decision = router.route_sync("Fix the security issue in auth.py")
# decision.primary_wizard = "security-audit"
# decision.secondary_wizards = ["code-review"]

How it works: 1. Uses LLM classification (Haiku tier) to understand your request 2. Falls back to keyword matching if no API key is set 3. Suggests secondary wizards for comprehensive analysis 4. Provides confidence scores for routing decisions

What is the Memory Graph?¶

The Memory Graph is a knowledge base that connects findings across all wizards. When one wizard finds a bug, other wizards can see related issues, past fixes, and patterns.

from empathy_os.memory import MemoryGraph, EdgeType

graph = MemoryGraph()

# Find similar bugs from past sessions
similar = graph.find_similar({"name": "Null reference error"})

# Traverse relationships
bug = graph.get_node(bug_id)
fixes = graph.find_related(bug_id, edge_types=[EdgeType.FIXED_BY])

Benefits: - Cross-session learning - wizards get smarter over time - Relationship tracking - bugs linked to fixes, vulnerabilities to patches - Pattern recognition - find similar issues across your codebase

What is Auto-Chaining?¶

Auto-Chaining allows wizards to automatically trigger related wizards based on their findings. For example, when Security Audit finds high-severity issues, it can automatically trigger Dependency Check.

Configure in .empathy/wizard_chains.yaml:

chains:
  security-audit:
    triggers:
      - condition: "high_severity_count > 0"
        next: dependency-check
        approval_required: false

Pre-built templates: - full-security-review: security-audit → dependency-check → code-review - pre-release: test-gen → security-audit → release-prep - code-quality: code-review → perf-audit → doc-gen - bug-fix-pipeline: bug-predict → code-review → test-gen

What is the Prompt Engineering Wizard?¶

The Prompt Engineering Wizard helps you craft better prompts for any AI task. It can analyze existing prompts, generate optimized ones, and reduce token costs.

from coach_wizards import PromptEngineeringWizard

wizard = PromptEngineeringWizard()

# Analyze a prompt
analysis = wizard.analyze_prompt("Fix this bug")
# analysis.overall_score = 0.13 (poor)
# analysis.issues = ["Missing role", "No output format"]

# Generate an optimized prompt
prompt = wizard.generate_prompt(
    task="Review code for security",
    role="a security engineer",
    output_format="JSON with severity"
)

# Reduce token costs
result = wizard.optimize_tokens(verbose_prompt)
# result.token_reduction = 0.20 (20% savings)

Technical Questions¶

What programming languages are supported?¶

The framework core is written in Python and supports analyzing code in:

Fully Supported: - Python - JavaScript/TypeScript - Java - Go - Rust

Partial Support: - C/C++ - Ruby - PHP - Swift - Kotlin

The analysis quality depends on the specific wizard and the LLM you're using. Claude 3.5 Sonnet and GPT-4 Turbo work best for multi-language support.

Which LLM providers are supported?¶

Official Support: - Anthropic (Claude) - Recommended, best results with prompt caching - OpenAI (GPT-4, GPT-3.5 Turbo) - Excellent quality, wider availability - Local Models (Ollama, LM Studio) - Privacy-first, free to run

Coming Soon: - Google (Gemini) - Cohere - Together AI - Custom endpoints

The framework is provider-agnostic - you can switch between providers without changing your code.

Do I need an API key?¶

Yes, you need an API key for the LLM provider you choose:

Anthropic (Recommended):

export ANTHROPIC_API_KEY=sk-ant-your-key-here

OpenAI:

export OPENAI_API_KEY=sk-your-key-here

Local Models: No API key needed - runs entirely on your machine using Ollama or LM Studio.

How much does it cost to run?¶

Framework Cost: $0 (Fair Source 0.9 open source)

LLM API Costs (approximate):

Anthropic Claude 3.5 Sonnet (Recommended): - Input: $3 per million tokens - Output: $15 per million tokens - With prompt caching: 90% cost reduction on repeated prompts - Typical usage: $5-20/month for active development

OpenAI GPT-4 Turbo: - Input: $10 per million tokens - Output: $30 per million tokens - Typical usage: $15-50/month for active development

Local Models (Ollama): - $0 - completely free - Requires capable hardware (16GB+ RAM recommended)

Cost Optimization Tips: 1. Use prompt caching (Claude only) - 90% savings 2. Use Haiku for simple tasks - 25x cheaper than Sonnet 3. Use local models for development 4. Cache wizard results to avoid repeated analysis

What are the system requirements?¶

Minimum: - Python 3.10+ - 4GB RAM - Internet connection (for cloud LLMs)

Recommended: - Python 3.11+ - 8GB+ RAM - SSD storage - Good internet connection (for optimal LLM performance)

For Local LLMs: - 16GB+ RAM - GPU (optional but recommended) - 10GB+ disk space for models

How accurate are Level 4 predictions?¶

Level 4 Anticipatory predictions are based on: - Code trajectory analysis - Project context (team size, growth rate, deployment frequency) - Historical patterns in similar codebases - Industry data on common failure modes

Accuracy Rates (based on production usage): - Security predictions: 75-85% accuracy - Performance predictions: 70-80% accuracy - Scalability predictions: 65-75% accuracy

Accuracy improves with: - More interaction history - Better project context - Regular feedback on prediction quality - Consistent usage patterns

Note: Predictions are probabilistic, not deterministic. Always validate before taking action.

Can I use this offline?¶

With Local LLMs: Yes! Use Ollama or LM Studio to run completely offline.

With Cloud LLMs: No - requires internet for API calls.

Hybrid Approach: - Use local models for development (offline) - Use cloud models for production (better quality)

Licensing and Pricing¶

How much does commercial licensing cost?¶

Framework: $0 - Completely free under Fair Source 0.9 license

Commercial Support (Optional): $99/developer/year

What's Included in Commercial Support: - Priority bug fixes and feature requests - Direct access to core development team - Guaranteed response times (24-48 hours) - Security advisories and patches - Upgrade assistance - Architecture consultation (1 hour/quarter)

What's included in the free tier?¶

Everything! There is no "free tier" vs "paid tier" - the entire framework is free under Fair Source 0.9.

You get: - Full source code access - All 16+ Coach wizards - All empathy levels (1-5) - Long-term memory (pattern storage) - Pattern library - Configuration system - CLI tools - Documentation - Community support

What you don't get (unless you purchase support): - Priority support - Guaranteed response times - Direct access to development team - Security advisories

Can I use this in my commercial product?¶

Yes! Fair Source 0.9 allows commercial use without restrictions.

You can: - Use it in commercial products - Modify the source code - Distribute modified versions - Charge for your products that use it - Keep your modifications private (no copyleft)

You must: - Include the Fair Source 0.9 license notice - Include the copyright notice - Document significant changes (if distributing)

You cannot: - Claim the framework as your own work - Hold Smart AI Memory liable for issues

Do I need to open source my code if I use this?¶

No! Fair Source 0.9 is permissive, not copyleft (unlike GPL).

Your code stays private. You're free to build proprietary products using the Empathy Framework.

Can I contribute to the project?¶

Yes! We welcome contributions:

How to Contribute: 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Add tests 5. Submit a pull request

What We Need: - Bug fixes - New wizards for additional domains - Documentation improvements - Test coverage expansion - Performance optimizations - Example code and tutorials

See Contributing for detailed guidelines.

Integration and Usage¶

How do I integrate this into my CI/CD pipeline?¶

GitHub Actions Example:

name: Empathy Framework Security Check
on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - run: pip install empathy-framework anthropic
      - run: |
          python -c "
          from coach_wizards import SecurityWizard
          import sys
          wizard = SecurityWizard()
          # Check all Python files
          # Exit 1 if critical issues found
          "
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

GitLab CI Example:

empathy-check:
  image: python:3.11
  before_script:
    - pip install empathy-framework anthropic
  script:
    - python security_check.py
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY

Can I use this with VS Code / JetBrains / other IDEs?¶

Yes! We provide integrations:

VS Code: - Official extension: empathy-framework (search in VS Code marketplace) - Real-time analysis as you type - Inline suggestions and fixes

JetBrains (IntelliJ, PyCharm, etc.): - Plugin: Empathy Framework - Similar features to VS Code extension

Language Server Protocol (LSP): - Works with any LSP-compatible editor (Vim, Emacs, Sublime Text, etc.) - Check the examples/ directory in the GitHub repository for setup instructions

How do I use this with Docker?¶

Dockerfile Example:

FROM python:3.11-slim

# Install Empathy Framework
RUN pip install empathy-framework anthropic

# Copy your code
COPY . /app
WORKDIR /app

# Set API key
ENV ANTHROPIC_API_KEY=sk-ant-your-key

# Run your analysis
CMD ["python", "analyze.py"]

Can I use multiple LLM providers simultaneously?¶

Yes! Create separate instances:

from empathy_llm_toolkit import EmpathyLLM

# Use Claude for complex reasoning (Level 4)
claude = EmpathyLLM(
    provider="anthropic",
    target_level=4,
    model="claude-3-5-sonnet-20241022"
)

# Use GPT-4 for quick responses (Level 2)
gpt = EmpathyLLM(
    provider="openai",
    target_level=2,
    model="gpt-4-turbo-preview"
)

# Use local model for privacy-sensitive tasks
local = EmpathyLLM(
    provider="local",
    target_level=2,
    endpoint="http://localhost:11434",
    model="llama2"
)

# Route to appropriate model based on task
async def handle_request(user_input, priority):
    if priority == "high":
        return await claude.interact("user", user_input)
    elif priority == "medium":
        return await gpt.interact("user", user_input)
    else:
        return await local.interact("user", user_input)

How do I test my custom wizards?¶

Use the built-in testing utilities:

import unittest
from coach_wizards import BaseCoachWizard

class TestMyWizard(unittest.TestCase):
    def setUp(self):
        self.wizard = MyCustomWizard()

    def test_detects_vulnerability(self):
        code = "SELECT * FROM users WHERE id='" + user_id + "'"
        result = self.wizard.run_full_analysis(code, "test.py", "python")
        self.assertTrue(len(result.issues) > 0)
        self.assertIn("SQL injection", result.issues[0].message)

    def test_predicts_future_issue(self):
        code = "..."
        context = {"growth_rate": 0.3, "user_count": 5000}
        result = self.wizard.run_full_analysis(
            code, "test.py", "python", context
        )
        self.assertTrue(len(result.predictions) > 0)

Long-Term Memory¶

How does long-term memory work?¶

The Empathy Framework includes built-in long-term memory for pattern storage:

Pattern Storage: When a wizard finds an important pattern, it's stored in long-term memory
Cross-Domain Retrieval: When analyzing code, the system searches for similar patterns from other domains
Level 5 Systems Empathy: Patterns learned in healthcare can prevent failures in software

Installation:

pip install empathy-framework[full]  # Includes all components

Usage:

from empathy_os import EmpathyOS

# Initialize with built-in pattern storage
os = EmpathyOS()

# Long-term memory is enabled by default
os.persist_pattern(
    content="Pattern content",
    pattern_type="coding_pattern"
)

What's stored in long-term memory?¶

Patterns Stored: - User interaction patterns (sequential, conditional, adaptive) - Code patterns (vulnerabilities, performance issues, best practices) - Domain-specific knowledge (healthcare protocols, financial regulations) - Historical predictions and their outcomes - Cross-domain pattern mappings

What's NOT Stored: - Your actual code or data (privacy-first) - API keys or secrets - Personal information - Proprietary business logic

Is my data secure with long-term memory?¶

Yes! The system is privacy-first:

Local Storage: All data stays on your machine by default

Encryption: Database is encrypted at rest (optional, required for SENSITIVE)

No Telemetry: Zero data collection or tracking

Data Control: You own and control all stored data

Can I disable long-term memory?¶

Yes! It's completely optional:

from empathy_os import EmpathyOS

# Disable long-term memory
os = EmpathyOS(enable_long_term_memory=False)

Or via configuration:

# empathy.config.yml
pattern_library_enabled: false

Security and Privacy¶

What security features does Empathy Framework include?¶

The Empathy Framework includes enterprise-grade security controls built for GDPR, HIPAA, and SOC2 compliance:

PII Scrubbing - Automatically detects and removes Personally Identifiable Information - Supported types: Email, SSN, phone numbers, credit cards, IP addresses, names, medical record numbers (MRN), patient IDs - Custom pattern support for organization-specific PII - Detailed audit logs for compliance reporting

Secrets Detection - Detects API keys (Anthropic, OpenAI, AWS, GitHub, Slack, Stripe) - Detects passwords, private keys (RSA, SSH, EC, PGP, TLS) - Detects JWT tokens, OAuth tokens, database connection strings - Shannon entropy analysis for unknown secret patterns - Never logs or exposes actual secret values

Audit Logging - Tamper-evident audit logs - Structured JSON logging for SIEM integration - Tracks all LLM requests, PII detections, secrets found - SOC2 CC7.2 and HIPAA §164.312(b) compliant

Secure Pattern Storage - Three-tier classification: PUBLIC, INTERNAL, SENSITIVE - AES-256-GCM encryption for SENSITIVE patterns - Retention policies per classification - Access control based on user roles

How do I use PII scrubbing?¶

from empathy_llm_toolkit.security import PIIScrubber

# Initialize scrubber
scrubber = PIIScrubber()

# Scrub PII from content
text = "Contact John at john.doe@email.com or 555-123-4567"
sanitized, detections = scrubber.scrub(text)

print(sanitized)
# Output: "Contact John at [EMAIL] or [PHONE]"

print(f"Found {len(detections)} PII instances")
# Each detection includes: pii_type, position, confidence

# Add custom patterns for organization-specific PII
scrubber.add_custom_pattern(
    name="employee_id",
    pattern=r"EMP-\d{6}",
    replacement="[EMPLOYEE_ID]",
    description="Company employee identifier"
)

How do I detect secrets in code?¶

from empathy_llm_toolkit.security import SecretsDetector, detect_secrets

# Quick detection
detections = detect_secrets(code_content)

# Or with configuration
detector = SecretsDetector(
    enable_entropy_analysis=True,  # Detect high-entropy strings
    entropy_threshold=4.5
)

detections = detector.detect(code_content)

for detection in detections:
    print(f"Found {detection.secret_type.value} at line {detection.line_number}")
    print(f"Severity: {detection.severity.value}")
    # Note: Actual secret value is NEVER exposed

# Add custom patterns
detector.add_custom_pattern(
    name="company_api_key",
    pattern=r"acme_[a-zA-Z0-9]{32}",
    severity="high"
)

How does Claude Memory security work?¶

The framework supports a hierarchical memory system with security controls:

Three-Level Hierarchy: 1. Enterprise (/etc/claude/CLAUDE.md) - Organization-wide security policies 2. User (~/.claude/CLAUDE.md) - Personal preferences (cannot override enterprise) 3. Project (./.claude/CLAUDE.md) - Team rules (cannot override enterprise or user)

Security Enforcement: - Enterprise policies CANNOT be overridden by user or project memory - PII scrubbing patterns defined at enterprise level - Secrets detection enforced before any LLM call - Audit logging of all memory access

from empathy_llm_toolkit.claude_memory import ClaudeMemoryConfig, ClaudeMemoryLoader

config = ClaudeMemoryConfig(
    enabled=True,
    load_enterprise=True,  # Load org-wide security policies
    load_user=True,
    load_project=True
)

loader = ClaudeMemoryLoader(config)
memory = loader.load_all_memory()
# Enterprise security policies are enforced automatically

Is my data secure with the Empathy Framework?¶

Yes! Security is built into the core:

Feature	Implementation
PII Protection	Automatic scrubbing before LLM calls (GDPR Article 5)
Secrets Prevention	Detection blocks API calls containing secrets
Encryption	AES-256-GCM for SENSITIVE patterns
Audit Trail	Complete logging of all operations (SOC2, HIPAA)
Local Storage	All data stays on your machine by default
No Telemetry	Zero data collection or phone-home

What compliance standards does this support?¶

GDPR (General Data Protection Regulation): - Article 5(1)(c) - Data Minimization: PII scrubbing - Article 5(1)(e) - Storage Limitation: Retention policies - Article 25 - Data Protection by Design: Classification system - Article 30 - Records of Processing: Audit logging - Article 32 - Security of Processing: Encryption

HIPAA (Health Insurance Portability and Accountability Act): - §164.312(a)(1) - Access Control: Classification-based access - §164.312(b) - Audit Controls: Comprehensive audit logging - §164.312(c)(1) - Integrity: Tamper-evident logs - §164.514 - De-identification: PII/PHI scrubbing

SOC2 (Service Organization Control 2): - CC6.1 - Logical Access: User authentication + authorization - CC6.6 - Encryption: AES-256-GCM for SENSITIVE data - CC7.2 - System Monitoring: Audit logging with alerting

Can I run this in air-gapped environments?¶

Yes! The framework supports air-gapped mode:

# Enable air-gapped mode
export AIR_GAPPED_MODE=true

In air-gapped mode: - NO external LLM API calls - Use local models only (Ollama) - Pattern storage: local filesystem only - Audit logs: local filesystem only - Memory: local CLAUDE.md files only

How do I set up secure pattern storage?¶

from empathy_llm_toolkit.security import SecurePatternStorage, Classification

# Initialize with security policies
storage = SecurePatternStorage(claude_memory_config)

# Store a pattern with auto-classification
result = storage.store_pattern(
    pattern_content="Clinical protocol for patient handoffs...",
    pattern_type="healthcare",
    user_id="doctor@hospital.com",
    auto_classify=True  # Auto-detects as SENSITIVE
)

# Result includes:
# - pattern_id: Unique identifier
# - classification: "SENSITIVE" (auto-detected from healthcare keywords)
# - sanitization_report: PII removed, secrets checked
# - encryption: Applied for SENSITIVE patterns

Classification Rules: - PUBLIC: General patterns, shareable, 365-day retention - INTERNAL: Proprietary patterns, team-only, 180-day retention - SENSITIVE: Healthcare/financial, encrypted, 90-day retention

Support and Community¶

How do I get support?¶

Free Community Support: - GitHub Issues: https://github.com/Deep-Study-AI/Empathy/issues - GitHub Discussions: https://github.com/Deep-Study-AI/Empathy/discussions - Documentation: https://github.com/Deep-Study-AI/Empathy/tree/main/docs - Examples: https://github.com/Deep-Study-AI/Empathy/tree/main/examples

Paid Commercial Support ($99/developer/year): - Priority bug fixes (24-48 hour response time) - Direct email/Slack access to core team - Architecture consultation - Security advisories - Upgrade assistance

Contact: patrick.roebuck@deepstudyai.com

Where can I report bugs?¶

GitHub Issues: https://github.com/Deep-Study-AI/Empathy/issues

Before Reporting: 1. Search existing issues 2. Check if it's already fixed in latest version 3. Reproduce with minimal example 4. Include version info (empathy-framework version)

Include in Report: - Empathy Framework version - Python version - LLM provider and model - Full error message and traceback - Minimal code to reproduce - Expected vs actual behavior

How can I request features?¶

GitHub Discussions: https://github.com/Deep-Study-AI/Empathy/discussions

Feature Request Template: 1. Problem Statement: What problem are you trying to solve? 2. Proposed Solution: How do you envision this working? 3. Alternatives Considered: What other approaches did you consider? 4. Additional Context: Examples, mockups, related issues

Where can I find examples and tutorials?¶

Official Examples: - GitHub: https://github.com/Deep-Study-AI/Empathy/tree/main/examples - Quick Start Guide: docs/QUICKSTART_GUIDE.md - User Guide: docs/USER_GUIDE.md

Community Examples: - GitHub Discussions: Share your use cases - Blog posts and tutorials (community-contributed)

Is there a Slack or Discord community?¶

Not yet, but we're considering it based on community interest.

Current Channels: - GitHub Discussions (primary community forum) - GitHub Issues (bug reports and feature requests) - Email (commercial support customers)

Vote for Community Platform: - Comment on this discussion to vote

How often is the framework updated?¶

Release Schedule: - Patch releases (1.0.x): As needed for bug fixes - Minor releases (1.x.0): Monthly with new features - Major releases (x.0.0): Annually with breaking changes

Security Updates: - Critical security issues: Within 24-48 hours - Non-critical security issues: Next patch release

Subscribe for Updates: - Watch the GitHub repository - Follow release notes: https://github.com/Deep-Study-AI/Empathy/releases

Troubleshooting¶

I'm getting "API key not found" errors¶

See the TROUBLESHOOTING.md guide for detailed solutions.

Quick fix:

# Check if API key is set
echo $ANTHROPIC_API_KEY

# Set it if missing
export ANTHROPIC_API_KEY=sk-ant-your-key-here

# Make permanent
echo 'export ANTHROPIC_API_KEY=sk-ant-your-key-here' >> ~/.bashrc
source ~/.bashrc

The framework is running slow¶

See TROUBLESHOOTING.md for performance optimization tips.

Quick fixes: 1. Enable prompt caching (Claude): 90% faster on repeated calls 2. Use faster model (claude-3-haiku-20240307): 10x faster 3. Use local model for development: No API latency

I'm not reaching higher empathy levels¶

Higher levels require building trust:

Level 2: 3+ interactions, trust > 0.3
Level 3: 10+ interactions, trust > 0.7
Level 4: 20+ interactions, trust > 0.8
Level 5: 50+ interactions, trust > 0.9

Build trust faster:

# Provide positive feedback
llm.update_trust("user", outcome="success", magnitude=1.0)

# Or force level for testing
result = await llm.interact(
    user_id="test",
    user_input="Test",
    force_level=4  # Force Level 4 for demo
)

Where can I find more troubleshooting help?¶

See TROUBLESHOOTING.md for comprehensive troubleshooting guide covering: - Installation issues - Import errors - API key configuration - Test failures - Performance problems - Memory issues - LLM provider errors - And more...

Additional Questions¶

How does this compare to GitHub Copilot?¶

Feature	GitHub Copilot	Empathy Framework
Primary Use	Code completion	Code analysis & prevention
Intelligence	Autocomplete	Multi-level reasoning
Prediction	Next line of code	Future bugs and bottlenecks
Learning	Pre-trained only	Learns from your patterns
Cost	$10-20/month per user	Free (+ LLM API costs)
Scope	Code generation	Full development lifecycle

Bottom Line: Copilot helps you write code faster. Empathy Framework helps you write better code and prevents future problems.

Can I build a SaaS product using this?¶

Yes! Fair Source 0.9 allows this. Many companies build SaaS products on top of Fair Source 0.9 projects.

You can: - Offer Empathy Framework as a service - Charge for your SaaS product - Keep your modifications private - Add proprietary features on top

You should: - Include Fair Source 0.9 license notice - Attribute the Empathy Framework - Consider contributing improvements back - Purchase commercial support for priority help

What's the long-term roadmap?¶

Near-term (Q1-Q2 2025): - Additional LLM providers (Gemini, Cohere) - Enhanced IDE integrations - More domain-specific wizards - Improved prediction accuracy

Mid-term (Q3-Q4 2025): - Multi-language support expansion - Team collaboration features - Enhanced cross-domain learning - Real-time code analysis

Long-term (2026+): - Level 6: Autonomous problem resolution - Healthcare and financial domain plugins - Enterprise features (RBAC, audit logs) - Cloud-hosted option

Check our GitHub repository for the latest development updates.

Still Have Questions?¶

Can't find your answer?

Check the User Guide
Check the API Reference
Search GitHub Discussions
Ask in GitHub Discussions
Email: patrick.roebuck@deepstudyai.com