# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a Hugging Face Spaces application called Z-Image that provides a web interface for the Z-Image-Turbo model, an AI image generation model from Tongyi-MAI. The application uses Gradio to create an Apple-style UI for generating images from text prompts.

## Architecture

### Single-File Application
The entire application logic is contained in `app.py`. There are no separate modules or components - everything from model loading to UI definition is in this single file.

### Model Loading Strategy
- The ZImagePipeline model loads at application startup (lines 14-25 in app.py)
- Model is loaded globally and reused across all generation requests
- Uses bfloat16 precision for optimal performance
- Automatically detects and uses GPU if available, falls back to CPU
- Model source: `Tongyi-MAI/Z-Image-Turbo` from Hugging Face

### Image Generation Flow
1. User enters prompt in Gradio interface
2. `generate_image()` function (app.py:28-75) processes the request
3. Uses fixed parameters:
   - Image size: 1024x1024
   - Inference steps: 9 (turbo model optimized for speed)
   - Guidance scale: 0.0 (classifier-free guidance disabled)
   - Fixed random seed: 42 for reproducibility
4. Returns PIL Image object to Gradio for display

### UI Architecture
- Built with Gradio Blocks API for custom layout
- Custom Apple-style CSS embedded in the file (lines 78-258)
- Theme configured using Gradio's theme system with additional CSS overrides
- Responsive design with mobile breakpoints
- Dark mode support included in CSS

## Development Commands

### Running the Application
```bash
python app.py
```

### Installing Dependencies
```bash
pip install -r requirements.txt
```

Note: requirements.txt installs from git repos for `diffusers` and `transformers` to get latest versions.

### Testing on Hugging Face Spaces
This app is designed to run on Hugging Face Spaces with:
- SDK: gradio 6.0.1
- GPU support via `@spaces.GPU()` decorator on the generate_image function

## Key Implementation Details

### Spaces GPU Decorator
The `@spaces.GPU()` decorator (app.py:27) is specific to Hugging Face Spaces and enables automatic GPU allocation for the image generation function. This won't work in local development but is essential for the production deployment.

### Global Pipeline Pattern
The `pipe` variable is global and loaded once at startup. The `generate_image()` function checks if pipe is None and raises an error if model loading failed. This pattern ensures:
- Model is loaded only once (expensive operation)
- Memory is reused across requests
- Fast inference after initial startup

### Error Handling
- Validates prompt is non-empty before generation (app.py:46-47)
- Wraps generation in try/except to provide user-friendly error messages (app.py:58-75)
- Checks for model load failure at startup

### CSS Integration
The application uses dual styling approach:
1. Gradio theme configuration (app.py:331-358)
2. Custom CSS injected via `css` parameter (app.py:359)

Both are necessary because Gradio's theme system doesn't expose all styling properties needed for the Apple aesthetic.

## Modifying the Application

### Changing Generation Parameters
Edit the `pipe()` call in `generate_image()` (app.py:59-67):
- `height`/`width`: Image dimensions (must be multiples of 8)
- `num_inference_steps`: More steps = higher quality but slower
- `guidance_scale`: Controls prompt adherence (0.0 = no guidance)
- Remove or modify `generator` to change randomness behavior

### Updating the Model
Change the model ID in `ZImagePipeline.from_pretrained()` (app.py:14-18). Ensure the new model is compatible with ZImagePipeline API.

### Modifying UI Layout
The Gradio interface is defined in the `gr.Blocks()` context (app.py:261-325):
- Header: gr.HTML block (lines 267-275)
- Input section: gr.Column with textbox and button (lines 278-293)
- Output section: gr.Column with image display (lines 296-303)
- Footer: gr.HTML block (lines 306-310)

### Styling Changes
Modify `apple_css` string (app.py:78-258) for visual changes. Key selectors:
- `.main-title`, `.subtitle`: Header text
- `textarea`: Prompt input field
- `button.primary`: Generate button
- `.output-section img`: Generated image display