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

# Batch humanization

> Submit hundreds of variants in one call and collect results as they finish.

Use `submit_batch()` when you have many variants to humanize — it chunks them into requests automatically and yields a `Job` per variant.

## Submit a batch

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

client = KallimaClient(api_key)

items = [
    {"variant_id": "var_aaa..."},
    {"variant_id": "var_bbb..."},
    {"variant_id": "var_ccc..."},
    # up to thousands — the SDK chunks at 50 per request
]

jobs = list(client.humanizations.submit_batch(items))
print(f"Submitted {len(jobs)} jobs")
```

## Wait for all jobs in parallel

`wait_for_all` polls all jobs concurrently and returns results as they finish:

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

for job in wait_for_all(jobs, timeout=300):
    if job.status == "completed":
        best = max(job.results, key=lambda s: s["oasis_score"]["mean"])
        print(f"{job.id}  best strategy: {best['strategy']}  OASis={best['oasis_score']['mean']:.2f}")
    else:
        print(f"{job.id}  failed: {job.error}")
```

## Process results in batches

If you have thousands of variants and want to avoid holding all jobs in memory, use `iter_batches`:

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

for batch_jobs in iter_batches(items, client=client, batch_size=50):
    completed = [j for j in batch_jobs if j.status == "completed"]
    print(f"Batch done — {len(completed)}/{len(batch_jobs)} succeeded")
```

## Full pipeline example

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

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

# Collect variant IDs from a prior listing
variant_ids = [v["id"] for v in client.variants.list(candidate_id="cand_...")]

items = [{"variant_id": vid} for vid in variant_ids]
jobs = list(client.humanizations.submit_batch(items))

results = []
for job in wait_for_all(jobs, timeout=600):
    if job.status == "completed":
        results.append({
            "variant_id": job.variant_id,
            "strategies": job.results,
        })

print(f"Collected results for {len(results)} variants")
```

<Note>
  Each humanization costs **1 credit**. A batch of 200 variants costs 200 credits.
  Check your balance with `client.me.get()` before submitting large batches.
</Note>