empathy-framework 4.9.1__tar.gz → 5.0.0__tar.gz

{empathy_framework-4.9.1 → empathy_framework-5.0.0}/CHANGELOG.md

@@ -7,6 +7,207 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [5.0.0] - 2026-01-27
+
+### 🚨 Breaking Changes
+
+**Agent Coordination System Migration**
+
+The legacy coordination system in `ShortTermMemory` has been removed in favor of the new, enhanced `CoordinationSignals` API. This migration provides better security, more features, and cleaner architecture.
+
+**What Changed:**
+- ❌ **Removed:** `ShortTermMemory.send_signal()` and `receive_signals()` methods
+- ❌ **Removed:** `TTLStrategy.COORDINATION` constant
+- ❌ **Changed:** Redis key format: `empathy:coord:*` → `empathy:signal:*`
+- ✅ **New API:** `empathy_os.telemetry.CoordinationSignals` (Pattern 2 from Agent Coordination Architecture)
+
+**Migration Guide:**
+
+```python
+# Before (v4.x - REMOVED):
+from empathy_os.memory import ShortTermMemory, AgentCredentials
+
+memory = ShortTermMemory()
+credentials = AgentCredentials("agent-1", AccessTier.CONTRIBUTOR)
+memory.send_signal("task_complete", {"status": "done"}, credentials, target_agent="agent-2")
+signals = memory.receive_signals(credentials, signal_type="task_complete")
+
+# After (v5.0 - NEW):
+from empathy_os.telemetry import CoordinationSignals
+from empathy_os.memory.types import AgentCredentials, AccessTier
+
+coordinator = CoordinationSignals(agent_id="agent-1")
+credentials = AgentCredentials("agent-1", AccessTier.CONTRIBUTOR)
+
+# Send signal (with permission check)
+coordinator.signal(
+    signal_type="task_complete",
+    target_agent="agent-2",
+    payload={"status": "done"},
+    credentials=credentials  # Required for security
+)
+
+# Receive signals
+signals = coordinator.get_pending_signals(signal_type="task_complete")
+```
+
+**Benefits of Migration:**
+- ✅ **Security:** Permission checks enforced (CONTRIBUTOR tier required)
+- ✅ **Features:** Blocking wait with timeout, event streaming integration
+- ✅ **Flexibility:** Per-signal TTL configuration (no fixed 5-minute limit)
+- ✅ **Type Safety:** Structured `CoordinationSignal` dataclass with validation
+- ✅ **Consistency:** Unified `empathy:` key namespace across framework
+
+### Added
+
+**Agent Coordination Patterns (Patterns 1-6)**
+
+Complete implementation of agent coordination patterns for multi-agent workflows:
+
+- **Pattern 1: Heartbeat Tracking** (`HeartbeatCoordinator`)
+  - TTL-based agent liveness monitoring (30s heartbeat expiration)
+  - Track agent status, progress, and current task
+  - Detect stale/failed agents automatically
+  - Files: `src/empathy_os/telemetry/agent_tracking.py`
+
+- **Pattern 2: Coordination Signals** (`CoordinationSignals`)
+  - TTL-based inter-agent communication (60s default TTL)
+  - Send targeted signals or broadcast to all agents
+  - Blocking wait with timeout support
+  - Permission enforcement (CONTRIBUTOR tier required)
+  - Files: `src/empathy_os/telemetry/agent_coordination.py`
+
+- **Pattern 4: Event Streaming** (`EventStreamer`)
+  - Real-time event streaming via Redis Streams
+  - Publish workflow events for monitoring/audit
+  - Subscribe with consumer groups
+  - Files: `src/empathy_os/telemetry/event_streaming.py`
+
+- **Pattern 5: Approval Gates** (`ApprovalGate`)
+  - Human-in-the-loop workflow control
+  - Block workflow execution pending approval
+  - Timeout handling for abandoned requests
+  - Files: `src/empathy_os/telemetry/approval_gates.py`
+
+- **Pattern 6: Quality Feedback Loop** (`FeedbackLoop`)
+  - Record quality scores per workflow/stage/tier
+  - Automatic tier upgrade recommendations (quality < 0.7)
+  - Adaptive routing based on historical performance
+  - Files: `src/empathy_os/telemetry/feedback_loop.py`
+
+**Agent Coordination Dashboard**
+
+Web-based dashboard for real-time monitoring of all 6 coordination patterns:
+
+- **Zero-Dependency Design:** Uses Python stdlib `http.server` (no Flask/FastAPI required)
+- **Three Implementation Tiers:**
+  - Standalone: Direct Redis access (recommended)
+  - Simple: Uses telemetry API classes
+  - FastAPI: Advanced features (optional dependency)
+- **Real-Time Updates:** Auto-refresh every 5 seconds
+- **7 Dashboard Panels:**
+  - Active agents with heartbeat status
+  - Coordination signals between agents
+  - Event stream (real-time events)
+  - Pending approval requests
+  - Quality metrics by workflow/stage/tier
+  - Underperforming stages (quality < 0.7)
+  - System health status
+- **CLI Integration:** `empathy dashboard start [--host HOST] [--port PORT]`
+- **VS Code Task:** `Cmd+Shift+B` to start dashboard and auto-open browser
+- **Files:** `src/empathy_os/dashboard/{standalone_server.py,simple_server.py,app.py,static/}`
+
+**Adaptive Model Routing**
+
+Telemetry-based model selection for cost optimization:
+
+- **AdaptiveModelRouter:** Analyzes historical performance data
+- **Auto-Upgrade:** Recommends tier upgrade when failure rate > 20%
+- **Quality Tracking:** Per-workflow/stage/tier success rate monitoring
+- **Workflow Integration:** `enable_adaptive_routing=True` parameter
+- **CLI Commands:** `empathy telemetry routing-stats`, `routing-check`
+- **Files:** `src/empathy_os/models/adaptive_routing.py`
+
+**Enhanced Telemetry CLI**
+
+New commands for coordination and routing monitoring:
+
+```bash
+empathy telemetry routing-stats [--workflow NAME] [--stage NAME] [--days N]
+empathy telemetry routing-check [--workflow NAME] [--threshold 0.7]
+empathy telemetry models [--days N]
+empathy telemetry agents [--status running|idle|failed]
+empathy telemetry signals --agent AGENT_ID [--type TYPE]
+```
+
+**Comprehensive Documentation**
+
+- `docs/AGENT_COORDINATION_ARCHITECTURE.md` - Pattern architecture (6 patterns)
+- `docs/DASHBOARD_COMPLETE.md` - Dashboard reference guide (500+ lines)
+- `docs/DASHBOARD_GUIDE.md` - Usage guide with examples
+- `docs/DASHBOARD_USAGE.md` - 5 methods to start dashboard
+- `docs/ADAPTIVE_ROUTING_ANTHROPIC_NATIVE.md` - Model selection guide
+- `DASHBOARD_QUICKSTART.md` - 3-command quick start
+
+### Changed
+
+**Improved Test Data**
+
+Test data now uses descriptive agent names for better UX:
+
+- **Workflow Agents:** `code-review`, `test-generation`, `security-audit`, `refactoring`, `bug-predict`
+- **Role Agents:** `orchestrator`, `validator`, `monitor`
+- Makes dashboard immediately understandable
+- Professional demo/screenshot appearance
+- File: `scripts/populate_redis_direct.py`
+
+**Redis Key Namespace Unification**
+
+All agent coordination keys now use consistent `empathy:` prefix:
+
+- Signals: `empathy:signal:{target}:{type}:{id}` (was `signal:*`)
+- Maintains consistency with other keys: `empathy:working:*`, `empathy:staged:*`, etc.
+
+**Workflow Base Class Enhancements**
+
+New opt-in features for workflows:
+
+```python
+workflow = MyWorkflow(
+    enable_adaptive_routing=True,      # Pattern 3: Adaptive tier selection
+    enable_heartbeat_tracking=True,    # Pattern 1: Agent liveness
+    enable_coordination=True,          # Pattern 2: Inter-agent signals
+    agent_id="my-workflow-abc123"      # Custom agent ID
+)
+```
+
+### Fixed
+
+**Security:** Permission enforcement restored in coordination system
+- All coordination signals require CONTRIBUTOR tier or higher
+- Prevents unauthorized agent communication
+- Backward compatible (warns if credentials not provided)
+
+### Testing
+
+**Comprehensive Test Suite:**
+- ✅ 280 telemetry tests passing (including 8 new permission tests)
+- ✅ Pattern 1-6 tests (19 heartbeat, 28 coordination, 24 feedback, etc.)
+- ✅ Dashboard integration tests
+- ✅ Permission enforcement tests (OBSERVER blocked, CONTRIBUTOR allowed)
+- ✅ Key format migration verified
+
+**Test Files:**
+- `tests/unit/telemetry/test_agent_tracking.py` (19 tests)
+- `tests/unit/telemetry/test_agent_coordination.py` (28 tests, including 8 permission tests)
+- `tests/unit/telemetry/test_event_streaming.py`
+- `tests/unit/telemetry/test_approval_gates.py`
+- `tests/unit/telemetry/test_feedback_loop.py` (24 tests)
+
+### Deprecated
+
+None (deprecated features removed in this major version)
+
 ## [4.9.0] - 2026-01-27
 
 ### 🚀 Performance & Memory Optimization Release

{empathy_framework-4.9.1 → empathy_framework-5.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: empathy-framework
-Version: 4.9.1
+Version: 5.0.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>

{empathy_framework-4.9.1 → empathy_framework-5.0.0}/docs/api-reference/index.md

@@ -51,6 +51,23 @@ Data persistence for patterns, metrics, and state.
 - `StateManager` - Manage user collaboration states
 - `MetricsCollector` - Track usage metrics and performance
 
+### [Workflows](workflows.md)
+Cost-optimized workflow patterns with 3-tier model routing.
+
+**Key Classes:**
+- `BaseWorkflow` - Base class for workflow implementation
+- `WorkflowBuilder` - Fluent API for building workflows
+- `SecurityAuditWorkflow`, `CodeReviewWorkflow`, etc. - Built-in workflows
+
+### [Memory](memory.md)
+Unified two-tier memory system for AI agent collaboration.
+
+**Key Classes:**
+- `UnifiedMemory` - Main entry point for memory operations
+- `RedisShortTermMemory` - Short-term Redis-backed storage
+- `SecureMemDocsIntegration` - Encrypted long-term storage
+- `MemoryGraph` - Cross-workflow intelligence graph
+
 ### [LLM Toolkit](llm-toolkit.md)
 LLM provider integration with security controls.
 

empathy_framework-5.0.0/docs/api-reference/memory.md

@@ -0,0 +1,301 @@
+# Memory API
+
+Unified two-tier memory system for AI agent collaboration.
+
+---
+
+## Overview
+
+The memory system provides two tiers:
+
+| Tier | Backend | Purpose |
+|------|---------|---------|
+| **Short-term** | Redis | Agent coordination, working memory, TTL-based expiration |
+| **Long-term** | File/SQLite | Cross-session patterns, encrypted storage, compliance |
+
+---
+
+## Quick Start
+
+```python
+from empathy_os.memory import UnifiedMemory
+
+# Initialize with environment auto-detection
+memory = UnifiedMemory(user_id="agent@company.com")
+
+# Short-term operations
+memory.stash("working_data", {"key": "value"})
+data = memory.retrieve("working_data")
+
+# Long-term operations
+result = memory.persist_pattern(
+    content="Algorithm for X",
+    pattern_type="algorithm",
+)
+pattern = memory.recall_pattern(result["pattern_id"])
+
+# Pattern promotion (short-term → long-term)
+staged_id = memory.stage_pattern({"content": "..."})
+memory.promote_pattern(staged_id)
+```
+
+---
+
+## UnifiedMemory
+
+Main entry point for memory operations.
+
+### Constructor
+
+```python
+UnifiedMemory(
+    user_id: str,                      # User/agent identifier
+    redis_url: str | None = None,      # Redis URL (auto-detected if None)
+    encryption_key: str | None = None, # Encryption key for SENSITIVE data
+    compliance_mode: str = "standard", # "standard" or "hipaa"
+)
+```
+
+### Short-term Methods
+
+| Method | Description |
+|--------|-------------|
+| `stash(key, value, ttl=3600)` | Store data with TTL (default 1 hour) |
+| `retrieve(key)` | Get data by key |
+| `delete(key)` | Remove data |
+| `extend_ttl(key, seconds)` | Extend expiration time |
+| `list_keys(pattern="*")` | List matching keys |
+
+### Long-term Methods
+
+| Method | Description |
+|--------|-------------|
+| `persist_pattern(content, pattern_type, classification)` | Save pattern permanently |
+| `recall_pattern(pattern_id)` | Retrieve pattern by ID |
+| `search_patterns(query, limit=10)` | Search patterns |
+| `delete_pattern(pattern_id)` | Remove pattern |
+
+### Pattern Promotion
+
+| Method | Description |
+|--------|-------------|
+| `stage_pattern(data)` | Stage pattern in short-term |
+| `promote_pattern(staged_id)` | Promote to long-term |
+| `validate_pattern(staged_id)` | Validate before promotion |
+
+---
+
+## Short-term Memory (Redis)
+
+Direct access to Redis-backed short-term memory.
+
+```python
+from empathy_os.memory import RedisShortTermMemory, AccessTier
+
+# Create with connection
+memory = RedisShortTermMemory(
+    redis_url="redis://localhost:6379",
+    default_ttl=3600,
+)
+
+# Store with access control
+memory.store(
+    key="sensitive_data",
+    value={"api_key": "..."},
+    access_tier=AccessTier.AGENT,  # Only agents can access
+)
+
+# Retrieve
+data = memory.get("sensitive_data")
+```
+
+### AccessTier
+
+| Tier | Access Level |
+|------|--------------|
+| `OBSERVER` | Read-only, limited scope |
+| `CONTRIBUTOR` | Read/write within scope |
+| `AGENT` | Full agent-level access |
+| `STEWARD` | Administrative access |
+
+---
+
+## Long-term Memory (Secure)
+
+Encrypted, classified storage for sensitive patterns.
+
+```python
+from empathy_os.memory import SecureMemDocsIntegration, Classification
+
+# Create secure storage
+storage = SecureMemDocsIntegration(
+    encryption_key="your-key-here",
+    compliance_mode="hipaa",
+)
+
+# Store with classification
+pattern_id = storage.store_pattern(
+    content="Patient data processing algorithm",
+    classification=Classification.SENSITIVE,
+    metadata={"domain": "healthcare"},
+)
+
+# Retrieve (auto-decrypts)
+pattern = storage.get_pattern(pattern_id)
+```
+
+### Classification
+
+| Level | Description |
+|-------|-------------|
+| `PUBLIC` | Shareable, no encryption |
+| `INTERNAL` | Team-only access |
+| `SENSITIVE` | Encrypted, audit logged |
+
+---
+
+## Memory Graph
+
+Cross-workflow intelligence through graph-based pattern storage.
+
+```python
+from empathy_os.memory import MemoryGraph, EdgeType
+
+graph = MemoryGraph(path="memory_graph.json")
+
+# Add findings from workflows
+bug_id = graph.add_finding(
+    workflow="bug-predict",
+    finding={"type": "bug", "name": "Null reference"},
+)
+
+fix_id = graph.add_finding(
+    workflow="code-review",
+    finding={"type": "fix", "name": "Add null check"},
+)
+
+# Create relationships
+graph.add_edge(bug_id, fix_id, EdgeType.FIXED_BY)
+
+# Query related findings
+fixes = graph.find_related(bug_id, edge_types=[EdgeType.FIXED_BY])
+```
+
+### EdgeType
+
+| Type | Description |
+|------|-------------|
+| `FIXED_BY` | Bug fixed by fix |
+| `CAUSES` | Issue causes another |
+| `SIMILAR_TO` | Similar patterns |
+| `CONTAINS` | Parent-child relationship |
+| `DEPENDS_ON` | Dependency relationship |
+
+---
+
+## Security Features
+
+### PII Scrubbing
+
+```python
+from empathy_os.memory import PIIScrubber
+
+scrubber = PIIScrubber()
+
+# Scrub before storing
+clean_text = scrubber.scrub(
+    "Contact john@example.com or call 555-1234",
+)
+# Result: "Contact [EMAIL] or call [PHONE]"
+```
+
+### Secrets Detection
+
+```python
+from empathy_os.memory import SecretsDetector
+
+detector = SecretsDetector()
+
+# Check for secrets before storing
+secrets = detector.detect(text)
+if secrets:
+    raise SecurityError(f"Found secrets: {secrets}")
+```
+
+### Audit Logging
+
+```python
+from empathy_os.memory import AuditLogger
+
+logger = AuditLogger(log_path="audit.log")
+
+# Log access
+logger.log_access(
+    user_id="agent_1",
+    pattern_id="pat_123",
+    action="read",
+    classification="SENSITIVE",
+)
+```
+
+---
+
+## Cross-session Coordination
+
+Coordinate between multiple agent sessions.
+
+```python
+from empathy_os.memory import CrossSessionCoordinator
+
+coordinator = CrossSessionCoordinator(redis_url="redis://localhost:6379")
+
+# Register session
+session_id = coordinator.register_session(
+    session_type=SessionType.WORKFLOW,
+    metadata={"workflow": "security-audit"},
+)
+
+# Broadcast to other sessions
+coordinator.broadcast(
+    channel="findings",
+    message={"severity": "high", "finding": "..."},
+)
+
+# Listen for messages
+async for message in coordinator.subscribe("findings"):
+    process_finding(message)
+```
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `REDIS_URL` | Redis connection URL |
+| `RAILWAY_REDIS_URL` | Railway-hosted Redis |
+| `EMPATHY_ENCRYPTION_KEY` | Encryption key for SENSITIVE |
+| `EMPATHY_COMPLIANCE_MODE` | "standard" or "hipaa" |
+
+### Memory Control Panel
+
+```bash
+# Start memory control panel
+empathy-memory serve
+
+# Check status
+empathy-memory status
+
+# List patterns
+empathy-memory patterns
+```
+
+---
+
+## See Also
+
+- [Short-term Memory Guide](../reference/SHORT_TERM_MEMORY.md)
+- [Getting Started - Redis Setup](../getting-started/redis-setup.md)
+- [Security Architecture](../architecture/SECURE_MEMORY_ARCHITECTURE.md)