Spaces:
Sleeping
Sleeping
Download app.py from BVendeville/reading-study-validity: direct link, hf CLI and curl.
- Browser
- Download file 35.5 kB
-
https://huggingface.co/spaces/BVendeville/reading-study-validity/resolve/main/app.py
- Command line
-
hf download hf://spaces/BVendeville/reading-study-validity/app.py
-
curl -L -o app.py https://huggingface.co/spaces/BVendeville/reading-study-validity/resolve/main/app.py
35.5 kB
| """Gradio annotation app for the human evaluation (HUMAN_EVALUATION.md §4). UI wiring only; logic is in core.py. | |
| python app.py --data example_input.json [--config config.yaml] [--host 0.0.0.0] [--port 7860] | |
| Every option has an env var (ANNOTATION_DATA, ANNOTATION_CONFIG, ANNOTATION_OUTPUT_DIR, ANNOTATION_LAYOUT, | |
| ANNOTATION_HUB_REPO) because a Hugging Face Space starts the app with no arguments. With ANNOTATION_HUB_REPO set, | |
| config, documents and answers live in that private dataset repo (hub.py). | |
| """ | |
| from __future__ import annotations | |
| import argparse | |
| import atexit | |
| import html | |
| import inspect | |
| import os | |
| import signal | |
| import sys | |
| import tempfile | |
| from pathlib import Path | |
| os.environ["GRADIO_ANALYTICS_ENABLED"] = "False" # before gradio is imported: no telemetry, no version check | |
| import gradio as gr # noqa: E402 | |
| HERE = Path(__file__).resolve().parent | |
| sys.path.insert(0, str(HERE)) | |
| import core as C # noqa: E402 | |
| import guide as G # noqa: E402 | |
| CSS = """ | |
| :root { color-scheme: light; } /* light theme only, see FRAME_FIT_JS */ | |
| /* Each text is one card: its name is a header bar INSIDE the card's border, so a name can only belong to the | |
| text it frames, even when the cards are stacked. */ | |
| .ann-card { border: 2px solid var(--border-color-primary); border-radius: 8px; overflow: hidden; } | |
| .ann-card-head { font-size: 1.15rem; font-weight: 700; padding: 0.45rem 1rem; | |
| background: var(--background-fill-secondary); border-bottom: 1px solid var(--border-color-primary); } | |
| .ann-card-source { border-color: var(--color-accent, #f97316); } | |
| .ann-card-source .ann-card-head { background: var(--color-accent-soft, #fff7ed); } | |
| .ann-text { max-height: 70vh; overflow-y: auto; padding: 0.5rem 1rem; line-height: 1.55; } | |
| .ann-card-source .ann-text { max-height: 45vh; } | |
| .ann-vertical { gap: 2rem !important; } /* clear space between stacked cards */ | |
| .ann-vertical .ann-card:not(.ann-card-source) .ann-text { max-height: none; } /* stacked texts grow to full length */ | |
| /* the participant's ID: hard to miss */ | |
| .ann-idwarn { background: #fff7e0; border: 2px solid #e0a800; border-radius: 8px; padding: 0.7rem 1rem; line-height: 1.6; } | |
| .ann-idbox { background: #fff7e0; border: 2px solid #e0a800; border-radius: 10px; padding: 1rem 1.2rem; | |
| font-size: 1.1rem; line-height: 1.6; margin-bottom: 0.5rem; } | |
| .ann-id { font-family: ui-monospace, monospace; font-size: 1.6rem; font-weight: 700; padding: 0.1rem 0.5rem; | |
| background: #fff; border: 1px dashed #b38600; border-radius: 6px; margin-left: 0.3rem; } | |
| /* the questions: large, normal weight, only the key words bold (written in Markdown) */ | |
| .ann-qtext p { font-size: 1.25rem !important; font-weight: 400 !important; line-height: 1.45; margin: 0.9rem 0 0.2rem; } | |
| .ann-qtext strong { font-weight: 700; } | |
| /* instructions panel: its own tinted background and a coloured header bar, so it stands apart from the task */ | |
| #guide { background: #eef4fb !important; border: 2px solid #2f6db5 !important; border-radius: 10px !important; } | |
| #guide > button.label-wrap { background: #2f6db5; color: #fff; font-weight: 700; font-size: 1.05rem; | |
| padding: 0.65rem 1rem; margin: -1px; width: calc(100% + 2px); | |
| border-radius: 8px 8px 0 0; } | |
| #guide > button.label-wrap span { color: #fff; } | |
| #guide .prose, #guide .md { background: transparent !important; } | |
| /* instructions panel: real titles, not body-size bold lines */ | |
| #guide h3 { font-size: 1.45rem !important; font-weight: 700; margin: 1.4rem 0 0.5rem; | |
| padding-bottom: 0.2rem; border-bottom: 1px solid var(--border-color-primary); } | |
| #guide h4 { font-size: 1.15rem !important; font-weight: 700; margin: 1.1rem 0 0.35rem; } | |
| #guide p, #guide li { line-height: 1.6; } | |
| .ann-error { color: var(--error-text-color, #b91c1c); font-weight: 600; } | |
| """ | |
| GRADIO_6 = int(gr.__version__.split(".")[0]) >= 6 | |
| # Events are UI-only: no API endpoint a script could call to skip the screen order. | |
| EVENT = {"api_visibility": "private"} if GRADIO_6 else {"show_api": False, "api_name": False} | |
| def theme(): | |
| """System fonts only: the default theme would fetch Google Fonts.""" | |
| return gr.themes.Default(font=["system-ui", "sans-serif"], font_mono=["ui-monospace", "monospace"]) | |
| # Inside the Hugging Face Space page the app sits in an iframe whose height gradio reports itself; gradio stops | |
| # reporting after a few successive grows, so long screens got cut off (submit button out of reach). This keeps the | |
| # frame as tall as the content: it measures the bottom of the last element (not the document, which can stretch to | |
| # the frame and would loop) and asks iframe-resizer for that height whenever it changes. | |
| # It also scrolls back to the top whenever a new screen is shown (the progress line changes): the submit button is at | |
| # the bottom, so otherwise the next document opened on its last text and the questions, with "Document N" and the | |
| # first texts out of view. It also keeps the page in the light theme whatever the reader's dark-mode setting. | |
| FRAME_FIT_JS = """ | |
| <script> | |
| (function () { | |
| let last = 0, shown = ''; | |
| function fit() { | |
| const pif = window.parentIFrame, end = document.getElementById('bottom_spacer'); | |
| if (!pif || !end) return; | |
| const h = Math.ceil(end.getBoundingClientRect().bottom + window.scrollY + 24); | |
| if (Math.abs(h - last) > 2) { last = h; pif.size(h); } | |
| } | |
| function toTop() { | |
| // only the "Document N of M" part: while an event runs, gradio's status timer adds text to the element | |
| const p = [...document.querySelectorAll('#s1_progress, #s2_progress')].find(e => e.offsetParent !== null); | |
| const m = p ? p.textContent.match(/Document \\d+ of \\d+/) : null; | |
| const key = m ? p.id + '|' + m[0] : null; // the id too: screens 1 and 2 of one document share the label | |
| if (!key || key === shown) return; | |
| shown = key; | |
| window.scrollTo(0, 0); | |
| const pif = window.parentIFrame; | |
| if (pif && pif.scrollToOffset) pif.scrollToOffset(0, 0); | |
| } | |
| function light() { | |
| // always the light theme: the custom colours assume it, and gradio's dark mode (from the system setting or | |
| // the Space page) gave white text on white panels | |
| for (const el of [document.documentElement, document.body]) if (el && el.classList.contains('dark')) el.classList.remove('dark'); | |
| } | |
| light(); | |
| new MutationObserver(() => { light(); fit(); toTop(); }).observe(document.documentElement, | |
| {subtree: true, childList: true, attributes: true}); | |
| window.addEventListener('resize', fit); | |
| setInterval(fit, 1000); | |
| })(); | |
| </script> | |
| """ | |
| def launch_kwargs(host=None, port=None) -> dict: | |
| """Keyword arguments for demo.launch(), keeping only those this gradio version accepts.""" | |
| kw = {"share": False, "ssr_mode": False, "server_name": host, "server_port": port, | |
| "show_api": False, # gradio 5: no API page | |
| "footer_links": [], # gradio 6: no footer (API docs, settings, run-history links) | |
| "run_history": False, # gradio 6: do not keep past runs in the browser | |
| "max_file_size": 1024, # the app takes no files: refuse anonymous uploads to the upload route | |
| "pwa": False, | |
| "head": FRAME_FIT_JS} # no installable-app manifest (on by default on a Space) | |
| if GRADIO_6: | |
| kw.update(theme=theme(), css=CSS) | |
| accepted = inspect.signature(gr.Blocks.launch).parameters | |
| return {k: v for k, v in kw.items() if k in accepted and v is not None} | |
| def _card(title: str, text: str, source: bool = False) -> str: | |
| body = "".join("<p>" + "<br>".join(html.escape(line) for line in block) + "</p>" for block in C.paragraphs(text)) | |
| return (f'<div class="ann-card{" ann-card-source" if source else ""}"><div class="ann-card-head">{title}</div>' | |
| f'<div class="ann-text">{body}</div></div>') | |
| def _id_box(code: str) -> str: | |
| return ('<div class="ann-idbox">Your ID is <span class="ann-id">' + html.escape(code) + '</span>' | |
| '<div>Write it down or take a screenshot <b>now</b>. You need it to come back to where you stopped, ' | |
| 'and nobody can recover it for you.</div></div>') | |
| def qmd(text: str, eid: str, visible: bool = True): | |
| """A question line: normal weight, large, with only its key words in bold (Markdown).""" | |
| return gr.Markdown(text, elem_id=eid, elem_classes=["ann-qtext"], visible=visible) | |
| def _err(msg: str | None) -> str: | |
| return f'<div class="ann-error">{html.escape(msg)}</div>' if msg else "" | |
| LAYOUTS = ("horizontal", "vertical") | |
| TASKS = ("both", "simplicity", "validity") # both = screen 1 then screen 2; or one screen per Space | |
| # Shown under the study title, so each Space says which part of the study it is and what to do. | |
| TASK_INTRO = { | |
| "both": "", | |
| "simplicity": "### How easy is each text to follow?\n" | |
| "For each document you read three simplifications of the same scientific text, written for " | |
| "non-expert readers, and say which is easiest and which is hardest to follow. You do not see the " | |
| "original text here.\n\nThe texts are in English: please take part only if you read English comfortably.", | |
| "validity": "### Does each text match the original?\n" | |
| "For each document you read the original scientific text and three simplifications of it, written " | |
| "for non-expert readers, and tick the simplifications that leave out important information, " | |
| "contradict the original, or state a finding more broadly than it supports.\n\nThe texts are in English: please take part only if you read English comfortably.", | |
| } | |
| def build_demo(docs, config, out_dir: str | Path, meta: dict, layout: str = "horizontal", on_saved=None, | |
| on_login=None, remote_has=None, task: str = "both", split: bool = False) -> gr.Blocks: | |
| """``docs`` and ``config`` are the frozen objects from core.load_data / core.load_config; they are only read. | |
| ``layout``: the three texts side by side ("horizontal") or one above another ("vertical"). | |
| ``on_saved(code)`` is called after a line is written (hub.AnswerSync.push, to copy it to the private repo). | |
| ``on_login(code)`` is called before the resume position is computed (hub.AnswerSync.pull). | |
| ``remote_has(code)`` says whether the private repo already has that ID (hub.AnswerSync.remote_has). | |
| ``task``: "both" (simplicity without the source, locked, then validity with it), "simplicity" (screen 1 only; | |
| the source is never shown) or "validity" (screen 2 only: source and texts together). | |
| ``split``: each person gets one of the four blocks (a quarter of the documents) instead of all of them.""" | |
| if layout not in LAYOUTS: | |
| raise ValueError(f"layout must be one of {LAYOUTS}, got {layout!r}") | |
| if task not in TASKS: | |
| raise ValueError(f"task must be one of {TASKS}, got {task!r}") | |
| meta = {**meta, "layout": layout, "task": task} | |
| def texts_box(): | |
| return gr.Row(equal_height=False) if layout == "horizontal" else gr.Column(elem_classes=["ann-vertical"]) | |
| n_docs = len(docs) | |
| systems = list(docs[0]["simplifications"]) | |
| salt = str(config["study"].get("position_salt", "")) | |
| study = config["study"] | |
| style = {} if GRADIO_6 else {"theme": theme(), "css": CSS} # gradio 6 takes them in launch() | |
| # delete_cache: anything left in gradio's temp dir (e.g. junk sent to the upload route) is removed hourly | |
| with gr.Blocks(title=study.get("title", "Annotation"), analytics_enabled=False, delete_cache=(3600, 3600), | |
| **style) as demo: | |
| state = gr.State(None) | |
| gr.Markdown(f"## {study.get('title', 'Annotation')}") | |
| if TASK_INTRO[task]: | |
| gr.Markdown(TASK_INTRO[task], elem_id="task_intro") | |
| guide_md = study.get(f"guide_{task}") or G.GUIDE.get(task) | |
| if guide_md: # always on the page, so it can be reopened at any time | |
| with gr.Accordion("Instructions and example (click to open or close at any time)", open=False, | |
| elem_id="guide"): | |
| gr.Markdown(guide_md) | |
| with gr.Column(visible=True) as g_start: | |
| key_in = gr.Textbox(label="Access key", type="password", placeholder="the key you were sent", | |
| visible=bool(config.get("access_key") or config.get("expert_access_key") | |
| or config.get("block_keys")), | |
| elem_id="key_in") | |
| if task != "both": | |
| gr.Markdown("Please read **Instructions and example** above before you start; you can open it again " | |
| "at any time, on every page.") | |
| gr.HTML('<div class="ann-idwarn"><b>First time?</b> Choose an ID (not your name). ' | |
| '<b>Write it down now, somewhere you will find it again</b> (on paper, in your phone, in a note): ' | |
| 'it is the <b>only</b> way to come back to where you stopped. We cannot look it up or reset it ' | |
| 'for you.<br><b>Coming back?</b> Enter the ID you chose last time.</div>') | |
| code_in = gr.Textbox(label="Your ID", placeholder="3 to 30 letters, digits, - or _", elem_id="code_in") | |
| with gr.Row(): | |
| new_btn = gr.Button("I'm new: start with this ID", variant="primary", elem_id="new_btn") | |
| code_btn = gr.Button("I'm coming back: continue", variant="secondary", elem_id="code_btn") | |
| start_err = gr.HTML("", elem_id="start_err") | |
| with gr.Group(visible=False) as g_consent: | |
| id_box = gr.HTML("", elem_id="id_box") # the participant's ID, shown big, before anything else | |
| id_saved_cb = gr.Checkbox(label="I have saved my ID somewhere I will find it again.", value=False, | |
| elem_id="id_saved_cb") | |
| gr.Markdown(study.get(f"consent_markdown_{task}") or study["consent_markdown"]) # per-Space text | |
| consent_cb = gr.Checkbox(label="I have read the above and agree to take part.", value=False, elem_id="consent_cb") | |
| consent_btn = gr.Button("Continue", variant="primary", elem_id="consent_btn") | |
| consent_err = gr.HTML("", elem_id="consent_err") | |
| with gr.Column(visible=False) as g_s1: | |
| s1_progress = gr.Markdown("", elem_id="s1_progress") | |
| gr.Markdown("Read the three texts below, then answer the questions.") | |
| with texts_box(): | |
| s1_texts = [] | |
| for L in C.LETTERS: | |
| with gr.Column(): | |
| s1_texts.append(gr.HTML("", elem_id=f"s1_text_{L}")) | |
| # each question is a Markdown line (only its key words in bold) above an unlabeled answer component | |
| qmd("Which of these did you find **easiest to follow**?", "q_easiest") | |
| easiest = gr.Radio(list(C.LETTERS), label=C.Q_EASIEST, show_label=False, value=None, elem_id="easiest") | |
| qmd("Which did you find **hardest to follow**?", "q_hardest") | |
| hardest = gr.Radio(list(C.LETTERS), label=C.Q_HARDEST, show_label=False, value=None, elem_id="hardest") | |
| gap_bm_q = qmd("", "q_gap_bm", visible=False) | |
| gap_bm = gr.Radio(list(C.GAPS), label="", show_label=False, value=None, visible=False, elem_id="gap_bm") | |
| gap_mw_q = qmd("", "q_gap_mw", visible=False) | |
| gap_mw = gr.Radio(list(C.GAPS), label="", show_label=False, value=None, visible=False, elem_id="gap_mw") | |
| s1_err = gr.HTML("", elem_id="s1_err") | |
| s1_btn = gr.Button("Submit and go to the next document" if task == "simplicity" else | |
| "Submit and continue (answers cannot be changed afterwards)", variant="primary", | |
| elem_id="s1_btn") | |
| with gr.Column(visible=False) as g_s2: | |
| s2_progress = gr.Markdown("", elem_id="s2_progress") | |
| gr.Markdown("Compare each text with the **source** it was written from." if task == "validity" else | |
| "Now compare each text with the **source** it was written from.") | |
| s2_source = gr.HTML("", elem_id="s2_source") # stays empty until screen 1 is locked | |
| with texts_box(): | |
| s2_texts = [] | |
| for L in C.LETTERS: | |
| with gr.Column(): | |
| s2_texts.append(gr.HTML("", elem_id=f"s2_text_{L}")) | |
| qmd("Does the simplification **leave out important information** from the source?", "q_omits") | |
| omits = gr.CheckboxGroup(list(C.LETTERS), label=C.Q_OMITS, show_label=False, value=[], elem_id="omits") | |
| qmd("Does the simplification **contradict the source**?", "q_contradicts") | |
| contradicts = gr.CheckboxGroup(list(C.LETTERS), label=C.Q_CONTRADICTS, show_label=False, value=[], | |
| elem_id="contradicts") | |
| overgen_q = qmd("Does the simplification **state a finding more broadly than the source supports**? For " | |
| "example dropping who it applies to, or under what conditions.", "q_overgen", visible=False) | |
| overgen = gr.CheckboxGroup(list(C.LETTERS), label=C.Q_OVERGENERALISES, show_label=False, value=[], | |
| visible=False, elem_id="overgen") | |
| gr.Markdown("There may well be no error: leave a question unticked if none of the texts applies.") | |
| s2_err = gr.HTML("", elem_id="s2_err") | |
| s2_btn = gr.Button("Submit and go to the next document", variant="primary", elem_id="s2_btn") | |
| with gr.Group(visible=False) as g_done: | |
| done_md = gr.Markdown("", elem_id="done_md") | |
| # end marker: FRAME_FIT_JS sizes the Space page's frame to its bottom; a little space after the last button | |
| gr.HTML('<div style="height:60px"></div>', elem_id="bottom_spacer") | |
| groups = {"start": g_start, "consent": g_consent, "s1": g_s1, "s2": g_s2, "done": g_done} | |
| ALL = [state, *groups.values(), start_err, consent_err, s1_progress, *s1_texts, easiest, hardest, gap_bm, | |
| gap_mw, gap_bm_q, gap_mw_q, overgen_q, id_box, id_saved_cb, s1_err, s2_progress, s2_source, *s2_texts, omits, contradicts, overgen, s2_err, done_md] | |
| def show(screen: str) -> dict: | |
| return {g: gr.update(visible=(k == screen)) for k, g in groups.items()} | |
| def progress(st) -> str: | |
| return f"**Document {st['pos'] + 1} of {len(st['queue'])}** · your ID: `{st['code']}`" | |
| def enter_next(st) -> dict: | |
| """The current document's first screen (screen 2 directly for the validity task), or the done screen.""" | |
| if task == "validity" and st["pos"] < len(st["queue"]): | |
| doc = C.doc_by_id(docs, st["queue"][st["pos"]]) | |
| st.update(positions=C.positions(st["code"], doc["doc_id"], systems, salt), s1=None, times={}) | |
| return enter_s2(st, doc) | |
| return enter_s1(st) | |
| def enter_s2(st, doc) -> dict: | |
| view = C.screen2_view(doc, st["positions"]) # the source enters the session only now | |
| st.update(screen="s2", view=view) | |
| st["times"]["screen2_shown"] = C.now_iso() | |
| return {**show("s2"), state: st, s2_progress: progress(st), s1_err: "", s2_err: "", | |
| **{t: "" for t in s1_texts}, | |
| s2_source: _card("Source", view["source"], source=True), | |
| **{t: _card(f"Text {L}", view["texts"][L]) for t, L in zip(s2_texts, C.LETTERS)}, | |
| omits: gr.update(value=[]), contradicts: gr.update(value=[]), | |
| overgen: gr.update(value=[], visible=st["cohort"] == "expert"), | |
| overgen_q: gr.update(visible=st["cohort"] == "expert")} | |
| def save(st, s2_answers, err_box, submitted_key) -> dict: | |
| """Write this document's line, push it, and move on (or show the error on the current screen).""" | |
| st["times"][submitted_key] = C.now_iso() | |
| doc_index = next(i for i, d in enumerate(docs) if d["doc_id"] == st["view"]["doc_id"]) | |
| rec = C.build_record(st, n_docs, doc_index, s2_answers, meta) | |
| try: | |
| if C.append_record(out_dir, rec) and on_saved: # False = already saved from another tab | |
| on_saved(st["code"]) | |
| except OSError as e: | |
| st["times"].pop(submitted_key) | |
| return {err_box: _err(f"Could not save your answers ({e}). Please try again or contact the organiser.")} | |
| st["pos"] = C.next_index(st["queue"], C.done_ids(out_dir, st["code"])) | |
| return enter_next(st) | |
| def enter_s1(st) -> dict: | |
| """Start screen 1 for the current document, or the done screen. Clears every screen-2 field.""" | |
| out = {s2_source: "", **{t: "" for t in s2_texts}, s2_err: "", s1_err: ""} | |
| if st["pos"] >= len(st["queue"]): | |
| st.update(screen="done", view=None) | |
| return {**out, **show("done"), state: st, | |
| done_md: f"All {len(st['queue'])} documents are done (ID `{st['code']}`). Thank you! You can close " | |
| f"this page."} | |
| doc = C.doc_by_id(docs, st["queue"][st["pos"]]) | |
| pos = C.positions(st["code"], doc["doc_id"], systems, salt) | |
| view = C.screen1_view(doc, pos) | |
| st.update(screen="s1", view=view, positions=pos, s1=None, times={"screen1_shown": C.now_iso()}) | |
| return {**out, **show("s1"), state: st, s1_progress: progress(st), | |
| **{t: _card(f"Text {L}", view["texts"][L]) for t, L in zip(s1_texts, C.LETTERS)}, | |
| easiest: gr.update(value=None), hardest: gr.update(value=None), | |
| gap_bm: gr.update(value=None, visible=False), gap_mw: gr.update(value=None, visible=False), | |
| gap_bm_q: gr.update(visible=False), gap_mw_q: gr.update(visible=False)} | |
| def pull(norm): | |
| if on_login: | |
| try: | |
| on_login(norm) | |
| except Exception as e: # noqa: BLE001 -- Hub unreachable: resume from the local copy | |
| print(f"[answer-sync] could not re-read {norm}'s answers from the repo: {e}", flush=True) | |
| def on_code(code, key, st): | |
| """A returning participant: the ID must exist (signed up before, or reserved in the config).""" | |
| if C.key_cohort(key, config) is None and C.block_key(key, config) is None: | |
| return {start_err: _err("Wrong access key.")} | |
| norm, err = C.validate_id(code) | |
| if err: | |
| return {start_err: _err(err)} | |
| pull(norm) | |
| if C.registration(out_dir, norm, config) is None: | |
| return {start_err: _err(f"No participant with the ID “{norm}”. Check it, or start as new.")} | |
| st = C.new_session(norm, config, docs, out_dir, split) | |
| return {**show("consent"), state: st, start_err: "", consent_err: "", id_box: _id_box(norm), | |
| id_saved_cb: gr.update(value=False)} | |
| def on_new(code, key, st): | |
| """A new participant: sign the ID up (cohort from the key, next order in rotation).""" | |
| block = None | |
| if split and config["block_keys"]: # this Space hands out blocks by personal key only | |
| info = C.block_key(key, config) | |
| if info is None: | |
| return {start_err: _err("Wrong access key. Use the personal key you were sent for this part.")} | |
| cohort, block = info["cohort"], info["block"] | |
| else: | |
| cohort = C.key_cohort(key, config) | |
| if cohort is None: | |
| return {start_err: _err("Wrong access key.")} | |
| norm, err = C.validate_id(code) | |
| if err: | |
| return {start_err: _err(err)} | |
| taken = C.id_taken(out_dir, norm, config) | |
| if not taken and remote_has: | |
| try: | |
| taken = remote_has(norm) | |
| except Exception as e: # noqa: BLE001 -- cannot check the repo: do not risk a duplicate | |
| print(f"[answer-sync] could not check ID {norm} in the repo: {e}", flush=True) | |
| return {start_err: _err("Could not check this ID right now. Please try again in a minute.")} | |
| if taken or not C.register(out_dir, norm, cohort, C.assign_order(out_dir, config, cohort), block): | |
| return {start_err: _err(f"The ID “{norm}” is already taken. If it is yours, click “I'm coming " | |
| f"back”; otherwise choose another.")} | |
| if on_saved: | |
| on_saved(norm) | |
| st = C.new_session(norm, config, docs, out_dir, split) | |
| return {**show("consent"), state: st, start_err: "", consent_err: "", id_box: _id_box(norm), | |
| id_saved_cb: gr.update(value=False)} | |
| def lost() -> dict: | |
| """No session: the server restarted (a Space restart) or gradio dropped an idle closed tab's state. An empty | |
| dict would make gradio paint an 'Error' badge on every component, with no hint of what to do.""" | |
| msg = _err("This page lost its connection to the study (the page was restarted or left idle for a long " | |
| "time). Your answers to earlier documents are saved, this one is not. Please reload this page and click " | |
| "“I'm coming back” with your ID.") | |
| return {consent_err: msg, s1_err: msg, s2_err: msg} | |
| def on_consent(agreed, saved, st): | |
| if not st: | |
| return lost() | |
| if st["screen"] != "consent": | |
| return {state: st} # a stale click: nothing to do | |
| if not saved: | |
| return {consent_err: _err("Please save your ID first, then tick the box: without it you cannot " | |
| "come back to where you stopped.")} | |
| if not agreed: | |
| return {consent_err: _err("Please tick the box to continue.")} | |
| st["consent_at"] = C.now_iso() | |
| return enter_next(st) | |
| def on_rank(e, h): | |
| """Show the two gap questions, naming the actual letters, once easiest and hardest are set.""" | |
| hide = {gap_bm: gr.update(value=None, visible=False), gap_mw: gr.update(value=None, visible=False), | |
| gap_bm_q: gr.update(visible=False), gap_mw_q: gr.update(visible=False)} | |
| if e not in C.LETTERS or h not in C.LETTERS: | |
| return {**hide, s1_err: ""} | |
| if e == h: | |
| return {**hide, s1_err: _err("The easiest and the hardest text must be different.")} | |
| m = C.middle_of(e, h) | |
| return {gap_bm: gr.update(label=C.gap_question(e, m), value=None, visible=True), | |
| gap_mw: gr.update(label=C.gap_question(m, h), value=None, visible=True), | |
| gap_bm_q: gr.update(value=f"**How much easier** is {e} than {m}?", visible=True), | |
| gap_mw_q: gr.update(value=f"**How much easier** is {m} than {h}?", visible=True), s1_err: ""} | |
| def on_s1(e, h, g1, g2, st): | |
| if not st: | |
| return lost() | |
| if st["screen"] != "s1": | |
| return {state: st} | |
| err = C.check_screen1(e, h, g1, g2) | |
| if err: | |
| return {s1_err: _err(err)} | |
| st["s1"] = C.screen1_answers(e, h, g1, g2) | |
| if task == "simplicity": | |
| return save(st, None, s1_err, "screen1_submitted") | |
| st["times"]["screen1_submitted"] = C.now_iso() | |
| return enter_s2(st, C.doc_by_id(docs, st["view"]["doc_id"])) | |
| def on_s2(om, co, ov, st): | |
| if not st: | |
| return lost() | |
| if st["screen"] != "s2": | |
| return {state: st} | |
| return save(st, C.screen2_answers(st["cohort"], om, co, ov), s2_err, "screen2_submitted") | |
| code_btn.click(on_code, [code_in, key_in, state], ALL, **EVENT) | |
| new_btn.click(on_new, [code_in, key_in, state], ALL, **EVENT) | |
| consent_btn.click(on_consent, [consent_cb, id_saved_cb, state], ALL, **EVENT) | |
| easiest.change(on_rank, [easiest, hardest], [gap_bm, gap_mw, gap_bm_q, gap_mw_q, s1_err], **EVENT) | |
| hardest.change(on_rank, [easiest, hardest], [gap_bm, gap_mw, gap_bm_q, gap_mw_q, s1_err], **EVENT) | |
| s1_btn.click(on_s1, [easiest, hardest, gap_bm, gap_mw, state], ALL, **EVENT) | |
| s2_btn.click(on_s2, [omits, contradicts, overgen, state], ALL, **EVENT) | |
| # On a Space, gradio's page adds a Hugging Face header (Space name, owner avatar, likes) that also loads Google | |
| # Fonts and calls the Hub API from the participant's browser. It names the account, so drop it: space_id is only | |
| # used for that header and for API docs snippets (off here). | |
| demo.space_id = None | |
| return demo | |
| def main(argv=None): | |
| ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) | |
| ap.add_argument("--data", default=os.environ.get("ANNOTATION_DATA"), help="input documents JSON") | |
| ap.add_argument("--config", default=os.environ.get("ANNOTATION_CONFIG"), | |
| help="default: config.yaml next to app.py, else config.example.yaml (env ANNOTATION_CONFIG)") | |
| ap.add_argument("--out", default=os.environ.get("ANNOTATION_OUTPUT_DIR"), | |
| help="annotation output directory (env ANNOTATION_OUTPUT_DIR; default annotations/<data file stem>)") | |
| ap.add_argument("--layout", default=os.environ.get("ANNOTATION_LAYOUT", "horizontal"), choices=LAYOUTS, | |
| help="texts side by side or one above another (env ANNOTATION_LAYOUT)") | |
| ap.add_argument("--task", default=os.environ.get("ANNOTATION_TASK", "both"), choices=TASKS, | |
| help="both screens, or only simplicity / only validity (env ANNOTATION_TASK); answers of a " | |
| "single-task app go to a folder <data stem>-<task>") | |
| ap.add_argument("--split", action="store_true", default=os.environ.get("ANNOTATION_SPLIT", "").strip().lower() in ("1", "true", "yes"), | |
| help="each person gets one of the four blocks (a quarter of the documents), assigned in " | |
| "rotation, so four people cover every document once (env ANNOTATION_SPLIT=1)") | |
| ap.add_argument("--hub-repo", default=os.environ.get("ANNOTATION_HUB_REPO"), | |
| help="private HF dataset repo holding config, documents and answers; --data/--config are then " | |
| "paths inside it (env ANNOTATION_HUB_REPO; token from HF_TOKEN)") | |
| public_env = os.environ.get("ANNOTATION_PUBLIC") | |
| ap.add_argument("--public", action="store_true", | |
| default=(public_env.strip().lower() not in ("", "0", "false", "no")) if public_env is not None | |
| else bool(os.environ.get("SPACE_ID")), | |
| help="anyone can reach the page: require a shared access key (env ANNOTATION_PUBLIC; on by " | |
| "default on a Hugging Face Space)") | |
| ap.add_argument("--accept-changed-data", action="store_true", | |
| default=bool(os.environ.get("ANNOTATION_ACCEPT_CHANGED_DATA")), | |
| help="start even if saved answers refer to another version of the documents file") | |
| ap.add_argument("--host", default=None, help="default: gradio's (GRADIO_SERVER_NAME or 127.0.0.1)") | |
| ap.add_argument("--port", type=int, default=None) | |
| args = ap.parse_args(argv) | |
| sys.stdout.reconfigure(line_buffering=True) # Space logs show each line as it happens, not at exit | |
| if not args.data: | |
| ap.error("--data (or ANNOTATION_DATA) is required") | |
| stem = Path(args.data).stem + ("" if args.task == "both" else f"-{args.task}") | |
| explicit_out = bool(args.out) | |
| if args.hub_repo: | |
| # always one folder per item set; without an explicit (persistent) dir, a fresh private one, so local test | |
| # answers in the checkout are never uploaded as real ones | |
| args.out = str(Path(args.out or tempfile.mkdtemp(prefix="annot_answers_")) / stem) | |
| elif not args.out: # one folder per input file, so answers to different item sets never share a file | |
| args.out = str(HERE / "annotations" / stem) | |
| sync = None | |
| if args.hub_repo: | |
| import hub as H | |
| store = H.open_store(args.hub_repo) | |
| cache = Path(tempfile.mkdtemp(prefix="annot_private_")) # outside the app folder, never served | |
| args.data = str(H.fetch(store, args.data, cache)) | |
| args.config = str(H.fetch(store, args.config or "config.yaml", cache)) | |
| print(f"private repo {args.hub_repo}: fetched documents and config") | |
| elif not args.config: | |
| args.config = str(HERE / "config.yaml") if (HERE / "config.yaml").exists() else str(HERE / "config.example.yaml") | |
| print(f"config: {Path(args.config).name}") | |
| docs = C.load_data(args.data) | |
| config = C.load_config(args.config, public=args.public, access_key=os.environ.get("ANNOTATION_ACCESS_KEY"), | |
| expert_access_key=os.environ.get("ANNOTATION_EXPERT_ACCESS_KEY")) | |
| print(f"access key: {'required' if config['access_key'] else 'none'}; " | |
| f"expert key: {'set' if config['expert_access_key'] else 'none (nobody joins the expert cohort)'}") | |
| Path(args.out).mkdir(parents=True, exist_ok=True) | |
| meta = {"data_sha256": C.file_sha256(args.data), "app_version": C.app_version()} | |
| def refuse_stale(where: str) -> None: | |
| stale = C.answers_from_other_data(args.out, meta["data_sha256"]) | |
| if stale and not args.accept_changed_data: | |
| sys.exit(f"Refusing to start: saved answers {where} refer to another version of the documents file " | |
| f"({stale} lines per code). Resume would count those documents as done. Move those answers " | |
| f"elsewhere, or set --accept-changed-data / ANNOTATION_ACCEPT_CHANGED_DATA=1 if intended.") | |
| refuse_stale(f"in {args.out}") # before anything local could be pushed to the repo | |
| if args.hub_repo: | |
| sync = H.AnswerSync(store, args.out, f"annotations/{stem}", push_local_only=explicit_out) | |
| counts = sync.restore() | |
| print(f"restored answers from the private repo: {counts or 'none yet'}") | |
| def _flush_and_exit(*_): # a Space restart sends SIGTERM: push what is pending first | |
| print("[answer-sync] shutting down, flushing pending pushes", flush=True) | |
| sync.flush(25) | |
| sys.exit(0) | |
| atexit.register(sync.flush, 25) | |
| signal.signal(signal.SIGTERM, _flush_and_exit) | |
| if args.hub_repo: | |
| refuse_stale(f"in the private repo under annotations/{stem}/") | |
| print(f"{len(docs)} documents, {len(config['annotators'])} reserved IDs, writing to {Path(args.out).resolve()}") | |
| demo = build_demo(docs, config, args.out, meta, layout=args.layout, on_saved=sync.push if sync else None, | |
| on_login=sync.pull if sync else None, remote_has=sync.remote_has if sync else None, | |
| task=args.task, split=args.split) | |
| demo.queue().launch(**launch_kwargs(args.host, args.port)) | |
| if __name__ == "__main__": | |
| main() | |