> ## 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.

# Quickstart

> Humanize an antibody in under five minutes.

## 1. Get an API key

Open the Kallima dashboard → **Settings → API tokens → New token**. Copy the token — it starts with `ab_` and won't be shown again.

## 2. Install the Python SDK

<CodeGroup>
  ```bash pip theme={null}
  pip install kallima
  ```

  ```bash uv theme={null}
  uv add kallima
  ```
</CodeGroup>

<Note>
  The SDK requires Python 3.10+. The only runtime dependency is `httpx`.
</Note>

## 3. Create a client

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

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

## 4. Pick a project

Create a project in the [dashboard](https://www.kallima.bio) and copy its ID from the URL, or fetch it via the SDK:

```python theme={null}
project = next(client.projects.list())
project_id = project["id"]
```

## 5. Register a source antibody

A **source antibody** is your parental sequence.

```python theme={null}
source_ab = client.source_antibodies.create(
    project_id=project_id,
    name="Adalimumab parental",
    species_origin="mouse",
    molecule_type="mab",
    vh_sequence="QVQLVESGGGLVQPGGSLRLSCAASGFTFSDYAMSWVRQAPGKGLEWVSAITWSGGSTYYADSVKGRFTISRDNSKNTLYLQMNSLRAEDTAVYYCAKDRGTTMVPFDYWGQGTLVTVSS",
    vl_sequence="DIQMTQSPSSLSASVGDRVTITCRASQGIRNYLAWYQQKPGKAPKRLIYAASTLQSGVPSRFSGSGSGTDFTLTISSLQPEDVATYYCQRYNRAPYTFGQGTKVEIK",
)
```

## 6. Create a therapeutic candidate

Creating a candidate automatically creates a baseline **variant** (`v1`). The `initial_variant_id` is what you pass to pipeline jobs.

```python theme={null}
candidate = client.therapeutic_candidates.create(
    project_id=project_id,
    name="Adalimumab baseline",
    format="mab",
    initial_chains=[
        {"chain_id": "H", "role": "heavy", "variable_sequence": source_ab["vh_sequence"]},
        {"chain_id": "L", "role": "light", "variable_sequence": source_ab["vl_sequence"]},
    ],
    source_antibody_ids=[source_ab["id"]],
)

variant_id = candidate["initial_variant_id"]
```

## 7. Submit a humanization

`submit()` returns a `Job` object immediately — the job runs asynchronously on GPU.

```python theme={null}
job = client.humanizations.submit(variant_id=variant_id)
print(job)  # Job(id='...', status='pending', job_type='humanization')
```

## 8. Wait for results

```python theme={null}
job.wait(timeout=120)  # polls until status='completed' or raises TimeoutError

if job.status == "completed":
    for strategy in job.results:
        print(strategy["strategy"], strategy["oasis_score"]["mean"])
else:
    print("Job failed:", job.error)
```

***

## Full example

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

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

# Pick the first project (or hard-code a project ID from the dashboard URL)
project_id = next(client.projects.list())["id"]

# Register the parental sequence
source_ab = client.source_antibodies.create(
    project_id=project_id,
    name="My antibody",
    species_origin="mouse",
    molecule_type="mab",
    vh_sequence="QVQLVES...",
    vl_sequence="DIQMTQS...",
)

# Create a therapeutic candidate (baseline variant created automatically)
candidate = client.therapeutic_candidates.create(
    project_id=project_id,
    name="Candidate v1",
    format="mab",
    initial_chains=[
        {"chain_id": "H", "role": "heavy", "variable_sequence": source_ab["vh_sequence"]},
        {"chain_id": "L", "role": "light", "variable_sequence": source_ab["vl_sequence"]},
    ],
    source_antibody_ids=[source_ab["id"]],
)

# Humanize the baseline variant
job = client.humanizations.submit(variant_id=candidate["initial_variant_id"])
job.wait(timeout=120)

for strategy in job.results:
    print(f"{strategy['strategy']:20s}  OASis={strategy['oasis_score']['mean']:.2f}")
```

***

## What's next

<CardGroup cols={2}>
  <Card title="Batch humanization" icon="layer-group" href="/guides/batch-humanization">
    Submit 100+ variants at once using `client.humanizations.submit_batch()`.
  </Card>

  <Card title="Structure prediction" icon="cube" href="/api-reference/structure-predictions/submit-a-structure-prediction">
    Get an ImmuneBuilder PDB + per-residue confidence scores for any variant.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Register an HTTPS endpoint to be notified when jobs finish.
  </Card>

  <Card title="Error handling" icon="triangle-exclamation" href="/authentication#errors">
    How to handle 402 insufficient credits, 429 rate limits, and retries.
  </Card>
</CardGroup>