m3triq 0.2.15 → 0.2.18

package/README.md

@@ -78,9 +78,16 @@ GPU-accelerated simulations to validate docking poses.
 ```bash
 m3t md run --protein 5NJ8 --ligand-smiles "CCO" --mode quick
 m3t md run --diffdock-job <job-id> --mode standard
+m3t md run --protein <oriented.pdb> --membrane            # cell-membrane MD (POPC bilayer, CHARMM36)
+m3t md run --protein 5NJ8 --ligand-smiles "CCO" --gpu h100 # run on an H100 (80GB VRAM)
+m3t md run --protein 5NJ8 --ligand-smiles "CCO" --gpu h200 # …or an H200 (141GB, ~1.4× bandwidth)
 m3t md results <job-id>
 ```
 
+`--membrane` runs cell-membrane MD for membrane proteins (GPCRs, transporters, ion channels): the protein is embedded in a POPC lipid bilayer with CHARMM36 instead of a plain water box. The input **must be a membrane-oriented structure** (transmembrane axis along Z, e.g. from the [OPM database](https://opm.phar.umich.edu)) — the worker does not orient the protein for you, so a raw RCSB structure produces a misaligned bilayer.
+
+`--gpu` selects the GPU backend: `a100` (default, GCP A100-40GB), `h100` (Nebius H100-80GB) or `h200` (Nebius H200-141GB) — both Nebius GPUs live in eu-north1. For typical soluble protein-ligand MD the A100 is the cost-effective default; reach for a Nebius GPU when the system is large enough to need the big VRAM (membrane bilayers, large multi-chain complexes) or when you want lower wall-clock latency. `h200` has ~1.4× the memory bandwidth of `h100` (and MD is bandwidth-bound), so it's usually a bit faster for a modestly higher rate. Nebius runs are billed at the matching GPU rate.
+
 ## Structure Prediction
 
 ```bash
@@ -93,6 +100,11 @@ m3t predict esmfold2 --sequence MKFLILLFNILCL...              # monomer
 m3t predict esmfold2 --chain A:EVQL... --chain B:DIQM...      # complex (antibody-antigen, PPI)
 m3t predict esmfold2-batch inputs.json                        # fold N complexes (results in input order)
 
+# AF2-Multimer — fold a protein complex (homo-/hetero-oligomer) with deep MSA + PDB templates
+m3t predict af2multimer --protein MKFL... --copies 3          # homotrimer (the biological unit)
+m3t predict af2multimer --protein EVQL... --protein DIQM...   # hetero-complex (distinct chains)
+m3t predict af2multimer --protein A... --protein B... --copies 2,1   # 2×A + 1×B
+
 # Boltz-2 — biomolecular complex (protein + DNA/RNA + ligand) with binding affinity
 m3t predict boltz2 --protein MKFL... --ligand "CC(=O)O" --rna GGUC...
 m3t predict boltz2 --protein MKFL... --ligand "CC(=O)O" --depth exhaustive   # + real per-chain MSAs
@@ -116,19 +128,19 @@ m3t glycan build "Neu5Ac(a2-3)Gal(b1-4)Glc" --out sialyllactose.sdf --attach N-l
 
 # Co-fold a protein with a glycan
 m3t predict openfold3 --protein MKFL... \
-  --glycan "Man(a1-3)[Man(a1-6)]Man(b1-4)GlcNAc(b1-4)GlcNAc" --depth exhaustive   # CCD + bonds (default)
-m3t predict openfold3 --protein MKFL... --glycan "Gal(b1-4)GlcNAc" --glycan-smiles  # force one SMILES blob
+  --glycan "Man(a1-3)[Man(a1-6)]Man(b1-4)GlcNAc(b1-4)GlcNAc" --depth exhaustive   # one connected SMILES ligand (default)
+m3t predict openfold3 --protein MKFL... --glycan "Gal(b1-4)GlcNAc" --glycan-ccd   # experimental CCD + bondedAtomPairs (see caveat)
 m3t predict boltz2    --protein MKFL... --glycan "Gal(b1-4)GlcNAc" --depth exhaustive
 ```
 
 - **IUPAC-condensed**: reducing end on the **right**, linkages in `()`, branches in `[]`
   (e.g. `Neu5Ac(a2-3)Gal(b1-4)Glc`). Common monosaccharides map to PDB CCD codes.
-- `--glycan` on **OpenFold3** defaults to the **per-residue CCD + glycosidic-bond**
-  (`bondedAtomPairs`) representation — the AF3-glycan literature finds a single SMILES blob
-  "frequently fails to reproduce correct conformations even for simple oligosaccharides".
-  Falls back to SMILES if the glycan can't be decomposed; `--glycan-smiles` forces SMILES.
-  Best-effort: if the hosted model rejects explicit bonds the fold retries as separate
-  ligand entities.
+- `--glycan` defaults to **one connected SMILES ligand**. The AF3-glycan literature
+  recommends per-residue CCD + `bondedAtomPairs` — but that assumes the model honors the
+  bonds, and the **hosted OpenFold3 NIM does not** (verified: a 2-sugar CCD glycan comes out
+  with the sugars ~4 Å apart, disconnected). SMILES is one bonded molecule, so it stays
+  connected. `--glycan-ccd` opts into the CCD path for AF3-proper backends — validate the
+  result with the geometry checker.
 - `--glycan` on **Boltz-2** rides as a single SMILES ligand (Boltz-2 has no inter-entity
   bond field).
 - **pLDDT is unreliable for carbohydrates** — high confidence can accompany wrong

package/dist/cli.js

@@ -26,7 +26,7 @@ const program = new Command();
 program
     .name('m3t')
     .description('M3TRIQ — protein-ligand analysis from the terminal')
-    .version('0.2.15')
+    .version('0.2.18')
     .option('--json', 'Output as JSON (machine-readable)')
     .hook('preAction', (thisCommand) => {
     const opts = thisCommand.optsWithGlobals();
@@ -107,5 +107,5 @@ export function getConsoleUrl() {
 /** Create an agents client for MCP tool calls. */
 export function createAgentsClient() {
     const config = getEffectiveConfig();
-    return new AgentsClient(config.agents_url);
+    return new AgentsClient(config.agents_url, config.api_key ?? '');
 }

package/dist/client.d.ts

@@ -61,6 +61,20 @@ export declare class M3triqClient {
     }): Promise<{
         job_id: string;
     }>;
+    createAf2MultimerComplexJob(params: {
+        project_id: string;
+        chains: {
+            id?: string;
+            sequence: string;
+            count?: number;
+        }[];
+        title?: string;
+        save_structure?: boolean;
+    }): Promise<{
+        job_id: string;
+        task_id?: string;
+        n_chains?: number;
+    }>;
     createEsmfold2BatchJob(params: {
         project_id: string;
         inputs: {
@@ -127,6 +141,7 @@ export declare class M3triqClient {
  */
 export declare class AgentsClient {
     private baseUrl;
-    constructor(baseUrl: string);
+    private apiKey;
+    constructor(baseUrl: string, apiKey?: string);
     callMcpTool(server: string, tool: string, params?: Record<string, unknown>): Promise<McpCallResult>;
 }

package/dist/client.js

@@ -123,6 +123,9 @@ export class M3triqClient {
     async createEsmcEmbedJob(params) {
         return this.request('POST', '/api/jobs/create_esmc_embed/', params);
     }
+    async createAf2MultimerComplexJob(params) {
+        return this.request('POST', '/api/jobs/create_af2_multimer_complex/', params);
+    }
     async createEsmfold2BatchJob(params) {
         return this.request('POST', '/api/jobs/create_esmfold2_batch/', params);
     }
@@ -229,14 +232,21 @@ export class M3triqClient {
  */
 export class AgentsClient {
     baseUrl;
-    constructor(baseUrl) {
+    apiKey;
+    constructor(baseUrl, apiKey = '') {
         this.baseUrl = baseUrl.replace(/\/$/, '');
+        this.apiKey = apiKey;
     }
     async callMcpTool(server, tool, params = {}) {
         const url = `${this.baseUrl}/mcp/call`;
+        // /mcp/call runs MCP tools with the platform's internal credentials, so it authenticates
+        // the caller and checks project access. Without this header the request is rejected 403.
+        const headers = { 'Content-Type': 'application/json' };
+        if (this.apiKey)
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
         const res = await fetch(url, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
+            headers,
             body: JSON.stringify({ server, tool, params }),
         });
         if (!res.ok) {

package/dist/commands/glycan.js

@@ -59,11 +59,11 @@ async function runGlycanBuild(iupac, opts) {
         if (result.bonds && result.bonds.length > 0) {
             lines.push(`Glycosidic bonds: ${result.bonds.map(b => `${b.child_idx}.${b.child_atom}→${b.parent_idx}.${b.parent_atom} (${b.linkage})`).join(', ')}`);
         }
-        lines.push('Use with: m3t predict openfold3 --protein <seq> --glycan "' + iupac + '" --depth exhaustive   (co-folds as CCD + bonds)');
+        lines.push('Use with: m3t predict openfold3 --protein <seq> --glycan "' + iupac + '" --depth exhaustive   (co-folds as one connected SMILES ligand)');
     }
     else if (result.ccd_note) {
         lines.push(`Note: ${result.ccd_note}`);
-        lines.push('Use with: m3t predict openfold3 --protein <seq> --glycan "' + iupac + '" --depth exhaustive   (falls back to SMILES ligand)');
+        lines.push('Use with: m3t predict openfold3 --protein <seq> --glycan "' + iupac + '" --depth exhaustive   (SMILES ligand)');
     }
     if (result.attachment) {
         const a = result.attachment;

package/dist/commands/md.js

@@ -17,15 +17,25 @@ export function registerMdCommands(program) {
         .option('--mode <mode>', 'Simulation mode: quick (10ns ~1hr) or standard (50ns ~5hrs)', 'quick')
         .option('--ns <n>', 'Override simulation duration in nanoseconds (1-100)')
         .option('--temperature <K>', 'Temperature in Kelvin', '300')
+        .option('--membrane', 'Cell-membrane MD: embed the protein in a POPC lipid bilayer (CHARMM36) instead of a water box. For membrane proteins (GPCRs, transporters, channels). Provide a membrane-oriented structure (TM axis along Z, e.g. from OPM); larger system so it runs slower than a soluble-protein MD of the same length.')
+        .option('--gpu <type>', 'GPU backend: a100 (default, GCP A100-40GB), h100 (Nebius H100-80GB) or h200 (Nebius H200-141GB) — both Nebius GPUs are in eu-north1. Use a Nebius GPU for large membrane/complex systems that need the big VRAM, or for lower wall-clock latency; h200 has ~1.4× h100 bandwidth (MD is bandwidth-bound) for a modestly higher rate.', 'a100')
         .description('Submit a molecular dynamics simulation job')
         .action(async (opts) => {
         const project = requireProject();
         const agents = createAgentsClient();
+        const gpu = String(opts.gpu || 'a100').toLowerCase();
+        if (gpu !== 'a100' && gpu !== 'h100' && gpu !== 'h200') {
+            process.stderr.write(`Error: --gpu must be 'a100', 'h100' or 'h200' (got '${opts.gpu}')\n`);
+            process.exit(1);
+        }
         const params = {
             mode: opts.mode,
             temperature_k: parseFloat(opts.temperature),
             project_id: project.id,
+            gpu,
         };
+        if (opts.membrane)
+            params.membrane = true;
         // Input source: DiffDock job OR protein + ligand
         if (opts.diffdockJob) {
             params.diffdock_job_id = opts.diffdockJob;
@@ -60,7 +70,7 @@ export function registerMdCommands(program) {
         }
         if (opts.ns)
             params.simulation_ns = parseFloat(opts.ns);
-        process.stderr.write(`Submitting MD simulation (${opts.mode} mode)...\n`);
+        process.stderr.write(`Submitting MD simulation (${opts.mode} mode, ${gpu.toUpperCase()} GPU)...\n`);
         const data = await agents.callMcpTool('md', 'run_md_simulation', params);
         // Extract job ID from response
         const jobId = extractJobId(data);

package/dist/commands/predict.js

@@ -72,6 +72,16 @@ export function registerPredictCommands(program) {
         .action(async (opts) => {
         await runBoltz2(opts);
     });
+    // m3t predict af2multimer — fold a protein complex (homo-/hetero-oligomer) with AF2-Multimer
+    predict.command('af2multimer')
+        .description('Fold a protein complex (homo-/hetero-oligomer) with AF2-Multimer — deep MSA + PDB templates (self-hosted A100). Use --copies for an oligomer (e.g. a homotrimer).')
+        .option('--protein <seq>', 'Protein chain sequence (or @path to file). Repeatable for hetero-complexes (distinct chains).', collectArg, [])
+        .option('--copies <csv>', 'Copies per --protein: a single number applies to all (homomer), or a CSV paired by order (e.g. "2,1"). Default 1.', '1')
+        .option('--no-save-structure', 'Do not save the predicted structure to the project')
+        .option('--name <name>', 'Custom job title')
+        .action(async (opts) => {
+        await runAf2Multimer(opts);
+    });
     // m3t predict openfold3
     predict.command('openfold3')
         .description('Predict biomolecular complex (protein + DNA/RNA + ligand) with OpenFold3 / AlphaFold3-class (NVIDIA NIM). Real MSAs + optional PDB templates.')
@@ -79,8 +89,8 @@ export function registerPredictCommands(program) {
         .option('--dna <seq>', 'DNA sequence (or @path to file). Repeatable.', collectArg, [])
         .option('--rna <seq>', 'RNA sequence (or @path to file). Repeatable.', collectArg, [])
         .option('--ligand <smiles_or_ccd>', 'Ligand as SMILES or CCD code (e.g. ATP). Repeatable.', collectArg, [])
-        .option('--glycan <iupac>', 'Carbohydrate in IUPAC-condensed notation (e.g. "Gal(b1-4)GlcNAc"). Co-folded as a proper multi-residue sugar chain (per-residue CCD codes + glycosidic bonds, the AF3-recommended representation). Repeatable.', collectArg, [])
-        .option('--glycan-smiles', 'Attach each glycan as a single SMILES blob instead of the default per-residue CCD + bonds. Less accurate for conformation; use only if the CCD path misbehaves.')
+        .option('--glycan <iupac>', 'Carbohydrate in IUPAC-condensed notation (e.g. "Gal(b1-4)GlcNAc"). Co-folded as one connected SMILES ligand (default — the hosted OpenFold3 NIM does NOT honor inter-residue bonds, so a CCD chain comes out disconnected). Repeatable.', collectArg, [])
+        .option('--glycan-ccd', 'EXPERIMENTAL: co-fold the glycan as per-residue CCD codes + glycosidic bondedAtomPairs (the AF3-recommended form). Verified that the hosted OpenFold3 NIM IGNORES the bonds → sugars come out ~4 A apart, disconnected; only use with a backend that honors bondedAtomPairs.')
         .option('--depth <tier>', 'MSA depth for protein chains: standard (UniRef30, default) | exhaustive (+envDB, best for orphan/phage) | custom | none. (fast→standard, deep→exhaustive accepted)', 'standard')
         .option('--templates', 'Seed the fold with PDB structural templates per protein chain (OpenFold3 self-aligns).')
         .option('--samples <n>', 'Number of diffusion samples (1-25, default: 1)', (v) => parseInt(v, 10), 1)
@@ -233,17 +243,15 @@ async function runOpenfold3(opts) {
         const parsed = parseLigand(lig);
         molecules.push({ type: 'ligand', id: chainIds[ci++], ...('ccd_code' in parsed ? { ccd_codes: [parsed.ccd_code] } : { smiles: parsed.smiles }) });
     }
-    // Glycans: by default a proper multi-residue chain (one single-CCD ligand per sugar
-    // + glycosidic bonds); --glycan-smiles forces a single SMILES ligand instead.
+    // Glycans: default to ONE connected SMILES ligand. The AF3 literature recommends
+    // per-residue CCD + bondedAtomPairs, but that assumes the model honors the bonds —
+    // and the hosted OpenFold3 NIM does NOT (verified: a 2-residue CCD glycan comes out
+    // with the sugars ~4 A apart, disconnected). SMILES is one bonded molecule, so it
+    // stays connected. --glycan-ccd opts into the CCD path for AF3-proper backends.
     const bonds = [];
     for (const g of opts.glycan) {
         const built = await buildGlycanViaMcp(g, false);
-        // DEFAULT to the per-residue CCD + glycosidic-bond representation: the AF3 glycan
-        // literature finds a single SMILES blob "frequently fails to reproduce correct
-        // conformations even for simple linear oligosaccharides", and recommends
-        // bondedAtomPairs + monosaccharide CCD codes. Fall back to SMILES only when the
-        // glycan can't be decomposed, or when the user forces it with --glycan-smiles.
-        const useCcd = !opts.glycanSmiles && built.ccd_supported && !!built.residues && built.residues.length > 0;
+        const useCcd = !!opts.glycanCcd && built.ccd_supported && !!built.residues && built.residues.length > 0;
         if (useCcd) {
             const idxToChain = {};
             for (const res of built.residues) {
@@ -257,11 +265,11 @@ async function runOpenfold3(opts) {
                     atom2: [idxToChain[b.parent_idx], 1, b.parent_atom],
                 });
             }
-            process.stderr.write(`Glycan "${g}" → ${built.residues.length} sugar residues + ${built.bonds?.length ?? 0} glycosidic bonds (CCD + bondedAtomPairs)\n`);
+            process.stderr.write(`Glycan "${g}" → ${built.residues.length} sugar residues + ${built.bonds?.length ?? 0} glycosidic bonds (CCD + bondedAtomPairs) — NOTE: the hosted NIM may not honor the bonds (sugars can come out disconnected); validate with the geometry checker.\n`);
         }
         else {
-            if (!opts.glycanSmiles && !built.ccd_supported) {
-                process.stderr.write(`Glycan "${g}": CCD decomposition unavailable (${built.ccd_note ?? 'unsupported monosaccharide/topology'}); falling back to a single SMILES ligand.\n`);
+            if (opts.glycanCcd && !built.ccd_supported) {
+                process.stderr.write(`Glycan "${g}": CCD decomposition unavailable (${built.ccd_note ?? 'unsupported monosaccharide/topology'}); using a single SMILES ligand.\n`);
             }
             if (!built.smiles) {
                 process.stderr.write(`Error: could not build glycan "${g}".\n`);
@@ -328,7 +336,7 @@ async function runOpenfold3(opts) {
             n_rna: opts.rna.length,
             ligands: opts.ligand.length,
             glycans: opts.glycan,
-            glycan_repr: opts.glycanSmiles ? 'smiles' : 'ccd+bonds',
+            glycan_repr: opts.glycanCcd ? 'ccd+bonds' : 'smiles',
             n_bonds: bonds.length,
         },
     });
@@ -353,6 +361,47 @@ async function runOpenfold3(opts) {
     lines.push(`View: ${url}`);
     output({ job_id: job.job_id, elapsed_seconds: elapsed, complex: result.complex, quality: result.quality, confidence: result.confidence, msa_depth: depth, templates_requested: !!opts.templates, templates_applied: !!result.templates_applied, url }, lines.join('\n'));
 }
+async function runAf2Multimer(opts) {
+    const proteins = opts.protein.map(resolveSequence);
+    if (proteins.length === 0) {
+        process.stderr.write('Error: at least one --protein is required.\n');
+        process.exit(1);
+    }
+    // Parse --copies: a single value applies to every chain (homomer); a CSV pairs by order.
+    const copyTokens = (opts.copies || '1').split(',').map(s => parseInt(s.trim(), 10));
+    if (copyTokens.some(n => !Number.isFinite(n) || n < 1)) {
+        process.stderr.write(`Error: --copies must be positive integers, got "${opts.copies}".\n`);
+        process.exit(1);
+    }
+    const chains = proteins.map((sequence, i) => ({
+        sequence,
+        count: copyTokens.length === 1 ? copyTokens[0] : (copyTokens[i] ?? 1),
+    }));
+    const totalChains = chains.reduce((s, c) => s + c.count, 0);
+    if (totalChains > 12) {
+        process.stderr.write(`Error: total chains (with copies) is ${totalChains}; max 12.\n`);
+        process.exit(1);
+    }
+    const project = requireProject();
+    const client = createClient();
+    const consoleUrl = getConsoleUrl();
+    const summary = chains.map(c => `${c.sequence.length}aa×${c.count}`).join(' + ');
+    const result = await client.createAf2MultimerComplexJob({
+        project_id: project.id,
+        chains,
+        title: opts.name,
+        save_structure: opts.saveStructure !== false,
+    });
+    const url = jobUrl(consoleUrl, project.id, result.job_id);
+    maybeOpenBrowser(url);
+    const lines = [
+        `AF2-Multimer complex queued (${totalChains} chains: ${summary})`,
+        `Job ID: ${result.job_id.substring(0, 8)}`,
+        `Deep MSA + PDB templates; ~30-60s warm, ~5-8 min cold A100 start`,
+        `View: ${url}`,
+    ];
+    output({ job_id: result.job_id, n_chains: totalChains, chains, url }, lines.join('\n'));
+}
 function collectArg(value, prev) {
     return [...prev, value];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "m3triq",
-  "version": "0.2.15",
+  "version": "0.2.18",
   "description": "M3TRIQ \u2014 protein-ligand analysis from the terminal",
   "type": "module",
   "bin": {