empathy-framework 3.8.0

AI collaboration framework with intelligent caching (up to 57% cache hit rate), tier routing (34-86% cost savings depending on task complexity), XML-enhanced prompts, persistent memory, CrewAI integration, and multi-agent orchestration. Includes HIPAA-compliant healthcare wizards.

Empathy Framework

The AI collaboration framework that predicts problems before they happen.

pip install empathy-framework[developer]  # Lightweight for individual developers

What's New in v3.7.0

🚀 XML-Enhanced Prompting: 15-35% Token Reduction + Graceful Validation

Slash your API costs and eliminate response parsing errors with production-ready XML enhancements.

Context Window Optimization — Save 15-35% on Every Request

from empathy_os.optimization import ContextOptimizer, CompressionLevel

optimizer = ContextOptimizer(CompressionLevel.MODERATE)
optimized_prompt = optimizer.optimize(your_xml_prompt)
# Achieves 15-25% token reduction automatically

• Tag compression: <thinking> → <t>, <answer> → <a> (15+ common tags)
• Whitespace optimization: Removes excess whitespace while preserving structure
• Redundancy elimination: Strips "Please note that", "Make sure to", etc.
• Real-world impact: Integration tests achieved 49.7% reduction on typical prompts
• Bidirectional: Full decompression to restore original tag names

XML Validation — Never Crash on Malformed Responses Again

from empathy_os.validation import validate_xml_response

result = validate_xml_response(llm_response)
if result.is_valid:
    data = result.parsed_data
else:
    # Fallback extraction worked - you still get partial data
    data = result.parsed_data or {}

• Graceful fallback parsing: Regex extraction when XML is malformed
• Optional XSD validation: Full schema validation with lxml
• Schema caching: Performance optimization for repeated validations
• 25 comprehensive tests: Covers edge cases, malformed input, and XSD validation

Migration Made Easy

See XML_WORKFLOW_MIGRATION_GUIDE.md for complete migration guide with:

• XMLAgent/XMLTask patterns with before/after examples
• Configuration options (config.xml.use_xml_structure)
• Benefits: 40-60% fewer misinterpretations, 20-30% fewer retries

Test Coverage: 229 new tests (86 XML enhancement + 143 robustness) — 100% passing

---

What's New in v3.6.0

💡 Finally! Error Messages That Actually Help You

No more cryptic NotImplementedError when extending the framework!

We completely rewrote error messages across 5 base classes. Now when you're building plugins or extensions, you get:

✅ Exactly which method you need to implement ✅ Which base class to extend ✅ Real working examples from the codebase to copy ✅ Clear explanations of what each method should return

Before (frustrating 😤):

NotImplementedError
# ...now what? Time to dig through source code for 30 minutes

After (helpful 🎯):

NotImplementedError: BaseLinterParser.parse() must be implemented.
Create a subclass of BaseLinterParser and implement the parse() method.
See ESLintParser, PylintParser, or MyPyParser for examples.
# Perfect! Now I know exactly what to do

Plus: 9 Integration TODOs Now Link to Working Code

• Want to add compliance tracking? → See ComplianceDatabase class (agents/compliance_db.py)
• Need multi-channel notifications? → See NotificationService class (agents/notifications.py)
• Wondering about MemDocs integration? → We documented why local cache works better (with rationale)
• Need secure document storage? → S3/Azure/SharePoint recommendations with HIPAA requirements

Impact: Onboard new contributors in minutes instead of hours. Build your first plugin in one sitting.

---

🔐 Production-Grade Security & Compliance

Secure Authentication System ✅ Deployed in Backend API

• Bcrypt password hashing with cost factor 12 (industry standard 2026)
• JWT tokens with 30-minute expiration and automatic refresh
• Rate limiting: 5 failed attempts = 15-minute lockout (prevents brute force)
• 18 comprehensive security tests covering all attack vectors
• Status: Fully integrated into backend/api/wizard_api.py

HIPAA/GDPR Compliance Database 🛠️ Infrastructure Ready

• Append-only architecture (INSERT only, no UPDATE/DELETE) - satisfies regulators
• Immutable audit trail for healthcare and enterprise compliance
• Compliance gap detection with severity classification
• 12 tests ensuring regulatory compliance
• Status: Production-ready code with integration points documented. See compliance_anticipation_agent.py for usage examples.

Multi-Channel Notification System 🛠️ Infrastructure Ready

• Email (SMTP), Slack (webhooks), SMS (Twilio)
• Graceful fallback when channels unavailable
• Smart routing: SMS only for critical alerts (cost optimization)
• 10 tests covering all notification scenarios
• Status: Production-ready code with integration points documented. See TODOs in compliance agent for usage examples.

---

Previous: Project Indexing & Test Suite Expansion (v3.5.4)

• Project Indexing System — JSON-based file tracking with automatic structure scanning, metadata tracking, and CrewAI integration
• 5,603 Tests — Comprehensive test coverage at 64% with 30+ new test modules
• BaselineManager Fix — Resolved test isolation bug affecting suppression system

Memory API Security Hardening (v3.5.0)

• Input Validation — Pattern IDs, agent IDs, and classifications validated to prevent path traversal and injection attacks
• API Key Authentication — Bearer token and X-API-Key header support with SHA-256 hash comparison
• Rate Limiting — Per-IP sliding window rate limiting (100 req/min default)
• HTTPS/TLS Support — Optional SSL certificate configuration for encrypted connections
• CORS Restrictions — Configurable allowed origins (localhost-only by default)
• Request Size Limits — 1MB body limit to prevent DoS attacks

Previous (v3.4.x)

• Trust Circuit Breaker — Automatic degradation when model reliability drops
• Pattern Catalog System — Searchable pattern library with similarity matching
• Memory Control Panel — VSCode sidebar for Redis and pattern management

Previous (v3.3.x)

• Formatted Reports — Every workflow includes formatted_report with consistent structure
• Enterprise-Safe Doc-Gen — Auto-scaling tokens, cost guardrails, file export
• Unified Typer CLI — One empathy command with Rich output
• Python 3.13 Support — Test matrix covers 3.10-3.13 across all platforms

Previous (v3.1.x)

• Smart Router — Natural language wizard dispatch: "Fix security in auth.py" → SecurityWizard
• Memory Graph — Cross-wizard knowledge sharing across sessions
• Auto-Chaining — Wizards automatically trigger related wizards
• Resilience Patterns — Retry, Circuit Breaker, Timeout, Health Checks

Previous (v3.0.x)

• Multi-Model Provider System — Anthropic, OpenAI, Google Gemini, Ollama, or Hybrid mode
• 34-86% Cost Savings — Smart tier routing varies by role: architects 34%, senior devs 65%, junior devs 86%*
• VSCode Dashboard — 10 integrated workflows with input history persistence

*See Cost Savings Analysis for your specific use case

---

Quick Start (2 Minutes)

1. Install

Individual Developers (Recommended):

pip install empathy-framework[developer]

Teams/Enterprises (Backend + Auth):

pip install empathy-framework[enterprise]

Healthcare Organizations (HIPAA/GDPR Compliance):

pip install empathy-framework[healthcare]

What's the difference?

• [developer] - Lightweight install for individual developers. Includes CLI tools, VSCode extension, LLM providers, agents. No backend server needed.

• [enterprise] - Everything in [developer] plus backend API server with authentication (bcrypt, JWT, rate limiting). For teams deploying to production.

• [healthcare] - Everything in [enterprise] plus HIPAA/GDPR compliance database, redis, and healthcare-specific plugins. Only needed for regulated industries.

Most developers should use [developer] - it's fast to install and has everything you need for software development.

2. Configure Provider

# Auto-detect your API keys and configure
python -m empathy_os.models.cli provider

# Or set explicitly
python -m empathy_os.models.cli provider --set anthropic
python -m empathy_os.models.cli provider --set hybrid  # Best of all providers

3. Use It

from empathy_os import EmpathyOS

os = EmpathyOS()
result = await os.collaborate(
    "Review this code for security issues",
    context={"code": your_code}
)

print(result.current_issues)      # What's wrong now
print(result.predicted_issues)    # What will break in 30-90 days
print(result.prevention_steps)    # How to prevent it

---

Why Empathy?

Feature	Empathy	SonarQube	GitHub Copilot
Predicts future issues	30-90 days ahead	No	No
Persistent memory	Redis + patterns	No	No
Multi-provider support	Claude, GPT-4, Gemini, Ollama	N/A	GPT only
Cost optimization	34-86% savings*	N/A	No
Your data stays local	Yes	Cloud	Cloud
Free for small teams	≤5 employees	No	No

---

What's New in v3.8.0

🚀 Intelligent Response Caching: Benchmarked Performance

Stop paying full price for repeated LLM calls. Measured results: up to 99.8% faster, 40% cost reduction on test generation, 57% cache hit rate on security audits.

Hybrid Cache: Hash + Semantic Matching

from empathy_os.workflows import SecurityAuditWorkflow

# That's it - caching auto-configured!
workflow = SecurityAuditWorkflow(enable_cache=True)
result = await workflow.execute(target_path="./src")

# Check savings
print(f"Cost: ${result.cost_report.total_cost:.4f}")
print(f"Cache hit rate: {result.cost_report.cache_hit_rate:.1f}%")
print(f"Savings: ${result.cost_report.savings_from_cache:.4f}")

Real Results (v3.8.0 benchmark - see CACHING_BENCHMARK_REPORT.md):

• Hash-only cache: 30.3% average hit rate across 12 workflows, up to 99.8% faster (code review: 17.8s → 0.03s)
• Hybrid cache: Up to 57% hit rate on similar prompts (security audit - benchmarked)
• Cost reduction: 40% on test-generation workflow (measured)

Two Cache Strategies

Hash-Only Cache (Default - Zero Dependencies):

• Perfect for CI/CD and testing
• 100% hit rate on identical prompts
• ~5μs lookup time
• No ML dependencies needed

Hybrid Cache (Semantic Matching):

• Up to 57% hit rate on similar prompts (benchmarked)
• Understands intent, not just text
• Install: pip install empathy-framework[cache]
• Best for development and production

Automatic Setup

Framework detects your environment and configures optimal caching:

# First run: Framework checks for sentence-transformers
# - Found? Uses hybrid cache (semantic matching, up to 57% hit rate)
# - Missing? Prompts: "Install for semantic matching? (y/n)"
# - Declined? Falls back to hash-only (100% hit rate on identical prompts)
# - Any errors? Disables gracefully, workflow continues

# Subsequent runs: Cache just works

The Caching Paradox: Adaptive Workflows

Discovered during v3.8.0 development: Some workflows (Security Audit, Bug Prediction) cost MORE on Run 2 with cache enabled - and that's a FEATURE.

Why? Adaptive workflows use cache to free up time for deeper analysis:

Security Audit without cache:
Run 1: $0.11, 45 seconds - surface scan finds 3 issues

Security Audit with cache:
Run 2: $0.13, 15 seconds - cache frees 30s for deep analysis
       → Uses saved time for PREMIUM tier vulnerability research
       → Finds 7 issues including critical SQLi we missed
       → Extra $0.02 cost = prevented security breach

Result: Cache makes workflows SMARTER, not just cheaper.

See Adaptive Workflows Documentation for full explanation.

Complete Documentation

• Quick Reference - Common scenarios, 1-page cheat sheet
• Configuration Guide - All options, when to use each
• Adaptive Workflows - Why Run 2 can cost more (it's good!)

Test it yourself:

# Quick test (2-3 minutes)
python benchmark_caching_simple.py

# Full benchmark (15-20 minutes, all 12 workflows)
python benchmark_caching.py

---

Become a Power User

Level 1: Basic Usage

pip install empathy-framework[developer]

• Lightweight install with CLI tools, LLM providers, and agents
• Works out of the box with sensible defaults
• Auto-detects your API keys

Level 2: Cost Optimization (Role-Based Savings)

Tier routing automatically routes tasks to appropriate models, saving 34-86% depending on your work role.

# Enable hybrid mode
python -m empathy_os.models.cli provider --set hybrid

Tier Pricing

Tier	Model	Use Case	Cost per Task*
CHEAP	GPT-4o-mini / Haiku	Summarization, formatting, simple tasks	$0.0045-0.0075
CAPABLE	GPT-4o / Sonnet	Bug fixing, code review, analysis	$0.0725-0.090
PREMIUM	o1 / Opus	Architecture, complex decisions, design	$0.435-0.450

*Typical task: 5,000 input tokens, 1,000 output tokens

Actual Savings by Role

Your Role	PREMIUM %	CAPABLE %	CHEAP %	Actual Savings	Notes
Architect / Designer	60%	30%	10%	34%	Design work requires complex reasoning
Senior Developer	25%	50%	25%	65%	Mix of architecture and implementation
Mid-Level Developer	15%	60%	25%	73%	Mostly implementation and bug fixes
Junior Developer	5%	40%	55%	86%	Simple features, tests, documentation
QA Engineer	10%	35%	55%	80%	Test generation, reports, automation
DevOps Engineer	20%	50%	30%	69%	Infrastructure planning + automation

See Complete Cost Analysis for provider comparisons (Anthropic vs OpenAI vs Ollama) and detailed calculations.

Level 3: Multi-Model Workflows

from empathy_llm_toolkit import EmpathyLLM

llm = EmpathyLLM(provider="anthropic", enable_model_routing=True)

# Automatically routes to appropriate tier
await llm.interact(user_id="dev", user_input="Summarize this", task_type="summarize")     # → Haiku
await llm.interact(user_id="dev", user_input="Fix this bug", task_type="fix_bug")         # → Sonnet
await llm.interact(user_id="dev", user_input="Design system", task_type="coordinate")     # → Opus

Level 4: VSCode Integration

Install the Empathy VSCode extension for:

• Real-time Dashboard — Health score, costs, patterns
• One-Click Workflows — Research, code review, debugging
• Visual Cost Tracking — See savings in real-time
  • See also: docs/dashboard-costs-by-tier.md for interpreting the By tier (7 days) cost breakdown.
• Memory Control Panel (Beta) — Manage Redis and pattern storage
  • View Redis status and memory usage
  • Browse and export stored patterns
  • Run system health checks
  • Configure auto-start in empathy.config.yml

memory:
  enabled: true
  auto_start_redis: true

Level 5: Custom Agents

from empathy_os.agents import AgentFactory

# Create domain-specific agents with inherited memory
security_agent = AgentFactory.create(
    domain="security",
    memory_enabled=True,
    anticipation_level=4
)

---

CLI Reference

Provider Configuration

python -m empathy_os.models.cli provider                    # Show current config
python -m empathy_os.models.cli provider --set anthropic    # Single provider
python -m empathy_os.models.cli provider --set hybrid       # Best-of-breed
python -m empathy_os.models.cli provider --interactive      # Setup wizard
python -m empathy_os.models.cli provider -f json            # JSON output

Model Registry

python -m empathy_os.models.cli registry                    # Show all models
python -m empathy_os.models.cli registry --provider openai  # Filter by provider
python -m empathy_os.models.cli costs --input-tokens 50000  # Estimate costs

Telemetry & Analytics

python -m empathy_os.models.cli telemetry                   # Summary
python -m empathy_os.models.cli telemetry --costs           # Cost savings report
python -m empathy_os.models.cli telemetry --providers       # Provider usage
python -m empathy_os.models.cli telemetry --fallbacks       # Fallback stats

Memory Control

empathy-memory serve    # Start Redis + API server
empathy-memory status   # Check system status
empathy-memory stats    # View statistics
empathy-memory patterns # List stored patterns

Code Inspection

empathy-inspect .                     # Run full inspection
empathy-inspect . --format sarif      # GitHub Actions format
empathy-inspect . --fix               # Auto-fix safe issues
empathy-inspect . --staged            # Only staged changes

---

XML-Enhanced Prompts

Enable structured XML prompts for consistent, parseable LLM responses:

# .empathy/workflows.yaml
xml_prompt_defaults:
  enabled: false  # Set true to enable globally

workflow_xml_configs:
  security-audit:
    enabled: true
    enforce_response_xml: true
    template_name: "security-audit"
  code-review:
    enabled: true
    template_name: "code-review"

Built-in templates: security-audit, code-review, research, bug-analysis, perf-audit, refactor-plan, test-gen, doc-gen, release-prep, dependency-check

from empathy_os.prompts import get_template, XmlResponseParser, PromptContext

# Use a built-in template
template = get_template("security-audit")
context = PromptContext.for_security_audit(code="def foo(): pass")
prompt = template.render(context)

# Parse XML responses
parser = XmlResponseParser(fallback_on_error=True)
result = parser.parse(llm_response)
print(result.summary, result.findings, result.checklist)

---

Enterprise Doc-Gen

Generate comprehensive documentation for large projects with enterprise-safe defaults:

from empathy_os.workflows import DocumentGenerationWorkflow

# Enterprise-safe configuration
workflow = DocumentGenerationWorkflow(
    export_path="docs/generated",     # Auto-save to disk
    max_cost=5.0,                     # Cost guardrail ($5 default)
    chunked_generation=True,          # Handle large projects
    graceful_degradation=True,        # Partial results on errors
)

result = await workflow.execute(
    source_code=your_code,
    doc_type="api_reference",
    audience="developers"
)

# Access the formatted report
print(result.final_output["formatted_report"])

# Large outputs are chunked for display
if "output_chunks" in result.final_output:
    for chunk in result.final_output["output_chunks"]:
        print(chunk)

# Full docs saved to disk
print(f"Saved to: {result.final_output.get('export_path')}")

---

Smart Router

Route natural language requests to the right wizard automatically:

from empathy_os.routing import SmartRouter

router = SmartRouter()

# Natural language routing
decision = router.route_sync("Fix the security vulnerability in auth.py")
print(f"Primary: {decision.primary_wizard}")      # → security-audit
print(f"Also consider: {decision.secondary_wizards}")  # → [code-review]
print(f"Confidence: {decision.confidence}")

# File-based suggestions
suggestions = router.suggest_for_file("requirements.txt")  # → [dependency-check]

# Error-based suggestions
suggestions = router.suggest_for_error("NullReferenceException")  # → [bug-predict, test-gen]

---

Memory Graph

Cross-wizard knowledge sharing - wizards learn from each other:

from empathy_os.memory import MemoryGraph, EdgeType

graph = MemoryGraph()

# Add findings from any wizard
bug_id = graph.add_finding(
    wizard="bug-predict",
    finding={
        "type": "bug",
        "name": "Null reference in auth.py:42",
        "severity": "high"
    }
)

# Connect related findings
fix_id = graph.add_finding(wizard="code-review", finding={"type": "fix", "name": "Add null check"})
graph.add_edge(bug_id, fix_id, EdgeType.FIXED_BY)

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

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

---

Auto-Chaining

Wizards automatically trigger related wizards based on findings:

# .empathy/wizard_chains.yaml
chains:
  security-audit:
    auto_chain: true
    triggers:
      - condition: "high_severity_count > 0"
        next: dependency-check
        approval_required: false
      - condition: "vulnerability_type == 'injection'"
        next: code-review
        approval_required: true

  bug-predict:
    triggers:
      - condition: "risk_score > 0.7"
        next: test-gen

templates:
  full-security-review:
    steps: [security-audit, dependency-check, code-review]
  pre-release:
    steps: [test-gen, security-audit, release-prep]

from empathy_os.routing import ChainExecutor

executor = ChainExecutor()

# Check what chains would trigger
result = {"high_severity_count": 5}
triggers = executor.get_triggered_chains("security-audit", result)
# → [ChainTrigger(next="dependency-check"), ...]

# Execute a template
template = executor.get_template("full-security-review")
# → ["security-audit", "dependency-check", "code-review"]

---

Prompt Engineering Wizard

Analyze, generate, and optimize prompts:

from coach_wizards import PromptEngineeringWizard

wizard = PromptEngineeringWizard()

# Analyze existing prompts
analysis = wizard.analyze_prompt("Fix this bug")
print(f"Score: {analysis.overall_score}")  # → 0.13 (poor)
print(f"Issues: {analysis.issues}")        # → ["Missing role", "No output format"]

# Generate optimized prompts
prompt = wizard.generate_prompt(
    task="Review code for security vulnerabilities",
    role="a senior security engineer",
    constraints=["Focus on OWASP top 10"],
    output_format="JSON with severity and recommendation"
)

# Optimize tokens (reduce costs)
result = wizard.optimize_tokens(verbose_prompt)
print(f"Reduced: {result.token_reduction:.0%}")  # → 20% reduction

# Add chain-of-thought scaffolding
enhanced = wizard.add_chain_of_thought(prompt, "debug")

---

Install Options

# Recommended (all features)
pip install empathy-framework[full]

# Minimal
pip install empathy-framework

# Specific providers
pip install empathy-framework[anthropic]  # Claude
pip install empathy-framework[openai]     # GPT-4, Ollama (OpenAI-compatible)
pip install empathy-framework[google]     # Gemini
pip install empathy-framework[llm]        # All providers

# Development
git clone https://github.com/Smart-AI-Memory/empathy-framework.git
cd empathy-framework && pip install -e .[dev]

---

What's Included

Component	Description
Empathy OS	Core engine for human↔AI and AI↔AI collaboration
Smart Router	Natural language wizard dispatch with LLM classification
Memory Graph	Cross-wizard knowledge sharing (bugs, fixes, patterns)
Auto-Chaining	Wizards trigger related wizards based on findings
Multi-Model Router	Smart routing across providers and tiers
Memory System	Redis short-term + encrypted long-term patterns
17 Coach Wizards	Security, performance, testing, docs, prompt engineering
10 Cost-Optimized Workflows	Multi-tier pipelines with formatted reports & XML prompts
Healthcare Suite	SBAR, SOAP notes, clinical protocols (HIPAA)
Code Inspection	Unified pipeline with SARIF/GitHub Actions support
VSCode Extension	Visual dashboard for memory and workflows
Telemetry & Analytics	Cost tracking, usage stats, optimization insights

---

The 5 Levels of AI Empathy

Level	Name	Behavior	Example
1	Reactive	Responds when asked	"Here's the data you requested"
2	Guided	Asks clarifying questions	"What format do you need?"
3	Proactive	Notices patterns	"I pre-fetched what you usually need"
4	Anticipatory	Predicts future needs	"This query will timeout at 10k users"
5	Transformative	Builds preventing structures	"Here's a framework for all future cases"

Empathy operates at Level 4 — predicting problems before they manifest.

---

Environment Setup

# Required: At least one provider
export ANTHROPIC_API_KEY="sk-ant-..."   # For Claude models  # pragma: allowlist secret
export OPENAI_API_KEY="sk-..."          # For GPT models  # pragma: allowlist secret
export GOOGLE_API_KEY="..."             # For Gemini models  # pragma: allowlist secret

# Optional: Redis for memory
export REDIS_URL="redis://localhost:6379"

# Or use a .env file (auto-detected)
echo 'ANTHROPIC_API_KEY=sk-ant-...' >> .env

---

Get Involved

• Star this repo if you find it useful
• Join Discussions — Questions, ideas, show what you built
• Read the Book — Deep dive into the philosophy
• Full Documentation — API reference, examples, guides

---

Project Evolution

For those interested in the development history and architectural decisions:

• Development Logs — Execution plans, phase completions, and progress tracking
• Architecture Docs — System design, memory architecture, and integration plans
• Marketing Materials — Pitch decks, outreach templates, and commercial readiness
• Guides — Publishing tutorials, MkDocs setup, and distribution policies

---

License

Fair Source License 0.9 — Free for students, educators, and teams ≤5 employees. Commercial license ($99/dev/year) for larger organizations. Details →

---

Built by Smart AI Memory · Documentation · Examples · Issues