CovaSyn Chemistry Tools

scope options:
  "basic"    — 40+ RDKit descriptors (atoms, bonds, rings, scaffolds, HBD/HBA, MW, complexity)
  "extended" — basic + Chi indices, Kier-Hall, Gasteiger charges, flexibility ratio
  "lipophilicity" — LogP, MR, TPSA, LabuteASA surface descriptors
  "mordred"  — 100 Mordred 2D descriptors (autocorrelation, topology, information content)
  "all"      — everything combined

Use this when you need atom positions for a structural feature
(e.g. "which atoms are in the aromatic ring?", "where are the stereocenters?",
"which carbon has the highest oxidation state?").

Returns: `{indices: [...], groups: [[...]], smarts_used: "..."}`. Plus:
  - `named_groups: [{name, atoms, smarts}]` for `functional_group_atoms`
  - `oxidation_states: [{atom, state}]` for `oxidation_state`

Supported query names (22):
  ring/topology    : aromatic_ring, aliphatic_ring, saturated_ring,
                     heterocycle, fused_ring, bridgehead
  atom-class       : halogen_atom, carbon_atom, heavy_atom, csp3_carbon
  stereo           : stereocenter, r_s_stereocenter, unspecified_stereocenter
  bonds & chains   : rotatable_bond, branch_point, chain_termini,
                     longest_carbon_chain
  derived          : murcko_scaffold_atoms, brics_break_atoms,
                     functional_group_atoms
  H-bonding / oxidation:
                     hba (Lipinski-style hydrogen-bond acceptors),
                     oxidation_state (per-carbon Pauling-EN ox-state,
                     with parallel `oxidation_states` field)

Examples:
  query="aromatic_ring" + smiles="c1ccccc1"  → indices [0..5], one group
  query="r_s_stereocenter" + smiles="C[C@H](O)C(=O)O" → stereo carbon indices
  query="hba" + smiles="CC(=O)O"  → carbonyl + hydroxyl O indices
  query="oxidation_state" + smiles="CC(=O)O" → carbon indices PLUS
    oxidation_states=[{atom:0, state:-3}, {atom:1, state:+3}]
  query="functional_group_atoms" + any SMILES → also returns named_groups list

Cost: 2 credits, available on Free tier.

Supported input: SMILES, InChI, MOL block, SDF block
to_format options: "smiles", "inchi", "inchikey", "molblock", "sdf"

Single molecule: provide smiles. Add highlight_smarts to highlight a substructure.
Grid of molecules: provide smiles_list (list of SMILES) + optional legends.
img_format: "svg" (default, scalable) or "png" (base64-encoded).

Turns a SMILES into a readable chemical description rather than a table of
numbers. Useful for reports, for captioning a drawn structure, and for
checking that a structure is what you meant to draw.

style="human"     — compact, chemistry-facing narrative: the parent skeleton,
                    heteroatom positions, unsaturation, the principal
                    characteristic group, then substituents with their locants.
style="technical"  — the full naming walkthrough, including how the name was
                    assembled token by token.

Returns: `{name, paragraphs: [...], text, rules_hit, smiles, style, engine}`,
or `{error, smiles}`. `text` is the paragraphs joined for direct display.

Equations and their params:
  "arrhenius"  — {k1, t1_k, k2?, t2_k?, ea_kj?} compute Ea or predict k at new T
  "vant_hoff"  — {k1, t1_k, k2, t2_k} compute reaction enthalpy delta-H
  "henderson_hasselbalch" — {pka, ph, acid (bool)} compute ionization fractions
  "ideal_gas"  — {n?, p_atm?, v_l?, t_k?} PV=nRT, solve for missing variable
  "beer_lambert" — {absorbance?, epsilon?, concentration?, path_length?} A=ecl
  "dilution"   — {c1, v1, c2?, v2?} C1V1=C2V2, solve for missing variable

Two sources, tried in order, and the response always says which one answered:
  - `source="pubchem"`  — the curated, human-checked IUPAC name. Authoritative,
    but only exists for compounds PubChem indexes.
  - `source="openclatura"` — a name constructed from the molecular graph by a
    deterministic IUPAC Blue Book (2013) rule engine. Works on any valid
    structure, including novel compounds, intermediates and analogues.

Parameters:
  prefer_pubchem — check PubChem first (default true). Set false to force
    generation, or to keep the call purely offline and ~100x faster: the
    rule engine takes ~5 ms, the PubChem round-trip 0.6-1 s.
  explain — also return `rules_hit`, the Blue Book rules that fired
    (e.g. P-44, P-61). Costs ~5x the naming time; off by default.
  verify — round-trip the generated name through OPSIN and report whether it
    parses back to the same structure. Needs a Java runtime; without one the
    result reports `verification="skipped_no_java"` instead of failing.

Returns: `{name, smiles, source, generated, engine}` (+ `rules_hit`,
`verification` when requested), or `{error, smiles}`.

A generated name is a systematic construction, not a database record —
treat `generated=true` accordingly.

action options:
  "lookup"     — find compound by name, CAS, SMILES, or InChIKey. Returns CID, IUPAC name, InChI, MW, XLogP, TPSA.
  "smiles"     — resolve a compound name or CAS to canonical SMILES.
  "properties" — fetch computed properties for a PubChem CID (pass CID as query).
  "similarity" — find similar compounds by Tanimoto (pass SMILES as query, set threshold 0-1).

Parameters:
  antibody_sequence: Antibody amino acid sequence.
  payload_smiles: Drug payload SMILES (e.g. MMAE, DM1).
  target_dar: Target drug-to-antibody ratio (default 4.0).

Returns: {total_mw, dar, conjugation_sites, aggregation_risk, payload_properties}

Parameters:
  seq1: First amino acid sequence.
  seq2: Second amino acid sequence.
  matrix: Scoring matrix — "BLOSUM62" (default), "BLOSUM45", "BLOSUM80".

Returns: {score, identity_pct, aligned_seq1, aligned_seq2, n_gaps}

Parameters:
  sequence: Antibody heavy or light chain amino acid sequence.
  scheme: Numbering scheme — "kabat" (default), "chothia", or "imgt".

Returns: {chain_type, CDR1/2/3 sequences and positions, framework_regions, cdr_developability}

A sequence that fails does not abort the batch: its slot carries {error: true, message, sequence} and the rest still return. Over 100 sequences the call is rejected rather than truncated, so a silently short result is not possible — split the batch.

Parameters:
  sequences: List of amino acid sequences (max 100).

Returns: {results: [profile | {error, message, sequence}]} in input order

Parameters:
  sequence: Protein amino acid sequence.
  ph_start: Lower bound of the pH window (default 2.0).
  ph_end: Upper bound of the pH window (default 12.0).

Returns: {charge_profile: [{ph, charge}], isoelectric_point}

Two uses: predicting in-vivo half-life and serum stability for a peptide therapeutic, and planning the digest for a peptide-mapping or MAM method — the trypsin list is the peptide map you will get.

Returns the same protease analysis that covabio_peptide embeds, on its own and for any protein length.

Parameters:
  sequence: Amino acid sequence.

Returns: {sites: {trypsin, chymotrypsin, pepsin, elastase}, total_cleavage_sites, stability_score, classification}

Scored against the optimal codon per amino acid, so it measures optimal-codon fraction rather than the geometric-mean CAI of Sharp & Li 1987. Stop codons are excluded. For mRNA therapeutics use covabio_mrna, which adds GC, CpG and uridine content.

Parameters:
  dna_sequence: Coding DNA sequence (ATG...stop).
  organism: Host codon table — "ecoli" (default) or "human".

Returns: {cai_score, total_codons, optimal_codons, scored_codons, organism, classification}

This is a sequence-motif rule set, not a structural or kinetic prediction: solvent exposure, local flexibility, pH and temperature all modulate the real rate, and a buried NG can be stable while an exposed ND is not. Treat the output as a site list to test, not a rate.

Parameters:
  sequence: Protein amino acid sequence (1-letter code).

Returns: {deamidation_sites: [{position, motif, risk, context}]} sorted by position

Parameters:
  sequence: Protein/antibody amino acid sequence.
  metal_binding_context: Set True for chelators/metal-binding constructs so functional
    Cys/His/carboxylate residues aren't penalized as liabilities (default False).

Returns: {composite_score, risk_dimensions: {aggregation, deamidation, ...}, flagged_positions}

Parameters:
  sequence: Protein amino acid sequence.
  alleles: Optional HLA allele list (default: 8 common DRB1 alleles).

Returns: {n_epitopes, epitopes: [{position, peptide, allele, score, binding_alleles}], epitope_density, risk_classification (low <0.18, moderate <0.27, high), hotspots, per_allele_scores, deimmunization_suggestions: [{position, original_aa, suggested_aa, position_class, predicted_reduction}], binder_thresholds, threshold_basis}

Sequence-derived only: it tells you which residues CAN carry an attribute, not which ones DO in a given lot. It replaces neither the LC-MS measurement nor the criticality ranking.

Parameters:
  sequence: Protein/antibody amino acid sequence.

Returns: {hotspots: [{position, modification_type, motif, risk, context}]}

Parameters:
  coding_sequence: mRNA coding DNA sequence (ATG...stop).
  organism: Target organism — "human" (default) or "ecoli".

Returns: {cai_score, gc_content, cpg_count, uridine_fraction, optimization_score}

Parameters:
  sequence: Nucleotide sequence (e.g. "ATCGATCG").
  oligo_type: "DNA" (default) or "RNA".

Returns: {tm_celsius, gc_content, molecular_weight, hairpin_detected, self_complementary}

Parameters:
  fasta_text: FASTA-formatted text (one or more records).

Returns: {entries: [{name, sequence}]}

Parameters:
  sequence: Peptide amino acid sequence (typically 5-50 residues).

Returns: {properties, cpp_score, amp_score, protease_sites, half_life}

Parameters:
  sequence: Amino acid sequence (1-letter code, e.g. "MKWVTFISLLLLFSSAYS...").

Returns: {molecular_weight, isoelectric_point, gravy, instability_index, charge_profile, ...}

Parameters:
  sequence: Protein amino acid sequence.

Returns: {length, one_to_three, codon_table, reverse_translate_ecoli, reverse_translate_human, signal_peptide_check, domain_search, restriction_sites_in_dna}

Parameters:
  target_sequence: Target mRNA sequence (DNA, minimum 21 nt).

Returns: {n_candidates, candidates: [{position, sense, antisense, score, gc_content}]}

Parameters:
  sequence: Protein amino acid sequence.
  concentration_mg_ml: Protein concentration (default 150 mg/mL for subcutaneous).
  ph: Formulation pH (default 6.0).

Returns: {viscosity_cP, risk_level, contributing_factors}

Use this when the user wants a general overview of a molecule.

Do NOT use this if the user asks specifically about:
  • SOLUBILITY in a solvent → use `covasolve_predict` (ML model with
    confidence intervals, ~10× more accurate than this tool's heuristic
    logS, and cheaper at 5 credits vs 6).
  • DRUGLIKENESS only      → `covachem_druglikeness` (1 cr).
  • pKa values             → `covachem_pka` (5 cr).
  • ADME parameters only   → `covachem_adme` (15 cr).

Cost: 6 credits (broad-scan premium). The targeted tools above are 1-5 cr
each and produce better results within their domain.

Returns OLS coefficients (coded + uncoded, with a plain-language model_equation_uncoded),
Type III ANOVA (+ Type I sequential SS under anova_type1), and significance. Blocking and
split-plot terms are picked up automatically from "Block"/"WholePlot" columns. Optional:
`factor_info` (list of {name, type:"categorical", levels:[...]}) enables multi-df categorical
F-tests; `response_family` ("gaussian"|"binomial"|"poisson") fits a GLM for non-normal responses.

Optional: `constraints` — list of {terms:{factor:coef}, op:"<="|">="|"==", rhs} in REAL units —
filters the D/I-optimal candidate set. `mixture=True` with a simplex `design_type`
("simplex_lattice"/"simplex_centroid") builds a bounded-mixture design (L-pseudocomponent,
components sum to 1, each ≥ its `low`); `degree` sets the simplex-lattice degree; `n_levels` sets
the D/I-optimal candidate-grid density.

Model-aware optimal designs: `model_terms` ("linear"|"interaction"|"quadratic") sets the model
matrix the D/I-optimal criterion optimizes for. `n_blocks` (>1) adds a "Block" column, confounding
the highest-order interaction(s) for factorial designs. `n_runs` / `resolution` / `generators`
control the `fractional_factorial` fraction, in that precedence order: `n_runs` (a power of 2,
counting base runs before center points) pins the fraction exactly — e.g. n_runs=16 on 5 factors
gives 2^(5-1), resolution V; `resolution` (3/4/5...) picks the smallest fraction reaching it;
`generators` gives the defining generators verbatim as pyDOE2 tokens, one per factor
(e.g. ["a","b","c","ab","ac"] for 2^(5-2)).
`design_type="taguchi"` builds an orthogonal-array design (`taguchi_levels` 2 or 3). `hard_to_change`
(list of factor names) produces a split-plot layout with a "WholePlot" column. `process_factors`
(with `mixture=True`) builds a mixture-process crossed design (`process_design_type`,
`process_center_points`). `n_runs` also sets the run count for D/I-optimal designs (default
len(factors)*3+1) and the sample count for latin_hypercube / sobol_sequence.

CCD variant: `face` — "circumscribed" (default), "faced" (star points on the faces, α = 1, for
factors that cannot physically exceed their range) or "inscribed" (the CCC scaled so the star
points land on the stated range). `axial_alpha` sets the axial distance; the default is
ROTATABLE, (2**k)**0.25, and "orthogonal" gives the α where Σx² = n_runs. The choice is worth
several points of power — check it with `covadoe_design_power` before running the design.

Common `design_type` aliases resolve ("full_factorial", "ccd", "dsd", "bbd"); the response
reports the canonical name actually built.

Builds the design and takes `ncp = effect_size² / (X'X)⁻¹_jj`, so it is correct for centre
points, axial points and unbalanced designs — unlike `covadoe_power_analysis`, which assumes
orthogonality and overstates power on a CCD, Box-Behnken or DSD. Use this when planning an
experiment; use `covadoe_post_hoc_power` only once you have measured responses.

`design_type` + `n_factors` builds the design (same generator as `covadoe_create_design`, so the
answer describes the design you would actually get). Common aliases resolve ("full_factorial",
"ccd", "dsd"). Alternatively pass `design`, an explicit coded run matrix, to score a design you
already hold — D/I-optimal, mixture, split-plot or hand-built. `n_runs` / `model_terms` are
forwarded to the generator for the optimal designs.

`model`: "linear" | "interaction" | "quadratic" | "quadratic_no_interaction" (a DSD supports only
the last). `term` names the coefficient — "x1", "x1^2", "x1*x2"; omit it to get power for every
term and group, which differ sharply on the same design. `alpha` is the significance level;
the CCD axial distance is `axial_alpha`, and the two are easy to confuse.

CCD variant: `axial_alpha` defaults to ROTATABLE, (2**n_factors)**0.25 — the design JMP,
Design-Expert and Minitab hand you. Pass a number, or "orthogonal" for the α where Σx² = n_runs
(at 3 factors: main-effect power 0.9400 against the rotatable 0.8846 on the same 17 runs; the
orthogonal α is also the premise of `covadoe_power_analysis`, so on that design the two agree
for a main effect and disagree for every other term). `face` — "circumscribed" (default),
"faced" (star points on the faces, α = 1) or "inscribed"; a bool works, and an unknown value is
rejected rather than quietly treated as circumscribed.

Returns power, power_by_term, power_by_group, df_error, relative_variance ((X'X)⁻¹_jj), the
resolved design_summary (the α and factorial level actually built — read both, an inscribed CCD
always reports α = 1), and `orthogonal_shortcut_power` — what `covadoe_power_analysis` would
have claimed — with its signed error (signed: the shortcut does not always overstate). Returns
`estimable: false` plus a reason when the model cannot be fitted on the design.

Analysis plots (need analysis_result, or design_data+response_col to auto-fit): main_effects,
interaction, pareto_effects, half_normal, normal_effects (signed Daniel plot; `alpha` sets the
reference threshold). Model plots (need model_result, or design_data+response_col): contour_2d,
surface_3d, residuals_4plot, prediction_profiler, cube_plot, ternary_mixture. Optimization plots:
desirability, pareto_front. `overlaid_contour` (sweet-spot / green-zone) takes `response_specs`
(list of {name, lower/upper}) + `factor_x`/`factor_y`; it fits one RSM per response from
design_data and returns the combined in-spec mask (`fixed_factors` pins the other factors).

Takes only scalars, so it never sees the design and cannot check its own premise. It uses
`ncp = n_runs · effect_size²`, which requires `(X'X)⁻¹_jj = 1/n_runs` — true for two-level
factorial and Plackett-Burman designs, and FALSE for a central composite, a Box-Behnken, a
definitive screening design, or a plain factorial WITH CENTRE POINTS.

On those it is wrong by a lot, and confidently: 0.8677 against a true 0.6228 on a Box-Behnken,
0.3874 against 0.2909 on a DSD, 0.3874 against 0.2491 on a 14-run factorial with centre points
(each Monte Carlo confirmed, 2026-08-07).

Use `covadoe_design_power` for ANY design carrying centre or axial points — it builds the design
and takes the non-centrality from `(X'X)⁻¹`, needs no data, and also reports what this tool would
have claimed. Use this one only when the design really is an orthogonal two-level design.
Every response carries `assumes_orthogonal_design: true` and a `validity` note.

When the unconstrained optimum is a saddle or sits outside the studied region, this traces the
locus of best predicted response on spheres of increasing radius around the design center — the
direction to run the next experiments. Pass a fitted `model` (from fit_rsm) OR raw `data` +
`response` to auto-fit one. Returns the eigenvalue nature, stationary point, and the ridge `path`
(radius, real-unit settings, predicted response ± CI) ending at `recommended_settings`.

Computes the S/N ratio per run and the factor-level S/N means to find the most robust setting.
`sn_type` selects the ratio ("larger_better"|"smaller_better"|"nominal_better"); if omitted it is
inferred from `response_goal` ("maximize"|"minimize"|"target"). Returns per-factor S/N tables,
the recommended robust level per factor, and a delta/rank contribution ordering.

Pass `path` whenever you have the spectrum file. The curve is baseline-corrected
and normalised the way covair_auto_analyze does it, and the verdict then requires
two things: that the structure's expected bands were found AND that the structure
accounts for the absorption actually measured. With neither a `path` nor peaks
there is nothing to verify against and the verdict is `no_evidence` -- not
`inconsistent`, which would assert evidence against the structure where none was
supplied. With peaks but no curve, `verdict_basis` reads `peak_recall_only` and
the verdict cannot reach `consistent`.

Do NOT read a verdict off `match_score`. It is the fraction of the CANDIDATE's own
expected bands that were found, so the denominator belongs to the candidate and a
structure predicting few bands scores high on any spectrum. Measured on a real
aspirin spectrum: hexane, which contains no oxygen, scores 1.00 where aspirin
scores 0.92, because all four of hexane's expected bands are C-H. Read `match_score`
with `n_expected_bands` beside it; `band_recall_verdict` shows what recall alone
would have concluded, and `verdict_note` says in words why the verdict differs.

Two measured limits. This blocks the "explains almost nothing" class, not wrong
structures in general -- nitrobenzene still reads `consistent` against an aspirin
spectrum. And on featureless input the unexplained-absorption test collapses onto
its chance level, so a broad candidate can pass on noise; check
`claimed_axis_fraction` in that case.

Unlike the peak-list MS tools, this takes the RAW LC-MS FILE by reference
(path = a signed URL or local path) and returns EVERY detected feature, not
one collapsed spectrum — the entry point for untargeted metabolomics. Uses
pyOpenMS FeatureFinderMetabo when available, else a scipy m/z-binning
fallback (the response's method_used field reports which ran).

A CSI:FingerID-style structural descriptor of the unknown, inferred from its
fragmentation. Useful as a scaffold-level fingerprint to compare against
candidate structures (see covams_search_by_fingerprint).

Predicts the query's fingerprint from its peaks and ranks each candidate
SMILES by Tanimoto agreement. The ranking rests only on the subset of bits
the predictor actually learned; the rest sit at an untrained 0.5 prior and
would otherwise order candidates by molecular size. That subset is a small
fraction of the fingerprint, so `bit_coverage` in the response is the
authoritative live number — read it, and the `warning` that accompanies a
low one, before acting on the order.

Measured on open structure retrieval against MassSpecGym candidate pools
(median 256 candidates): the correct structure comes first about 3.5 % of
the time, against a 2.4 % permutation noise floor. The lift is real but
roughly one percentage point, so the right answer is NOT at rank 1 in about
96 % of cases. Use it to cut a long candidate list down, never to name a
compound.

If you already suspect what the compound is, use covams_search_db instead:
matching the spectrum against the packaged 169k-spectrum library is a far
stronger signal, and dereplicating a known compound is the common case.

**Always use this tool when the user asks about solubility, log S, dissolution,
or "how much X dissolves in Y".** Much more accurate than the heuristic logS
in `covachem_profile` and explicitly accounts for the solvent (covachem only
gives intrinsic water-logS).

Returns: log S (mol/L), mg/mL, g/L, mole fraction, 95% confidence interval,
model confidence (0-1), applicability domain flag.

Solvent SMILES examples:
  water = "O"
  ethanol = "CCO"
  methanol = "CO"
  DMSO = "CS(C)=O"
  acetone = "CC(C)=O"
  ethyl acetate = "CCOC(C)=O"

Cost: 5 credits, available on Free tier.

Parameters:
  job_id: The id returned by the submitting tool, e.g. "covafold-fold_protein:abc123".

Returns: {status: cancelled|already_finished|not_found, message}.
FREE — and the job's own credits are returned automatically.

Returns:
  - balance: subscription credits remaining (resets weekly to weekly_allocation, capped at max_balance)
  - prepaid_balance: pre-paid credits remaining (no expiration; consumed after sub balance is empty)
  - total_available: balance + prepaid_balance (the actual amount you can spend right now)
  - weekly_allocation: sub credits added every 7 days
  - max_balance: rollover ceiling for sub credits (4× weekly_allocation)
  - tier: free / pro / unlimited / enterprise
  - max_concurrent_calls: parallel call limit for your tier
  - next_reset_at: ISO timestamp when next weekly grant happens
  - pricing_version: currently active pricing version
  - prepaid_packs: list of available credit-pack sizes + EUR prices for your tier

This tool is FREE in all tiers — never costs credits to check your balance.

Use this when something doesn't work, you have a feature request,
or a question. Your data (SMILES, structures, results) is NEVER
included — only your message and optional contact info.

Args:
    subject: Short summary of the feedback.
    message: Detailed description.
    severity: One of "bug", "feature", "question", "other".
    contact: Optional email/name so we can follow up.
    tool_name: Which tool the feedback is about (optional).
    error_message: Error text if reporting a bug (optional).
    api_key: Your API key (used for rate limiting only).

Parameters:
  job_id: The id from covasyn_jobs, e.g. "covafold-fold_protein:abc123".

Returns: {job: {...}} or {error}. FREE — never costs credits.

Some GPU tools return a ``job_id`` instead of an inline result because the
computation runs too long for one response (e.g. chemreason_retrosynthesis).
Call this with that job_id; if it is not ready, re-call every ~20 seconds
until ``status`` is ``completed`` or ``failed``.

Parameters:
  job_id: The id returned by the submitting tool, e.g. "chemreason:abc123".

Returns: {status: running|completed|failed, result?, error?}.
FREE — never costs credits.

Parameters:
  scope: "canvas" (default) for jobs started from the current canvas,
         or "account" for every job on your account.
  tool:  optional filter, e.g. "covafold". Empty (default) returns EVERY
         durable job — an LLM asked "what jobs do I have?" must not be
         handed a silently truncated answer. A UI that can only act on one
         kind of job passes its own filter explicitly.

Returns: {jobs: [{job_id, tool, state, submitted_at, credits, importable}]}.
FREE — never costs credits. Never returns sequences or structures; fetch
those with covasyn_job_detail / covasyn_job_result.

mode="protein" | "nucleic_acid" | "enzyme_kinetics"

concentration_unit is REQUIRED and must match the unit the calibration
curve was built in: "mg/mL", "mg/L" or "ug/mL" (the latter two are
equivalent). Dissolution calibrations are most often built in ug/mL — a
100 mg tablet in 900 mL is ~111 ug/mL at full release. Getting this wrong
shifts every result by a factor of 1000, so there is deliberately no
default; the response echoes the unit back and flags implausible profiles
in unit_check.

Optionally calculates f2 similarity if reference_profile is provided.