hla-compass 2.1.2

Python SDK for HLA-Compass bioinformatics platform - Build powerful modules for immuno-peptidomics analysis

HLA-Compass Python SDK

The official Python SDK (Python 3.11+) for developing modules on the HLA-Compass platform.

🚀 Quick Start

# 1. Install (requires Python 3.11+)
pip install hla-compass

# 2. Setup
hla-compass auth login --env dev

# 3. Create
hla-compass init my-module --template no-ui
cd my-module

# 4. Test
hla-compass test --input examples/sample_input.json

# 5. Ship
hla-compass build --tag ghcr.io/acme-bio/my-module:1.0.0 --push
hla-compass sign-image --image-ref ghcr.io/acme-bio/my-module:1.0.0 --generate-keys
hla-compass verify-image --env dev --image-ref ghcr.io/acme-bio/my-module:1.0.0 --generate-keys
hla-compass publish --env dev --image-ref ghcr.io/acme-bio/my-module:1.0.0 --wait --generate-keys

This external publish flow assumes your organization has already approved the image namespace and configured a source-registry pull credential for it.

📚 New to HLA-Compass? Try the Ten-Minute Tutorial.

---

🤖 AI-Assisted Development

Every module scaffolded by hla-compass init includes two reference files designed for both human developers and AI coding assistants:

File	Purpose
SKILL.md	Complete development reference. Covers the full Module API, all self.api / self.data / self.storage / self.db methods, manifest schema, data access patterns, MCP integration, testing, publishing, and common recipes. Point your AI assistant here first.
CLAUDE.md	Concise AI context file. Quick-reference for architecture, key commands, and import conventions. References SKILL.md for details.

Tip: When using an AI coding assistant (Claude, Copilot, etc.), ensure it reads SKILL.md in your module directory. It contains everything needed to build a correct, production-ready HLA-Compass module without guessing at API signatures or platform conventions.

---

🛠️ CLI Entry Points

Command	Description
init	Scaffold a new module (includes SKILL.md reference guide)
validate	Validate module structure and manifest
test	Run module execution (local or remote context)
build	Build a module image on top of the managed module runtime base image
sign-image	Sign a pre-built image with the local Cosign keypair
verify-image	Verify an image against resolved platform signer + scan policy
publish	Register a pre-built signed external image, or use the internal managed publish path
auth	Manage platform login and keys

---

🔧 Local SDK Development

When iterating on the SDK itself, build images against your local checkout:

hla-compass build --sdk-path ../sdk/python
# or set HLA_COMPASS_SDK_PATH=../sdk/python for dev/test/serve/build

To target a specific architecture:

hla-compass build --platform linux/amd64

Multi-arch builds require --platform linux/amd64,linux/arm64 --push.

---

💎 Key Features

• Module-first CLI: Scaffold, build, test, and publish with a single toolchain.
• Signed publishing: Keys + manifest signing baked into publish.
• Signer-aware verification: verify-image resolves org registry trust before publish starts.
• Data helpers: Storage + data access helpers for module runtimes.
• Local dev loop: Containerized dev/serve/test flow that matches production.

External GHCR publishing is image-first. The supported contract is:

1. Build the image with hla-compass build (the generated Dockerfile defaults to ghcr.io/alitheabio/hla-compass-module-runtime:py311-trixie).
2. Sign it with either GitHub Actions OIDC or hla-compass sign-image.
3. Verify it with hla-compass verify-image.
4. Publish it with hla-compass publish --image-ref ... --wait.

The CLI uses the active org for the selected environment by default, or --org-id to override it.

Scientific Helper Notes

The convenience helpers get_hla_alleles(), get_hla_frequencies(), and get_protein_coverage() are implemented, but they rely on scientific-query capability rather than dedicated JWT user endpoints. In practice that means:

• Module runtimes with DB access work.
• API-key authenticated programmatic clients work.
• Plain JWT-only user sessions do not yet expose separate REST routes for these helpers.

predict_hla_binding() is also implemented, but it is a wrapper over an async module run and requires a configured binding module id (HLA_BINDING_MODULE_ID or hla_binding_module_id in SDK config).

---

📖 Advanced Documentation

• Installation Guide – Detailed setup for various roles.
• Module Developer Handbook – Best practices and deep dives.
• API Reference – Full Pydoc catalog of classes and methods.

---

🤝 Support & Issues

• Bugs: GitHub Issues
• Discussion: #hla-compass-dev Slack channel