m3triq 0.2.14 → 0.2.15

package/README.md

@@ -95,12 +95,47 @@ m3t predict esmfold2-batch inputs.json                        # fold N complexes
 
 # 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
 
 # OpenFold3 — AlphaFold3-class complex (protein + DNA/RNA + ligand); real MSAs
 m3t predict openfold3 --protein EVQL... --protein DIQM...      # complex, auto-paired
 m3t predict openfold3 --protein MKFL... --ligand ATP --depth exhaustive
 ```
 
+## Carbohydrate / Glycan Co-folding
+
+Protein–carbohydrate interactions (e.g. lectins, phage receptor-binding proteins,
+glycan-recognizing binders) are poorly served by classical docking — Vina/GNINA
+score sugars badly. The reliable route is to **define** the glycan, then **co-fold**
+it with the protein in an AlphaFold3-class model.
+
+```bash
+# Define a glycan: IUPAC-condensed → SMILES + 3D SDF + per-residue CCD/bond decomposition
+m3t glycan build "Gal(b1-4)GlcNAc"
+m3t glycan build "Neu5Ac(a2-3)Gal(b1-4)Glc" --out sialyllactose.sdf --attach N-linked
+
+# 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
+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` 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
+  stereochemistry. Validate ring pucker / glycosidic torsions on the output.
+- `--depth exhaustive` (metagenomic envDB) is recommended for orphan / phage / bacterial
+  families where standard databases come back sparse.
+
 ## MSA Generation
 
 Generate a multiple-sequence alignment (`.a3m`) — the evolutionary input folders use.

package/dist/cli.js

@@ -11,6 +11,7 @@ import { registerJobCommands } from './commands/jobs.js';
 import { registerDockingCommands } from './commands/docking.js';
 import { registerPredictCommands } from './commands/predict.js';
 import { registerMsaCommands } from './commands/msa.js';
+import { registerGlycanCommands } from './commands/glycan.js';
 import { registerChemblCommands } from './commands/chembl.js';
 import { registerSandboxCommands } from './commands/sandbox.js';
 import { registerDesignCommands } from './commands/design.js';
@@ -25,7 +26,7 @@ const program = new Command();
 program
     .name('m3t')
     .description('M3TRIQ — protein-ligand analysis from the terminal')
-    .version('0.2.14')
+    .version('0.2.15')
     .option('--json', 'Output as JSON (machine-readable)')
     .hook('preAction', (thisCommand) => {
     const opts = thisCommand.optsWithGlobals();
@@ -39,6 +40,7 @@ registerJobCommands(program);
 registerDockingCommands(program);
 registerPredictCommands(program);
 registerMsaCommands(program);
+registerGlycanCommands(program);
 registerChemblCommands(program);
 registerSandboxCommands(program);
 registerDesignCommands(program);

package/dist/client.d.ts

@@ -87,7 +87,7 @@ export declare class M3triqClient {
             id: string;
             sequence: string;
         }[];
-        depth: 'standard' | 'exhaustive' | 'custom' | 'fast' | 'deep';
+        depth: 'standard' | 'exhaustive' | 'custom';
         pair: boolean;
         templates?: boolean;
         custom?: {

package/dist/client.js

@@ -166,6 +166,7 @@ export class M3triqClient {
                 title: params.title,
                 description: params.description ?? '',
                 result_data: params.result_data,
+                ...(params.prediction_inputs ? { prediction_inputs: params.prediction_inputs } : {}),
             }),
         });
         if (!res.ok) {
@@ -187,6 +188,7 @@ export class M3triqClient {
                 title: params.title,
                 description: params.description ?? '',
                 result_data: params.result_data,
+                ...(params.prediction_inputs ? { prediction_inputs: params.prediction_inputs } : {}),
             }),
         });
         if (!res.ok) {

package/dist/commands/glycan.d.ts

@@ -0,0 +1,4 @@
+import type { Command } from 'commander';
+import type { GlycanBuildResult } from '../types.js';
+export declare function registerGlycanCommands(program: Command): void;
+export declare function buildGlycanViaMcp(iupac: string, embed3d?: boolean, attachment?: string): Promise<GlycanBuildResult>;

package/dist/commands/glycan.js

@@ -0,0 +1,73 @@
+import fs from 'node:fs';
+import { createAgentsClient } from '../cli.js';
+import { output } from '../output.js';
+export function registerGlycanCommands(program) {
+    const glycan = program
+        .command('glycan')
+        .description('Build / define carbohydrate (glycan) ligands for co-folding and docking');
+    // m3t glycan build "<iupac>"
+    glycan
+        .command('build')
+        .argument('<iupac>', 'Glycan in IUPAC-condensed notation (reducing end on the right). e.g. "Gal(b1-4)GlcNAc"')
+        .description('Build a glycan from IUPAC-condensed notation → SMILES + 3D SDF + CCD/bond decomposition')
+        .option('--out <file.sdf>', 'Write the 3D structure to an SDF file')
+        .option('--no-3d', 'Skip 3D conformer generation (SMILES + decomposition only)')
+        .option('--attach <type>', 'Also emit a protein-glycosylation attachment template: N-linked | O-linked | O-linked-thr')
+        .action(async (iupac, opts) => {
+        await runGlycanBuild(iupac, opts);
+    });
+}
+export async function buildGlycanViaMcp(iupac, embed3d = true, attachment) {
+    const agents = createAgentsClient();
+    const data = (await agents.callMcpTool('rdkit', 'build_glycan', {
+        iupac,
+        embed_3d: embed3d,
+        ...(attachment ? { attachment } : {}),
+    }));
+    if (data.success === false || data.error) {
+        throw new Error(data.error ?? `could not build glycan "${iupac}"`);
+    }
+    return data;
+}
+async function runGlycanBuild(iupac, opts) {
+    const embed3d = opts['3d'] !== false || !!opts.out; // need 3D if writing SDF
+    let result;
+    try {
+        result = await buildGlycanViaMcp(iupac, embed3d, opts.attach);
+    }
+    catch (e) {
+        process.stderr.write(`Error: ${e.message}\n`);
+        process.exit(1);
+        return;
+    }
+    if (opts.out) {
+        if (!result.sdf) {
+            process.stderr.write('Warning: no 3D structure was generated; nothing written.\n');
+        }
+        else {
+            fs.writeFileSync(opts.out, result.sdf);
+            process.stderr.write(`Wrote 3D structure → ${opts.out}\n`);
+        }
+    }
+    const lines = [
+        `Glycan: ${iupac}`,
+        `SMILES: ${result.smiles}`,
+        `Formula: ${result.formula ?? '?'}   MW: ${result.molecular_weight ?? '?'}   rotatable bonds: ${result.n_rotatable_bonds ?? '?'}`,
+    ];
+    if (result.ccd_supported && result.residues) {
+        lines.push(`Residues (${result.n_residues}, reducing-end first): ${result.residues.map(r => `${r.name}[${r.ccd}]`).join(' · ')}`);
+        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)');
+    }
+    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)');
+    }
+    if (result.attachment) {
+        const a = result.attachment;
+        lines.push(`Attachment: glycan ${a.glycan_atom} → protein ${a.protein_residue} ${a.protein_atom} (${a.type})`);
+    }
+    output(result, lines.join('\n'));
+}

package/dist/commands/msa.js

@@ -12,8 +12,7 @@ import { jobUrl, maybeOpenBrowser } from '../url.js';
 //              default; a monomer is never paired). --no-pair to force unpaired.
 // --templates also searches the PDB and saves per-chain structural templates.
 // Produces a downloadable .a3m artifact per chain (+ templates_<chain>.json).
-// (Legacy --depth fast/deep still accepted: fast = standard+unpaired, deep = standard.)
-const MSA_DEPTHS = ['standard', 'exhaustive', 'custom', 'fast', 'deep'];
+const MSA_DEPTHS = ['standard', 'exhaustive', 'custom'];
 export function registerMsaCommands(program) {
     program.command('msa')
         .description('Generate a multiple-sequence alignment (a3m) — per-chain and (for complexes) species-paired')

package/dist/commands/predict.js

@@ -3,6 +3,7 @@ import { createAgentsClient, createClient, getConsoleUrl } from '../cli.js';
 import { requireProject } from '../config.js';
 import { output } from '../output.js';
 import { jobUrl, maybeOpenBrowser } from '../url.js';
+import { buildGlycanViaMcp } from './glycan.js';
 export function registerPredictCommands(program) {
     const predict = program.command('predict').description('Predict 3D structure from sequence (single protein or biomolecular complex)');
     // m3t predict esmfold
@@ -62,6 +63,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"); built to a SMILES ligand. Repeatable.', collectArg, [])
+        .option('--depth <tier>', 'Attach real per-chain MSAs: none (default, NIM-internal) | standard | exhaustive | custom', 'none')
         .option('--samples <n>', 'Number of structure samples (1-25, default: 1)', (v) => parseInt(v, 10), 1)
         .option('--recycling <n>', 'Recycling steps (1-10, default: 3)', (v) => parseInt(v, 10), 3)
         .option('--sampling <n>', 'Diffusion sampling steps (10-1000, default: 50)', (v) => parseInt(v, 10), 50)
@@ -76,7 +79,9 @@ 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('--depth <tier>', 'MSA depth for protein chains: fast | deep | exhaustive | none (default fast)', 'fast')
+        .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('--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)
         .option('--name <name>', 'Custom job title')
@@ -101,6 +106,11 @@ async function runPredict(sequence, method, name) {
     output(data, `${method} prediction created\nJob ID: ${result.job_id.substring(0, 8)}\nLength: ${sequence.length} residues\nEstimated: ${timeEst}`);
 }
 async function runBoltz2(opts) {
+    const depth = normalizeMsaDepth(opts.depth || 'none');
+    if (!['none', 'standard', 'exhaustive', 'custom'].includes(depth)) {
+        process.stderr.write(`Error: --depth must be none | standard | exhaustive | custom, got "${opts.depth}".\n`);
+        process.exit(1);
+    }
     const polymers = [];
     for (const seq of opts.protein)
         polymers.push({ molecule_type: 'protein', sequence: resolveSequence(seq) });
@@ -113,12 +123,23 @@ async function runBoltz2(opts) {
         process.exit(1);
     }
     const ligands = opts.ligand.map(parseLigand);
+    // Glycans → SMILES ligands (Boltz-2 has no inter-entity bond field, so a glycan
+    // rides in as one SMILES molecule).
+    for (const g of opts.glycan) {
+        const built = await buildGlycanViaMcp(g, false);
+        if (!built.smiles) {
+            process.stderr.write(`Error: could not build glycan "${g}".\n`);
+            process.exit(1);
+        }
+        process.stderr.write(`Glycan "${g}" → SMILES ligand (${built.formula ?? '?'})\n`);
+        ligands.push({ smiles: built.smiles });
+    }
     const project = requireProject();
     const client = createClient();
     const agents = createAgentsClient();
     const consoleUrl = getConsoleUrl();
     const summary = describeComplex(polymers, ligands);
-    process.stderr.write(`Boltz-2: ${summary}\n`);
+    process.stderr.write(`Boltz-2: ${summary}${depth !== 'none' ? ` (MSA depth=${depth})` : ''}\n`);
     process.stderr.write('Running prediction (NVIDIA NIM, ~1-5 min)...');
     const startTime = Date.now();
     const mcpData = await agents.callMcpTool('bionemo', 'predict_structure_boltz2', {
@@ -127,6 +148,7 @@ async function runBoltz2(opts) {
         diffusion_samples: opts.samples,
         recycling_steps: opts.recycling,
         sampling_steps: opts.sampling,
+        msa_depth: depth,
     });
     const result = mcpData;
     if (result.error || !result.success) {
@@ -152,8 +174,18 @@ async function runBoltz2(opts) {
             quality: result.quality,
             num_structures_returned: result.num_structures_returned,
             diffusion_samples: result.diffusion_samples,
+            msa_depth: depth,
             model: 'boltz2',
         },
+        prediction_inputs: {
+            model: 'boltz2',
+            msa_depth: depth,
+            n_protein: opts.protein.length,
+            n_dna: opts.dna.length,
+            n_rna: opts.rna.length,
+            ligands: ligands.length,
+            glycans: opts.glycan,
+        },
     });
     const url = jobUrl(consoleUrl, project.id, job.job_id);
     maybeOpenBrowser(url);
@@ -181,10 +213,10 @@ async function runBoltz2(opts) {
     }, lines.join('\n'));
 }
 async function runOpenfold3(opts) {
-    const depth = (opts.depth || 'fast').toLowerCase();
-    const OF3_DEPTHS = ['fast', 'deep', 'exhaustive', 'custom', 'none'];
+    const depth = normalizeMsaDepth(opts.depth || 'standard');
+    const OF3_DEPTHS = ['standard', 'exhaustive', 'custom', 'none'];
     if (!OF3_DEPTHS.includes(depth)) {
-        process.stderr.write(`Error: --depth must be one of ${OF3_DEPTHS.join(' | ')}, got "${opts.depth}".\n`);
+        process.stderr.write(`Error: --depth must be one of ${OF3_DEPTHS.join(' | ')} (fast/deep accepted as aliases), got "${opts.depth}".\n`);
         process.exit(1);
     }
     // Build the OpenFold3 molecules array (proteins get chain ids A, B, ...).
@@ -201,8 +233,46 @@ 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.
+    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;
+        if (useCcd) {
+            const idxToChain = {};
+            for (const res of built.residues) {
+                const id = chainIds[ci++];
+                idxToChain[res.index] = id;
+                molecules.push({ type: 'ligand', id, ccd_codes: [res.ccd] });
+            }
+            for (const b of built.bonds ?? []) {
+                bonds.push({
+                    atom1: [idxToChain[b.child_idx], 1, b.child_atom],
+                    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`);
+        }
+        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 (!built.smiles) {
+                process.stderr.write(`Error: could not build glycan "${g}".\n`);
+                process.exit(1);
+            }
+            molecules.push({ type: 'ligand', id: chainIds[ci++], smiles: built.smiles });
+            process.stderr.write(`Glycan "${g}" → SMILES ligand (${built.formula ?? '?'})\n`);
+        }
+    }
     if (molecules.length === 0) {
-        process.stderr.write('Error: at least one --protein, --dna, --rna, or --ligand is required.\n');
+        process.stderr.write('Error: at least one --protein, --dna, --rna, --ligand, or --glycan is required.\n');
         process.exit(1);
     }
     const project = requireProject();
@@ -210,7 +280,7 @@ async function runOpenfold3(opts) {
     const agents = createAgentsClient();
     const consoleUrl = getConsoleUrl();
     const summary = molecules.map(m => `${m.type}(${m.id})`).join(' + ');
-    process.stderr.write(`OpenFold3: ${summary} (depth=${depth}${opts.templates ? ', +templates' : ''})\n`);
+    process.stderr.write(`OpenFold3: ${summary} (depth=${depth}${opts.templates ? ', +templates' : ''}${bonds.length ? `, ${bonds.length} bonds` : ''})\n`);
     process.stderr.write('Running prediction (NVIDIA NIM; real MSA may cold-start the engine, up to a few min)...');
     const startTime = Date.now();
     const mcpData = await agents.callMcpTool('bionemo', 'predict_complex_structure_openfold3', {
@@ -219,6 +289,7 @@ async function runOpenfold3(opts) {
         templates: !!opts.templates,
         diffusion_samples: opts.samples,
         output_format: 'pdb',
+        ...(bonds.length > 0 ? { bonds } : {}),
     });
     const result = mcpData;
     if (result.error || !result.success) {
@@ -248,6 +319,18 @@ async function runOpenfold3(opts) {
             templates_applied: !!result.templates_applied,
             model: 'openfold3',
         },
+        prediction_inputs: {
+            model: 'openfold3',
+            msa_depth: depth,
+            templates: !!opts.templates,
+            n_protein: opts.protein.length,
+            n_dna: opts.dna.length,
+            n_rna: opts.rna.length,
+            ligands: opts.ligand.length,
+            glycans: opts.glycan,
+            glycan_repr: opts.glycanSmiles ? 'smiles' : 'ccd+bonds',
+            n_bonds: bonds.length,
+        },
     });
     const url = jobUrl(consoleUrl, project.id, job.job_id);
     maybeOpenBrowser(url);
@@ -265,12 +348,24 @@ async function runOpenfold3(opts) {
         lines.push(`pLDDT: ${conf.plddt}`);
     if (opts.templates)
         lines.push(`Templates: ${result.templates_applied ? 'applied' : 'requested but not applied (NIM dropped them)'}`);
+    if (opts.glycan.length > 0)
+        lines.push('Note: validate the glycan geometry (ring pucker / glycosidic torsions) — pLDDT is unreliable for carbohydrates.');
     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'));
 }
 function collectArg(value, prev) {
     return [...prev, value];
 }
+// MSA depth vocabulary aligns with the MSA service (standard|exhaustive|custom|none).
+// fast/deep are accepted as legacy aliases (fast→standard, deep→exhaustive).
+function normalizeMsaDepth(d) {
+    const v = (d || '').toLowerCase();
+    if (v === 'fast')
+        return 'standard';
+    if (v === 'deep')
+        return 'exhaustive';
+    return v;
+}
 function resolveSequence(input) {
     // @path → read file (FASTA-aware: strip header/whitespace)
     if (input.startsWith('@')) {

package/dist/types.d.ts

@@ -128,6 +128,36 @@ export interface Boltz2JobParams {
     title: string;
     result_data: Record<string, unknown>;
     description?: string;
+    prediction_inputs?: Record<string, unknown>;
+}
+export interface GlycanResidue {
+    index: number;
+    name: string;
+    ccd: string;
+}
+export interface GlycanBond {
+    child_idx: number;
+    parent_idx: number;
+    child_atom: string;
+    parent_atom: string;
+    linkage: string;
+}
+export interface GlycanBuildResult {
+    success?: boolean;
+    input?: string;
+    smiles?: string;
+    sdf?: string;
+    formula?: string;
+    molecular_weight?: number;
+    n_rotatable_bonds?: number;
+    n_residues?: number;
+    ccd_supported?: boolean;
+    residues?: GlycanResidue[];
+    bonds?: GlycanBond[];
+    reducing_end?: GlycanResidue;
+    attachment?: Record<string, unknown>;
+    ccd_note?: string;
+    error?: string;
 }
 export interface Openfold3Molecule {
     type: 'protein' | 'dna' | 'rna' | 'ligand';

package/package.json

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