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

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

Optional idempotency_key= on mutating POSTs (jobs, inference, utils submit).

Async twin: AsyncCogniChem with the same method names (await client.jobs.run(...)).

Errors

API failures raise subclasses of CogniChemError parsed from RFC 7807 problem details (detail, title, status, type, request_id, errors on 422).

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

Examples

See examples/ for scripts covering utilities, inference, and job submission.

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

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