Metadata-Version: 2.4
Name: immunocheck
Version: 0.1.0
Summary: Free API client for VHH nanobody immunogenicity & developability assessment
Home-page: https://github.com/salinas2000/immunocheck
Author: JFInnova
Author-email: fsalinas@jfinnova.es
Project-URL: Documentation, https://api.jfinnova.es/docs
Project-URL: Landing Page, https://jfinnova.es/immunocheck
Project-URL: Bug Tracker, https://github.com/salinas2000/immunocheck/issues
Keywords: nanobody,VHH,immunogenicity,developability,MHC-II,epitope,humanization,antibody,bioinformatics,biotherapeutics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ImmunoCheck

**Free API for VHH nanobody immunogenicity & developability assessment.**

Comprehensive immunogenicity risk scoring combining MHC-II epitope prediction, humanization scoring against 26 IGHV germlines, and full physicochemical developability profiling â€” in one API call.

No API key required. Free for academic and commercial use.

[![API Docs](https://img.shields.io/badge/API-Docs-emerald)](https://api.jfinnova.es/docs)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.8+](https://img.shields.io/badge/Python-3.8+-yellow.svg)](https://www.python.org)

## Quick Start

```bash
pip install immunocheck
```

```python
from immunocheck import analyze

result = analyze("QVQLVESGGGLVQPGGSLRLSCAASGFTFS...")

print(result["overall_risk"])                          # LOW / MODERATE / HIGH
print(result["risk_score"])                            # 0-10
print(result["humanization"]["humanization_grade"])    # A-F
print(result["developability"]["developability_grade"])  # A-D
```

## What It Does

ImmunoCheck runs three complementary analyses on your antibody/nanobody sequence:

| Analysis | What it checks |
|----------|---------------|
| **MHC-II Epitope Prediction** | Screens against 8 HLA-DRB1 alleles (EMA/FDA reference set). Identifies strong/weak binders and hotspot positions. |
| **Humanization Scoring** | Compares against 26 IGHV germlines. T20 score, framework identity, VHH hallmark residues (positions 37, 44, 45, 47). |
| **Developability Profiling** | MW, pI, GRAVY, instability index, aggregation hotspots, chemical liabilities (deamidation, oxidation, isomerization). |

Results are combined into an **overall immunogenicity risk score** (0-10) with a grade (LOW / MODERATE / HIGH).

## Usage

### Simple analysis

```python
from immunocheck import analyze

result = analyze(
    "QVQLVESGGGLVQPGGSLRLSCAASGFTFSSYNMS...",
    format="VHH",              # VHH, VH, scFv, or mAb_VH
    include_epitopes=False     # Set True for MHC-II prediction (slower)
)
```

### Client with options

```python
from immunocheck import ImmunoCheck

client = ImmunoCheck(timeout=180)

# Check API status
print(client.health())

# Analyze
result = client.analyze(sequence, format="VHH", include_epitopes=True)
```

### cURL

```bash
curl -X POST https://api.jfinnova.es/api/v1/immunocheck \
  -H "Content-Type: application/json" \
  -d '{"sequence": "QVQLVESGGGLVQPGG...", "format": "VHH"}'
```

### R

```r
library(httr)
library(jsonlite)

res <- POST(
  "https://api.jfinnova.es/api/v1/immunocheck",
  body = list(sequence = "QVQLVESGGGLVQPGG...", format = "VHH"),
  encode = "json", content_type_json()
)
data <- fromJSON(content(res, "text"))
```

## Response Format

```json
{
  "sequence_name": "VHH_116aa",
  "sequence_length": 116,
  "format": "VHH",
  "overall_risk": "LOW",
  "risk_score": 2.8,
  "humanization": {
    "best_germline": { "germline": "IGHV3-23", "identity": 0.82 },
    "t20_score": 0.847,
    "framework_identity": 0.79,
    "humanization_grade": "B",
    "hallmark_residues": [
      { "position": 37, "expected": "V", "found": "V", "is_canonical": true }
    ]
  },
  "developability": {
    "molecular_weight_da": 12634.5,
    "isoelectric_point": 8.21,
    "gravy": -0.312,
    "instability_index": 28.4,
    "is_stable": true,
    "liabilities": [],
    "aggregation_hotspots": [],
    "developability_grade": "A"
  }
}
```

## Rate Limits

| Limit | Value |
|-------|-------|
| Per minute | 5 requests |
| Per hour | 30 requests |
| Per day | 100 requests |
| Sequence length | 50-500 amino acids |

No API key required. For higher limits, contact fsalinas@jfinnova.es.

## Interactive Playground

Try it in your browser: **[jfinnova.es/immunocheck](https://jfinnova.es/immunocheck)**

Full API documentation: **[api.jfinnova.es/docs](https://api.jfinnova.es/docs)**

## Built By

**[JFInnova](https://jfinnova.es)** â€” AI-driven nanobody therapeutics for neuroinflammation.

## License

MIT
