Metadata-Version: 2.4
Name: learning-brain
Version: 3.0.0
Summary: Self-learning brain with neurogenesis and AI dopamine
Author-email: Learning Brain Team <team@learningbrain.dev>
License-Expression: MIT
Project-URL: Homepage, https://github.com/learningbrain/learning-brain
Project-URL: Issues, https://github.com/learningbrain/learning-brain/issues
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20.0

# 🧠 Learning Brain

> A self-learning neural network that grows new neurons! Like GGUF, but dynamic.

**Learning Brain** is a Python package that provides neurogenesis and continuous learning for AI models. It's like GGUF, but instead of being static, it grows new neurons when it learns!

This package includes the **SELSC Engine v2** - the same engine used in the HuggingFace model:
https://huggingface.co/Specialgfhdhdh/learning-qwen

## ✨ Features

- 🧬 **Neurogenesis** - Automatically grows new neurons when confused
- 🧠 **STDP Learning** - Spike-Timing-Dependent Plasticity for realistic neural learning
- 💊 **Dopamine System** - Reward-modulated learning rate
- 💾 **Persistent State** - Save/load learned brain states to `.brain` files
- 🔄 **Model Agnostic** - Works with any base model (Qwen, Llama, etc.)
- 📦 **pip Installable** - Easy to install and use

## 🧬 SELSC Engine v2

The package includes the **SELSC Engine v2** - the evolved brain from your HuggingFace model!

Features:
- Neurogenesis (grows new neurons when error > threshold)
- Dopamine-modulated STDP learning
- Surprise detection for adaptive learning
- Same architecture as https://huggingface.co/Specialgfhdhdh/learning-qwen

## 🚀 Installation

```bash
# From PyPI (when published)
pip install learning-brain

# From source
pip install .
```

## 📖 Usage

### Python API

```python
from learning_brain import Brain

# Create a new learning brain for a model
brain = Brain("qwen")

# Teach it something
result = brain.learn("The sky is blue and the grass is green")
print(result)
# {'tokens': 9, 'active_neurons': 100, 'neuron_grown': False, 'interactions': 1}

# Save the learned brain
brain.save()

# Check brain info
print(brain.info)
# {'model': 'qwen', 'path': 'qwen.brain', 'active_neurons': 100, ...}

# Later, load the brain
brain = Brain.load("qwen.brain")
```

### CLI

```bash
# Run interactive session
python -m learning_brain run qwen

# Create a new brain
python -m learning_brain create mymodel

# Run demo
python -m learning_brain demo
```

### Interactive Session

```bash
$ python -m learning_brain run qwen
==================================================
🧠 Learning Brain - qwen
==================================================
Info: {'model': 'qwen', 'path': 'qwen.brain', 'active_neurons': 100, ...}

Commands:
  save - Save and exit
  info - Show brain info
  quit - Exit without saving
--------------------------------------------------

> teach me about artificial intelligence
  Learned: 4 tokens
  Active neurons: 100

> machine learning is fascinating
  Learned: 4 tokens
  Active neurons: 100
  🧬 NEW NEURON GROWN!

> save
💾 Brain saved: qwen.brain
Goodbye!
```

## 🧬 How It Works

### Neurogenesis

The brain automatically grows new neurons when it encounters high error (confusion). This is similar to how real brains work - when a neuron is "confused" (high error), the brain activates a dormant neuron to help process the new information.

### STDP Learning

Spike-Timing-Dependent Plasticity (STDP) is a learning rule where:
- If neuron A fires *before* neuron B → connection A→B strengthens (Long-Term Potentiation)
- If neuron A fires *after* neuron B → connection A→B weakens (Long-Term Depression)

This creates realistic, Hebbian-style learning.

### File Format

The `.brain` file contains:
- Neural network weights
- Active neuron mask
- Vocabulary
- Learning history
- Cumulative error traces

This is like GGUF but supports runtime learning and neurogenesis!

## ⚙️ Configuration

```python
brain = Brain(
    model_name="qwen",
    vocab_size=10000,       # Max vocabulary size
    max_neurons=10000,      # Max neurons
    initial_neurons=100,    # Starting neurons
    lr_stdp=0.001,          # Learning rate
    tau_stdp=20.0,          # STDP time constant
    error_threshold=0.8,    # Error threshold for neurogenesis
)
```

## 📁 Project Structure

```
learning_brain_pkg/
├── learning_brain/
│   ├── __init__.py     # Main package (EvolvedChat, Brain, SELSC_Engine)
│   └── selsc_engine.py # SELSC Engine v2
├── setup.py           # pip setup script
├── README.md          # This file
└── LICENSE            # MIT License
```

## 💾 .neuro File Format

The `.neuro` file contains both the Qwen model weights AND the SELSC brain:

```python
from learning_brain import EvolvedChat

# Create and chat
chat = EvolvedChat(model="Qwen/Qwen2.5-0.5B-Instruct", brain_path="mybrain.brain")
chat.chat("Hello!")

# Save EVERYTHING to .neuro file
chat.save("my_ai.neuro")  # Includes Qwen + SELSC brain!

# Later, load and chat immediately
chat = EvolvedChat.load_neuro("my_ai.neuro")
chat.chat("What did I teach you?")
```

## 🤝 Contributing

Contributions welcome! Please open an issue or PR.

## 📝 License

MIT License - feel free to use!

---

Made with 🧬 by the Learning Brain Team
