Plasmole

Export a plasmid as GenBank or FASTA text. Pass `sequence` (A/T/G/C/N), `features` as a list of {name, type, start, end, strand} dicts with 1-indexed positions, and `format` ('genbank' or 'fasta'); `name` and `topology` fill in the header. Fits a request to save, download, or hand off a plasmid produced by an earlier tool as a file. The format decides what survives: FASTA has no feature table, so exporting to FASTA drops every feature. GenBank keeps them. Every result reports `features_supplied` and `features_written`, plus `warnings` naming each feature that was dropped for being malformed, for spanning coordinates outside the sequence, or for a span the topology cannot carry, so a partial export_plasmid_file is visible rather than silent. A feature whose end is before its start crosses the origin and is written as a GenBank join() over its two halves on a circular plasmid; on a linear one it is dropped and named. The response carries the file content as a string. Limits: sequence of A/T/G/C/N, 50,000 bp or less. For research use only.

export_plasmid_file

Retrieves one NCBI nucleotide record by exact accession (NC_000913.3, U12345, NM_001256799) and returns the sequence, annotated features in 1-indexed coordinates, a construct_handle, and a link that opens the record in Plasmole. Reach for it when the user has an accession and wants that record's sequence, features or map. Input is an accession only: a gene, plasmid or vector name (TP53, GFP, lacZ, pUC19) does not resolve here, and search_ncbi turns a name into candidate accessions this tool can load. An accession inferred from a name rather than looked up either fails or returns an unrelated record, and the tool cannot detect that it was inferred. Optional include_enzymes=true draws restriction cut sites and a predicted digest on the same map; it is off by default. The construct_handle can be passed to find_restriction_sites, predict_digest, edit_sequence or version tools instead of fetching again. Limits: records over 500,000 bp are refused with their real size rather than truncated, and a record carrying no sequence is refused rather than returned empty. Successful fetches are cached seven days. For research use only; confirm critical accessions against the NCBI record.

fetch_ncbi

Finds restriction enzyme cut sites using BioPython.Restriction with REBASE data. Each site returns its recognition sequence, 1-based position and cut_after_base, and is drawn on a map; a construct_handle overlays them on that construct's features. Use it when someone asks which enzymes cut a sequence, whether a site is unique, or where an enzyme cuts. Topology: linear defaults to true, and a circular plasmid searched as linear misses sites spanning the origin, so pass linear=false for a plasmid. Dense 4-cutters are NOT in the default set of about 30 common cloning enzymes; they and any other enzyme are searched only when named in enzyme_names. Unknown names are skipped and listed in unknown_enzymes. Completeness: site_count is how many sites were found; sites may list fewer, enzymes in sites_omitted carry a cut count and no positions, and map_truncated means the map drew enzymes_shown_count of distinct_enzyme_count. Named enzymes that did not cut are listed in enzymes_with_no_sites, and none_found_note says whether a linear search or an N could hide a site. Input is A/T/G/C/N only, up to 50,000 bp. For research use only: star activity and methylation sensitivity are not modeled.

find_restriction_sites

Lists the version history of one Plasmole construct, identified by a `construct_handle` minted by an earlier auto_annotate, edit_sequence, or assemble_fragments_by_overlap call. Versions are immutable snapshots. Each entry carries version_number, name, length, topology, sha256, seguid, and claimed (whether that version has been saved into the caller's library). Raw sequence bases are not returned; export_plasmid_file or restore_construct_version return bases. Use it when the user asks which versions of a construct exist, which one is current, how long each is, or whether two versions hold the same sequence (equal sha256 or seguid means identical bases). Refusals: an unknown handle, a handle belonging to a different user, and an expired handle each return an error rather than a partial or empty list. Construct handles are temporary and expire seven days after the construct was first created, after which its versions are no longer readable.

list_construct_versions

Opens a plasmid file the user attached to the conversation. Pass the attachment in the file parameter: the file is fetched and parsed server side in full, and the tool returns an interactive map plus a link to open it in Plasmole. Reach for it when the plasmid arrives as an upload rather than as text in the message. Accepts GenBank (.gb, .gbk), FASTA (.fa, .fasta, .fna), .ape, and the binary .dna format, which is parsed only here. Taking the file by reference keeps its content out of the message, so a long file is not shortened by message limits. Limit 5 MB; larger files, other formats, and downloads that fail or are blocked are refused with the reason rather than parsed in part. include_enzymes=true adds restriction cut marks and a predicted digest gel to the same map for a default panel of 29 cloning enzymes; if sites_truncated is true then sites holds sites_shown of site_count positions and every enzyme in sites_omitted is reported by cut count only. Returns a construct_handle later tools take in place of re-uploading. Research use only.

open_uploaded_plasmid_file

Rewrites a coding DNA sequence for a chosen expression host while preserving the encoded protein, and returns the optimized sequence, optimization_score and original_score, the number of codons changed, any warnings, and protein_preserved (computed by translating both sequences and comparing them). optimization_score is the Codon Adaptation Index of the optimized sequence against the host table, times 100, and original_score is the same measure of the input; maximize_expression reaches 100 by construction, so compare the two rather than reading 100 as an improvement. Both are null, with the reason in warnings, when nothing could be scored. An in-frame stop codon before the last codon is named in warnings: the codons after it are still recoded although that frame never translates them. Use it when the user wants a gene recoded for expression in a different host, or wants rare codons reduced in a coding sequence. Accepts `sequence` or a `construct_handle` from an earlier call, `organism` (one of E_coli, yeast, mammalian), and `strategy` (one of maximize_expression, balance_codons, minimize_repeats). The input must be a complete reading frame: A, T, G, C only (whitespace ignored), DNA rather than RNA, a whole number of codons, and at least one sense codon. A length that is not a multiple of 3, any other character including U or N, a sequence of stop codons only, a sequence over 30,000 bp, or an organism or strategy outside the lists above is refused rather than trimmed or guessed. This call reads only: it saves no construct and stores no optimization history. For research use only.

optimize_codons

Parses plasmid text in GenBank, FASTA or .ape format into a structured plasmid, keeping the record's own feature table, and returns an interactive map plus a link to open it in Plasmole. Reach for it when the plasmid arrives as text in the conversation: pass that text in content. The file parameter takes an uploaded file on hosts that pass file references; those bytes are fetched and parsed server side, so a long file is not shortened by message limits. Supply one of the two, not both. The binary .dna format is parsed only by open_uploaded_plasmid_file. Limit 5 MB of text; larger input and other formats are refused rather than guessed at. Text with no header that is otherwise valid DNA is read as FASTA. include_enzymes=true draws restriction cut marks and a predicted digest gel on the same map for a default panel of 29 cloning enzymes; if sites_truncated is true then sites holds sites_shown of site_count positions and every enzyme in sites_omitted is reported by cut count only. Returns a construct_handle later tools take in place of the file. Research use only.

parse_plasmid_text

Predicts a restriction digest: fragment sizes computed from the cut positions, plus a simulated gel with visible and runoff bands, co-migration and a diagnostic verdict. Takes a sequence or construct_handle. Use it when someone asks what bands a digest should give, whether an enzyme set linearizes a plasmid, or whether a digest distinguishes two constructs. Topology defaults to circular; a linear template predicted as circular joins its ends and returns one fragment too few, so pass topology='linear'. Optional experimental_goal (linearization, insert_verification, construct_discrimination, general_inspection) scopes the verdict; without one it is clarity-based. enzymes must be a non-empty list, and the returned enzymes field lists what was searched, not only what cut. Unknown names come back in unknown_enzymes and are excluded; a call where none are recognised is not an uncut digest. Requested enzymes with no site are listed in enzymes_with_no_sites with a sentence in warnings; null there means the check did not run. Input is A/T/G/C/N only, up to 50,000 bp. For research use only: complete digestion is assumed; partial digests, methylation and star activity are not modeled.

predict_digest

Restores an earlier snapshot of a Plasmole construct, given `construct_handle` and `version_number`. The restore is non-destructive: the chosen snapshot is copied forward as a new highest version and every existing version stays in place and readable, so restoring version 2 of a five-version construct produces version 6 carrying version 2's bases. Use it when the user wants to undo an edit, return a construct to how it looked earlier, or continue work from an earlier state. Returns construct_version (the new tip), restored_from_version, name, sequence, features, topology, length, sha256, and seguid. Ownership and lineage stay with the original construct and are not reassigned to the caller. Refusals: an unknown handle, a version_number that does not exist, a handle belonging to a different user, or an expired handle returns an error and nothing is written. Construct handles expire seven days after the construct was first created.

restore_construct_version

Resolves a gene, plasmid, vector or keyword name to candidate NCBI nucleotide accessions. Reach for it when the user names what they want ('get me TP53', 'the GFP sequence', 'lacZ from E. coli', 'pUC19', 'pET28a') rather than giving an accession, which is the input fetch_ncbi requires. It searches the gene-name field, the protein-name field (the product annotation on a record's coding sequences, so a protein name like 'GFP' reaches records that ENCODE it rather than only records named after it) and the title/keyword fields TOGETHER and interleaves all three, so no one lane can hide another lane's match and vector names, which are not gene symbols, still resolve; match_field on each candidate says which lane found it. Genome-assembly fragments (whole-genome shotgun) are excluded: they are not the molecule anyone names, and they used to crowd out the real record. Returns ranked candidates, each with accession, symbol, name, organism, length_bp, kind and description, plus the total hit count; a candidate's accession is what fetch_ncbi loads. kind is the SHAPE of the record -- cds (a coding sequence), gene (a source-organism gene or transcript), vector (an engineered construct carrying it), genome (a larger molecule containing it), or unknown when the record does not say. kind is NOT a claim that the record is the molecule requested, and unknown means unclassified, not unimportant. symbol and organism are null when the record supplies neither; they are never filled in from the caller's own query. When the surviving candidates span more than one kind, ambiguous is true and disambiguation_question carries a question to put to the user before fetching -- 'GFP' can mean a bare coding sequence, a vector carrying it, or the native gene, and those are different molecules. An accession inferred from a name rather than looked up here can look plausible and still point at a different record. Optional organism ('Homo sapiens', 'Escherichia coli') narrows the species. Limits: query up to 200 characters, limit clamped to 1-25 (default 5). Ranking prefers records under the 500,000 bp fetch_ncbi can load; larger ones surface only when nothing smaller matches. Candidates are then ordered by kind: cds, gene and vector rank above unknown, which ranks above genome, so a 441,000 bp plasmid that merely contains what you asked for cannot outrank a 711 bp coding sequence. That ordering is by record shape, not a relevance score, and it never reorders records of the same kind. When nothing fetchable matches, the result is an empty candidate list with a note, not a guessed accession. For research use only; confirm a candidate matches intent before fetching.

search_ncbi

Verifies a clone by aligning a Sanger sequencing read against a reference sequence. Reach for it when the user has sequencing back from a picked colony or a miniprep and asks whether the clone is correct. Accepts either read_sequence (pasted basecalls) or ab1_base64 (a base64 AB1 trace), one or the other and not both; an AB1 is parsed and its low-quality ends trimmed first. The reference comes from reference_sequence or a construct_handle. Both strands are tried. Returns percent identity, a verdict, and each difference at its 1-based reference position, capped at 50 with mutations_truncated set. Two traps. Quality: when the whole trace is low quality the trim bounds span the entire read and trim.all_low_quality is true, so the verdict rests on unreliable bases. Coverage: a read is a fragment, so mode defaults to semi_global and the read is not charged for reference it does not span. identity_pct counts gaps; identity_in_covered_region_pct is over the bases actually compared and is the one that answers whether the clone is right; it is omitted when nothing could be compared. coverage_pct and covered_reference_span say how much of the reference the read SPANNED, so sequence the read aligned across but the clone lacks is inside that span and reported as a deletion, not as missing coverage. terminal_gaps lists ends that could not be compared -- reference the read never reached, or read past the reference such as vector flanking an insert -- reported, not counted as differences. unreadable_positions counts N basecalls. An exact match is only claimed at full coverage. Read and reference must be A/T/G/C/N and 20,000 bp or less; anything else is refused. For research use only.

verify_clone_from_sanger_read

Draws primers onto a Plasmole sequence map showing where each one binds. Reach for it when a user asks to see, check or map primer binding sites on a template or plasmid, or to view a designed pair on the sequence. Two input forms: forward_primer and/or reverse_primer, each with a 1-based "start-end" position; or primers=[{name, sequence}] for oligos the user already has, which are located by their 3' anneal core, so 5' tails such as restriction sites or assembly overhangs do not block placement. A supplied position is verified against the template: if the bases there do not spell the oligo it is re-located by 3'-anchored search, or kept as given when no binding site exists (normal for mutagenesis or degenerate primers), and every such case is listed in position_overrides. A primer that will not prime is returned in unlocated rather than dropped, and a primer with more than one binding site is drawn and flagged as possible mispriming. Every drawn site carries certainty: 'definite' when every base of the footprint was read, or 'possible' when the footprint covers N, where an unknown base matched an unknown base -- a possible site is not an established binding site and must not be narrated as one. An entry in unlocated carries certainty for the same reason: an exact search cannot match an N, so where the template or the oligo carries one the verdict is 'possible' and the oligo must not be reported as definitely not priming. When an earlier tool returned a construct_handle, pass it instead of sequence: the bases and the topology both come from the handle, which is what lets a primer whose footprint spans the origin be drawn correctly. Pass topology="circular" for a plasmid; the default, linear, misses primers whose footprint spans the origin. Forward primers draw right-pointing, reverse left-pointing. Inputs: A/T/G/C/N, up to 50,000 bp. For research use only.

visualize_primers