AGENTS.md

# AGENTS.md

> **ВАЖНО — язык общения:** Всегда отвечай пользователю **только на русском языке**,
> независимо от языка кода или комментариев в репозитории. Пользователь слабо
> понимает английский.

Project instructions for AI coding agents working on Whyx-PROmpTea (Whyx-PROptimizer).

## Overview
Gradio web app that rewrites, expands, and generates variations of Stable Diffusion
prompts. Core logic lives in `src/`, UI in `app.py`, visual theme in `theme/whyx_theme.py`,
data/tag pools in `data/`.

## Environment
- Python 3.13 (a `.venv/` virtualenv is present in the project root for local dev).
- Gradio 5.x / 6.x (do NOT pin gradio in requirements.txt — HF Spaces pins its own).
  `app.py` auto-detects via `_GRADIO_MAJOR`:
  - Gradio 5: `theme`, `css`, `head` go in `gr.Blocks()`
  - Gradio 6: `theme`, `css`, `head` go in `demo.launch()`

## Conventions
- Keep source modules under `src/`; import as `from src import ...`.
- Tag pools are JSON files under `data/tag_pools/`; do not commit generated runtime files
  like `data/session_history.json` if they become corrupt — reset to `[]`.
- Ratings map centrally through `src.safety_filter`: UI ratings (`pg`, `pg13`, `pg16`, `r`, `r+`)
  must never be hard-coded to tag-pool ratings elsewhere.
- `data/negative_templates.json` is the single source of truth for negative-prompt strings.
- The artist pool (`data/tag_pools/artist.json`) can be refreshed with `scripts/fetch_top_artists.py`
  and post-enriched with `scripts/enrich_artist_signatures.py`.

## Verification
- Import check: `.venv\Scripts\python.exe -c "import app"` should succeed with no errors.
- Functional check: parse/rewrite/generate via `src.prompt_parser`, `src.prompt_rewriter`,
  `src.variation_engine`.
- Tests: run `.venv\Scripts\python.exe -m pytest tests/ -q` (21+ expected passes).
- Run the app: `.venv\Scripts\python.exe app.py` and confirm it serves HTTP 200 on the configured port.