hla-compass 1.5.4

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

HLA-Compass Python SDK

The official Python SDK for developing modules on the HLA-Compass platform.

Requirements

• Python 3.8 or higher (3.8, 3.9, 3.10, 3.11, 3.12, 3.13 supported)
• pip package manager

Installation

Install from PyPI (Recommended)

pip install hla-compass

For development tools:

pip install hla-compass[dev]

For data export features (DataFrame/Excel support):

pip install hla-compass[data]

For machine learning modules:

pip install hla-compass[ml]

Install from Source (Latest Development Version)

# Clone the repository
git clone https://github.com/AlitheaBio/HLA-Compass-platform.git
cd HLA-Compass-platform/sdk/python

# Install in development mode
pip install -e .

Quick Start

# Install SDK
pip install hla-compass

# Create module
hla-compass init my-module --type no-ui --compute lambda

# Test locally
cd my-module
hla-compass test --local

# Build package
hla-compass build

📚 For complete development guide, see: /docs/MODULE_DEVELOPMENT_GUIDE.md

Module Development

For comprehensive module development information including:

• Base Module class and APIs
• Data access patterns
• Storage operations
• Error handling
• Testing strategies
• Deployment workflows

See the complete guide: /docs/MODULE_DEVELOPMENT_GUIDE.md

CLI Commands

Module Management

# Create new module
hla-compass init <name> [options]
# Options: --yes (skip prompts), --template, --type, --compute

# Validate module structure
hla-compass validate [--json]  # --json for machine-readable output

# Test module (auto-detects local vs remote based on auth)
hla-compass test [--input FILE] [--verbose]

# Test locally without API
hla-compass test --local [--input FILE]

# Test against real API (requires auth)
# Note: Remote mode currently executes locally with API authentication context
# Full remote execution on the platform is on the roadmap
hla-compass test --remote [--input FILE]

# Output as JSON for CI/automation
hla-compass test --json [--input FILE]

# Package signing
hla-compass sign <package-file>

# Deploy module
hla-compass deploy <package-file> [--env ENV]

# List deployed modules
hla-compass list [--env ENV]

Authentication

# Login to platform
hla-compass auth login --env dev

# Logout
hla-compass auth logout

# Register as a developer (self-service)
hla-compass auth register [--env ENV]

CLI Feature Matrix

Command	Description	Status
hla-compass configure	Initialize SDK config and signing keys	Available
hla-compass init	Scaffold a new module from templates	Available
hla-compass validate	Validate module structure and manifest	Available
hla-compass test --local	Run module locally without API	Available
hla-compass test --remote	Run locally with API auth context	Available (executes locally)
hla-compass auth login/logout/register	Authentication flows	Available
hla-compass build	Build package; signs manifest by default	Available
hla-compass sign	Sign an existing package/directory	Available
hla-compass publish	Build/sign and publish to platform	Available
hla-compass deploy	Deploy published module to environment	Available
hla-compass list	List deployed modules	Available
hla-compass test	Test module execution (local/remote)	Available
hla-compass templates list	List module templates	Planned
hla-compass local-services	Start local DB/S3 dev services	Planned

Notes:

• --remote test currently executes locally with API authentication context; full remote execution is on the roadmap.
• For end-to-end deployments, prefer the publish path integrated with the platform pipelines.

Testing

Unit Testing

# tests/test_module.py
import pytest
from hla_compass.testing import ModuleTester, MockContext

def test_module_execution():
    tester = ModuleTester()
    
    input_data = {
        'sequence': 'MLLSVPLLL',
        'threshold': 0.5
    }
    
    result = tester.test_local(
        'backend/main.py',
        input_data
    )
    
    assert result['status'] == 'success'
    assert len(result['results']) > 0

Integration Testing

# Test with mock API data
def test_with_mock_data():
    context = MockContext.create(
        api_data={
            'peptides': [
                {'id': '1', 'sequence': 'MLLSVPLLL'},
                {'id': '2', 'sequence': 'SIINFEKL'}
            ]
        }
    )
    
    result = tester.test_local(
        'backend/main.py',
        {'min_length': 8},
        context
    )
    
    assert len(result['results']) == 2

Performance Testing

# Benchmark module performance
def test_performance():
    tester = ModuleTester()
    
    results = tester.benchmark(
        'backend/main.py',
        input_data,
        iterations=100
    )
    
    assert results['average_time'] < 0.1  # 100ms

Advanced Features

Module Types

Lambda Modules (Quick Analysis)

• Execution time: <15 minutes
• Memory: 128MB - 10GB
• Best for: Simple calculations, data filtering

Fargate Modules (Long Running)

• Execution time: <8 hours
• Memory: 512MB - 30GB
• Best for: Complex pipelines, batch processing

SageMaker Modules (ML Inference)

• GPU support available
• Pre-trained model hosting
• Best for: Machine learning predictions

With-UI Modules

For modules with frontend components:

// frontend/index.tsx
import React from 'react';
import { ModuleProps } from '@hla-compass/sdk';

export const ModuleUI: React.FC<ModuleProps> = ({
  input,
  onExecute,
  result
}) => {
  return (
    <div>
      {/* Your UI here */}
    </div>
  );
};

Custom Validation

class MyModule(Module):
    def validate_inputs(self, input_data):
        # Call parent validation
        validated = super().validate_inputs(input_data)
        
        # Custom validation
        sequence = validated.get('sequence', '')
        if not all(aa in 'ACDEFGHIKLMNPQRSTVWY' for aa in sequence):
            raise ValidationError("Invalid amino acids in sequence")
        
        return validated

Best Practices

1. Input Validation: Always validate inputs thoroughly
2. Error Handling: Use try-except blocks and provide clear error messages
3. Logging: Use appropriate logging levels (debug, info, warning, error)
4. Performance: Process data in batches when possible
5. Memory: Stream large results instead of loading all into memory
6. Security: Never hardcode credentials or sensitive data
7. Testing: Write comprehensive tests for all functionality
8. Documentation: Document inputs, outputs, and algorithms clearly

Environment Variables

• HLA_COMPASS_ENV: Default environment (dev, staging, prod) - takes precedence over HLA_ENV
• HLA_ENV: Alternative environment variable (used if HLA_COMPASS_ENV not set)
• HLA_COMPASS_CONFIG_DIR: Configuration directory (default: ~/.hla-compass)
• HLA_COMPASS_LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR)
• HLA_CORRELATION_ID: Optional global correlation ID propagated as X-Correlation-Id

Troubleshooting

Common Issues

1. Import Errors: Ensure all dependencies are in requirements.txt
2. Timeout Errors: Increase timeout in manifest.json or optimize code
3. Memory Errors: Process data in smaller chunks or increase memory
4. Authentication Errors: Run hla-compass auth login to refresh tokens

Debug Mode

Enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)

Request Headers & Tracing

The SDK standardizes outbound request headers and retry behavior.

• Accept: Always application/json (session default)
• User-Agent: hla-compass-sdk/<version> python/<version> os/<platform>
• Content-Type: application/json for JSON requests (per-call)
• X-Request-Id: Unique UUID per HTTP attempt (changes on retry)
• X-Correlation-Id: Optional global correlation ID for cross-service tracing
  • Set environment variable HLA_CORRELATION_ID to propagate a stable value
  • Added to both SDK auth requests and APIClient requests
• Idempotency-Key: Added to POST requests to make retries safe
  • A stable UUID is generated per SDK call and reused across retry attempts
  • Server-side should de-duplicate requests using this key

Retry Policy

• GET/HEAD/OPTIONS: Retries enabled (connection/read) with exponential backoff via urllib3.Retry
• 401 Unauthorized: One automatic token refresh (Auth.refresh_token) and retry
• 429 Too Many Requests: Honors Retry-After (falls back to exponential backoff)
• 5xx Server Errors: Exponential backoff; for POST, retries only when an Idempotency-Key is present (the SDK adds one per call)
• Timeouts/Network errors: Limited retries with backoff for transient connection issues

Tip: For end-to-end traceability, set HLA_CORRELATION_ID in your environment and pass it across your systems.

Deployment Note: SimpleDeployer (Deprecated / Dev-only)

The legacy hla_compass.deployer.SimpleDeployer utility is disabled by default and intended only for local development experiments. It bypasses platform authentication and infrastructure pipelines.

• Disabled by default; to enable explicitly set HLA_ENABLE_SIMPLE_DEPLOYER=1.
• Recommended path: use hla-compass build + hla-compass publish/deploy and the platform’s Serverless/Terraform pipelines.

Support

• Complete Guide: /docs/MODULE_DEVELOPMENT_GUIDE.md
• Examples: /modules/examples/
• Issues: GitHub Issues
• Quick Start: /docs/MODULE_DEVELOPMENT_GUIDE.md#quick-start

License

Copyright © 2024 Alithea Bio. All rights reserved.