# Ouroboros Model Architecture Test Checklist

## Supported ModelTypes (from brain.py)

| ModelType | Interface | Test Method | Status |
|-----------|-----------|-------------|--------|
| `LLM` | `generate()` | Text completion/chat | ✅ |
| `EMBEDDING` | `encode()` | Semantic vectors | ✅ |
| `RL` | `act()` / `step()` | Action selection | ⬜ (needs SB3 loader) |
| `VISION` | `detect()` | Object detection | ⬜ |
| `PLANNER` | `plan()` | Trajectory generation | ⬜ |
| `SLAM` | `update()` + `get_pose()` | Localization | ⬜ |
| `CONTROL` | `control()` | Motor commands | ⬜ |
| `SENSOR` | `fuse()` | Sensor fusion | ⬜ |
| `COMMS` | `send()` / `recv()` | Message passing | ⬜ |
| `STATE_MACHINE` | `tick()` | FSM transitions | ⬜ |
| `INFINITY_EMBED` | infinity-emb async | High-throughput embed | ⬜ |
| `INFINITY_RERANK` | infinity-emb async | Document reranking | ✅ |
| `INFINITY_CLASSIFY` | infinity-emb async | Zero-shot classify | ⬜ |
| `INFINITY_CLIP` | infinity-emb async | Image embedding | ⬜ |
| `INFINITY_CLAP` | infinity-emb async | Audio embedding | ⬜ |
| `GENERIC` | callable fallback | Direct invocation | ✅ |

---

## Available Pre-Downloaded Models (D:\huggingface\hub)

### 🔤 Text Generation (LLM)
| Model | Size | Test Command |
|-------|------|--------------|
| `HuggingFaceTB/SmolLM2-1.7B-Instruct` | 1.7B | `plug_model("HuggingFaceTB/SmolLM2-1.7B-Instruct"); generate("Hello")` |
| `HuggingFaceTB/SmolLM2-135M-Instruct` | 135M | `plug_model("HuggingFaceTB/SmolLM2-135M-Instruct"); generate("Hello")` |
| `LiquidAI/LFM2.5-1.2B-Thinking` | 1.2B | Thinking/reasoning model |
| `Qwen/Qwen2.5-0.5B-Instruct` | 0.5B | `generate("Explain quantum computing")` |
| `Qwen/Qwen2.5-1.5B-Instruct` | 1.5B | `generate("Write a haiku")` |
| `TinyLlama/TinyLlama-1.1B-Chat-v1.0` | 1.1B | Chat completion |
| `google/flan-t5-small` | 77M | Seq2seq generation |
| `google/gemma-3-1b-it` | 1B | Instruction-tuned |
| `google/gemma-3-270m` | 270M | Small Gemma |
| `google/gemma-3-270m-it` | 270M | Instruction-tuned |
| `gpt2` / `openai-community/gpt2` | 124M | Causal LM baseline |
| `openai-community/gpt2-medium` | 355M | Medium GPT-2 |
| `ibm-granite/granite-4.0-micro` | micro | IBM Granite |
| `unsloth/granite-4.0-350m` | 350M | Unsloth optimized |
| `tiiuae/falcon-rw-1b` | 1B | Falcon base |
| `aloobun/falcon-1b-cot-t2` | 1B | Chain-of-thought |
| `microsoft/phi-2` | 2.7B | Phi-2 reasoning |
| `mistralai/Mistral-7B-Instruct-v0.3` | 7B | Mistral instruct |
| `meta-llama/Llama-3.2-1B` | 1B | Llama 3.2 |
| `sshleifer/tiny-gpt2` | tiny | Unit test model |

### 🧮 Embedding Models
| Model | Dims | Test Command |
|-------|------|--------------|
| `BAAI/bge-small-en-v1.5` | 384 | `plug_model("BAAI/bge-small-en-v1.5"); embed_text("test")` |
| `BAAI/bge-base-en-v1.5` | 768 | Larger BGE |
| `BAAI/bge-large-en-v1.5` | 1024 | Largest BGE |
| `sentence-transformers/all-MiniLM-L6-v2` | 384 | Fast SBERT |
| `sentence-transformers/all-MiniLM-L12-v2` | 384 | Deeper MiniLM |
| `sentence-transformers/all-mpnet-base-v2` | 768 | MPNet base |
| `sentence-transformers/distiluse-base-multilingual-cased` | 512 | Multilingual |
| `intfloat/e5-small-v2` | 384 | E5 small |
| `intfloat/e5-base-v2` | 768 | E5 base |
| `thenlper/gte-small` | 384 | GTE small |
| `thenlper/gte-large` | 1024 | GTE large |
| `TaylorAI/gte-tiny` | 384 | Tiny GTE |
| `nomic-ai/nomic-embed-text-v1.5` | 768 | Nomic embed |
| `jinaai/jina-embeddings-v2-small-en` | 512 | Jina v2 |
| `jinaai/jina-embeddings-v3` | 1024 | Jina v3 |
| `Snowflake/snowflake-arctic-embed-xs` | 384 | Arctic embed |
| `ibm-granite/granite-embedding-small-english-r2` | 384 | Granite embed |
| `google/embeddinggemma-300m` | varies | Gemma embed |
| `Qwen/Qwen3-Embedding-0.6B` | 1024 | Qwen embed |

### 🔁 Reranking Models
| Model | Test Command |
|-------|--------------|
| `BAAI/bge-reranker-base` | `rerank(query, documents)` |

### 🖼️ Vision-Language Models (VLM)
| Model | Size | Capabilities |
|-------|------|--------------|
| `Qwen/Qwen2-VL-2B-Instruct` | 2B | Vision + text |
| `Qwen/Qwen2.5-VL-3B-Instruct` | 3B | Improved VL |
| `Qwen/Qwen2.5-VL-7B-Instruct` | 7B | Large VL |
| `vikhyatk/moondream2` | 1.6B | Tiny VLM |
| `moondream/starmie-v1` | varies | Moondream variant |
| `h2oai/h2ovl-mississippi-800m` | 800M | H2O VL |
| `TIGER-Lab/VLM2Vec-Qwen2VL-2B` | 2B | VLM to vectors |
| `owl10/ReCogDrive-VLM-2B` | 2B | Driving VLM |

### 🎮 Reinforcement Learning (RL)
| Model | Environment | Test Command |
|-------|-------------|--------------|
| `sb3/ppo-CartPole-v1` | CartPole | `model.act(obs)` |
| `sb3/ppo-LunarLander-v2` | LunarLander | `model.act(obs)` |
| `sb3/ppo-Acrobot-v1` | Acrobot | `model.act(obs)` |
| `sb3/ppo-BreakoutNoFrameskip-v4` | Breakout | Atari |
| `sb3/ppo-PongNoFrameskip-v4` | Pong | Atari |
| `sb3/ppo-SpaceInvadersNoFrameskip-v4` | Space Invaders | Atari |
| `sb3/ppo-MsPacmanNoFrameskip-v4` | Ms. Pacman | Atari |
| `sb3/ppo-QbertNoFrameskip-v4` | Q*bert | Atari |
| `sb3/ppo-BeamRiderNoFrameskip-v4` | Beam Rider | Atari |
| `sb3/ppo-EnduroNoFrameskip-v4` | Enduro | Atari |
| `sb3/ppo-AsteroidsNoFrameskip-v4` | Asteroids | Atari |
| `sb3/ppo-RoadRunnerNoFrameskip-v4` | Road Runner | Atari |
| `sb3/ppo-SeaquestNoFrameskip-v4` | Seaquest | Atari |
| `sb3/ppo-MiniGrid-*` | MiniGrid | Grid world |
| `sb3/dqn-*` | Various | DQN variants |
| `sb3/qrdqn-*` | Various | QR-DQN variants |
| `qgallouedec/ppo-MiniGrid-FourRooms-v0` | MiniGrid | Four rooms |

### ♟️ Game AI
| Model | Game | Test |
|-------|------|------|
| `Maxlegrec/ChessBot` | Chess | `model.act(board_state)` |
| `notjing/chessai` | Chess | Chess AI |

### 💻 Code Models
| Model | Task | Test |
|-------|------|------|
| `Salesforce/codet5-small` | Code generation | `generate("def fibonacci")` |
| `microsoft/codebert-base` | Code understanding | Embeddings |

### 🎨 Image Generation
| Model | Type | Test |
|-------|------|------|
| `CompVis/stable-diffusion-v1-4` | Diffusion | `generate_image("a cat")` |

### 📄 Document Processing
| Model | Task | Test |
|-------|------|------|
| `ibm-granite/granite-docling-258M` | Document understanding | OCR/layout |

---

## Test Execution Plan

### Phase 1: Embedding Models (fastest, most reliable)
```python
# Test all embedding models
for model in ["BAAI/bge-small-en-v1.5", "sentence-transformers/all-MiniLM-L6-v2", ...]:
    plug_model(model)
    result = embed_text("The quick brown fox")
    assert len(result.embedding) > 0
```

### Phase 2: Text Generation (LLMs)
```python
# Test text generation
for model in ["HuggingFaceTB/SmolLM2-135M-Instruct", "Qwen/Qwen2.5-0.5B-Instruct", ...]:
    plug_model(model)
    result = generate("Hello, my name is", max_tokens=50)
    assert len(result.output) > 0
```

### Phase 3: Vision-Language Models
```python
# Test VLMs with image input
plug_model("vikhyatk/moondream2")
result = forward({"image": "path/to/image.jpg", "text": "What is in this image?"})
```

### Phase 4: RL Models
```python
# Test RL action selection
from huggingface_sb3 import load_from_hub
model = load_from_hub("sb3/ppo-CartPole-v1")
plug_model(model)
action = invoke_slot(0, obs, mode="forward")
```

### Phase 5: Reranking
```python
plug_model("BAAI/bge-reranker-base")
result = rerank("What is AI?", ["AI is...", "Machine learning...", "Deep learning..."])
```

### Phase 6: Image Generation
```python
plug_model("CompVis/stable-diffusion-v1-4")
result = generate_image("a beautiful sunset over mountains")
# Returns base64 image or file path
```

---

## Rerun Visualization Verification

| Path | What to Check | Status |
|------|---------------|--------|
| `mcp/tool` | Tool names appear | ⬜ |
| `mcp/duration_ms` | Latency timeseries | ⬜ |
| `inference/timing/*` | Per-stage latency | ⬜ |
| `inference/embedding` | Tensor view | ⬜ |
| `inference/dreamer/*` | Latent state norms | ⬜ |
| `inference/council/*` | Per-councilor confidence | ⬜ |
| `bag/size` | Item count | ⬜ |
| `bag/ops` | Stash/summon activity | ⬜ |
| `state/slots/activity` | Slot invocation bar chart | ⬜ |
| `evolution/fitness/*` | Fitness curves (if compiling) | ⬜ |

---

## Quick Start Commands

```bash
# Start MCP server (auto-inits Rerun)
python your_capsule.py --mcp

# Or in Python:
from your_capsule import run_mcp_server
run_mcp_server()
```

Then use MCP tools:
- `plug_model("BAAI/bge-small-en-v1.5")` - Plug embedding model
- `list_slots()` - See what's plugged
- `embed_text("test query")` - Generate embeddings
- `generate("Hello")` - Generate text
- `forward({"text": "test"})` - Full inference path

---

## Notes

- **Local models**: Set `HF_HOME=D:\huggingface` to use cached models
- **GPU**: Most models benefit from CUDA; check `torch.cuda.is_available()`
- **Memory**: 7B+ models need 16GB+ RAM or GPU offloading
- **infinity-emb**: For high-throughput, use `infinity_server` with async embedding