// Mirrors backend/app/schemas.py by hand — keep these two files in sync. export type ReviewStatus = "draft" | "locked"; export type ReviewType = | "systematic-review" | "literature-review" | "qualitative-review" | "rapid-review" | "meta-analysis"; export type ReviewDomain = | "hepatotoxicity" | "nephrotoxicity" | "neurotoxicity" | "cardiotoxicity" | "genotoxicity" | "carcinogenicity" | "reproductive-developmental-toxicity" | "endocrine-disruption" | "immunotoxicity" | "respiratory-toxicity" | "dermal-toxicity" | "ecotoxicity"; export interface ReviewOption { value: T; label: string; } export interface ReviewOptions { review_types: ReviewOption[]; review_domains: ReviewOption[]; } export type LiteratureSource = | "pubmed" | "europe_pmc" | "ntp" | "iarc" | "openalex" | "scopus" | "wos" | "embase" | "epa_iris" | "echa" | "efsa" | "atsdr"; export const ALL_SOURCES: { value: LiteratureSource; label: string }[] = [ { value: "pubmed", label: "PubMed" }, { value: "europe_pmc", label: "Europe PMC" }, { value: "openalex", label: "OpenAlex" }, { value: "scopus", label: "Scopus (needs API key)" }, { value: "wos", label: "Web of Science (needs API key)" }, { value: "embase", label: "Embase (search by hand)" }, { value: "epa_iris", label: "EPA IRIS (search by hand)" }, { value: "echa", label: "ECHA (search by hand)" }, { value: "efsa", label: "EFSA (search by hand)" }, { value: "atsdr", label: "ATSDR (search by hand)" }, { value: "ntp", label: "NTP" }, { value: "iarc", label: "IARC" }, ]; export interface ProtocolDraft { title: string; review_type: ReviewType | null; review_domain: ReviewDomain[]; population: string; intervention: string; comparator: string | null; outcome: string; inclusion_criteria: string[]; exclusion_criteria: string[]; /** Exposure synonyms, OR-ed. Empty → falls back to the Intervention text. */ intervention_terms: string[]; /** Outcome synonyms, OR-ed. Empty → falls back to the Outcome text. */ outcome_terms: string[]; sources: LiteratureSource[]; /** 1 = single reviewer; 2 = two independent, blinded reviewers per record. */ reviewers_required: 1 | 2; /** OHAT key questions deciding the tier — observational designs. */ rob_key_questions_observational: number[]; /** OHAT key questions deciding the tier — animal studies and human trials. */ rob_key_questions_experimental: number[]; /** Review-specific risk-of-bias criteria (confounders, exposure, outcome). */ rob_criteria: string | null; } export interface FieldChange { field: string; before: unknown; after: unknown; } export interface ProtocolAmendment { /** Protocol version this amendment produced (the locked original is 1). */ version: number; amended_at: string; reason: string; changes: FieldChange[]; } export interface Protocol extends ProtocolDraft { id: string; status: ReviewStatus; created_at: string; locked_at: string | null; version: number; amendments: ProtocolAmendment[]; } // --- Phase 2: Comprehensive search --- export type SourceAvailability = "searched" | "unavailable_no_api" | "manual"; export type QueryMode = "search_terms" | "legacy_free_text"; export interface SourceCount { source: LiteratureSource; availability: SourceAvailability; identified_count: number; /** Records actually downloaded; null for searches run before this was recorded. */ retrieved_count: number | null; /** Exact query string sent to this source. */ query: string | null; note: string | null; searched_on?: string | null; } export interface SearchResultItem { id: string; title: string; authors: string; journal: string | null; year: string | null; doi: string | null; url: string; abstract: string | null; found_in: LiteratureSource[]; } /** An earlier search run, kept for reporting (PRISMA-S). */ export interface SearchRunSummary { id: string; run_number: number; executed_at: string; query: string; query_mode: QueryMode; protocol_version: number | null; rerun_reason: string | null; source_counts: SourceCount[]; /** Records after deduplication. */ record_count: number; } export interface SearchRun { id: string; protocol_id: string; executed_at: string; /** Human-readable search strategy. */ query: string; query_mode: QueryMode; source_counts: SourceCount[]; results: SearchResultItem[]; run_number: number; protocol_version: number | null; rerun_reason: string | null; previous_runs: SearchRunSummary[]; } // --- Phase 3: Screening + extraction --- export type ScreeningStage = "title_abstract" | "full_text"; export type ScreeningDecisionValue = "include" | "exclude"; /** "review" = a reviewer's own decision; "adjudication" = resolution of a conflict. */ export type ScreeningRole = "review" | "adjudication"; export interface ScreeningRecordCreate { paper_id: string; stage: ScreeningStage; decision: ScreeningDecisionValue; reviewer: string; reason: string | null; /** The listed exclusion reason chosen (or "Other"); counted in PRISMA. */ reason_category?: string | null; role?: ScreeningRole; /** Justification — required when resolving a conflict. */ note?: string | null; } export interface ScreeningRecordEntry extends ScreeningRecordCreate { id: string; protocol_id: string; decided_at: string; } export interface ExtractionRecordCreate { paper_id: string; species: string | null; route: string | null; duration: string | null; noael: string | null; loael: string | null; effect_finding: string | null; notes: string | null; extracted_by: string; /** Outcome-based extraction (OHAT confidence rating). */ outcome?: string | null; evidence_stream?: EvidenceStream | null; direction?: EffectDirection | null; controlled_exposure?: boolean | null; exposure_prior_to_outcome?: boolean | null; individual_outcome_data?: boolean | null; comparison_group?: boolean | null; klimisch_score?: 1 | 2 | 3 | 4 | null; klimisch_justification?: string | null; guideline_followed?: string | null; glp_compliant?: boolean | null; substance_identity_reported?: boolean | null; controls_reported?: boolean | null; doses_group_sizes_reported?: boolean | null; methods_source?: "full_text" | "abstract_only" | null; } export interface ExtractionRecordEntry extends ExtractionRecordCreate { id: string; protocol_id: string; extracted_at: string; } // --- Phase 4: PRISMA flow + synthesis --- export interface ReasonCount { reason: string; count: number; } export interface AgreementStat { stage: ScreeningStage; reviewer_a: string; reviewer_b: string; records_compared: number; percent_agreement: number; /** null when undefined (every decision identical). */ kappa: number | null; } export interface PrismaCounts { identified: number; /** null when the search run predates retrieval recording. */ retrieved: number | null; not_retrieved: number | null; duplicates_removed: number | null; after_dedup: number; /** Records with a current title/abstract decision. */ screened: number; awaiting_screening: number; excluded_title_abstract: number; sought_for_retrieval: number; awaiting_full_text: number; excluded_full_text: number; included: number; excluded_title_abstract_reasons: ReasonCount[]; excluded_full_text_reasons: ReasonCount[]; reviewers_required: number; awaiting_second_title_abstract: number; conflicts_title_abstract: number; awaiting_second_full_text: number; conflicts_full_text: number; agreement: AgreementStat[]; } export interface SynthesisResult { id: string; protocol_id: string; generated_at: string; text: string; } // --- Risk of bias (OHAT) --- export type StudyDesign = | "experimental_animal" | "human_controlled_trial" | "cohort" | "case_control" | "cross_sectional" | "case_series"; export type RobRating = "definitely_low" | "probably_low" | "probably_high" | "not_reported" | "definitely_high"; export interface RobQuestion { number: number; bias_type: string; label: string; text: string; applies_to: StudyDesign[]; } export interface RobReference { questions: RobQuestion[]; designs: { value: StudyDesign; label: string; experimental: boolean }[]; ratings: { value: RobRating; symbol: string; label: string; help: string }[]; default_key_questions_observational: number[]; default_key_questions_experimental: number[]; confidence: ConfidenceReference; } export interface RobAnswer { question: number; rating: RobRating; justification: string; } export interface RobAssessmentCreate { paper_id: string; outcome: string; study_design: StudyDesign; answers: RobAnswer[]; reviewer: string; role?: ScreeningRole; note?: string | null; } export interface RobAssessmentEntry extends RobAssessmentCreate { id: string; protocol_id: string; assessed_at: string; } export interface RobSummaryItem { paper_id: string; outcome: string; state: "single" | "pending" | "awaiting_second" | "agreed" | "conflict" | "adjudicated"; reviewers: string[]; final: RobAssessmentEntry | null; tier: number | null; key_questions: number[]; /** Question numbers rated differently; 0 = study design differs. */ conflicting_questions: number[]; } // --- Confidence in the body of evidence (OHAT Steps 5–6) --- export type ConfidenceLevel = "very_low" | "low" | "moderate" | "high"; export type EvidenceStream = "human" | "animal" | "in_vitro"; export type EffectDirection = "increased" | "decreased" | "no_association"; export type LevelOfEvidence = "high" | "moderate" | "low" | "no_health_effect" | "inadequate"; export type StudyFeatureKey = | "controlled_exposure" | "exposure_prior_to_outcome" | "individual_outcome_data" | "comparison_group"; export interface ConfidenceReference { levels: { value: ConfidenceLevel; label: string; help: string }[]; features: { key: StudyFeatureKey; label: string }[]; factors: { key: string; direction: "down" | "up"; label: string; help: string }[]; streams: { value: EvidenceStream; label: string }[]; directions: { value: EffectDirection; label: string }[]; levels_of_evidence: { value: LevelOfEvidence; label: string; help: string }[]; } export interface FactorAdjustment { factor: string; /** -2..0 for downgrade factors, 0..+2 for upgrade factors. */ change: number; justification: string; } export interface ConfidenceRatingCreate { outcome: string; evidence_stream: EvidenceStream; initial_confidence: ConfidenceLevel; initial_justification: string; factors: FactorAdjustment[]; direction: EffectDirection; rated_by: string; } export interface ConfidenceRatingEntry extends ConfidenceRatingCreate { id: string; protocol_id: string; rated_at: string; final_confidence: ConfidenceLevel; level_of_evidence: LevelOfEvidence; } export interface ConfidenceStudy { paper_id: string; feature_count: number | null; initial_confidence: ConfidenceLevel | null; rob_tier: number | null; direction: EffectDirection | null; effect_finding: string | null; } export interface ConfidenceGroup { outcome: string; evidence_stream: EvidenceStream | null; studies: ConfidenceStudy[]; suggested_initial_confidence: ConfidenceLevel | null; current: ConfidenceRatingEntry | null; history_count: number; } // --- AI-assisted screening ranking --- export interface RankedItem { paper_id: string; rank: number; /** 0-100; higher = more likely relevant. */ score: number; matched_terms: string[]; has_abstract: boolean; /** True when the record already has a title/abstract decision. */ screened: boolean; } export interface RankingResult { protocol_id: string; search_run_id: string; generated_at: string; mode: "protocol_only" | "protocol_and_decisions"; relevant_used: number; not_relevant_used: number; screening_entries_seen: number; validation_included: number; validation_in_top_fifth: number; method_note: string; items: RankedItem[]; } // --- Import of exported records --- export interface ImportPreview { format: string; parsed: number; skipped_no_title: number; with_abstract: number; with_doi: number; duplicates_within_file: number; already_in_tool: number; new_records: number; sample_titles: string[]; applied: boolean; run: SearchRun | null; }