Metadata-Version: 2.4
Name: empathy-framework
Version: 3.5.5
Summary: AI collaboration framework with persistent memory, anticipatory intelligence, code inspection, and multi-agent orchestration
Author-email: Patrick Roebuck <patrick.roebuck@smartAImemory.com>
Maintainer-email: Smart-AI-Memory <patrick.roebuck@smartAImemory.com>
License: # Fair Source License, version 0.9
        
        **Copyright © 2025 Deep Study AI, LLC**
        
        ## Grant of Rights
        
        **Licensor:** Deep Study AI, LLC
        **Licensed Work:** Empathy
        **Change Date:** January 1, 2029 (4 years from first release)
        **Change License:** Apache License 2.0
        
        ---
        
        ## Terms
        
        ### Grant of Use
        
        Subject to the conditions below, Licensor grants you a non-exclusive, worldwide, royalty-free license to:
        
        - Use the Licensed Work
        - Modify the Licensed Work
        - Create derivative works
        - Distribute copies (subject to restrictions)
        
        ### Usage Limits - Free Tier
        
        You may use the Licensed Work **free of charge** if you meet ANY of these conditions:
        
        1. **Educational Use:** You are a student or educator using the Licensed Work for educational purposes
        2. **Small Business:** Your organization has **5 or fewer total employees**
        3. **Personal/Research:** You are using the Licensed Work for personal projects or academic research
        4. **Evaluation:** You are evaluating the Licensed Work for up to 30 days
        
        ### Usage Limits - Commercial License Required
        
        A **Commercial License is REQUIRED** if:
        
        1. Your organization has **6 or more employees**, AND
        2. You are using the Licensed Work in a production environment, OR
        3. You are using the Licensed Work to provide services to third parties
        
        **Commercial License:** $99 USD per developer per year
        
        - "Developer" means any employee, contractor, or agent who uses, modifies, or deploys the Licensed Work
        - One license covers all environments (development, staging, production, CI/CD)
        - License includes updates and support
        - Purchase at: https://smartaimemory.com/empathy-framework/pricing
        
        ### Restrictions
        
        You may NOT:
        
        1. **Remove or modify** licensing, copyright notices, or attribution
        2. **Circumvent** the usage limits or commercial license requirements
        3. **Offer as a managed service** without a separate reseller agreement
        4. **Sublicense, sell, or rent** the Licensed Work to third parties
        5. **Use the Licensed Work** in violation of applicable laws
        
        ### Source Code Availability
        
        The source code for the Licensed Work is available at:
        https://github.com/Smart-AI-Memory/empathy
        
        You may view, inspect, and audit the source code for:
        - Security review
        - Compliance verification
        - Understanding implementation
        - Creating derivative works (subject to this license)
        
        ### Attribution
        
        If you distribute the Licensed Work or derivative works, you must:
        
        1. Include this license file
        2. Provide attribution to "Deep Study AI, LLC - Empathy"
        3. Include a link to https://github.com/Smart-AI-Memory/empathy
        
        ### Warranty Disclaimer
        
        THE LICENSED WORK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
        
        ### Liability Limitation
        
        IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE LICENSED WORK.
        
        ### Change Date Conversion
        
        On the Change Date (January 1, 2029), this license automatically converts to the Change License (Apache License 2.0), and all restrictions in this Fair Source License no longer apply.
        
        **Rationale:** After 4 years, the Licensed Work becomes fully open source, allowing maximum community benefit while protecting Licensor's commercial interests during the critical growth period.
        
        ### Verification Rights
        
        Licensor reserves the right to:
        
        1. Request verification of compliance with usage limits
        2. Audit use of the Licensed Work with reasonable notice
        3. Terminate licenses for violations after 30-day cure period
        
        ### Commercial License Purchase
        
        To purchase a Commercial License:
        
        1. Visit: https://smartaimemory.com/empathy-framework/pricing
        2. Email: admin@smartaimemory.com
        3. Complete order form and payment
        4. Receive license key and invoice
        
        Volume discounts available for teams of 20+ developers.
        
        ### Definitions
        
        - **Employee:** Any W-2 employee, 1099 contractor working >20 hours/week, or intern
        - **Production Environment:** Any environment serving end users or customers
        - **Developer:** Any person who uses, modifies, or deploys the Licensed Work
        - **Organization:** The legal entity employing you, or yourself if self-employed
        
        ### Questions?
        
        For licensing questions, contact: licensing@smartaimemory.com
        
        ---
        
        ## Why Fair Source?
        
        This license balances:
        
        ✅ **Free for small teams** - Students, educators, and small businesses (≤5 employees) use free forever
        ✅ **Source code visibility** - Review code for security, compliance, learning
        ✅ **Commercial sustainability** - Larger organizations pay to fund development
        ✅ **Future open source** - Automatically becomes Apache 2.0 in 4 years
        
        We believe software should be inspectable and accessible while ensuring sustainable development.
        
        ---
        
        **Version:** 0.9
        **Last Updated:** November 7, 2025
        **Effective Date:** January 1, 2025
        
Project-URL: Homepage, https://www.smartaimemory.com
Project-URL: Documentation, https://www.smartaimemory.com/framework-docs/
Project-URL: Getting Started, https://www.smartaimemory.com/framework-docs/tutorials/quickstart/
Project-URL: FAQ, https://www.smartaimemory.com/framework-docs/reference/FAQ/
Project-URL: Book, https://www.smartaimemory.com/book
Project-URL: Repository, https://github.com/Smart-AI-Memory/empathy-framework
Project-URL: Issues, https://github.com/Smart-AI-Memory/empathy-framework/issues
Project-URL: Discussions, https://github.com/Smart-AI-Memory/empathy-framework/discussions
Project-URL: Changelog, https://github.com/Smart-AI-Memory/empathy-framework/blob/main/CHANGELOG.md
Keywords: ai,collaboration,empathy,anticipatory-ai,systems-thinking,llm,claude,memdocs,level-5-ai,code-inspection,static-analysis,code-quality,sarif,github-actions,developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3.0.0,>=2.0.0
Requires-Dist: typing-extensions<5.0.0,>=4.0.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.0
Requires-Dist: structlog<25.0.0,>=23.0.0
Requires-Dist: defusedxml<1.0.0,>=0.7.0
Requires-Dist: rich<14.0.0,>=13.0.0
Requires-Dist: typer<1.0.0,>=0.9.0
Provides-Extra: anthropic
Requires-Dist: anthropic<1.0.0,>=0.8.0; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai<2.0.0,>=1.6.0; extra == "openai"
Provides-Extra: google
Requires-Dist: google-generativeai<1.0.0,>=0.8.0; extra == "google"
Provides-Extra: llm
Requires-Dist: anthropic<1.0.0,>=0.8.0; extra == "llm"
Requires-Dist: openai<2.0.0,>=1.6.0; extra == "llm"
Requires-Dist: google-generativeai<1.0.0,>=0.8.0; extra == "llm"
Provides-Extra: memdocs
Requires-Dist: memdocs>=1.0.0; extra == "memdocs"
Provides-Extra: agents
Requires-Dist: langchain<0.3.0,>=0.1.0; extra == "agents"
Requires-Dist: langchain-core<0.3.0,>=0.1.0; extra == "agents"
Requires-Dist: langgraph<0.2.0,>=0.1.0; extra == "agents"
Provides-Extra: crewai
Requires-Dist: crewai<1.0.0,>=0.1.0; extra == "crewai"
Provides-Extra: healthcare
Requires-Dist: python-docx<1.0.0,>=0.8.11; extra == "healthcare"
Requires-Dist: pyyaml<7.0,>=6.0; extra == "healthcare"
Requires-Dist: redis<6.0.0,>=5.0.0; extra == "healthcare"
Provides-Extra: software
Requires-Dist: python-docx<1.0.0,>=0.8.11; extra == "software"
Requires-Dist: pyyaml<7.0,>=6.0; extra == "software"
Provides-Extra: backend
Requires-Dist: fastapi<1.0.0,>=0.109.1; extra == "backend"
Requires-Dist: uvicorn<1.0.0,>=0.20.0; extra == "backend"
Requires-Dist: starlette<1.0.0,>=0.40.0; extra == "backend"
Requires-Dist: PyJWT[crypto]>=2.8.0; extra == "backend"
Provides-Extra: lsp
Requires-Dist: pygls<2.0.0,>=1.0.0; extra == "lsp"
Requires-Dist: lsprotocol<2024.0.0,>=2023.0.0; extra == "lsp"
Provides-Extra: windows
Requires-Dist: colorama<1.0.0,>=0.4.6; extra == "windows"
Provides-Extra: docs
Requires-Dist: mkdocs<2.0.0,>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material<10.0.0,>=9.4.0; extra == "docs"
Requires-Dist: mkdocstrings[python]<1.0.0,>=0.24.0; extra == "docs"
Requires-Dist: mkdocs-with-pdf<1.0.0,>=0.9.3; extra == "docs"
Requires-Dist: pymdown-extensions<11.0,>=10.0; extra == "docs"
Provides-Extra: dev
Requires-Dist: pytest<9.0,>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio<1.0,>=0.21; extra == "dev"
Requires-Dist: pytest-cov<5.0,>=4.0; extra == "dev"
Requires-Dist: black<26.0,>=24.3.0; extra == "dev"
Requires-Dist: mypy<2.0,>=1.0; extra == "dev"
Requires-Dist: ruff<1.0,>=0.1; extra == "dev"
Requires-Dist: coverage<8.0,>=7.0; extra == "dev"
Requires-Dist: bandit<2.0,>=1.7; extra == "dev"
Requires-Dist: pre-commit<4.0,>=3.0; extra == "dev"
Requires-Dist: httpx<1.0.0,>=0.27.0; extra == "dev"
Requires-Dist: fastapi<1.0.0,>=0.109.1; extra == "dev"
Provides-Extra: full
Requires-Dist: anthropic<1.0.0,>=0.8.0; extra == "full"
Requires-Dist: openai<2.0.0,>=1.6.0; extra == "full"
Requires-Dist: google-generativeai<1.0.0,>=0.8.0; extra == "full"
Requires-Dist: memdocs>=1.0.0; extra == "full"
Requires-Dist: langchain<0.3.0,>=0.1.0; extra == "full"
Requires-Dist: langchain-core<0.3.0,>=0.1.0; extra == "full"
Requires-Dist: langgraph<0.2.0,>=0.1.0; extra == "full"
Requires-Dist: python-docx<1.0.0,>=0.8.11; extra == "full"
Requires-Dist: pyyaml<7.0,>=6.0; extra == "full"
Provides-Extra: all
Requires-Dist: anthropic<1.0.0,>=0.8.0; extra == "all"
Requires-Dist: openai<2.0.0,>=1.6.0; extra == "all"
Requires-Dist: google-generativeai<1.0.0,>=0.8.0; extra == "all"
Requires-Dist: memdocs>=1.0.0; extra == "all"
Requires-Dist: langchain<0.3.0,>=0.1.0; extra == "all"
Requires-Dist: langchain-core<0.3.0,>=0.1.0; extra == "all"
Requires-Dist: langgraph<0.2.0,>=0.1.0; extra == "all"
Requires-Dist: python-docx<1.0.0,>=0.8.11; extra == "all"
Requires-Dist: pyyaml<7.0,>=6.0; extra == "all"
Requires-Dist: fastapi<1.0.0,>=0.109.1; extra == "all"
Requires-Dist: uvicorn<1.0.0,>=0.20.0; extra == "all"
Requires-Dist: starlette<1.0.0,>=0.40.0; extra == "all"
Requires-Dist: pygls<2.0.0,>=1.0.0; extra == "all"
Requires-Dist: lsprotocol<2024.0.0,>=2023.0.0; extra == "all"
Requires-Dist: colorama<1.0.0,>=0.4.6; extra == "all"
Requires-Dist: mkdocs<2.0.0,>=1.5.0; extra == "all"
Requires-Dist: mkdocs-material<10.0.0,>=9.4.0; extra == "all"
Requires-Dist: mkdocstrings[python]<1.0.0,>=0.24.0; extra == "all"
Requires-Dist: mkdocs-with-pdf<1.0.0,>=0.9.3; extra == "all"
Requires-Dist: pymdown-extensions<11.0,>=10.0; extra == "all"
Requires-Dist: pytest<9.0,>=7.0; extra == "all"
Requires-Dist: pytest-asyncio<1.0,>=0.21; extra == "all"
Requires-Dist: pytest-cov<5.0,>=4.0; extra == "all"
Requires-Dist: black<26.0,>=24.3.0; extra == "all"
Requires-Dist: mypy<2.0,>=1.0; extra == "all"
Requires-Dist: ruff<1.0,>=0.1; extra == "all"
Requires-Dist: coverage<8.0,>=7.0; extra == "all"
Requires-Dist: bandit<2.0,>=1.7; extra == "all"
Requires-Dist: pre-commit<4.0,>=3.0; extra == "all"
Requires-Dist: httpx<1.0.0,>=0.27.0; extra == "all"
Requires-Dist: urllib3<3.0.0,>=2.3.0; extra == "all"
Requires-Dist: aiohttp<4.0.0,>=3.10.0; extra == "all"
Requires-Dist: filelock<4.0.0,>=3.16.0; extra == "all"
Dynamic: license-file

# Empathy Framework

**The AI collaboration framework that predicts problems before they happen.**

[![PyPI](https://img.shields.io/pypi/v/empathy-framework)](https://pypi.org/project/empathy-framework/)
[![Tests](https://img.shields.io/badge/tests-5%2C603%20passing-brightgreen)](https://github.com/Smart-AI-Memory/empathy-framework/actions)
[![Coverage](https://img.shields.io/badge/coverage-64%25-yellow)](https://github.com/Smart-AI-Memory/empathy-framework)
[![License](https://img.shields.io/badge/license-Fair%20Source%200.9-blue)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10+-blue)](https://www.python.org)

```bash
pip install empathy-framework[full]
```

## What's New in v3.5.x

### 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
- **80-96% Cost Savings** — Smart tier routing: cheap models detect, best models decide
- **VSCode Dashboard** — 10 integrated workflows with input history persistence

---

## Quick Start (2 Minutes)

### 1. Install

```bash
pip install empathy-framework[full]
```

### 2. Configure Provider

```bash
# 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

```python
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** | 80-96% savings | N/A | No |
| **Your data stays local** | Yes | Cloud | Cloud |
| **Free for small teams** | ≤5 employees | No | No |

---

## Become a Power User

### Level 1: Basic Usage

```bash
pip install empathy-framework
```

- Works out of the box with sensible defaults
- Auto-detects your API keys

### Level 2: Cost Optimization

```bash
# Enable hybrid mode for 80-96% cost savings
python -m empathy_os.models.cli provider --set hybrid
```

| Tier | Model | Use Case | Cost |
|------|-------|----------|------|
| Cheap | GPT-4o-mini / Haiku | Summarization, simple tasks | $0.15-0.25/M |
| Capable | GPT-4o / Sonnet | Bug fixing, code review | $2.50-3.00/M |
| Premium | o1 / Opus | Architecture, complex decisions | $15/M |

### Level 3: Multi-Model Workflows

```python
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`

```yaml
memory:
  enabled: true
  auto_start_redis: true
```

### Level 5: Custom Agents

```python
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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:

```yaml
# .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`

```python
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:

```python
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:

```python
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:

```python
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:

```yaml
# .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]
```

```python
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:

```python
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

```bash
# 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

```bash
# 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](https://github.com/Smart-AI-Memory/empathy-framework)** if you find it useful
- **[Join Discussions](https://github.com/Smart-AI-Memory/empathy-framework/discussions)** — Questions, ideas, show what you built
- **[Read the Book](https://smartaimemory.com/book)** — Deep dive into the philosophy
- **[Full Documentation](https://smartaimemory.com/framework-docs/)** — API reference, examples, guides

---

## Project Evolution

For those interested in the development history and architectural decisions:

- **[Development Logs](docs/development-logs/)** — Execution plans, phase completions, and progress tracking
- **[Architecture Docs](docs/architecture/)** — System design, memory architecture, and integration plans
- **[Marketing Materials](docs/marketing/)** — Pitch decks, outreach templates, and commercial readiness
- **[Guides](docs/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 →](LICENSE)

---

**Built by [Smart AI Memory](https://smartaimemory.com)** · [Documentation](https://smartaimemory.com/framework-docs/) · [Examples](examples/) · [Issues](https://github.com/Smart-AI-Memory/empathy-framework/issues)
