HOWTO.md

# Codette Training Lab — HOWTO Guide
## For Jonathan (and Future Jonathan Who Forgot Everything)

---

## Quick Reference: What Goes Where

```

codette-training-lab/

├── adapters/                    # GGUF LoRA adapter files (~27MB each)

│   ├── newton-lora-f16.gguf     # Trained, working

│   ├── davinci-lora-f16.gguf    # Trained, working

│   └── (6 more after HF job)   # empathy, philosophy, quantum, etc.

│

├── bartowski/                   # Base GGUF model (Q4_K_M, ~4.6GB)

│   └── Meta-Llama-3.1-8B-Instruct-GGUF/

│       └── Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf

│

├── datasets/                    # Training data (8 JSONL files, ~20K examples total)

│   ├── newton_reasoning.jsonl   # 3000 examples

│   ├── davinci_reasoning.jsonl  # 2500 examples

│   └── (6 more...)

│

├── inference/                   # Everything for RUNNING Codette

│   ├── codette_orchestrator.py  # Main brain: routes queries to adapters

│   ├── adapter_router.py        # Keyword/LLM routing engine

│   ├── model_loader.py          # Transformers-based model loader (GPU path)

│   ├── codette_chat_ui.py       # Legacy tkinter chat UI (still works!)

│   ├── codette_server.py        # NEW: Web UI backend (FastAPI-free)

│   ├── codette_session.py       # NEW: Cocoon-backed session manager

│   └── static/                  # NEW: Web UI frontend

│       ├── index.html           # Single-page chat app

│       ├── style.css            # Dark theme + adapter colors

│       ├── app.js               # Chat logic + streaming

│       └── spiderweb.js         # Canvas visualization of agent network

│

├── reasoning_forge/             # RC+xi reasoning engine (v2.0)

│   ├── forge_engine.py          # Main forge: 3 modes (single, feedback, debate)

│   ├── epistemic_metrics.py     # Tension/coherence/coverage scoring

│   ├── quantum_spiderweb.py     # 5D belief graph + attractors + glyphs

│   ├── cocoon_sync.py           # Fernet-encrypted state sync protocol

│   ├── synthesis_engine.py      # Multi-perspective synthesis

│   └── critic_agent.py          # Meta-evaluation agent

│

├── training/                    # Everything for TRAINING adapters

│   ├── train_hf_job_v3.py       # HuggingFace cloud GPU training (A10G)

│   ├── train_cpu_lean.py        # Local CPU Pipeline 1 (~18GB RAM)

│   ├── train_cpu_offload.py     # Local CPU Pipeline 2 (~8-12GB RAM)

│   └── (other training scripts)

│

├── dataset_engine/              # Dataset generation from concepts

├── evaluation/                  # Eval scripts

├── research/                    # Papers, frameworks, experiments

├── configs/                     # YAML configs for adapters/pipeline

│

├── codette_chat.bat             # Double-click: launch tkinter chat UI

├── train_local.bat              # Launch local CPU training

└── codette_web.bat              # NEW: Double-click: launch web UI

```

---

## How To: Launch Codette (Chat)

### Option A: Web UI (Recommended)
```

Double-click: codette_web.bat

   OR

J:\python.exe J:\codette-training-lab\inference\codette_server.py

   THEN open: http://localhost:7860

```

### Option B: Legacy Tkinter UI
```

Double-click: codette_chat.bat

   OR

J:\python.exe J:\codette-training-lab\inference\codette_chat_ui.py

```

### Option C: Command Line
```

J:\python.exe J:\codette-training-lab\inference\codette_orchestrator.py

J:\python.exe J:\codette-training-lab\inference\codette_orchestrator.py --query "How does gravity work?"

J:\python.exe J:\codette-training-lab\inference\codette_orchestrator.py --adapter newton --query "F=ma"

```

---

## How To: Train Adapters

### Cloud (HuggingFace GPU — Fast, ~10-20 min per adapter)
1. Go to huggingface.co/jobs
2. Submit `training/train_hf_job_v3.py` as a UV job
3. Select `a10g-small` flavor, 8h timeout
4. Add secret: `HF_TOKEN=$HF_TOKEN`
5. Trained adapters auto-upload to `Raiff1982/codette-lora-adapters`

### Local CPU (Slow but free)
```

train_local.bat lean newton          # Pipeline 1: ~18GB RAM, ~30-90s/step

train_local.bat offload empathy      # Pipeline 2: ~8-12GB RAM, ~2-5min/step

train_local.bat lean --list          # Show available adapters

```

### After Training: Convert to GGUF
```

J:\python.exe J:\TheAI\llama.cpp\convert_lora_to_gguf.py ^

  --base J:\codette-training-lab\bartowski\Meta-Llama-3.1-8B-Instruct-GGUF\Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf ^

  --lora /path/to/trained/adapter ^

  --outfile J:\codette-training-lab\adapters\ADAPTERNAME-lora-f16.gguf

```

---

## How To: Add a New Adapter After Training

1. Convert HuggingFace adapter to GGUF (see above)
2. Place the `.gguf` file in `adapters/` folder
3. Edit `inference/codette_orchestrator.py`:
   - Uncomment the adapter in `ADAPTER_GGUF_MAP`
4. Restart Codette — the router auto-discovers available adapters

---

## The Cocoon System (How Codette Remembers)

The Cocoon is Codette's encrypted memory system:

- **QuantumSpiderweb**: A 5D graph where each reasoning agent is a node.
  Nodes have states (psi, tau, chi, phi, lambda) representing thought magnitude,
  temporal progression, processing speed, emotional valence, and semantic weight.

- **Attractors**: When agents' beliefs converge, they form attractor clusters.
  These represent stable consensus points in Codette's reasoning.

- **Glyphs**: Identity signatures formed from FFT-compressed tension history.
  They're like fingerprints of how Codette reasoned about a topic.

- **CocoonSync**: Encrypts the entire spiderweb state with Fernet (AES-128-CBC),
  signs it with HMAC-SHA256, and can sync between Codette instances.

- **Sessions**: Each conversation saves a cocoon package. When you come back,
  Codette loads the cocoon and remembers not just WHAT you discussed, but
  HOW she was thinking about it — which attractors had formed, which
  perspectives were in tension.

### Key Metrics
- **Phase Coherence (Gamma)**: 0-1, how aligned agent perspectives are. Target: >= 0.98
- **Epistemic Tension (xi)**: 0-1, productive disagreement between agents. Target: <= 0.05
- **Ethical Alignment (eta)**: 0-1, AEGIS ethical compliance. Target: >= 0.90
- **Tension Productivity**: Was disagreement resolved in synthesis? Higher = better.
- **Perspective Coverage**: Which of the 8 perspectives contributed? Shows as colored dots.

---

## Hardware Notes

### This Machine (HP OmniBook 7 Flip 16)
- CPU: Intel Core Ultra 7 256V (Lunar Lake)
- GPU: Intel Arc 140V (8GB) — XPU backend works but llama.cpp uses CPU
- RAM: 16.8 GB physical + 32 GB page file on C: = ~51 GB virtual
- Storage: C: NVMe 512GB, J: USB 4TB (Seagate), K: USB 2TB (WD)
- Python: J:\python.exe (3.10) with PYTHONPATH="J:/Lib/site-packages"
- Page file: C: drive ONLY (Windows cannot create page files on USB drives!)

### Minimum Requirements (Any User)
- 4GB RAM: Q2 GGUF, 1 adapter at a time, text metrics only
- 8GB RAM: Q4 GGUF, auto-routing, basic UI
- 16GB RAM: Full Codette with all features

### SYCL/XPU PATH Fix
Scripts auto-set this, but if you get DLL errors:
```

set PATH=J:\Lib\site-packages\Library\bin;%PATH%

```

---

## Git / Backup

### Repos
- GitHub: https://github.com/Raiff1982/codette-training-lab
- HuggingFace: https://huggingface.co/Raiff1982/codette-training-lab
- Adapters: https://huggingface.co/Raiff1982/codette-lora-adapters
- Datasets: https://huggingface.co/datasets/Raiff1982/codette-training-data

### Push to Both
```

cd J:\codette-training-lab

git add -A && git commit -m "your message"

git push origin master    # GitHub

git push hf master        # HuggingFace

```

### Important: .gitignore
Large files are excluded: `datasets/*.jsonl`, `*.png`, `*.jpg`, `*.gguf`
Datasets live on HuggingFace dataset repo, not in git.

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| `ModuleNotFoundError: No module named 'xxx'` | `J:\python.exe -m pip install xxx` |
| `c10_xpu.dll` not found | Set PATH (see SYCL/XPU section) |
| `total_mem` AttributeError | Use `total_memory` (PyTorch API change) |
| Page file won't create on J:/K: | USB drives can't have page files. Use C: |
| HF push rejected (large files) | Check .gitignore, scrub with filter-branch |
| Training OOM on CPU | Use Pipeline 2 (offload), reduce seq_len |

| Adapter not found | Check `adapters/` folder for .gguf files |

| Voice not working | Install: `pip install sounddevice SpeechRecognition` |



---



## Key Dependencies



```

# Core inference (already installed)

llama-cpp-python          # GGUF model loading

torch                     # For XPU/training only



# Training (cloud or local)

transformers>=4.45.0,<4.48.0

peft>=0.10.0,<0.14.0

trl==0.12.2               # Cloud only (not installed locally)



# Voice (optional)

sounddevice               # Microphone recording

SpeechRecognition         # Google STT API



# Web UI (zero extra deps — uses Python stdlib!)

# No FastAPI, no Flask, no npm, no node — pure Python http.server

```