coracle-protein 0.1.0

Python client for the Coracle protein behavior-prediction API

coracle-protein

Python client for the Coracle protein behavior-prediction API. Coracle returns functional readouts from a protein sequence (solubility, aggregation, disorder, foldability, stability, function residues, mutation effect, transmembrane topology, thermostability, isoelectric point, flexibility, metal-binding, interface), plus antibody developability and structure-input lanes: training-free, de novo by construction, deterministic, and sub-second.

The client is a thin wrapper over the hosted API. The behavior engine runs server-side; this package sends sequences (or structures) and returns typed results. Every prediction carries an honest validation tier, a scope note stating what it does not claim, and a provenance record so it can be reproduced and traced.

Install

pip install coracle-protein

Quickstart

from coracle_protein import Client

client = Client(api_key="cprot_...")   # or set CORACLE_PROTEIN_API_KEY in the environment

pred = client.predict_solubility("MQIFVKTLTGKTITLEVEPSDTIENVK")

print(pred.method, pred.validation_tier)   # "predict_solubility validated"
print(pred.scope_note)                     # what the number does not claim
print(pred.result)                         # the per-method payload (a dict)
print(pred.provenance.request_id)          # quote this in support requests

No API key? Client() calls the anonymous demo tier (a small daily cap, public sequences only, watermarked). A key lifts the cap and unlocks private and designed sequences plus the structure-input lanes on Pro and above.

What you get back

Every prediction method returns a Prediction with a uniform envelope:

field	meaning
method	the endpoint name
validation_tier	validated / calibrated / scoped / experimental
estimate_kind	the kind of quantity returned
scope_note	what the readout does NOT claim
calibration_note	the calibration basis (by calibration_note_ref; pass verbose=True to inline the full text)
warnings	advisories attached to this call
watermark	set on Free / demo output, empty on paid tiers
provenance	model_version, schema_version, request_id, served_at
result	the per-method payload, a dict

The per-method payload is on pred.result. As a convenience, pred["key"], pred.get("key"), and "key" in pred read from result, and pred.raw holds the complete server response.

Errors

All raise subclasses of coracle_protein.CoracleError, each carrying the server's code and request_id:

from coracle_protein import LicenseError, RateLimitError, ValidationError

try:
    pred = client.predict_active_site("path/to/structure.pdb")
except LicenseError as e:        # 403 - a paid endpoint or a structure lane below Pro
    ...
except RateLimitError as e:      # 429 - e.retry_after is the suggested backoff in seconds
    ...
except ValidationError as e:     # 400/422 - malformed sequence, mutation, or structure
    ...

The calls

From sequence (Free):

client.predict_solubility(seq)
client.predict_aggregation(seq, segment_window=6, include_profile=True)
client.predict_repeat_aggregation(seq)                 # or repeat_residue="Q", repeat_count=47
client.predict_disorder(seq)
client.predict_foldability(seq)
client.predict_stability(seq)
client.predict_function(seq)
client.predict_mutation_effect(seq, "L67A")
client.predict_transmembrane(seq)
client.predict_thermostability(seq)
client.predict_isoelectric_point(seq, ph=7.4)
client.predict_flexibility(seq)                        # add structure= for the Pro lane
client.predict_metal_binding(seq)                      # add structure= for the Pro lane
client.predict_interface(seq)                          # add structure= for the Pro lane
client.predict_catalysis("catalase")                   # client.catalysis_catalog() lists the keys

Paid (Pro and above):

client.predict_antibody_developability(vh, vl)
client.predict_thermostabilizing_mutations(seq, top=15)
client.predict_chemical_liability(seq, structure=pdb_text)   # structure enables the validated lane
client.predict_structure_gated_ddg(pdb_text, mutations=["L67A"])
client.predict_active_site(pdb_text)
client.predict_structure_accessibility(pdb_text)

The structure-input lanes accept PDB text or a path to a local .pdb / .cif file. Supplying a structure to predict_flexibility, predict_metal_binding, or predict_interface switches that call to its Pro structure-gated lane.

Introspection (unmetered): client.capabilities(), client.health(), client.catalysis_catalog().

Tiers

tier	quota	sequences
Demo	5 / day, no signup	public only, watermarked
Free	30 / month, signed up	public only, watermarked
Pro	higher	private and designed; structure-input lanes; commercial-use license
Team	higher	Pro plus shared usage and seats
Enterprise	unlimited	on-prem and a commercial license

See protein.coracleresearch.com for pricing and the guide.

License

Proprietary. This client may be installed and used to access the hosted Coracle service under your account terms; see the LICENSE file. The behavior engine runs server-side and is not included in this package.