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

## 🚀 Quick Start

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

## 📚 Docs Model

- [../../internal-docs/guides/module-developer/onboarding.md](../../internal-docs/guides/module-developer/onboarding.md): canonical workflow for module authors.
- [../../internal-docs/guides/module-developer/golden-workflow.md](../../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](../../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:

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

## 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](../../internal-docs/guides/index.md)** – Top-level developer entrypoint.
- **[Module Developer Handbook](../../internal-docs/guides/module-developer/index.md)** – Canonical module workflow and references.
- **[API Reference](../../internal-docs/components/api/API_REFERENCE.md)** – Repo API reference surface.

---

## 🤝 Support & Issues

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