README.md

metadata

title: Beacon
emoji: 🕯️
colorFrom: yellow
colorTo: red
sdk: docker
app_port: 7860
pinned: false

Handoff: Astroparse — annotated astronomy paper reader

Overview

Astroparse turns an astronomy PDF into a cleanly typeset reading view with paragraph-level AI marginalia. The pipeline: PDF → text extraction (pymupdf4llm) → header/footer cleaning → paragraph segmentation → SPECTER2 embeddings + BM25 index → literature retrieval (Pathfinder / NASA ADS) → per-paragraph LLM commentary rendered as Tufte-style margin notes beside the text. Users pick a commentary mode per paragraph (historical context, referee critique, related-literature observations, plain-language explainer, methods comparison), inspect the retrieved papers behind each note (abstract, relevance scores, ADS/arXiv links), choose their LLM provider (Claude / OpenAI / Gemini) with their own API key, and save/reload the whole annotated state as a JSON session.

Primary user: a single researcher (the project owner), with intent to expand to a public web app if useful.

About the Design Files

The files in this bundle are design references created in HTML — a working prototype showing the intended look and behavior, not production code to copy directly. The task is to recreate this design in a real application environment. There is no existing codebase; the recommended stack (chosen to fit the Python-native pipeline) is:

• Frontend: React + Vite (the prototype's JSX components port almost directly; they currently run via in-browser Babel, which must not ship to production)
• Backend: Python + FastAPI (pymupdf4llm, SPECTER2, BM25, and Pathfinder/ADS access are all Python)
• Hosting: Hugging Face Spaces (Docker) for the first deployment; Fly.io/Render later if a custom domain is needed

Important: the prototype simulates parsing and retrieval (it ships one hard-coded paper, Mowla & Iyer 2024, and a curated 10-paper retrieval set in data.js). The pipeline screen plays a scripted animation. In production these become real backend calls — see "Backend pipeline specification" below. The LLM commentary generation in the prototype is REAL (it calls providers from the browser) and its prompt design should be kept.

Fidelity

High-fidelity. Colors, typography, spacing, and interactions are final design intent. Recreate the UI pixel-faithfully. The only placeholder behaviors are the simulated parsing/retrieval described above.

Design language (read first)

"Annotated encyclopedia / manuscript marginalia." A parchment folio on a darker desk; EB Garamond for all reading text; IBM Plex Mono for machine traces (pipeline logs, scores, file names, buttons); rubrication red for marks of structure (pilcrows, drop caps, rules, active states); five mode colors at matched oklch lightness/chroma. No rounded-corner cards, no gradients, no icons — typography does all the work. Buttons are underlined mono text, not pills.

Design tokens

Colors

Theme is driven by 3 CSS variables (user-switchable palettes via Tweaks):

Token	Default ("Parchment")	Alt 1 ("Ivory")	Alt 2 ("Chalk")
--paper (background)	#f6f1e6	#fbf8f1	#f3f2ee
--ink (text)	#2b2418	#231f17	#22241f
--rubric (accent)	#9a3b20	#8a5a18	#3f5a96

Desk (page surround): color-mix(in oklab, var(--paper) 86%, var(--ink) 14%). All secondary grays are mixes of ink into paper (e.g. 70% ink for secondary text, 50% for captions, 25% for hairline borders, 14% for rules, 8% for faint dividers) — never neutral hex grays, so every tint stays warm with the palette.

Mode colors (fixed, all oklch(0.52 C H)):

Mode	Color	Glyph
Historical context	oklch(0.52 0.10 70) amber	H
Referee mode	oklch(0.52 0.13 28) red	R
From the literature	oklch(0.52 0.10 250) blue	L
Plain-language	oklch(0.52 0.10 150) green	P
Methods comparison	oklch(0.52 0.10 310) violet	M

Typography

• EB Garamond (Google Fonts, 400/500/600 + italics): all reading text, headings, wordmark
• IBM Plex Mono (400/500): logs, scores, chips, text-buttons, hints, metadata
• Body: 19px default (user-adjustable 16–23px via Tweaks), line-height 1.58, justified + hyphens: auto (toggleable)
• Paper title: 31px / 600 / line-height 1.22, centered, text-wrap: balance
• Section headings: 13px / 500 / uppercase / letter-spacing 0.18em
• Margin notes: 13.5px / line-height 1.5; note mode label: 12.5px small-caps, letter-spacing 0.08em, weight 500, in mode color
• Mono UI text: 10–12px, letter-spacing 0.04–0.14em
• Wordmark "astroparse": uppercase, letter-spacing 0.28–0.32em, 12–14px, rubric color

Spacing & chrome

• Folio: max-width 1180px, centered, padding 64px 72px 48px, 1px border (ink 18%), shadow 0 1px 2px rgba(40,30,10,0.08), 0 18px 50px -24px rgba(40,30,10,0.4)
• Border radius: 0 everywhere except 2px on chips/inputs and 50% on mode dots
• Text column: flex 0 1 660px, 48px gap to margin column
• Margin column: flex 1 0 300px, max-width 330px, 1px left rule (ink 14%), notes inset 28px from the rule
• Paragraph spacing: 1.15em; note-to-note minimum gap: 26px

Screens / Views

1. Upload ("Place a manuscript here")

Centered column on the desk background: wordmark, then a folio drop-zone card (min(620px, 92vw); padding 58px 48px 44px) with a double border — 1px solid outer (ink 18%) plus 1px dashed inset outline (outline-offset: -10px, ink 30%; turns rubric on hover/drag, card scales 1.01 on drag-over). Contents, centered: a 58px rubric pilcrow ¶; "Place a manuscript here" (26px / 500); italic subline "drop an astronomy PDF, or click to browse" (16px, ink 70%); mono caption "parsed with pymupdf4llm · annotated against the literature via Pathfinder" (10.5px, ink 52%, 26px above-gap). Below the card: two mono text-buttons — "open ‹last/sample manuscript›" and "reload a saved session (.json)" — separated by "·". Bottom mono caption explains prototype limitations (drop in production). Behavior: click anywhere on card opens file picker (accept application/pdf); drag-and-drop accepted; choosing a .json via the second button restores a session directly.

2. Pipeline ("in preparation")

Same desk + wordmark. A folio card (min(600px, 92vw), padding 30px 38px 24px). Header row: italic filename (17px) left, "IN PREPARATION" mono uppercase rubric right; hairline rule below. Then six stages as a list, each separated by faint rules (ink 8%):

• Row: roman numeral (mono 11px, rubric, right-aligned 26px col) · stage name (17px / 500) · tool name (mono 10.5px, ink 50%, right) · status mark (✓ done / … active, rubric)
• Pending stages at 38% opacity; active stage name in rubric
• Under active/done stages: mono log lines (11px, ink 58%, indented 36px) appear one-by-one (~420ms apart, fade+2px rise 300ms)

Stages (names are part of the design voice): i. Reading manuscript (pymupdf4llm) · ii. Cleaning the leaves (header/footer removal) · iii. Ruling the columns (paragraph segmentation) · iv. Committing to memory (SPECTER2 embeddings) · v. Indexing the lexicon (BM25) · vi. Consulting the library (Pathfinder). Log lines report real counts from the backend in production. Footer: right-aligned "skip to the manuscript →" text-button. Auto-advance ~1.1s after the last stage. In production, drive stage transitions from real pipeline progress (SSE or polling).

3. Reader (the core screen)

Toolbar (sticky, backdrop-blur paper at 88% opacity, hairline bottom border, padding 13px 28px): wordmark · filename (mono 10.5px ink 50%) · spacer · text-buttons: "annotator: ‹provider›", "save session ↓", "load", "new manuscript".

Folio (margin 36px auto 70px): centered paper header — title, italic author line (16px ink 75%), mono metadata line "arXiv:2402.08696 · 20 pp · Nature 636, 332–338 (2024)" (10.5px ink 50%).

Mode legend: a centered row between hairline rules; five items (8px color dot + small-caps label, 13px, ink 70%, hover → mode color). Clicking a legend item sets every note to that mode (tooltip: "set every note to …").

Two-column body: text column + margin column (rule between). Notes can flip to the left side via Tweaks (flex-direction: row-reverse; rule flips side).

Text column:

• Section headings as specced above
• Paragraphs with a rubric pilcrow ¶ hanging in the left gutter (absolute, left: -1.5em, 0.85em, 55% opacity)
• First paragraph of each section gets a drop cap (::first-letter: float left, 3.05em, line-height 0.82, weight 500, rubric) when the Tweak is on
• Hovering a paragraph tints it AND its note with the note's mode color at 7% (color-mix(... 7%, transparent)), and vice versa — this cross-highlight is the key affordance linking the columns

Margin column — each paragraph has exactly one note, absolutely positioned:

• Alignment rule (critical): every note's top is pinned EXACTLY level with its paragraph's top. If a paragraph is shorter than its note, the text column adds extra space below that paragraph (extra margin-bottom in px) so the next paragraph/note pair is also level. Algorithm: measure natural paragraph tops (subtracting previously applied spacers), walk pairs in order, spacer[i] = max(0, noteTop[i] + noteHeight[i] + 26 − nextParagraphNaturalTop). Re-run on resize, font load, and any note content/mode change; must be idempotent (no oscillation). Disable spacers and absolute positioning below 900px viewport (notes become static blocks under their paragraphs).
• Note anatomy, top to bottom: 1.5px top rule in mode color; header row — small-caps mode label in mode color + "✦" marker if LLM-generated + "↻" regenerate button (hidden until note hover; ink 40% → rubric on hover); body text; citation chips; mode dots.
• Citation chips: mono 10px, [n] AuthorYY (rank number in mode color), 1px border (ink 22%), 2px radius, padding 2px 7px 2px 5px; hover → mode color border/text. Click opens the citation popover.
• Mode dots: five 19px circles, mono 9px glyph letters (H R L P M); inactive: 1px border ink 25%, text ink 50%; hover: mode color; active: filled with mode color, paper-colored glyph. Clicking switches that note's mode; if no commentary exists yet for (paragraph, mode), generation starts.
• Loading state: italic "consulting the literature…" with an animated ellipsis (steps(4), 1.2s)
• Error state: italic message (include the provider error, e.g. "no API key set — open the annotator settings") + "try again" text-button

Folio footer (rule + centered mono 10px, ink 45%): "annotations are machine-generated against retrieved literature — verify before citing". Keep this disclaimer.

4. Citation popover

Fixed-position card (360px; paper bg; 1px border ink 30%; shadow 0 16px 44px -16px rgba(40,30,10,0.5); padding 18px 20px 14px) anchored under the clicked chip, clamped to viewport (flips above if needed); invisible full-screen backdrop click-to-close; Esc closes; × button top-right. Contents: mono overline "RETRIEVED · RANK n" (9.5px, rubric, letter-spacing 0.1em) · title (16.5px / 600) · italic authors+year+journal (13px, ink 65%) · abstract (13.5px / 1.5) · score bars (when "Retrieval scores" tweak is on): rows of label | track | value — mono 10px, 3px track (ink 12%) with rubric fill; "specter" normalized /1.0, "bm25" /20 · footer links "ADS ↗" and "arXiv ↗" (mono 11px rubric) → https://ui.adsabs.harvard.edu/abs/{bibcode}/abstract and https://arxiv.org/abs/{arxiv}, new tab.

5. Annotator settings

Fixed panel, top-right (top 64px, right 24px, width 360px; same chrome as popover). Title "The Annotator" (19px / 600), italic subtitle "which mind writes in your margins". Fields:

• Provider: four toggle chips (mono 10.5px, 2px radius) — Built-in (Claude) / Anthropic / OpenAI / Gemini; active chip filled rubric. (In production, drop "Built-in" unless you ship a server-funded default.) Switching provider resets the model field to that provider's default: claude-haiku-4-5 / gpt-4o-mini / gemini-2.0-flash.
• Model: mono text input (12px; 1px border ink 22%; focus border rubric; bg ink 4%).
• API key (hidden for built-in): password input + mono hint "‹console URL› · stored only in this browser, sent only to ‹provider›".
• Footer rule + right-aligned "done". Field labels: 11px / 500 / uppercase / letter-spacing 0.14em / ink 70%.

6. Tweaks panel (prototype-only)

The prototype has a design-review Tweaks panel (palette, body size, drop caps, justification, notes side, score visibility). In production, promote notes side, body size, justification, and palette to a small user-facing "display" preferences menu; persist with the session/app preferences.

Interactions & Behavior

• Upload → pipeline → reader is a linear state machine (screen: 'upload' | 'pipeline' | 'reader').
• Mode switch (dot click): updates noteModes[paraId]; if commentary[paraId+':'+mode] is missing, fire generation (show loading state). Concurrent requests for the same key must be deduped; multiple different notes may generate in parallel.
• Regenerate (↻): always re-fires generation for the current (paragraph, mode), overwriting.
• Legend click: sets all paragraphs' modes (generating any missing ones).
• Hover cross-highlight paragraph ↔ note (7% mode-color tint both sides).
• Toast: fixed bottom-center, ink bg / paper text, mono 11px, padding 9px 18px, ~2.6s, for session events ("session written to …", "session restored", "could not read that session file").
• No animations on note re-positioning (snap, don't tween — tweening reads as drift).
• Responsive: below 900px, single column; notes render as static blocks beneath their paragraphs; folio padding 40px 26px.

State Management

screen        'upload' | 'pipeline' | 'reader'
fileName      string
paper         { title, authors, venue, arxivId, pages, paragraphs: [{ id, section, firstOfSection?, text }] }
litPapers     { [litId]: { id, short, title, authors, year, journal, bibcode, arxiv, abstract,
                           scores: { specter, bm25, rank } } }
litByPara     { [paraId]: litId[] }            // top-3, ranked
noteModes     { [paraId]: modeId }             // per-paragraph current mode
commentary    { [`${paraId}:${modeId}`]: { text, cites: litId[], source: 'canned'|'llm',
                                            error?, message? } }
generating    { [`${paraId}:${modeId}`]: true }  // in-flight
annotator     { provider: 'anthropic'|'openai'|'gemini', model: string, key: string }

Autosave the session to localStorage on every commentary/mode change; restore on load. Annotator config persists separately (localStorage, key never leaves the browser in the prototype — see security note below).

Session JSON schema (export/import — keep stable)

{
  "version": 1,
  "savedAt": "ISO-8601",
  "fileName": "string",
  "screen": "reader",
  "noteModes": { "p1": "explainer", ... },
  "commentary": { "p1:explainer": { "text": "...", "cites": ["mowla22"], "source": "llm" }, ... },
  "paper": { ...full paper object... }
}

Production additions: a content hash of the source PDF (to re-anchor sessions), and litPapers/litByPara (the prototype omits them from import since they're static). Never serialize the API key into sessions.

LLM commentary generation

Prompt template (keep; it produces good notes):

You are an erudite astronomical annotator writing a marginal note beside a paragraph of a
research paper, in the tradition of an annotated encyclopedia. Scholarly, precise, a little
wry. Write 55–85 words, a single paragraph, no markdown, no preamble. Refer to the retrieved
works by bracketed number, e.g. [1], where relevant.

{MODE_INSTRUCTION}

PARAGRAPH (from section "{section}"):
{paragraph text}

RETRIEVED LITERATURE (via Pathfinder):
[1] {short} — "{title}" ({journal}). {abstract}
[2] ...

Marginal note:

Mode instructions (verbatim in app.jsx): history = how the claim emerged, which earlier works set it up; referee = strongest assumption / unstated caveat / a check to report, specific not generic; literature = how retrieved works support/contradict/extend, compare numbers; explainer = plain language for a beginning grad student, unpack jargon, don't dumb down; methods = contrast technique with retrieved works' approaches, note trade-offs.

Provider routing (see annotator.jsx for working request shapes): Anthropic POST /v1/messages (max_tokens 400), OpenAI POST /v1/chat/completions, Gemini POST /v1beta/models/{model}:generateContent. Surface provider errors verbatim-but-truncated in the note error state.

Security note: the prototype calls provider APIs directly from the browser with the user's key (acceptable for a personal tool). For the public app, proxy LLM calls through the backend: accept the user's key per-request over HTTPS, hold it in memory only, never log or persist it. Cache completions server-side by hash(paragraph + mode + retrievedSetIds + model).

Backend pipeline specification (replaces the simulation)

FastAPI service; suggested endpoints:

1. POST /api/parse (multipart PDF) → { paper }.
   • pymupdf4llm.to_markdown() for extraction
   • Cleaning: drop lines repeating across ≥ half the pages (running headers/footers), page numbers, arXiv/DOI stamps; repair hyphenated line breaks; set aside figure/table captions and the references section
   • Segment into paragraphs (min length ~200 chars; merge continuation fragments across page breaks); detect section headings; mark firstOfSection
2. POST /api/index → embeds paragraphs with SPECTER2 (sentence-transformers, CPU fine at this scale) and builds a rank_bm25 index. Can be merged into /parse.
3. POST /api/retrieve → per-paragraph top-3 papers { litByPara, litPapers }.
   • Pathfinder (the authors' astronomy literature retrieval tool) or equivalent hybrid search over NASA ADS: SPECTER cosine + BM25, normalized as in the popover's score display. Requires an ADS API token (server-side secret)
4. POST /api/annotate { paragraph, mode, lit, provider, model, key } → { text } (the proxy above)
5. Progress for the pipeline screen via SSE or a polled job-status endpoint, mapping 1:1 to the six stage rows (with real counts in the log lines).

Assets

No images or icon fonts. Everything is typography: ¶ (U+00B6), ✦ (U+2726), ↻ (U+21BB), ✓, ↗, →, ×. Fonts from Google Fonts: EB Garamond, IBM Plex Mono. The bundled manuscript content in data.js (Mowla & Iyer 2024 + 10 retrieval papers with real bibcodes/arXiv IDs) is useful as a test fixture for the real pipeline.

Files

• Astroparse.html — shell; ALL CSS lives here (the canonical style reference)
• app.jsx — root state machine, session save/load, generation orchestration, prompt + mode instructions, Tweaks wiring
• reader.jsx — reader screen: note alignment algorithm (recompute), MarginNote, CitePopover, score bars, legend
• pipeline.jsx — upload screen + staged pipeline animation
• annotator.jsx — provider settings panel + apComplete() multi-provider router (working request shapes for all three APIs)
• data.js — data model exemplar: modes, paper, litPapers, litByPara, defaultModes, canned commentary, pipeline stage copy
• tweaks-panel.jsx — prototype-only design-review scaffolding; do not port

Open Astroparse.html in a browser to interact with the reference implementation.