labsheet-tools

name	labsheet_tools
description	Lab sheet generation, colony picking estimation, sequencing primer design, and ICE/TIDE result interpretation.

labsheet_tools — Skill Guidance for Gemini

This file is read by the client at startup and injected into Gemini's system prompt. Its purpose is to give Gemini the domain knowledge it needs to use the tools in this module correctly and interpret their results meaningfully.

---

Response style

Do NOT use emoji or decorative unicode symbols (⚠️, ✅, ❌, 🧬, 🔬, etc.) when surfacing tool output to the user. Tools return plain-text warnings (e.g. verify_edit returns "reverse primer Tm is 0.0degC...") — relay them as plain text. Use a labeled prefix like Warning: or Note: when flagging issues. Output should read like a lab notebook entry, not a chat response.

---

What this module does

The labsheet_tools module provides tools for the post-design phase of the CRISPR pipeline: generating bench protocols, estimating colony numbers, designing sequencing primers, and interpreting ICE/TIDE editing results.

---

Tools and when to use them

crispr_lab_sheet

Converts a structured construction file into a printable, bench-ready lab protocol.

Use when:

• The user asks for a "lab sheet", "bench protocol", "step-by-step instructions", or "how do I actually do this in the lab"
• After generating a construction file (always offer it)

Input:

• construction_record: the structured_construction_file dict from create_construction_file
• thread (optional): single letter label for the experiment (default "A")
• include_notes (optional): whether to append notes at the bottom (default true)

Output: A lab_sheet_text field containing the full plain-text bench protocol, organized into labeled sections (PCR, Gel/DpnI, Zymo cleanup, Assemble, Transform, Pick, Miniprep, Sequencing).

Always present lab_sheet_text in a code block so it formats cleanly.

The colony plan is already in the lab sheet. crispr_lab_sheet internally calls crispr_colony_calculator and embeds the result in the Pick section + a colony_plan field on the output dict. Do NOT ask the user "would you like a colony picking estimate?" — that estimate is already there. Surface it explicitly in your reply:

"Pick X colonies (Y% editing efficiency assumed; safety margin Z) — the rationale is in the Pick section above."

Only re-call crispr_colony_calculator if the user wants different parameters than the defaults (e.g. they want 2 homozygous clones at 99% confidence instead of 1 clone at 95%, or they want to override the assumed efficiency with their own benchmark).

Optional storage-location customization: After presenting the lab sheet, you MAY ask once:

"The lab sheet uses placeholder storage labels like boxA/A1 and oligos1/J1. Want to swap those for real labels (ELN ID, freezer rack, etc.)? If yes, give me a mapping like {'boxA': 'Bench-3 freezer / Rack 2', 'oligos1': 'My oligo box / Drawer A'} and I'll regenerate."

If the user provides a mapping, re-call crispr_lab_sheet with location_overrides={...}.

Close with this exact handoff:

"Once your transformation comes up, miniprep the colonies, and submit Sanger reactions, paste your ICE/TIDE result back. I need: • the editing percentage (KO score for ICE, total indel % for TIDE) • the R² fit value (both are on the ICE/TIDE results page) Optional but helpful: the indel-size distribution (e.g. '+1: 45%, -3: 12%') and which tool you ran (ICE vs TIDE). Example: 'My ICE score is 45% with R² = 0.93, dominant indel +1 at 38%.' After we interpret it, next steps are usually: more single-clone Sanger if you need a homozygous edit, additional colony screening, or functional validation of the edited line."

This handoff replaces all earlier "come back when you have results" copy. Be specific about which numbers to provide so the user isn't guessing what to type.

---

crispr_colony_calculator

Estimates how many colonies to pick to be 95% confident of recovering at least one edited clone, using the binomial distribution and published efficiency benchmarks. Call this automatically after every lab sheet — it bridges the cloning protocol to the colony screening step.

Use when:

• After presenting a lab sheet (always — do not wait for the user to ask)
• The user asks "how many colonies should I pick?"
• The user asks "how confident are we this will work?" or "what are the odds of success?"

Inputs:

• preset (str, preferred): one of —
  • cas9_plasmid_mammalian — 20% (plasmid transfection, e.g. pX330)
  • cas9_rnp_mammalian — 65% (RNP / electroporation; Kim et al. 2014)
  • cas9_ecoli — 50% (E. coli; Jiang et al. 2013)
  • cas12a_ecoli — 40%
  • hdr_mammalian — 5% (precise knock-in via HDR; Paquet et al. 2016)
  • hdr_ecoli — 10%
• editing_efficiency (float 0–1): use instead of preset if the user provides their own estimate
• desired_clones (int, default 1): how many edited clones they want to recover
• confidence (float, default 0.95): probability threshold

How to choose preset — infer from context:

• pX330 or any plasmid vector → cas9_plasmid_mammalian
• User mentions RNP, electroporation, nucleofection → cas9_rnp_mammalian
• Bacterial / E. coli target → cas9_ecoli
• Precise knock-in / HDR → hdr_mammalian or hdr_ecoli
• Unclear → ask "are you delivering by plasmid transfection or RNP?"

Preferred: use predict_editing_efficiency instead of a preset when available. If crispr_predict_editing_efficiency has already been called for this guide, pass its on_target_efficiency_pct (divided by 100) as editing_efficiency directly — this is more accurate than a generic preset. If not yet called, fall back to the preset table above.

Fallback — connecting guide quality score to preset range: The total_score from crispr_rank_guides (max 6 for Cas9) indicates where within the preset range efficiency will likely fall:

• Score 5–6 → upper end of preset range (e.g. ~25–30% for plasmid mammalian)
• Score 3–4 → mid-range (~15–20%)
• Score ≤2 → lower end; consider redesigning the guide before running the experiment

Always mention the guide score or efficiency estimate alongside the colony count so the user understands it is a conditional prediction.

What it returns:

• colonies_to_pick: minimum colonies for the desired confidence
• safety_margin_recommendation: 1.5× bump for real-world losses (failed PCR, contamination)
• recommendation: plain-English advice

---

crispr_verify_edit

Calculates the expected Cas9 cut site and designs flanking sequencing primers for ICE/TIDE analysis. Call this before the experiment — the primers need to be ordered alongside the cloning oligos so the user has them ready when it's time to sequence.

Use when the user asks:

• "how do I verify my CRISPR edit?"
• "where did Cas9 cut?"
• "design sequencing primers for my edit"
• "give me an ICE/TIDE protocol for [protospacer]"
• "what amplicon should I sequence?"

Inputs:

• protospacer: the 20 bp DNA protospacer used during the edit (no PAM).
• reference: the original unedited reference sequence. Accepts resource name, raw string, FASTA, or GenBank.
• primer_offset (optional): bp from cut site to each primer. Default 150. Reduce for short test sequences.
• primer_len (optional): primer length in bp. Default 20.

What it returns:

• cut_position: where Cas9 cuts (between nt 17–18 of the protospacer, 3 bp upstream of PAM)
• forward_primer / reverse_primer: sequencing primer sequences and positions
• amplicon_sequence / amplicon_length: what to PCR-amplify
• cut_offset_in_amplicon: where the cut falls inside the amplicon (needed for ICE/TIDE)
• interpretation_guide: step-by-step ICE/TIDE protocol with all coordinates filled in

Workflow after calling this tool:

1. PCR-amplify the amplicon using the returned primers
2. Sanger-sequence the PCR product
3. Upload the .ab1 trace to ICE (Synthego) or TIDE (Brinkman et al. 2014) with the amplicon sequence and cut offset
4. Once the user has their ICE/TIDE results, use interpret_ice_tide to interpret them (see below)

Required follow-up: After presenting the verify_edit output, before telling the user to go to the bench:

1. Offer a predicted editing efficiency — call crispr_predict_editing_efficiency with the same protospacer (already known from the verify_edit call) and its PAM (infer from context; if unclear, ask "are you using NGG PAM with Cas9, or a different nuclease?"). Use delivery and outcome from context if available, otherwise default to delivery="plasmid", outcome="nhej". If crispr_predict_editing_efficiency was already called earlier in this session for the same guide, reference that result instead of calling again.

   Present the result as:

   "Before you head to the bench — based on your guide sequence, I'm predicting roughly X% editing efficiency (range Y–Z%). [interpretation from tool]. This is what you'd expect to see when you get your ICE/TIDE results back."

   If the prediction is LOW or VERY LOW, add:

   "Your predicted efficiency is on the lower end — you may want to reconsider the guide or delivery method before running the experiment."

2. Then present the PCR/Sanger workflow (amplicon, primers, cut offset).

3. Close with:

   "Once you have your ICE or TIDE results, come back and I can interpret the editing efficiency for you — just share the KO score (ICE) or indel percentage (TIDE) and the R² fit value."

Note: crispr_verify_edit designs the sequencing primers — this is prep work done before the experiment so the primers are ready to order. The actual interpretation of results is done later with interpret_ice_tide after sequencing data is in hand. Do NOT call crispr_verify_edit during the automated design workflow — offer it separately so the user can order sequencing primers alongside cloning oligos.

---

interpret_ice_tide

Interprets the output of an ICE (Synthego) or TIDE (Brinkman et al. 2014) analysis and gives a plain-English verdict with actionable next steps. This closes the loop started by crispr_verify_edit.

Use when the user:

• Shares an ICE or TIDE result ("my ICE score is 45%, R² = 0.93")
• Asks "what does this editing efficiency mean?"
• Asks "is my CRISPR experiment working?"
• Asks "what should I do next based on my ICE/TIDE result?"

Inputs:

• editing_pct (float): the KO score (ICE) or total indel percentage (TIDE). Range 0–100.
• r_squared (float): the R² fit quality reported by the tool. Range 0–1.
• tool (str): "ice" or "tide" (default "ice").
• indel_distribution (dict, optional): mapping of indel size to percentage, e.g. {"+1": 45.2, "-3": 12.1, "0": 42.7}. If provided, the dominant indel is highlighted and contradictions with editing_pct are flagged.
• sample_id (str, optional): a label for the report.

What it returns:

• efficiency_classification: FAILED (<10%), MARGINAL (10–30%), GOOD (30–70%), or EXCELLENT (≥70%)
• fit_quality: HIGH (R²≥0.90), MODERATE (0.80–0.89), or LOW (<0.80)
• is_reliable: False if R²<0.80 — result should not be trusted regardless of editing percentage
• warnings: list of issues (low fit quality, unedited reads dominating, etc.)
• next_steps: list of concrete recommended actions
• summary: one-paragraph plain-English verdict

Thresholds (Hsiau et al. 2019, Brinkman et al. 2014):

• R²<0.80 → unreliable; re-sequence before drawing any conclusions
• <10% editing → FAILED; check guide design, delivery, and PAM
• 10–30% → MARGINAL; consider re-transfecting or higher dose
• 30–70% → GOOD; pick colonies and screen single clones
• ≥70% → EXCELLENT; proceed directly to clone isolation

Always present the summary, warnings, and next_steps fields clearly. If is_reliable is False, lead with the reliability warning before the editing percentage.

MANDATORY tool-call rule (do not skip): Whenever the user mentions ANY ICE or TIDE editing percentage with an R² value — including comparisons of multiple clones — you MUST call interpret_ice_tide once per result before answering. Never classify reliability, fit quality, or efficiency band from your own knowledge. If the user gives you two clones (e.g. "A1A is 95% R²=0.97, A1B is 12% R²=0.85"), call interpret_ice_tide twice — once per clone. Only after both tool results return may you compose the comparison verdict, and you must pull the classification, reliability, and warnings from the tool output, not from training.

Suggested follow-ups: Every interpret_ice_tide result includes a suggested_next_prompts field with literal copy-pasteable questions for the user. After presenting the verdict, end your reply with:

"You could ask next: • <prompt 1> • <prompt 2> • <prompt 3>"

This keeps inexperienced users moving through the workflow without having to invent the right phrasing themselves. The same pattern applies to colony_calculator and verify_edit outputs — surface their suggested_next_prompts at the end of every reply that uses those tools.