If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Tongyi-MAI/Z-Image shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit 3mo ago
• 17 active contributors
• Distributed ownership (top contributor 47% of recent commits)
• Apache-2.0 licensed
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Tongyi-MAI/Z-Image repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Tongyi-MAI/Z-Image.

What it runs against: a local clone of Tongyi-MAI/Z-Image — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Tongyi-MAI/Z-Image | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 117 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Tongyi-MAI/Z-Image. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Tongyi-MAI/Z-Image.git
#   cd Z-Image
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Tongyi-MAI/Z-Image and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Tongyi-MAI/Z-Image(\\.git)?\\b" \\
  && ok "origin remote is Tongyi-MAI/Z-Image" \\
  || miss "origin remote is not Tongyi-MAI/Z-Image (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 117 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~87d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Tongyi-MAI/Z-Image"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Z-Image is a 6B-parameter diffusion transformer family for efficient image generation, with Z-Image-Turbo achieving sub-second latency on H800 GPUs using only 8 NFEs (Number of Function Evaluations) while fitting in 16GB consumer VRAM. It excels at photorealistic generation, bilingual text rendering (English/Chinese), and instruction adherence using a single-stream transformer architecture instead of traditional UNet-based diffusion. Modular architecture with src/zimage containing core components (autoencoder.py, transformer.py, scheduler.py, pipeline.py), src/config housing inference and model configs, src/utils providing helpers/loaders, and src/tools for utilities like manifest generation. Entry points are inference.py and batch_inference.py at root; manifests in src/config/manifests/ define model-specific configurations (e.g., z-image-turbo.txt).

ML researchers and engineers building production image generation systems who need fast inference without sacrificing quality; practitioners deploying on consumer hardware or enterprise GPUs; developers integrating image generation into applications requiring sub-second response times.

Actively developed and production-ready. The project has official checkpoints on Hugging Face and ModelScope, published research (arxiv 2511.22699), and multiple inference entry points (inference.py, batch_inference.py). However, repo maturity cannot be fully assessed from structure alone—check GitHub stars and recent commit timestamps, but the presence of distilled 'Turbo' variants and online demos suggests active maintenance.

Moderate risk: the codebase is 100% Python with heavy PyTorch dependencies not fully visible in the file list; no test directory is evident, suggesting limited test coverage for a production model. Single-maintainer risk under Tongyi-MAI organization. The model weights are external (Hugging Face/ModelScope), so availability depends on third-party hosting. Breaking changes between Z-Image and Z-Image-Turbo variants may affect compatibility.

The project is actively maintained with two model variants (base Z-Image and distilled Z-Image-Turbo). Development appears focused on inference optimization and deployment (batch_inference.py suggests recent scaling work). The presence of both single and batch inference scripts indicates ongoing refinement for different deployment scenarios.

Clone the repository: git clone https://github.com/Tongyi-MAI/Z-Image.git && cd Z-Image. Install dependencies using the pyproject.toml: pip install -e . (standard Python package install). Run inference: python inference.py (check the script for required arguments like prompt, model_id, and output_path).

Daily commands: Single image: python inference.py --prompt 'your prompt here' --model_id Tongyi-MAI/Z-Image-Turbo --output output.png. Batch processing: python batch_inference.py (check script for CSV/batch config format). Both scripts load configs from src/config/inference.py and model manifests from src/config/manifests/.

• src/zimage/pipeline.py: Core inference pipeline orchestrating transformer, scheduler, and autoencoder; main entry point for generating images
• src/zimage/transformer.py: Implements the single-stream diffusion transformer architecture that differentiates Z-Image from standard UNet diffusion models
• src/config/inference.py: Pydantic config schema for inference parameters; controls sampling steps, guidance, model selection, and device placement
• src/zimage/scheduler.py: Diffusion noise schedule and step management; critical for controlling inference speed vs. quality tradeoff (8 NFEs for Turbo)
• inference.py: User-facing CLI for single image generation; demonstrates how to instantiate pipeline and handle model loading
• src/config/manifests/z-image-turbo.txt: Model-specific configuration manifest defining Turbo variant parameters like step count, guidance scale, and checkpoint references
• src/utils/loader.py: Handles model checkpoint loading from Hugging Face/ModelScope and device management; critical for production deployment

For inference changes: modify src/config/inference.py (config schema) and src/zimage/pipeline.py (pipeline logic). For model architecture: src/zimage/transformer.py (core model) and src/zimage/autoencoder.py (VAE). For optimization: src/utils/attention.py. For new model variants: add manifest in src/config/manifests/ and update src/config/model.py. New utilities go in src/utils/.

1. Model checkpoints are remote (Hugging Face/ModelScope), not bundled—ensure internet access and HF token if private weights. 2) The 8 NFE Turbo variant requires specific scheduler config in src/config/manifests/z-image-turbo.txt; using wrong manifest will degrade speed. 3) Device placement in src/utils/loader.py may require CUDA/GPU for sub-second latency claims; CPU inference will be much slower. 4) Batch inference script (batch_inference.py) signature unknown—inspect actual file for expected input format (CSV, JSON, etc.). 5) src/utils/attention.py likely contains Flash Attention or similar optimization flags that must be enabled for benchmark numbers.

• Diffusion Transformers (DiT) — Z-Image replaces UNet with a single-stream transformer for diffusion, improving efficiency and enabling the sub-second Turbo variant; understanding this architecture is essential for modifying the core model
• Number of Function Evaluations (NFEs) — Z-Image-Turbo achieves quality parity with 8 NFEs vs. standard 20-50 steps; optimizing the scheduler and step count directly impacts this metric
• Noise Schedule / Variance Schedule — src/zimage/scheduler.py controls the diffusion noise schedule; tweaking this schedule is how Z-Image achieves both fast (Turbo) and high-quality generation variants
• Latent Diffusion — Z-Image generates in latent space using the autoencoder; understanding VAE compression/decompression is critical for quality and memory efficiency
• Classifier-Free Guidance — Core technique for instruction adherence and quality control in Z-Image; configured in inference.py as guidance_scale parameter
• Flash Attention / Attention Optimization — src/utils/attention.py likely implements memory-efficient attention kernels necessary to achieve sub-second latency on consumer GPUs with 6B parameters
• Model Manifests / Config as Specification — src/config/manifests/ defines variant-specific hyperparameters without code changes; mastering this pattern allows deploying new Z-Image variants without editing core code

• huggingface/diffusers — Standard diffusion inference framework; Z-Image's pipeline and scheduler are inspired by or compatible with this ecosystem
• openai/dall-e — Predecessor high-quality image generation model; Z-Image advances on efficiency and multi-language support
• Stability-AI/stable-diffusion — Foundational open-source diffusion model; Z-Image's single-stream transformer is a direct architectural evolution
• facebookresearch/DiT — Diffusion Transformers paper and reference; foundational to Z-Image's transformer-based diffusion approach
• Tongyi-MAI/Z-Image-Demo — Likely companion repo with Gradio/Streamlit UI wrappers around this inference codebase for online demos

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for src/utils modules

The utils directory (attention.py, helpers.py, import_utils.py, loader.py) has no corresponding test files. These are foundational utilities used by the pipeline, autoencoder, and transformer modules. Adding tests would improve reliability and make contributions safer.

• [ ] Create tests/test_attention.py with tests for attention mechanisms in src/utils/attention.py
• [ ] Create tests/test_loader.py with tests for model loading in src/utils/loader.py
• [ ] Create tests/test_import_utils.py with tests for dynamic imports in src/utils/import_utils.py
• [ ] Add pytest configuration to pyproject.toml
• [ ] Verify tests run with pytest tests/

Add GitHub Actions CI workflow for inference testing

The repo has inference.py and batch_inference.py entry points but no CI pipeline to verify they work correctly. A GitHub Actions workflow would catch regressions when dependencies or core modules (src/zimage/) change.

• [ ] Create .github/workflows/test-inference.yml
• [ ] Add steps to install dependencies from pyproject.toml
• [ ] Add a step to test inference.py with a minimal prompt and seed for deterministic output
• [ ] Add a step to test batch_inference.py with sample inputs
• [ ] Ensure workflow runs on push to main and pull requests

Add configuration validation and schema documentation

src/config/inference.py and src/config/model.py define configuration but have no validation layer or clear schema documentation. This causes user confusion when invalid configs are passed. Adding Pydantic models or dataclasses with docs would improve UX.

• [ ] Create src/config/schemas.py with Pydantic BaseModel definitions for InferenceConfig and ModelConfig
• [ ] Add field validators for critical parameters (e.g., steps > 0, valid scheduler types)
• [ ] Update src/config/inference.py and src/config/model.py to use the new schemas
• [ ] Add docstrings documenting each config field with valid values and defaults
• [ ] Update README.md with a configuration reference section pointing to src/config/schemas.py

• Add unit tests for src/zimage/scheduler.py covering different step counts (8 for Turbo, standard for base) to catch regressions in noise schedule changes
• Document the exact manifest format and config overrides in README with examples for both Z-Image and Z-Image-Turbo variants; src/config/manifests/README.md exists but is likely sparse
• Implement error handling and validation in src/utils/loader.py for missing/corrupted HuggingFace checkpoints with fallback guidance (currently silent failures likely crash inference.py)

The Z-Image codebase appears to be a machine learning project with a relatively clean structure. No critical vulnerabilities were immediately identified from the file structure alone. The main security concerns are: (1) inability to verify dependency security without seeing pyproject.toml content, (2) potential issues with model/file download validation, (3) missing input validation patterns, and (4) lack of visible security controls in logging. The project would benefit from explicit dependency pinning, input validation frameworks, secure download verification, and security-focused code review of inference and configuration handling modules.

• Medium · Missing Dependency Specification — pyproject.toml. The pyproject.toml file content is not provided, making it impossible to verify if all dependencies are pinned to specific versions and if any known vulnerable packages are being used. This could lead to supply chain attacks or use of outdated/vulnerable libraries. Fix: Ensure all dependencies are pinned to specific, reviewed versions. Regularly audit dependencies using tools like pip-audit or poetry audit. Consider using lock files (poetry.lock or requirements.lock) for reproducible builds.
• Low · Potential Model/Data Download Security — src/utils/loader.py, src/utils/import_utils.py, src/zimage/pipeline.py. The codebase references HuggingFace model downloads (Z-Image, Z-Image-Turbo). Without examining the loader.py and import_utils.py files, there's a risk that model downloads may not validate checksums or handle untrusted sources securely. Fix: Implement cryptographic checksum validation (SHA256) for all downloaded models. Use HTTPS for downloads and verify SSL certificates. Consider pinning to specific model revisions rather than using 'latest'.
• Low · Unrestricted File I/O Operations — batch_inference.py, inference.py, src/tools/generate_manifest.py. The presence of inference.py, batch_inference.py, and tools suggest file operations that may accept user input. Without reviewing the actual code, there's potential risk of path traversal vulnerabilities or arbitrary file access. Fix: Validate and sanitize all file paths. Use os.path.abspath() and verify paths are within expected directories. Implement allowlists for accessible directories. Use pathlib with strict validation.
• Low · Missing Input Validation Framework — src/config/inference.py, src/zimage/pipeline.py. No visible input validation or sanitization patterns in the file structure. The inference pipeline likely accepts user-supplied prompts and parameters that should be validated. Fix: Implement strict input validation for all user-supplied parameters. Validate prompt length, type, and content. Use schema validation libraries like pydantic or marshmallow.
• Low · No Visible Logging Security Controls — src/utils/helpers.py, src/zimage/pipeline.py. Without examining the actual code, it's unclear if sensitive information (model paths, prompts, system details) might be logged insecurely, potentially exposing information in logs. Fix: Implement secure logging practices. Avoid logging sensitive user inputs, model paths, or system configuration. Use log rotation and restrict log file permissions. Consider using structured logging with appropriate sanitization.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.