Metadata-Version: 2.4
Name: empathy-framework
Version: 5.0.3
Summary: AI collaboration framework with real LLM agent execution, AskUserQuestion tool integration, Socratic agent generation, progressive tier escalation (70-85% cost savings), meta-orchestration, dynamic agent composition (6 patterns), intelligent caching (85% hit rate), semantic workflow discovery, visual workflow editor, MCP integration for Claude Code, and multi-agent orchestration.
Author-email: Patrick Roebuck <admin@smartaimemory.com>
Maintainer-email: Smart-AI-Memory <admin@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<26.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
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: anthropic<1.0.0,>=0.25.0
Provides-Extra: anthropic
Requires-Dist: anthropic<1.0.0,>=0.25.0; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai<2.0.0,>=1.12.0; extra == "openai"
Provides-Extra: google
Requires-Dist: google-generativeai<1.0.0,>=0.3.0; extra == "google"
Provides-Extra: llm
Requires-Dist: anthropic<1.0.0,>=0.25.0; extra == "llm"
Requires-Dist: openai<2.0.0,>=1.12.0; extra == "llm"
Requires-Dist: google-generativeai<1.0.0,>=0.3.0; extra == "llm"
Provides-Extra: memdocs
Requires-Dist: memdocs>=1.0.0; extra == "memdocs"
Provides-Extra: agents
Requires-Dist: langchain<2.0.0,>=1.0.0; extra == "agents"
Requires-Dist: langchain-core<2.0.0,>=1.2.5; extra == "agents"
Requires-Dist: langchain-text-splitters<0.4.0,>=0.3.9; extra == "agents"
Requires-Dist: langgraph<2.0.0,>=1.0.0; extra == "agents"
Requires-Dist: langgraph-checkpoint<4.0.0,>=3.0.0; extra == "agents"
Requires-Dist: marshmallow<5.0.0,>=4.1.2; extra == "agents"
Provides-Extra: crewai
Requires-Dist: crewai<1.0.0,>=0.1.0; extra == "crewai"
Requires-Dist: langchain<2.0.0,>=0.1.0; extra == "crewai"
Requires-Dist: langchain-core<2.0.0,>=1.2.6; extra == "crewai"
Provides-Extra: cache
Requires-Dist: sentence-transformers<4.0.0,>=2.0.0; extra == "cache"
Requires-Dist: torch<3.0.0,>=2.0.0; extra == "cache"
Requires-Dist: numpy<3.0.0,>=1.24.0; extra == "cache"
Provides-Extra: healthcare
Requires-Dist: anthropic<1.0.0,>=0.25.0; extra == "healthcare"
Requires-Dist: openai<2.0.0,>=1.12.0; extra == "healthcare"
Requires-Dist: google-generativeai<1.0.0,>=0.3.0; extra == "healthcare"
Requires-Dist: memdocs>=1.0.0; extra == "healthcare"
Requires-Dist: langchain<2.0.0,>=1.0.0; extra == "healthcare"
Requires-Dist: langchain-core<2.0.0,>=1.2.5; extra == "healthcare"
Requires-Dist: langchain-text-splitters<0.4.0,>=0.3.9; extra == "healthcare"
Requires-Dist: langgraph<2.0.0,>=1.0.0; extra == "healthcare"
Requires-Dist: langgraph-checkpoint<4.0.0,>=3.0.0; extra == "healthcare"
Requires-Dist: marshmallow<5.0.0,>=4.1.2; 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: fastapi<1.0.0,>=0.109.1; extra == "healthcare"
Requires-Dist: uvicorn<1.0.0,>=0.20.0; extra == "healthcare"
Requires-Dist: starlette<1.0.0,>=0.40.0; extra == "healthcare"
Requires-Dist: bcrypt<5.0.0,>=4.0.0; extra == "healthcare"
Requires-Dist: PyJWT[crypto]>=2.8.0; extra == "healthcare"
Requires-Dist: opentelemetry-api<2.0.0,>=1.20.0; extra == "healthcare"
Requires-Dist: opentelemetry-sdk<2.0.0,>=1.20.0; extra == "healthcare"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0.0,>=1.20.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: bcrypt<5.0.0,>=4.0.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: otel
Requires-Dist: opentelemetry-api<2.0.0,>=1.20.0; extra == "otel"
Requires-Dist: opentelemetry-sdk<2.0.0,>=1.20.0; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0.0,>=1.20.0; extra == "otel"
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<10.0,>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio<2.0,>=0.21; extra == "dev"
Requires-Dist: pytest-cov<8.0,>=4.0; extra == "dev"
Requires-Dist: pytest-xdist<4.0,>=3.5.0; extra == "dev"
Requires-Dist: pytest-testmon<3.0,>=2.1.0; extra == "dev"
Requires-Dist: pytest-picked<1.0,>=0.5.0; extra == "dev"
Requires-Dist: black<27.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<5.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"
Requires-Dist: requests<3.0.0,>=2.28.0; extra == "dev"
Provides-Extra: developer
Requires-Dist: anthropic<1.0.0,>=0.25.0; extra == "developer"
Requires-Dist: openai<2.0.0,>=1.12.0; extra == "developer"
Requires-Dist: google-generativeai<1.0.0,>=0.3.0; extra == "developer"
Requires-Dist: memdocs>=1.0.0; extra == "developer"
Requires-Dist: langchain<2.0.0,>=1.0.0; extra == "developer"
Requires-Dist: langchain-core<2.0.0,>=1.2.5; extra == "developer"
Requires-Dist: langchain-text-splitters<0.4.0,>=0.3.9; extra == "developer"
Requires-Dist: langgraph<2.0.0,>=1.0.0; extra == "developer"
Requires-Dist: langgraph-checkpoint<4.0.0,>=3.0.0; extra == "developer"
Requires-Dist: marshmallow<5.0.0,>=4.1.2; extra == "developer"
Requires-Dist: python-docx<1.0.0,>=0.8.11; extra == "developer"
Requires-Dist: pyyaml<7.0,>=6.0; extra == "developer"
Provides-Extra: enterprise
Requires-Dist: anthropic<1.0.0,>=0.25.0; extra == "enterprise"
Requires-Dist: openai<2.0.0,>=1.12.0; extra == "enterprise"
Requires-Dist: google-generativeai<1.0.0,>=0.3.0; extra == "enterprise"
Requires-Dist: memdocs>=1.0.0; extra == "enterprise"
Requires-Dist: langchain<2.0.0,>=1.0.0; extra == "enterprise"
Requires-Dist: langchain-core<2.0.0,>=1.2.5; extra == "enterprise"
Requires-Dist: langchain-text-splitters<0.4.0,>=0.3.9; extra == "enterprise"
Requires-Dist: langgraph<2.0.0,>=1.0.0; extra == "enterprise"
Requires-Dist: langgraph-checkpoint<4.0.0,>=3.0.0; extra == "enterprise"
Requires-Dist: marshmallow<5.0.0,>=4.1.2; extra == "enterprise"
Requires-Dist: python-docx<1.0.0,>=0.8.11; extra == "enterprise"
Requires-Dist: pyyaml<7.0,>=6.0; extra == "enterprise"
Requires-Dist: fastapi<1.0.0,>=0.109.1; extra == "enterprise"
Requires-Dist: uvicorn<1.0.0,>=0.20.0; extra == "enterprise"
Requires-Dist: starlette<1.0.0,>=0.40.0; extra == "enterprise"
Requires-Dist: bcrypt<5.0.0,>=4.0.0; extra == "enterprise"
Requires-Dist: PyJWT[crypto]>=2.8.0; extra == "enterprise"
Requires-Dist: opentelemetry-api<2.0.0,>=1.20.0; extra == "enterprise"
Requires-Dist: opentelemetry-sdk<2.0.0,>=1.20.0; extra == "enterprise"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0.0,>=1.20.0; extra == "enterprise"
Provides-Extra: full
Requires-Dist: anthropic<1.0.0,>=0.25.0; extra == "full"
Requires-Dist: openai<2.0.0,>=1.12.0; extra == "full"
Requires-Dist: google-generativeai<1.0.0,>=0.3.0; extra == "full"
Requires-Dist: memdocs>=1.0.0; extra == "full"
Requires-Dist: langchain<2.0.0,>=1.0.0; extra == "full"
Requires-Dist: langchain-core<2.0.0,>=1.2.5; extra == "full"
Requires-Dist: langchain-text-splitters<0.4.0,>=0.3.9; extra == "full"
Requires-Dist: langgraph<2.0.0,>=1.0.0; extra == "full"
Requires-Dist: langgraph-checkpoint<4.0.0,>=3.0.0; extra == "full"
Requires-Dist: marshmallow<5.0.0,>=4.1.2; 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.25.0; extra == "all"
Requires-Dist: openai<2.0.0,>=1.12.0; extra == "all"
Requires-Dist: google-generativeai<1.0.0,>=0.3.0; extra == "all"
Requires-Dist: memdocs>=1.0.0; extra == "all"
Requires-Dist: langchain<2.0.0,>=1.0.0; extra == "all"
Requires-Dist: langchain-core<2.0.0,>=1.2.5; extra == "all"
Requires-Dist: langchain-text-splitters<0.4.0,>=0.3.9; extra == "all"
Requires-Dist: langgraph<2.0.0,>=1.0.0; extra == "all"
Requires-Dist: langgraph-checkpoint<4.0.0,>=3.0.0; extra == "all"
Requires-Dist: marshmallow<5.0.0,>=4.1.2; 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: bcrypt<5.0.0,>=4.0.0; extra == "all"
Requires-Dist: PyJWT[crypto]>=2.8.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: opentelemetry-api<2.0.0,>=1.20.0; extra == "all"
Requires-Dist: opentelemetry-sdk<2.0.0,>=1.20.0; extra == "all"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2.0.0,>=1.20.0; 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<10.0,>=7.0; extra == "all"
Requires-Dist: pytest-asyncio<2.0,>=0.21; extra == "all"
Requires-Dist: pytest-cov<8.0,>=4.0; extra == "all"
Requires-Dist: black<27.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<5.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

**AI-powered developer workflows with cost optimization and pattern learning.**

Run code review, debugging, testing, and release workflows from your terminal or Claude Code. Smart tier routing saves 34-86% on LLM costs.

[![PyPI](https://img.shields.io/pypi/v/empathy-framework?color=blue)](https://pypi.org/project/empathy-framework/)
[![Tests](https://img.shields.io/badge/tests-7%2C168%20passing%20(99.9%25)-brightgreen)](https://github.com/Smart-AI-Memory/empathy-framework/actions)
[![Python](https://img.shields.io/badge/python-3.10+-blue)](https://www.python.org)
[![License](https://img.shields.io/badge/license-Fair%20Source%200.9-blue)](LICENSE)
[![Performance](https://img.shields.io/badge/performance-18x%20faster-success)](https://github.com/Smart-AI-Memory/empathy-framework/blob/main/CHANGELOG.md)

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

---

## 🎯 Transitioning to Claude-Native Architecture

**Empathy Framework is evolving to focus exclusively on Anthropic/Claude** to unlock features impossible with multi-provider abstraction:

- **📦 Prompt Caching:** 90% cost reduction on repeated prompts
- **📖 200K Context:** Largest context window available (vs 128K for competitors)
- **🧠 Extended Thinking:** See Claude's internal reasoning process
- **🔧 Advanced Tool Use:** Optimized for agentic workflows

**Timeline:**
- ✅ **v4.8.0 (Jan 2026):** Deprecation warnings for OpenAI/Google/Ollama providers
- ✅ **v5.0.0 (Jan 26, 2026):** Non-Anthropic providers removed (BREAKING - COMPLETE)
- ✅ **v5.0.2 (Jan 28, 2026):** Cost optimization suite with batch processing and caching monitoring

**Migration Guide:** [docs/CLAUDE_NATIVE.md](docs/CLAUDE_NATIVE.md)

---

## What's New in v5.0.2

**💰 50% Cost Savings with Batch API** - Process non-urgent tasks asynchronously:

```bash
empathy batch submit batch_requests.json  # Submit batch job
empathy batch status msgbatch_abc123      # Check progress
empathy batch results msgbatch_abc123 output.json  # Download results
```

Perfect for: log analysis, report generation, bulk classification, test generation

**📊 Precise Token Counting** - >98% accurate cost tracking:

- Integrated Anthropic's `count_tokens()` API for billing-accurate measurements
- 3-tier fallback: API → tiktoken (local) → heuristic
- Cache-aware cost calculation (25% write markup, 90% read discount)

**📈 Cache Performance Monitoring** - Track your 20-30% caching savings:

```bash
empathy cache stats           # Show hit rates and cost savings
empathy cache stats --verbose # Detailed token metrics
empathy cache stats --format json  # Machine-readable output
```

**🧭 Adaptive Routing Analytics** - Intelligent tier recommendations:

```bash
empathy routing stats <workflow>    # Performance metrics
empathy routing check --all         # Tier upgrade recommendations
empathy routing models --provider anthropic  # Compare models
```

**🔧 Dashboard Fixes** - All 6 agent coordination patterns now operational:
- Agent heartbeats displaying correctly
- Event streaming functional
- Coordination signals working
- Approval gates operational

[See Full Changelog](CHANGELOG.md#502---2026-01-28) | [Batch API Guide](docs/BATCH_API_GUIDE.md) | [User API Docs](docs/USER_API_DOCUMENTATION.md)

---

## What's New in v4.9.0

**⚡ 18x Faster Performance** - Massive performance gains through Phase 2 optimizations:

- **Redis Two-Tier Caching:** 2x faster memory operations (37,000x for cached keys)
- **Generator Expressions:** 99.9% memory reduction across 27 optimizations
- **Parallel Scanning:** Multi-core processing enabled by default (2-4x faster)
- **Incremental Scanning:** Git diff-based updates (10x faster)

**🧭 Natural Language Workflows** - Use plain English instead of workflow names:

```bash
/workflows "find security vulnerabilities"  # → security-audit
/workflows "check code performance"         # → perf-audit
/workflows "predict bugs"                   # → bug-predict
/plan "review my code"                      # → code-review
```

**📊 Real-World Performance:**

- Combined workflow: 3.59s → 0.2s (**18x faster**)
- Full scan: 3,472 files in 0.98s (was 3.59s)
- Redis cached operations: 37ms → 0.001ms

**🎯 Improved Navigation:**

- Split `/workflow` into `/workflows` (automated analysis) and `/plan` (planning/review)
- Clearer hub organization with better categorization
- Natural language routing matches intent to workflow

[See CHANGELOG.md](CHANGELOG.md) | [Performance Docs](docs/REDIS_OPTIMIZATION_SUMMARY.md)

---

## What's New in v4.7.0

**$0 Workflows via Skills** - Multi-agent workflows run through Claude Code's Task tool instead of API calls. No additional cost with your Claude subscription.

**Socratic Workflows** - Interactive discovery through guided questions. Workflows ask what you need rather than requiring upfront configuration.

**Security Hardened** - Fixed critical vulnerabilities (path traversal, JWT, SSRF).

**Hub-Based Commands** - Organized workflows into intuitive command hubs.

---

## Quick Start

### 1. Install

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

### 2. Configure

```bash
# Auto-detect API keys
python -m empathy_os.models.cli provider

# Or set explicitly
python -m empathy_os.models.cli provider --set anthropic
```

### 3. Use

**In Claude Code:**

```bash
/dev           # Developer tools (debug, commit, PR, review)
/testing       # Run tests, coverage, benchmarks
/workflows     # Automated analysis (security, bugs, perf)
/plan          # Planning, TDD, code review
/docs          # Documentation generation
/release       # Release preparation

# Natural language support:
/workflows "find security issues"
/plan "review my code"
```

**CLI:**

```bash
empathy workflow run security-audit --path ./src
empathy workflow run test-coverage --target 90
empathy telemetry show  # View cost savings
```

**Python:**

```python
from empathy_os import EmpathyOS

async with EmpathyOS() as empathy:
    result = await empathy.level_2_guided(
        "Review this code for security issues"
    )
    print(result["response"])
```

---

## Command Hubs

Workflows are organized into hubs for easy discovery:

| Hub               | Command       | Description                                  |
| ----------------- | ------------- | -------------------------------------------- |
| **Developer**     | `/dev`        | Debug, commit, PR, code review, quality      |
| **Testing**       | `/testing`    | Run tests, coverage analysis, benchmarks     |
| **Documentation** | `/docs`       | Generate and manage documentation            |
| **Release**       | `/release`    | Release prep, security scan, publishing      |
| **Workflows**     | `/workflows`  | Automated analysis (security, bugs, perf)    |
| **Plan**          | `/plan`       | Planning, TDD, code review, refactoring      |
| **Utilities**     | `/utilities`  | Project init, dependencies, profiling        |
| **Learning**      | `/learning`   | Pattern learning and session evaluation      |
| **Context**       | `/context`    | State management and memory                  |
| **Agent**         | `/agent`      | Create and manage custom agents              |

**Natural Language Support:**

```bash
# Use plain English - intelligent routing matches your intent
/workflows "find security vulnerabilities"  # → security-audit
/workflows "check code performance"         # → perf-audit
/workflows "predict bugs"                   # → bug-predict
/plan "review my code"                      # → code-review
/plan "help me plan this feature"           # → planning

# Or use traditional workflow names
/workflows security-audit
/plan code-review
```

**Interactive menus:**

```bash
/dev                    # Show interactive menu
/dev "debug auth error" # Jump directly to debugging
/testing "run coverage" # Run coverage analysis
/release                # Start release preparation
```

---

## Socratic Method

Workflows guide you through discovery instead of requiring upfront configuration:

```text
You: /dev

Claude: What development task do you need?
  1. Debug issue
  2. Create commit
  3. PR workflow
  4. Quality check

You: 1

Claude: What error or unexpected behavior are you seeing?
```

**How it works:**

1. **Discovery** - Workflow asks targeted questions to understand your needs
2. **Context gathering** - Collects relevant code, errors, and constraints
3. **Dynamic agent creation** - Assembles the right team based on your answers
4. **Execution** - Runs with appropriate tier selection

**Create custom agents with Socratic guidance:**

```bash
/agent create    # Guided agent creation
/agent team      # Build multi-agent teams interactively
```

---

## Cost Optimization

### Skills = $0 (Claude Code)

When using Claude Code, workflows run as skills through the Task tool - **no API costs**:

```bash
/dev           # $0 - uses your Claude subscription
/testing       # $0
/release       # $0
/agent create  # $0
```

### API Mode (CI/CD, Automation)

For programmatic use, smart tier routing saves 34-86%:

| Tier    | Model               | Use Case                    | Cost        |
| ------- | ------------------- | --------------------------- | ----------- |
| CHEAP   | Haiku / GPT-4o-mini | Formatting, simple tasks    | ~$0.005     |
| CAPABLE | Sonnet / GPT-4o     | Bug fixes, code review      | ~$0.08      |
| PREMIUM | Opus / o1           | Architecture, complex design | ~$0.45      |

```bash
# Track API usage and savings
empathy telemetry savings --days 30
```

---

## Key Features

### Multi-Agent Workflows

```bash
# 4 parallel agents check release readiness
empathy orchestrate release-prep

# Sequential coverage improvement
empathy orchestrate test-coverage --target 90
```

### Response Caching

Up to 57% cache hit rate on similar prompts. Zero config needed.

```python
from empathy_os.workflows import SecurityAuditWorkflow

workflow = SecurityAuditWorkflow(enable_cache=True)
result = await workflow.execute(target_path="./src")
print(f"Cache hit rate: {result.cost_report.cache_hit_rate:.1f}%")
```

### Pattern Learning

Workflows learn from outcomes and improve over time:

```python
from empathy_os.orchestration.config_store import ConfigurationStore

store = ConfigurationStore()
best = store.get_best_for_task("release_prep")
print(f"Success rate: {best.success_rate:.1%}")
```

### Multi-Provider Support

```python
from empathy_llm_toolkit.providers import (
    AnthropicProvider,  # Claude
    OpenAIProvider,     # GPT-4
    GeminiProvider,     # Gemini
    LocalProvider,      # Ollama, LM Studio
)
```

---

## CLI Reference

```bash
# Provider configuration
python -m empathy_os.models.cli provider
python -m empathy_os.models.cli provider --set hybrid

# Workflows
empathy workflow list
empathy workflow run <workflow-name>

# Cost tracking
empathy telemetry show
empathy telemetry savings --days 30
empathy telemetry export --format csv

# Orchestration
empathy orchestrate release-prep
empathy orchestrate test-coverage --target 90

# Meta-workflows
empathy meta-workflow list
empathy meta-workflow run release-prep --real
```

---

## Install Options

```bash
# Individual developers (recommended)
pip install empathy-framework[developer]

# All LLM providers
pip install empathy-framework[llm]

# With caching (semantic similarity)
pip install empathy-framework[cache]

# Enterprise (auth, rate limiting)
pip install empathy-framework[enterprise]

# Healthcare (HIPAA compliance)
pip install empathy-framework[healthcare]

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

---

## Environment Setup

```bash
# At least one provider required
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="..."

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

---

## VSCode Extension

Install the Empathy VSCode extension for:

- **Dashboard** - Health score, costs, patterns
- **One-Click Workflows** - Run from command palette
- **Memory Panel** - Manage Redis and patterns
- **Cost Tracking** - Real-time savings display

---

## Documentation

- [Quick Start Guide](docs/quickstart.md)
- [CLI Reference](docs/cli-reference.md)
- [Testing Guide](docs/testing-guide.md)
- [Keyboard Shortcuts](docs/keyboard-shortcuts.md)
- [Full Documentation](https://smartaimemory.com/framework-docs/)

---

## Security

- Path traversal protection on all file operations
- JWT authentication with rate limiting
- PII scrubbing in telemetry
- HIPAA/GDPR compliance options
- **Automated security scanning** with 82% accuracy (Phase 3 AST-based detection)

See [SECURITY.md](SECURITY.md) for vulnerability reporting.

### Security Scanning

**Automated security scanning in CI/CD** - 82% accuracy, blocks critical issues:

```bash
# Run security audit locally
empathy workflow run security-audit

# Scan specific directory
empathy workflow run security-audit --input '{"path":"./src"}'
```

**Documentation:**

- **[Developer Workflow Guide](docs/DEVELOPER_SECURITY_WORKFLOW.md)** - Quick reference for handling security findings (all developers)
- **[CI/CD Integration Guide](docs/CI_SECURITY_SCANNING.md)** - Complete setup and troubleshooting (DevOps, developers)
- **[Scanner Architecture](docs/SECURITY_SCANNER_ARCHITECTURE.md)** - Technical implementation details (engineers, architects)
- **[Remediation Process](docs/SECURITY_REMEDIATION_PROCESS.md)** - 3-phase methodology for improving scanners (security teams, leadership)
- **[API Reference](docs/api-reference/security-scanner.md)** - Complete API documentation (developers extending scanner)

**Key achievements:**

- 82.3% reduction in false positives (350 → 62 findings)
- 16x improvement in scanner accuracy
- <15 minute average fix time for critical issues
- Zero critical vulnerabilities in production code

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## License

**Fair Source License 0.9** - Free for students, educators, and teams ≤5 employees. Commercial license for larger organizations. [Details →](LICENSE)

---

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