<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 (12GB+ VRAM recommended)
- **[uv](https://docs.astral.sh/uv/)** — fast Python package manager

### One-Command Install

WebUI (recommended)

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

CLI Mode (advanced - use Kitty or similar terminal with graphics support)

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

That's it! This downloads Z-Explorer from PyPI and launches the setup wizard.

### First-Time Setup

On first launch, Z-Explorer guides you through setup:

**Step 1: Dependencies**

Z-Explorer uses bleeding-edge versions of some libraries that aren't on PyPI yet. The wizard checks and installs them automatically:

```
📦 Checking dependencies...
  ⚠ sdnq not installed
  ⚠ diffusers needs update (missing ZImagePipeline)

? Install required dependencies now? (Y/n)
```

**Step 2: Model Configuration**

```
? Choose a setup option:
> Quick Start (Recommended for beginners)
  Custom Setup
  Full Quality
```

**Pick "Quick Start"** — it downloads optimized models that work great on 12GB GPUs:
- Image model: ~6GB download, ~12GB VRAM
- LLM: ~4GB download, fast inference

The wizard downloads everything automatically. Grab a coffee ☕

### Other Options

- **Custom Setup** — Mix and match model sources (local files, HuggingFace, quantized)
- **Full Quality** — Maximum quality for 24GB+ GPUs (~15GB download)

For advanced configuration, see [docs/CONFIGURATION.md](docs/CONFIGURATION.md).

### Reconfigure Anytime

```bash
z-explorer --setup        # Re-run setup wizard
z-explorer --show-config  # Check current configuration
```

### From Source (Development)

```bash
git clone https://github.com/pyros-projects/z-Explorer.git
cd z-Explorer
uv sync
uv run z-explorer
```

---

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

