# HLA-Compass Python SDK

[![PyPI version](https://badge.fury.io/py/hla-compass.svg)](https://badge.fury.io/py/hla-compass)
[![Python Versions](https://img.shields.io/pypi/pyversions/hla-compass.svg)](https://pypi.org/project/hla-compass/)

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

## 🚀 Quick Start

```bash
# 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](../../internal-docs/guides/module-developer/tutorial.md)**.

---

## 🤖 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:

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

```bash
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](../../internal-docs/guides/index.md)** – Detailed setup for various roles.
- **[Module Developer Handbook](../../internal-docs/guides/module-developer/index.md)** – Best practices and deep dives.
- **[API Reference](https://developer.alithea.bio/sdk)** – Full Pydoc catalog of classes and methods.

---

## 🤝 Support & Issues

- **Bugs**: [GitHub Issues](https://github.com/AlitheaBio/HLA-Compass-platform/issues)
- **Discussion**: #hla-compass-dev Slack channel
