dno 0.2.8

Dynamic Neural Organism (DNO): A self-evolving, growing, and pruning neural network framework.

DNO: Dynamic Neural Organism 🧬

"Don't just train a model. Raise an organism."

DNO (Dynamic Neural Organism) is a next-generation PyTorch framework that treats neural networks as living, evolving biological entities. Unlike static architectures (Transformers, CNNs) that are fixed at initialization, a DNO grows, specializes, and adapts in real-time based on the complexity of the data it consumes.

---

📚 Table of Contents

1. Core Philosophy
2. What's New in v0.2.7
3. Installation
4. The DNO Lifecycle (User Guide)
   • Phase 1: DNA Configuration
   • Phase 2: Infancy (Scratch Training)
   • Phase 3: Adulthood (Adaptive Growth)
   • Phase 4: Serialization (Save/Load)
5. Advanced Mechanics
   • Surgical Training Control
   • Robust Persistence (Zombie Repair)
6. API Reference

---

🧠 Core Philosophy

Traditional AI is like a Statue: You carve it (define architecture), polish it (train), and it stays that way forever. DNO is like a Tree: You plant a seed (Seed Cortex). If the environment is rich (complex data), it grows branches (Expert Lobes). If a branch is useless, it withers (Pruning).

Key Features

• Neurogenesis (Mitosis): The network physically adds new layers when "confused" (High Entropy).
• Specialized Organisms: The brain divides into a "General Core" and "Expert Lobes".
• Dynamic Gradient Locking: Automatically freezes the General Core when training Experts, and vice versa.
• Smart Routing: Routes "Familiar" data to the Core and "Novel" data to Experts.
• Auto-Casting: Safely handles raw Token IDs (LongTensor) by auto-casting to Float32 where needed.

---

🚀 What's New in v0.2.7

Version 0.2.7 introduces Surgical Precision to the biological chaos.

1. Surgical Training Control

You can now forcefully intervene in the organism's growth:

• freeze_all_except(tag): Instantly freeze the entire brain except for a specific module (e.g., "expert_coding"). This allows for focused, interference-free training of new skills.
• inject_layer(parent, new_tag): Don't wait for evolution! Force a mitosis event on any layer to manually create a new expert lobe on demand.

2. Robust Persistence ("Zombie Repair")

Loading dynamic networks is risky—what if the factory fails to reconstruct a specific custom layer?

• Automatic Fallback: If a layer fails to load, DNO v0.2.7 automatically reconstructs it as a generic GPTModel block (Transformer Decoder), preserving the connections and topology.
• Deep Scan & Repair: After loading, the system performs a deep scan to identify and repair any "Zombie" (broken/None) modules.

3. Smart Manager

• Tag-Based Lookup: manager.get_module("expert_python") works instantly. No need to memorize UUIDs.
• Organ Summary: manager.list_organs() gives you a biological report of all active tissues (layers).

---

📦 Installation

pip install dno

Requires Python 3.8+ and PyTorch.

---

🧬 The DNO Lifecycle

Raising a DNO involves distinct biological phases.

1. DNA Configuration (DnoConfig)

Before birth, you must define the organism's genetic constraints.

from dno.config import DnoConfig

config = DnoConfig(
    # --- Lifecycle Control ---
    training_phase='scratch',   # Start in 'scratch' (Infancy) or 'adaptive' (Adulthood)
    
    # --- Growth Triggers ---
    entropy_threshold=0.6,      # If confusion > 0.6, consider growing
    evolution_cooldown_steps=100, # Wait 100 steps between growth events
    
    # --- Physical Constraints ---
    max_param_count=100_000_000, # Cap size at 100M parameters
    vram_limit_gb=4.0,           # Stop growing if VRAM exceeds 4GB
    
    # --- Architecture Defaults ---
    d_model=128,                 # Hidden dimension size
    n_heads=4                    # Attention heads (if using Transformer blocks)
)

2. Infancy (scratch Training)

Goal: Build a strong generalist core ("Seed Cortex"). Behavior: Growth is DISABLED. The model behaves like a standard, static PyTorch model.

from dno.core.manager import OrganismManager 
from dno.core.base import BaseEvolvableModule
from dno.core.network import DynamicNetwork
import torch.nn as nn

# 1. Initialize
manager = OrganismManager()
network = DynamicNetwork(manager, config)

# 2. Add the Seed Cortex (Your base model)
# Wrap any PyTorch module in BaseEvolvableModule
seed_layer = nn.Sequential(
    nn.Linear(128, 128),
    nn.ReLU(),
    nn.Linear(128, 10)
)
seed = BaseEvolvableModule(seed_layer)
seed.dynamic_id = "seed_cortex"
seed.set_specialty("general") # IMPORTANT: Mark as General Core

network.add_layer(seed)

# 3. Train as usual (Standard PyTorch Loop)
# In this phase, NO growth happens.
output = network(input_data)
loss.backward()
optimizer.step()

3. Adulthood (adaptive Growth)

Goal: Adapt to new, complex tasks by growing specialized organs. Behavior: The model monitors its own entropy. If it encounters data it cannot understand (High Entropy), it triggers Mitosis.

from dno.core.growth import GrowthEngine

# 1. Switch Phase
network.config.training_phase = 'adaptive'

# 2. Initialize Growth Engine
growth_engine = GrowthEngine(network, config)

# ... inside training loop ...
outputs = network(inputs)

# The network automatically calculates 'Entropy' (Confusion) during forward pass.
# You can check this history or let the engine handle it.

# 3. Check for Growth Trigger
is_triggered, reason = growth_engine.check_growth_trigger(
    entropy_history=network.get_recent_entropy(), 
    current_step=step
)

if is_triggered:
    print(f"🌟 EPIPHANY! Growing new expert due to: {reason}")
    
    # TRIGGER MITOSIS
    # Clones the 'seed_cortex' to create a new 'expert_coding_v1' module
    growth_engine.mitosis(
        parent_uuid="seed_cortex", 
        optimizer=optimizer, 
        specialty_tag="expert_coding_v1"
    )

4. Fluid Serialization

Standard torch.save fails on DNOs because their architecture (topology) changes dynamically. Use .dno format.

# Save everything (Topology + Weights + Config + History)
network.save_dno("my_organism.dno")

# Load it back
# Define a explicit factory to reconstruct your custom blocks
def my_reconstruction_factory(type_name):
    if type_name == "SeedBlock":
        return SeedBlock(...) 
    return nn.Linear(...) # Default fallback

# Load it back
new_network = DynamicNetwork.load_dno(
    "my_organism.dno", 
    module_factory=my_reconstruction_factory
)

---

🔧 Advanced Mechanics

Surgical Training Control (v0.2.7)

Use the GrowthEngine to manually direct evolution.

# 1. Force a new layer to grow from the seed
# IMPORTANT: Pass the optimizer so the new layer's parameters are registered!
growth_engine.inject_layer(
    parent_tag="seed_cortex", 
    new_tag="expert_math_v1",
    optimizer=optimizer 
)

# 2. Focus training ONLY on this new math expert
# This freezes "seed_cortex" and all other modules, preventing interference.
growth_engine.freeze_all_except("expert_math_v1")

# ... Train on math dataset ...

Robust Persistence & Zombie Repair (v0.2.7)

DNO v0.2.7 is resilient to corruption. If you load a brain but are missing the custom class definition for a specific organ, DNO won't crash.

# Identify missing/broken modules
net = DynamicNetwork.load_dno("brain.dno", module_factory=my_factory)

# DNO automatically detects "Zombie" nodes (where factory failed) 
# and resurrects them as generic GPT Blocks (Transformer Decoders).
# Your graph topology remains intact!

Dynamic Gradient Locking 🔒

DNO automatically manages requires_grad to prevent "Catastrophic Forgetting".

• Familiar Data (CPT): The system freezes all Expert layers. Only the General Core updates.
• Novel Data (SFT/High Entropy): The system freezes the General Core. Only the Expert layers update. This happens automatically inside network.forward() based on the data_type or entropy detection.

---

🤝 Contributing

DNO is an open-source experiment.

• Bug Reports: Open an issue on GitHub.
• Feature Requests: We are looking for new "Organs" (Memory modules, Attention blocks).

📜 License

MIT License.