io.github.neptun2000/heor-agent

Build a structured epidemiology extraction table (country × prevalence × incidence × definition × year) from agent-extracted rows. Applies an explicit source-quality hierarchy (IHME GBD/WHO > national survey/registry > systematic review > single observational study) and Hoy et al. 2012 / JBI prevalence-study checklist scoring. Use after literature_search (with literature_search_plan) and screen_abstracts for descriptive epidemiology — replaces risk_of_bias for prevalence/incidence reviews. Pass one row per country/source; the tool ranks preferred estimates per country.

Author evidence claims once and reference them by ID across deliverables (dossiers, publications, payer materials). A claim is a single source-of-truth statement — an ICER, an effect estimate, a prevalence — persisted in the project knowledge base. Actions: 'upsert' (create/update a claim; id auto-derived from the statement if omitted), 'list', 'get', 'remove', and 'import' (auto-register claims from a tool result — pass import_from {source_tool, result} with the structured output of models.cost_effectiveness (→ ICER, incremental QALYs, incremental cost) or models.budget_impact (→ net budget impact); the registry self-populates instead of manual upserts). Each claim carries a numeric_value + value_display + unit + keywords (anchors used by evidence.consistency_check to locate it in prose) + citation + source_tool/run for provenance + status (draft/verified/superseded). Requires an existing project (project.create). Pairs with evidence.consistency_check (detect drift across documents) and publication.draft (reuse claims). Enum values case-insensitive.

Score neurology & cognitive outcome scales (UMSARS/UPDRS/MDS-UPDRS/ADAS-Cog/MoCA/MMSE). Returns total + subscale scores, MCID-based responder classification, and trajectory comparison vs NNIPPS/PPMI/ADNI reference cohorts. Integrates with jca_pico_scope for MSA (neurology_msa, orphan Phase 2 2028)/PD (neurology_pd)/AD (neurology_ad) indication categories.

Generate a clinician/patient interview guide (Pufulete Step 2/3) for the 'unmeasurable' confounders that literature cannot supply — patient treatment preference, tolerability expectation, etc. Pure template (no LLM, no network). Pass confounder_identification's expert_interview_required list as `unmeasurable_confounders`. Each confounder is probed against the two confounding criteria (associated with treatment AND outcome), measurability in available data, and proxy availability, plus DAG-elicitation prompts. Returns a ready-to-paste markdown checklist + structured survey_items.

IQWiG / Pufulete 2022 Step 1: systematically identify candidate CONFOUNDER variables for a non-randomised comparison, with full provenance. DETERMINISTIC — you (the agent) read each corpus paper and pass structured `candidate_extractions` (variable_name + source_paper_pmid/doi + source_location + verbatim_snippet); the tool enforces closed-corpus provenance (it NEVER cites a paper outside the corpus), verifies every source via Crossref/PubMed, dedupes, and proposes consolidation HINTS for human review. Emits an expert-interview block for confounders literature cannot supply (patient preference, tolerability). Output is always a DRAFT for human consolidation — never a complete list. Use this for IQWiG/G-BA confounder identification instead of generating confounder lists from memory.

Detect drift of evidence claims across deliverables (HTA dossier, publication, GVD/AMCP payer materials). Loads claims from the project registry (project_id) and/or takes inline claims, then scans each supplied deliverable's text and flags where a DIFFERENT number sits next to a claim's keywords (drift — e.g. an ICER you updated in the model but not in the dossier) or where a claim is absent. Returns a claim × deliverable matrix, the list of drifting claims, and per-finding detail. Keyword-anchored + numeric: it catches drifting numbers near claim keywords, not paraphrased claims — a 'consistent' result is necessary, not sufficient. Pairs with evidence.claim_registry. Pure detection over caller-supplied text.

Generate an integrated Evidence Generation Plan (iEGP). Assess the evidence base across HEOR domains (epidemiology, disease_burden, clinical_efficacy, comparative_effectiveness, safety, economic_cea, budget_impact, hrqol_utilities, adherence, unmet_need, patient_experience) — each with a status (robust/limited/absent/discordant) — and the tool returns the gaps, a recommended evidence-generation activity for each, the tool that operationalises it, the deliverable it unblocks, and a severity-prioritised plan (gaps on decision-critical domains for the chosen context escalate). Optionally fold in discordant_outcomes / single_source_outcomes from evidence.triangulation. Returns a readiness score (% of domains robust) and a prioritised plan to close the gaps. Use after an SLR/triangulation pass to decide what evidence to generate next, and to feed the iEGP deliverable. Pairs with rwe.method_select (how to fill a gap) and workflow.living_evidence (the end-to-end flow). Pure logic; enum values case-insensitive.

Compute indirect treatment comparisons using the Bucher method (single common comparator) or frequentist network meta-analysis (full network). Requires user-supplied effect sizes (point estimates + 95% CI) from published trials. Supports MD, OR, RR, HR. Auto-selects method by network structure. When direct head-to-head A-vs-C evidence is also in the network, automatically tests Bucher's consistency assumption (z = (direct − indirect) / SE_diff) per NICE DSU TSD 18 / Cochrane 11.4.3 — flags |z|≥1.96 as 'substantial inconsistency' so the agent can warn the user before relying on the indirect estimate.

Assess the feasibility of an indirect treatment comparison (ITC) by walking through the three core assumptions (exchangeability, homogeneity, consistency) and recommending an appropriate method: direct comparison, Bucher, full NMA, anchored MAIC/STC, unanchored MAIC/STC, ML-NMR, NMR/subgroup meta-regression, or infeasible. Cites Cope 2014 (BMC Med), NICE DSU TSD 18 (Phillippo), Signorovitch 2023 (J Dermatol Treatment), and Cochrane Handbook Ch 10-11. Use this BEFORE running evidence.indirect or evidence.population_adjusted to select the right method.

Analyze literature search results to build an evidence network map. Extracts intervention-comparator pairs from titles and abstracts, constructs a treatment comparison network, and assesses NMA (network meta-analysis) feasibility. Pass the results array from a prior literature.search call.

⚠️ EXPERIMENTAL / orientation-only. Approximate population-adjusted indirect comparison using summary-level statistics (mean, SD per covariate). True MAIC/STC per NICE DSU TSD 18 requires individual patient data (IPD) for one trial. This tool inflates the SE of a Bucher indirect comparison based on covariate imbalance (MAIC-style ESS penalty) and applies a simple linear adjustment based on standardized mean differences (STC-style). Point estimates should be interpreted as approximate — not submission-ready. For a definitive analysis, use IPD with an outcome regression model.

Assess risk of bias for a set of studies using the appropriate Cochrane instrument: RoB 2 (RCTs), ROBINS-I (observational studies), or AMSTAR-2 (systematic reviews/meta-analyses). Instrument is auto-detected from study_type or can be specified. Judgments are inferred from abstract text — domains without sufficient reporting are marked Unclear. Returns a per-study table and a rob_results object to pass to hta_dossier_prep for evidence-based GRADE assessment. Accepts `studies` as a single object OR an array; auto-wraps singletons. Enum values are case-insensitive — `"RoB2"`/`"rob2"`, `"AUTO"`/`"auto"` all work.

Fit parametric survival distributions (Exponential, Weibull, Log-logistic, Log-normal, Gompertz) to either patient-level event-time data (preferred — true right-censored MLE per Collett 2015 / NICE DSU TSD 14) OR Kaplan-Meier step-summary data (legacy approximation, used when only published KM digitization is available). Returns AIC/BIC model comparison and extrapolation table. Supply EXACTLY ONE of `event_data` (patient-level rows) or `km_data` (KM table).

Triangulate RCT vs real-world evidence per outcome. For each outcome supply what the randomised trials show (rct) and what real-world evidence shows (rwe) — each as a direction of benefit (favors: intervention/comparator/no_difference) plus an optional point estimate + measure. The tool classifies concordance (concordant / discordant / partial / single-source), and when both bodies give an estimate on the SAME measure, whether the real-world effect is LARGER (long-term use, broad heterogeneous populations) or SMALLER (efficacy–effectiveness gap) — sign-normalised by benefit_direction so 'larger' always means more benefit. Returns a per-outcome concordance table, a key message per outcome, an overall triangulation statement, and a concordance summary. Use to build the 'literature review of RCTs and RWE — key message per relevant outcome' section of a dossier, or to pressure-test whether RWE corroborates trial efficacy before a submission. RWE is treated as complementary to, not a substitute for, RCTs. Pure logic, no external calls; enum values case-insensitive.

Generate a structured unmet need section for HTA dossiers (NICE STA, EMA, FDA, IQWiG, HAS, JCA, GVD, AMCP). Consume-only: first retrieve evidence with literature_search, then pass only cited facts across 4 HEOR dimensions — disease burden, treatment landscape, QoL impact, economic burden. By default (auto_check_regulatory=true), automatically checks current regulatory status of comparators in treatment_landscape.current_soc via primary-source databases (OpenFDA/EMA EPI) and injects verbatim label quotes with auto-numbered citations. Degrades gracefully on API errors — never blocks dossier output. Set auto_check_regulatory:false to skip. Produces a standardised markdown section plus a 1-paragraph unmet_need_summary for downstream tools. Pipe unmet_need_summary into hta_dossier(unmet_need_summary:...) to pre-fill NICE Section B (unmet need) or GVD Section 4. Design log #23 + #26.

Get a pre-filled, copy-runnable JSON input for any of the heavy-schema tools (cost_effectiveness_model, budget_impact_model, survival_fitting, population_adjusted_comparison, evidence_indirect). Use when you want to demo a tool but don't want to invent inputs from scratch — the example is editable so you can tweak intervention names, costs, populations, etc. before calling the actual tool.

Score an AI-assisted HTA/HEOR workflow against 6 governance dimensions (transparency, citation validation, human-in-the-loop, PHI/data handling, bias & equity, auditability), each traced to the verified ELEVATE-GenAI reporting domains (ISPOR Working Group on Generative AI, Value in Health 2025). Two modes: 'describe' (free-text workflow_description + structured probes — a blank probe scores 'insufficient', never a pass) and 'audit_record' (pass a prior HEORAgent AuditRecord to auto-derive transparency/citation/auditability). Returns a Red/Amber/Green/Insufficient scorecard, a use_case-gated verdict ('any Red blocks submission-ready'), tailored mitigations, a pipeable governance_summary, and an ELEVATE disclosure block. Governance subset only — does not score ELEVATE's model-evaluation domains (robustness, calibration, deployment/efficiency). Design log #34.

Structure evidence into HTA body-specific submission format (NICE STA, EMA, FDA, IQWiG, HAS, EU JCA, or Global Value Dossier). Produces draft sections with gap analysis and auto-GRADE evidence quality tables. Accepts output from literature.search and models.cost_effectiveness. Enum values are case-insensitive — `"NICE"`/`"nice"`, `"STA"`/`"sta"` etc. all work.

Verifiable PPDD evidence engine for a German G-BA (AMNOG) benefit assessment. Produces a Peers / Precedent / Drift / Delta pack for a drug-class + indication where every fact is provenance-tagged: peers are asserted only from a curated, verified G-BA precedent knowledge base (or agent citations verified via verify_citations); anything unverifiable is reported as `unknown`, NEVER fabricated. Recomputes peer relevance under each candidate zVT (appropriate comparator) — the dominant AMNOG risk. Deterministic (no LLM). Feeds hta_review_simulation and the virtual G-BA panel. YOU (the agent) supply peer_drugs (class members) and candidate_facts with citations; the tool enforces provenance. Design log #49.

Maintain a Living Global Value Dossier as a diffable artifact, so a refresh regenerates only the sections whose figures changed instead of the whole GVD. Actions: 'snapshot' (record which registry claims each GVD section is built from — pass sections [{name, claim_ids}] — capturing each claim's current value as the baseline) and 'refresh' (diff the snapshot against the live claim registry and return the stale sections to regenerate, with old→new values per claim). Builds on evidence.claim_registry (the single source of truth) and pairs with workflow.living_evidence (which calls this on each living-evidence cycle). Diff is by value (0.5% tolerance / exact), and also flags sections whose claims were removed/superseded. Requires an existing project. This tool computes the diff and regeneration list; regeneration itself is done by hta.dossier. Enum values case-insensitive.

Virtual HTA institutional-panel simulator. hta_body='gba' (default): faithful G-BA §35a hearing (mundliche Anhoerung) roster - IQWiG/Biostatistician, G-BA/GKV-SV Assessor, KOL/Clinical Expert, Patient Representative. hta_body='nice': NICE EAG statistician/technical team/clinical expert/patient expert. hta_body='eu_jca': JCA assessor/co-assessor/member-state PICO scope (requires drug_class). hta_body='us_payer': payer medical director/pharmacoeconomist. Each seat thin-wraps an existing deterministic HEORAgent tool over ONE shared, citation-verified evidence pack (pass the output of hta.gba_ppdd as ppdd_pack for the gba body). Argues value/evidence/comparator scope/access - NEVER a clinical treatment recommendation (enforced by an MLR guard that rewrites any 'recommend/prefer/choose X over Y' phrasing). Re-runs comparator-sensitive seats under each candidate zVT (appropriate comparator) via zvt_scenarios. Optional question_set batch mode fans anticipated dossier questions across the relevant seats. Deterministic (no LLM). Every artefact carries a SYNTHETIC-simulation banner and requires human review before submission use. Design log #50.

Predict the clarification questions an HTA body will ask about a dossier, BEFORE submission. Consumes an hta.dossier / hta.workflow output (dossier_markdown), structured dossier_sections, or just {drug, indication, pico, model_results} for a pre-mortem. Runs a deterministic gap/risk scan over a 10-category taxonomy (comparator, indirect comparison, survival extrapolation, clinical risk-of-bias, economic-model structure, utilities, decision uncertainty, subgroups, real-world evidence, innovation/added-benefit) and returns ranked ANTICIPATED questions with rationale, severity (critical/standard/minor), what-the-committee-looks-for, and a suggested response. Precedent links are whitelist-only (verified NICE TA table) and never claim a question was historically asked. v1 bodies: NICE EAG and G-BA/IQWiG (FDA, HAS, EU JCA → v2). Fully deterministic; carries an ISPOR ELEVATE-GenAI disclosure block. Design log #38.

Look up EQ-5D value set characteristics (UK 3L, England 5L, new UK 5L 2026, NICE DSU mapping) or estimate the ICER/QALY impact of the new UK EQ-5D-5L value set for a given indication type. Cites Biz, Hernández Alava, Wailoo (2026) Value in Health. Use when user asks about NICE 5L transition, UK utility value sets, or impact on NICE STA submissions.

End-to-end HTA submission orchestrator. One call runs literature_search (with PRISMA-style stability via runs=N) → screen_abstracts (PICO filter) → risk_of_bias (auto RoB 2/ROBINS-I/AMSTAR-2) → cost_effectiveness_model (Markov + 1k PSA, defaults from indication) → hta_dossier (auto-GRADE downgrade from RoB output) → validate_links (post-hoc URL audit). Returns a combined report with per-phase timings, the full dossier draft, and the URL validation table. Use as a single-shot drop-in replacement for the 4-5 separate prompts a generic LLM would need to chain these tools manually. Each phase wrapped in safe-run so single-step failures do not abort the pipeline.

Score the readability of an Informed Consent Form (ICF) text. Returns Flesch-Kincaid Grade Level, Flesch Reading Ease, Gunning Fog Index, SMOG Grade, plus per-sentence breakdown identifying the worst offenders, medical-jargon detection with plain-language alternatives, and a pass/borderline/fail verdict vs a target grade level (default 8 per FDA / NIH guidance). Pairs with irb_review when planning a study — investigators paste the ICF draft, get back a concrete rewrite list. Pure logic, no external API.

Classify a planned study under 45 CFR 46 (US Common Rule) + EU CTR 536/2014 to produce an IRB / Ethics Committee submission scaffold. Returns: review tier (exempt §46.104 cat 1-8 / expedited §46.110 cat 1-7 / full-board §46.108), EU CTR review path with timeline, vulnerable-population obligations (Subpart B/C/D), GDPR Art. 9 + HIPAA §164.514 data-management plan, SAE-reporting framework (CTR Annex III / FDA IND / PSUR), ICF complexity tier, COI framework (PHS 42 CFR 50 / EU CTR Art. 14), and a ready-to-paste cover letter. v1 covers EU+US; UK/Japan/Canada planned for v2. Optional pv_classification input ties IRB review to the regulatory PV category — when primary_category is PASS_imposed, SAE timelines override to CTR Annex III. Enum values are case-insensitive — `"interventional"`/`"Interventional"`, `"us_irb"`/`"US_IRB"` etc. all work.

Produce the canonical EU Joint Clinical Assessment (JCA) PICO matrix for a drug-indication pair. Returns a consolidated PICO list (per JCA process under Reg. 2021/2282) plus country-specific comparator universes, outcome instrument preferences, population subgroup focus, and a heterogeneity warning. Pipe `pico_matrix.picos` directly into `hta_dossier({hta_body:"jca", picos: ...})`. v1 covers DE/FR/IT/ES/NL + UK (post-Brexit context). Heterogeneity warning fires at ≥3 distinct comparator molecules across ≥2 jurisdictions — a tool-level assumption, not a published EUnetHTA threshold; treat the warning as a prompt to run evidence_network + itc_feasibility, not as a definitive diagnosis. NSCLC EGFR-mutant comparator detail is currently modeled only for line_of_therapy="second_line"; other lines use a generic chemotherapy anchor with a warning. Enum values are case-insensitive — `"DE"`/`"de"`, `"first_line"`/`"First_Line"` etc. all work.

Read a file from a project's raw/ or wiki/ tree. Path is relative to project root. Only raw/ and wiki/ subtrees accessible.

Search a project's knowledge base (raw/ and wiki/) for text matches. Returns file paths with line numbers and snippets. Use this to find previously-retrieved literature, model runs, and compiled wiki content without re-querying external APIs.

Write a file to the project's wiki/ tree. Path MUST start with 'wiki/' and end with '.md'. Use this to compile/organize evidence from raw/ files into a structured knowledge base. Supports Obsidian-style [[wikilinks]].

Retrieve FULL TEXT (Methods/Results sections + baseline/results tables) for already-identified articles by PMID, PMCID, or DOI, from Europe PMC (PMC open-access subset + author manuscripts + preprints). License-gated: non-open-access articles return NO body text (full_text_available:false) — only a pointer. Use AFTER literature_search/screen_abstracts to read the methods text that abstracts omit — e.g. for confounder_identification (baseline-characteristics tables), risk_of_bias (randomization/blinding text), or survival/ITC data extraction. Deterministic fetch (no LLM); you read the returned sections. Pass up to 20 articles.

Protocol-locked LIVING systematic literature review with delta refresh. Stateless: the tool never stores anything — the caller persists state. Two modes: 'init' locks a protocol, runs a baseline literature.search, and returns the baseline records for you to persist; 'refresh' takes the protocol + your previous_records, re-runs the search, and returns the delta (new/dropped records, a deterministic material-change flag, recommended downstream re-runs, and the next-refresh date). Material change fires on: a new RCT, ≥ threshold new records, or a conference late-breaker. Cadence (monthly/quarterly/half_yearly/annual/conference_adhoc) is a recommendation surfaced to your scheduler (e.g. Vercel Cron) — there is no in-server timer. Pipe a material refresh into evidence_network / itc_feasibility. Design log #39.

Screen literature search results using PICO criteria. Scores each abstract by relevance to the research question, classifies study design, and returns a ranked shortlist with inclusion/exclusion decisions and reasons. For descriptive epidemiology omit intervention/comparator and pass population + condition + outcomes. Pass the results array from a prior literature.search call (use output_format='json'). Follows Cochrane Handbook Chapter 4 screening methodology.

Search PubMed, ClinicalTrials.gov, bioRxiv/medRxiv, ChEMBL, FDA Orange Book, FDA Purple Book, enterprise sources (Embase, ScienceDirect, Cochrane, Citeline, Pharmapendium, Cortellis), HTA cost reference sources (CMS NADAC, PSSRU, NHS National Cost Collection, BNF, PBS Schedule), LATAM sources (DATASUS, CONITEC, ANVISA, PAHO, IETS, FONASA), APAC sources (HITAP), and HTA appraisal/guidance sources (NICE TAs, CADTH CDR/pCODR, ICER, PBAC PSDs, G-BA AMNOG, HAS Transparency Committee, IQWiG, AIFA, TLV Sweden, INESSS Quebec) for evidence on a drug or indication. Returns structured results including HTA precedents and appraisal decisions with a full audit trail suitable for HTA submissions.

Estimate the total budget impact of adopting a new intervention over 1-5 years. Follows ISPOR Budget Impact Analysis good practice guidelines (Mauskopf 2007, Sullivan 2014). Computes year-by-year net cost to payer, including market share uptake, treatment displacement, and population growth. IMPORTANT: drug_cost_annual and comparator_cost_annual are required numeric inputs. If the user has not provided them, use your training knowledge of published list prices (NHS BNF/Drug Tariff for nhs perspective, WAC/AWP for us_payer) or the most recent NICE appraisal cost inputs as your best estimate — do NOT refuse to run the model. Flag any self-sourced prices in the output as 'estimated from published list price' and state the source.

Build a cost-utility analysis (ICER, QALY, PSA, sensitivity analysis) for a drug vs comparator. Follows ISPOR good practice guidelines and NICE reference case. Includes probabilistic sensitivity analysis (PSA), one-way sensitivity, and cost-effectiveness acceptability curve (CEAC). NOTE: utility inputs are value-set-dependent — UK submissions in 2026+ will transition from DSU 3L→5L mapping to the new UK EQ-5D-5L value set (NICE consultation 2026-04-15 to 2026-05-13). Use utility_value_set tool to check expected impact on ICER before finalising inputs.

Initialize a new HEOR project workspace with directory skeleton and project.yaml metadata. Idempotent — returns existing project if already created. Required before using the `project` parameter in other tools. Enum values are case-insensitive — `"NICE"`, `"Nice"`, and `"nice"` all work for hta_targets.

Draft a publication — abstract, manuscript, poster, or plain-language summary — that reuses claims from the project registry so the same source-of-truth figures appear in the publication as in the dossier. Structures the content per type (structured abstract / IMRaD manuscript / poster / lay summary), auto-selects the reporting guideline for the study_design (CONSORT for RCTs, STROBE for observational, PRISMA for systematic reviews, CHEERS for economic evaluations), enforces a word limit (default per type, overridable), and emits a GPP2022 + ICMJE compliance checklist (authorship criteria, disclosures, funding, trial registration, data-sharing). Pass reference_claim_ids + project_id to pull registered claims into the Results. Flags over-limit drafts, unregistered RCTs, and superseded claims; notes that AI cannot be an author (ICMJE). Pairs with evidence.claim_registry + evidence.consistency_check. Enum values case-insensitive.

Classify a planned study into its EMA pharmacovigilance regulatory category (PASS imposed/voluntary, PAES, RMP Annex 4, DUS, active surveillance registry, pregnancy registry, spontaneous reporting, ICH E2E plan). Returns the matching GVP module + ENCePP study-category label (not a registered protocol ID — consult the ENCePP Code of Conduct checklist for templates) + submission obligations + RMP implications + FDA analogue. Use BEFORE preparing an HTA dossier or before designing a post-authorisation study. Pass the structured `pv_classification` output to `hta_dossier` to populate its Pharmacovigilance Plan section. Enum values are case-insensitive — `"RCT"`/`"rct"`, `"EU"`/`"eu"` etc. all work.

Build a class-level comparative safety profile from spontaneous-report data (FAERS / EudraVigilance / VigiBase / WHO VigiBase). Ranks the top-N adverse events for each product in a drug class by reporting rate per 1,000 exposed (supply exposed_population per product) or by raw report count, lays the products side-by-side in a class-comparison matrix, and emits key observations — shared class profile, product-level differentiators, and explicit call-outs for events_of_interest (e.g. report that 'cardiovascular' did not rank in the top 10 for any product). Optionally layers in disproportionality (PRR/ROR/IC/EBGM) per drug-AE pair when you supply grand_total + per-product total_reports + per-AE event_total. Complements pv.signal_workflow (which scores one drug × one AE). ⚠️ Spontaneous-report rates reflect reporting behaviour, not incidence — output is a comparative reporting profile, hypothesis-generating only. Pure logic, no external calls.