hla-compass 3.3.0

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 and integrations on the HLA-Compass platform.

🚀 Quick Start

# 1. Install
pip install "hla-compass>=2.0.2"

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

# 3. Optionally pin a default organization for publish operations
hla-compass auth use-org 00000000-0000-0000-0000-000000000000 --env dev

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

# 5. Validate and smoke test
hla-compass validate
hla-compass test --input examples/sample_input.json

# 6. Publish (source-upload — the platform builds the container)
hla-compass publish --env dev --scope org --wait

This README is intentionally concise. The canonical module-authoring workflow lives in ../../internal-docs/guides/module-developer/onboarding.md.

📚 Docs Model

• ../../internal-docs/guides/module-developer/onboarding.md: canonical workflow for module authors.
• ../../internal-docs/guides/module-developer/golden-workflow.md: canonical GitHub Actions and OIDC release automation path.
• SKILL.md generated by hla-compass init: canonical in-module runtime and API reference for developers and AI assistants.
• CLAUDE.md generated by hla-compass init: short in-module orientation that points back to SKILL.md.
• ../../internal-docs/guides/sdk-developer/index.md: SDK contributor and integration guidance.

---

🤖 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	Canonical in-module reference. Covers the runtime contract, helper APIs, testing patterns, and current publish commands. Point your AI assistant here first.
CLAUDE.md	Concise in-module orientation 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 a containerized module smoke execution
dev	Run the interactive local rerun loop
serve	Serve the UI template locally
publish	Upload module source to the platform for server-side build and registration
publish-status	Inspect or watch module intake status
auth	Manage platform login and keys
mcp	Print MCP schema or run a local MCP server for the current module

---

🔧 Local SDK Development

When iterating on the SDK itself, use the HLA_COMPASS_SDK_PATH environment variable so that dev/test/serve commands pick up your local checkout:

export HLA_COMPASS_SDK_PATH=../sdk/python
hla-compass dev
hla-compass test --input examples/sample_input.json

---

💎 Key Features

• Module-first CLI: Scaffold, test, and publish with a single toolchain.
• Source-upload publishing: hla-compass publish uploads source; the platform builds the container, scans it, and registers the module. No Docker, GHCR, or signing keys required.
• Data helpers: Storage + data access helpers for module runtimes.
• Local dev loop: Containerized dev/serve/test flow that matches production.

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

Compute Types

Public module manifests use these compute types:

• lambda
• fargate
• batch

docker remains accepted only as a legacy publish alias and is normalized to fargate.

Scientific Helper Notes

The convenience helpers get_hla_alleles(), get_hla_frequencies(), and get_protein_coverage() are implemented as typed REST calls in SDK 3.0.0+. They no longer switch implicitly between direct database access and REST.

Migration guidance:

• High-level SDK callers now need a reachable HLA-Compass API endpoint for these helpers.
• Module runtimes that need direct DB access should use ScientificQuery or self.data.sql.query(...) explicitly.
• API-key authenticated clients continue to work; the SDK now targets /v1/api/data/... typed endpoints instead of issuing raw SQL on the caller's behalf.
• Plain JWT user sessions now work through /v1/data/... typed endpoints.

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

• Developer Guide – Top-level developer entrypoint.
• Module Developer Handbook – Canonical module workflow and references.
• API Reference – Repo API reference surface.

---

🤝 Support & Issues

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