@inflexa-ai/harness 0.30.3 → 0.31.1

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

@@ -1,17 +1,22 @@
 /**
  * Shared HTTP fetch helper for bioinformatics API tools.
  *
- * Provides retry-with-backoff for rate-limited APIs (429/503), request
+ * Provides retry-with-backoff for a rate-limited or a transiently-broken API
+ * (429/502/503/504), 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 { z } from "zod";
 import { sleep } from "../../lib/async-utils.js";
-const RETRYABLE_STATUSES = new Set([429, 503]);
+// 502 and 504 sit here next to 429 and 503 because a gateway in front of a bio
+// provider answers with one of them while the origin restarts, and it sends an
+// HTML body. That answer is transient, thus a retry gets the real payload.
+const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
 /**
- * Fetch a URL with retry on 429/503, exponential backoff, and timeout.
+ * Fetch a URL with retry on 429/502/503/504, 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`).
@@ -116,6 +121,41 @@ export function describeApiError(e) {
 export function isUnexpectedApiError(e) {
     return !(e.type === "http_status" && e.status >= 400 && e.status < 500);
 }
+/**
+ * Read a number that a provider serializes as a JSON string.
+ *
+ * A Tastypie `decimal` field (ChEMBL `max_phase`, `standard_value`,
+ * `pchembl_value`) and the eutils `esearch` counts arrive as strings, and the
+ * same value arrives as a number from a different serializer of the same
+ * provider. One helper answers for both encodings, thus no call site invents its
+ * own rule.
+ *
+ * A value that is not a finite number gives `null`. As a result a caller never
+ * sees `NaN`, which compares false against itself and poisons every downstream
+ * threshold.
+ */
+export function parseWireNumber(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    const trimmed = value.trim();
+    // `Number("")` and `Number(" ")` give 0, thus an empty string must not reach it.
+    if (trimmed === "")
+        return null;
+    const parsed = Number(trimmed);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/**
+ * The schema form of `parseWireNumber`, for a field that a provider serializes
+ * as a string or as a number.
+ *
+ * The helper accepts neither `null` nor an omission, because absence is a
+ * per-provider policy and no field is widened without evidence. A caller
+ * composes `.nullable()`, `.optional()`, or both, per the policy of its
+ * provider.
+ */
+export const zWireNumber = z.union([z.string(), z.number()]).transform((value) => parseWireNumber(value));
 /**
  * Parse tab-separated text into rows of columns (e.g., KEGG responses).
  * Filters out empty lines.

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

@@ -5,7 +5,12 @@
  * 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.
+ *
+ * Absence policy: Bgee and the Ensembl calls in this file omit the key of an
+ * absent value, and neither one sends an explicit `null`. Thus a maybe-absent
+ * field carries `.optional()`, not `.nullable()`.
  */
+import { z } from "zod";
 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>;
@@ -31,6 +36,17 @@ export interface MultiSpeciesExpression {
     notFound: string[];
 }
 export declare function bucketRank(expressionState: string, score: number | null): ExpressionRank;
+export declare const EnsemblLookupSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const EnsemblHomologyResponseSchema: z.ZodObject<{
+    data: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        homologies: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
 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

@@ -5,6 +5,10 @@
  * 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.
+ *
+ * Absence policy: Bgee and the Ensembl calls in this file omit the key of an
+ * absent value, and neither one sends an explicit `null`. Thus a maybe-absent
+ * field carries `.optional()`, not `.nullable()`.
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError, isUnexpectedApiError } from "./api-utils.js";
@@ -51,8 +55,8 @@ 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({
+export const EnsemblLookupSchema = z.object({ id: z.string().optional() });
+export 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) {
@@ -102,8 +106,15 @@ async function resolveHumanEnsembl(symbol) {
         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`;
+/**
+ * Resolve the ortholog of one human gene in one other species.
+ *
+ * The route keys on the Ensembl gene id, and never on the symbol. The symbol
+ * route serves the identical envelope, but it answers HTTP 503 under load while
+ * the id route answers. Thus the caller resolves the id first.
+ */
+async function resolveOrtholog(humanEnsemblId, targetSpecies) {
+    const url = `${ENSEMBL_BASE}/homology/id/homo_sapiens/${encodeURIComponent(humanEnsemblId)}` + `?type=orthologues;target_species=${targetSpecies};format=condensed`;
     const res = await apiFetchValidated(url, EnsemblHomologyResponseSchema, { headers: ENSEMBL_HEADERS });
     if (res.isErr()) {
         if (isUnexpectedApiError(res.error))
@@ -133,7 +144,7 @@ export async function getMultiSpeciesExpression(geneSymbol, species = [...SUPPOR
     const idEntries = await Promise.all(species.map(async (sp) => {
         if (sp === "homo_sapiens")
             return { sp, id: humanEnsemblId };
-        const id = await resolveOrtholog(geneSymbol, sp);
+        const id = await resolveOrtholog(humanEnsemblId, sp);
         return { sp, id };
     }));
     const bySpecies = [];

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

@@ -5,7 +5,12 @@
  * 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.
+ *
+ * Absence policy: cBioPortal omits the key of an absent value, and it never
+ * sends an explicit `null`. Thus a maybe-absent field carries `.optional()`,
+ * not `.nullable()`.
  */
+import { z } from "zod";
 export interface CancerStudy {
     studyId: string;
     cancerType: string;
@@ -19,6 +24,21 @@ export interface MutationFrequency {
     frequency: number;
     studies: string[];
 }
+export declare const RawMutationRowSchema: z.ZodObject<{
+    studyId: z.ZodString;
+    sampleId: z.ZodString;
+}, z.core.$strip>;
+export declare const RawCancerStudySchema: z.ZodObject<{
+    studyId: z.ZodString;
+    cancerTypeId: z.ZodOptional<z.ZodString>;
+    cancerType: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    allSampleCount: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 /**
  * Compute somatic mutation frequencies for a target across all curated
  * cancer studies in cBioPortal, grouped by cancer type. Returns one row

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

@@ -5,6 +5,10 @@
  * 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.
+ *
+ * Absence policy: cBioPortal omits the key of an absent value, and it never
+ * sends an explicit `null`. Thus a maybe-absent field carries `.optional()`,
+ * not `.nullable()`.
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError } from "./api-utils.js";
@@ -19,10 +23,11 @@ const RawMolecularProfileSchema = z.object({
     studyId: z.string(),
     molecularAlterationType: z.string().optional(),
 });
-const RawMutationCountSchema = z.object({
+// One mutation row of `mutations/fetch`. The aggregation counts the distinct
+// samples of a study, thus it reads only the two key fields of the row.
+export const RawMutationRowSchema = z.object({
     studyId: z.string(),
     sampleId: z.string(),
-    mutationCount: z.number().optional(),
 });
 const RawSampleListSchema = z.object({
     sampleListId: z.string().optional(),
@@ -30,10 +35,13 @@ const RawSampleListSchema = z.object({
     category: z.string().optional(),
     sampleCount: z.number().optional(),
 });
-const RawCancerStudySchema = z.object({
+export const RawCancerStudySchema = z.object({
     studyId: z.string(),
     cancerTypeId: z.string().optional(),
-    cancerType: z.object({ name: z.string().optional(), cancerTypeId: z.string().optional() }).optional(),
+    // The nested block keys its identifier as `id`. The `projection=DETAILED`
+    // answer carries the block, and `projection=SUMMARY` omits it, thus the
+    // top-level `cancerTypeId` stays the fallback.
+    cancerType: z.object({ id: z.string().optional(), name: z.string().optional() }).optional(),
     name: z.string().optional(),
     description: z.string().optional(),
     /** The denominator of a study. The sample-list SUMMARY projection carries no count. */
@@ -77,11 +85,11 @@ async function listMutationProfiles() {
         throw new Error(describeApiError(res.error));
     return (res.value ?? []).filter((p) => p.molecularAlterationType === "MUTATION_EXTENDED");
 }
-async function fetchMutationCountsForGene(entrezGeneId, profileIds) {
+async function fetchMutationRowsForGene(entrezGeneId, profileIds) {
     if (profileIds.length === 0)
         return [];
     const url = `${CBIOPORTAL_BASE}/mutations/fetch?projection=SUMMARY`;
-    const res = await apiFetchValidated(url, z.array(RawMutationCountSchema), {
+    const res = await apiFetchValidated(url, z.array(RawMutationRowSchema), {
         method: "POST",
         headers: { ...HEADERS, "Content-Type": "application/json" },
         body: JSON.stringify({
@@ -132,7 +140,7 @@ export async function getSomaticMutationFrequencies(geneSymbol, options = {}) {
     const studyById = new Map();
     for (const s of studies)
         studyById.set(s.studyId, s);
-    const mutations = await fetchMutationCountsForGene(entrezGeneId, profileIds);
+    const mutations = await fetchMutationRowsForGene(entrezGeneId, profileIds);
     const mutatedStudySamples = new Map();
     for (const m of mutations) {
         if (!mutatedStudySamples.has(m.studyId))
@@ -145,7 +153,7 @@ export async function getSomaticMutationFrequencies(geneSymbol, options = {}) {
         const sampleCount = study?.allSampleCount ?? 0;
         if (sampleCount === 0)
             continue;
-        const cancerTypeId = study?.cancerType?.cancerTypeId ?? study?.cancerTypeId ?? "unknown";
+        const cancerTypeId = study?.cancerType?.id ?? study?.cancerTypeId ?? "unknown";
         const cancerTypeName = study?.cancerType?.name ?? typeNames.get(cancerTypeId) ?? cancerTypeId;
         if (!byCancerType.has(cancerTypeId)) {
             byCancerType.set(cancerTypeId, {

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

@@ -2,7 +2,13 @@
  * Pure async client functions for the ChEMBL REST API.
  *
  * Used directly by target-assessment workflow steps and by tool wrappers.
+ *
+ * Absence policy: ChEMBL sends an explicit `null` for an absent value, and it
+ * never omits the key. Thus a maybe-absent field carries `.nullable()`, not
+ * `.optional()`.
  */
+import { z } from "zod";
+import type { Logger } from "../../lib/logger.js";
 export interface ChemblCompound {
     chemblId: string;
     preferredCompoundName: string | null;
@@ -65,6 +71,92 @@ export interface ChemblPolypharmHit {
     standardUnits: string | null;
     pchemblValue: number | null;
 }
+export declare const TargetSearchResponseSchema: z.ZodObject<{
+    targets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        target_chembl_id: z.ZodOptional<z.ZodString>;
+        pref_name: z.ZodOptional<z.ZodString>;
+        target_type: z.ZodOptional<z.ZodString>;
+        organism: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        target_components: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            accession: z.ZodOptional<z.ZodString>;
+            target_component_synonyms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                syn_type: z.ZodOptional<z.ZodString>;
+                component_synonym: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const ActivitiesResponseSchema: z.ZodObject<{
+    activities: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        activity_id: z.ZodOptional<z.ZodNumber>;
+        molecule_chembl_id: z.ZodOptional<z.ZodString>;
+        target_chembl_id: z.ZodOptional<z.ZodString>;
+        standard_type: z.ZodOptional<z.ZodString>;
+        standard_value: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>>;
+        standard_units: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        assay_chembl_id: z.ZodOptional<z.ZodString>;
+        assay_type: z.ZodOptional<z.ZodString>;
+        pchembl_value: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const MechanismsResponseSchema: z.ZodObject<{
+    mechanisms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        mechanism_of_action: z.ZodOptional<z.ZodString>;
+        action_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        target_chembl_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        molecule_chembl_id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const DrugIndicationsResponseSchema: z.ZodObject<{
+    drug_indications: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        molecule_chembl_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        mesh_heading: z.ZodOptional<z.ZodString>;
+        efo_term: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        max_phase_for_ind: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const MoleculeSearchResponseSchema: z.ZodObject<{
+    molecules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        molecule_chembl_id: z.ZodOptional<z.ZodString>;
+        pref_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        max_phase: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>>;
+        molecule_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        first_approval: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        molecule_hierarchy: z.ZodOptional<z.ZodObject<{
+            parent_chembl_id: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const MoleculeStructuresResponseSchema: z.ZodObject<{
+    molecule_structures: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        standard_inchi_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const CompoundsResponseSchema: z.ZodObject<{
+    molecules: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodObject<{
+        molecule_chembl_id: z.ZodOptional<z.ZodString>;
+        pref_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        molecule_structures: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            canonical_smiles: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>;
+        molecule_properties: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            full_mwt: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>>;
+            alogp: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>>;
+            full_molformula: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>, z.ZodTransform<ChemblCompound, {
+        molecule_chembl_id?: string | undefined;
+        pref_name?: string | null | undefined;
+        molecule_structures?: {
+            canonical_smiles?: string | null | undefined;
+        } | null | undefined;
+        molecule_properties?: {
+            full_mwt?: number | null | undefined;
+            alogp?: number | null | undefined;
+            full_molformula?: string | null | undefined;
+        } | null | undefined;
+    }>>>>;
+}, z.core.$strip>;
 /** Search ChEMBL for compounds by target, compound name, or SMILES. */
 export declare function searchCompounds(query: string, searchType: CompoundSearchType, limit?: number): Promise<ChemblCompound[]>;
 export declare function searchTargets(query: string, limit?: number): Promise<ChemblTarget[]>;
@@ -75,6 +167,16 @@ export declare function getBioactivity(chemblId: string, type: BioactivityIdType
     limit?: number;
 }): Promise<ChemblActivity[]>;
 export declare function getMechanism(chemblId: string): Promise<ChemblMechanism[]>;
+/**
+ * Approved drugs by name or by disease term.
+ *
+ * The `drug` resource of ChEMBL has no search endpoint, and it carries neither a
+ * name nor an indication. The molecule name search runs first, because an
+ * `icontains` read of `drug_indication` captures a drug name that is a substring
+ * of a disease term ("insulin" matches "insulin resistance"). A query that
+ * names no molecule falls through to the indication read, which answers
+ * highest-phase first and can carry a clinical-stage molecule below approval.
+ */
 export declare function getDrugInfo(query: string, limit?: number): Promise<ChemblDrug[]>;
 /**
  * Fetch all clinical-stage modulators (max_phase ≥ 2 by default) for a target.
@@ -83,7 +185,7 @@ export declare function getDrugInfo(query: string, limit?: number): Promise<Chem
 export declare function getTargetModulators(targetChemblId: string, options?: {
     minPhase?: number;
     limit?: number;
-}): Promise<ChemblModulator[]>;
+}, logger?: Logger): Promise<ChemblModulator[]>;
 /**
  * Fetch off-target binding hits for a modulator: every target the molecule
  * has been measured against (excluding the primary target), with potency.
@@ -102,7 +204,7 @@ export declare function getModulatorPolypharmacology(moleculeChemblId: string, o
  * 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>;
+export declare function getModulatorOnTargetPchembl(modulatorChemblId: string, targetChemblId: string, logger?: Logger): Promise<number | null>;
 /**
  * Secondary path: fetch clinical-stage small molecules via the activity table.
  *
@@ -121,7 +223,7 @@ export declare function getModulatorsViaActivity(args: {
     max_phase_min?: number;
     molecule_type?: string;
     limit?: number;
-}): Promise<ChemblModulator[]>;
+}, logger?: Logger): Promise<ChemblModulator[]>;
 /**
  * Fetch the canonical InChI key for a ChEMBL molecule. Returns null when
  * ChEMBL has no recorded structure (typical for peptide/protein entries