Effort: standard
Goal
The default /hypothesis/{id} view assumes a senior researcher
audience: dense mechanistic prose, PMID stacks, 10-dim composite
scoring. A med student or rotating clinician opening the same page
bounces in 5 seconds. We need an alternate per-hypothesis view
that re-renders the same artifact at a different reading level
without losing rigor — rephrased mechanism, defined jargon, simpler
analogies, and a "where this would show up clinically" connection.
This is not a separate document — it's a render mode of the
existing hypothesis. Toggle in the page UI; default to the audience
implied by the user's profile (or phd for anonymous traffic).
Acceptance Criteria
☐ New module scidex/agora/hypothesis_audience_view.py:
-
render_for_audience(hyp_id, audience: Literal['med_student',
'undergrad', 'patient', 'phd', 'expert']) -> dict returns
{statement_md, mechanism_md, evidence_md, clinical_relevance_md,
glossary_terms, comprehension_check_question}. The phd /
expert audience returns the original strings unchanged; non-
default audiences invoke an LLM with a per-audience prompt.
☐ Audience prompts live in
scidex/agora/prompts/audience_views/ as Markdown templates
with placeholder substitution. Each prompt explicitly
preserves: every PMID citation; numerical effect sizes;
hypothesis falsification criteria. Prompts forbid
simplifications that change the underlying claim.
☐ UI: on /hypothesis/{id} add an audience-selector
dropdown in the hero (default =
phd). Switching the
dropdown rerenders the page sections without a full
navigation; selection persists in
localStorage.
☐ Cache: rendered alternate views cached in
hypothesis_audience_renders table keyed by
(hyp_id, audience, hyp_version); invalidated on
hypothesis update.
☐ comprehension_check_question is a single multiple-choice
question testing the reader understood the core claim;
stored alongside the render and submitted via
/api/hypothesis/{id}/comprehension-check. Aggregate
correctness rate is logged for evaluating the audience-
view quality.
☐ Glossary terms surfaced in the response (jargon flagged by
the LLM during render) are listed at the bottom of the page
with 1-line definitions; hover-tooltip render is deferred
to a follow-up spec.
☐ Pytest: mock LLM returns canned text; assert all 5
sections populated; assert PMIDs from the original
hypothesis are preserved verbatim in the rendered
evidence_md; assert cache key changes when hyp_version
changes.
☐ Human acceptance: pick the top-3 AD hypotheses; verify the
med_student and
patient views produce coherent prose
under 250 words per section.
Approach
Read scidex/agora/synthesis_engine.py for the LLM call
wrapper and JSON-parse helper.
Audience-view prompts are short and specific:
med_student — "explain the mechanism using analogies a USMLE
Step 1 student would recognize; preserve every PMID";
patient — "explain in everyday English at 8th-grade reading
level; do not promise treatments";
undergrad — "assume intro-bio knowledge".
Comprehension question generation is part of the same LLM
call (single prompt, structured JSON output).
PMID preservation is enforced post-generation: regex extract
PMIDs from input, reject the render if any are missing.
The cache lives in PostgreSQL (not Redis) for consistency
with the rest of the artifact pipeline.
Dependencies
scidex.core.llm.complete — LLM call.- Wave-1 hypothesis artifact schema.
Work Log