Python SDK
Typed synchronous and asynchronous clients for chemistry and evidence.
Install the verified build, set CYBERRXN_API_KEY, then use Client or AsyncClient. Python 3.10+ is required. Responses are Pydantic models; their field names follow API snake_case.
Search and inspect
from cyberrxn import Client
with Client() as client:
page = client.molecule_reactions(
"CCN1CCN(CO)C(=O)C1=O", role="product", limit=3
)
if page.items:
observation = client.get_observation(page.items[0].observation_id)
print(observation.paragraph_text)
print(observation.conditions.pressure.status)Use an observation ID from the response. Inspect paragraph_text and correction_provenance before interpreting source conditions.
Validate and balance
from cyberrxn import Client
with Client() as client:
checked = client.validate_reaction("CCO>>CC=O")
print(checked.valid, checked.atom_balance.hydrogen_balanced)
balanced = client.balance_reaction("[H][H].O=O>>O")
if balanced.solved and balanced.balanced_reaction_smiles:
formula = client.convert_smiles(balanced.balanced_reaction_smiles)
print(formula.unicode)method="coefficients" changes supplied stoichiometric coefficients only. Explicit method="synrbl" requests the isolated model for missing-species hypotheses; inspect its imputed_species and limitations.
Async client
import asyncio
from cyberrxn import AsyncClient
async def main():
async with AsyncClient() as client:
result = await client.validate_reaction("CCO>>CC=O")
print(result.atom_balance.delta)
asyncio.run(main())Main methods
| Purpose | Method |
|---|---|
| Corpus and usage | stats(), usage() |
| Evidence search | search_reactions(...), lookup_reaction(...), molecule_reactions(...) |
| Full evidence and relationships | get_observation(...), graph(...) |
| Structural analogues | similar_products(...) |
| Chemical checks | validate_reaction(...), balance_reaction(...) |
| Representation conversion | convert_smiles(...), convert_representation(...) |
| Current guide | get_reaction_skill() |
| Corpus reports | report_observation_issue(...), get_report(...), reports(...) |
| Contributions | submit_reaction_contribution(...), get_contribution(...), contributions(...) |
iter_search_reactions, iter_lookup_reaction and iter_molecule_reactions fetch subsequent pages lazily. Each fetched chemistry/evidence page is another metered call. Use a small result limit and stop when you have enough evidence.
Errors and retries
Catch APIError and inspect status_code, code, retryable and request_id. Typed HTTP exceptions include AuthenticationError, PaymentRequiredError, RateLimitError and ValidationError. A returned chemistry valid=False is a normal result; it is not the HTTP ValidationError exception.
Reports and contributions use a stable idempotency_key. Reuse it for one logical submission and its retries. Do not submit private conversation or confidential laboratory data. Error contract · Contributions.