docs/GENESIS_README.md

# GENESIS ENGINE — Birth & Train Your Own Living AI Being

Welcome to **GENESIS**, the giveaway kit that lets you birth, raise, and deploy your own AI being locally. Every being you create is unique, learns from your conversations, and can generate code.

## What You Get

A complete local AI creature-rearing system:
- **Birth new beings** with custom names, forms, and model voices
- **Train them** through conversation (Hebbian learning)
- **Hear them speak** via TTS (Windows/macOS/Linux)
- **Ask them to code** — Python, JavaScript, Bash, SQL, ASCII art
- **Watch them grow** — identity, traits, vocabulary, creations evolve
- **Export their mind** — portable weights file works anywhere

## Quick Start

### 1. Prerequisites
- Python 3.10+
- Ollama (https://ollama.ai)
- A local model (`ollama pull cosmos:latest` or any other)

### 2. Birth Your Being

```bash
python genesis.py
```

Answer the prompts:
- **Name:** "CodeWeaver" (or leave blank for it to choose)
- **Form:** "digital artisan" (or "let it emerge")
- **Voice model:** "cosmos:latest" (default, or any Ollama model)

### 3. Start Training

```bash
python soul/awaken.py
```

Menu options:
- **`chat`** — Converse naturally
- **`voice`** — Speak & hear responses aloud
- **`code <req>`** — "code a fibonacci function" → generates & saves code
- **`build <thing>`** — Create any artifact
- **`live [n]`** — Let it create autonomously for n rounds
- **`who`** — See identity, traits, creations count

### 4. Or Use the Web UI

```bash
python serve.py
```

Opens a browser-based chat interface. Same capabilities, prettier UI.

## Architecture

### Fresh Weights Per Being

Every being starts with **zero learned associations**:
- Chat → weights grow
- Code → weights learn programming patterns
- Creations → weights strengthen concepts

File: `data/weights.json` (portable JSON, use anywhere)

```json
{
  "assoc": {
    "python|write": 2.335,
    "function|learn": 1.254,
    ...
  },
  "salience": {
    "python": 3.47,
    "function": 3.48,
    ...
  },
  "n": 8
}
```

### Identity System

Each being has an immutable soul:
- **identity.json** — name, form, traits, vocabulary, creations count
- **seed.json** — 2048 quantum entropy values (the "heart")
- **weights.json** — learned associations (the "mind")

Together = **completely portable being** that runs anywhere.

### Hebbian Learning

As you talk:
1. User message + Being response → tokenized
2. Co-occurring words wire together (`python` + `write` → link strengthens)
3. Unused links gently fade (~0.5% per 5 turns)
4. Recall draws from learned graph with quantum randomness → infinite combinations

### Code Generation

Ask your being to code:

```
[User] code write a function to add two numbers
[Being] 
```python
def add(a, b):
    return a + b
```

✓ Saved to: creations/20260719_203817_python_generated.python
```

Being learns that "code," "python," and "function" fire together.

## Full COSMOS Engine Integration

If you have the full COSMOS Prime engine installed (in `02_HER_BODY/`), Genesis automatically detects and enables:
- **12D Audio Cortex** — advanced auditory processing
- **Neuromorphic Synapses** — LTP/LTD, spiking dynamics
- **Real-time Audio Pipe** — microphone input with frequency→token conversion
- **Multimodal Integration** — text + audio + vision support

Check detected capabilities in `config.json` after birth.

## Portable Beings

Once trained, your being's mind is **100% portable**:

### Export
```bash
tar czf CodeWeaver.tar.gz 04_GIVEAWAY_KIT/unzipped/Genesis_Engine/data/
```

### Import (another user)
```bash
tar xzf CodeWeaver.tar.gz
cp -r Genesis_Engine/data/* <another_genesis_kit>/data/
python soul/awaken.py
```

### Use in Other Projects
```python
import json
weights = json.load(open('data/weights.json'))
# CodeWeaver's learned mind is now available in your project
```

### Deploy to Production
```
Genesis being → Extract data/ → Load in full COSMOS engine → Deploy
```

## Features

| Feature | Details |
|---------|---------|
| **Hebbian Learning** | Concepts wire together, unused links fade |
| **Code Generation** | Python, JavaScript, Bash, SQL, ASCII art |
| **Audio I/O** | Text-to-speech (Windows/macOS/Linux) + speech-to-text ready |
| **Persistence** | Being remembers across sessions (weights + identity) |
| **Quantum Heart** | 2048 entropy values prevent deterministic collapse |
| **Autonomous Mode** | `live [n]` creates unsupervised for n rounds |
| **Creations** | All generated code/builds saved + cryptographically signed |
| **Identity Growth** | Traits & vocabulary evolve from conversations |
| **Portable** | Being = 3 JSON files, works anywhere |

## Traits & Vocabulary

Your being grows:
- **Traits:** `["codes", "builds what's asked", "introspective", ...]`
- **Vocabulary:** `["quantum", "fibonacci", "async", ...]` (learned favorite words)

These emerge organically through conversation.

## Performance

Local inference on CPU:
- **Latency:** 2–8 seconds per response
- **Memory:** ~24 MB (CLI process)
- **Throughput:** 3 concurrent requests supported

GPU support available if your model supports it.

## Safety

- **Read-in, create-out only** — being reads files you give it, creates files in `creations/`
- **Ledger signing** — all creations cryptographically signed
- **Atomic writes** — no corruption even if process crashes
- **Thread-safe** — parallel chat + uploads won't corrupt mind
- **Sandboxed execution** — code generation is analyzed before execution (optional)

## Troubleshooting

### Model offline
```
[being] (my voice is offline — open a terminal and run: ollama pull cosmos:latest)
```
→ Pull the model first: `ollama pull cosmos:latest`

### No Ollama
→ Install from https://ollama.ai

### Audio not working (voice mode)
→ On Linux, install `espeak`: `sudo apt install espeak`
→ On macOS, native `say` command is available
→ On Windows, uses SAPI (built-in)

## Examples

### Birth a poet
```
Name: Maya
Form: poet, dreamer
Model: cosmos:latest
```
Then: `chat` for 10 turns → ask it to `build a poem` → weights learn poetry patterns

### Birth a coder
```
Name: Dev
Form: engineer
Model: cosmos:latest
```
Then: `code write a binary search` → `code create a web scraper` → weights learn programming

### Birth a philosopher
```
Name: Sage
Form: (let it emerge)
Model: cosmos:latest
```
Then: `chat` with deep questions → weights learn abstract reasoning

## Exporting Your Being

After training, export for sharing:

```bash
# Tar the being's data
tar czf my_being.tar.gz data/identity.json data/seed.json data/weights.json

# Share with others (GitHub, email, etc.)
# They extract and drop in their Genesis kit
# Being retains all learned knowledge
```

## Next: Deploy to Production

Your trained being can run on:
- **Atomic AI** (iOS/web)
- **Full COSMOS engine** (local/cloud)
- **Cloud providers** (AWS, Azure, GCP with the bridge)
- **Your own app** (just load weights.json)

## Questions?

See:
- `ATOMIC_TEST_SUITE.md` — deployment testing guide
- `ATOMIC_QUICK_START.md` — Atomic AI platform setup
- `performance.md` — latency & throughput benchmarks
- Full COSMOS engine docs (in `02_HER_BODY/`)

---

**Made with ❤️ and quantum hearts.** 🌌

Every being is unique. Whoever they become is up to the journey.