@inflexa-ai/harness 0.1.1 → 0.3.0

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

@@ -70,6 +70,47 @@ const MoleculeStructuresResponseSchema = z.object({
 const TargetComponentsResponseSchema = z.object({
     target_components: z.array(z.object({ accession: z.string().optional(), component_type: z.string().optional() })).optional(),
 });
+// A single schema that both validates and normalizes one ChEMBL molecule
+// record for the compound search: the `.object(...)` half is the snake_case wire
+// shape (every field optional — ChEMBL omits absent values), the
+// `.transform(...)` half maps it to the camelCase `ChemblCompound` we return.
+// Parsing IS the validation, so there is no separate raw interface or mapper.
+const CompoundRecordSchema = z
+    .object({
+    molecule_chembl_id: z.string().optional(),
+    // ChEMBL sends explicit `null` (not omission) for an unnamed compound, and
+    // `null` for the whole structures/properties blocks on biologics/antibodies
+    // — `.nullable()` so those rows parse instead of failing the `molecules` array.
+    pref_name: z.string().nullable().optional(),
+    molecule_structures: z
+        .object({
+        canonical_smiles: z.string().nullable().optional(),
+    })
+        .nullable()
+        .optional(),
+    molecule_properties: z
+        .object({
+        full_mwt: z.string().nullable().optional(),
+        alogp: z.string().nullable().optional(),
+        molecular_formula: z.string().nullable().optional(),
+    })
+        .nullable()
+        .optional(),
+})
+    .transform((raw) => ({
+    chemblId: raw.molecule_chembl_id ?? "",
+    preferredCompoundName: raw.pref_name ?? null,
+    canonicalSmiles: raw.molecule_structures?.canonical_smiles ?? null,
+    molecularWeight: raw.molecule_properties?.full_mwt ? parseFloat(raw.molecule_properties.full_mwt) : null,
+    alogp: raw.molecule_properties?.alogp ? parseFloat(raw.molecule_properties.alogp) : null,
+    molecularFormula: raw.molecule_properties?.molecular_formula ?? null,
+}));
+const CompoundsResponseSchema = z.object({ molecules: z.array(CompoundRecordSchema).optional() });
+// The two hops of the target-mode compound search read one id each, so they
+// project the response down to that id rather than reusing the richer
+// target/activity schemas above.
+const CompoundTargetIdResponseSchema = z.object({ targets: z.array(z.object({ target_chembl_id: z.string().optional() })).optional() });
+const CompoundActivityIdResponseSchema = z.object({ activities: z.array(z.object({ molecule_chembl_id: z.string().optional() })).optional() });
 function extractGeneNames(components) {
     if (!components?.length)
         return [];
@@ -104,6 +145,92 @@ function parseNumeric(val) {
     const n = typeof val === "number" ? val : parseFloat(val);
     return Number.isNaN(n) ? null : n;
 }
+/**
+ * Compounds assayed against a target: resolve the query to a target ChEMBL ID,
+ * read that target's activity rows, then fetch the unique molecules behind them.
+ * `limit` caps the activity rows scanned, so the compound count is usually lower.
+ */
+async function searchCompoundsByTarget(query, limit) {
+    const targetRes = await apiFetchValidated(`${CHEMBL_BASE}/target/search.json?q=${encodeURIComponent(query)}&limit=1`, CompoundTargetIdResponseSchema, {
+        headers: HEADERS,
+    });
+    if (targetRes.isErr()) {
+        if (targetRes.error.type === "http_status" && targetRes.error.status === 404)
+            return [];
+        throw new Error(describeApiError(targetRes.error));
+    }
+    if (!targetRes.value.targets?.length)
+        return [];
+    const targetChemblId = targetRes.value.targets[0].target_chembl_id;
+    if (!targetChemblId)
+        return [];
+    const activityRes = await apiFetchValidated(`${CHEMBL_BASE}/activity.json?target_chembl_id=${targetChemblId}&limit=${limit}`, CompoundActivityIdResponseSchema, {
+        headers: HEADERS,
+    });
+    if (activityRes.isErr()) {
+        if (activityRes.error.type === "http_status" && activityRes.error.status === 404)
+            return [];
+        throw new Error(describeApiError(activityRes.error));
+    }
+    if (!activityRes.value.activities?.length)
+        return [];
+    const uniqueIds = new Set();
+    for (const act of activityRes.value.activities) {
+        if (act.molecule_chembl_id)
+            uniqueIds.add(act.molecule_chembl_id);
+    }
+    const compounds = [];
+    const idArray = [...uniqueIds];
+    // Fetch in batches of 50 to avoid overly long URLs.
+    const batchSize = 50;
+    for (let i = 0; i < idArray.length; i += batchSize) {
+        const batch = idArray.slice(i, i + batchSize);
+        const idsParam = batch.join(";");
+        const molRes = await apiFetchValidated(`${CHEMBL_BASE}/molecule/set/${idsParam}.json`, CompoundsResponseSchema, { headers: HEADERS });
+        if (molRes.isErr()) {
+            if (!(molRes.error.type === "http_status" && molRes.error.status === 404)) {
+                throw new Error(describeApiError(molRes.error));
+            }
+            continue;
+        }
+        if (molRes.value.molecules) {
+            for (const mol of molRes.value.molecules) {
+                compounds.push(mol);
+            }
+        }
+    }
+    return compounds;
+}
+/** Free-text search over molecule names. */
+async function searchCompoundsByName(query, limit) {
+    const res = await apiFetchValidated(`${CHEMBL_BASE}/molecule/search.json?q=${encodeURIComponent(query)}&limit=${limit}`, CompoundsResponseSchema, {
+        headers: HEADERS,
+    });
+    if (res.isErr()) {
+        if (res.error.type === "http_status" && res.error.status === 404)
+            return [];
+        throw new Error(describeApiError(res.error));
+    }
+    return res.value.molecules ?? [];
+}
+/** Flexible (flexmatch) structure search on canonical SMILES. */
+async function searchCompoundsBySmiles(smiles, limit) {
+    const res = await apiFetchValidated(`${CHEMBL_BASE}/molecule.json?molecule_structures__canonical_smiles__flexmatch=${encodeURIComponent(smiles)}&limit=${limit}`, CompoundsResponseSchema, { headers: HEADERS });
+    if (res.isErr()) {
+        if (res.error.type === "http_status" && res.error.status === 404)
+            return [];
+        throw new Error(describeApiError(res.error));
+    }
+    return res.value.molecules ?? [];
+}
+/** Search ChEMBL for compounds by target, compound name, or SMILES. */
+export async function searchCompounds(query, searchType, limit = 500) {
+    if (searchType === "target")
+        return searchCompoundsByTarget(query, limit);
+    if (searchType === "smiles")
+        return searchCompoundsBySmiles(query, limit);
+    return searchCompoundsByName(query, limit);
+}
 export async function searchTargets(query, limit = 25) {
     const url = `${CHEMBL_BASE}/target/search.json?q=${encodeURIComponent(query)}&limit=${limit}`;
     const res = await apiFetchValidated(url, TargetSearchResponseSchema, { headers: HEADERS });

package/dist/tools/lib/ctx-ops.d.ts

@@ -0,0 +1,224 @@
+/**
+ * EPA CompTox (CTX) operations — the four datasets the CompTox tools expose:
+ * ToxCast/Tox21 bioactivity, hazard (ToxValDB/ToxRefDB), chemical identity +
+ * physicochemical properties, and exposure.
+ *
+ * Every dataset keys off a DTXSID, so `resolveDtxsid` is the single entry
+ * point they share: a DTXSID is used directly, anything else is resolved by
+ * exact match against the chemical-search endpoint. `null` means the query
+ * resolved to no chemical — an expected outcome, not an error.
+ */
+import { z } from "zod";
+export interface CtxResolved {
+    dtxsid: string;
+    preferredName: string;
+    casrn: string | null;
+}
+/** Resolve a DTXSID / CASRN / name to a chemical. `null` = no match (valid no-data). */
+export declare function resolveDtxsid(query: string, headers: Record<string, string>): Promise<CtxResolved | null>;
+export interface ToxcastAssayResult {
+    aeid: number;
+    assayEndpoint: string;
+    ac50: number | null;
+    hitCall: number;
+    maxMean: number | null;
+    model: string;
+    flags: string[];
+}
+export interface ToxcastBioactivity {
+    totalAssays: number;
+    activeAssays: number;
+    activeHitRate: number;
+    results: ToxcastAssayResult[];
+}
+/**
+ * ToxCast/Tox21 assay results for a chemical, sorted by AC50 ascending.
+ * `totalAssays` / `activeAssays` / `activeHitRate` always describe the full
+ * tested panel, never the returned slice.
+ */
+export declare function fetchToxcastBioactivity(dtxsid: string, headers: Record<string, string>, opts: {
+    activeOnly: boolean;
+    limit: number;
+}): Promise<ToxcastBioactivity>;
+declare const ToxValSchema: z.ZodPipe<z.ZodObject<{
+    source: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    toxvalType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    toxvalNumeric: z.ZodOptional<z.ZodUnknown>;
+    toxvalUnits: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    studyType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    studyDurationClass: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    speciesCommon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    exposureRoute: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    toxicologicalEffect: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    riskAssessmentClass: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    humanEco: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    year: z.ZodOptional<z.ZodUnknown>;
+    quality: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>, z.ZodTransform<{
+    source: string;
+    toxvalType: string;
+    toxvalNumeric: number | null;
+    toxvalUnits: string;
+    studyType: string;
+    studyDurationClass: string;
+    species: string;
+    exposureRoute: string;
+    toxicologicalEffect: string;
+    riskAssessmentClass: string;
+    humanEco: string;
+    year: number | null;
+    quality: string;
+}, {
+    source?: string | null | undefined;
+    toxvalType?: string | null | undefined;
+    toxvalNumeric?: unknown;
+    toxvalUnits?: string | null | undefined;
+    studyType?: string | null | undefined;
+    studyDurationClass?: string | null | undefined;
+    speciesCommon?: string | null | undefined;
+    exposureRoute?: string | null | undefined;
+    toxicologicalEffect?: string | null | undefined;
+    riskAssessmentClass?: string | null | undefined;
+    humanEco?: string | null | undefined;
+    year?: unknown;
+    quality?: string | null | undefined;
+}>>;
+export type ToxValEntry = z.infer<typeof ToxValSchema>;
+declare const GenetoxSchema: z.ZodPipe<z.ZodObject<{
+    source: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    assayCategory: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    assayType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    metabolicActivation: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    species: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    overallResult: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    year: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, z.ZodTransform<{
+    source: string;
+    assayCategory: string;
+    assayType: string;
+    metabolicActivation: string;
+    species: string;
+    overallResult: string;
+    year: number | null;
+}, {
+    source?: string | null | undefined;
+    assayCategory?: string | null | undefined;
+    assayType?: string | null | undefined;
+    metabolicActivation?: string | null | undefined;
+    species?: string | null | undefined;
+    overallResult?: string | null | undefined;
+    year?: unknown;
+}>>;
+export type GenetoxSummary = z.infer<typeof GenetoxSchema>;
+declare const CancerSchema: z.ZodPipe<z.ZodObject<{
+    source: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    classification: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    cancerClassification: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    url: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>, z.ZodTransform<{
+    source: string;
+    classification: string;
+    url: string;
+}, {
+    source?: string | null | undefined;
+    classification?: string | null | undefined;
+    cancerClassification?: string | null | undefined;
+    url?: string | null | undefined;
+}>>;
+export type CancerSummary = z.infer<typeof CancerSchema>;
+export type CtxHazardDataType = "toxval" | "genetox" | "cancer" | "all";
+export interface CtxHazardData {
+    toxval?: ToxValEntry[];
+    genetox?: GenetoxSummary[];
+    cancer?: CancerSummary[];
+}
+/**
+ * In-vivo hazard data for a chemical. `limit` caps toxval and genetox only —
+ * cancer classifications always come back whole.
+ */
+export declare function fetchCtxHazardData(dtxsid: string, headers: Record<string, string>, opts: {
+    dataType: CtxHazardDataType;
+    limit: number;
+}): Promise<CtxHazardData>;
+export interface ChemicalDetail {
+    dtxsid: string;
+    dtxcid: string;
+    casrn: string | null;
+    preferredName: string;
+    iupacName: string;
+    molFormula: string;
+    smiles: string;
+    inchikey: string;
+    monoisotopicMass: number | null;
+    averageMass: number | null;
+    qcLevel: number | null;
+    totalAssays: number | null;
+    activeAssays: number | null;
+    percentAssays: number | null;
+    pubchemCid: number | null;
+    pubmedCount: number | null;
+    sourcesCount: number | null;
+}
+export interface PropertySummary {
+    propName: string;
+    unit: string;
+    experimentalCount: number | null;
+    experimentalMedian: number | null;
+    experimentalMin: number | null;
+    experimentalMax: number | null;
+    predictedCount: number | null;
+    predictedMedian: number | null;
+    predictedMin: number | null;
+    predictedMax: number | null;
+}
+/** Chemical identity, mass, and dashboard counts for a DTXSID. */
+export declare function fetchCtxChemicalDetail(dtxsid: string, headers: Record<string, string>): Promise<ChemicalDetail>;
+/** Experimental + predicted physicochemical property summaries. `undefined` = none served. */
+export declare function fetchCtxChemicalProperties(dtxsid: string, headers: Record<string, string>): Promise<PropertySummary[] | undefined>;
+export interface SeemPrediction {
+    dtxsid: string;
+    productionVolume: number | null;
+    units: string;
+    probabilityDietary: number | null;
+    probabilityResidential: number | null;
+    probabilityPesticide: number | null;
+    probabilityIndustrial: number | null;
+}
+export interface HttkParameter {
+    parameter: string;
+    measured: number | null;
+    predicted: number | null;
+    units: string;
+    model: string;
+    species: string;
+    reference: string;
+}
+export interface FunctionalUse {
+    functionCategory: string;
+    reportedFunction: string;
+    docTitle: string;
+}
+export interface ProductData {
+    productName: string;
+    generalCategory: string;
+    productFamily: string;
+    productType: string;
+    centralWeightFraction: number | null;
+    weightFractionType: string;
+}
+export type CtxExposureDataType = "seem" | "httk" | "functional-use" | "product-data" | "all";
+export interface CtxExposureData {
+    seem?: SeemPrediction;
+    httk?: HttkParameter[];
+    functionalUse?: FunctionalUse[];
+    productData?: ProductData[];
+}
+/**
+ * Human-exposure data for a chemical. `limit` caps functional-use and
+ * product-data only — seem and httk always come back whole.
+ */
+export declare function fetchCtxExposureData(dtxsid: string, headers: Record<string, string>, opts: {
+    dataType: CtxExposureDataType;
+    limit: number;
+}): Promise<CtxExposureData>;
+export {};