Metadata-Version: 2.4
Name: glycanbench
Version: 1.0.0
Summary: Unified computational platform for glycomics and glycobiology research
Author-email: Ashok Palaniappan and Vigneshwaran CJ <apalania@scbt.sastra.edu>
License: MIT
Project-URL: Homepage, https://glycanbench.sastra.edu
Project-URL: Repository, https://github.com/APalaniaLab/GlycanBench
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.6
Requires-Dist: uvicorn>=0.32.1
Requires-Dist: python-multipart
Requires-Dist: pydantic>=2.12.4
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: langchain-groq>=1.1.1
Requires-Dist: langchain-community>=0.4.1
Requires-Dist: langchain-core>=1.2.2
Requires-Dist: numpy>=1.24.3
Requires-Dist: pandas>=2.0.3
Requires-Dist: scipy>=1.10.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: seaborn>=0.12.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: glycowork[chem]>=1.5.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pymupdf>=1.24.0
Requires-Dist: glypy>=1.0.17
Requires-Dist: biopython>=1.85
Requires-Dist: rdkit>=2024.9.6
Requires-Dist: torch>=2.9.1
Requires-Dist: torch-geometric>=2.7.0
Requires-Dist: requests>=2.31.0
Requires-Dist: urllib3>=2.0.4
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: isort>=5.10.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: httpx>=0.24.0; extra == "test"
Dynamic: license-file

# GlycanBench

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
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)

```python
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](examples/glycanbench_demo.ipynb) for a full walkthrough of every capability.

### From the command line

```bash
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

```bash
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:

```env
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](https://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):**

```env
GROQ_API_KEY=gsk_your_actual_key_here
```

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

**Windows PowerShell (current session only):**

```powershell
$env:GROQ_API_KEY = "gsk_your_actual_key_here"
```

**Windows PowerShell (persist across sessions):**

```powershell
[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):**

```bash
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:

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

## Development

```bash
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](Makefile) for the full command list.

## License

MIT — see [LICENSE](LICENSE).
