empathy-framework 3.2.3__py3-none-any.whl → 3.8.2__py3-none-any.whl

{empathy_framework-3.2.3.dist-info → empathy_framework-3.8.2.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: empathy-framework
-Version: 3.2.3
-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>
+Version: 3.8.2
+Summary: AI collaboration framework with intelligent caching (up to 57% cache hit rate), tier routing (34-86% cost savings depending on task complexity), XML-enhanced prompts, persistent memory, CrewAI integration, and multi-agent orchestration. Includes HIPAA-compliant healthcare wizards.
+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**
@@ -174,24 +174,57 @@ 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
+Requires-Dist: crewai<1.0.0,>=0.1.0
+Requires-Dist: langchain<2.0.0,>=0.1.0
+Requires-Dist: langchain-core<2.0.0,>=0.1.0
 Provides-Extra: anthropic
-Requires-Dist: anthropic<1.0.0,>=0.8.0; extra == "anthropic"
+Requires-Dist: anthropic<1.0.0,>=0.25.0; extra == "anthropic"
 Provides-Extra: openai
-Requires-Dist: openai<2.0.0,>=1.6.0; 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.8.0; extra == "llm"
-Requires-Dist: openai<2.0.0,>=1.6.0; 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<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"
+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"
+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"
@@ -200,12 +233,17 @@ 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"
@@ -222,30 +260,79 @@ 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: 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.8.0; extra == "full"
-Requires-Dist: openai<2.0.0,>=1.6.0; 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<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: 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.8.0; extra == "all"
-Requires-Dist: openai<2.0.0,>=1.6.0; 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<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: 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"
@@ -271,36 +358,202 @@ Dynamic: license-file
 **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-2%2C365%20passing-brightgreen)](https://github.com/Smart-AI-Memory/empathy-framework/actions)
-[![Coverage](https://img.shields.io/badge/coverage-55%25-yellow)](https://github.com/Smart-AI-Memory/empathy-framework)
+[![Tests](https://img.shields.io/badge/tests-5%2C941%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]
+pip install empathy-framework[developer]  # Lightweight for individual developers
+```
+
+## What's New in v3.8.0
+
+### 🎯 **Transparent Cost Claims: Honest Role-Based Savings (34-86%)**
+
+**Real savings depend on your work role.** Architects using 60% PREMIUM tasks see 34% savings, while junior devs see 86%. See [role-based analysis](docs/cost-analysis/COST_SAVINGS_BY_ROLE_AND_PROVIDER.md) for your specific case.
+
+### 🚀 **Intelligent Response Caching: Up to 57% Hit Rate (Benchmarked)**
+
+**Hash-only cache**: 100% hit rate on identical prompts, ~5μs lookups
+**Hybrid cache**: Up to 57% hit rate on semantically similar prompts (measured on security audit workflow)
+
+```python
+from empathy_os.cache import create_cache
+
+# Hash-only mode (fast, exact matches)
+cache = create_cache(cache_type="hash")
+
+# Hybrid mode (semantic similarity)
+cache = create_cache(cache_type="hybrid", similarity_threshold=0.95)
+```
+
+See [caching docs](docs/caching/) for benchmarks and configuration.
+
+---
+
+### Previous Release: v3.7.0
+
+#### 🚀 **XML-Enhanced Prompting: 15-35% Token Reduction + Graceful Validation**
+
+**Slash your API costs and eliminate response parsing errors with production-ready XML enhancements.**
+
+#### Context Window Optimization — **Save 15-35% on Every Request**
+
+```python
+from empathy_os.optimization import ContextOptimizer, CompressionLevel
+
+optimizer = ContextOptimizer(CompressionLevel.MODERATE)
+optimized_prompt = optimizer.optimize(your_xml_prompt)
+# Achieves 15-25% token reduction automatically
+```
+
+- **Tag compression**: `<thinking>` → `<t>`, `<answer>` → `<a>` (15+ common tags)
+- **Whitespace optimization**: Removes excess whitespace while preserving structure
+- **Redundancy elimination**: Strips "Please note that", "Make sure to", etc.
+- **Real-world impact**: Integration tests achieved **49.7% reduction** on typical prompts
+- **Bidirectional**: Full decompression to restore original tag names
+
+#### XML Validation — **Never Crash on Malformed Responses Again**
+
+```python
+from empathy_os.validation import validate_xml_response
+
+result = validate_xml_response(llm_response)
+if result.is_valid:
+    data = result.parsed_data
+else:
+    # Fallback extraction worked - you still get partial data
+    data = result.parsed_data or {}
+```
+
+- **Graceful fallback parsing**: Regex extraction when XML is malformed
+- **Optional XSD validation**: Full schema validation with lxml
+- **Schema caching**: Performance optimization for repeated validations
+- **25 comprehensive tests**: Covers edge cases, malformed input, and XSD validation
+
+#### Migration Made Easy
+
+See [XML_WORKFLOW_MIGRATION_GUIDE.md](XML_WORKFLOW_MIGRATION_GUIDE.md) for complete migration guide with:
+
+- XMLAgent/XMLTask patterns with before/after examples
+- Configuration options (`config.xml.use_xml_structure`)
+- Benefits: **40-60% fewer misinterpretations**, **20-30% fewer retries**
+
+**Test Coverage**: **229 new tests** (86 XML enhancement + 143 robustness) — **100% passing**
+
+---
+
+## What's New in v3.6.0
+
+### 💡 **Finally! Error Messages That Actually Help You**
+
+**No more cryptic `NotImplementedError` when extending the framework!**
+
+We completely rewrote error messages across **5 base classes**. Now when you're building plugins or extensions, you get:
+
+✅ **Exactly which method** you need to implement
+✅ **Which base class** to extend
+✅ **Real working examples** from the codebase to copy
+✅ **Clear explanations** of what each method should return
+
+**Before** (frustrating 😤):
+
+```python
+NotImplementedError
+# ...now what? Time to dig through source code for 30 minutes
+```
+
+**After** (helpful 🎯):
+
+```python
+NotImplementedError: BaseLinterParser.parse() must be implemented.
+Create a subclass of BaseLinterParser and implement the parse() method.
+See ESLintParser, PylintParser, or MyPyParser for examples.
+# Perfect! Now I know exactly what to do
 ```
 
-## What's New in v3.1.0
+#### Plus: 9 Integration TODOs Now Link to Working Code
+
+- **Want to add compliance tracking?** → See `ComplianceDatabase` class (agents/compliance_db.py)
+- **Need multi-channel notifications?** → See `NotificationService` class (agents/notifications.py)
+- **Wondering about MemDocs integration?** → We documented why local cache works better (with rationale)
+- **Need secure document storage?** → S3/Azure/SharePoint recommendations with HIPAA requirements
+
+**Impact**: Onboard new contributors in **minutes instead of hours**. Build your first plugin in **one sitting**.
+
+---
+
+### 🔐 Production-Grade Security & Compliance
+
+#### Secure Authentication System ✅ *Deployed in Backend API*
+
+- **Bcrypt password hashing** with cost factor 12 (industry standard 2026)
+- **JWT tokens** with 30-minute expiration and automatic refresh
+- **Rate limiting**: 5 failed attempts = 15-minute lockout (prevents brute force)
+- **18 comprehensive security tests** covering all attack vectors
+- **Status**: Fully integrated into `backend/api/wizard_api.py`
+
+#### HIPAA/GDPR Compliance Database 🛠️ *Infrastructure Ready*
+
+- **Append-only architecture** (INSERT only, no UPDATE/DELETE) - satisfies regulators
+- **Immutable audit trail** for healthcare and enterprise compliance
+- **Compliance gap detection** with severity classification
+- **12 tests** ensuring regulatory compliance
+- **Status**: Production-ready code with [integration points documented](agents/compliance_db.py). See [compliance_anticipation_agent.py](agents/compliance_anticipation_agent.py) for usage examples.
+
+#### Multi-Channel Notification System 🛠️ *Infrastructure Ready*
+
+- **Email** (SMTP), **Slack** (webhooks), **SMS** (Twilio)
+- **Graceful fallback** when channels unavailable
+- **Smart routing**: SMS only for critical alerts (cost optimization)
+- **10 tests** covering all notification scenarios
+- **Status**: Production-ready code with [integration points documented](agents/notifications.py). See TODOs in compliance agent for usage examples.
+
+---
+
+### Previous: Project Indexing & Test Suite Expansion (v3.5.4)
+
+- **Project Indexing System** — JSON-based file tracking with automatic structure scanning, metadata tracking, and CrewAI integration
+- **5,603 Tests** — Comprehensive test coverage at 64% with 30+ new test modules
+- **BaselineManager Fix** — Resolved test isolation bug affecting suppression system
+
+### Memory API Security Hardening (v3.5.0)
+
+- **Input Validation** — Pattern IDs, agent IDs, and classifications validated to prevent path traversal and injection attacks
+- **API Key Authentication** — Bearer token and X-API-Key header support with SHA-256 hash comparison
+- **Rate Limiting** — Per-IP sliding window rate limiting (100 req/min default)
+- **HTTPS/TLS Support** — Optional SSL certificate configuration for encrypted connections
+- **CORS Restrictions** — Configurable allowed origins (localhost-only by default)
+- **Request Size Limits** — 1MB body limit to prevent DoS attacks
+
+### Previous (v3.4.x)
 
-### Agent Intelligence System
-- **Smart Router** — Natural language wizard dispatch: "Fix security in auth.py" → routes to SecurityWizard
-- **Memory Graph** — Cross-wizard knowledge sharing: bugs, fixes, and patterns connected across sessions
-- **Auto-Chaining** — Wizards automatically trigger related wizards based on findings
-- **Prompt Engineering Wizard** — Analyze, generate, and optimize prompts with token cost savings
+- **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
 
-### Resilience Patterns
-- **Retry with Backoff** — Automatic retries with exponential backoff and jitter
-- **Circuit Breaker** — Prevent cascading failures (CLOSED → OPEN → HALF_OPEN states)
-- **Timeout & Fallback** — Graceful degradation with configurable fallbacks
-- **Health Checks** — Monitor system components with configurable thresholds
+### 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)
-- **XML-Enhanced Prompts** — Structured prompts for consistent, parseable LLM responses
-- **Multi-Model Provider System** — Choose Anthropic, OpenAI, Ollama, or Hybrid mode
-- **80-96% Cost Savings** — Smart tier routing: cheap models detect, best models decide
+
+- **Multi-Model Provider System** — Anthropic, OpenAI, Google Gemini, Ollama, or Hybrid mode
+- **34-86% Cost Savings** — Smart tier routing varies by role: architects 34%, senior devs 65%, junior devs 86%*
 - **VSCode Dashboard** — 10 integrated workflows with input history persistence
-- **Security Hardening** — Fixed command injection vulnerabilities in VSCode extension
-- **Provider Auto-Detection** — Automatically configures based on your API keys
+
+*See [Cost Savings Analysis](docs/cost-analysis/COST_SAVINGS_BY_ROLE_AND_PROVIDER.md) for your specific use case
 
 ---
 
@@ -308,10 +561,37 @@ pip install empathy-framework[full]
 
 ### 1. Install
 
+**Individual Developers (Recommended):**
+
 ```bash
-pip install empathy-framework[full]
+pip install empathy-framework[developer]
+```
+
+**Teams/Enterprises (Backend + Auth):**
+
+```bash
+pip install empathy-framework[enterprise]
+```
+
+**Healthcare Organizations (HIPAA/GDPR Compliance):**
+
+```bash
+pip install empathy-framework[healthcare]
 ```
 
+<details>
+<summary><b>What's the difference?</b></summary>
+
+- **`[developer]`** - Lightweight install for individual developers. Includes CLI tools, VSCode extension, LLM providers, agents. **No backend server needed.**
+
+- **`[enterprise]`** - Everything in `[developer]` plus backend API server with authentication (bcrypt, JWT, rate limiting). For teams deploying to production.
+
+- **`[healthcare]`** - Everything in `[enterprise]` plus HIPAA/GDPR compliance database, redis, and healthcare-specific plugins. Only needed for regulated industries.
+
+**Most developers should use `[developer]`** - it's fast to install and has everything you need for software development.
+
+</details>
+
 ### 2. Configure Provider
 
 ```bash
@@ -347,34 +627,153 @@ print(result.prevention_steps)    # How to prevent it
 |---------|---------|-----------|----------------|
 | **Predicts future issues** | 30-90 days ahead | No | No |
 | **Persistent memory** | Redis + patterns | No | No |
-| **Multi-provider support** | Claude, GPT-4, Ollama | N/A | GPT only |
-| **Cost optimization** | 80-96% savings | N/A | No |
+| **Multi-provider support** | Claude, GPT-4, Gemini, Ollama | N/A | GPT only |
+| **Cost optimization** | 34-86% savings* | N/A | No |
 | **Your data stays local** | Yes | Cloud | Cloud |
 | **Free for small teams** | ≤5 employees | No | No |
 
 ---
 
+## What's New in v3.8.0
+
+### 🚀 **Intelligent Response Caching: Benchmarked Performance**
+
+**Stop paying full price for repeated LLM calls. Measured results: up to 99.8% faster, 40% cost reduction on test generation, 57% cache hit rate on security audits.**
+
+#### Hybrid Cache: Hash + Semantic Matching
+
+```python
+from empathy_os.workflows import SecurityAuditWorkflow
+
+# That's it - caching auto-configured!
+workflow = SecurityAuditWorkflow(enable_cache=True)
+result = await workflow.execute(target_path="./src")
+
+# Check savings
+print(f"Cost: ${result.cost_report.total_cost:.4f}")
+print(f"Cache hit rate: {result.cost_report.cache_hit_rate:.1f}%")
+print(f"Savings: ${result.cost_report.savings_from_cache:.4f}")
+```
+
+**Real Results** (v3.8.0 benchmark - see [CACHING_BENCHMARK_REPORT.md](CACHING_BENCHMARK_REPORT.md)):
+
+- **Hash-only cache**: 30.3% average hit rate across 12 workflows, up to 99.8% faster (code review: 17.8s → 0.03s)
+- **Hybrid cache**: Up to 57% hit rate on similar prompts (security audit - benchmarked)
+- **Cost reduction**: 40% on test-generation workflow (measured)
+
+#### Two Cache Strategies
+
+**Hash-Only Cache** (Default - Zero Dependencies):
+- Perfect for CI/CD and testing
+- 100% hit rate on identical prompts
+- ~5μs lookup time
+- No ML dependencies needed
+
+**Hybrid Cache** (Semantic Matching):
+
+- Up to 57% hit rate on similar prompts (benchmarked)
+- Understands intent, not just text
+- Install: `pip install empathy-framework[cache]`
+- Best for development and production
+
+#### Automatic Setup
+
+Framework detects your environment and configures optimal caching:
+
+```python
+# First run: Framework checks for sentence-transformers
+# - Found? Uses hybrid cache (semantic matching, up to 57% hit rate)
+# - Missing? Prompts: "Install for semantic matching? (y/n)"
+# - Declined? Falls back to hash-only (100% hit rate on identical prompts)
+# - Any errors? Disables gracefully, workflow continues
+
+# Subsequent runs: Cache just works
+```
+
+#### The Caching Paradox: Adaptive Workflows
+
+**Discovered during v3.8.0 development**: Some workflows (Security Audit, Bug Prediction) cost MORE on Run 2 with cache enabled - and that's a FEATURE.
+
+**Why?** Adaptive workflows use cache to free up time for deeper analysis:
+
+```
+Security Audit without cache:
+Run 1: $0.11, 45 seconds - surface scan finds 3 issues
+
+Security Audit with cache:
+Run 2: $0.13, 15 seconds - cache frees 30s for deep analysis
+       → Uses saved time for PREMIUM tier vulnerability research
+       → Finds 7 issues including critical SQLi we missed
+       → Extra $0.02 cost = prevented security breach
+```
+
+**Result**: Cache makes workflows SMARTER, not just cheaper.
+
+See [Adaptive Workflows Documentation](docs/caching/ADAPTIVE_WORKFLOWS.md) for full explanation.
+
+#### Complete Documentation
+
+- **[Quick Reference](docs/caching/QUICK_REFERENCE.md)** - Common scenarios, 1-page cheat sheet
+- **[Configuration Guide](docs/caching/CONFIGURATION_GUIDE.md)** - All options, when to use each
+- **[Adaptive Workflows](docs/caching/ADAPTIVE_WORKFLOWS.md)** - Why Run 2 can cost more (it's good!)
+
+**Test it yourself**:
+```bash
+# Quick test (2-3 minutes)
+python benchmark_caching_simple.py
+
+# Full benchmark (15-20 minutes, all 12 workflows)
+python benchmark_caching.py
+```
+
+---
+
 ## Become a Power User
 
 ### Level 1: Basic Usage
+
 ```bash
-pip install empathy-framework
+pip install empathy-framework[developer]
 ```
+
+- Lightweight install with CLI tools, LLM providers, and agents
 - Works out of the box with sensible defaults
 - Auto-detects your API keys
 
-### Level 2: Cost Optimization
+### Level 2: Cost Optimization (Role-Based Savings)
+
+**Tier routing automatically routes tasks to appropriate models, saving 34-86% depending on your work role.**
+
 ```bash
-# Enable hybrid mode for 80-96% cost savings
+# Enable hybrid mode
 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 |
+
+#### Tier Pricing
+
+| Tier | Model | Use Case | Cost per Task* |
+|------|-------|----------|----------------|
+| CHEAP | GPT-4o-mini / Haiku | Summarization, formatting, simple tasks | $0.0045-0.0075 |
+| CAPABLE | GPT-4o / Sonnet | Bug fixing, code review, analysis | $0.0725-0.090 |
+| PREMIUM | o1 / Opus | Architecture, complex decisions, design | $0.435-0.450 |
+
+*Typical task: 5,000 input tokens, 1,000 output tokens
+
+#### Actual Savings by Role
+
+| Your Role | PREMIUM % | CAPABLE % | CHEAP % | Actual Savings | Notes |
+|-----------|-----------|-----------|---------|----------------|-------|
+| **Architect / Designer** | 60% | 30% | 10% | **34%** | Design work requires complex reasoning |
+| **Senior Developer** | 25% | 50% | 25% | **65%** | Mix of architecture and implementation |
+| **Mid-Level Developer** | 15% | 60% | 25% | **73%** | Mostly implementation and bug fixes |
+| **Junior Developer** | 5% | 40% | 55% | **86%** | Simple features, tests, documentation |
+| **QA Engineer** | 10% | 35% | 55% | **80%** | Test generation, reports, automation |
+| **DevOps Engineer** | 20% | 50% | 30% | **69%** | Infrastructure planning + automation |
+
+**See [Complete Cost Analysis](docs/cost-analysis/COST_SAVINGS_BY_ROLE_AND_PROVIDER.md) for provider comparisons (Anthropic vs OpenAI vs Ollama) and detailed calculations.**
 
 ### Level 3: Multi-Model Workflows
+
 ```python
 from empathy_llm_toolkit import EmpathyLLM
 
@@ -387,13 +786,27 @@ await llm.interact(user_id="dev", user_input="Design system", task_type="coordin
 ```
 
 ### 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.
+  - 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
 
@@ -410,6 +823,7 @@ security_agent = AgentFactory.create(
 ## 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
@@ -419,6 +833,7 @@ 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
@@ -426,6 +841,7 @@ 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
@@ -434,6 +850,7 @@ 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
@@ -442,6 +859,7 @@ empathy-memory patterns # List stored patterns
 ```
 
 ### Code Inspection
+
 ```bash
 empathy-inspect .                     # Run full inspection
 empathy-inspect . --format sarif      # GitHub Actions format
@@ -488,6 +906,41 @@ 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:
@@ -632,9 +1085,10 @@ pip install empathy-framework[full]
 pip install empathy-framework
 
 # Specific providers
-pip install empathy-framework[anthropic]
-pip install empathy-framework[openai]
-pip install empathy-framework[llm]  # Both
+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
@@ -654,7 +1108,7 @@ cd empathy-framework && pip install -e .[dev]
 | **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 XML prompts |
+| **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 |
@@ -680,8 +1134,9 @@ cd empathy-framework && pip install -e .[dev]
 
 ```bash
 # Required: At least one provider
-export ANTHROPIC_API_KEY="sk-ant-..."   # For Claude models
-export OPENAI_API_KEY="sk-..."          # For GPT models
+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"