ReferenceAI skillsWorking with batches

Working with batches

Use to prepare plans for multiple candidates and check whether they can be submitted.

Skill version: 1.0.0. Resource: skill://nadoobio-batch-screening/SKILL.md.

Principles

  • For multiple candidates, do not repeatedly call create_plan. Store inputs as CSV or FASTA in the project and use create_batch_plans.
  • First read the file's generation, sha256, and inspectionVersion using inspect_input and pass them unchanged. Changed values produce batch_source_changed.
  • Do not guess column positions. Call preview_batch_plans with mappings: [] to inspect headers (column index:name) and the data-row count. This call creates no plans.
  • Map columns by position (columnIndex), not by name. If a name column exists, specify it with nameColumn.
  • After mapping, call preview_batch_plans again with the same arguments to check for rejected rows or setting problems, then call create_batch_plans.
  • If the user requested plans and the preview has no rejected rows or setting issues, proceed to create_batch_plans in the same conversation. Creating plans does not execute them. Report both preview and creation results.

Reading results

  • For rejected in rows, correct only that row and create it again with a new batchRequestId. Retrying does not duplicate already-created plans.
  • Read the creation response's approval.status and reason first. For pending, give the person the returned approval.href to review plans, inputs, settings, and terms on the web and approve selected plans. For reviewMode: exact_plan_list, review at most 100 at a time; one page's approval is not approval of the entire batch. Never record human consent using an API key. After approval, submit only when the user requests it, calling submit_batch with the original batchId. For the older individual_plan_approval_required response, follow each plan's get_plan review link and submit_plan route. Explain other unavailable values according to the returned reason.
  • submit_batch submits in row order. On stoppedByQuota:true, report quota and stop. Retrying the same submitRequestId returns already-received rows as skipped.

Input formats and setting combinations

  • Check supported inputs, chain counts, and required data in the current get_tool_schema and list_execution_options responses. Do not assume batch execution supports every individual-run input.
  • Use actual headers and schema setting keys for CSV mapping. Column indexes start at 0. Check the preview response for FASTA sequence/name column positions and supported setting combinations.
  • Do not invent settings the user has not chosen. Distinguish source-row counts from the number of plans generated by combinations. Use preview counts, including errors and empty rows.
  • Changes to settings, column mapping, or combination axes require a new creation request. If only the response was lost, recover with the original body and the same batchRequestId or submitRequestId.
  • planHash tracks inputs and settings; it does not guarantee identical bytes across environments. On completion, provide results, provenance, and the detail/structure links returned by the server.

Checking conditions before submission

After human approval, use get_plan to check current approval and usageTerms. If terms exist, check for acceptedAt and pass the returned usageTerms.termsHash unchanged as submit_batch.acceptedTermsHash. Passing a hash does not replace consent. If plans have different terms hashes, check each plan's current terms and use submit_plan individually rather than applying one hash to the batch. Retries after response loss must retain the original body and request ID.

Requerying a batch creation request returns current pending, approved, expired, and accepted counts in approval.counts. If approval.status is partial, review only remaining pending or expired items. If approved, check current terms and submission eligibility. If submitted, provide existing job links; do not request new approval or recreate the batch. approval.required: false means no new plan approval is needed for that lookup, not that current terms, permissions, and limits have passed.

On this page