Metadata-Version: 2.4
Name: helix-sdk
Version: 1.0.3
Summary: Semantic image compression for AI training datasets
Author-email: HELIX Team <team@helix-codec.dev>
License: MIT
Project-URL: Homepage, https://github.com/DB0SZ1/PROJECT-HELIX
Project-URL: Documentation, https://github.com/DB0SZ1/PROJECT-HELIX#readme
Project-URL: Repository, https://github.com/DB0SZ1/PROJECT-HELIX.git
Project-URL: Issues, https://github.com/DB0SZ1/PROJECT-HELIX/issues
Keywords: image-compression,ai,machine-learning,deep-learning,pytorch,gemini,computer-vision,dataset,training
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Multimedia :: Graphics :: Graphics Conversion
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24.0
Requires-Dist: pillow>=9.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: local
Requires-Dist: opencv-python>=4.8.0; extra == "local"
Requires-Dist: google-genai>=1.0.0; extra == "local"
Provides-Extra: ml
Requires-Dist: torch>=2.0.0; extra == "ml"
Requires-Dist: torchvision>=0.15.0; extra == "ml"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: all
Requires-Dist: helix-sdk[dev,local,ml]; extra == "all"

# 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

```bash
# 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)

```python
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

```python
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

```python
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

```python
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

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

### BatchCompressor

```python
from helix_sdk import BatchCompressor

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

## CLI

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