Pattern Library¶

Pattern discovery, learning, and sharing system for multi-agent coordination.

Overview¶

The Pattern Library enables AI systems to:

Discover Patterns: Automatically identify recurring interaction patterns
Learn from Experience: Improve responses based on successful patterns
Share Knowledge: Coordinate across multiple agents via shared pattern libraries
Track Confidence: Maintain confidence scores based on success rate
Decay Over Time: Patterns fade if unused (adaptive learning)

Key Concepts¶

Patterns¶

A pattern is a discovered interaction template that worked well in the past:

Pattern(
    id="pattern_deployment_friday",
    agent_id="agent_123",
    pattern_type="warning",
    name="Friday Deployment Warning",
    description="Warn about Friday afternoon deployments",
    context={"day": "friday", "time": "afternoon", "action": "deploy"},
    code="Recommend delaying until Monday morning",
    confidence=0.92,  # 92% confidence based on past success
    usage_count=25,
    success_count=23,
    tags=["deployment", "best-practice", "timing"]
)

Multi-Agent Coordination¶

Multiple agents can share patterns via a common library:

graph LR
    A[Agent 1: Frontend] --> L[Shared Pattern Library]
    B[Agent 2: Backend] --> L
    C[Agent 3: DevOps] --> L
    L --> A
    L --> B
    L --> C

When one agent discovers a useful pattern, all agents learn from it.

Class Reference¶

PatternLibrary¶

Shared library for multi-agent pattern discovery and sharing

Enables Level 5 Systems Empathy: AI-AI cooperation where one agent's discovery benefits all agents in the collective.

Key Concepts: - Pattern Discovery: Agents detect patterns in their interactions - Pattern Contribution: Agents share patterns with the library - Pattern Querying: Agents query for relevant patterns before acting - Collective Learning: All agents benefit from each discovery

Pattern Types: 1. Sequential: "After X, users typically need Y" 2. Temporal: "On Mondays at 9am, prioritize Z" 3. Conditional: "If context A, approach B works best" 4. Behavioral: "Users with trait X prefer style Y"

Example

library = PatternLibrary()

Agent 1 contributes a pattern¶

pattern = Pattern( ... id="pat_001", ... agent_id="compliance_agent", ... pattern_type="sequential", ... name="Post-update documentation pattern", ... description="After system updates, users need help finding changed features", ... confidence=0.85 ... ) library.contribute_pattern("compliance_agent", pattern)

Agent 2 queries for relevant patterns¶

context = {"recent_event": "system_update", "user_confusion": True} matches = library.query_patterns("documentation_agent", context) print(f"Found {len(matches)} relevant patterns")

`init()` ¶

Initialize PatternLibrary

`contribute_pattern(agent_id, pattern)` ¶

Agent contributes a discovered pattern to the library

Parameters:

Name	Type	Description	Default
`agent_id`	`str`	ID of contributing agent	required
`pattern`	`Pattern`	Pattern to contribute	required

Example

pattern = Pattern( ... id="pat_002", ... agent_id="agent_1", ... pattern_type="conditional", ... name="High-stakes decision pattern", ... description="For high-stakes decisions, provide options with tradeoffs", ... confidence=0.9 ... ) library.contribute_pattern("agent_1", pattern)

`get_agent_patterns(agent_id)` ¶

Get all patterns contributed by a specific agent

Parameters:

Name	Type	Description	Default
`agent_id`	`str`	Agent identifier	required

Returns:

Type	Description
`list[Pattern]`	List of patterns from this agent

`get_library_stats()` ¶

Get statistics about the pattern library

Returns:

Type	Description
`dict[str, Any]`	Dict with library statistics

`get_pattern(pattern_id)` ¶

Get a specific pattern by ID

Parameters:

Name	Type	Description	Default
`pattern_id`	`str`	Pattern identifier	required

Returns:

Type	Description
`Pattern \| None`	Pattern if found, None otherwise

`get_related_patterns(pattern_id, depth=1)` ¶

Get patterns related to a given pattern

Parameters:

Name	Type	Description	Default
`pattern_id`	`str`	Source pattern ID	required
`depth`	`int`	How many hops to traverse (1 = immediate neighbors)	`1`

Returns:

Type	Description
`list[Pattern]`	List of related patterns

`get_top_patterns(n=10, sort_by='success_rate')` ¶

Get top N patterns by specified metric

Parameters:

Name	Type	Description	Default
`n`	`int`	Number of patterns to return	`10`
`sort_by`	`str`	Metric to sort by ("success_rate", "usage_count", "confidence")	`'success_rate'`

Returns:

Type	Description
`list[Pattern]`	Top N patterns

`link_patterns(pattern_id_1, pattern_id_2)` ¶

Create a link between related patterns

Helps agents discover complementary patterns.

Parameters:

Name	Type	Description	Default
`pattern_id_1`	`str`	First pattern ID	required
`pattern_id_2`	`str`	Second pattern ID	required

`query_patterns(agent_id, context, pattern_type=None, min_confidence=0.5, limit=10)` ¶

Query relevant patterns for current context

Parameters:

Name	Type	Description	Default
`agent_id`	`str`	ID of querying agent	required
`context`	`dict[str, Any]`	Current context dictionary	required
`pattern_type`	`str \| None`	Optional filter by pattern type	`None`
`min_confidence`	`float`	Minimum confidence threshold (0-1)	`0.5`
`limit`	`int`	Maximum patterns to return	`10`

Returns:

Type	Description
`list[PatternMatch]`	List of PatternMatch objects, sorted by relevance

Example

context = { ... "user_role": "developer", ... "task_type": "debugging", ... "time_of_day": "morning" ... } matches = library.query_patterns("debug_agent", context, min_confidence=0.7)

`record_pattern_outcome(pattern_id, success)` ¶

Record outcome of using a pattern

Updates pattern statistics to improve future recommendations.

Parameters:

Name	Type	Description	Default
`pattern_id`	`str`	ID of pattern that was used	required
`success`	`bool`	Whether using the pattern was successful	required

`reset()` ¶

Reset library to empty state

Central repository for discovered patterns.

Example:

from empathy_os.pattern_library import PatternLibrary, Pattern

# Create library
library = PatternLibrary()

# Contribute a pattern
pattern = Pattern(
    id="pat_123",
    agent_id="agent_1",
    pattern_type="suggestion",
    name="Add error handling",
    description="Suggest error handling for API calls",
    context={"task": "api_call", "error_handling": False},
    code="Always wrap API calls in try-except blocks",
    confidence=0.85
)

library.contribute_pattern(agent_id="agent_1", pattern=pattern)

# Find matching patterns
matches = library.find_patterns(
    context={"task": "api_call"},
    min_confidence=0.75
)

for match in matches:
    print(f"Pattern: {match.pattern.name}")
    print(f"Confidence: {match.confidence:.0%}")
    print(f"Code: {match.pattern.code}")

Pattern¶

A discovered pattern that can be shared across AI agents

Patterns represent reusable solutions, common behaviors, or learned heuristics that one agent discovered and others can benefit from.

Examples: - Sequential patterns: "After action X, users typically need Y" - Temporal patterns: "On Mondays, prioritize Z" - Conditional patterns: "If context A, then approach B works best"

`success_rate` `property` ¶

Calculate success rate of pattern usage

`record_usage(success)` ¶

Record pattern usage outcome

Individual pattern with metadata and confidence tracking.

Attributes: - id (str): Unique pattern identifier - agent_id (str): Agent that discovered the pattern - pattern_type (str): Type (suggestion, warning, optimization, etc.) - name (str): Human-readable name - description (str): Detailed description - context (dict): Context where pattern applies - code (str): Pattern implementation/response template - confidence (float): Confidence score (0.0-1.0) - usage_count (int): Times pattern was used - success_count (int): Times pattern led to success - failure_count (int): Times pattern led to failure - tags (List[str]): Searchable tags - discovered_at (datetime): When pattern was discovered - last_used (datetime): When pattern was last used

Derived Properties: - success_rate (float): success_count / usage_count - age_days (float): Days since discovery

Example:

from empathy_os.pattern_library import Pattern
from datetime import datetime

pattern = Pattern(
    id="pat_security_review",
    agent_id="security_bot",
    pattern_type="warning",
    name="Security Review Required",
    description="Flag code changes that need security review",
    context={
        "file_type": "authentication",
        "has_security_review": False
    },
    code="This change affects authentication. Request security review.",
    confidence=0.90,
    tags=["security", "authentication", "compliance"]
)

# Update based on usage
pattern.usage_count += 1
pattern.success_count += 1
pattern.last_used = datetime.now()

# Confidence increases with success
new_confidence = pattern.success_rate * 0.9 + 0.1
print(f"Confidence: {new_confidence:.0%}")

PatternMatch¶

Result of pattern matching against current context

Result of pattern matching with relevance score.

Attributes: - pattern (Pattern): The matched pattern - confidence (float): Match confidence (0.0-1.0) - relevance (float): Context relevance score (0.0-1.0)

Example:

matches = library.find_patterns(
    context={"task": "deployment", "environment": "production"},
    min_confidence=0.70
)

for match in matches:
    print(f"Pattern: {match.pattern.name}")
    print(f"  Confidence: {match.confidence:.0%}")
    print(f"  Relevance: {match.relevance:.0%}")
    print(f"  Code: {match.pattern.code}")
    print()

Usage Patterns¶

Single-Agent Pattern Learning¶

from empathy_os import EmpathyOS
from empathy_os.pattern_library import PatternLibrary

# Create agent with pattern learning
library = PatternLibrary()
empathy = EmpathyOS(
    user_id="user_123",
    target_level=4,
    pattern_library=library,
    pattern_learning_enabled=True
)

# Agent discovers patterns from successful interactions
for i in range(100):
    response = empathy.interact(
        user_id="user_123",
        user_input=f"Task {i}",
        context={"iteration": i}
    )

    # Record success/failure
    empathy.record_success(success=user_was_satisfied)

# Check discovered patterns
patterns = library.get_top_patterns(n=10)
for pattern in patterns:
    print(f"{pattern.name}: {pattern.confidence:.0%} confidence")

from empathy_os import EmpathyOS
from empathy_os.pattern_library import PatternLibrary

# Shared library for team coordination
shared_library = PatternLibrary()

# Create multiple specialized agents
frontend_agent = EmpathyOS(
    user_id="frontend_agent",
    target_level=4,
    pattern_library=shared_library  # Same library
)

backend_agent = EmpathyOS(
    user_id="backend_agent",
    target_level=4,
    pattern_library=shared_library  # Same library
)

devops_agent = EmpathyOS(
    user_id="devops_agent",
    target_level=4,
    pattern_library=shared_library  # Same library
)

# Frontend agent discovers a pattern
frontend_response = frontend_agent.interact(
    user_id="developer_1",
    user_input="How do I optimize this API call?",
    context={"task": "api_optimization"}
)

# Pattern is saved to shared library
# Now backend agent can use it!
backend_response = backend_agent.interact(
    user_id="developer_2",
    user_input="My API is slow",
    context={"task": "api_optimization"}
)

# Backend agent benefits from frontend agent's learning
print("Backend agent used pattern discovered by frontend agent!")

Pattern Persistence¶

from empathy_os.pattern_library import PatternLibrary
from empathy_os.persistence import PatternPersistence

# Create and populate library
library = PatternLibrary()
# ... add patterns ...

# Save to JSON (human-readable, good for backups)
PatternPersistence.save_to_json(library, "patterns.json")

# Save to SQLite (queryable, good for production)
PatternPersistence.save_to_sqlite(library, "patterns.db")

# Load later
loaded_library = PatternPersistence.load_from_json("patterns.json")
# or
loaded_library = PatternPersistence.load_from_sqlite("patterns.db")

Pattern Discovery¶

from empathy_os.pattern_library import PatternLibrary, Pattern

library = PatternLibrary()

# Automatically discover patterns from interactions
def discover_pattern_from_interaction(user_input, response, success, context):
    """Discover pattern from successful interaction"""
    if success and context.get("confidence", 0) > 0.80:
        pattern = Pattern(
            id=f"pattern_{hash(user_input)}",
            agent_id="discovery_agent",
            pattern_type="auto_discovered",
            name=f"Pattern for: {user_input[:50]}",
            description=f"Discovered from successful interaction",
            context=context,
            code=response,
            confidence=context.get("confidence", 0.80)
        )

        library.contribute_pattern("discovery_agent", pattern)
        return pattern
    return None

# Use in interaction loop
response = empathy.interact(user_id="user_123", user_input="...", context={})
empathy.record_success(success=True)

pattern = discover_pattern_from_interaction(
    user_input="How do I deploy?",
    response=response.response,
    success=True,
    context={"confidence": response.confidence}
)

if pattern:
    print(f"Discovered new pattern: {pattern.name}")

Pattern Decay (Adaptive Learning)¶

from empathy_os.pattern_library import PatternLibrary
from datetime import datetime, timedelta

library = PatternLibrary()

# ... patterns are used over time ...

# Decay unused patterns
def decay_unused_patterns(library, decay_rate=0.01, max_age_days=90):
    """Reduce confidence of old, unused patterns"""
    for pattern in library.patterns.values():
        age_days = (datetime.now() - pattern.last_used).days

        if age_days > max_age_days:
            # Pattern hasn't been used in 90+ days
            pattern.confidence *= (1 - decay_rate * age_days)
            pattern.confidence = max(0.0, pattern.confidence)

        if pattern.confidence < 0.50:
            # Remove low-confidence patterns
            library.remove_pattern(pattern.id)

# Run periodically
decay_unused_patterns(library)

Advanced Features¶

Pattern Conflict Detection¶

def detect_conflicts(library):
    """Find patterns that conflict with each other"""
    conflicts = []

    for p1 in library.patterns.values():
        for p2 in library.patterns.values():
            if p1.id >= p2.id:
                continue

            # Check for context overlap but different recommendations
            if (p1.context == p2.context and
                p1.code != p2.code and
                p1.confidence > 0.75 and
                p2.confidence > 0.75):

                conflicts.append((p1, p2))

    return conflicts

conflicts = detect_conflicts(library)
for p1, p2 in conflicts:
    print(f"Conflict: {p1.name} vs {p2.name}")
    print(f"  {p1.name}: {p1.code}")
    print(f"  {p2.name}: {p2.code}")

Pattern Recommendation¶

def recommend_best_pattern(library, context, min_confidence=0.75):
    """Find best pattern for given context"""
    matches = library.find_patterns(context, min_confidence=min_confidence)

    if not matches:
        return None

    # Score by: confidence * relevance * recency
    best_match = max(
        matches,
        key=lambda m: (
            m.confidence *
            m.relevance *
            (1.0 - m.pattern.age_days / 365.0)  # Prefer recent patterns
        )
    )

    return best_match

# Use in interactions
context = {"task": "deployment", "environment": "production"}
best = recommend_best_pattern(library, context)

if best:
    print(f"Recommendation: {best.pattern.name}")
    print(f"  {best.pattern.code}")
    print(f"  Confidence: {best.confidence:.0%}")

Pattern Library¶

Overview¶

Key Concepts¶

Patterns¶

Multi-Agent Coordination¶

Class Reference¶

PatternLibrary¶

Agent 1 contributes a pattern¶

Agent 2 queries for relevant patterns¶

__init__() ¶

contribute_pattern(agent_id, pattern) ¶

get_agent_patterns(agent_id) ¶

get_library_stats() ¶

get_pattern(pattern_id) ¶

get_related_patterns(pattern_id, depth=1) ¶

get_top_patterns(n=10, sort_by='success_rate') ¶

link_patterns(pattern_id_1, pattern_id_2) ¶

query_patterns(agent_id, context, pattern_type=None, min_confidence=0.5, limit=10) ¶

record_pattern_outcome(pattern_id, success) ¶

reset() ¶

Pattern¶

success_rate property ¶

record_usage(success) ¶

PatternMatch¶

Usage Patterns¶

Single-Agent Pattern Learning¶

Multi-Agent Pattern Sharing¶

Pattern Persistence¶

Pattern Discovery¶

Pattern Decay (Adaptive Learning)¶

Advanced Features¶

Pattern Conflict Detection¶

Pattern Recommendation¶

See Also¶

`init()` ¶

`contribute_pattern(agent_id, pattern)` ¶

`get_agent_patterns(agent_id)` ¶

`get_library_stats()` ¶

`get_pattern(pattern_id)` ¶

`get_related_patterns(pattern_id, depth=1)` ¶

`get_top_patterns(n=10, sort_by='success_rate')` ¶

`link_patterns(pattern_id_1, pattern_id_2)` ¶

`query_patterns(agent_id, context, pattern_type=None, min_confidence=0.5, limit=10)` ¶

`record_pattern_outcome(pattern_id, success)` ¶

`reset()` ¶

`success_rate` `property` ¶

`record_usage(success)` ¶