@inflexa-ai/harness 0.1.1

package/dist/workflows/target-assessment/assemblers/safety.d.ts

@@ -0,0 +1,352 @@
+/**
+ * Phase-4 deterministic assemblers — safety sections.
+ *
+ * Each assembler maps Phase-1 / Phase-2 / Phase-3 outputs onto the
+ * corresponding dossier section schema. Coverage is honored end-to-end:
+ * when an upstream came back `queried_no_data` or the derived row set is
+ * empty, the section is marked `queried_no_data` / `not_loaded` rather
+ * than fabricated. Aggregate rows preserve their contributing evidence
+ * under `evidence: [...]` arrays.
+ */
+import type { EvidenceItem, RegulatoryActionRow } from "@inflexa-ai/harness/contracts/target-dossier.js";
+import type { Phase2Bundle } from "../steps/phase2-aggregate.js";
+import type { Phase3Bundle } from "../steps/phase3-aggregate.js";
+import type { FamilyComplexesBundle } from "../schemas.js";
+import { type CanonicalOrgan } from "../lib/meddra-organ-map.js";
+import { HIGH_EXPRESSION_TPM_THRESHOLD } from "../lib/expression-constants.js";
+export { HIGH_EXPRESSION_TPM_THRESHOLD };
+import type { ChemblModulator } from "../../../tools/lib/chembl-client.js";
+export declare const SAFETY_RELEVANT_ORGANS: Set<string>;
+export declare function isSafetyRelevant(tissue: string, organ?: string | null): boolean;
+export declare const REPRODUCTIVE_TOX_TISSUES: Set<string>;
+export declare const REPRODUCTIVE_TOX_TPM_FLOOR = 20;
+export declare const DEFAULT_TPM_FLOOR = 100;
+export declare function meetsTpmFloor(tissue: string, value: number): boolean;
+export declare function assembleLiabilitySummary(phase2: Phase2Bundle, context: {
+    offTargetRows: OffTargetPanelRows | null;
+    preferredModality: string | null;
+}): {
+    liability_bullets: never[];
+    modality_recommendation: string | null;
+    same_class_drug_count: number;
+    inferred_therapeutic_area: string | null;
+    no_liabilities_disclosure: string;
+};
+type FanoutResults = Phase3Bundle["fanout"];
+export declare function aggregateFaersAcrossModulators(fanout: FanoutResults | undefined): {
+    total_reports: number;
+    seriousness: {
+        coverage: "available";
+        total_reports: number;
+        by_seriousness: {
+            death: number;
+            life_threatening: number;
+            hospitalization: number;
+            disabling: number;
+            other_serious: number;
+            congenital_anomaly: number;
+        };
+        fatal_report_count: number;
+    } | {
+        coverage: "queried_no_data";
+        total_reports: number;
+        by_seriousness?: undefined;
+        fatal_report_count?: undefined;
+    };
+    top_signals: {
+        meddra_term: string;
+        organ: CanonicalOrgan | undefined;
+        report_count: number;
+    }[];
+    per_modulator: {
+        modulator: string;
+        modulator_id: string | null;
+        report_count: number;
+        coverage: "available" | "queried_no_data" | "not_loaded";
+    }[];
+} | null;
+export declare function aggregateTrialAes(fanout: FanoutResults | undefined): {
+    serious: {
+        term: string;
+        incidence_pct: number;
+        organ?: string;
+        nct_ids: string[];
+    }[];
+    non_serious: {
+        term: string;
+        incidence_pct: number;
+        organ?: string;
+        nct_ids: string[];
+    }[];
+    non_serious_floor_pct: number;
+    dropped_uninformative_count: number;
+    coverage_qualifier: {
+        trials_queried: number;
+        trials_with_ae_data: number;
+        serious_floor_applied: number;
+        non_serious_floor_pct_applied: number;
+    };
+} | null;
+/** Fold below this threshold → selectivity window is insufficient. */
+export declare const SELECTIVITY_FOLD_THRESHOLD = 30;
+export type RawOffTargetRow = {
+    off_target_id?: string | null;
+    off_target_name?: string | null;
+    target_chembl_id?: string | null;
+    target_type?: string | null;
+    accession?: string | null;
+    pchembl: number;
+    selectivity: {
+        fold: number;
+        log_units: number;
+    };
+    selectivity_window_below_threshold?: boolean;
+    evidence?: EvidenceItem[];
+    organ_system?: string | null;
+    target_class?: string | undefined;
+    is_safety_panel_target?: boolean;
+    clinical_consequence?: string | null;
+    metadata?: {
+        merged_chembl_ids?: string[];
+    };
+};
+export type CleanOffTargetRow = Omit<RawOffTargetRow, "target_chembl_id" | "target_type" | "accession" | "off_target_id" | "organ_system" | "evidence"> & {
+    off_target_id: string | null;
+    off_target_name: string;
+    organ_system: string | null;
+    evidence: EvidenceItem[];
+    selectivity_window_below_threshold: boolean;
+    clinical_consequence: string | null;
+    is_safety_panel_target: boolean;
+    metadata: {
+        merged_chembl_ids: string[];
+    };
+};
+/**
+ * V4 off-target row shape after relationship classification. Used by the
+ * organ-rollup builder, evidence tally, and liability-summary signal count —
+ * the typed members all rely on `relationship`, `organ_system`, `pchembl`,
+ * `evidence`, and `is_safety_panel_target` only.
+ */
+export type OffTargetPanelRows = Array<{
+    off_target_id: string | null;
+    off_target_name: string;
+    pchembl: number;
+    is_safety_panel_target: boolean;
+    organ_system: string | null;
+    evidence: EvidenceItem[];
+    relationship: "off_target";
+}>;
+/**
+ * Filter and deduplicate raw off-target rows before panel assembly.
+ *
+ * Removes: on-target self-rows, cell-line entries, sentinel/unresolved names.
+ * Deduplicates: by UniProt accession when present, otherwise by normalized name;
+ *   keeps the highest-pchembl row as the winner and records merged ChEMBL ids.
+ * Computes: `selectivity_window_below_threshold`, `clinical_consequence`,
+ *   `is_safety_panel_target` (via the existing safety-panel lookup).
+ */
+export declare function filterAndDedupOffTargetRows(rows: RawOffTargetRow[], ctx: {
+    assessmentTargetChemblId: string | null;
+}): CleanOffTargetRow[];
+/**
+ * V4 off-target panel row split. Each clean off-target row is classified as:
+ *   - `on_target_self_hit`: alternate ChEMBL ID for the assessment target itself
+ *   - `intended_co_target`: every modulator that hits this target intends it
+ *     (e.g., GLP1R + GIPR for tirzepatide); not an off-target liability
+ *   - `off_target`: real off-target — selectivity computed vs primary potency
+ */
+export declare function aggregateOffTargetPanel(phase2: Phase2Bundle, fanout: FanoutResults | undefined, assessmentUniprot: string, assessmentGeneSymbol?: string, familyComplexes?: FamilyComplexesBundle | null, onTargetChemblIds?: string[]): {
+    rows: {
+        off_target_id: string | null;
+        off_target_name: string;
+        pchembl: number;
+        is_safety_panel_target: boolean;
+        organ_system: string | null;
+        clinical_consequence: string | null;
+        selectivity: {
+            vs_primary_potency: {
+                primary_pchembl_used: number;
+                primary_source: "chembl_target_drug_indication" | "literature_curated";
+                fold: number;
+                log_units: number;
+            };
+        } | {
+            selectivity_unknown: true;
+            reason: string;
+        };
+        selectivity_window_below_threshold: boolean;
+        evidence: {
+            source: string;
+            pmid?: string | undefined;
+            doi?: string | undefined;
+            predicate?: string | undefined;
+            score?: number | undefined;
+            strength?: string | undefined;
+            is_human?: boolean | undefined;
+            is_clinical?: boolean | undefined;
+            excerpt?: string | undefined;
+            metadata?: Record<string, unknown> | undefined;
+            regulatory_reference?: {
+                document: string;
+                section?: string | undefined;
+                doc_id?: string | undefined;
+                doc_url?: string | undefined;
+            } | undefined;
+        }[];
+        relationship: "off_target";
+        target_class?: string | undefined;
+        metadata?: {
+            merged_chembl_ids?: string[] | undefined;
+        } | undefined;
+    }[];
+    excluded_rows: {
+        off_target_id: string | null;
+        off_target_name: string;
+        pchembl: number;
+        is_safety_panel_target: boolean;
+        organ_system: string | null;
+        clinical_consequence: string | null;
+        selectivity: {
+            vs_primary_potency: {
+                primary_pchembl_used: number;
+                primary_source: "chembl_target_drug_indication" | "literature_curated";
+                fold: number;
+                log_units: number;
+            };
+        } | {
+            selectivity_unknown: true;
+            reason: string;
+        };
+        selectivity_window_below_threshold: boolean;
+        evidence: {
+            source: string;
+            pmid?: string | undefined;
+            doi?: string | undefined;
+            predicate?: string | undefined;
+            score?: number | undefined;
+            strength?: string | undefined;
+            is_human?: boolean | undefined;
+            is_clinical?: boolean | undefined;
+            excerpt?: string | undefined;
+            metadata?: Record<string, unknown> | undefined;
+            regulatory_reference?: {
+                document: string;
+                section?: string | undefined;
+                doc_id?: string | undefined;
+                doc_url?: string | undefined;
+            } | undefined;
+        }[];
+        relationship: "intended_co_target" | "on_target_self_hit" | "obligate_cofactor";
+        reason: string;
+        target_class?: string | undefined;
+        metadata?: {
+            merged_chembl_ids?: string[] | undefined;
+        } | undefined;
+    }[];
+} | null;
+/** Minimum distinct active substances required for class-liability designation. */
+export declare const CLASS_MIN_DRUGS = 3;
+export declare const CLASS_LIABILITY_FRACTION = 0.3;
+export type ClassDrug = {
+    drug_id: string;
+    parent_chembl_id: string | null;
+    drug_name: string;
+    max_phase: number;
+};
+/**
+ * Deduplicates a list of drugs by active substance (parent_chembl_id, falling
+ * back to drug_id when parent is absent), then derives the count and suppression
+ * reason used consistently across drugs_in_class and per_organ rollups.
+ *
+ * Dedup winner per group: highest max_phase; ties broken by drug_id lexicographic
+ * order so the result is deterministic.
+ */
+export declare function computeClassPrecedentCounts(drugs: ClassDrug[]): {
+    drug_count_in_class: number;
+    drugs_in_class: ClassDrug[];
+    suppressed_reason: string | null;
+};
+export declare function aggregateClassPrecedent(phase2: Phase2Bundle, fanout: FanoutResults | undefined): {
+    drugs_in_class: ClassDrug[];
+    per_organ: {
+        organ: CanonicalOrgan;
+        drug_count_in_class: number;
+        drugs_with_signal: number;
+        signal_fraction: number;
+        is_class_liability: boolean;
+        suppressed_reason: string | null;
+        top_aes: {
+            term: string;
+            report_count: number;
+        }[];
+    }[];
+} | null;
+export declare function buildOrganRollup(faers: ReturnType<typeof aggregateFaersAcrossModulators>, trialAes: ReturnType<typeof aggregateTrialAes>, offTarget: OffTargetPanelRows | null, classP: ReturnType<typeof aggregateClassPrecedent>, regulatoryActions?: RegulatoryActionRow[] | null): {
+    organ: CanonicalOrgan;
+    risk_level: "high" | "medium" | "low";
+    signal_type_count: number;
+    signals: {
+        chembl_polypharm_count: number;
+        faers_count: number;
+        trial_ae_count: number;
+        class_liability_present: boolean;
+    };
+    evidence: {
+        source: string;
+        pmid?: string | undefined;
+        doi?: string | undefined;
+        predicate?: string | undefined;
+        score?: number | undefined;
+        strength?: string | undefined;
+        is_human?: boolean | undefined;
+        is_clinical?: boolean | undefined;
+        excerpt?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+        regulatory_reference?: {
+            document: string;
+            section?: string | undefined;
+            doc_id?: string | undefined;
+            doc_url?: string | undefined;
+        } | undefined;
+    }[];
+}[] | null;
+/**
+ * Testable wrapper around `buildOrganRollup` that accepts named parameters.
+ * Exported for unit tests; production code calls `buildOrganRollup` directly
+ * inside `assembleDossier`.
+ */
+export declare function assembleOrganRollupRows(opts: {
+    classPrecedent?: ReturnType<typeof aggregateClassPrecedent> | null;
+    regulatoryActions?: {
+        coverage: string;
+        data?: {
+            rows: RegulatoryActionRow[];
+        };
+    } | null;
+}): ReturnType<typeof buildOrganRollup> extends null ? never[] : NonNullable<ReturnType<typeof buildOrganRollup>>;
+export declare function assembleDrugInteractions(phase2: Phase2Bundle, enrichedModulators?: ChemblModulator[]): {
+    drug_id: string;
+    drug_name: string;
+    best_score: number;
+    predicates: string[];
+    sources: string[];
+    paper_count: number;
+    dominant_direction: "unknown";
+    has_human_evidence: boolean;
+    has_clinical_evidence: boolean;
+    evidence: {
+        source: string;
+        predicate: string;
+        score: number;
+        is_clinical: boolean;
+        is_human: boolean;
+        metadata: {
+            chembl_id: string;
+            max_phase: number;
+            molecule_type: string | null;
+            first_approval: number | null;
+            triage_rationale: string | undefined;
+        };
+    }[];
+}[] | null;