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

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

• env + own model + own tokenizer + data pipeline
• NLP pretraining v1 (2,000 steps, val_loss 3.67) — exposed missing token-mixing
• architecture fix: basis-expansion now has a causal liquid recurrence (state_t = forget*state_{t-1} + expansion_t); weights transfer, no new params
• 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

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

• env + own model + own tokenizer + data pipeline
• NLP pretraining v1 (2,000 steps, val_loss 3.67) — exposed missing token-mixing
• architecture fix: causal liquid recurrence (state_t = forget*state_{t-1} + expansion_t)
• forensic SFT + code stage + teacher distillation dataset (114 gold examples)
• 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