Metadata-Version: 2.4
Name: helix-sdk
Version: 1.0.1
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: opencv-python>=4.8.0
Requires-Dist: google-genai>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
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,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.

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

## Installation

```bash
pip install helix-sdk
```

With PyTorch support:
```bash
pip install helix-sdk[ml]
```

## Quick Start

```python
from helix_sdk import HelixSDK

sdk = HelixSDK()

# Compress
result = sdk.compress("image.jpg", "image.hlx")

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

## ML Training

```python
from helix_sdk import HelixDataset, HelixLoader

dataset = HelixDataset("/data/hlx/", target_resolution="512p")
loader = HelixLoader(dataset, batch_size=64, num_workers=4)

for batch in loader:
    model.train_step(batch)
```

## API

### HelixSDK

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

### HelixLoader

```python
HelixLoader(
    dataset,
    batch_size=64,
    num_workers=4,
    variants_per_image=3
)
```

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

## Benchmarks

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

## Requirements

- Python >= 3.10
- Gemini API key (set `GEMINI_API_KEY` env var)

## License

MIT
