Metadata-Version: 2.4
Name: coracle-protein
Version: 0.1.0
Summary: Python client for the Coracle protein behavior-prediction API
Project-URL: Homepage, https://protein.coracleresearch.com
Project-URL: Documentation, https://protein.coracleresearch.com/guide
Author: Coracle Research
License: Copyright (c) 2026 Coracle Research. All rights reserved.
        
        This package (the "Client") is the official Python client for the Coracle
        Research protein behavior-prediction service. It is proprietary software.
        
        Permission is granted to install and use the Client solely to access the hosted
        Coracle Research service through a valid account, subject to the commercial
        terms that govern that account. All other rights are reserved.
        
        The prediction engine and its methodology run server-side, are not included in
        this package, and are proprietary and confidential trade secrets. No license,
        express or implied, to the engine or its methodology is granted by this package.
        
        No license is granted to copy, modify, redistribute, sublicense, or sell the
        Client except under a separate written agreement signed by the copyright holder.
        Predictions returned by the service are governed by your account tier's terms.
        
        THE CLIENT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
        FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE COPYRIGHT
        HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT OF,
        OR IN CONNECTION WITH THE CLIENT OR THE USE OR OTHER DEALINGS IN THE CLIENT.
License-File: LICENSE
Keywords: aggregation,antibody,bioinformatics,developability,protein,solubility,thermostability
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: respx>=0.20; extra == 'dev'
Description-Content-Type: text/markdown

# coracle-protein

Python client for the [Coracle](https://protein.coracleresearch.com) 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

```bash
pip install coracle-protein
```

## Quickstart

```python
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`:

```python
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):

```python
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):

```python
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](https://protein.coracleresearch.com) for
pricing and the [guide](https://protein.coracleresearch.com/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.
