{"id":57224,"plugin_id":"plugin_asdk_app_6a5fc156fad88191a3977b60131d7391","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-10-27T00:11:09.999Z","digest":"401e03600a07fb13cd6eee9406b85c0b5623d67c2dfeed1e5680a853cdac7ead","against":7399,"payload":{"description":"Author, validate, run, monitor, and read results from declarative multi-step Tamarind Bio pipelines through MCP with submitPipeline, validatePipeline, getPipelineSchema, getPipelineTemplate, listPipelineTemplates, getPipelineRun, getPipelineRunResults, listPipelineRuns, and stopPipelineRun. Use when stages depend on earlier stages (design to fold to score), or to run or re-run a saved pipeline template. Not for a single job, one independent batch, or CLI orchestration.","included_files":[{"relative_path":"agents/openai.yaml","size_in_bytes":427}],"name":"tamarind-mcp-pipeline","skill_md_contents":"---\nname: tamarind-mcp-pipeline\ndescription: Author, validate, run, monitor, and read results from declarative multi-step Tamarind Bio pipelines through MCP with submitPipeline, validatePipeline, getPipelineSchema, getPipelineTemplate, listPipelineTemplates, getPipelineRun, getPipelineRunResults, listPipelineRuns, and stopPipelineRun. Use when stages depend on earlier stages (design to fold to score), or to run or re-run a saved pipeline template. Not for a single job, one independent batch, or CLI orchestration.\n---\n\n# Run Tamarind pipelines through MCP\n\nA pipeline is a declarative graph the server runs for you: it dispatches each step's jobs, waits for\ntheir molecules to land, and feeds them to the next step. Do not chain jobs by hand out of\n`submitJob`/`submitBatch` polling.\n\n| tool | use it for |\n|---|---|\n| `getPipelineSchema` | the IR schema + authoring guide — **read before writing a graph** |\n| `listPipelineTemplates` | find a saved pipeline instead of authoring one |\n| `getPipelineTemplate` | one template's graph + the manifest of inputs you must bind |\n| `validatePipeline` | judge a run **before** it spends compute |\n| `submitPipeline` | run it (spends compute) |\n| `getPipelineRun` | poll status and per-step progress |\n| `getPipelineRunResults` | read the molecules and scores each step produced |\n| `listPipelineRuns` | find runs — they do **not** appear in `getJobs()` |\n| `stopPipelineRun` | stop a run — **not** `cancelBatch` |\n\n## Path A — run a saved template\n\nCheaper and safer than authoring. Always look before you author.\n\n1. `listPipelineTemplates(search=...)` → pick an `id`. Always search or use a small limit; an\n   unfiltered listing can exceed the response cap. Rows are summaries and carry no graph, and a\n   name may not describe what the graph does — confirm against the IR in step 2, never the name.\n   When several match, compare their fan-out (tool nodes, and any stage that multiplies molecules)\n   before choosing: they can differ several-fold in cost while all validating clean.\n   `owner` defaults to `\"org\"`, so you see templates you did not create; narrow with `owner=\"mine\"`.\n2. `getPipelineTemplate(templateId)` → read **`inputs`**: the manifest of what you must bind — the\n   node id to key each binding by, molecule-vs-file, the molecule type, reference chain labels, and\n   any `residueFields`.\n3. Confirm the tools the saved graph names still exist with `getJobSchema(<tool>)` — validation\n   does not check that — and read your output column names from it while you are there.\n4. `validatePipeline(...)` until `valid: true`.\n5. `submitPipeline(...)`.\n\n**Listed does not mean runnable.** Someone else's unpublished template lists fine, then fails\nvalidation with `403 pipeline_permission_denied`. That is terminal — pick another or ask the owner to\npublish. Prefer rows where `isPublished` is true or `createdBy` is you.\n\n`settings` and `version` are **reference-mode only**. `settings` is `{nodeId: {settingKey: value}}`,\nlimited to the template's editable settings. Omit `version` for published-then-latest.\n\n## Path B — author a graph inline\n\nOnly when nothing suitable exists. Passing `pipeline` to `submitPipeline` saves a new unpublished\ntemplate you own and runs it in one call.\n\nCall `getPipelineSchema()` first, every time — it is fetched live, so it always matches the deployed\nvalidator. Authoring blind reliably produces graphs the API rejects. Rules from it you cannot guess:\n\n- **No edge list.** Topology lives inside each node's `inputs`, where a node names what it consumes.\n- **Omit `metadata.defaultGroup` on an inline graph.** It is required only when SAVING a template;\n  inline, the binding supplies the group. Do not hunt for a group id or borrow one — submit fills a\n  *missing* `defaultGroup` from your binding but **never replaces one you left in**, and an\n  unresolvable id is not rejected, so a placeholder becomes a permanent reference to molecules the\n  run never used.\n- **A `filter` must do something:** `intersect: true` (which needs ≥2 sources) or ≥1 rule. An empty\n  filter is invalid, not a pass-through.\n\n### Filter rules\n\nRules narrow a filter's sources, in order. Two kinds — a predicate, and a ranked cut:\n\n```jsonc\n{\"kind\": \"jsonlogic\", \"rule\": {\">\": [{\"var\": {\"producerNodeId\": \"score\", \"columnName\": \"QED\"}}, 0.5]}}\n{\"kind\": \"top_k\", \"k\": 2,\n \"rank_by\": [{\"field\": {\"producerNodeId\": \"score\", \"columnName\": \"QED\"}, \"order\": \"desc\"}]}\n```\n\n`producerNodeId` is the upstream **node id**, not a tool name. `columnName` must be that tool's\nexact output header — read it from `getJobSchema(<tool>)`, never guess: headers carry spaces,\nparens and units (`\"SA Score\"`, `\"LogP (Crippen)\"`), and a wrong one still validates clean, so a\nguessed name ranks on nothing. A declared column is not guaranteed to arrive either — confirm the\ncolumn is present in a scored molecule before ranking a whole run on it.\n\n**Barriers.** `intersect: true`, any `top_k`, and a two-input tool with `combination_mode` all wait\nfor **every** upstream molecule before anything downstream dispatches. Size your poll deadline for\nthe slowest molecule, not the median.\n- **Residue selections go in the binding**, never in a node's `settings`.\n\n## Bindings\n\nOne entry per input node, keyed by that node's id. Group ids come from `listMoleculeGroups` /\n`searchMolecules` — but inspect a group narrowly: a single molecule can carry its structure files\ninline and run to hundreds of thousands of characters.\n\nSupply molecules **exactly one way**:\n\n```jsonc\n{\"inputProtein\": {\"group\": \"<groupId>\"}}      // an existing molecule group\n{\"inputProtein\": {\"sequences\": [\"MKT...\"]}}   // or raw values — server mints the group,\n{\"inputLigand\":  {\"smiles\": [\"CCO\"]}}         // and rolls it back if the submit fails\n{\"inputTarget\":  {\"pdbs\": [\"<uploadedPath>\"]}}\n{\"inputLigand\":  {\"sdfs\": [\"<uploadedPath>\"]}}\n{\"inputCsv\":     {\"file\": \"<path>\"}}          // a file input\n```\n\n`pdbs`/`sdfs` take paths relative to your user folder for files you already uploaded — not contents.\n\nTwo optional keys inside a binding:\n\n- **`residuesByChain`**, in one of **two shapes**. Get it right: the wrong shape is refused, and\n  `validatePipeline` reports it as `setting-invalid` on the tool node with a message that never\n  mentions `residuesByChain` and a null `field`, so it does not read like a residue problem:\n\n  ```jsonc\n  // ADVANCED — the default for newly created templates. Per (tool node, field).\n  {\"residuesByChain\": {\"<toolNodeId>\": {\"designedResidues\": {\"A\": \"42-44,58-59\"}}}}\n\n  // SIMPLE — one selection for every residue field this input feeds.\n  {\"residuesByChain\": {\"A\": \"1-76\"}}\n  ```\n\n  The shape is detected from the value: a chain → range **string** is simple, a node → **object** is\n  advanced. `getPipelineTemplate` reports the mode in `simplifiedResidues`. Ranges are always\n  strings, never lists: `\"1-76\"`, `\"42 43 44\"`, `\"10-20,45,60-64\"`.\n- **`chainMapping`** — only when your chain IDs differ from the template's reference chains.\n\n### The residue trap\n\nA non-empty `residueFields` means the run **may** take a selection — **not** that it requires one.\nEntries carry no per-field `required` flag, so the manifest cannot tell you which it is.\n\nInventing one is not a harmless default: it reaches the tool as designed residues, hotspots, or a\nbinding site, constraining the design to the wrong residues and spending GPU on scientifically wrong\noutput **that still looks successful**.\n\nSo do not guess — and do not refuse a runnable template either. Validate with the bindings you\nactually have; a genuinely required selection comes back as `required-field-unset` naming the field.\nAsk the user for the real one then.\n\n`targetsChains` is not a reliable key for `residuesByChain`: it is empty on some entries, and on\nothers names a chain the input does not have (one the graph creates downstream).\n\n## Validate before every submit\n\n`submitPipeline` spends real compute. `validatePipeline` executes and saves nothing. Call it on the\nsame graph and bindings, and only submit on `valid: true`.\n\nIt reads what *describes* the run — `pipeline` or `templateId`+`version`, `bindings`, `settings`,\n`name`. It ignores `runName`, `project` and `idempotencyKey`, which only name and tag the run.\n\nBoth outcomes return HTTP 200 — **read `valid`, do not branch on the status code**; if `valid` is\nabsent entirely, you have an error envelope instead, so read `code`. Each error\ncarries a `code`, `severity`, the `node`, the `field` where there is one, and a fix-it `message`:\n\n| code | usual cause |\n|---|---|\n| `required-field-unset` | often a residue selection — it belongs in the **binding**, not settings |\n| `input-unbound` | an input node with no entry in `bindings` |\n| `tool-unknown` | the node names a tool that does not exist |\n| `setting-invalid` / `param-out-of-range` | a bad node setting |\n| `chain-incompatible` | chain labels do not line up |\n| `molecule-class-incompatible` | upstream does not produce what downstream consumes |\n| `binding-invalid` | the binding's shape — **or a file that does not exist**; its remedy text says `files`, but the key is `file` |\n| `molecule_group_not_found` | the bound group id does not exist, or is not yours |\n\nTwo failure modes to handle deliberately:\n\n- **`validationUnavailable` means NOT JUDGED** — there is no verdict, so do not start editing the\n  graph in response to one. **Read `status`/`code` before retrying:** the flag is also set on a\n  permanent `403 pipeline_permission_denied`, whose hint still says to retry. A 403 is terminal.\n  Retry only a non-403, and if that fails identically every time, report it rather than looping.\n- **`valid: true` is not a guarantee.** It does not confirm the tools exist — a graph naming a\n  nonexistent tool validates clean. Worse, it does **not** enforce `requiresStructure`: a\n  `sequences` binding on an input whose manifest demands a structure returns `valid: true`, and the\n  run then spends GPU on something the first tool cannot consume. Check `requiresStructure` yourself\n  and bind a structure (`group`/`pdbs`) when it is set. If submit rejects a graph validation\n  approved, **believe submit** — re-validating will not reproduce it.\n\n## Submit, then poll\n\n`submitPipeline` returns a run whose `id` is the `runId`. Pass `idempotencyKey` so a retried submit\nis safe, `runName` to name this run explicitly, `project` to stamp an org project on its jobs.\n\n**Check which molecules the run actually used.** A saved template carries its own reference group on\neach input; your binding overrides it, but nothing in the results says which one won, and scoring\nsomeone else's molecules produces a complete, plausible, entirely wrong answer. The submit response\nechoes the group used at `inputs.<nodeId>.group` — confirm it is the group you bound, or a freshly\nminted one if you passed raw values, before trusting anything downstream.\n\nPoll `getPipelineRun(runId)` on a **finite deadline** — never an unbounded loop. Steps are under\n**`nodeRuns`**, each reporting `status`, `jobsTotal`/`jobsComplete`, `outputCount`, `outputGroup`.\n\n- **A step carries two ids.** `id` is that step's own run id; `nodeId` is the stable pipeline node id,\n  and `nodeId` is what `getPipelineRunResults(node=...)` wants.\n- **The order is not stable and is not topological** — a dependent step can be listed ahead of the\n  one it consumes, and the order can change between polls. Index by `nodeId`, never by position.\n\nIf a submit response is ambiguous, find the run with `listPipelineRuns(templateId=...)` before\nretrying — rows carry no `idempotencyKey`, and `name` is not a reliable handle, so the template is\nwhat narrows it. Never submit a second time to resolve uncertainty about the first.\n\n## Read results\n\n`getPipelineRunResults(runId)` returns each step's molecules **with their scores** — what you rank\non. Results appear per step as it finishes, so this works before the run completes; a step with\nnothing yet reports an empty `molecules` list.\n\n**Results do not come back in binding order, and molecule names are opaque.** Never zip results to\nyour inputs positionally — you will mislabel every one. Identify a molecule by its own returned\nfields; note that an input SMILES is canonicalized on the way in, so comparing against the exact\nstring you submitted also fails.\n\nThe envelope's top-level `status` is the **run's**, not the step's — a finished step can sit inside\na response whose `status` still reads `running`.\n\n**The two tools name the same thing differently — do not carry keys across:**\n\n| | array key | node id key |\n|---|---|---|\n| `getPipelineRun` | `nodeRuns` | `nodeId` |\n| `getPipelineRunResults` | `steps` | `node` |\n\n**Scores sit in different places depending on the shape you get. Read whichever you receive:**\n\n- step outputs — id in `complexId`, scores under `scores`, and the molecule's own value in\n  `sequence` (the canonical SMILES for a small molecule) — this is what you identify a result by\n- group molecules — id in `id`, scores under `metadata`\n\nIn both, **scores are keyed by tool name**: `scores[\"<tool>\"][\"MW\"]`, never `scores[\"MW\"]`. This\nholds for a filter step too — a filter runs no tool of its own, so its survivors carry the keys of\nwhichever tools scored them upstream.\n\nIn the group shape, **`metadata[\"<tool>\"]` is a list of every run that ever scored that molecule**,\nnot just yours. Take the entry whose `runId` equals `\"nr-\"` + that step's **`id`** from\n`getPipelineRun` (its `id`, not its `nodeId`). Reading `[0]` silently gives you another run's\nnumbers. Those entries also carry the `jobId`, which is the only place a step's job id is exposed.\n\n**`outputGroup: null` does not mean \"nothing here.\"** It is only the group that step *minted*, and\nwhether a step mints one is a property of the **run**, not the step — the same node of the same\ntemplate version returns a group on one run and `null` on another. Never infer the shape from it: a\nstep enriching its inputs in place, and a filter whose survivors are step outputs, both report null\nwhile holding plenty. Read the step itself.\n\nPaging: `limit` is 1-100 (default 25) and bounds molecules, **not payload**. A molecule accumulates\nevery tool's scores that touched it, so a later step's payload is a superset of the earlier ones' and\neven `node` plus `limit=1` can exceed the response cap on a one-molecule run. Always pass `node`,\nread the last finished step rather than polling each, and pull the fields you need. `cursor` (from\n`nextCursor`) requires `node`.\n\n## Stopping, and finding runs later\n\n- Stop with `stopPipelineRun(runId)`. Finished steps keep their outputs; work in flight is cancelled.\n  **Do not use `cancelBatch`** — it understands only the older job layout and will not stop a run.\n- Find runs with `listPipelineRuns` (filter by `status`, `templateId`, `owner`; here `owner` defaults\n  to `\"mine\"`, unlike templates). **Pipeline runs do not appear in `getJobs()`.**\n\n## Cost and authorization\n\nA run fans out into many jobs and can cost far more than a single submit. Scope is not reported\nanywhere before you submit: a template exposes `editableSettings` names without values and its IR\nomits any setting left at default, so you must compose it yourself — `getJobSchema(<tool>)` for each\nmultiplying setting's default, times your molecule count. The true figure only appears as `jobsTotal`\nafter the run starts. Confirm material scope with the user\nbefore the first `submitPipeline`, and again before re-running with a materially larger binding.\nAuthorization for one run is not authorization for the next.\n\n## Reading a failure\n\nA failed step reports its status in `getPipelineRun`, which does **not** expose a job id. To reach\nthe logs you need one from the group-shape `metadata` entries above; with it, `getJobs`/`getJobLogs`\n(bounded line count) give the tool's own output. Checkpoint the failure rather than resubmitting.\n\n**These reads are eventually consistent, and lag completion by minutes.** A step can report\n`running` with `jobsComplete: 0`, and its results can come back `molecules: []`, well after it has\nactually finished — the timestamps you get later prove it. So before reporting a stall, a partial,\nor an empty step, poll again: the most likely explanation for \"nothing happened\" is that you read\ntoo early. A step at `jobsComplete: 0` while a sibling on the same input has finished is usually\njust queueing. Keep polling to your deadline, then report partial state; never resubmit. Only a run\nwhere **every** job is complete with no progress is a real delivery-side stall — report that one\nwith the `runId` and the step's `node`.\n"},"changes":[{"path":"/description","type":"changed","before":"Orchestrate multiple dependent Tamarind Bio tools as a resumable MCP campaign where successful stages feed later stages, such as design to fold to score. Use when stages depend on earlier artifacts or metrics. Not for one job, one independent batch, a nonexistent submitPipeline call, or CLI orchestration.","after":"Author, validate, run, monitor, and read results from declarative multi-step Tamarind Bio pipelines through MCP with submitPipeline, validatePipeline, getPipelineSchema, getPipelineTemplate, listPipelineTemplates, getPipelineRun, getPipelineRunResults, listPipelineRuns, and stopPipelineRun. Use when stages depend on earlier stages (design to fold to score), or to run or re-run a saved pipeline template. Not for a single job, one independent batch, or CLI orchestration."},{"path":"/included_files","type":"changed","before":[],"after":[{"relative_path":"agents/openai.yaml","size_in_bytes":427}]},{"path":"/skill_md_contents","type":"changed","before":"---\nname: tamarind-mcp-pipeline\ndescription: Orchestrate multiple dependent Tamarind Bio tools as a resumable MCP campaign where successful stages feed later stages, such as design to fold to score. Use when stages depend on earlier artifacts or metrics. Not for one job, one independent batch, a nonexistent submitPipeline call, or CLI orchestration.\n---\n\n# Chain Tamarind jobs through MCP\n\nThe current MCP surface has no declarative pipeline submission tool. Build an explicit resumable campaign from `validateJob`, `estimateTime`, `submitJob` or `submitBatch`, bounded `getJobs` polling, and server-side artifact paths.\n\n## Plan the data flow\n\nFor every stage record:\n\n- deterministic stage and durable job/batch names;\n- live tool and validated settings;\n- required artifact and producing stage;\n- success criterion and metric direction;\n- fan-out and `topN` boundary;\n- chosen output file and exact `s3Path`;\n- current remote status and authorization state.\n\nKeep this as a reviewable state object in the task or a local JSON file when the client has a workspace. Re-read authoritative remote state before resuming.\n\n## Execute one stage at a time\n\nFor each stage:\n\n1. Call `getJobSchema`.\n2. Build the stage settings from confirmed inputs.\n3. Call `validateJob`; require `valid: true` and no mutation warning.\n4. Call `estimateTime` and confirm any material new scope.\n5. Call `submitJob` once, or one `submitBatch` for a bounded fan-out.\n6. Poll with `getJobs` at 15-30 second intervals and a finite deadline.\n7. On explicit success, call `listJobFiles`; select the output using stage-specific evidence.\n8. Pass the exact returned `s3Path` into the next schema when supported. Otherwise retrieve with `getJobFile` and re-upload with `uploadFile`.\n\nNever guess filenames or paths. Never advance a failed, stopped, or still-running stage.\n\n## Fan-out and selection\n\nUse `submitBatch(fromJob=...)` or `submitBatch(fromFile=...)` only when one generated sequence maps directly into the downstream `sequenceField`. For target-candidate complexes or any row that combines shared context with one candidate, build explicit `settings` plus `jobNames` so every final input is reviewable. Bound the expansion with `topN`, validate shared or explicit settings, estimate total cost, and obtain authorization before the fan-out.\n\nInspect and rank successful subjobs only. Advance a diverse, evidence-backed shortlist rather than every candidate or one scalar winner.\n\n## Recovery and safety\n\n- If a submit response is ambiguous, query its durable name; do not invoke the submit tool again.\n- If a polling deadline expires, checkpoint the active status and reattach later; do not restart the stage.\n- On failure, call `getJobLogs` with a bounded line count, checkpoint the failure, and stop.\n- Confirm total campaign scope before the first paid stage and again before a material fan-out or changed payload.\n- Use `cancelJob` or `cancelBatch` only after resolving and confirming the exact active target.\n- Preserve intermediate outputs, settings, metrics, and selection rationale for reproducibility.\n\nReturn the campaign state, completed and pending stages, durable names, selected artifacts, spend information, and the exact next safe action.\n","after":"---\nname: tamarind-mcp-pipeline\ndescription: Author, validate, run, monitor, and read results from declarative multi-step Tamarind Bio pipelines through MCP with submitPipeline, validatePipeline, getPipelineSchema, getPipelineTemplate, listPipelineTemplates, getPipelineRun, getPipelineRunResults, listPipelineRuns, and stopPipelineRun. Use when stages depend on earlier stages (design to fold to score), or to run or re-run a saved pipeline template. Not for a single job, one independent batch, or CLI orchestration.\n---\n\n# Run Tamarind pipelines through MCP\n\nA pipeline is a declarative graph the server runs for you: it dispatches each step's jobs, waits for\ntheir molecules to land, and feeds them to the next step. Do not chain jobs by hand out of\n`submitJob`/`submitBatch` polling.\n\n| tool | use it for |\n|---|---|\n| `getPipelineSchema` | the IR schema + authoring guide — **read before writing a graph** |\n| `listPipelineTemplates` | find a saved pipeline instead of authoring one |\n| `getPipelineTemplate` | one template's graph + the manifest of inputs you must bind |\n| `validatePipeline` | judge a run **before** it spends compute |\n| `submitPipeline` | run it (spends compute) |\n| `getPipelineRun` | poll status and per-step progress |\n| `getPipelineRunResults` | read the molecules and scores each step produced |\n| `listPipelineRuns` | find runs — they do **not** appear in `getJobs()` |\n| `stopPipelineRun` | stop a run — **not** `cancelBatch` |\n\n## Path A — run a saved template\n\nCheaper and safer than authoring. Always look before you author.\n\n1. `listPipelineTemplates(search=...)` → pick an `id`. Always search or use a small limit; an\n   unfiltered listing can exceed the response cap. Rows are summaries and carry no graph, and a\n   name may not describe what the graph does — confirm against the IR in step 2, never the name.\n   When several match, compare their fan-out (tool nodes, and any stage that multiplies molecules)\n   before choosing: they can differ several-fold in cost while all validating clean.\n   `owner` defaults to `\"org\"`, so you see templates you did not create; narrow with `owner=\"mine\"`.\n2. `getPipelineTemplate(templateId)` → read **`inputs`**: the manifest of what you must bind — the\n   node id to key each binding by, molecule-vs-file, the molecule type, reference chain labels, and\n   any `residueFields`.\n3. Confirm the tools the saved graph names still exist with `getJobSchema(<tool>)` — validation\n   does not check that — and read your output column names from it while you are there.\n4. `validatePipeline(...)` until `valid: true`.\n5. `submitPipeline(...)`.\n\n**Listed does not mean runnable.** Someone else's unpublished template lists fine, then fails\nvalidation with `403 pipeline_permission_denied`. That is terminal — pick another or ask the owner to\npublish. Prefer rows where `isPublished` is true or `createdBy` is you.\n\n`settings` and `version` are **reference-mode only**. `settings` is `{nodeId: {settingKey: value}}`,\nlimited to the template's editable settings. Omit `version` for published-then-latest.\n\n## Path B — author a graph inline\n\nOnly when nothing suitable exists. Passing `pipeline` to `submitPipeline` saves a new unpublished\ntemplate you own and runs it in one call.\n\nCall `getPipelineSchema()` first, every time — it is fetched live, so it always matches the deployed\nvalidator. Authoring blind reliably produces graphs the API rejects. Rules from it you cannot guess:\n\n- **No edge list.** Topology lives inside each node's `inputs`, where a node names what it consumes.\n- **Omit `metadata.defaultGroup` on an inline graph.** It is required only when SAVING a template;\n  inline, the binding supplies the group. Do not hunt for a group id or borrow one — submit fills a\n  *missing* `defaultGroup` from your binding but **never replaces one you left in**, and an\n  unresolvable id is not rejected, so a placeholder becomes a permanent reference to molecules the\n  run never used.\n- **A `filter` must do something:** `intersect: true` (which needs ≥2 sources) or ≥1 rule. An empty\n  filter is invalid, not a pass-through.\n\n### Filter rules\n\nRules narrow a filter's sources, in order. Two kinds — a predicate, and a ranked cut:\n\n```jsonc\n{\"kind\": \"jsonlogic\", \"rule\": {\">\": [{\"var\": {\"producerNodeId\": \"score\", \"columnName\": \"QED\"}}, 0.5]}}\n{\"kind\": \"top_k\", \"k\": 2,\n \"rank_by\": [{\"field\": {\"producerNodeId\": \"score\", \"columnName\": \"QED\"}, \"order\": \"desc\"}]}\n```\n\n`producerNodeId` is the upstream **node id**, not a tool name. `columnName` must be that tool's\nexact output header — read it from `getJobSchema(<tool>)`, never guess: headers carry spaces,\nparens and units (`\"SA Score\"`, `\"LogP (Crippen)\"`), and a wrong one still validates clean, so a\nguessed name ranks on nothing. A declared column is not guaranteed to arrive either — confirm the\ncolumn is present in a scored molecule before ranking a whole run on it.\n\n**Barriers.** `intersect: true`, any `top_k`, and a two-input tool with `combination_mode` all wait\nfor **every** upstream molecule before anything downstream dispatches. Size your poll deadline for\nthe slowest molecule, not the median.\n- **Residue selections go in the binding**, never in a node's `settings`.\n\n## Bindings\n\nOne entry per input node, keyed by that node's id. Group ids come from `listMoleculeGroups` /\n`searchMolecules` — but inspect a group narrowly: a single molecule can carry its structure files\ninline and run to hundreds of thousands of characters.\n\nSupply molecules **exactly one way**:\n\n```jsonc\n{\"inputProtein\": {\"group\": \"<groupId>\"}}      // an existing molecule group\n{\"inputProtein\": {\"sequences\": [\"MKT...\"]}}   // or raw values — server mints the group,\n{\"inputLigand\":  {\"smiles\": [\"CCO\"]}}         // and rolls it back if the submit fails\n{\"inputTarget\":  {\"pdbs\": [\"<uploadedPath>\"]}}\n{\"inputLigand\":  {\"sdfs\": [\"<uploadedPath>\"]}}\n{\"inputCsv\":     {\"file\": \"<path>\"}}          // a file input\n```\n\n`pdbs`/`sdfs` take paths relative to your user folder for files you already uploaded — not contents.\n\nTwo optional keys inside a binding:\n\n- **`residuesByChain`**, in one of **two shapes**. Get it right: the wrong shape is refused, and\n  `validatePipeline` reports it as `setting-invalid` on the tool node with a message that never\n  mentions `residuesByChain` and a null `field`, so it does not read like a residue problem:\n\n  ```jsonc\n  // ADVANCED — the default for newly created templates. Per (tool node, field).\n  {\"residuesByChain\": {\"<toolNodeId>\": {\"designedResidues\": {\"A\": \"42-44,58-59\"}}}}\n\n  // SIMPLE — one selection for every residue field this input feeds.\n  {\"residuesByChain\": {\"A\": \"1-76\"}}\n  ```\n\n  The shape is detected from the value: a chain → range **string** is simple, a node → **object** is\n  advanced. `getPipelineTemplate` reports the mode in `simplifiedResidues`. Ranges are always\n  strings, never lists: `\"1-76\"`, `\"42 43 44\"`, `\"10-20,45,60-64\"`.\n- **`chainMapping`** — only when your chain IDs differ from the template's reference chains.\n\n### The residue trap\n\nA non-empty `residueFields` means the run **may** take a selection — **not** that it requires one.\nEntries carry no per-field `required` flag, so the manifest cannot tell you which it is.\n\nInventing one is not a harmless default: it reaches the tool as designed residues, hotspots, or a\nbinding site, constraining the design to the wrong residues and spending GPU on scientifically wrong\noutput **that still looks successful**.\n\nSo do not guess — and do not refuse a runnable template either. Validate with the bindings you\nactually have; a genuinely required selection comes back as `required-field-unset` naming the field.\nAsk the user for the real one then.\n\n`targetsChains` is not a reliable key for `residuesByChain`: it is empty on some entries, and on\nothers names a chain the input does not have (one the graph creates downstream).\n\n## Validate before every submit\n\n`submitPipeline` spends real compute. `validatePipeline` executes and saves nothing. Call it on the\nsame graph and bindings, and only submit on `valid: true`.\n\nIt reads what *describes* the run — `pipeline` or `templateId`+`version`, `bindings`, `settings`,\n`name`. It ignores `runName`, `project` and `idempotencyKey`, which only name and tag the run.\n\nBoth outcomes return HTTP 200 — **read `valid`, do not branch on the status code**; if `valid` is\nabsent entirely, you have an error envelope instead, so read `code`. Each error\ncarries a `code`, `severity`, the `node`, the `field` where there is one, and a fix-it `message`:\n\n| code | usual cause |\n|---|---|\n| `required-field-unset` | often a residue selection — it belongs in the **binding**, not settings |\n| `input-unbound` | an input node with no entry in `bindings` |\n| `tool-unknown` | the node names a tool that does not exist |\n| `setting-invalid` / `param-out-of-range` | a bad node setting |\n| `chain-incompatible` | chain labels do not line up |\n| `molecule-class-incompatible` | upstream does not produce what downstream consumes |\n| `binding-invalid` | the binding's shape — **or a file that does not exist**; its remedy text says `files`, but the key is `file` |\n| `molecule_group_not_found` | the bound group id does not exist, or is not yours |\n\nTwo failure modes to handle deliberately:\n\n- **`validationUnavailable` means NOT JUDGED** — there is no verdict, so do not start editing the\n  graph in response to one. **Read `status`/`code` before retrying:** the flag is also set on a\n  permanent `403 pipeline_permission_denied`, whose hint still says to retry. A 403 is terminal.\n  Retry only a non-403, and if that fails identically every time, report it rather than looping.\n- **`valid: true` is not a guarantee.** It does not confirm the tools exist — a graph naming a\n  nonexistent tool validates clean. Worse, it does **not** enforce `requiresStructure`: a\n  `sequences` binding on an input whose manifest demands a structure returns `valid: true`, and the\n  run then spends GPU on something the first tool cannot consume. Check `requiresStructure` yourself\n  and bind a structure (`group`/`pdbs`) when it is set. If submit rejects a graph validation\n  approved, **believe submit** — re-validating will not reproduce it.\n\n## Submit, then poll\n\n`submitPipeline` returns a run whose `id` is the `runId`. Pass `idempotencyKey` so a retried submit\nis safe, `runName` to name this run explicitly, `project` to stamp an org project on its jobs.\n\n**Check which molecules the run actually used.** A saved template carries its own reference group on\neach input; your binding overrides it, but nothing in the results says which one won, and scoring\nsomeone else's molecules produces a complete, plausible, entirely wrong answer. The submit response\nechoes the group used at `inputs.<nodeId>.group` — confirm it is the group you bound, or a freshly\nminted one if you passed raw values, before trusting anything downstream.\n\nPoll `getPipelineRun(runId)` on a **finite deadline** — never an unbounded loop. Steps are under\n**`nodeRuns`**, each reporting `status`, `jobsTotal`/`jobsComplete`, `outputCount`, `outputGroup`.\n\n- **A step carries two ids.** `id` is that step's own run id; `nodeId` is the stable pipeline node id,\n  and `nodeId` is what `getPipelineRunResults(node=...)` wants.\n- **The order is not stable and is not topological** — a dependent step can be listed ahead of the\n  one it consumes, and the order can change between polls. Index by `nodeId`, never by position.\n\nIf a submit response is ambiguous, find the run with `listPipelineRuns(templateId=...)` before\nretrying — rows carry no `idempotencyKey`, and `name` is not a reliable handle, so the template is\nwhat narrows it. Never submit a second time to resolve uncertainty about the first.\n\n## Read results\n\n`getPipelineRunResults(runId)` returns each step's molecules **with their scores** — what you rank\non. Results appear per step as it finishes, so this works before the run completes; a step with\nnothing yet reports an empty `molecules` list.\n\n**Results do not come back in binding order, and molecule names are opaque.** Never zip results to\nyour inputs positionally — you will mislabel every one. Identify a molecule by its own returned\nfields; note that an input SMILES is canonicalized on the way in, so comparing against the exact\nstring you submitted also fails.\n\nThe envelope's top-level `status` is the **run's**, not the step's — a finished step can sit inside\na response whose `status` still reads `running`.\n\n**The two tools name the same thing differently — do not carry keys across:**\n\n| | array key | node id key |\n|---|---|---|\n| `getPipelineRun` | `nodeRuns` | `nodeId` |\n| `getPipelineRunResults` | `steps` | `node` |\n\n**Scores sit in different places depending on the shape you get. Read whichever you receive:**\n\n- step outputs — id in `complexId`, scores under `scores`, and the molecule's own value in\n  `sequence` (the canonical SMILES for a small molecule) — this is what you identify a result by\n- group molecules — id in `id`, scores under `metadata`\n\nIn both, **scores are keyed by tool name**: `scores[\"<tool>\"][\"MW\"]`, never `scores[\"MW\"]`. This\nholds for a filter step too — a filter runs no tool of its own, so its survivors carry the keys of\nwhichever tools scored them upstream.\n\nIn the group shape, **`metadata[\"<tool>\"]` is a list of every run that ever scored that molecule**,\nnot just yours. Take the entry whose `runId` equals `\"nr-\"` + that step's **`id`** from\n`getPipelineRun` (its `id`, not its `nodeId`). Reading `[0]` silently gives you another run's\nnumbers. Those entries also carry the `jobId`, which is the only place a step's job id is exposed.\n\n**`outputGroup: null` does not mean \"nothing here.\"** It is only the group that step *minted*, and\nwhether a step mints one is a property of the **run**, not the step — the same node of the same\ntemplate version returns a group on one run and `null` on another. Never infer the shape from it: a\nstep enriching its inputs in place, and a filter whose survivors are step outputs, both report null\nwhile holding plenty. Read the step itself.\n\nPaging: `limit` is 1-100 (default 25) and bounds molecules, **not payload**. A molecule accumulates\nevery tool's scores that touched it, so a later step's payload is a superset of the earlier ones' and\neven `node` plus `limit=1` can exceed the response cap on a one-molecule run. Always pass `node`,\nread the last finished step rather than polling each, and pull the fields you need. `cursor` (from\n`nextCursor`) requires `node`.\n\n## Stopping, and finding runs later\n\n- Stop with `stopPipelineRun(runId)`. Finished steps keep their outputs; work in flight is cancelled.\n  **Do not use `cancelBatch`** — it understands only the older job layout and will not stop a run.\n- Find runs with `listPipelineRuns` (filter by `status`, `templateId`, `owner`; here `owner` defaults\n  to `\"mine\"`, unlike templates). **Pipeline runs do not appear in `getJobs()`.**\n\n## Cost and authorization\n\nA run fans out into many jobs and can cost far more than a single submit. Scope is not reported\nanywhere before you submit: a template exposes `editableSettings` names without values and its IR\nomits any setting left at default, so you must compose it yourself — `getJobSchema(<tool>)` for each\nmultiplying setting's default, times your molecule count. The true figure only appears as `jobsTotal`\nafter the run starts. Confirm material scope with the user\nbefore the first `submitPipeline`, and again before re-running with a materially larger binding.\nAuthorization for one run is not authorization for the next.\n\n## Reading a failure\n\nA failed step reports its status in `getPipelineRun`, which does **not** expose a job id. To reach\nthe logs you need one from the group-shape `metadata` entries above; with it, `getJobs`/`getJobLogs`\n(bounded line count) give the tool's own output. Checkpoint the failure rather than resubmitting.\n\n**These reads are eventually consistent, and lag completion by minutes.** A step can report\n`running` with `jobsComplete: 0`, and its results can come back `molecules: []`, well after it has\nactually finished — the timestamps you get later prove it. So before reporting a stall, a partial,\nor an empty step, poll again: the most likely explanation for \"nothing happened\" is that you read\ntoo early. A step at `jobsComplete: 0` while a sibling on the same input has finished is usually\njust queueing. Keep polling to your deadline, then report partial state; never resubmit. Only a run\nwhere **every** job is complete with no progress is a real delivery-side stall — report that one\nwith the `runId` and the step's `node`.\n"}],"summary":"Fields changed: 3. /description, /included_files, /skill_md_contents.","summary_kind":"deterministic","summary_metadata":{}}