Cheat sheets

Paper Writer, Critic and Iteration

Schedule experiments with UCB, iterate a draft with a five-score critic, and emit LaTeX, BibTeX and a manifest.

  • Concepts and terms
  • Tasks and commands
  • Annotated code
  • Diagrams
  • Defaults and numbers
  • Troubleshooting
  • Questions and tips

Source

End-to-end research demo#

dispatchResultUCB statspaper.triggerMiniPapermini_to_full_papermanifestclientSeedhypothesesalpha, beta,gammaprocessIterationSchedulerUCB pickerprocess3 parallelslotsasyncio tasksqueueResult busreward perbranchprocesspick_best_branchhighest meanrewardmodelCriticLoopfive scores perroundprocessPaperWritertex, bib,manifeststoreDemoReportstop_reasondispatchResultUCB statspaper.triggerMiniPapermini_to_full_papermanifestclientSeed hypothesesalpha, beta, gammaprocessIterationSchedulerUCB pickerprocess3 parallelslotsasyncio tasksqueueResult busreward per branchprocesspick_best_branchhighest meanrewardmodelCriticLoopfive scores perroundprocessPaperWritertex, bib, manifeststoreDemoReportstop_reason

Run the lessons#

CommandWhat it does
python3 code/main.py (54)Writes paper.tex, references.bib, manifest.json to a temp dir
python3 code/main.py (55)Prints the critic loop result and per-round trace
python3 code/main.py (56)Prints stop_reason, paper triggers and branch stats
python3 code/main.py (57)Prints best branch, critic status and paper sections

Calls in code#

TaskCode
Figures from experiment outputsfigs = read_experiment_manifest(experiments, out_dir)
Render LaTeX onlyrender_latex(paper)
Fill prose and write three filesmanifest = PaperWriter(prose=prose).write(paper, out_dir)
Pair critic and revisercritic, reviser = make_deterministic_critic_pair()
Iterate a draftCriticLoop(critic=critic, reviser=reviser, max_rounds=6, target_score=8.0)
Mock experimentsmake_deterministic_runner(base_rewards, noise=0.04, delay_ms=2.0, seed=seed)
Schedule and waitreport = await sched.run(seed)
Pick and promotepick_best_branch(sched_report), then mini_to_full_paper(critic_result.paper, branch)

Declare the paper skeleton#

paper = Paper(
title="<title>", authors=["Lab Bot"], abstract="<abstract>",
sections=[
Section(id="method", title="Method", cites=["jones2021"],
figure_refs=[figs[0].id]),label sec:method
],
figures=figs,label fig:<id>
bibliography=[
BibEntry(key="jones2021", entry_type="article",
fields={"title": "On loops", "author": "Jones", "year": "2021"}),
],
)
prose = MockProseGenerator(outlines={"method": "<outline>"})
writer = PaperWriter(prose=prose)gates run before any file

Questions#

Why a skeleton first?
Gates check figures, cites and sections before any prose.
What does the critic read?
manifest.json. It does not parse LaTeX.
Why UCB?
Greedy never explores. Uniform never exploits.
Why import, not copy?
The demo adjusts sys.path and composes the earlier lessons.

Run the UCB scheduler#

seed = [Hypothesis(id="h-a-1", branch="branch-a"),
Hypothesis(id="h-b-1", branch="branch-b")]
runner = make_deterministic_runner(
base_rewards={"branch-a": 0.85, "branch-b": 0.55},
seed=7, delay_ms=2.0,
)reward is base + N(0, noise)
sched = IterationScheduler(
runner=runner, slots=3, max_experiments=20,
paper_threshold=0.7, prune_floor=0.25, prune_after_runs=3,
expander=deterministic_expander,two follow-ups per high reward
)
report = asyncio.run(sched.run(seed))SchedulerReport
report.to_dict()stop_reason, paper_triggers

Critic round and stop rules#

1Criticscores clarity, novelty, evidence, methodologyand related_work from 0 to 10.2Criticemits one suggestion for each dimension below8.0.3Harnessall five at or above target_score stops withreason target.4Harnessmean gain at most plateau_epsilon for 2 roundsstops with plateau.5Reviserapplies each edit, for example expand-body oradd-method-section.6Harnessafter max_rounds the status is stopped withreason budget.7Ordertarget wins over plateau. Plateau wins overbudget.

Formulas and scores#

UCB1
mean reward + c times sqrt(ln(total_runs) / runs).
Untried branch
ucb_score returns float("inf"), so it runs first.
Prune
mean below prune_floor after prune_after_runs trials.
Paper trigger
branch mean at or above paper_threshold, once per branch.
Clarity
min(10.0, 3.0 + avg_body / 50.0).
Evidence
min(10.0, 2.0 + 2.0 * fig_refs + 1.5 * cites).
Novelty
9.0 for high, 6.0 for medium, 3.0 for low originality_tag.
Demo originality
high at reward 0.8 or more, medium at 0.6 or more.

Loop defaults#

SettingDefaultNote
max_rounds5Critic budget. Below 1 raises ValueError
target_score8.0Every dimension, not the mean
plateau_epsilon0.1For plateau_window 2 rounds
slots3Parallel asyncio tasks
max_experiments50max_seconds is 30.0
exploration_csqrt(2)UCB exploration weight
paper_threshold0.7Fires paper.trigger
prune_floor0.2After prune_after_runs 3 trials

Errors and fixes#

SymptomCauseFix
PaperValidationError: cites unknown bibliography keySection cite has no BibEntryAdd the entry to bibliography
PaperValidationError: references unknown figure idfigure_refs names a missing figureAdd the figure first
NoTriggerErrorNo branch reached paper_thresholdCheck branch rewards against the threshold
Five flat rounds, verdict budgetSuggestions never raise the scoreFix the critic, not the draft
Branch never scheduled againBranch is prunedCheck prune_floor and prune_after_runs
Trace event kind errorRunner task raisedRead the repr of the exception in the trace