hla-compass 2.1.3

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. Build, sign, verify, publish
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 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
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; omit --image-ref only for controlled SDK and internal workflows
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, 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

• 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