Niodoo Physics LLM

Inference-time activation steering for local LLM generation (physics-inspired forces on activations — no weight updates).

Lead: Jason Van Pham (Ruffian-L) — direction and final implementation. Built with: Grok · Claude / Claude Code · ChatGPT / Codex · Gemini. Built with Llama (Meta) — GGUF path in experiments.

Archive + experiment log of early physics-steering work.
Active research direction: niodoo-hidden-state-steering. Live residual harness: hydrodynamic-swarm.

Best face of this repo

Summary

• Model: bartowski GGUF Q4_K_M of Meta Llama 3.1 8B Instruct (main experiments).
• Mechanism: activation-space steering before sampling; selected layer band.
• Primary artifact: PARB multi-seed, blind judging — overall accuracy did not improve; selective trap-style wins only.
• Limits: non-deterministic effect; can hurt simple recall, latency, cleanliness.

Mechanism

Niodoo applies a small set of steering terms during generation:

The default command path uses GGUF model loading through Candle and exposes parameters such as --physics-blend, --repulsion-strength, --gravity-well, --physics-start-layer, and --physics-end-layer.

Benchmark Results

The strongest evidence in this repo is the multi-seed PARB run:

• Artifact: artifacts/parb_rigorous_clean.json
• Generated: 2025-12-19T01:45:05
• Judge: Grok blind grader
• Questions: 77
• Seeds: 5
• Total runs: 770, from 77 questions x 5 seeds x 2 systems

Question-level winner counts:

Interpretation:

• Niodoo was worse overall on this benchmark.
• Niodoo still changed the failure distribution, with selective wins on a subset of reasoning-trap prompts.
• The benchmark demonstrates that activation steering can sometimes move a model out of a local wrong trajectory.

An earlier single-seed review is also included:

• Artifact: artifacts/parb_comparison_review.json
• Questions: 72
• Baseline: 15.5 / 72, 21.5%
• Niodoo: 29.0 / 72, 40.3%

Treat the single-seed result as a historical experiment. The multi-seed blind-judged run above is the more robust result.

Representative Effects

Examples from the multi-seed artifact where Niodoo scored higher than baseline:

Examples where baseline scored higher:

The useful result is not deterministic correctness. It is observable behavior change: steering can induce exploration, but the same mechanism can also over-correct or introduce artifacts.

Reproducibility

Build:

git clone https://github.com/Ruffian-L/Niodoo-Physics-LLM.git
cd Niodoo-Physics-LLM
cargo build --release --bin niodoo

Run one prompt:

./target/release/niodoo \
  --model-path /path/to/model.gguf \
  --prompt "Your prompt" \
  --mode-orbital \
  --physics-blend 1.5 \
  --repulsion-strength=-0.5 \
  --gravity-well 0.2 \
  --max-steps 256 \
  --seed 42

Disable steering for a baseline-style run:

./target/release/niodoo \
  --model-path /path/to/model.gguf \
  --prompt "Your prompt" \
  --physics-blend 0.0 \
  --ghost-gravity 0.0 \
  --seed 42

Notes:

• The historical benchmark runner is scripts/parb_rigorous.py.
• Rerunning it requires a local model, Ollama, and an external judge API key.

Configuration (no code edits needed to run on another machine):

Example:

export NIODOO_MODEL=/path/to/Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf
export XAI_API_KEY=...            # only needed to re-judge
python3 scripts/parb_rigorous.py

Telemetry

Niodoo emits per-token debug and telemetry lines during generation. Example:

{"token":"Hi","step":0,"gravity_force":0.0,"repulsion_force":4.17,"total_force":4.17,"ramp_factor":0.167}

Common fields:

Limitations

• Results are sampling- and seed-dependent.
• Steering can lower accuracy on simple factual recall.
• High force settings can produce malformed text or leaked control tags.
• Latency is higher than baseline generation.
• Some benchmark artifacts use local paths and historical scripts.
• The current repo is a December 2025 prototype; later hidden-state transfer work is a separate stabilization direction.

Repository Layout

src/main.rs                  CLI entry point and generation loop
src/physics/                 Activation steering and physics modules
scripts/parb_rigorous.py     Historical multi-seed benchmark runner
artifacts/                   Primary benchmark outputs (PARB runs, telemetry, blind-test key)
archive/experiment-logs/     Raw historical tuning/stress-test logs, kept for transparency
server/niodoo_server.py      Experimental FastAPI wrapper
docs/TUNING.md               Historical tuning notes

What To Cite

To cite this project:

Niodoo is a local inference-time activation steering prototype. In the primary
multi-seed PARB artifact, it underperformed baseline Llama 3.1 8B overall
but produced selective wins on 15 of 77 question-level comparisons, showing that
activation steering can change reasoning trajectories without weight updates.

Credits and Thank Yous

This project builds directly on work by many others.

• Llama: Built with Llama 3.1 by Meta AI. The main experiments and model target use bartowski's GGUF quantization (Q4_K_M) of Meta Llama 3.1 8B Instruct. This work touches and steers activations from Llama-family models.
• bartowski: High-quality GGUF quantizations (including the Q4_K_M files used throughout all benchmarks and experiments) hosted at https://huggingface.co/bartowski.
• Unsloth: Fast and memory-efficient fine-tuning/optimization library used in the original work and tuning pipelines that led to this physics steering research (and prior Qwen experiments).
• Qwen (Alibaba): Prior original work that led to this project involved Qwen models.
• Hugging Face Candle (candle-core, candle-nn, candle-transformers) for GGUF model loading and CUDA inference of Llama (and related) architectures.
• GGUF format and quantized model support from the llama.cpp project and community.
• clap for the command-line interface.
• axum + tokio + futures for the experimental server and async runtime.
• Other crates: safetensors, half, friedrich (see Cargo.toml for full list).

AI Collaborators

Jason Van Pham leads this research program. This was not built alone. Collaborators (name everyone):

Thank you to the companies: Google, Anthropic, xAI, OpenAI, and Alibaba.

License

The Niodoo code and tooling in this repository is licensed under the Apache License, Version 2.0 — see LICENSE.

Llama 3.1 models (used when you provide weights such as Meta-Llama-3.1-8B-Instruct) are licensed under the Llama 3.1 Community License — see LICENSE-LLAMA and the required attribution in NOTICE.

Llama 3.1 is licensed under the Llama 3.1 Community License, Copyright © Meta Platforms, Inc. All Rights Reserved.

This project prominently displays "Built with Llama".

Prior related work also involved Qwen models from Alibaba Cloud (subject to their own licenses).

See NOTICE for full attribution details.