Metadata-Version: 2.3
Name: z-explorer
Version: 0.4.4
Summary: AI Image Generation Without the UI Tax - Z-Image-Turbo + Qwen3-4B
Requires-Dist: aiohttp>=3.11.18
Requires-Dist: art>=6.5
Requires-Dist: bitsandbytes>=0.48.2
Requires-Dist: loguru>=0.7.3
Requires-Dist: pillow>=10.4.0
Requires-Dist: pydantic>=2.11.3
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: python-fasthtml>=0.12.14
Requires-Dist: questionary>=2.1.0
Requires-Dist: requests>=2.32.3
Requires-Dist: rich>=13.9.4
Requires-Dist: term-image>=0.7.2
Requires-Dist: websockets>=15.0.1
Requires-Dist: torch>=2.0.0
Requires-Dist: transformers>=4.40.0
Requires-Dist: accelerate>=0.30.0
Requires-Dist: huggingface-hub>=0.23.0
Requires-Dist: sentencepiece>=0.2.0
Requires-Dist: fastapi>=0.109.0
Requires-Dist: uvicorn>=0.27.0
Requires-Dist: sse-starlette>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: diffusers
Requires-Python: >=3.10, <3.13
Description-Content-Type: text/markdown

<p align="center">
  <img alt="Z-Explorer" src="docs/assets/banner.png" width="800">
</p>

<h1 align="center">🔥 Z-Explorer</h1>

<p align="center">
  <strong>AI Image Generation Without the UI Tax</strong><br>
  <em>Type a prompt. Get art. That's it.</em>
</p>

<p align="center">
  <a href="#the-problem">The Problem</a> •
  <a href="#the-solution">The Solution</a> •
  <a href="#prompt-magic">Prompt Magic</a> •
  <a href="#installation">Installation</a>
</p>

---

## The Problem

You wanted to make AI art. Instead you got:

- 47 browser tabs of documentation
- A node graph that looks like spaghetti had a baby with a circuit board
- "CUDA out of memory" every 5 minutes
- Settings panels with 200 sliders you don't understand
- That one workflow that worked yesterday but doesn't today

**You're spending more time fighting the tool than creating.**

We think that's insane.

---

## The Solution

Z-Explorer strips away everything between you and your art.

```
>>> a cute fox in a magical forest
```

That's it. No nodes. No tabs. No sliders. Just your idea, rendered.

**How it works:**

1. **Type a prompt** — natural language, just like talking to a person
2. **Hit enter** — generation starts instantly
3. **See your art** — displayed right there, no hunting through folders

Everything runs locally. No cloud. No API keys. No monthly fees. Your GPU, your art, your privacy.

---

## Prompt Magic

This is where Z-Explorer shines. We built features that make prompt crafting *fun*, not tedious.

### 🎲 Prompt Variables — Randomized Creativity

Tired of typing the same things? Use variables for instant variety:

```
>>> a __animal__ wearing a crown
```

Each generation picks a random animal. Run it 10 times, get 10 different creatures. 

Variables are just text files. Add your own:

```
# library/mood.md
ethereal
cyberpunk
cottagecore
dark fantasy
solarpunk
```

Now use `__mood__` anywhere. Your vocabulary, your variables.

### 🧠 Auto-Generated Variables

Here's where it gets magical. **Use a variable that doesn't exist:**

```
>>> a portrait of a __famous_inventor__
```

Z-Explorer's local LLM generates it on the fly:

```
✨ Generated __famous_inventor__ with 20 values
   → Nikola Tesla, Ada Lovelace, Leonardo da Vinci...
```

Saved to your library. Ready for next time.

No more googling "list of famous inventors". Just ask, and it appears.

### ✨ Prompt Enhancement — From Vague to Vivid

Your prompt: `a cat`

What the AI actually needs: `A majestic orange tabby cat with emerald eyes, sitting on a velvet cushion, soft golden hour lighting streaming through a Victorian window, hyperrealistic fur detail, shallow depth of field, cinematic composition`

The `>` operator bridges that gap:

```
>>> a cat > make it cozy and magical
```

The local LLM expands your idea into a rich, detailed prompt. Same intent, 10x better output.

Or use it standalone:

```
>>> /enhance a robot in a garden
```

See exactly what the AI will receive before committing.

### 🔄 Batch Generation — Explore Variations

Want 10 variations? Easy:

```
>>> a __animal__ in space : x10
```

Generates 10 images with different animals and seeds. Find the diamond in the rough.

Combine with size control:

```
>>> epic landscape : x5,w1920,h1080
```

5 widescreen landscapes. One command.

---

## Two Ways to Create

### 🌐 Web UI (Default)

Launch Z-Explorer and get a beautiful web-based UI:

- **Masonry gallery** of all your generations
- **Fake CLI** for that terminal aesthetic (with autocomplete!)
- **Live preview** — images appear the moment they're done
- **Prompt saved** with every image

```bash
z-explorer
```

### ⌨️ CLI Mode (For Purists)

Prefer a pure terminal experience?

```bash
z-explorer --cli
```

Same power, different vibe. Perfect for SSH sessions or terminal lovers.

---

## Installation

### Prerequisites

- **Python 3.10, 3.11, or 3.12** (3.13+ not yet supported)
- **NVIDIA GPU** with CUDA support (8GB+ VRAM recommended)
- **[uv](https://docs.astral.sh/uv/)** — fast Python package manager

### One-Command Install

```bash
uvx --python 3.12 z-explorer
```

That's it! This downloads Z-Explorer from PyPI and launches the web UI in your browser.

For CLI mode:
```bash
uvx --python 3.12 z-explorer --cli
```

### From Source (Development)

```bash
# Clone the repo
git clone https://github.com/pyros-projects/z-Explorer.git
cd z-Explorer

# Install dependencies
uv sync

# Launch!
uv run z-explorer
```

First launch downloads models (~8GB). After that, everything runs offline.

---

## Commands

| Command | Description |
|---------|-------------|
| `/help` | Show all commands |
| `/vars` | List available prompt variables |
| `/enhance <prompt>` | Preview enhanced prompt |
| `/seed <number>` | Set seed for reproducibility |
| `/size <WxH>` | Set output dimensions (e.g., 1920x1080) |
| `/gpu` | Check GPU memory status |
| `/unload` | Free GPU memory |
| `/quit` | Exit |

**Prompt Syntax:**

```
__variable__        Random value from variable
__variable:5__      Specific index (5th value)
prompt > instruction   Enhance prompt with instruction
prompt : x10,w1920    Batch with parameters
```

---

## What's Under the Hood

- **Z-Image-Turbo** — Lightning-fast image generation
- **Qwen3-4B** — Local LLM for enhancement and variable generation
- **FastAPI** — Backend API server
- **Svelte** — Beautiful web UI

Everything runs locally. No internet required after initial setup.

---

## Gallery

<table>
  <tr>
    <td><img src="docs/assets/gallery-1.png" width="250"></td>
    <td><img src="docs/assets/gallery-2.png" width="250"></td>
    <td><img src="docs/assets/gallery-3.png" width="250"></td>
  </tr>
</table>

---

<p align="center">
  <em>AI art tools are gatekept by complexity.</em><br>
  <strong>We're changing that.</strong>
</p>

---

## License

MIT — Go forth and create.

