> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kallima.bio/llms.txt
> Use this file to discover all available pages before exploring further.

# Codon export

> Generate codon-optimized CDS for CHO, HEK293, or other expression hosts.

Codon export takes the amino acid sequence of a variant and outputs a codon-optimized coding sequence (CDS) for your target expression host. Results are available as FASTA, CSV, or GenBank. Each variant in the batch costs 2 credits.

## List available strategies

Strategies differ in their optimization objective (CAI maximization, GC content tuning, rare codon avoidance, cryptic splice site avoidance, etc.). Fetch the catalogue before submitting to pick the right one.

```python theme={null}
from kallima import KallimaClient

client = KallimaClient(api_key)

strategies = client.codon_exports.strategies()
for s in strategies:
    print(s["name"], "—", s["description"])
```

## Submit a batch

One call submits one or more variants. The API returns a batch record with a `job_id` per variant.

```python theme={null}
batch = client.codon_exports.submit_batch(
    strategy="cai_max",
    host="cho",
    output_formats=["fasta", "genbank"],
    items=[
        {"variant_id": "var_aaa..."},
        {"variant_id": "var_bbb..."},
    ],
)

batch_id = batch["batch_id"]
job_ids = batch["job_ids"]    # one per variant, same order as items
export_ids = batch["export_ids"]  # one per variant
```

Supported hosts include `cho`, `hek293`, `e_coli`, `pichia`. Supported formats: `fasta`, `csv`, `genbank`.

## Constraints

Every strategy applies the same set of sequence-level constraints on top of the chosen codons. Pass any of these in `options` on `submit_batch`; unset fields use the defaults below.

| Option                            | Type      | Default                                                          | Notes                                                             |
| --------------------------------- | --------- | ---------------------------------------------------------------- | ----------------------------------------------------------------- |
| `restriction_sites`               | string\[] | `["EcoRI","BamHI","HindIII","NdeI","XbaI","SalI","NotI","XhoI"]` | NEB common 6/8-cutters to avoid. Pick from the NEB common set.    |
| `gc_min` / `gc_max`               | float 0–1 | `0.40` / `0.60`                                                  | Global GC bounds across the full CDS.                             |
| `gc_window_min` / `gc_window_max` | float 0–1 | `0.30` / `0.70`                                                  | Bounds inside each sliding window.                                |
| `gc_window_size`                  | int (nt)  | `80`                                                             | Width of the sliding GC window.                                   |
| `repeat_kmer_size`                | int (nt)  | `9`                                                              | Flag any direct repeat at least this long. `0` disables.          |
| `check_splice_sites`              | bool      | `true`                                                           | Scan for cryptic splice donors / acceptors.                       |
| `splice_score_threshold`          | float 0–1 | `0.80`                                                           | Normalized Shapiro-Senapathy score above which a site is flagged. |

```python theme={null}
batch = client.codon_exports.submit_batch(
    strategy="cai_max",
    host="cho",
    output_formats=["fasta"],
    items=[{"variant_id": "var_aaa..."}],
    options={
        "restriction_sites": ["EcoRI", "BamHI", "NotI"],
        "gc_min": 0.42,
        "gc_max": 0.58,
        "check_splice_sites": True,
        "splice_score_threshold": 0.85,
    },
)
```

### Cryptic splice sites

`check_splice_sites` runs a Shapiro-Senapathy PWM scan over the CDS and reports any donor or acceptor scoring at or above `splice_score_threshold`. Donors are scored against a 9-nt window with the invariant `GT` at +1/+2; acceptors against a 17-nt window (polypyrimidine tract + invariant `AG` at -2/-1). Hits land in `export["violations"]` with `type="splice_site"` and severity `soft` — they don't block the export, but you should review them before cloning into a lentiviral or AAV vector, where cryptic splicing can truncate the transgene.

```python theme={null}
export = client.codon_exports.get(export_id)
for v in export["violations"]:
    if v["type"] == "splice_site":
        print(v["detail"])  # "Putative cryptic splice donor at position 312 (score 0.87). …"
```

The 0.80 default trades recall for precision — strong putative sites get flagged, weak motifs are ignored. Lower the threshold (e.g. `0.70`) for AAV / lentiviral CAR-T workflows where a missed cryptic splice is more costly than extra review.

## Poll for completion

```python theme={null}
import time

for job_id in job_ids:
    job = client.jobs.get(job_id)
    while job.status not in ("completed", "failed", "canceled"):
        time.sleep(10)
        job = client.jobs.get(job_id)
    print(job_id, job.status)
```

## Download results

Once a job is complete, download the export for each variant:

```python theme={null}
for export_id in export_ids:
    export = client.codon_exports.get(export_id)
    if export["variable_cds"] is None:
        continue  # still running

    fasta_bytes = client.codon_exports.download(export_id, format="fasta")
    with open(f"{export_id}.fasta", "wb") as f:
        f.write(fasta_bytes)

    genbank_zip = client.codon_exports.download(export_id, format="genbank")
    with open(f"{export_id}.zip", "wb") as f:
        f.write(genbank_zip)
```

`genbank` format is returned as a ZIP archive containing one `.gb` file per chain.

### Export record fields

```python theme={null}
export = client.codon_exports.get(export_id)

print(export["strategy"])              # "cai_max"
print(export["host"])                  # "cho"
print(export["constraints_satisfied"]) # bool — False if the optimizer hit hard constraints
print(export["violations"])            # list of unmet constraint descriptions
print(export["metrics"])               # dict — CAI, GC content, rare codon count, etc.
```

## Add a signal peptide

Signal peptides are prepended to the CDS before optimization. The signal peptide catalogue lists built-in sequences plus any org-custom entries.

```python theme={null}
# Browse available signal peptides
for sp in client.codon_exports.signal_peptides():
    print(sp["id"], sp["name"])

# Attach per chain when submitting
batch = client.codon_exports.submit_batch(
    strategy="cai_max",
    host="cho",
    output_formats=["fasta"],
    items=[
        {
            "variant_id": "var_aaa...",
            "signal_peptides": {
                "H": "sp-uuid-for-heavy",
                "L": "sp-uuid-for-light",
            },
        }
    ],
)
```

## Full pipeline example

```python theme={null}
import os, time
from kallima import KallimaClient

client = KallimaClient(os.environ["KALLIMA_API_KEY"])

variant_ids = ["var_aaa...", "var_bbb..."]
items = [{"variant_id": vid} for vid in variant_ids]

batch = client.codon_exports.submit_batch(
    strategy="cai_max",
    host="cho",
    output_formats=["fasta", "csv"],
    items=items,
)

for job_id, export_id in zip(batch["job_ids"], batch["export_ids"]):
    job = client.jobs.get(job_id)
    while job.status not in ("completed", "failed", "canceled"):
        time.sleep(10)
        job = client.jobs.get(job_id)

    if job.status != "completed":
        print(f"{job_id} failed")
        continue

    data = client.codon_exports.download(export_id, format="fasta")
    with open(f"{export_id}.fasta", "wb") as f:
        f.write(data)
    print(f"Saved {export_id}.fasta")
```