GlycanBench

A Python package for glycomics and glycobiology analysis: format conversion, 2D/3D structure rendering, biosynthetic networks, descriptors, clustering, sequence alignment, immunogenicity prediction, and an AI research chat assistant.

Every capability is usable three ways: as a Python SDK (no server), from the command line, or over HTTP via an optional FastAPI server.

Install

pip install -e .
# with dev/test tooling:
pip install -e ".[dev,test]"

Heavy scientific dependencies (RDKit, PyTorch, glycowork, etc.) install automatically from pyproject.toml.

Quick start

As a library (no server)

import glycanbench as gb

gb.create.convert("Gal(b1-4)Glc", input_format="iupac")
gb.visualize.draw_2d("Gal(b1-4)GlcNAc", highlight_motif="Gal(b1-4)GlcNAc")
gb.predict.immunogenicity("Gal(a1-3)Gal(b1-4)GlcNAc")
gb.cluster.three_or_more([
    {"name": "Lactose", "iupac": "Gal(b1-4)Glc"},
    {"name": "LacNAc", "iupac": "Gal(b1-4)GlcNAc"},
])

gb.tool_inventory() lists every function by category; gb.route_map() maps the original web UI's pages to their SDK equivalents.

See examples/glycanbench_demo.ipynb for a full walkthrough of every capability.

From the command line

glycanbench create convert --glycan "Gal(b1-4)Glc" --input-format iupac
glycanbench visualize draw --glycan "Gal(b1-4)Glc" --output snfg.png
glycanbench cluster multiple --glycans '[{"name":"A","smiles":"CCO"},{"name":"B","smiles":"CCN"}]' --output cluster.png
glycanbench predict validate --sequence "Gal(b1-4)Glc"
glycanbench --help          # full command tree

Command groups mirror the SDK: create, visualize, analyse, compare, align, cluster, predict, chat, data, plus server and version. Run glycanbench <group> --help for a group's subcommands.

As an HTTP server

glycanbench server --reload
# or: python start_server.py

• Server: http://127.0.0.1:5000
• Interactive docs: http://127.0.0.1:5000/docs
• ReDoc: http://127.0.0.1:5000/redoc

Package structure

glycanbench/
├── core/          Plain-Python logic (no FastAPI/Pydantic) -- convert, compare, descriptor,
│                  insight, motif, pathway, seq_align, species, visualize, draw,
│                  characterize, cluster, network, model
├── api/           Thin FastAPI routers -- Pydantic models + a call into core/, per feature
│   └── chat/      GlycomicsChat (LLM-backed research assistant)
├── sdk.py         Public SDK -- imports from core/ directly, no FastAPI dependency at call time
├── cli.py         Command-line interface, wraps sdk.py
├── app.py         FastAPI application factory (mounts api/ routers)
├── config.py      Settings (env vars, .env)
├── dataset/       Bundled reference data (GLYSUM matrix, species data, monosaccharide counts)
├── models/        MPNN immunogenicity model checkpoint
└── vocab/         Glycoword vocabulary for the prediction model

examples/          glycanbench_demo.ipynb -- full SDK walkthrough
tests/             Package structure, route, and SDK smoke tests

core/ has zero FastAPI/Pydantic imports — it's the part that matters if you're only using the SDK or CLI. api/ exists purely to expose the same core/ logic over HTTP.

Configuration

Copy .env.example to .env and set what you need:

GROQ_API_KEY=your_groq_api_key_here   # required for gb.chat.ask(...)

Only gb.chat.ask(...) / glycanbench chat need GROQ_API_KEY; everything else works without any API keys.

Getting a Groq API key

1. Go to console.groq.com and sign in (Google/GitHub or email).
2. Open API Keys in the left sidebar.
3. Click Create API Key, give it a name, copy the key (starts with gsk_...) — it's only shown once.

Setting GROQ_API_KEY

Pick one:

.env file (recommended, picked up automatically):

GROQ_API_KEY=gsk_your_actual_key_here

Never commit .env — it's already in .gitignore.

Windows PowerShell (current session only):

$env:GROQ_API_KEY = "gsk_your_actual_key_here"

Windows PowerShell (persist across sessions):

[System.Environment]::SetEnvironmentVariable("GROQ_API_KEY", "gsk_your_actual_key_here", "User")

Restart your terminal/IDE after running this for it to take effect.

macOS/Linux (bash/zsh):

export GROQ_API_KEY="gsk_your_actual_key_here"     # current session
echo 'export GROQ_API_KEY="gsk_your_actual_key_here"' >> ~/.bashrc   # persist

Verify it's set:

import os
print(bool(os.getenv("GROQ_API_KEY")))   # True if set

Development

make install-dev   # pip install -e ".[dev,test]" + dev requirements
make test           # pytest tests/ -v --cov=glycanbench
make lint            # flake8 + mypy + black --check + isort --check-only
make format           # black + isort
make server            # glycanbench server --reload
make build              # python -m build

See the Makefile for the full command list.

License

MIT — see LICENSE.