@moldesk/adapters 0.0.0-stage → 0.0.3

package/dist/index.d.ts

@@ -0,0 +1,121 @@
+export interface InstallContext {
+    manifestName: string;
+    modelDir: string;
+    assetsDir: string;
+    runner?: import("@moldesk/runtime").InstallCommandRunner;
+    /** The host platform the runtime entry being installed/verified was resolved
+     * for. Populated by the core installer from its own platform-selection result
+     * — never guessed from `process.platform` by the adapter — so `verifyInstallation`
+     * can pick the right probe (e.g. CUDA vs MPS) even before `installation.json`
+     * exists (during the pre-promotion staging-directory verify). */
+    platform?: import("@moldesk/registry").PlatformId;
+}
+export interface RunContext {
+    manifestName: string;
+    /** Absolute path to the copied input inside the run directory, never the user's original path. */
+    inputPath: string;
+    /** The run directory's `output/` subdir. `collectOutputs` must only look here. */
+    outputDir: string;
+    modelDir: string;
+    assetsDir: string;
+    /** Normalized, validated, defaulted params (see `ParamDescriptor`/`validateParams`). */
+    params: Record<string, unknown>;
+    /** Resolved runtime executable (e.g. the managed venv's `python`) for this run. */
+    runtimeExecutable: string;
+    /** The host platform the installed runtime was resolved for, when determinable.
+     * Lets an adapter's `command()` cross-validate a param (e.g. accelerator) against
+     * the *installed* runtime rather than guessing from `process.platform`. */
+    platform?: import("@moldesk/registry").PlatformId;
+    /** Staged companion inputs (see `resolveCompanionInputs`), keyed by the same
+     * `id` the adapter declared. Populated only when `resolveCompanionInputs`
+     * returned entries for this run's job file; absent for single-file models. */
+    companionInputs?: Array<{
+        id: string;
+        path: string;
+    }>;
+    /** Injected for testability when `collectOutputs` post-processes outputs with
+     * the installed runtime (e.g. OpenDDE's mmCIF → PDB export); defaults to
+     * `@moldesk/runtime`'s `runCommand`. */
+    runner?: import("@moldesk/runtime").InstallCommandRunner;
+}
+/**
+ * Minimal, structural view of an `InstalledModel` record (from `@moldesk/core`)
+ * that `resolveParamDefaults` needs. Defined locally rather than importing
+ * `InstalledModel` from `@moldesk/core` because `@moldesk/core` depends on
+ * `@moldesk/adapters` — importing the other way would be a package cycle.
+ */
+export interface ResolveParamDefaultsInstalledRuntime {
+    kind: string;
+    python?: {
+        platform?: import("@moldesk/registry").PlatformId;
+        platformSelected?: boolean;
+    };
+}
+export interface ResolveParamDefaultsContext {
+    manifestName: string;
+    installed: {
+        runtime: ResolveParamDefaultsInstalledRuntime;
+    };
+}
+export interface ParamDescriptor {
+    name: string;
+    type: "string" | "number" | "boolean";
+    required?: boolean;
+    default?: string | number | boolean;
+    min?: number;
+    max?: number;
+    enum?: Array<string | number>;
+    description?: string;
+}
+export interface InstallPlanStep {
+    readonly id: string;
+    readonly description: string;
+}
+export interface InstallPlan {
+    readonly steps: readonly InstallPlanStep[];
+}
+export interface CollectedOutput {
+    id: string;
+    path: string;
+}
+export interface VerificationResult {
+    passed: boolean;
+    output?: string;
+}
+export interface ModelAdapterDefinition {
+    readonly modelName: string;
+    /** Params this model accepts via `--param key=value`; empty/omitted if none. */
+    readonly params?: ParamDescriptor[];
+    validateInput(inputPath: string): Promise<void>;
+    installPlan(context: InstallContext): Promise<InstallPlan>;
+    command(context: RunContext): Promise<import("@moldesk/registry").CommandSpec>;
+    collectOutputs(context: RunContext): Promise<CollectedOutput[]>;
+    verifyInstallation(context: InstallContext): Promise<VerificationResult>;
+    /**
+     * Optional hook for params whose correct default depends on which platform's
+     * runtime entry was actually installed (e.g. Boltz's `accelerator`: `mps` on a
+     * Darwin/boltz-community install, `gpu` on a Linux/CUDA install) rather than a
+     * single static `ParamDescriptor.default`. When present, `runModel` calls this
+     * *before* `validateParams`, merging the result in as additional defaults — a
+     * key here only fills in when the caller didn't explicitly supply `--param
+     * <key>=...`, and a declared `ParamDescriptor.default` only applies when this
+     * hook doesn't supply that key. This makes the resolved value visible in
+     * `run.json`'s `parameters.effective` up front, not only deep inside `command()`.
+     */
+    resolveParamDefaults?(context: ResolveParamDefaultsContext): Record<string, unknown>;
+    /**
+     * Optional hook for models whose job file references companion files that must
+     * be safely staged alongside the primary input (e.g. DiffDock-L's job JSON
+     * referencing a separate protein PDB and ligand file). Given the *original*
+     * (pre-copy) resolved job file path, returns the companion references to
+     * stage; `run.ts` then validates and copies each one via
+     * `@moldesk/runtime`'s `stageCompanionInputs` and passes the staged paths back
+     * as `RunContext.companionInputs`. Absent means unchanged single-file
+     * behavior — no companion staging occurs. All job-format-specific parsing
+     * (what a reference means, how it's found) stays here in the adapter; `core`/
+     * `runtime` only provide generic, validated staging.
+     */
+    resolveCompanionInputs?(inputPath: string): Promise<import("@moldesk/runtime").CompanionInputRef[]>;
+}
+export { adapterCatalog, getAdapter, hasAdapter, validateAdapterCatalog } from "./catalog.js";
+export { validateParams, type ParamValidationResult } from "./params.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { adapterCatalog, getAdapter, hasAdapter, validateAdapterCatalog } from "./catalog.js";
+export { validateParams } from "./params.js";

package/dist/ligandmpnn/index.d.ts

@@ -0,0 +1,2 @@
+import type { ModelAdapterDefinition } from "../index.js";
+export declare const ligandmpnnAdapter: ModelAdapterDefinition;

package/dist/ligandmpnn/index.js

@@ -0,0 +1,80 @@
+import fs from "node:fs";
+import path from "node:path";
+import { MoldeskError } from "@moldesk/registry";
+import { runCommand } from "@moldesk/runtime";
+import { collectGlobOutputs } from "../outputs.js";
+const CHECKPOINT_TARGET = path.join("model_params", "ligandmpnn_v_32_010_25.pt");
+/** run.py writes `<out_folder>/seqs/<pdb_name>.fa` (verified against the pinned source revision). */
+const OUTPUTS = [{ id: "sequences", glob: "seqs/*.fa", required: true }];
+const PARAMS = [
+    { name: "temperature", type: "number", default: 0.1, min: 0, description: "Temperature to sample sequences" },
+    { name: "seed", type: "number", default: 0, description: "Random seed for torch, numpy, and python random" },
+    { name: "batch_size", type: "number", default: 1, min: 1, description: "Number of sequences to generate per pass" },
+    { name: "number_of_batches", type: "number", default: 1, min: 1, description: "Number of times to design sequences using the batch size" },
+];
+export const ligandmpnnAdapter = {
+    modelName: "ligandmpnn",
+    params: PARAMS,
+    async validateInput(inputPath) {
+        if (!fs.existsSync(inputPath)) {
+            throw new MoldeskError({
+                code: "INVALID_RUN_INPUT",
+                message: `Input file not found: ${inputPath}.`,
+                remediation: "Provide a path to an existing .pdb file.",
+            });
+        }
+        if (path.extname(inputPath).toLowerCase() !== ".pdb") {
+            throw new MoldeskError({
+                code: "INVALID_RUN_INPUT",
+                message: `LigandMPNN requires a .pdb input file, got "${path.extname(inputPath) || "(no extension)"}".`,
+                remediation: "Provide a .pdb structure file.",
+            });
+        }
+    },
+    async installPlan(_context) {
+        return {
+            steps: [
+                { id: "source", description: "Fetch the pinned LigandMPNN source revision" },
+                { id: "checkpoint", description: "Download and checksum the LigandMPNN checkpoint" },
+                { id: "python", description: "Create an isolated managed Python 3.11 environment" },
+                { id: "dependencies", description: "Install pinned Python dependencies" },
+                { id: "verify", description: "Verify source, checkpoint, and Python imports" },
+            ],
+        };
+    },
+    async command(context) {
+        const params = context.params;
+        const args = [
+            path.join(context.modelDir, "source", "run.py"),
+            "--pdb_path", context.inputPath,
+            "--out_folder", context.outputDir,
+            // run.py defaults to model_type=protein_mpnn; must be set explicitly for LigandMPNN.
+            "--model_type", "ligand_mpnn",
+            "--checkpoint_ligand_mpnn", path.join(context.assetsDir, CHECKPOINT_TARGET),
+        ];
+        if (params.temperature !== undefined)
+            args.push("--temperature", String(params.temperature));
+        if (params.seed !== undefined)
+            args.push("--seed", String(params.seed));
+        if (params.batch_size !== undefined)
+            args.push("--batch_size", String(params.batch_size));
+        if (params.number_of_batches !== undefined)
+            args.push("--number_of_batches", String(params.number_of_batches));
+        return { executable: context.runtimeExecutable, args };
+    },
+    async collectOutputs(context) {
+        return collectGlobOutputs(context.outputDir, OUTPUTS);
+    },
+    async verifyInstallation(context) {
+        const requiredFiles = [
+            path.join(context.modelDir, "source", "run.py"),
+            path.join(context.assetsDir, CHECKPOINT_TARGET),
+        ];
+        const missing = requiredFiles.filter((file) => !fs.existsSync(file));
+        if (missing.length > 0)
+            return { passed: false, output: `Missing ${missing.join(", ")}` };
+        const python = path.join(context.modelDir, ".venv", "bin", "python");
+        const result = await (context.runner ?? runCommand)(python, ["-c", "import numpy, prody, torch"], { timeoutMs: 120_000 });
+        return { passed: result.code === 0, output: (result.code === 0 ? result.stdout : result.stderr).trim() };
+    },
+};

package/dist/ligandmpnn/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ligandmpnn/index.test.js

@@ -0,0 +1,85 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { ligandmpnnAdapter } from "./index.js";
+const dirs = [];
+function tempDir() {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "moldesk-ligandmpnn-test-"));
+    dirs.push(dir);
+    return dir;
+}
+afterEach(() => {
+    for (const dir of dirs.splice(0))
+        fs.rmSync(dir, { recursive: true, force: true });
+});
+describe("ligandmpnnAdapter.validateInput", () => {
+    it("accepts an existing .pdb file", async () => {
+        const dir = tempDir();
+        const input = path.join(dir, "structure.pdb");
+        fs.writeFileSync(input, "ATOM\n");
+        await expect(ligandmpnnAdapter.validateInput(input)).resolves.toBeUndefined();
+    });
+    it("rejects a missing file", async () => {
+        await expect(ligandmpnnAdapter.validateInput(path.join(tempDir(), "missing.pdb"))).rejects.toMatchObject({
+            code: "INVALID_RUN_INPUT",
+        });
+    });
+    it("rejects a non-.pdb extension", async () => {
+        const dir = tempDir();
+        const input = path.join(dir, "structure.cif");
+        fs.writeFileSync(input, "ATOM\n");
+        await expect(ligandmpnnAdapter.validateInput(input)).rejects.toMatchObject({ code: "INVALID_RUN_INPUT" });
+    });
+});
+describe("ligandmpnnAdapter.command", () => {
+    it("always sets --model_type ligand_mpnn and an absolute checkpoint path", async () => {
+        const spec = await ligandmpnnAdapter.command({
+            manifestName: "ligandmpnn",
+            inputPath: "/run/input/structure.pdb",
+            outputDir: "/run/output",
+            modelDir: "/models/ligandmpnn",
+            assetsDir: "/models/ligandmpnn/assets",
+            params: { temperature: 0.1, seed: 0, batch_size: 1, number_of_batches: 1 },
+            runtimeExecutable: "/models/ligandmpnn/.venv/bin/python",
+        });
+        expect(spec.args).toContain("--model_type");
+        expect(spec.args).toContain("ligand_mpnn");
+        expect(spec.args).toContain("--checkpoint_ligand_mpnn");
+        expect(spec.args).toContain(path.join("/models/ligandmpnn/assets", "model_params", "ligandmpnn_v_32_010_25.pt"));
+        expect(spec.args).toContain("--temperature");
+        expect(spec.args).toContain("0.1");
+    });
+});
+describe("ligandmpnnAdapter.collectOutputs", () => {
+    it("collects generated .fa files from the seqs/ subdirectory", async () => {
+        const dir = tempDir();
+        const outputDir = path.join(dir, "output");
+        fs.mkdirSync(path.join(outputDir, "seqs"), { recursive: true });
+        fs.writeFileSync(path.join(outputDir, "seqs", "structure.fa"), ">structure\nMKV\n");
+        const outputs = await ligandmpnnAdapter.collectOutputs({
+            manifestName: "ligandmpnn",
+            inputPath: path.join(dir, "input", "structure.pdb"),
+            outputDir,
+            modelDir: dir,
+            assetsDir: path.join(dir, "assets"),
+            params: {},
+            runtimeExecutable: "python",
+        });
+        expect(outputs).toEqual([{ id: "sequences", path: path.join(outputDir, "seqs", "structure.fa") }]);
+    });
+    it("throws MISSING_REQUIRED_OUTPUT when no .fa files were produced", async () => {
+        const dir = tempDir();
+        const outputDir = path.join(dir, "output");
+        fs.mkdirSync(outputDir, { recursive: true });
+        await expect(ligandmpnnAdapter.collectOutputs({
+            manifestName: "ligandmpnn",
+            inputPath: path.join(dir, "input", "structure.pdb"),
+            outputDir,
+            modelDir: dir,
+            assetsDir: path.join(dir, "assets"),
+            params: {},
+            runtimeExecutable: "python",
+        })).rejects.toMatchObject({ code: "MISSING_REQUIRED_OUTPUT" });
+    });
+});

package/dist/opendde/index.d.ts

@@ -0,0 +1,2 @@
+import type { ModelAdapterDefinition } from "../index.js";
+export declare const openddeAdapter: ModelAdapterDefinition;