AGENTS.md

# AGENTS.md — AI Creative Studio (abalanescu/flow)

**Mission:** Turn the HF PRO subscription into a working multi-modal showcase that
uses BOTH resources: ZeroGPU (40 min/day A100) + Inference API (~$2/month credit).

## The two HF resources (know the difference)

| Resource | What it runs | How it's billed | In this repo |
|---|---|---|---|
| **ZeroGPU** | Local GGUF models via `@spaces.GPU` | 40 min/day of A100, free | Gemma 4 26B Heretic (uncensored) chat |
| **Inference API** | Serverless hosted models | ~$2/month credit | FLUX.1 image gen + Whisper transcription |

**Rule:** ZeroGPU = local GGUF inference. Inference API = serverless FLUX/Whisper.
Never mix them up. Both are already wired in `app.py`.

## Environment

- `HF_TOKEN` is exported in the shell and valid for user `abalanescu`. Use it for
  all HuggingFace API calls. Do NOT hardcode it in files.
- GGUF models are mounted at `/data` on the `abalanescu/flow` Space.
- Default model: `gemma-4-26B-A4B-it-ultra-uncensored-heretic.i1-Q4_K_M.gguf`

## Memory (Memrize)

Project memory lives in `.memrize/memrize.db`. Track progress there:
```bash
~/projects/memrize/target/release/memrize remember <key> <value>
~/projects/memrize/target/release/memrize pin <rule>
~/projects/memrize/target/release/memrize stats
```

## App structure (`app.py`)

5 tabs, each labeled with which resource it uses:
1. **Gemma Chat** (ZeroGPU) — uncensored multi-turn chat
2. **FLUX Image Gen** (Inference API) — text-to-image
3. **Whisper Transcribe** (Inference API) — audio-to-text
4. **Voice to Art** (BOTH) — Whisper → Gemma → FLUX pipeline
5. **Prompt Enhancer** (BOTH) — Gemma enhances prompt → FLUX renders

## Workflow for agents

1. Read `GOAL.md` for current milestone.
2. Check `.memrize/memrize.db` for prior decisions/facts.
3. Make changes, verify with `python3 -m py_compile app.py`.
4. Record progress in memrize.
5. Commit as you go.

## Guardrails

- Never hardcode `HF_TOKEN` in source files.
- Never commit `.memrize/` secrets or the DB if it contains sensitive data.
- Keep the resource labels accurate in the UI so users track their budget.