Metadata-Version: 2.4
Name: z-vision-generator
Version: 0.6.3
Summary: Z-Vision Generator — cross-platform AI image and video generator
Project-URL: Homepage, https://github.com/knuthelge/ZVisionGenerator
Project-URL: Repository, https://github.com/knuthelge/ZVisionGenerator
Project-URL: Documentation, https://knuthelge.github.io/ZVisionGenerator/
Project-URL: Changelog, https://github.com/knuthelge/ZVisionGenerator/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/knuthelge/ZVisionGenerator/issues
Author: Knut Risheim
License-Expression: AGPL-3.0-or-later
License-File: LICENSE
Keywords: ai,diffusers,flux,image-generation,mlx,stable-diffusion,video-generation,z-image
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.14
Requires-Dist: accelerate>=1.13.0
Requires-Dist: bitsandbytes>=0.49.0; sys_platform != 'darwin'
Requires-Dist: diffusers>=0.37.1
Requires-Dist: hf-transfer>=0.1.9
Requires-Dist: huggingface-hub>=0.30.0
Requires-Dist: mflux>=0.17.4; sys_platform == 'darwin'
Requires-Dist: mlx-lm>=0.31.0; sys_platform == 'darwin'
Requires-Dist: mlx>=0.31.0; sys_platform == 'darwin'
Requires-Dist: numpy>=2.0.0
Requires-Dist: pillow>=12.0.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: safetensors>=0.4.0
Requires-Dist: scipy>=1.17.0
Requires-Dist: torch>=2.11.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: transformers>=5.0.0
Description-Content-Type: text/markdown

# Z-Vision Generator

[![CI](https://github.com/knuthelge/ZVisionGenerator/actions/workflows/ci.yml/badge.svg)](https://github.com/knuthelge/ZVisionGenerator/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/z-vision-generator)](https://pypi.org/project/z-vision-generator/)
[![Python 3.14+](https://img.shields.io/badge/python-3.14%2B-blue)](https://www.python.org/downloads/)
[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue)](LICENSE)

<p align="center">
    <img src="https://raw.githubusercontent.com/knuthelge/ZVisionGenerator/main/zvision.png" alt="Z-Vision Generator Logo" width="500"/>
</p>

Local AI image and video generation — hassle-free and fun. No tangled node graphs, no cloud dependencies, just prompts and results. Runs on macOS (Apple Silicon / MLX) and Windows (NVIDIA / CUDA), tuned for an M-series Mac with 32 GB unified memory and an NVIDIA RTX 3080.

## Features

- **Image generation** — text-to-image with Z-Image and FLUX.2 Klein (4B/9B) model families
- **Video generation** — text-to-video and image-to-video with LTX-2.3 (macOS)
- **Cross-platform** — automatic backend selection: MLX on macOS, CUDA on Windows
- **Prompt system** — YAML prompt files with variables, structured prompts, snippets, and batch runs
- **Model store** — central `~/.ziv/` directory with bare-name resolution and HuggingFace fallback
- **LoRA support** — single or stacked, configurable weights, bare-name resolution
- **Image upscale** — generate small → Lanczos → img2img refine → CAS sharpen
- **Video upscale** — distilled-only two-stage 2× spatial upscaling
- **Reference images** — img2img steering from any starting image
- **Quantization** — 4-bit and 8-bit on both platforms
- **Post-processing** — contrast, saturation, and CAS sharpening (image only)
- **Interactive controls** — skip, quit, pause, and repeat during batch runs (image only)

## Platform Support

| Platform | Image Generation | Video Generation |
|----------|------------------|------------------|
| macOS (Apple Silicon) | ✅ Z-Image / FLUX via mflux/MLX | ✅ LTX-2.3 via MLX |
| Windows (NVIDIA GPU) | ✅ Z-Image / FLUX via diffusers/CUDA | ❌ Not supported |

## Installation

Requires Python 3.14+ and [uv](https://docs.astral.sh/uv/).

> **uv is required.** This package cannot be installed with pip — some dependencies require uv-specific resolution that pip does not support. All commands below use uv.

```bash
# Install globally from PyPI
uv tool install z-vision-generator

# Install globally from repository
uv tool install -e git+https://github.com/knuthelge/ZVisionGenerator.git

# Development setup
git clone https://github.com/knuthelge/ZVisionGenerator && cd ZVisionGenerator
uv sync
```

> Video generation requires [ffmpeg](https://ffmpeg.org/). On macOS, `ziv-video` offers to install it via Homebrew on first run.

## Quick Start

```bash
# Generate an image (bare name from ~/.ziv/models/)
ziv -m my-model --prompt "a beautiful sunset"

# Generate from a HuggingFace model
ziv -m Tongyi-MAI/Z-Image-Turbo --prompt "a cat in a garden"

# Batch run from a prompts file
ziv -m my-model -p prompts.yaml -r 3

# Generate a video
ziv-video -m dgrauet/ltx-2.3-mlx-q4 --prompt "A cat walking through a garden"

# Image-to-video
ziv-video -m dgrauet/ltx-2.3-mlx-q4 --image photo.jpg --prompt "Camera zooms in slowly"
```

## Documentation

Full documentation is available at **[knuthelge.github.io/ZVisionGenerator](https://knuthelge.github.io/ZVisionGenerator/)**.

- [Getting Started](https://knuthelge.github.io/ZVisionGenerator/getting-started/) — installation, model store, quick start
- [Image Guide](https://knuthelge.github.io/ZVisionGenerator/guides/image/) — aliases, sizes, reference images, LoRA, upscaling, quantization
- [Video Guide](https://knuthelge.github.io/ZVisionGenerator/guides/video/) — T2V, I2V, upscale, audio, LoRA, constraints
- [Prompts Guide](https://knuthelge.github.io/ZVisionGenerator/guides/prompts/) — prompt files, variables, structured prompts, snippets
- [Converter Guide](https://knuthelge.github.io/ZVisionGenerator/guides/converter/) — checkpoint conversion, LoRA import, asset listing
- [CLI Reference](https://knuthelge.github.io/ZVisionGenerator/reference/cli/) — full argument tables for all commands
- [Development](https://knuthelge.github.io/ZVisionGenerator/development/) — setup, testing, architecture

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

This project is licensed under the [GNU Affero General Public License v3.0 or later](LICENSE).
