empathy-framework 3.3.3__tar.gz → 3.4.0__tar.gz

{empathy_framework-3.3.3 → empathy_framework-3.4.0}/PKG-INFO

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

empathy_framework-3.4.0/docs/guides/pattern-catalog.md

@@ -0,0 +1,222 @@
+# Pattern Catalog Guide
+
+The Pattern Catalog is a collection of reusable software patterns extracted from the Empathy Framework, organized for cross-domain transfer and Level 5 (Systems Thinking) capability development.
+
+## What is the Pattern Catalog?
+
+The Pattern Catalog serves three purposes:
+
+1. **Document existing patterns** - Capture what we've built so it can be reused
+2. **Enable cross-domain transfer** - Apply patterns from one domain to solve problems in another
+3. **Accelerate Level 5 thinking** - Train the ability to recognize "this problem is like that solved problem"
+
+## Catalog Location
+
+```
+patterns/
+├── README.md                    # Index and usage guide
+├── reliability/                 # Patterns from reliability engineering
+│   ├── circuit-breaker.md
+│   ├── graceful-degradation.md
+│   └── retry-with-backoff.md
+├── observability/               # Patterns from observability/SRE
+│   ├── health-monitoring.md
+│   └── telemetry-tracking.md
+└── cross-domain/               # Level 5 transfer examples
+    ├── circuit-breaker-to-trust.md
+    ├── alerting-to-empathy-levels.md
+    └── graceful-degradation-to-conversation.md
+```
+
+## How to Use the Catalog
+
+### For Developers
+
+When facing a new problem:
+
+1. **Search for similar patterns** - Look through the catalog for patterns that solve similar problems
+2. **Check cross-domain transfers** - Non-obvious solutions often come from other domains
+3. **Consider the abstraction** - What's the core mechanism? Does it apply elsewhere?
+
+```python
+# Example: Need to handle user who keeps getting wrong answers
+
+# Search catalog → find circuit-breaker.md
+# Read cross-domain → circuit-breaker-to-trust.md
+# Result: Use TrustCircuitBreaker instead of inventing new solution
+
+from empathy_os.trust import TrustCircuitBreaker
+breaker = TrustCircuitBreaker(user_id="user_123")
+```
+
+### For Architects
+
+When designing new features:
+
+1. **Check if pattern already exists** - Avoid reinventing the wheel
+2. **Identify pattern opportunities** - When building something new, is it generalizable?
+3. **Document new patterns** - Contribute to the catalog
+
+### For AI Systems
+
+The catalog can be referenced by AI systems:
+
+```python
+# When solving a problem, reference relevant patterns
+patterns = catalog.search("protect relationship from failures")
+# Returns: circuit-breaker-to-trust.md
+
+# Apply the pattern
+solution = apply_pattern(patterns[0], problem_context)
+```
+
+## Pattern Template
+
+Every pattern follows this structure:
+
+```markdown
+# Pattern Name
+
+**Source Domain:** Where this pattern originated
+**Location in Codebase:** File paths
+**Level:** Capability level (1-5)
+
+## Overview
+What problem does this solve?
+
+## Implementation
+Code examples from actual codebase
+
+## Key Insight
+The one thing to remember
+
+## Cross-Domain Transfer Potential
+Where else could this apply?
+```
+
+## Understanding Cross-Domain Transfer
+
+Cross-domain transfer is the Level 5 capability that makes the catalog powerful. It's the ability to recognize that:
+
+> "This problem in Domain A has the same structure as that solved problem in Domain B"
+
+### Example: Circuit Breaker → Trust
+
+| Reliability Domain | Trust Domain |
+|-------------------|--------------|
+| Service keeps failing | User keeps getting wrong answers |
+| Stop calling failing service | Stop acting without confirmation |
+| Wait for recovery period | Wait for trust recovery period |
+| Test with limited calls | Test with supervised interactions |
+| Resume normal operation | Restore full autonomy |
+
+The **mechanism** is identical:
+1. Track failures/damage
+2. Trip when threshold exceeded
+3. Wait for recovery period
+4. Test recovery
+5. Resume normal
+
+### Finding Transfer Opportunities
+
+Ask these questions:
+
+1. **What's the abstract problem?**
+   - Not "API keeps timing out" but "unreliable component"
+   - Not "user frustrated with wrong answers" but "relationship degrading"
+
+2. **What's the mechanism?**
+   - State machine? Threshold? Fallback chain?
+   - Time-based? Count-based? Score-based?
+
+3. **Where else does this structure appear?**
+   - Different domain, same structure = transfer opportunity
+
+## Current Patterns
+
+### Reliability Patterns
+
+| Pattern | Key Insight | Implementation |
+|---------|-------------|----------------|
+| [Circuit Breaker](../../patterns/reliability/circuit-breaker.md) | Fail fast to prevent cascade | `src/empathy_os/resilience/circuit_breaker.py` |
+| [Graceful Degradation](../../patterns/reliability/graceful-degradation.md) | Partial value beats failure | `src/empathy_os/resilience/fallback.py` |
+| [Retry with Backoff](../../patterns/reliability/retry-with-backoff.md) | Transient failures recover | `src/empathy_os/resilience/retry.py` |
+
+### Observability Patterns
+
+| Pattern | Key Insight | Implementation |
+|---------|-------------|----------------|
+| [Health Monitoring](../../patterns/observability/health-monitoring.md) | Degraded predicts failure | `src/empathy_os/resilience/health.py` |
+| [Telemetry Tracking](../../patterns/observability/telemetry-tracking.md) | Failures are learning data | `src/empathy_os/models/telemetry.py` |
+
+### Cross-Domain Transfers (Implemented)
+
+| Transfer | From → To | Implementation |
+|----------|-----------|----------------|
+| [Circuit Breaker → Trust](../../patterns/cross-domain/circuit-breaker-to-trust.md) | Reliability → Trust | `src/empathy_os/trust/circuit_breaker.py` |
+
+### Cross-Domain Transfers (Documented, Not Yet Implemented)
+
+| Transfer | From → To | Status |
+|----------|-----------|--------|
+| [Alerting → Empathy Levels](../../patterns/cross-domain/alerting-to-empathy-levels.md) | Observability → Empathy | Documented |
+| [Graceful Degradation → Conversation](../../patterns/cross-domain/graceful-degradation-to-conversation.md) | Reliability → UX | Documented |
+
+## Contributing to the Catalog
+
+### Adding a New Pattern
+
+1. **Identify the pattern** - What's the core mechanism?
+2. **Find the implementation** - Where is it in the codebase?
+3. **Document using template** - Create markdown file in appropriate directory
+4. **Look for transfers** - Could this apply elsewhere?
+
+### Adding a Cross-Domain Transfer
+
+1. **Identify source pattern** - What pattern are you transferring?
+2. **Map the concepts** - Create a table showing the mapping
+3. **Implement if valuable** - Create working code
+4. **Document the transfer** - Why does this work?
+
+### Pattern Naming
+
+- Use lowercase with hyphens: `circuit-breaker.md`
+- Be descriptive but concise
+- Cross-domain: `source-to-target.md`
+
+## Metrics
+
+Track catalog health:
+
+- **Patterns documented:** 8
+- **Cross-domain transfers:** 3 (1 implemented)
+- **Codebase coverage:** ~40%
+- **Last updated:** 2025-12-28
+
+## Level 5 Capability Development
+
+The catalog is a tool for developing Level 5 (Systems Thinking) capability:
+
+| Level | Description | Catalog Usage |
+|-------|-------------|---------------|
+| 1 - Reactive | Respond to requests | None |
+| 2 - Guided | Follow patterns | Reference patterns |
+| 3 - Proactive | Anticipate needs | Suggest patterns |
+| 4 - Anticipatory | Predict problems | Recognize pattern fits |
+| 5 - Systems | Transfer across domains | Create new transfers |
+
+### Exercises
+
+1. **Pattern Recognition** - Given a problem, find 3 potentially applicable patterns
+2. **Transfer Identification** - Find an existing pattern, identify 2 new domains it could apply to
+3. **Implementation** - Take a documented transfer and implement it
+
+## Further Reading
+
+- [Trust Circuit Breaker Guide](./trust-circuit-breaker.md) - Detailed guide on the implemented transfer
+- [Pattern Catalog README](../../patterns/README.md) - Catalog index and quick reference
+- [Empathy Framework Architecture](../architecture.md) - Overall system design
+
+---
+
+*The Pattern Catalog is a key component of reaching Level 5 (Systems Thinking) capability.*