euleris

Topological molecular analysis — the official Python client for the Euleris API.

euleris is a thin HTTP client. All computation (spectrum extraction, scoring, ADME/toxicity prediction, similarity search) runs server-side on the Euleris compute engine. The client just sends SMILES and returns typed results.

Install

pip install euleris
# optional: DataFrame support
pip install "euleris[pandas]"

Authentication

Get an API key (ek_...) from https://cognitive-engineering.dev/pricing.

Provide it in any of these ways (checked in this order):

1. Environment variable:

   export EULERIS_API_KEY=ek_your_key
   

2. Config file ~/.euleris/config:

   [default]
   api_key = ek_your_key
   

3. Explicitly in code:

   import euleris
   euleris.configure(api_key="ek_your_key")
   

Quickstart

import euleris

# Analyze a single molecule
result = euleris.analyze("CCO")
print(result.score)          # topological score
print(result.spectrum)       # {"N3": 0, "N6": 1, ...}
print(result.meta.atoms)     # 3

# Structural descriptors (V1.4)
print(result.N6_m)           # aromatic cycle density N6/m
print(result.phi)            # fraction of bonds on at least one cycle
print(result.rho_lq)         # bridge/hub criticality correlation, None if not computed
print(result.spectral.q1)    # full spectral block when rho_lq is available

# Batch analysis
batch = euleris.batch(["CCO", "c1ccccc1", "CC(=O)O"])
print(batch.stats)           # {"total": 3, "valid": 3, "invalid": 0}
df = batch.to_dataframe()    # requires euleris[pandas]

# Compare two molecules
cmp = euleris.compare("c1ccccc1", "c1ccncc1")
print(cmp.delta_score)

# Similarity search
sim = euleris.similar("c1ccccc1", top_k=5, library="zinc")
for match in sim.matches:
    print(match.smiles, match.similarity)

Using an explicit client

from euleris import EulerisClient

client = EulerisClient(api_key="ek_your_key")
result = client.analyze("CCO")

Error handling

from euleris import EulerisError, AuthError, RateLimitError, InvalidSmilesError

try:
    euleris.analyze("not-a-molecule")
except InvalidSmilesError as e:
    print("Bad SMILES:", e)
except RateLimitError as e:
    print("Slow down:", e)
except AuthError as e:
    print("Check your key:", e)
except EulerisError as e:
    print("Something went wrong:", e)

Links

• API docs: https://cognitive-engineering.dev/euleris/app/api-docs
• Pricing / API keys: https://cognitive-engineering.dev/pricing

License

Proprietary. Copyright (c) 2026 Cognitive Engineering / David Martin Venti.