@inflexa-ai/harness 0.1.1

package/dist/tools/lib/api-utils.js

@@ -0,0 +1,128 @@
+/**
+ * Shared HTTP fetch helper for bioinformatics API tools.
+ *
+ * Provides retry-with-backoff for rate-limited APIs (429/503), request
+ * timeouts, and tab-delimited text parsing. `apiFetch` is the external-call
+ * boundary, so it is where a throw becomes a `Result`: it returns a
+ * `ResultAsync<T, ApiError>` rather than throwing — callers branch on
+ * `isErr()` and read `value` / `error` (see `result.ts` for the house rules).
+ */
+import { ResultAsync, err, ok } from "neverthrow";
+import { sleep } from "../../lib/async-utils.js";
+const RETRYABLE_STATUSES = new Set([429, 503]);
+/**
+ * Fetch a URL with retry on 429/503, exponential backoff, and timeout.
+ * `err` carries the structured failure; a non-ok HTTP status is reported as
+ * `http_status` so callers can branch on a concrete code (a 404 is usually an
+ * expected "not found" → a data variant; see `isUnexpectedApiError`).
+ */
+export function apiFetch(url, options = {}) {
+    return new ResultAsync(runFetch(url, options));
+}
+/**
+ * `apiFetch` that validates the JSON response against a Zod `schema` before
+ * returning it. The success value is the schema's parsed output, so callers
+ * receive a payload whose shape has been checked rather than an unchecked
+ * `apiFetch<T>` cast that trusts the wire.
+ *
+ * A response the schema rejects — the upstream API changed its contract, or
+ * returned an error envelope where data was expected — resolves to an
+ * `invalid_response` err. That is deliberately an *unexpected* `ApiError`
+ * (`isUnexpectedApiError` returns true for it): a contract break should
+ * surface, not silently become empty/garbage results downstream. To keep a
+ * tool's graceful degradation, model genuinely-optional fields as
+ * `.optional()`/`.nullable()` in the schema so a partial-but-valid response
+ * still parses; reserve rejection for real type/shape drift.
+ *
+ * JSON only — `parseAs` is forced to `"json"`, since a schema over raw text is
+ * just `z.string()`, which `apiFetch<string>` already covers.
+ */
+export function apiFetchValidated(url, schema, options = {}) {
+    return apiFetch(url, { ...options, parseAs: "json" }).andThen((data) => {
+        const parsed = schema.safeParse(data);
+        if (parsed.success)
+            return ok(parsed.data);
+        return err({ type: "invalid_response", issues: summarizeZodIssues(parsed.error) });
+    });
+}
+/** Compact one-line rendering of a Zod validation failure (first few issues). */
+function summarizeZodIssues(error) {
+    const issues = error.issues.slice(0, 5).map((issue) => {
+        const path = issue.path.map((segment) => String(segment)).join(".");
+        return path ? `${path}: ${issue.message}` : issue.message;
+    });
+    const remaining = error.issues.length - issues.length;
+    return remaining > 0 ? `${issues.join("; ")} (+${remaining} more)` : issues.join("; ");
+}
+async function runFetch(url, options) {
+    const { method = "GET", headers = {}, body, maxRetries = 3, retryDelayMs = 1000, timeoutMs = 90_000, parseAs = "json" } = options;
+    let lastError = "";
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            const res = await fetch(url, {
+                method,
+                headers,
+                body,
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (RETRYABLE_STATUSES.has(res.status) && attempt < maxRetries) {
+                await sleep(retryDelayMs * 2 ** attempt);
+                lastError = `HTTP ${res.status}`;
+                continue;
+            }
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                return err({ type: "http_status", status: res.status, body: text.trim() });
+            }
+            const data = parseAs === "text" ? (await res.text()) : (await res.json());
+            return ok(data);
+        }
+        catch (e) {
+            if (e instanceof DOMException && e.name === "TimeoutError") {
+                return err({ type: "timeout", timeoutMs });
+            }
+            lastError = e instanceof Error ? e.message : String(e);
+            if (attempt < maxRetries) {
+                await sleep(retryDelayMs * 2 ** attempt);
+                continue;
+            }
+        }
+    }
+    return err({ type: "exhausted", attempts: maxRetries + 1, lastError });
+}
+/** Render an `ApiError` as a one-line message (for a rethrow or log). */
+export function describeApiError(e) {
+    switch (e.type) {
+        case "http_status":
+            return e.body ? `HTTP ${e.status}: ${e.body}` : `HTTP ${e.status}`;
+        case "timeout":
+            return `Request timed out after ${e.timeoutMs}ms`;
+        case "exhausted":
+            return `Failed after ${e.attempts} attempts: ${e.lastError}`;
+        case "invalid_response":
+            return `Response did not match the expected schema: ${e.issues}`;
+    }
+}
+/**
+ * Is an `ApiError` an unexpected failure?
+ *
+ * A concrete 4xx means the request itself was wrong — a bad identifier, a
+ * resource that does not exist — an expected outcome the caller models as
+ * data (an empty result, a `notFound` entry). Everything else — 5xx, a
+ * timeout, retry exhaustion, a transport failure, or a schema mismatch
+ * (`invalid_response`) — is unexpected and the caller should surface it by
+ * throwing (or returning `err`).
+ */
+export function isUnexpectedApiError(e) {
+    return !(e.type === "http_status" && e.status >= 400 && e.status < 500);
+}
+/**
+ * Parse tab-separated text into rows of columns (e.g., KEGG responses).
+ * Filters out empty lines.
+ */
+export function parseTSV(text) {
+    return text
+        .split("\n")
+        .filter((line) => line.trim() !== "")
+        .map((line) => line.split("\t"));
+}

package/dist/tools/lib/bgee-client.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure async client functions for the Bgee multi-species expression API.
+ *
+ * Resolves a human gene symbol to its Ensembl ID, fans out to ortholog
+ * lookups for the configured non-human species (Ensembl REST), then
+ * queries Bgee per (species, ortholog ENSG) for tissue-level expression
+ * calls. Returns a per-species table of tissue × expression-rank.
+ */
+export declare const SUPPORTED_SPECIES: readonly ["homo_sapiens", "mus_musculus", "rattus_norvegicus", "canis_lupus_familiaris", "macaca_mulatta"];
+export type SupportedSpecies = (typeof SUPPORTED_SPECIES)[number];
+export declare const SPECIES_TAXON: Record<SupportedSpecies, number>;
+export type ExpressionRank = "absent" | "low" | "medium" | "high";
+export interface TissueRow {
+    tissue: string;
+    cellType: string | null;
+    expressionScore: number | null;
+    confidence: "gold" | "silver" | null;
+    expressionState: "expressed" | "not expressed";
+    rank: ExpressionRank;
+}
+export interface SpeciesEntry {
+    species: SupportedSpecies;
+    taxonId: number;
+    ensemblId: string;
+    tissues: TissueRow[];
+}
+export interface MultiSpeciesExpression {
+    geneSymbol: string;
+    humanEnsemblId: string | null;
+    bySpecies: SpeciesEntry[];
+    notFound: string[];
+}
+export declare function bucketRank(expressionState: string, score: number | null): ExpressionRank;
+export declare function parseExpressionResponse(raw: unknown): TissueRow[];
+/** Fetch multi-species expression for a human gene symbol. */
+export declare function getMultiSpeciesExpression(geneSymbol: string, species?: SupportedSpecies[]): Promise<MultiSpeciesExpression>;

package/dist/tools/lib/bgee-client.js

@@ -0,0 +1,150 @@
+/**
+ * Pure async client functions for the Bgee multi-species expression API.
+ *
+ * Resolves a human gene symbol to its Ensembl ID, fans out to ortholog
+ * lookups for the configured non-human species (Ensembl REST), then
+ * queries Bgee per (species, ortholog ENSG) for tissue-level expression
+ * calls. Returns a per-species table of tissue × expression-rank.
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError, isUnexpectedApiError } from "./api-utils.js";
+const ENSEMBL_BASE = "https://rest.ensembl.org";
+const BGEE_BASE = "https://www.bgee.org/api";
+export const SUPPORTED_SPECIES = ["homo_sapiens", "mus_musculus", "rattus_norvegicus", "canis_lupus_familiaris", "macaca_mulatta"];
+export const SPECIES_TAXON = {
+    homo_sapiens: 9606,
+    mus_musculus: 10090,
+    rattus_norvegicus: 10116,
+    canis_lupus_familiaris: 9615,
+    macaca_mulatta: 9544,
+};
+const ENSEMBL_HEADERS = {
+    Accept: "application/json",
+    "Content-Type": "application/json",
+};
+export function bucketRank(expressionState, score) {
+    if (expressionState === "not expressed")
+        return "absent";
+    if (score === null)
+        return "low";
+    if (score >= 75)
+        return "high";
+    if (score >= 25)
+        return "medium";
+    return "low";
+}
+// A single expression call from the Bgee API `data.calls` array, plus the envelope that
+// wraps them. Validated at the fetch boundary; `parseExpressionResponse` reads the fields
+// defensively. Every field optional — the API omits absent values.
+const BgeeCallSchema = z.object({
+    condition: z
+        .object({
+        anatEntity: z.object({ name: z.string().optional() }).optional(),
+        cellType: z.object({ name: z.string().optional() }).optional(),
+    })
+        .optional(),
+    expressionScore: z.object({ expressionScore: z.union([z.string(), z.number()]).optional() }).optional(),
+    expressionQuality: z.string().optional(),
+    expressionState: z.string().optional(),
+});
+const BgeeExpressionResponseSchema = z.object({
+    data: z.object({ calls: z.array(BgeeCallSchema).optional() }).optional(),
+});
+// Ensembl REST response shapes consumed by the ortholog-resolution path.
+const EnsemblLookupSchema = z.object({ id: z.string().optional() });
+const EnsemblHomologyResponseSchema = z.object({
+    data: z.array(z.object({ homologies: z.array(z.object({ id: z.string().optional(), type: z.string().optional() })).optional() })).optional(),
+});
+export function parseExpressionResponse(raw) {
+    // `raw` is the untyped Bgee API payload; `.data.calls` is reached defensively and
+    // the `Array.isArray` guard below means a shape mismatch degrades to an empty list.
+    const calls = raw?.data?.calls;
+    if (!Array.isArray(calls))
+        return [];
+    const out = [];
+    for (const call of calls) {
+        const anatName = call?.condition?.anatEntity?.name ?? "";
+        const tissue = anatName.trim().toLowerCase();
+        if (!tissue)
+            continue;
+        const cellTypeName = call?.condition?.cellType?.name;
+        const cellType = typeof cellTypeName === "string" && cellTypeName.trim() !== "" ? cellTypeName.trim().toLowerCase() : null;
+        const rawScore = call?.expressionScore?.expressionScore;
+        let expressionScore = null;
+        if (typeof rawScore === "string" || typeof rawScore === "number") {
+            const n = typeof rawScore === "number" ? rawScore : parseFloat(rawScore);
+            expressionScore = Number.isFinite(n) ? n : null;
+        }
+        const quality = call?.expressionQuality;
+        const confidence = quality === "gold" || quality === "silver" ? quality : null;
+        const stateRaw = call?.expressionState;
+        const expressionState = stateRaw === "not expressed" ? "not expressed" : "expressed";
+        out.push({
+            tissue,
+            cellType,
+            expressionScore,
+            confidence,
+            expressionState,
+            rank: bucketRank(expressionState, expressionScore),
+        });
+    }
+    return out;
+}
+async function resolveHumanEnsembl(symbol) {
+    const url = `${ENSEMBL_BASE}/lookup/symbol/homo_sapiens/${encodeURIComponent(symbol)}`;
+    const res = await apiFetchValidated(url, EnsemblLookupSchema, { headers: ENSEMBL_HEADERS });
+    if (res.isErr()) {
+        if (isUnexpectedApiError(res.error))
+            throw new Error(describeApiError(res.error));
+        return null;
+    }
+    if (typeof res.value.id !== "string" || !res.value.id.startsWith("ENSG"))
+        return null;
+    return res.value.id;
+}
+async function resolveOrtholog(symbol, targetSpecies) {
+    const url = `${ENSEMBL_BASE}/homology/symbol/homo_sapiens/${encodeURIComponent(symbol)}` + `?type=orthologues;target_species=${targetSpecies};format=condensed`;
+    const res = await apiFetchValidated(url, EnsemblHomologyResponseSchema, { headers: ENSEMBL_HEADERS });
+    if (res.isErr()) {
+        if (isUnexpectedApiError(res.error))
+            throw new Error(describeApiError(res.error));
+        return null;
+    }
+    const homologies = res.value.data?.[0]?.homologies ?? [];
+    const onetoone = homologies.find((h) => h.type === "ortholog_one2one");
+    return (onetoone?.id ?? homologies[0]?.id ?? null) || null;
+}
+async function fetchBgeeForSpecies(ensemblId, taxonId) {
+    const url = `${BGEE_BASE}/?page=gene&action=expression&display_type=json` + `&gene_id=${encodeURIComponent(ensemblId)}&species_id=${taxonId}`;
+    const res = await apiFetchValidated(url, BgeeExpressionResponseSchema);
+    if (res.isErr()) {
+        if (isUnexpectedApiError(res.error))
+            throw new Error(describeApiError(res.error));
+        return [];
+    }
+    return parseExpressionResponse(res.value);
+}
+/** Fetch multi-species expression for a human gene symbol. */
+export async function getMultiSpeciesExpression(geneSymbol, species = [...SUPPORTED_SPECIES]) {
+    const humanEnsemblId = await resolveHumanEnsembl(geneSymbol);
+    if (!humanEnsemblId) {
+        return { geneSymbol, humanEnsemblId: null, bySpecies: [], notFound: [] };
+    }
+    const idEntries = await Promise.all(species.map(async (sp) => {
+        if (sp === "homo_sapiens")
+            return { sp, id: humanEnsemblId };
+        const id = await resolveOrtholog(geneSymbol, sp);
+        return { sp, id };
+    }));
+    const bySpecies = [];
+    const notFound = [];
+    await Promise.all(idEntries.map(async ({ sp, id }) => {
+        if (!id) {
+            notFound.push(sp);
+            return;
+        }
+        const tissues = await fetchBgeeForSpecies(id, SPECIES_TAXON[sp]);
+        bySpecies.push({ species: sp, taxonId: SPECIES_TAXON[sp], ensemblId: id, tissues });
+    }));
+    return { geneSymbol, humanEnsemblId, bySpecies, notFound };
+}

package/dist/tools/lib/cbioportal-client.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pure async client for cBioPortal somatic mutation frequencies.
+ *
+ * Used by §3.4 (Genetic Alterations — somatic mutation frequencies). Queries
+ * the public cBioPortal REST API for mutation occurrence across all curated
+ * cancer studies, then aggregates by cancer type to produce the spec's
+ * "where is the target broken in human disease, and how often" view.
+ */
+export interface CancerStudy {
+    studyId: string;
+    cancerType: string;
+    cancerTypeName: string;
+}
+export interface MutationFrequency {
+    cancerTypeId: string;
+    cancerTypeName: string;
+    totalSamples: number;
+    mutatedSamples: number;
+    frequency: number;
+    studies: string[];
+}
+/**
+ * Compute somatic mutation frequencies for a target across all curated
+ * cancer studies in cBioPortal, grouped by cancer type. Returns one row
+ * per cancer type containing total samples checked, samples with at
+ * least one mutation in the gene, and the contributing studies.
+ */
+export declare function getSomaticMutationFrequencies(geneSymbol: string, options?: {
+    minSamplesPerCancerType?: number;
+    maxStudies?: number;
+}): Promise<{
+    entrezGeneId: number | null;
+    rows: MutationFrequency[];
+}>;

package/dist/tools/lib/cbioportal-client.js

@@ -0,0 +1,159 @@
+/**
+ * Pure async client for cBioPortal somatic mutation frequencies.
+ *
+ * Used by §3.4 (Genetic Alterations — somatic mutation frequencies). Queries
+ * the public cBioPortal REST API for mutation occurrence across all curated
+ * cancer studies, then aggregates by cancer type to produce the spec's
+ * "where is the target broken in human disease, and how often" view.
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError } from "./api-utils.js";
+const CBIOPORTAL_BASE = "https://www.cbioportal.org/api";
+const HEADERS = { Accept: "application/json" };
+// Raw cBioPortal wire shapes, validated at the fetch boundary. Fields the code
+// reads as map keys or feeds into `string[]` params stay required — a missing
+// value there is a contract break we surface as `invalid_response`, not a silent
+// `undefined`; every other field is optional because the API omits absent values.
+const RawMolecularProfileSchema = z.object({
+    molecularProfileId: z.string(),
+    studyId: z.string(),
+    molecularAlterationType: z.string().optional(),
+});
+const RawMutationCountSchema = z.object({
+    studyId: z.string(),
+    sampleId: z.string(),
+    mutationCount: z.number().optional(),
+});
+const RawSampleListSchema = z.object({
+    sampleListId: z.string().optional(),
+    studyId: z.string(),
+    category: z.string().optional(),
+    sampleCount: z.number().optional(),
+});
+const RawCancerStudySchema = z.object({
+    studyId: z.string(),
+    cancerTypeId: z.string().optional(),
+    cancerType: z.object({ name: z.string().optional(), cancerTypeId: z.string().optional() }).optional(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+});
+async function listStudies() {
+    const url = `${CBIOPORTAL_BASE}/studies?projection=SUMMARY&pageSize=10000`;
+    const res = await apiFetchValidated(url, z.array(RawCancerStudySchema), { headers: HEADERS });
+    if (res.isErr())
+        throw new Error(describeApiError(res.error));
+    return res.value ?? [];
+}
+async function listAllSampleLists() {
+    const url = `${CBIOPORTAL_BASE}/sample-lists?projection=SUMMARY&pageSize=10000`;
+    const res = await apiFetchValidated(url, z.array(RawSampleListSchema), { headers: HEADERS });
+    if (res.isErr())
+        throw new Error(describeApiError(res.error));
+    return res.value ?? [];
+}
+async function listMutationProfiles() {
+    const url = `${CBIOPORTAL_BASE}/molecular-profiles?projection=SUMMARY&pageSize=10000`;
+    const res = await apiFetchValidated(url, z.array(RawMolecularProfileSchema), { headers: HEADERS });
+    if (res.isErr())
+        throw new Error(describeApiError(res.error));
+    return (res.value ?? []).filter((p) => p.molecularAlterationType === "MUTATION_EXTENDED");
+}
+async function fetchMutationCountsForGene(entrezGeneId, profileIds) {
+    if (profileIds.length === 0)
+        return [];
+    const url = `${CBIOPORTAL_BASE}/mutations/fetch?projection=SUMMARY`;
+    const res = await apiFetchValidated(url, z.array(RawMutationCountSchema), {
+        method: "POST",
+        headers: { ...HEADERS, "Content-Type": "application/json" },
+        body: JSON.stringify({
+            molecularProfileIds: profileIds,
+            entrezGeneIds: [entrezGeneId],
+        }),
+    });
+    if (res.isErr())
+        throw new Error(describeApiError(res.error));
+    return res.value ?? [];
+}
+/**
+ * Resolve a gene symbol to its NCBI Entrez Gene ID via cBioPortal's gene
+ * search endpoint. cBioPortal's mutation API requires entrezGeneId, not
+ * symbol.
+ */
+async function resolveEntrezId(symbol) {
+    const url = `${CBIOPORTAL_BASE}/genes/${encodeURIComponent(symbol)}`;
+    const res = await apiFetchValidated(url, z.object({ entrezGeneId: z.number().optional() }), { headers: HEADERS });
+    if (res.isErr())
+        return null;
+    return res.value?.entrezGeneId ?? null;
+}
+/**
+ * Compute somatic mutation frequencies for a target across all curated
+ * cancer studies in cBioPortal, grouped by cancer type. Returns one row
+ * per cancer type containing total samples checked, samples with at
+ * least one mutation in the gene, and the contributing studies.
+ */
+export async function getSomaticMutationFrequencies(geneSymbol, options = {}) {
+    const minSamples = options.minSamplesPerCancerType ?? 50;
+    const maxStudies = options.maxStudies ?? 500;
+    const entrezGeneId = await resolveEntrezId(geneSymbol);
+    if (entrezGeneId == null)
+        return { entrezGeneId: null, rows: [] };
+    const [studies, profiles, sampleLists] = await Promise.all([listStudies(), listMutationProfiles(), listAllSampleLists()]);
+    const allSampleListByStudy = new Map();
+    for (const sl of sampleLists) {
+        if (sl.category === "all_cases_in_study") {
+            allSampleListByStudy.set(sl.studyId, sl);
+        }
+    }
+    const studiesWithMutations = profiles
+        .map((p) => p.studyId)
+        .filter((sid) => allSampleListByStudy.has(sid))
+        .slice(0, maxStudies);
+    const profileIds = profiles.filter((p) => studiesWithMutations.includes(p.studyId)).map((p) => p.molecularProfileId);
+    const studyById = new Map();
+    for (const s of studies)
+        studyById.set(s.studyId, s);
+    const mutations = await fetchMutationCountsForGene(entrezGeneId, profileIds);
+    const mutatedStudySamples = new Map();
+    for (const m of mutations) {
+        if (!mutatedStudySamples.has(m.studyId))
+            mutatedStudySamples.set(m.studyId, new Set());
+        mutatedStudySamples.get(m.studyId).add(m.sampleId);
+    }
+    const byCancerType = new Map();
+    for (const studyId of studiesWithMutations) {
+        const sl = allSampleListByStudy.get(studyId);
+        if (!sl?.sampleCount)
+            continue;
+        const study = studyById.get(studyId);
+        const cancerTypeId = study?.cancerType?.cancerTypeId ?? study?.cancerTypeId ?? "unknown";
+        const cancerTypeName = study?.cancerType?.name ?? cancerTypeId;
+        if (!byCancerType.has(cancerTypeId)) {
+            byCancerType.set(cancerTypeId, {
+                name: cancerTypeName,
+                total: 0,
+                mutated: 0,
+                studies: new Set(),
+            });
+        }
+        const bucket = byCancerType.get(cancerTypeId);
+        bucket.total += sl.sampleCount;
+        bucket.mutated += mutatedStudySamples.get(studyId)?.size ?? 0;
+        bucket.studies.add(studyId);
+    }
+    const rows = [];
+    for (const [cancerTypeId, agg] of byCancerType.entries()) {
+        if (agg.total < minSamples)
+            continue;
+        rows.push({
+            cancerTypeId,
+            cancerTypeName: agg.name,
+            totalSamples: agg.total,
+            mutatedSamples: agg.mutated,
+            frequency: agg.total === 0 ? 0 : agg.mutated / agg.total,
+            studies: [...agg.studies].sort(),
+        });
+    }
+    rows.sort((a, b) => b.frequency - a.frequency);
+    return { entrezGeneId, rows };
+}

package/dist/tools/lib/chembl-client.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Pure async client functions for the ChEMBL REST API.
+ *
+ * Used directly by target-assessment workflow steps and by tool wrappers.
+ */
+export interface ChemblTarget {
+    targetChemblId: string;
+    preferredName: string | null;
+    targetType: string | null;
+    organism: string | null;
+    geneNames: string[];
+}
+export interface ChemblActivity {
+    activityId: number | null;
+    compoundChemblId: string;
+    targetChemblId: string | null;
+    standardType: string | null;
+    standardValue: number | null;
+    standardUnits: string | null;
+    assayChemblId: string | null;
+    assayType: string | null;
+    pchemblValue: number | null;
+}
+export interface ChemblMechanism {
+    mechanismOfAction: string | null;
+    actionType: string | null;
+    targetChemblId: string | null;
+    targetName: string | null;
+    moleculeChemblId: string;
+}
+export interface ChemblDrug {
+    moleculeChemblId: string;
+    preferredName: string | null;
+    maxPhase: number | null;
+    moleculeType: string | null;
+    firstApproval: number | null;
+    indication: string | null;
+}
+export interface ChemblModulator {
+    moleculeChemblId: string;
+    parentChemblId: string | null;
+    preferredName: string | null;
+    maxPhase: number | null;
+    moleculeType: string | null;
+    firstApproval: number | null;
+}
+export interface ChemblPolypharmHit {
+    moleculeChemblId: string;
+    targetChemblId: string;
+    targetName: string | null;
+    standardType: string | null;
+    standardValue: number | null;
+    standardUnits: string | null;
+    pchemblValue: number | null;
+}
+export declare function searchTargets(query: string, limit?: number): Promise<ChemblTarget[]>;
+export declare function getBioactivity(chemblId: string, type: "compound" | "target", options?: {
+    activityType?: string;
+    limit?: number;
+}): Promise<ChemblActivity[]>;
+export declare function getMechanism(chemblId: string): Promise<ChemblMechanism[]>;
+export declare function getDrugInfo(query: string, limit?: number): Promise<ChemblDrug[]>;
+/**
+ * Fetch all clinical-stage modulators (max_phase ≥ 2 by default) for a target.
+ * Used for §2.6.6 (class precedent) and as the input to §2.6.4 (off-target panel).
+ */
+export declare function getTargetModulators(targetChemblId: string, options?: {
+    minPhase?: number;
+    limit?: number;
+}): Promise<ChemblModulator[]>;
+/**
+ * Fetch off-target binding hits for a modulator: every target the molecule
+ * has been measured against (excluding the primary target), with potency.
+ * Used for §2.6.4 / §2.8 off-target panel.
+ */
+export declare function getModulatorPolypharmacology(moleculeChemblId: string, options?: {
+    minPchembl?: number;
+    limit?: number;
+    excludeTargetChemblId?: string;
+}): Promise<ChemblPolypharmHit[]>;
+/**
+ * Fetch the median pChEMBL value for a modulator measured against its primary
+ * on-target. Filters to activities with non-null pchembl_value against the
+ * specified target ChEMBL ID. Returns null when no activities are found.
+ *
+ * Used by the polypharm fanout step so the assembler's computeSelectivity
+ * can produce real fold values instead of selectivity_unknown.
+ */
+export declare function getModulatorOnTargetPchembl(modulatorChemblId: string, targetChemblId: string): Promise<number | null>;
+/**
+ * Secondary path: fetch clinical-stage small molecules via the activity table.
+ *
+ * ChEMBL's mechanism table can lag behind for newer programmes (e.g.,
+ * orforglipron for GLP1R). Querying the activity table with
+ * `max_phase__gte` catches these molecules earlier. The activity table
+ * carries `molecule_chembl_id` but not `max_phase` or `molecule_type` —
+ * those require a follow-up molecule lookup. We batch unique molecule IDs
+ * and fetch molecule records in slices of 5.
+ *
+ * Returns one `ChemblModulator` per unique molecule that passes the
+ * min-phase and molecule-type filters.
+ */
+export declare function getModulatorsViaActivity(args: {
+    target_chembl_id: string;
+    max_phase_min?: number;
+    molecule_type?: string;
+    limit?: number;
+}): Promise<ChemblModulator[]>;
+/**
+ * Fetch the canonical InChI key for a ChEMBL molecule. Returns null when
+ * ChEMBL has no recorded structure (typical for peptide/protein entries
+ * with `molecule_type: "Unknown"`).
+ */
+export declare function getMoleculeInChIKey(moleculeChemblId: string): Promise<string | null>;
+/**
+ * Resolve a drug's mechanism-of-action targets to UniProt accessions.
+ * Returns deduplicated accessions across all mechanism rows.
+ * Empty array on no mechanism, missing target, or non-protein target.
+ *
+ * Used by target-identity-filter to detect off-target trials (e.g., a
+ * trial of a CALCRL drug being surfaced under a CALCR assessment).
+ */
+export declare function getDrugPrimaryTargetUniprots(moleculeChemblId: string): Promise<string[]>;