Metadata-Version: 2.1
Name: dno
Version: 0.2.7
Summary: Dynamic Neural Organism (DNO): A self-evolving, growing, and pruning neural network framework.
Home-page: https://github.com/yourusername/dno
Author: Uğurhan Çolak
Author-email: ugurhancolak5544@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch (>=1.9.0)
Requires-Dist: numpy

# DNO: Dynamic Neural Organism 🧬

[![PyPI version](https://badge.fury.io/py/dno.svg)](https://badge.fury.io/py/dno)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> **"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](#core-philosophy)
2. [What's New in v0.2.7](#whats-new-in-v027)
3. [Installation](#installation)
4. [The DNO Lifecycle (User Guide)](#the-dno-lifecycle)
    - [Phase 1: DNA Configuration](#1-dna-configuration-dnoconfig)
    - [Phase 2: Infancy (Scratch Training)](#2-infancy-scratch-training)
    - [Phase 3: Adulthood (Adaptive Growth)](#3-adulthood-adaptive-growth)
    - [Phase 4: Serialization (Save/Load)](#4-fluid-serialization)
5. [Advanced Mechanics](#advanced-mechanics)
    - [Surgical Training Control](#surgical-training-control-v027)
    - [Robust Persistence (Zombie Repair)](#robust-persistence-zombie-repair-v027)
6. [API Reference](#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

```bash
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.

```python
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.

```python
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**.

```python
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.

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

# Load it back
new_network = DynamicNetwork.load_dno(
    "my_organism.dno", 
    module_factory=lambda t: nn.Linear(...) # Factory to reconstruct base layers
)
```

---

## 🔧 Advanced Mechanics

### Surgical Training Control (v0.2.7)
Use the `GrowthEngine` to manually direct evolution.

```python
# 1. Force a new layer to grow from the seed
growth_engine.inject_layer(parent_tag="seed_cortex", new_tag="expert_math_v1")

# 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.

```python
# 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.


