GUI_API_AUDIT.md

# KEY System GUI API Audit

> **Generated**: January 3, 2026  
> **Purpose**: Specification for GUI redesign - All public APIs, data structures, actions, and observable state

---

## Table of Contents
1. [Public APIs](#1-public-apis)
2. [Data Structures](#2-data-structures)
3. [User Actions](#3-user-actions)
4. [Observable State](#4-observable-state)
5. [Event System](#5-event-system)
6. [Configuration Schema](#6-configuration-schema)

---

## 1. Public APIs

### 1.1 Brain Module (`brain.py`)

#### `Brain` (Abstract Base Class)
```python
class Brain(ABC):
    # Properties
    @property id: str                    # Unique brain identifier (12 char hex)
    @property generation: int            # Generation number
    @property fitness: Optional[float]   # Fitness score (settable)
    @property param_count: int           # Total trainable parameters
    @property brain_type: str            # Architecture type ('mlp', 'lora', 'random')
    
    # Core Methods (abstract)
    def forward(inputs: Dict[str, Any]) -> Dict[str, Any]
    def get_params() -> np.ndarray       # Flatten all params to 1D
    def set_params(params: np.ndarray)   # Load params from 1D array
    
    # State Management (for stateful brains)
    def get_state() -> Dict[str, Any]
    def set_state(state: Dict[str, Any])
    def reset_state()
    
    # Evolution Interface
    def mutate(rate: float = None, scale: float = None) -> Brain
    def crossover(other: Brain, method: str = 'uniform') -> Brain
    def copy() -> Brain
    
    # Serialization
    def save(path: Path)
    @classmethod load(path: Path) -> Brain
    def to_dict() -> Dict[str, Any]
```

#### `MLPBrain` (Concrete)
```python
class MLPBrain(Brain):
    # Properties
    input_size: int
    hidden_size: int
    output_size: int
    activation: Callable  # 'tanh', 'relu', 'sigmoid', 'linear'
    
    # Weights (internal)
    w1: np.ndarray  # (input_size, hidden_size)
    b1: np.ndarray  # (hidden_size,)
    w2: np.ndarray  # (hidden_size, output_size)
    b2: np.ndarray  # (output_size,)
```

#### `LoRABrain` (VLM Adapter Evolution)
```python
class LoRABrain(Brain):
    # Configuration
    lora_rank: int = 8
    lora_alpha: int = 16
    target_modules: List[str] = ['q_proj', 'v_proj']
    hidden_dim: int = 2048
    test_mode: bool = False
    
    # Class-level (shared singleton)
    _base_model: Model           # Frozen VLM (shared)
    _processor: Processor        # Tokenizer/processor (shared)
    
    # Instance-level
    _adapter_weights: Dict[str, np.ndarray]  # Per-module LoRA A/B matrices
    _peft_model: PeftModel       # PEFT model instance
    
    # Methods
    def forward(inputs: Dict) -> Dict[str, Any]
        # inputs: {'text': str, 'image': optional, 'video': optional, 'max_new_tokens': int}
        # returns: {'response': str, 'confidence': float}
    
    async def aforward(prompt: str, images=None, max_new_tokens: int = 512) -> str
    
    def get_adapter_weights() -> Dict[str, np.ndarray]
    def apply_to_model()          # Apply evolved weights to PEFT model
    def save_adapter(path: Path)
    @classmethod load_adapter(path: Path) -> LoRABrain
    
    # Quine (Self-Replication)
    def to_source(path: Path = None) -> str    # Generate Python source file
    @classmethod from_source(path: Path) -> LoRABrain
    def replicate(mutation_rate: float = 0.1, mutation_scale: float = 0.1, 
                  output_dir: Path = None) -> Path  # Write mutated child as .py file
    
    async def live(pulse=None, vp=None, perceive_fn=None, max_ticks: int = None)
```

#### Factory Functions
```python
def create_Brain(brain_type: str, **kwargs) -> Brain
def create_population(n: int, brain_type: str = 'mlp', **kwargs) -> List[Brain]
```

---

### 1.2 Mobile Population (`mobile.py`)

```python
class MobilePopulation:
    """Async population where each brain runs its own lifecycle loop"""
    
    # Constructor
    def __init__(
        pulse: Pulse = None,
        vp: ViolationPressure = None,
        children_dir: Path = None,
        max_population: int = 100,
        enable_logging: bool = False,
    )
    
    # Properties (Observable State)
    members: Dict[str, BrainState]  # Active brains
    total_spawned: int
    total_despawned: int
    generation: int
    pulse: Pulse
    vp: ViolationPressure
    
    # Core Methods
    async def spawn(brain: LoRABrain) -> str        # Add brain, returns ID
    async def despawn(brain_id: str)                # Remove brain
    async def run_forever(tick_interval: float = 0.01)
    async def run_for(duration: float = None, ticks: int = None)
    async def shutdown()
    
    # Status
    def status() -> Dict[str, Any]
        # Returns: {
        #   'population_size': int,
        #   'max_population': int,
        #   'total_spawned': int,
        #   'total_despawned': int,
        #   'generation': int,
        #   'running': bool,
        #   'brains': Dict[id, BrainState]
        # }

@dataclass
class BrainState:
    brain: LoRABrain
    task: asyncio.Task
    spawned_at: float
    tick_count: int
    last_fitness: float
    children_spawned: int
    status: str  # 'running', 'stopping', 'cancelled', 'error: ...'

# Convenience Function
async def run_mobile_evolution(
    initial_population: int = 5,
    duration: float = None,
    ticks: int = 100,
    layers: List[int] = None,
) -> MobilePopulation
```

---

### 1.3 Population Manager (`population.py`)

```python
class PopulationManager:
    """NEAT-inspired population management with speciation"""
    
    # Constructor
    def __init__(
        trait_keys: List[str],
        population_size: int,
        fitness_fn: Callable[[Node], float],
        config: SpeciesConfig = None,
        brain_factory: Optional[Callable] = None,
    )
    
    # Properties (Observable State)
    population: List[Node]
    species_list: List[Species]
    generation: int
    best_node: Node
    best_fitness: float
    history: List[Dict]
    trait_keys: List[str]
    config: SpeciesConfig
    
    # Core Methods
    def evaluate(verbose: bool = False) -> List[float]
    def speciate(verbose: bool = False)
    def reproduce() -> Dict  # Returns: {'mutations': int, 'crossovers': int, 'elites': int, 'eliminated': int}
    def step(verbose: bool = False) -> Dict  # evaluate + speciate + reproduce
    
    # Query Methods
    def get_snapshot() -> Dict[str, Any]  # Comprehensive population state
    def get_best() -> Tuple[Node, float]
    def get_species_info() -> List[Dict]
    
    # Serialization
    def to_checkpoint_dict() -> Dict
    @staticmethod from_checkpoint_dict(data: Dict, fitness_fn: Callable, brain_factory=None) -> PopulationManager

@dataclass
class SpeciesConfig:
    genetic_distance_threshold: float = 0.35
    max_stagnation: int = 50
    elitism: int = 0
    survival_threshold: float = 0.2
    crossover_rate: float = 0.7
    min_species_size: int = 3
    tournament_size: int = 3

class Species:
    id: int
    representative: Node
    members: List[Node]
    generation_created: int
    last_improvement: int
    best_fitness: float
    avg_fitness: float
    
    def get_avg_fitness() -> float
    def get_best_fitness() -> float
    def is_stagnant(current_gen: int, max_stagnation: int) -> bool
    def contains_node(node, threshold: float) -> bool
    def update_representative()

def genetic_distance(node1, node2) -> float  # Returns 0-1+
```

---

### 1.4 VLM Base (`vlm_base.py`)

```python
# Configuration
@dataclass
class VLMConfig:
    model_name: str = "Qwen/Qwen2.5-VL-3B-Instruct"
    quantization: Literal['none', '8bit', '4bit'] = '4bit'
    device: str = 'auto'
    torch_dtype: str = 'float16'
    trust_remote_code: bool = True
    use_flash_attention: bool = False
    max_memory: Optional[Dict[str, str]] = None
    offload_folder: Optional[str] = None
    min_pixels: int = 256 * 28 * 28
    max_pixels: int = 1280 * 28 * 28

# Singleton API
def configure(
    model_name: str = None,
    quantization: Literal['none', '8bit', '4bit'] = None,
    device: str = None,
    torch_dtype: str = None,
    use_flash_attention: bool = None,
    max_memory: Dict[str, str] = None,
    offload_folder: str = None,
    min_pixels: int = None,
    max_pixels: int = None,
) -> VLMConfig

def get_config() -> VLMConfig
def get_base_model() -> Model      # Singleton, loads on first call
def get_processor() -> Processor   # Singleton
def reload()                       # Force reload with current config
```

---

### 1.5 Configuration (`config.py`)

```python
def load_config(path: Path = None) -> Dict[str, Any]
def get(section: str, key: str = None, default: Any = None) -> Any
def reload() -> Dict[str, Any]
def get_defaults() -> Dict[str, Any]
```

---

### 1.6 Causation Explorer (`explorer.py`)

```python
@dataclass
class Event:
    timestamp: float
    component: str
    event_type: str  # 'state_change', 'threshold_crossed', 'transition'
    data: Dict[str, Any]
    event_id: str
    
    def to_dict() -> Dict[str, Any]

@dataclass
class CausationLink:
    from_event: str
    to_event: str
    causation_type: str  # 'temporal', 'correlation', 'threshold', 'direct'
    strength: float      # 0.0-1.0
    explanation: str
    metrics: List[str]

class CausationExplorer:
    # Properties
    graph: nx.DiGraph           # Causation graph (NetworkX)
    events: Dict[str, Event]
    events_by_component: Dict[str, List[str]]
    events_by_type: Dict[str, List[str]]
    metric_history: Dict[str, deque]
    thresholds: Dict[str, Dict]  # Configurable thresholds
    
    # Event Management
    def add_event(event: Event) -> List[CausationLink]
    
    # Exploration
    def explore_backwards(event_id: str, max_depth: int = 10) -> List[Dict]
    def explore_forwards(event_id: str, max_depth: int = 10) -> List[Dict]
    def find_path(from_id: str, to_id: str) -> Optional[List[Dict]]
    def get_event_summary(event_id: str) -> Dict[str, Any]
    
    # Search
    def search(query: str) -> List[Dict]
    def search_by_metric(metric: str, min_val: float = None, max_val: float = None) -> List[Dict]
    
    # Statistics
    def stats() -> Dict[str, Any]
    
    # Data Loading
    def load_from_json(filepath: Path) -> int
    def load_from_jsonl(filepath: Path) -> int
    def load_all_jsonl(log_dir: Path = None) -> int
    def load_from_shared_state(filepath: Path = None) -> int
    def load_from_logs(log_dir: Path = None) -> int
    def load_all(data_dir: Path = None) -> Dict[str, int]
    
    # Export
    def save_to_json(filepath: Path)
    def to_numpy() -> Tuple[np.ndarray, np.ndarray, List[str]]  # features, adjacency, event_ids
    def to_dataframe() -> pd.DataFrame
```

---

### 1.7 Fitness Functions (`fitness.py`, `fitness_code.py`)

#### Base Classes
```python
class Fitness(ABC):
    @abstractmethod def evaluate(node: Any, context: Dict = None) -> float
    def evaluate_batch(nodes: List, context: Dict = None) -> np.ndarray
    @property name: str
    @property is_minimization: bool

class FunctionFitness(Fitness):  # Wrap lambda as Fitness
class CompositeFitness(Fitness): # Weighted combination
```

#### Benchmark Functions
```python
class SphereFitness(Fitness)      # f(x) = -sum(x_i^2)
class RastriginFitness(Fitness)   # Multimodal, many local optima
class RosenbrockFitness(Fitness)  # Narrow curved valley
```

#### VLM Fitness
```python
@dataclass
class VLMTask:
    prompt: str
    image: Optional[Union[str, Path, np.ndarray]] = None
    video: Optional[Union[str, Path]] = None
    expected: Optional[str] = None
    keywords: List[str] = []
    forbidden: List[str] = []
    bbox_expected: Optional[List[float]] = None
    max_tokens: int = 128
    weight: float = 1.0

class VLMFitness(Fitness):
    def __init__(tasks: List[VLMTask], time_penalty: float = 0.0, ...)
    def evaluate(node, context=None) -> float
```

#### Code Understanding Fitness
```python
@dataclass
class CodeTask:
    file_path: str
    code_snippet: str
    question: str
    expected_keywords: List[str]
    task_type: str  # 'comprehension', 'pattern', 'reasoning'
    difficulty: float = 1.0

class CodeFitness:
    def __init__(config: CodeFitnessConfig = None)
    def evaluate(adapter_id: str) -> float
    def evaluate_single(adapter, prompt: str, code_snippet: str, expected_keywords: List[str]) -> float
```

---

### 1.8 Pulse & Pressure (`pulse.py`, `pressure.py`)

#### Pulse (System Clock)
```python
class Pulse:
    # Properties
    rate: float      # Breaths per second
    phase: float     # 0 to 2π
    depth: float     # 0 to 1
    cycle: int       # Completed cycles
    intensity: float # Multiplier
    
    # Methods
    def tick() -> Dict[str, float]  # Advance pulse, return state
    def state() -> Dict[str, float] # {'depth', 'phase', 'cycle', 'intensity', 'timestamp'}
    def value() -> float            # depth * intensity
    def is_inhale() -> bool         # phase < π
    def is_exhale() -> bool         # phase >= π
    def set_rate(rate: float)
    def set_intensity(intensity: float)
```

#### Violation Pressure (Loss Function)
```python
class ViolationClass(Enum):
    VP0 = "VP0"  # 0.00-0.25: Stable
    VP1 = "VP1"  # 0.25-0.50: Drifting
    VP2 = "VP2"  # 0.50-0.75: Unstable
    VP3 = "VP3"  # 0.75-0.99: Critical
    VP4 = "VP4"  # >= 1.00: Collapse

@dataclass
class StabilityEnvelope:
    center: float = 0.5
    radius: float = 0.25
    compression: float = 1.0

class ViolationPressure:
    envelopes: Dict[str, StabilityEnvelope]
    
    def set_envelope(trait: str, center: float, radius: float, compression: float)
    def get_envelope(trait: str) -> StabilityEnvelope
    def compute(traits: Dict[str, float]) -> Tuple[float, Dict[str, float]]  # (total_vp, breakdown)
    def classify(total_vp: float) -> ViolationClass
    def error(traits: Dict[str, float]) -> float  # Simple loss value
    
    # ML Integration
    def as_loss_fn() -> Callable
    def torch_loss(values, centers, radii) -> Tensor
```

---

### 1.9 Tracking (`tracking.py`)

#### WandB Tracker
```python
class WandbTracker:
    def __init__(project: str = "evolutionary-nlp", entity: str = None, enabled: bool = True)
    def start_run(name: str = None, config: Dict = None, tags: List[str] = None)
    def log_generation(generation: int, fitness: np.ndarray, species_info: List[Dict] = None, extra_metrics: Dict = None)
    def log_evaluation(generation: int, train_metrics: Dict, eval_metrics: Dict)
    def log_population_viz(generation: int, embedding: np.ndarray, labels: np.ndarray, fitness: np.ndarray)
    def log_vlm_inference(adapter_id, file, task_type, question, response, prompt_tokens, output_tokens, inference_ms, ...)
    def log_vlm_fitness(adapter_id, fitness, scores, task_types, step=None)
    def log_causation_event(event_type, component, data, links=None, step=None)
    def log_adapter_population(generation, adapter_fitness, adapter_similarity=None, anomaly_ratio=None, diversity_score=None)
    def save_inference_table()
    def finish()
```

#### TensorBoard Tracker
```python
class TensorBoardTracker:
    def __init__(log_dir: str = "runs", experiment_name: str = None, enabled: bool = True)
    def log_generation(generation: int, fitness: np.ndarray, species_info: List[Dict] = None, extra_metrics: Dict = None)
    def log_evaluation(generation: int, train_metrics: Dict, eval_metrics: Dict)
    def close()
```

#### Unified Tracker
```python
class EvolutionTracker:
    def __init__(backend: str = "auto", project: str = "evolutionary-nlp", log_dir: str = "runs")
        # backend: "wandb", "tensorboard", "auto", "none"
    def start_run(name: str = None, config: Dict = None)
    def log_generation(generation: int, fitness: np.ndarray, species_info: List[Dict] = None, extra_metrics: Dict = None)
    def log_evaluation(generation: int, train_metrics: Dict, eval_metrics: Dict)
    def finish()
```

---

### 1.10 Checkpointing (`checkpoints.py`)

```python
@dataclass
class CheckpointMetadata:
    name: str
    version: str
    timestamp: str
    generation: int
    best_fitness: float
    avg_fitness: float
    num_species: int
    population_size: int
    config_hash: str
    notes: str = ""

@dataclass
class Checkpoint:
    metadata: CheckpointMetadata
    config: Dict
    population_traits: List[Dict]
    history: List[Dict]
    species_data: Optional[Dict]
    nlp_weights: Optional[bytes]
    event_log: Optional[List[Dict]]
    
    def save(path: Path = None) -> Path
    @classmethod load(path: Path) -> Checkpoint

# Functions
def create_checkpoint(name, generation, config, population, history, ...) -> Checkpoint
def list_checkpoints(name_filter: str = None) -> List[CheckpointMetadata]
def get_latest_checkpoint(name: str = None) -> Optional[Path]
def compare_checkpoints(ckpt1, ckpt2) -> Dict

class AutoCheckpointer:
    def __init__(name, config, checkpoint_every=50, keep_best=5, keep_recent=3)
    def maybe_checkpoint(generation, population, history, ..., force=False) -> Optional[Path]
```

---

### 1.11 Node (`node.py`)

```python
@dataclass
class Node:
    traits: Dict[str, float]
    generation: int = 0
    parent_ids: List[str] = []
    brain: Optional[Brain] = None
    fitness: Optional[float] = None
    
    @property id: str
    
    # Methods
    def score(vp: ViolationPressure) -> float
    def mutate(rate: float = 0.1, mutate_brain: bool = True) -> Node
    def crossover(other: Node, cross_brain: bool = True) -> Node
    def think(inputs: Dict) -> Dict
    def has_brain() -> bool
    def attach_brain(brain: Brain)
    def detach_brain() -> Optional[Brain]
    def to_vector(keys: List[str] = None) -> np.ndarray
    @classmethod from_vector(vector: np.ndarray, keys: List[str]) -> Node
    def to_dict() -> Dict
    @classmethod from_dict(data: Dict, brain_class=None) -> Node

# Helper Functions
def random_node(keys: List[str], brain_factory=None) -> Node
def create_nodes(n: int, keys: List[str], brain_factory=None) -> List[Node]
def create_population(n: int, keys: List[str], brain_factory=None) -> List[Node]
```

---

## 2. Data Structures

### 2.1 Brain State
```python
{
    'id': str,                    # 12-char hex identifier
    'brain_type': str,            # 'mlp', 'lora', 'random'
    'generation': int,            # Generation number
    'param_count': int,           # Total parameters
    'fitness': Optional[float],   # Current fitness
    'parent_ids': List[str],      # Parent brain IDs
    
    # LoRA-specific
    'lora_rank': int,
    'lora_alpha': int,
    'target_modules': List[str],
    'hidden_dim': int,
    'adapter_weights': Dict[str, np.ndarray],
}
```

### 2.2 Population Snapshot
```python
{
    # Core
    'generation': int,
    'population_size': int,
    
    # Fitness
    'best_fitness': float,
    'avg_fitness': float,
    'min_fitness': float,
    'max_fitness': float,
    'fitness_std': float,
    'fitness_range': float,
    'selection_pressure': float,
    
    # Species
    'num_species': int,
    'species_sizes': List[int],
    'species_avg_fitnesses': List[float],
    'species_best_fitnesses': List[float],
    'largest_species_size': int,
    'smallest_species_size': int,
    'avg_species_age': float,
    'max_stagnation': int,
    
    # Sklearn Clustering Quality
    'silhouette_score': float,        # [-1, 1]
    'davies_bouldin_score': float,    # [0, inf)
    'calinski_harabasz_score': float, # [0, inf)
    
    # Diversity
    'overall_diversity': float,
    'trait_means': Dict[str, float],
    'trait_stds': Dict[str, float],
    
    # Brain/Neural metrics
    'num_brains': int,
    'brain_ratio': float,
    'avg_brain_params': float,
    'avg_brain_weight_mean': float,
    'avg_brain_weight_std': float,
    'avg_brain_weight_norm': float,
    'brain_weight_norm_std': float,
    
    # LoRA Adapter metrics
    'num_lora_brains': int,
    'avg_lora_params': float,
    'avg_lora_rank': float,
    'lora_weight_diversity': float,
    'avg_adapter_similarity': float,
    'min_adapter_similarity': float,
    'max_adapter_similarity': float,
    'num_anomalous_adapters': int,
    'anomaly_ratio': float,
    
    # Reproduction stats (from step())
    'mutations': int,
    'crossovers': int,
    'elites': int,
    'eliminated': int,
    'step_time_ms': float,
}
```

### 2.3 Species Info
```python
{
    'id': int,
    'size': int,
    'avg_fitness': float,
    'best_fitness': float,
    'age': int,                  # Generations since created
    'stagnant_gens': int,        # Generations without improvement
}
```

### 2.4 Pulse State
```python
{
    'depth': float,       # 0-1, sine wave position
    'phase': float,       # 0 to 2π
    'cycle': int,         # Completed breath cycles
    'intensity': float,   # Multiplier
    'timestamp': float,   # Last tick time
}
```

### 2.5 Violation Pressure State
```python
{
    'total_vp': float,           # 0-1+ overall pressure
    'vp_class': ViolationClass,  # VP0-VP4
    'breakdown': Dict[str, float],  # Per-trait VP values
}
```

### 2.6 Mobile Population Status
```python
{
    'population_size': int,
    'max_population': int,
    'total_spawned': int,
    'total_despawned': int,
    'generation': int,
    'running': bool,
    'brains': {
        brain_id: {
            'id': str,
            'generation': int,
            'ticks': int,
            'fitness': float,
            'children': int,
            'status': str,  # 'running', 'stopping', 'cancelled', 'error: ...'
        }
    }
}
```

### 2.7 Causation Event
```python
{
    'event_id': str,
    'timestamp': float,
    'component': str,
    'event_type': str,
    'data': Dict[str, Any],
}
```

### 2.8 Checkpoint
```python
{
    'metadata': {
        'name': str,
        'version': str,
        'timestamp': str,
        'generation': int,
        'best_fitness': float,
        'avg_fitness': float,
        'num_species': int,
        'population_size': int,
        'config_hash': str,
        'notes': str,
    },
    'config': Dict,
    'population': List[NodeDict],
    'species': List[SpeciesDict],
    'history': List[SnapshotDict],
}
```

---

## 3. User Actions

### 3.1 Initialization
| Action | API Call | Parameters |
|--------|----------|------------|
| Create Population Manager | `PopulationManager(...)` | trait_keys, population_size, fitness_fn, config, brain_factory |
| Create Mobile Population | `MobilePopulation(...)` | pulse, vp, children_dir, max_population |
| Configure VLM | `vlm_base.configure(...)` | model_name, quantization, device, ... |
| Load Config | `config.load_config(path)` | path |

### 3.2 Evolution Control
| Action | API Call | Parameters |
|--------|----------|------------|
| Step (sync) | `pm.step(verbose)` | verbose |
| Evaluate Only | `pm.evaluate(verbose)` | verbose |
| Speciate Only | `pm.speciate(verbose)` | verbose |
| Reproduce | `pm.reproduce()` | - |
| Run Mobile (forever) | `await pop.run_forever(tick_interval)` | tick_interval |
| Run Mobile (limited) | `await pop.run_for(duration, ticks)` | duration, ticks |
| Shutdown | `await pop.shutdown()` | - |

### 3.3 Brain Management
| Action | API Call | Parameters |
|--------|----------|------------|
| Spawn Brain | `await pop.spawn(brain)` | brain |
| Despawn Brain | `await pop.despawn(brain_id)` | brain_id |
| Mutate Brain | `brain.mutate(rate, scale)` | rate, scale |
| Crossover Brains | `brain.crossover(other, method)` | other, method |
| Copy Brain | `brain.copy()` | - |
| Replicate (Quine) | `brain.replicate(mutation_rate, output_dir)` | mutation_rate, output_dir |

### 3.4 Checkpointing
| Action | API Call | Parameters |
|--------|----------|------------|
| Save Checkpoint | `checkpoint.save(path)` | path |
| Load Checkpoint | `Checkpoint.load(path)` | path |
| Create Checkpoint | `create_checkpoint(...)` | name, generation, config, population, history, ... |
| List Checkpoints | `list_checkpoints(name_filter)` | name_filter |
| Get Latest | `get_latest_checkpoint(name)` | name |
| Auto-checkpoint | `checkpointer.maybe_checkpoint(...)` | generation, population, ... |
| Compare | `compare_checkpoints(ckpt1, ckpt2)` | ckpt1, ckpt2 |

### 3.5 Saving/Loading
| Action | API Call | Parameters |
|--------|----------|------------|
| Save Brain | `brain.save(path)` | path |
| Load Brain | `Brain.load(path)` | path |
| Save Adapter | `lora_brain.save_adapter(path)` | path |
| Load Adapter | `LoRABrain.load_adapter(path)` | path |
| Export to Source | `brain.to_source(path)` | path |
| Load from Source | `LoRABrain.from_source(path)` | path |
| Save PM State | `pm.to_checkpoint_dict()` | - |
| Load PM State | `PopulationManager.from_checkpoint_dict(...)` | data, fitness_fn |

### 3.6 Tracking
| Action | API Call | Parameters |
|--------|----------|------------|
| Start Run | `tracker.start_run(name, config, tags)` | name, config, tags |
| Log Generation | `tracker.log_generation(gen, fitness, species_info, extra)` | gen, fitness, ... |
| Log Evaluation | `tracker.log_evaluation(gen, train_metrics, eval_metrics)` | gen, metrics, ... |
| Log VLM Inference | `wandb_tracker.log_vlm_inference(...)` | adapter_id, file, task_type, ... |
| Log Causation | `wandb_tracker.log_causation_event(...)` | event_type, component, data, links |
| Finish | `tracker.finish()` | - |

### 3.7 Causation Exploration
| Action | API Call | Parameters |
|--------|----------|------------|
| Add Event | `explorer.add_event(event)` | event |
| Explore Why | `explorer.explore_backwards(event_id, max_depth)` | event_id, max_depth |
| Explore Effects | `explorer.explore_forwards(event_id, max_depth)` | event_id, max_depth |
| Find Path | `explorer.find_path(from_id, to_id)` | from_id, to_id |
| Search Events | `explorer.search(query)` | query |
| Get Stats | `explorer.stats()` | - |
| Load Data | `explorer.load_all(data_dir)` | data_dir |

### 3.8 Configuration
| Action | API Call | Parameters |
|--------|----------|------------|
| Get Config Value | `config.get(section, key, default)` | section, key, default |
| Reload Config | `config.reload()` | - |
| Set VP Envelope | `vp.set_envelope(trait, center, radius, compression)` | trait, center, radius, compression |
| Set Pulse Rate | `pulse.set_rate(rate)` | rate |
| Set Pulse Intensity | `pulse.set_intensity(intensity)` | intensity |

---

## 4. Observable State

### 4.1 Real-time Metrics (per step/tick)
| Metric | Source | Update Frequency |
|--------|--------|------------------|
| Current Generation | `pm.generation`, `pop.generation` | Per step/tick |
| Population Size | `len(pm.population)`, `len(pop.members)` | Per step |
| Best Fitness | `pm.best_fitness` | Per step |
| Avg Fitness | `snapshot['avg_fitness']` | Per step |
| Fitness Distribution | `snapshot` fitness stats | Per step |
| Species Count | `len(pm.species_list)` | Per step |
| Pulse State | `pulse.state()` | Per tick |
| VP Level | `vp.compute(traits)` | Per tick |

### 4.2 Curves (time series)
| Metric | Source | Chart Type |
|--------|--------|------------|
| Fitness over generations | `pm.history` | Line chart |
| Species count over time | `pm.history` | Line chart |
| Diversity over time | `snapshot['overall_diversity']` | Line chart |
| VP levels over time | Per-brain VP values | Multi-line |
| Population size over time | `pm.history` | Area chart |
| Selection pressure | `snapshot['selection_pressure']` | Line chart |

### 4.3 Population Composition
| Metric | Source | Visualization |
|--------|--------|---------------|
| Species distribution | `pm.get_species_info()` | Pie/treemap |
| Fitness per species | Species info | Box plot |
| Trait distributions | `snapshot['trait_means/stds']` | Histogram |
| Brain type breakdown | Population analysis | Bar chart |
| LoRA adapter similarity | `snapshot['avg_adapter_similarity']` | Heatmap |

### 4.4 Individual Brain State
| Metric | Source | Update |
|--------|--------|--------|
| Brain ID | `brain.id` | Static |
| Generation | `brain.generation` | Static |
| Param Count | `brain.param_count` | Static |
| Fitness | `brain.fitness` | Per eval |
| Parent IDs | `brain._parent_ids` | Static |
| Adapter Weights | `lora_brain.get_adapter_weights()` | On demand |

### 4.5 Causation Graph
| Metric | Source | Visualization |
|--------|--------|---------------|
| Event count | `explorer.stats()['total_events']` | Counter |
| Link count | `explorer.stats()['total_links']` | Counter |
| Graph density | `explorer.stats()['graph_density']` | Gauge |
| Components | `explorer.events_by_component` | Legend |
| Strongest links | `explorer.stats()['strongest_links']` | Table |

---

## 5. Event System

### 5.1 Events to Log/Display
| Event | Trigger | Data |
|-------|---------|------|
| Fitness Improvement | New best fitness | old_best, new_best, node_id, traits |
| Species Created | New species | species_id, founding_node_id, founding_traits |
| Species Extinct | Species dies | species_id, age, peak_fitness, cause |
| Mutation | Node mutated | parent_id, child_id, parent_traits, child_traits |
| Crossover | Crossover occurs | parent1_id, parent2_id, child_id, traits |
| Selection | Generation complete | selected_ids, eliminated_ids, elite_ids |
| Brain Spawn | Mobile spawn | brain_id, generation, parent_id |
| Brain Despawn | Mobile despawn | brain_id, reason, tick_count |
| VP Threshold | VP level change | vp_class, total_vp, traits |
| Checkpoint Saved | Checkpoint written | filepath, generation, best_fitness |
| Checkpoint Loaded | Checkpoint loaded | filepath, generation |

### 5.2 Event Types (CausationExplorer)
- `state_change` - General metric update
- `threshold_crossed` - VP/metric threshold crossed
- `transition` - State machine transition

### 5.3 Causation Types
- `temporal` - Time-based correlation
- `correlation` - Metrics changed together
- `threshold` - Threshold crossing caused event
- `direct` - Known direct causation (pulse→network, etc.)

---

## 6. Configuration Schema

### 6.1 Full `config.json` Schema
```json
{
  "pressure": {
    "default_center": 0.5,
    "default_radius": 0.25,
    "default_compression": 1.0,
    "envelopes": {
      "<trait_name>": {"center": float, "radius": float, "compression": float}
    }
  },
  "vp_thresholds": {
    "VP0": 0.25, "VP1": 0.5, "VP2": 0.75, "VP3": 0.99,
    "modularity_collapse": 0.3, "organism_collapse": 500
  },
  "convergence": {"mutation_rate": 0.1, "noise_std": 0.05},
  "attractor": {"max_iterations": 1000, "tolerance": 1e-6, "learning_rate": 0.01},
  "pulse": {"rate": 1.0, "intensity": 1.0, "decay": 0.99},
  "population": {
    "size": 6, "dimensions": 10,
    "trait_keys": ["x0", "x1", ...],
    "use_brains": true
  },
  "evolution": {
    "generations": 100, "mutation_rate": 0.3, "mutation_strength": 0.2,
    "crossover_rate": 0.7, "fitness_function": "code",
    "target_species": 5, "log_interval": 10, "mode": "hybrid"
  },
  "speciation": {
    "genetic_distance_threshold": 0.25, "max_stagnation": 15,
    "elitism": 2, "survival_threshold": 0.2,
    "crossover_rate": 0.7, "min_species_size": 3
  },
  "dbscan": {"eps": null, "min_samples": 3, "eps_percentile": 0.7, "scale_features": true},
  "fitness": {
    "function": "code", "bounds_low": -5.12, "bounds_high": 5.12,
    "normalize": true, "invert": true
  },
  "communication": {
    "enabled": false, "max_turns": 10, "task_type": "collaboration",
    "role_pair": ["Developer", "Architect"],
    "scoring_weights": {"turn_engagement": 0.3, "task_completion": 0.3, "coherence": 0.4}
  },
  "node": {"mutation_rate": 0.3, "mutation_strength": 0.2},
  "brain": {
    "enabled": false, "hidden_sizes": [16, 16],
    "activation": "tanh", "mutation_rate": 0.1, "mutation_strength": 0.3
  },
  "lora_brain": {
    "enabled": true, "base_model": "D:/models/Qwen2.5-VL-3B-Instruct",
    "quantization": "4bit", "lora_rank": 8, "lora_alpha": 16,
    "lora_dropout": 0.0, "target_modules": ["q_proj", "v_proj"],
    "hidden_dim": 2048, "use_flash_attention": false
  },
  "vlm": {
    "min_pixels": 200704, "max_pixels": 1003520,
    "max_new_tokens": 150, "code_dir": "F:/folder/key", "tasks_per_eval": 3
  },
  "weight_evolution": {
    "algorithm": "CMA_ES", "sigma_init": 0.1, "weight_decay": 0.0, "fitness_shaping": true
  },
  "nlp_training": {
    "enabled": true, "vocab_size": 1500, "embed_dim": 64,
    "hidden_dim": 128, "max_seq_len": 32, "num_lstm_layers": 1,
    "num_classes": 2, "population_size": 16, "sigma_init": 0.3,
    "train_samples": 64, "eval_samples": 32
  },
  "explorer": {
    "log_dir": "data/logs", "shared_state_path": "data/.shared_simulation_state.json",
    "max_events": 10000,
    "causation_thresholds": {"temporal_window": 1.0, "correlation_min": 0.7, "direct_max_delay": 0.1}
  },
  "checkpointing": {
    "enabled": true, "checkpoint_every": 10, "keep_best": 5,
    "keep_recent": 3, "checkpoint_dir": "checkpoints"
  },
  "logging": {
    "wandb_project": "key-evolution", "wandb_entity": null,
    "tensorboard_enabled": true, "tensorboard_logdir": "runs/key",
    "log_interval": 1, "log_level": "INFO"
  },
  "performance": {
    "batch_size": 5, "tick_delay_ms": 20, "parallel_fitness": true, "num_workers": 4
  },
  "hf_sync": {
    "enabled": true, "dataset_name": null, "sync_checkpoints": true,
    "sync_logs": true, "retry_attempts": 3, "timeout_seconds": 30
  },
  "visualization": {
    "umap_enabled": true, "umap_n_neighbors": 15, "umap_min_dist": 0.1,
    "umap_n_jobs": 1, "plot_every": 10, "max_history_points": 500
  },
  "selection": {"method": "tournament", "tournament_size": 3, "truncation_threshold": 0.5},
  "experiment": {"name": "default", "tags": ["evolution", "bbob"], "seed": 42, "deterministic": true}
}
```

---

## GUI Design Recommendations

### Panels/Views
1. **Dashboard** - Overview: generation, best fitness, population size, VP status
2. **Population View** - Species tree, fitness distribution, individual brains
3. **Evolution Control** - Start/stop/step, parameter adjustments
4. **Brain Inspector** - Selected brain details, weights visualization, lineage
5. **Causation Explorer** - Event graph, search, exploration tools
6. **Metrics Charts** - Fitness curves, diversity, species count over time
7. **Checkpoints** - List, load, compare, export
8. **Configuration** - Edit config.json sections, VP envelopes
9. **Logs** - Real-time event stream, wandb/tensorboard links

### Real-time Updates
- WebSocket or polling for `get_snapshot()`, `pulse.state()`, `pop.status()`
- Event stream from logger for mutations, crossovers, spawns

### Key Interactions
- Click brain → show details, lineage, weights
- Click species → filter to species members
- Click event → explore causation backwards/forwards
- Drag VP envelope centers/radii in visualization
- Play/pause/step evolution controls