helix-sdk 1.0.3

Semantic image compression for AI training datasets

HELIX SDK

Semantic image compression for AI training. Convert images into compact blueprints containing identity-critical information for regeneration at any resolution.

What's New in 1.0.2

• 🌐 Remote Mode - Use HELIX via API without heavy local dependencies
• 📦 Lightweight Install - Core package now only requires httpx, numpy, pillow
• 🏢 Data Center Ready - Perfect for cloud storage and on-demand materialization

Features

• 10-20x compression - Store blueprints, not pixels
• On-demand materialization - Reconstruct at 256p to 8K from same file
• Infinite variants - Generate augmentation variants per image
• ML-ready loaders - PyTorch-compatible Dataset and DataLoader
• Remote or Local - Use API or run locally with full models

Installation

# Lightweight (Remote Mode - recommended for most users)
pip install helix-sdk

# With local processing (requires Gemini API key)
pip install helix-sdk[local]

# With PyTorch support
pip install helix-sdk[ml]

Quick Start

Remote Mode (Recommended)

from helix_sdk import HelixSDK

# Connect to HELIX API (no local models needed!)
sdk = HelixSDK(base_url="https://api.helix-codec.dev")

# Compress - sends image to API, receives .hlx
result = sdk.compress("image.jpg", "image.hlx")

# Materialize at any resolution
sdk.materialize("image.hlx", "output.png", resolution="4K")

Local Mode

from helix_sdk import HelixSDK

# Use local models (requires pip install helix-sdk[local])
sdk = HelixSDK(mode="local", api_key="your-gemini-key")

sdk.compress("image.jpg", "image.hlx")
sdk.materialize("image.hlx", "output.png", resolution="4K")

ML Training

from helix_sdk import HelixDataset, HelixLoader

# Works with both local and remote mode!
dataset = HelixDataset(
    "/data/hlx/", 
    target_resolution="512p",
    base_url="https://api.helix-codec.dev"  # Optional: use API
)

loader = HelixLoader(dataset, batch_size=64, num_workers=4)

for batch in loader:
    model.train_step(batch)

API Reference

HelixSDK

HelixSDK(
    api_key=None,           # Gemini API key (for local mode)
    base_url=None,          # HELIX API URL (enables remote mode)
    mode="auto",            # "auto", "local", or "remote"
    default_resolution="1080p"
)

Method	Description
compress(input, output)	Compress image to HLX
materialize(input, output, resolution)	Reconstruct from HLX
compress_directory(in_dir, out_dir)	Batch compression
get_info(hlx_path)	Get HLX metadata

HelixDataset

HelixDataset(
    path="/data/hlx/",
    target_resolution="512p",
    enable_variants=True,
    cache_materializations=True,
    base_url=None,          # Optional: enable remote mode
    api_key=None
)

BatchCompressor

from helix_sdk import BatchCompressor

compressor = BatchCompressor(workers=8)
stats = compressor.compress_directory("/images/", "/hlx/")

CLI

helix compress image.jpg
helix materialize image.hlx -r 4K
helix batch /images/ /output/ -w 8
helix info image.hlx

Environment Variables

Variable	Description
HELIX_API_URL	Default API URL for remote mode
GEMINI_API_KEY	Gemini API key for local mode

Benchmarks

Metric	Value
Compression Ratio	10-20x
Identity Match (SSIM)	98.7%
Materialization Time	~3s

Requirements

• Python >= 3.10
• For local mode: Gemini API key (GEMINI_API_KEY)
• For remote mode: HELIX API access (HELIX_API_URL)

License

MIT