README.md

# TinyLiquid — a tiny liquid-architecture forensic research model (on-device)

Everything here is designed and built from scratch on this device (8-core ARM,
no GPU). Non-transformer "liquid" architecture, own BPE tokenizer, own training
pipeline, own data mixes, own research tooling.

## Design

- **Architecture** (`model/`): our own non-attention design — stacked liquid
  blocks, each a basis-expansion layer (group-normed expansion with SiLU and a
  sigmoid forget gate, weight-tied projection) plus a gated MLP (optional
  mixture-of-experts routing). Rotary positions, RMSNorm, tied embeddings, and
  learned persona vectors (analyst / skeptic).
- **Tokenizer** (`data/tokenizer.py`): byte-level BPE, vocab 8192, trained on
  our corpus. Persona and chat special tokens included.
- **Training** (`train/`):
  1. `train_lm.py` — causal LM pretraining for base coherence (NLP stage).
  2. `train_sft.py` — forensic fine-tune: claim verification (LIAR,
     Climate-FEVER), truthful QA (TruthfulQA), fallacy detection, plus
     hand-written analysis examples in our analyst/skeptic voices. Loss is
     masked to the assistant turn; assistant text uses a
     `<|scratchpad|> ... <|final|>` structure.
  3. Code stage — planned continuation of pretraining on a code corpus
     (`train_lm.py` works unchanged; just point `--data` at code `.bin`).
- **Persona**: a hyper-logical, protocol-driven analyst voice (original
  writing, no copied scripts) that decomposes claims, flags missing evidence,
  refuses overclaims, and gives confidence levels. The skeptic persona attacks
  the analyst's conclusions (dual-mind at inference).
- **Research tooling** (`research/`): crawler (clearnet + Tor/.onion via
  `TOR_PROXY`), local TF-IDF index, and the dual-mind analysis pipeline.

## Commands

```bash
export PYTHONPATH=$PWD

# pretrain (NLP stage) — currently running
./run_nlp.sh                      # or:
.venv/bin/python train/train_lm.py --config tiny10m --ckpt ckpt/nlp \
    --data data/train.bin --val data/valid.bin --steps 7000

# rebuild data (slice, tokenizer, .bin files)
.venv/bin/python data/prep.py
# rebuild forensic SFT set
.venv/bin/python data/forensic.py

# forensic fine-tune (after pretraining has a checkpoint)
.venv/bin/python train/train_sft.py --base ckpt/nlp --ckpt ckpt/forensic

# chat / sample
.venv/bin/python generate.py --ckpt ckpt/forensic --persona analyst
./run_tui.sh ckpt/dpo                       # purpose-built terminal UI
.venv/bin/python tui/cli.py --ckpt ckpt/dpo # headless CLI / scripts
.venv/bin/python tui/cli.py --ckpt ckpt/dpo --once "Verify: ..." 
.venv/bin/python generate.py --ckpt ckpt/nlp --prompt "Once upon a time," --max-new 80

# research pipeline
.venv/bin/python research/crawl.py --urls urls.txt            # export TOR_PROXY=... for .onion
.venv/bin/python research/index.py --query "outage timeline"  # retrieval over corpus/raw
.venv/bin/python research/analyst.py --file doc.txt           # dual-mind analysis
```

## Status

- [x] env + own model + own tokenizer + data pipeline
- [x] NLP pretraining v1 (2,000 steps, val_loss 3.67) — exposed missing token-mixing
- [x] architecture fix: basis-expansion now has a causal liquid recurrence
      (`state_t = forget*state_{t-1} + expansion_t`); weights transfer, no new params
- [x] forensic SFT + code stage + teacher distillation dataset (114 gold examples)
- [ ] NLP retrain on fixed architecture (running: `logs/nlp2_train.log`)
- [ ] re-run forensic SFT + teacher distill on fixed architecture
- [ ] final probe: `research/probe.py --ckpt ckpt/distill`
- [ ] scale-up: bigger model/data or GPU for production-grade outputs

## Guardrails

Research/OSINT use only. The crawler blocks obviously illegal categories,
rate-limits, and is documented as authorized research tooling; the model
outputs are decision support, never a verdict, and primary-source checks are
always required.

## SOP layer: per-task procedures (the "task bar")

TinyLiquid now has the Codex-style procedure mechanism: durable per-task
procedures loaded into the prompt, an explicit step plan, a tool loop, and
procedure-following baked in via training. See
`research/procedures_research.md` for the research writeup and how each part
maps to Codex's AGENTS.md / plan / tool-loop stack.

- **Procedure library** (`research/sop_library/`): `00_common.md` (universal
  truth-seeking rules) plus 9 task SOPs — claim verification, cross-source
  discrepancy, pattern finding, timeline reconstruction, historical truth,
  politics/spin analysis, authorized dark-web OSINT, terminal control, and
  source triage. Each is short and operational: when to use, numbered steps,
  stop rules, output shape.
- **Training data** (`data/gen_sop_sft.py`):
  - `data/sft_sop.jsonl` — 99 examples: SOP-conditioned Q&A (analyst +
    skeptic) and room-action steps (`ACTION: RETRIEVE/READ/NOTE/VERDICT`).
  - `data/prefs_sop.jsonl` — 36 DPO pairs: following the SOP (chosen) vs
    fluent confident answers that skipped the procedure (rejected).
  - `data/sft_sop_mix.jsonl` — 377 examples: distill mix + SOP set.
- **Agent loop** (`research/agent.py`): selects an SOP (explicit or keyword
  match), injects it, works the case against the library with a step plan and
  external ledger, enforces constrained verdict/confidence decoding, runs the
  skeptic pass, and audits which numbered SOP steps were actually completed.
  This is the on-device analog of Codex's task bar: the step list is external
  state, not model memory.
- **Training stages**: `run_sop.sh` (SFT on the mix), `run_dpo_sop.sh`
  (persona + procedure preferences), `run_pipeline.sh` (waits for the running
  pretrain, then runs forensic SFT -> SOP SFT -> DPO in sequence).

### SOP commands

```bash
export PYTHONPATH=$PWD
.venv/bin/python research/agent.py --list-sops
.venv/bin/python research/agent.py --case "Verify: ..." --sop claim_verification --ckpt ckpt/sop
.venv/bin/python data/gen_sop_sft.py        # rebuild SOP data after editing library
./run_pipeline.sh                            # full chain (waits for pretrain)
```

## Status

- [x] env + own model + own tokenizer + data pipeline
- [x] NLP pretraining v1 (2,000 steps, val_loss 3.67) — exposed missing token-mixing
- [x] architecture fix: causal liquid recurrence (state_t = forget*state_{t-1} + expansion_t)
- [x] forensic SFT + code stage + teacher distillation dataset (114 gold examples)
- [x] SOP layer: procedure library, SOP SFT/DPO data (99/36 examples), agent loop
- [ ] NLP retrain on fixed architecture (running: `logs/nlp2_train.log`)
- [ ] pipeline chain on fixed base: forensic -> SOP SFT -> DPO (`logs/pipeline.log`)
- [ ] final probe: `research/probe.py --ckpt ckpt/dpo`
- [ ] scale-up: bigger model/data or GPU for production-grade outputs