Skip to content

Latest commit

 

History

History
234 lines (171 loc) · 7.72 KB

primitive.md

File metadata and controls

234 lines (171 loc) · 7.72 KB

Emerge: Goal-Directed Synchronization

Temporal coordination through adaptive strategies - Systems that pursue synchronization targets via multiple pathways, switching strategies when defaults fail to achieve coordination goals. See Goal-Directed for how this works.

Why Emerge?

Traditional synchronization requires explicit coordination logic. Emerge lets you specify WHAT you want (target state) and automatically figures out HOW to achieve it through adaptive strategies.

Real-World Problems It Solves

  • API Request Batching - Reduce API calls by 80% through automatic coordination
  • Load Distribution - Spread work across workers without central control
  • Connection Pooling - Optimize database connections adaptively
  • Task Scheduling - Coordinate concurrent tasks without explicit locks
  • Self-Healing Systems - Maintain service levels despite failures

See Use Cases for detailed examples.

Quick Start

For a comprehensive guide including scale selection, goal choosing, and integration with existing systems:

→ See the Quick Start Guide

For a quick code example:

import (
    "github.com/carlisia/bio-adapt/client/emerge"
    "github.com/carlisia/bio-adapt/emerge/swarm/scale"
)

client := emerge.MinimizeAPICalls(scale.Small)  // 50 agents
err := client.Start(ctx)

Configuration Options

1. Simple Presets - Recommended

// Use predefined configurations for common goals
client := emerge.MinimizeAPICalls(scale.Large)   // API batching
client := emerge.DistributeLoad(scale.Medium)    // Load balancing

2. Custom Configuration

// Fine-tune parameters with builder pattern
client := emerge.Custom().
    WithGoal(goal.MinimizeAPICalls).
    WithScale(scale.Large).
    WithTargetCoherence(0.95).
    Build()

3. Direct Swarm Access (Advanced)

// For advanced users who need direct swarm control
import "github.com/carlisia/bio-adapt/emerge"

cfg := swarm.For(goal.MinimizeAPICalls).With(scale.Large)
swarm, _ := swarm.New(1000, targetState, swarm.WithGoalConfig(cfg))
swarm.Run(ctx)

Core Concepts

Goal State

The target configuration you want the system to achieve:

  • Phase: Synchronization point (0 to 2π)
  • Frequency: How often agents act
  • Coherence: Synchronization level (0=chaos, 1=perfect)

Adaptive Strategies

System automatically switches between strategies to reach goals:

  • PhaseNudge: Gentle adjustments for stability
  • FrequencyLock: Align oscillation speeds
  • PulseCoupling: Strong synchronization bursts
  • EnergyAware: Resource-constrained coordination
  • Adaptive: Context-aware strategy selection

Energy Constraints

Realistic resource limits that prevent infinite adaptation:

agent.SetEnergy(100)                // Starting energy
agent.SetEnergyRecoveryRate(5)      // Units per second
agent.SetMinEnergyThreshold(20)     // Minimum to act

Use Case Examples

API Request Batching

// Goal: Minimize API calls through coordinated batching
client := emerge.MinimizeAPICalls(scale.Small)  // 50 agents
err := client.Start(ctx)

// Monitor synchronization
for !client.IsConverged() {
    time.Sleep(100 * time.Millisecond)
    fmt.Printf("Coherence: %.2f%%\n", client.Coherence() * 100)
}
// Result: 80% reduction in API calls

Load Distribution

// Goal: Spread work evenly (anti-synchronization)
client := emerge.DistributeLoad(scale.Medium)  // 200 agents
err := client.Start(ctx)

// The system automatically targets low coherence for distribution
// Result: Even load distribution without central scheduler

Database Connection Pooling

// Goal: Balance connection reuse and distribution
client := emerge.Custom().
    WithGoal(goal.MinimizeAPICalls).  // Similar to connection pooling
    WithScale(scale.Medium).
    WithTargetCoherence(0.7).  // Moderate clustering
    Build()

err := client.Start(ctx)
// Result: Adaptive connection management under varying load

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Agent 1   │◀────▶│   Agent 2   │◀────▶│   Agent 3   │
│   φ=0.2π    │     │   φ=0.3π    │     │   φ=0.25π   │
└─────────────┘     └─────────────┘     └─────────────┘
        ▲                   ▲                   ▲
        └───────────────────┼───────────────────┘
                   Adaptive Strategies
                            │
                            ▼
                ┌─────────────────────────┐
                │      Goal State         │
                │   Target: Coherence=0.9 │
                │   Multiple Paths →      │
                └─────────────────────────┘

Package Structure

emerge/
├── agent/          # Core agent implementation with optimizations
├── swarm/          # Swarm coordination and management
├── core/           # Fundamental types and interfaces
├── strategy/       # Adaptive strategy implementations
├── goal/           # Goal definitions and management
├── monitoring/     # Convergence tracking
└── decision/       # Strategy selection engines

Advanced Features

Disruption Recovery

swarm.DisruptAgents(0.3)  // Disrupt 30% of agents
// System automatically finds alternative paths to target
// Recovery means achieving the original goal, not just stability

Performance Optimizations

The system automatically optimizes based on scale:

  • Small swarms (≤100): Simple sync.Map for flexibility
  • Large swarms (>100): Fixed arrays for cache locality
  • Atomic grouping: Related fields share cache lines
  • Batch processing: Configurable for massive swarms

Performance Characteristics

  • Convergence: Sub-linear scaling with swarm size
  • Memory: ~2-3KB per agent at scale
  • Fault tolerance: Automatic multi-path recovery
  • Network overhead: O(log N) coordination traffic

Theory Foundation

Emerge combines mathematical models with goal-directed principles:

  • Kuramoto Model: Mathematical foundation for phase synchronization
  • Goal-Directedness: Systems maintain targets as invariants (Levin's research)
  • Attractor Basins: Multiple convergence paths to same target
  • Adaptive Navigation: Switch strategies when progress stalls

API Stability

  • Core interfaces (Agent, Swarm) are stable
  • Strategy interfaces support custom implementations
  • Internal optimizations are transparent to users

Contributing

We welcome contributions to make emerge even better! Areas of interest:

  • Performance optimizations for massive swarms (10,000+ agents)
  • New adaptive strategies for goal achievement
  • Integration with distributed systems frameworks
  • More real-world use case examples
  • More benchmarking and performance analysis

Please check our development guide and open an issue to discuss your ideas.

Learn More