Build it. Train it. Talk to it. Retrain it. Understand it.

Home • Step-by-Step • First Lesson • Teacher Guide • Student Worksheet • Architecture • How LLMs Work

Kairo is a classroom-ready mini LLM lab for making AI behavior visible. Learners train a tiny transformer, compare outputs before and after changing the training data, and inspect token probabilities and attention so LLMs feel understandable rather than magical.

Repository: whiteyoh/my-llm

Kairo helps learners understand how language models learn from text by making the hidden steps visible and discussable. Students can inspect tokenization, next-token prediction, loss trends, retraining effects, probability distributions, and attention patterns.

It is designed for classrooms, STEM clubs, workshops, and self-learning where people need a clear, hands-on model of how LLM behavior changes with data.

• Normal story-style output before retraining.
• A changed style after pirate retraining with different vocabulary and rhythm.
• A realistic reminder that tiny models may repeat themselves or produce strange text, which is useful for learning.

• Teachers running AI literacy lessons
• Middle/high school students learning ML basics
• Clubs and workshops wanting hands-on LLM demos
• Developers who want a tiny transparent transformer example

• Train a small byte-level GPT model on local text.
• Generate text from saved checkpoints.
• Compare the same prompt across different datasets.
• Evaluate loss and perplexity on a dataset.
• Use Learn Mode to inspect tokens, probabilities, attention, and retrain effects.
• Print classroom-ready teacher and student materials.

Many AI tools hide how models behave. Kairo surfaces the mechanism so students can observe, test, and discuss model behavior with evidence.

Train on normal stories, then retrain on pirate text and watch style shift immediately.

Same model architecture. Different data. Different behavior.

1. Normal stories: train on a neutral dataset (for example space_adventure.txt).
2. Compare: generate from a fixed prompt and record the output.
3. Pirate style: retrain on pirate_dialogue.txt and compare tone/word choices.
4. Questions: ask what changed and why, using output evidence.
5. Learn Mode: inspect token probabilities and attention maps.

python -m venv .venv
source .venv/bin/activate
pip install -e .

Optional extras:

pip install -e ".[learn]"
pip install -e ".[pdf]"
pip install -e ".[dev]"

Contributor setup (installs everything needed for checks, tests, and printables):

pip install -e ".[dev,learn,pdf]"

After pip install -e ., you can use either the kairo-* commands or the script paths shown in older examples.

Train:

kairo-train --input_file data/samples/space_adventure.txt --out_dir runs/demo --epochs 1 --batch_size 4 --seq_len 32 --d_model 64 --n_heads 4 --n_layers 2 --device cpu

Generate:

kairo-generate --checkpoint runs/demo/best.pt --prompt "The robot opened the door" --max_new_tokens 20 --device cpu

Evaluate:

kairo-evaluate --checkpoint runs/demo/best.pt --input_file data/samples/space_adventure.txt --device cpu

Chat:

kairo-chat --checkpoint runs/demo/best.pt --device cpu

Build a QA training corpus from JSONL records:

kairo-build-qa-corpus --input_jsonl qa_space_facts.jsonl --output_file runs/qa_space_facts.txt

The QA sample JSONL is included in both data/samples/ (repo use) and src/tiny_llm/samples/ (packaged installs). You can pass either a full path or just the bundled sample name.

Train and ask QA with context:

kairo-train --input_file runs/qa_space_facts.txt --out_dir runs/qa_demo --epochs 1 --batch_size 4 --seq_len 32 --d_model 64 --n_heads 4 --n_layers 2 --device cpu
kairo-qa --checkpoint runs/qa_demo/best.pt --question "Who pilots the Aurora?" --context "Captain Rowan is the pilot of the starship Aurora."

kairo-qa now includes a classroom-safe grounding fallback: if the generated answer looks low-quality and a context is supplied, it returns the best matching context sentence instead of random token noise.

Learn Mode (after installing the learn extra):

kairo-learn

Agent operations dashboard (after installing the learn extra):

kairo-agents-dashboard

The dashboard reads agent definitions from .Codex/agents/ and Codex/agents/, shows live status by agent, and stores session state in runs/agent_dashboard/state.json.

Regenerate classroom PDFs:

python tools/pdf/generate_printables.py
python tools/pdf/generate_tech_i_can_book.py

Use python tools/pdf/generate_printables.py letter for US Letter output.

Run quality checks:

ruff check .
python -m compileall src tests tools
pytest -q

For local parity with CI, install .[dev,learn,pdf] first. Without the pdf extra, the book-generation tests are skipped by design.

• Step-by-Step Guide
• First Lesson Walkthrough
• Teacher Guide
• Student Worksheet
• Architecture
• How LLMs Work
• Sample Training Text Guide
• Code Snippet Style Guide

• Teacher Guide (PDF)
• Student Worksheet (PDF)
• First Lesson Walkthrough (PDF)
• Tech I Can: Kairo Book (PDF)

• Kairo logo
• Simple architecture flowchart
• Learn Mode token preview
• Learn Mode attention map
• Learn Mode probability table
• Learn Mode retrain compare

Kairo is a local learning tool, not a production chatbot. It includes lightweight classroom safety checks, but teachers should still supervise prompts, training data, and generated outputs. The model can repeat, drift, or sound confident while being wrong; those limitations are part of the lesson.

Home • Step-by-Step • First Lesson • Teacher Guide • Student Worksheet • Architecture • How LLMs Work