WFGY/README.md

# WFGY SDK · Self-Healing Variance Gate for Any LLM  
_Turn any model — even GPT-2 — into a variance-tamed, hallucination-resistant thinker in 5 minutes._

[![CI](https://github.com/onestardao/WFGY/actions/workflows/ci.yml/badge.svg)](https://github.com/onestardao/WFGY/actions/workflows/ci.yml)
[![Colab](https://img.shields.io/badge/Colab-Run-yellow?logo=google-colab)](https://colab.research.google.com/github/onestardao/WFGY/blob/main/README_demo.ipynb)
[![HF Space](https://img.shields.io/badge/Live Demo-HuggingFace-blue?logo=huggingface)](https://huggingface.co/spaces/onestardao/wfgy-demo)
[![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.15630970-blue)](https://doi.org/10.5281/zenodo.15630970)

> **Goal → 10 000 ★ before July 1**   Unlock **WFGY 2.0** for everyone.  
> Miss the mark? 2.0 goes pay-walled & sealed forever.

---

## 0 · One-Minute Install & Run (Colab / local)

```bash
git clone https://github.com/onestardao/WFGY.git
cd WFGY
pip install -e .
python examples/example_01_basic_run.py   # shows variance ↓ & KL ↑

Or click the Colab badge above – no setup, just press Run-All.

---

1 · Why WFGY?

Problem	Vanilla LLM	+ WFGY
Logit noise / spikes	high	↓ 40–90 %
Hallucination rate	frequent	rare
Multi-step reasoning fail	common	success ↑ 42 %
Stability (time-to-failure)	—	3.6 × longer

Benchmarks & full numbers: see paper and examples/.

---

2 · Quick API

import wfgy_sdk as w, numpy as np
from wfgy_sdk.evaluator import compare_logits, pretty_print

# dummy logits
raw = np.random.randn(32000)
G = np.random.randn(256); G /= np.linalg.norm(G)
I = G + np.random.normal(scale=0.05, size=256)

out = w.get_engine().run(I, G, raw)
pretty_print(compare_logits(raw, out))

CLI (one line):

wfgy "Explain quantum tunnelling to a 5-year-old"

---

3 · Live Demo

Play with a prompt in your browser: https://huggingface.co/spaces/onestardao/wfgy-demo Variance %, KL divergence & histogram appear instantly; share button posts your result to X/Twitter.

---

4 · Spec & Reproducibility

Asset	Location
ONNX graphs (+ SHA-256)	specs/onnx/
Public API markdown	specs/
Dockerfile (CPU slim)	/Dockerfile
Continuous Integration	GitHub Actions badge (top of page)
Issue templates (bug / red-team / feature)	.github/ISSUE_TEMPLATE/

Exact commit hash used in the camera-ready paper: a1b2c3d (Replace with the current short hash before submission.)

---

5 · The Secret Folder 👀

I_am_not_lizardman/ contains 8 + 1 “Challenge-Einstein” papers

• extra Easter eggs. Open at your own risk.

---

6 · Roadmap

Milestone	Status
CI, Colab badge, HF Space	✅ now
Telegram /wfgy bot	⏳ v1.1
Adaptive-gamma WFGY 2.0	🔒 unlocks at 10 000 ★

---

7 · Citation

PSBigBig. “WFGY 1.0: A Self-Healing Variance Gate for LLMs.” Zenodo (2025).
doi:10.5281/zenodo.15630970

---

Play WFGY for more than 5 minutes and you might never return to traditional AI. Stars fuel research—one click = one photon of semantic clarity. ⭐