Metadata-Version: 2.4
Name: lexigram-multimedia-upscale
Version: 0.1.0
Summary: Image and video super-resolution for the Lexigram Framework — Real-ESRGAN and HAT backends
Project-URL: Homepage, https://lexigram.dev
Project-URL: Repository, https://github.com/dbtinoy-/lexigram-multimedia-experimental
Project-URL: Issues, https://github.com/dbtinoy-/lexigram-multimedia-experimental/issues
Project-URL: Changelog, https://github.com/dbtinoy-/lexigram/blob/main/CHANGELOG.md
Author-email: Lexigram Framework Team <team@lexigram.dev>
Maintainer-email: Lexigram Framework Team <team@lexigram.dev>
License: MIT
License-File: LICENSE
Keywords: ai,framework,lexigram,multimedia,super-resolution,upscale
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: lexigram-contracts>=0.1.0
Requires-Dist: lexigram>=0.1.1
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: hat-server
Provides-Extra: real-esrgan-server
Provides-Extra: test
Requires-Dist: lexigram-testing>=0.1.1; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# lexigram-multimedia-upscale

Image and video super-resolution for the Lexigram Framework — local reference-server backends (`real-esrgan`, `hat`).

---

## Overview

`lexigram-multimedia-upscale` upscales images 2x or 4x with Real-ESRGAN or HAT reference servers, and registers a `VideoUpscaleService` for frame-level video upscaling when a `VideoProcessor` is available in the container.

> Full documentation: [docs.lexigram.dev](https://docs.lexigram.dev)

## Install

```bash
uv add lexigram-multimedia-upscale
# Optional extras
uv add "lexigram-multimedia-upscale[real-esrgan-server]"  # Real-ESRGAN server deps
uv add "lexigram-multimedia-upscale[hat-server]"          # HAT server deps
```

## Quick Start

```python
from lexigram import Application
from lexigram.di.module import Module, module
from lexigram.multimedia.upscale import UpscaleModule
from lexigram.contracts.multimedia import UpscaleProvider, UpscaleRequest, MediaAsset


@module(imports=[UpscaleModule.configure()])
class AppModule(Module):
    pass


async def main() -> None:
    async with Application.boot(modules=[AppModule]) as app:
        upscale = await app.container.resolve(UpscaleProvider)
        asset = MediaAsset(mime_type="image/png", provider="local", bytes_data=b"<png>")
        result = await upscale.upscale(UpscaleRequest(asset=asset, scale_factor=4))
        if result.is_ok():
            upscaled = result.unwrap()  # MediaAsset — upscaled image bytes or URI


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())
```

## Configuration

> **Zero-config usage:** Call `UpscaleModule.configure()` with no arguments to use the `real-esrgan` backend at `http://localhost:5400`.

### Option 1 — YAML file

```yaml
# application.yaml
multimedia:
  upscale:
    backend: "hat"
    default_scale_factor: 2
```

### Option 2 — Profiles + Environment Variables

```bash
export LEX_PROFILE=production
export LEX_MULTIMEDIA__UPSCALE__BACKEND=real-esrgan
export LEX_MULTIMEDIA__UPSCALE__DEFAULT_SCALE_FACTOR=4
```

### Option 3 — Python

```python
from lexigram.multimedia.upscale import UpscaleModule
from lexigram.multimedia.upscale.config import UpscaleConfig

UpscaleModule.configure(
    config=UpscaleConfig(backend="hat", default_scale_factor=2)
)
```

### Config reference

| Field | Default | Env var | Description |
|-------|---------|---------|-------------|
| `backend` | `"real-esrgan"` | `LEX_MULTIMEDIA__UPSCALE__BACKEND` | `real-esrgan`, `hat` |
| `real_esrgan_base_url` | `"http://localhost:5400"` | `LEX_MULTIMEDIA__UPSCALE__REAL_ESRGAN_BASE_URL` | Real-ESRGAN server URL |
| `hat_base_url` | `"http://localhost:5401"` | `LEX_MULTIMEDIA__UPSCALE__HAT_BASE_URL` | HAT server URL |
| `default_scale_factor` | `4` | `LEX_MULTIMEDIA__UPSCALE__DEFAULT_SCALE_FACTOR` | Default upscale factor (2 or 4) |
| `timeout` | `30.0` | `LEX_MULTIMEDIA__UPSCALE__TIMEOUT` | Request timeout in seconds |

## Module Factory Methods

| Method | Description |
|--------|-------------|
| `UpscaleModule.configure(config)` | Configure with explicit upscale config |
| `UpscaleModule.stub()` | No-op module for unit testing |

## Key Features

- **Two backends** — `real-esrgan`, `hat` reference servers
- **Video upscaling** — `VideoUpscaleService` for frame-level video super-resolution (when `VideoProcessor` is available)
- **Reference servers** — `lexigram-upscale-real-esrgan-serve` and `lexigram-upscale-hat-serve` console scripts run each local model server
- **Result-based** — `upscale() -> Result[MediaAsset, MultimediaError]`; errors are domain values, not exceptions

## Testing

```python
from lexigram import Application
from lexigram.multimedia.upscale import UpscaleModule

async def test_boot():
    async with Application.boot(modules=[UpscaleModule.stub()]) as app:
        assert app.container is not None
```

## Key Source Files

| File | What it contains |
|------|-----------------|
| `src/lexigram/multimedia/upscale/module.py` | `UpscaleModule.configure()` and `.stub()` |
| `src/lexigram/multimedia/upscale/config.py` | `UpscaleConfig` |
| `src/lexigram/multimedia/upscale/di/provider.py` | `UpscaleGenerationProvider` — registers `UpscaleProvider`, wires task handlers |
| `src/lexigram/multimedia/upscale/providers/` | Backend implementations (`real_esrgan`, `hat`) |
| `src/lexigram/multimedia/upscale/servers/` | Reference-server entry points (`lexigram-upscale-*-serve`) |
| `src/lexigram/multimedia/upscale/video_upscale_service.py` | `VideoUpscaleService` — frame-level video upscaling |
| `src/lexigram/multimedia/upscale/tasks.py` | Background upscale task handlers |
| `src/lexigram/multimedia/upscale/exceptions.py` | `UpscaleError` hierarchy |
