one small package, operable by one person

what is in the gaige package?

how do you install gaige?

pip install gaige is the whole install for analysis: Python 3.10 and up, numpy and requests, nothing else. add "gaige[gpu]" when you need to score against real models. version 0.0.4 is on PyPI with its own verification receipts, and the source, history, and CI run in the open on GitHub.

what do you run first?

create a virtual environment, install the lane you need, then ask the machine before any run: gaige plan answers with measured memory floors and honest refusals, gaige corpora lists the built-in piles and the labeled-jsonl format, and gaige providers grades served-model attestation before a run wastes an evening.

$ python -m venv .venv && source .venv/bin/activate
$ pip install gaige             # core: analysis anywhere, no GPU needed
$ pip install "gaige[gpu]"      # scoring: torch + transformers<5 + bitsandbytes
$ pip install "gaige[verify]"   # provenance evidence: c2pa-python + PyWavelets + opencv

$ gaige plan                    # what can THIS machine honestly run, measured
$ gaige corpora                 # built-in corpora + the labeled-jsonl format
$ gaige providers               # served-model providers + attestation grades

gaige plan answers with measured memory floors and honest refusals: “NO — needs 8.0 GB free VRAM, have 7.9” is a feature, not an error. 4-bit quantization is CUDA-only; on CPU, use fp32 and expect the fingerprint to record a different instrument.

what does a gaige receipt contain?

$ gaige run --corpus hc3-mini --n 100 --seed 17 --detector fast-detect-gpt
→ reports/<timestamp>-fast-detect-gpt/
    report.md      the receipt, human-readable
    results.json   every statistic, wholesale
    scores.csv     per-document scores
    roc.json       the curve
    env.json       instrument fingerprint + the exact reproduce command
    run.json       run identity

$ gaige run --corpus your-labeled.jsonl      # rows: {"text": ..., "label": "human"|"ai"}
$ gaige analyze --report reports/<timestamp> # re-derive anywhere · no GPU · bit-identical
$ gaige export --report reports/<timestamp> --out site-data/  # public receipt JSON
$ gaige verify picture.png                   # provenance evidence sweep · statuses, never a score
$ gaige admit --baseline reports/<ts>-<detector>/ --candidate new.jsonl  # divergence from your accepted baseline

one run writes the whole receipt: a human-readable report, every statistic in JSON, per-document scores, the ROC curve, and the instrument fingerprint with its exact reproduce command. the headline is an AUROC with a bootstrap interval; thresholds come in two families kept apart by construction; refusals, subgroups, and the fingerprint carry the honesty. row by row:

the figures quoted above, with their measurement conditions:

what does gaige verify report?

evidence statuses, never a score: gaige verify sweeps a file for c2pa content credentials and watermarks and answers FOUND, ABSENT, INCONCLUSIVE, or NEEDS_KEYS per scheme. every negative is earned rather than assumed, every result states what it means, and the sweep records the verifier fingerprint. in detail:

gaige verify (since 0.0.3) sweeps a file for provenance evidence and emits statuses, never a score: c2pa content credentials, where absence is a typed signal: only a true “no manifest found” reads ABSENT, and a validation failure never does; the publicly checkable dwtdct image watermark behind a per-image carrier self-test, where a negative earns ABSENT only when a probe payload embedded into that same image survives a round trip, proving the carrier could have held the mark, and otherwise the answer is INCONCLUSIVE, because on an unfavourable carrier the decoder returns silence either way; and keyed text schemes reported honestly as NEEDS_KEYS. every result states what a negative from it means, and every sweep carries the verifier fingerprint, including which optional libraries were absent.

$ pip install "gaige[verify]"
$ gaige verify picture.png      # FOUND / ABSENT / INCONCLUSIVE / NEEDS_KEYS · never a verdict

what does gaige admit measure?

how far unlabeled candidate material diverges from an accepted baseline receipt, measured on the baseline’s own fingerprinted instrument. the headline is a two-sided conformal novelty rate with its exact false-alarm law printed; refusal floors, per-document placements, and stratified detail ride beside it. the receipt never says admit or reject: that stays your call. in full:

gaige admit (since 0.0.4) measures how far unlabeled candidate material diverges from an accepted baseline receipt, under the baseline’s own fingerprinted instrument. the headline number is a two-sided conformal novelty rate: the share of candidate documents outside the baseline’s acceptance band, beside what exchangeability would predict, with each side’s exact false-alarm law printed and a floor below which the guarantee is refused, not granted. ks distance and quantile shifts ride beside it with intervals, every document gets its own placement, strata are withheld under twenty documents, and the live lane refuses any instrument mismatch. supplied scores are accepted for the no-GPU lane and labeled unattested. the receipt never says admit or reject; the decision is yours.

$ gaige admit --baseline reports/<ts>-<detector>/ --candidate new-material.jsonl
$ gaige admit --baseline reports/<ts>-<detector>/ --candidate-scores scores.csv   # no-GPU lane · labeled unattested

commands

also in the box: gaige probe new and gaige probe lint: probe-set authoring with schema enforcement, manifest-gated so a probe run refuses material that violates the declared instrument decisions.

known edges

• transformers stays below 5. newer majors silently ignore the 4-bit config; gaige counts quantized modules at load and refuses a silent fp16 load rather than emit a receipt that lies about its instrument.
• 4-bit is CUDA-only. on CPU the honest option is fp32: the falcon-7b pair needs roughly 56 GB of RAM and real patience, and the fingerprint records it as the different instrument it is.
• CPU-only boxes: install torch from the CPU index first. pip install torch --index-url https://download.pytorch.org/whl/cpu, then the [gpu] extra; otherwise pip resolves the multi-gigabyte CUDA build you cannot use.
• memory floors refuse. loads check free VRAM/RAM against measured floors and name the numbers when they decline; co-resident work is protected on purpose.
• nothing transfers. thresholds, scores, and separation are properties of one instrument on one corpus. every receipt states what it was measured on, and no number is offered as universal.
• benchmark text stays outside. corpus adapters download benchmark rows when you prepare a slice and record exactly where each row came from. none of that text ships with gaige or gets redistributed.