empathy-framework 4.7.0__py3-none-any.whl → 4.8.0__py3-none-any.whl

empathy_framework-4.8.0.dist-info/METADATA

@@ -0,0 +1,753 @@
+Metadata-Version: 2.4
+Name: empathy-framework
+Version: 4.8.0
+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<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
+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<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<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<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
+
+**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)](https://pypi.org/project/empathy-framework/)
+[![Tests](https://img.shields.io/badge/tests-11%2C000%2B%20passing-brightgreen)](https://github.com/Smart-AI-Memory/empathy-framework/actions)
+[![Coverage](https://img.shields.io/badge/coverage-68%25-yellow)](https://github.com/Smart-AI-Memory/empathy-framework)
+[![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)
+
+```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.1.0 (Feb 2026):** Prompt caching enabled by default
+
+**Migration Guide:** [docs/CLAUDE_NATIVE.md](docs/CLAUDE_NATIVE.md)
+
+---
+
+## What's New in v4.8.0
+
+**🚀 Scanner Performance Optimizations** - **3.65x faster** project scanning with parallel processing and incremental updates:
+
+- **Parallel Processing:** Multi-core scanning enabled by default (2x faster)
+- **Incremental Scanning:** Git diff-based updates (10x faster for typical changes)
+- **Optional Dependencies:** Skip dependency analysis for 27% speedup
+
+**📊 Real-World Performance:**
+
+- Full scan: 3,472 files in 1.8s (was 3.6s)
+- Incremental: 100 changed files in 0.3s (was 1.0s)
+
+[See performance guide](docs/SCANNER_OPTIMIZATIONS.md) | [Examples](examples/scanner_usage.py)
+
+---
+
+## 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
+/docs          # Documentation generation
+/release       # Release preparation
+```
+
+**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      |
+| **Workflow**      | `/workflow`  | Planning, TDD, refactoring workflows         |
+| **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              |
+
+**Example usage:**
+
+```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)