st fact

st-fact — Fact-check stories in a container

Sends a single story to an AI and asks it to fact-check every claim, scoring each one true, partially true, or false. Appends the result to the container.

Run after: st-prep Run before: st-verdict st-fix st-heatmap st-cross

st-fact subject.json                    # fact-check story 1 with default AI
st-fact -s 2 --agent gemini subject.json  # fact-check story 2 with Gemini
st-fact --no-cache subject.json        # bypass API cache
st-fact --all subject.json             # fact-check all stories in the container
st-fact --agent all subject.json          # run all AIs in parallel (one per story)
st-fact --timeout 30 subject.json      # 30-second per-paragraph timeout
st-fact --file subject.json            # also write results to a file
st-fact --paragraph subject.json       # write paragraph segments to _paragraph_test_n.txt

Options

Option	Description
-s N, --story N	Fact-check a single story by number (default: 1)
--all	Fact-check every story in the container
--agent AI	AI provider to use, or all to run all providers in parallel (default: xai)
--cache	Enable the API response cache (default: enabled)
--no-cache	Bypass the API response cache
--file	Also write results to a .txt file alongside the container
--paragraph	Write paragraph segments to _paragraph_test_N.txt for debugging
--display	Write results to the display (default: on)
--silent	Suppress all output including progress bars; used internally by st-cross
-v, --verbose	Verbose output
-q, --quiet	Minimal output
--timeout N	With --agent all: per-job limit in minutes (default: 20). Single-AI mode: per-paragraph limit in seconds (default: 0 = no limit)
--retry-budget SECONDS	Total retry budget in seconds passed through to process_prompt() (default: 0 = unlimited). Useful for parallel st-cross --parallel runs where a single 105-second tail would stall the matrix. Per-call (per segment), independent of --timeout (per subprocess).

What happened to --ai-review / --ai-caption / --ai-summary / …?

These interpretive flags moved to st-verdict in cross-st 0.7.0. st-fact is now a pure verifier: it produces fact-check data; st-verdict interprets it. This is the GATHER → VERIFY → INTERPRET architecture.

Old (st-fact)	New (st-verdict)
st-fact --ai-review subject.json	st-verdict --what-is-false subject.json (or --what-is-true / --what-is-missing)
st-fact --ai-title subject.json	st-verdict --ai-title subject.json
st-fact --ai-short subject.json	st-verdict --ai-short subject.json
st-fact --ai-caption subject.json	st-verdict --ai-caption subject.json
st-fact --ai-summary subject.json	st-verdict --ai-summary subject.json
st-fact --ai-story subject.json	st-verdict --ai-story subject.json

If you call any of the removed flags, st-fact exits with a one-line error pointing at the right st-verdict invocation — no silent failure.

See also: Three Stages — the GATHER → VERIFY → INTERPRET architecture this migration is part of.

For developers

Splits the story into segments via mmd_util.build_segments(), sends them to the AI, and appends a fact[] entry to the container. The entry includes score, counts, summary, claims[] (per-segment verdicts), and timing{}.

The structured claims[] list is parsed from the AI's free-text reply via the shared cross_st/_report_signals.CLAIM_BLOCK_RE regex (also used by st-verdict and st-fix), so all three tools agree on what counts as a parseable claim. The pattern tolerates stray markdown markup (**, __) — anthropic in particular wraps every label in bold, which used to silently drop every anthropic claim from the structured list (counts and score were unaffected).