CogniChem Python Client

Official Python SDK for the CogniChem compute API (/api/v1).

Installation

pip install cognichem-client

Requires Python 3.10+.

Quick start

from cognichem_client import CogniChem

client = CogniChem(api_key="YOUR_API_KEY")
# or: CogniChem.from_env()  # reads COGNICHEM_API_KEY / COGNICHEM_BASE_URL

# Short utility
result = client.utils.run(
    "convert",
    {
        "input_data": "CCO",
        "input_format": "smiles",
        "output_format": "pdbblock",
    },
)
print(result.data)

# Long-running job: submit → wait → download
submitted = client.jobs.submit(
    job_name="my-padel-run",
    job_type="padel-descriptor",
    payload={
        "input_data": ["CCO", "CCC"],
        "input_format": "smiles",
        "descriptor_types": ["ALOGP", "AtomCount"],
    },
)
status = client.jobs.wait(submitted.process_id)  # completed | error | cancelled
if status.status == "completed":
    artifact = client.jobs.result(submitted.process_id, save_path="./")
    print(artifact.filename)

Authentication

API keys carry read and/or write scopes. Submitting jobs, workflow runs, or uploads needs write. API-key mutations must send an Idempotency-Key; the client generates one per call unless you pass idempotency_key= (pass your own to make retries safe).

Environment variables:

• COGNICHEM_API_KEY
• COGNICHEM_ACCESS_TOKEN (optional Bearer)
• COGNICHEM_BASE_URL (default https://api.cognichem.com)

Create and manage keys in your CogniChem account. Collection endpoints under /auth/api-keys require JWT.

API surface

Async twin: AsyncCogniChem with the same method names (await client.jobs.run(...), async for event in client.chat.stream(...)).

Workflows

from cognichem_client import CogniChem, artifact_ref

client = CogniChem.from_env()

spec = client.workflows.template("smiles-embed-dock").spec
target = client.artifacts.upload("target.pdb", data_kind="protein_structure", data_format="pdb")
params = {
    "ligands": ["CCO", "c1ccccc1O"],
    "target_structure": artifact_ref(target.id, "structure"),
}

assert client.workflows.validate(spec, params=params).valid
estimate = client.workflows.estimate(spec, params=params)  # USD hold at your tier

run = client.workflows.runs.run("dock-demo", spec, params=params, max_run_cost=estimate.total * 1.5)
# run.status is "completed" (or "paused" if it hit max_run_cost; call runs.resume)
for item in client.workflows.runs.artifacts(run.id).items:
    print(item.step_key, item.port, item.artifact_id, item.record_count)

runs.wait stops on completed, failed, cancelled, or paused (a paused run needs you to resume it). runs.run raises ProcessFailedError / ProcessCancelledError on failure.

Job and run outputs are durable artifacts: client.jobs.status(pid).result_artifact_id points at one. Inspect the manifest with client.artifacts.get(...) and fetch single records with download(..., record=...) instead of whole zips. Bind artifacts into workflow params or job payloads with artifact_ref(id, port).

Completion events

for event in client.events.listen(kind="workflow_run"):
    print(event.subject_id, event.status)  # re-read the run for detail

CogniChem Assistant (JWT)

client = CogniChem(access_token=token)
session = client.chat.sessions.create("Docking plan")
reply = client.chat.send(session.id, "Dock aspirin against COX-1", reasoning_effort="low")
print(reply.content, reply.billed_usd)
for proposal in client.chat.proposals.list(session.id).items:
    client.chat.proposals.approve(session.id, proposal.id, proposal.estimate_usd)

Each turn holds wallet funds at your tier's token rate and bills the metered tokens. A thread at its spend cap raises ConflictError (code == "session-spend-cap"); continue_spend_cap raises the cap.

Errors

API failures raise subclasses of CogniChemError parsed from RFC 7807 problem details (detail, title, status, type, request_id, retryability, errors). code is the problem type slug (for example missing-idempotency-key, insufficient-scope, spend-ceiling-exceeded, insufficient-wallet, session-spend-cap, estimate-changed), and body holds any extra fields.

Polling helpers raise PollTimeoutError, ProcessFailedError, or ProcessCancelledError when appropriate.

Examples

See examples/ for scripts covering utilities, inference, job submission, workflow templates, artifact records, science lookups, and the Assistant.

Live OpenAPI docs: https://api.cognichem.com/docs

Development

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
ruff check src tests
mypy
pytest
python scripts/sync_routes.py
# refresh the ROUTE_MAP snapshot from a monorepo checkout:
python scripts/sync_routes.py --backend-config ../cognichem/apps/back-end-api/src/core/config.py --write-snapshot

Migrating from 0.1.x

1.0 is a clean break. There is no compatibility shim for CogniChemClient / client.utility. See CHANGELOG.md.

License

Apache 2.0