Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.
Python ai-filmmakingai-videoai-video-generatorapple-siliconhailuoimage-to-videolip-synclocal-ailora-trainingltx-2ltx-2-5ltx-videomacosminimax-h3mlxmusic-generationoffline-aipinokiotext-to-videovideo-generation
feat(agent): Phase 0 quick wins + roadmap + image-gen research
mrbizarrobc102b14e39f
diff --git a/agent/project.py b/agent/project.pyindex e03ca04..7fbc8d2 100644--- a/agent/project.py+++ b/agent/project.py@@ -80,6 +80,96 @@ def read_notes_excerpt(state_dir: Path,return tail[cut + 1:].decode("utf-8", errors="replace")+_RING_SLOTS = 7 # 7-version history → ~1 day on a chatty session+++def _rotate_ring(p: Path) -> None:+ """Rotate one slot in the .bak ring buffer before write.++ Slot N becomes N+1 (oldest, slot 6, drops). Then current file copies+ to slot 0. Lets the user (or the agent's `restore_project_notes`+ affordance) undo a runaway append. Phase 0 #0.12 from the roadmap —+ project memory survives across sessions but a misclick or runaway+ agent can corrupt context. Cheap insurance.+ """+ try:+ if not p.is_file():+ return+ # Move existing slots up: 5 → 6, 4 → 5, …, 0 → 1.+ for i in range(_RING_SLOTS - 1, 0, -1):+ src = p.with_suffix(p.suffix + f".{i - 1}.bak")+ dst = p.with_suffix(p.suffix + f".{i}.bak")+ if src.exists():+ try:+ os.replace(str(src), str(dst))+ except OSError:+ pass+ # Copy current file to slot 0.+ slot0 = p.with_suffix(p.suffix + ".0.bak")+ try:+ data = p.read_bytes()+ slot0.write_bytes(data)+ try:+ os.chmod(slot0, 0o600)+ except OSError:+ pass+ except OSError:+ pass+ except Exception: # noqa: BLE001 — never block the append+ pass+++def list_note_versions(state_dir: Path) -> list[dict]:+ """Return metadata for the available .bak slots — newest first."""+ p = notes_path(state_dir)+ out: list[dict] = []+ for i in range(_RING_SLOTS):+ slot = p.with_suffix(p.suffix + f".{i}.bak")+ if slot.is_file():+ try:+ stat = slot.stat()+ out.append({+ "slot": i,+ "path": str(slot),+ "bytes": stat.st_size,+ "mtime": stat.st_mtime,+ })+ except OSError:+ pass+ return out+++def restore_note_version(state_dir: Path, slot: int) -> bool:+ """Replace the live notes file with the contents of `slot`.++ The restore is itself undoable on the next append — append_note+ rotates the current (post-restore) file into slot 0 then.++ Important: read the source bytes BEFORE we rotate, otherwise the+ rotation overwrites the requested slot with the current file's+ bytes and we'd "restore" the same thing we were trying to undo.+ """+ if slot < 0 or slot >= _RING_SLOTS:+ return False+ p = notes_path(state_dir)+ src = p.with_suffix(p.suffix + f".{slot}.bak")+ if not src.is_file():+ return False+ try:+ # Snapshot source contents first.+ data = src.read_bytes()+ tmp = p.with_suffix(p.suffix + ".restoretmp")+ tmp.write_bytes(data)+ os.replace(str(tmp), str(p))+ try:+ os.chmod(p, 0o600)+ except OSError:+ pass+ return True+ except OSError:+ return False++def append_note(state_dir: Path, text: str, *,kind: str = "note", author: str = "agent") -> dict:"""Append a timestamped entry to the notes file.@@ -92,7 +182,9 @@ def append_note(state_dir: Path, text: str, *,the agreed master style is "documentary, kodak portra 400, …"The header on a fresh file describes what the file is for — written- once on first append.+ once on first append. Before each append the previous state is+ rotated into a 7-slot ring buffer (`.0.bak` … `.6.bak`) so a runaway+ agent or misclick can be undone."""p = notes_path(state_dir)state_dir.mkdir(parents=True, exist_ok=True)@@ -100,6 +192,8 @@ def append_note(state_dir: Path, text: str, *,text = (text or "").strip()if not text:raise ValueError("note text is empty")+ if not fresh:+ _rotate_ring(p) # snapshot before mutatingts = datetime.fromtimestamp(time.time()).strftime("%Y-%m-%d %H:%M")block = f"\n## {ts} [{kind} · {author}]\n{text}\n"if fresh:diff --git a/agent/runtime.py b/agent/runtime.pyindex a126e16..5bd30f0 100644--- a/agent/runtime.py+++ b/agent/runtime.py@@ -374,6 +374,47 @@ def _escape(s: str) -> str:# ---- Tools doc renderer ----------------------------------------------------+def list_tool_catalog() -> list[dict]:+ """Structured catalog of every registered tool — for the UI's+ capabilities sheet (Phase 0 #0.5 from the roadmap). One row per+ tool with `name`, `summary` (first non-empty line of the docstring),+ and `body` (rest, trimmed). Stable order matches `render_tools_doc`.+ """+ order = [+ "estimate_shot", "submit_shot", "get_queue_status",+ "wait_for_shot", "extract_frame", "inspect_clip",+ "generate_shot_images", "get_selected_anchors", "upload_image",+ "read_document", "list_loras", "get_master_style",+ "read_project_notes", "append_project_notes",+ "write_session_manifest", "finish",+ ]+ seen = set()+ out: list[dict] = []+ def _row(name: str) -> dict | None:+ fn = tools.TOOL_HANDLERS.get(name)+ if fn is None:+ return None+ doc = (fn.__doc__ or "").strip()+ if not doc:+ return {"name": name, "summary": "", "body": ""}+ lines = doc.split("\n")+ summary = lines[0].strip()+ body = "\n".join(lines[1:]).strip()+ return {"name": name, "summary": summary, "body": body}+ for name in order:+ row = _row(name)+ if row is not None:+ out.append(row)+ seen.add(name)+ for name in sorted(tools.TOOL_HANDLERS.keys()):+ if name in seen:+ continue+ row = _row(name)+ if row is not None:+ out.append(row)+ return out++def render_tools_doc() -> str:"""Format the registered tools' docstrings for the system prompt.diff --git a/docs/AGENTIC_FLOWS_ROADMAP.md b/docs/AGENTIC_FLOWS_ROADMAP.mdnew file mode 100644index 0000000..37c4f36--- /dev/null+++ b/docs/AGENTIC_FLOWS_ROADMAP.md@@ -0,0 +1,109 @@+# Phosphene Agentic Flows — Roadmap to Pro-App Caliber++_Generated 2026-05-07 by deep UX audit. 50+ items across 4 phases._++## Executive summary++The Agentic Flows tab today is **technically dense and functionally rich** — a careful operator manual, four engine kinds, a memory-pressure guard, a Stage pane that shows live render progress, anchor-pick collaboration, project memory, multi-take support, reasoning surfacing. The single biggest gap is **legibility of capability**: a first-time user opens the tab, sees three vague conversation starters and an engine pill, and has no idea that the agent can read a PDF script, generate Flux anchors, write a manifest, lock a master style across sessions, or refine an existing clip. Sixteen tools, five engines, three image backends, two operating modes, four quality tiers, four shot modes — none of it is discoverable. The product reads as a chat box, not as a director's workstation.++The single biggest opportunity is to **convert hidden depth into a structured workspace**. Replace the pure-chat metaphor with a three-panel surface where chat is the conversation channel, but the project's *state* — script, characters, master style, shot list, picks, renders, manifest — lives in dedicated, navigable, editable structures around it. Sessions become projects. Every artifact the agent produces is first-class and editable by the user. The agent stops being a chatbot that emits files and becomes a director's seat-of-control. This is the move from "Claude can render videos" to "Phosphene's directing agent."++The recommended order of operations: **Phase 0** lands table-stakes professionalism (real first-message streaming, recovery from common error modes, in-app docs, accessibility floor). **Phase 1** rebuilds discoverability and information architecture (capabilities palette, command palette, structured project memory, smart defaults). **Phase 2** adds the wow features that turn casual users into evangelists (project templates, voice memos, comparison view, auto-recovery, NLE export, smart routing). **Phase 3** is the long tail — collaboration, scheduled queues, macros. Phase 0 is roughly 2 weeks of work; Phase 1 is 4–6 weeks; Phase 2 is 4–6 weeks; Phase 3 ships opportunistically.++## Phase 0 — table stakes (~2 weeks)++| # | Item | Effort | Why |+|---|---|---|---|+| 0.1 | SSE chat streaming | L | Demo-killer wait; content visible while it generates is the largest perceived-quality lift |+| 0.2 | Stop button that actually stops (server-side cancel) | M | Today's × only aborts the client; server keeps spending tokens |+| 0.3 | Recoverable error cards with one-click remediations | M | Errors as paths forward (Retry / Switch model / Stop engine) |+| 0.4 | In-app capability tour on first run | M | Three-phase loop, anchor-pick UX, overnight-batch model |+| 0.5 | `/help` slash command + capabilities sheet | S | Surfaces every tool's docstring as a structured catalog |+| 0.6 | Keyboard accessibility floor (focus-visible, aria-live, reduced-motion) | M | WCAG AA fail today |+| 0.7 | Session restore on panel restart | M | Half-rendered batches feel orphaned; resume / discard banner |+| 0.8 | Default-engine recommendation banner | S | New users run bundled Gemma forever; surface Qwen / Anthropic when appropriate |+| 0.9 | "What just happened?" turn summary | S | 30-card-deep turns lose context; one-line summary at the bottom |+| 0.10 | Cost / wall-time predictor before submit | S | Total wall + $ before saying "Confirm batch" |+| 0.11 | Engine readiness check at session start | S | Surface 401 / unreachable BEFORE user uploads attachments |+| 0.12 | Atomic project-notes history + undo | S | 7-version ring buffer; restore previous version |++## Phase 1 — high-impact polish (4–6 weeks)++| # | Item | Effort |+|---|---|---|+| 1.1 | Command palette (Cmd+P) — sessions / shots / tools / settings | M |+| 1.2 | Capabilities panel + tool catalog | M |+| 1.3 | Structured project memory (replace single markdown file) | L |+| 1.4 | Live anchor preview + thumbnail-while-rendering | M |+| 1.5 | Smart defaults from history | M |+| 1.6 | Information architecture — collapse the agent header | S |+| 1.7 | Inline error cards on tool failures | S |+| 1.8 | Comparison view — two takes side by side | M |+| 1.9 | Adaptive engine routing (small for tools, big for prose) | L |+| 1.10 | Voice input → script paste (Whisper) | M |+| 1.11 | Project templates (documentary / music video / talking head…) | M |+| 1.12 | Slash commands in composer (`/queue` `/style` `/picks` `/cost` `/finish`) | S |+| 1.13 | Sketch mode / dry-run on submit_shot | S |+| 1.14 | Refine UX — show context inline, not just a chip | S |+| 1.15 | RAM chip → live system pulse with breakdown popover | S |+| 1.16 | Discoverability for engine kinds (radio cards w/ pricing) | S |+| 1.17 | Session export to markdown | S |+| 1.18 | Project export bundle (zip with manifest + mp4s + picks + transcript) | M |+| 1.19 | Reasoning indicator with throughput | S |+| 1.20 | Modal focus traps + escape keys | S |+| 1.21 | Empty states everywhere have actions | S |++## Phase 2 — delight (4–6 weeks)++| # | Item | Effort |+|---|---|---|+| 2.1 | Live thumbnail preview during LTX render | L |+| 2.2 | Shot timeline view (drag to reorder) | L |+| 2.3 | NLE export — Final Cut XML / Premiere XML | M |+| 2.4 | Auto-recovery from engine errors mid-batch | M |+| 2.5 | Smart-route to Anthropic on Qwen reasoning loop detection | M |+| 2.6 | Inline annotation on a clip | L |+| 2.7 | Pre-defined macros (saved prompt sequences) | M |+| 2.8 | Background mode + scheduled queues | M |+| 2.9 | LoRA picker the agent can recommend from | S |+| 2.10 | Acid-test "this prompt won't work" guardrail w/ Director's note | M |+| 2.11 | Cross-session search | M |+| 2.12 | Showcase / public gallery (static HTML) | L |+| 2.13 | Director's chair keyboard shortcuts (J/K/L/P/R) | S |+| 2.14 | Anchor prompt expansion ("more like this but darker") | S |+| 2.15 | Dry-run cost estimate per-shot | S |++## Phase 3 — long tail (opportunistic)++| # | Item |+|---|---|+| 3.1 | Multi-machine collaboration (iCloud-synced sessions) |+| 3.2 | Session fork ("try a different direction") |+| 3.3 | Live URL share for trusted machines |+| 3.4 | Image-engine: DiffusionKit / CoreML on ANE |+| 3.5 | Sketched anchor input (canvas painter → ControlNet Flux) |+| 3.6 | Multi-agent — director + cinematographer split |+| 3.7 | Real-time render preview in chat |+| 3.8 | Auto-stitch optional draft cut |+| 3.9 | Engine A/B comparison mode |+| 3.10 | Semantic diff between takes |+| 3.11 | Whisper inline as speech-to-shot (silence-segmented chunking) |+| 3.12 | OBS / streaming integration |+| 3.13 | Pull-request-style review of the agent's plan |++## Critical implementation seams++Every roadmap item names a specific file + function or HTML element. Most land in:++- `mlx_ltx_panel.py` (~16,900 lines) — single file with HTTP server + inlined HTML/CSS/JS. Key seams: `#agentChat`, `agentSend()`, `renderEmpty()`, `renderToolResultCard()`, `renderAnchorGrid()`, agent header, Stage pane (`agentStageRender()`), settings drawer, sessions sidebar (`aspInit()`), composer.+- `agent/runtime.py` — `Session` + `run_turn`. SSE streaming, cancel support, auto-recovery, multi-engine routing.+- `agent/tools.py` — every tool with docstrings consumed by the system prompt. New tools, `dry_run` flag, `prompt_diff` arg.+- `agent/prompts.py` — system prompt builder. Project templates inject addenda; structured project memory replaces `{project_notes_block}`.+- `agent/engine.py` — OpenAI/Anthropic client. SSE deltas, cancel-via-connection-close, reasoning-loop detection emits structured `recommend_engine` error.+- `agent/project.py` — markdown notes. Add `read_structured()` parsing `[<kind> · ...]` sections; add ring buffer for undo.+- `agent/image_engine.py` — backends. Refactor to a generator so candidates stream as they finish.+- `docs/AGENTIC_FLOWS.md` + `docs/STATE.md` — source of truth. Every shipped item gets a row.++## The agent-tool connection rule (from `docs/AGENTIC_FLOWS.md`)++Every new manual UI feature must also be exposed to the agent as a tool. New roadmap features that introduce manual surfaces (timeline view, comparison view, macros, scheduled queues) need matching agent tools.diff --git a/docs/IMAGE_GEN_RESEARCH_2026-05.md b/docs/IMAGE_GEN_RESEARCH_2026-05.mdnew file mode 100644index 0000000..dd287fa--- /dev/null+++ b/docs/IMAGE_GEN_RESEARCH_2026-05.md@@ -0,0 +1,118 @@+# Phosphene Image-Gen Research — Apple Silicon, May 2026++_Tier-aware research for the agent's anchor-still pipeline (i2v inputs).+LTX 2.3's t2v is weak; image-gen quality is the dominant lever for video output._++## TL;DR++- **"Flux Klein"** = **FLUX.2 [klein] 4B** by Black Forest Labs (Jan 2026). Apache 2.0, mflux-compatible at 4-bit (~4.3 GB), 4-step inference, ~12-18 s/image on Comfortable Mac. **Ship as default.**+- **mflux 0.17.x is now multi-family.** Legacy `mflux-generate` is FLUX.1-only. New CLIs: `mflux-generate-flux2`, `mflux-generate-z-image-turbo`, `mflux-generate-fibo`, `mflux-generate-qwen`, `mflux-generate-kontext`. Panel currently calls legacy → silently misses every new family.+- **Z-Image-Turbo (Tongyi/Alibaba, Nov 2025)** is the Compact-tier default — 6B model, ~5.9 GB at 4-bit, 8-9 steps, fits 16 GB.++## The single default to ship++**FLUX.2 [klein] 4B at 4-bit, 4 steps** via:++```+mflux-generate-flux2 \+ --model Runpod/FLUX.2-klein-4B-mflux-4bit \+ --base-model flux2-klein-4b \+ --steps 4 \+ --quantize 4 \+ --guidance 1.0+```++Apache 2.0 → no gating, commercial OK. ~4.3 GB on disk, fits Compact tier with LTX dormant. 4 candidates per shot in 50-75 s on Comfortable. Multi-reference editing built-in.++## Tier-aware defaults++| Tier | RAM | Default model | Quant | Steps | Wall time |+|---|---|---|---|---|---|+| Compact | 16-32 GB | `Tongyi-MAI/Z-Image-Turbo` (mflux-4bit) | 4 | 9 | ~15-25 s |+| Comfortable | 32-79 GB | `Runpod/FLUX.2-klein-4B-mflux-4bit` | 4 | 4 | ~12-18 s |+| Roomy | 80-119 GB | klein-4B 8-bit OR Krea-dev 8-bit | 4-8 | 4-25 | ~18-80 s |+| Studio | 120 GB+ | klein-4B 4-bit OR FLUX.2-dev 4-bit | 4 | 4 | ~12 s |++Auto-detect snippet:+```python+def _default_image_engine_for_tier(tier: str) -> dict:+ if tier == "base": # Compact+ return {"kind": "mflux", "family": "z_image_turbo",+ "model_path": "filipstrand/Z-Image-Turbo-mflux-4bit",+ "steps": 9, "quantize": 4, "guidance": 0.0}+ if tier in ("standard", "high", "pro"):+ return {"kind": "mflux", "family": "flux2",+ "model_path": "Runpod/FLUX.2-klein-4B-mflux-4bit",+ "steps": 4, "quantize": 4, "guidance": 1.0}+ return {"kind": "mock"}+```++## Model landscape (mflux-friendly repos)++| Model | Repo | Params | 4-bit GB | License | Steps |+|---|---|---|---|---|---|+| **FLUX.2-klein-4B** | `Runpod/FLUX.2-klein-4B-mflux-4bit` | 4B | **4.3** | **Apache 2.0** | **4** |+| FLUX.2-klein-9B | community ports forming | 9B | ~9-11 | Non-commercial | 4-8 |+| FLUX.2-dev | `black-forest-labs/FLUX.2-dev` | 32B | ~16-18 | Non-commercial | 25-50 |+| **Z-Image-Turbo** | **`filipstrand/Z-Image-Turbo-mflux-4bit`** | 6B | **5.9** | **Apache 2.0** | **8-9** |+| Z-Image (base) | `Tongyi-MAI/Z-Image` | 6B | ~6.5 | Apache 2.0 | 25 |+| FLUX.1-Krea-dev | `filipstrand/FLUX.1-Krea-dev-mflux-4bit` | 12B | 9.61 | Non-commercial (gated) | 25 |+| FLUX.1-dev | `madroid/flux.1-dev-mflux-4bit` | 12B | ~9.5 | Non-commercial (gated) | 25-50 |+| FLUX.1-schnell | `dhairyashil/FLUX.1-schnell-mflux-4bit` | 12B | ~9 | Apache 2.0 | 2-4 |+| FIBO | `briaai/FIBO` | 8B | ~10-12 | Open-RAIL-ish | 30 |+| Qwen-Image | `filipstrand/Qwen-Image-mflux-6bit` | 20B | ~16 (6-bit) | Apache 2.0 | 25-50 |+| Flex.1-alpha | `ostris/Flex.1-alpha` | 8B | ~9-10 | Apache 2.0 | 25 |++## mflux 0.17.x per-family CLIs++| Command | Family |+|---|---|+| `mflux-generate` (legacy) | flux1 |+| `mflux-generate-flux2` | flux2 (klein-4B, klein-9B, dev) |+| `mflux-generate-flux2-edit` | flux2 image-edit |+| `mflux-generate-z-image` | z_image base |+| `mflux-generate-z-image-turbo` | z_image_turbo |+| `mflux-generate-fibo` | fibo |+| `mflux-generate-fibo-edit` | fibo edit (incl. remove-bg) |+| `mflux-generate-qwen` | qwen |+| `mflux-generate-kontext` | flux1-kontext |+| `mflux-generate-fill` | flux1 inpaint |+| `mflux-generate-controlnet` | flux1 controlnet |+| `mflux-upscale-seedvr2` | seedvr2 upscaler (could replace pipersr!) |++All share the same argparse mixins — `--prompt`, `--negative-prompt`, `--width`, `--height`, `--steps`, `--guidance`, `--seed`, `--quantize`, `--model`, `--base-model`, `--output`, `--metadata`, `--lora-paths`, `--lora-scales`, `--image-path`, `--image-strength`.++## Implementation plan (20 ranked items)++1. **(M)** Family-aware `_resolve_mflux_bin` in `agent/image_engine.py:131` + new `MFLUX_FAMILY_BIN` lookup table. Without this, none of the 0.17 families are reachable.+2. **(M)** Per-family default-flag table in `_generate_mflux`. klein-4B uses 4 steps + guidance 1; Z-Image-Turbo uses 9 steps + guidance 0; Krea-dev keeps 25 + guidance 4.5.+3. **(L)** Tier auto-detect via `_default_image_engine_for_tier` in `mlx_ltx_panel.py:~2042`. Apply at first boot when `agent_image_config.json` doesn't exist.+4. **(M)** Add FLUX.2-klein-4B to the model dropdown — `mlx_ltx_panel.py:10881`. Add `<optgroup>` per family.+5. **(M)** Add Z-Image-Turbo to the model dropdown.+6. **(M)** "Quality dial" pill group above the model dropdown — Fast (Z-Image-Turbo) / Balanced (klein-4B 4-bit) / Max (Krea-dev 8-bit on Roomy+, klein-4B 4-bit elsewhere).+7. **(M)** Reuse `_hf_model_install_async` for image weights — "Download" button in image drawer. Pre-flight via `_hf_size_estimate`.+8. **(S)** `health_check` extension reporting `weights_downloaded: bool` per family. Surface in Settings drawer pill.+9. **(M)** "Test current pipeline" button — runs portrait prompt at n=1, shows wall-time inline.+10. **(M)** OOM pre-flight: `if (model_gb + LTX_peak_gb > tier_ram): refuse + suggest 4-bit`.+11. **(M)** Tier-aware subprocess timeout — 240s for klein-4B/Z-Image, 600s for Krea-dev/dev.+12. **(L)** `mflux_warm_helper.py` — long-lived subprocess that loads the model once and accepts prompts via stdin. Mirror `mlx_warm_helper.py`. Saves 25-50s cold-load per shot batch.+13. **(M)** Sibling venv `image-gen/env/` so mflux deps don't conflict with LTX's transformers/mlx pins. `_resolve_mflux_bin` checks there first.+14. **(S)** HF gating UX — when `_hf_size_estimate` returns `gated: true`, surface "Open HF model card → accept terms → paste HF_TOKEN" inline.+15. **(S)** Update `docs/AGENTIC_FLOWS.md § Image generation backends` — document family dispatch, tier defaults, deprecate legacy `mflux-generate`-only path.+16. **(S)** Update `agent/image_engine.py:1-28` module docstring — current still says "Two backends ship in v1: mock, bfl" with mflux as "future".+17. **(M)** Tier-aware default for `ImageEngineConfig.mflux_model` (was `"krea-dev"` — wrong for 16 GB Macs).+18. **(L)** "Compare models" Settings page — runs test prompt across 3 picks side-by-side, click to set as default.+19. **(L)** Add `mflux-upscale-seedvr2` as post-render option for image candidates.+20. **(S)** Surface `--metadata` flag (writes JSON sidecar with prompt+seed+steps+model). Save next to candidate PNG.++## Sources++- [filipstrand/mflux on GitHub](https://github.com/filipstrand/mflux)+- [mflux releases page](https://github.com/filipstrand/mflux/releases)+- [black-forest-labs/FLUX.2-klein-4B on HF](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B)+- [Runpod/FLUX.2-klein-4B-mflux-4bit on HF (~4.3 GB)](https://huggingface.co/Runpod/FLUX.2-klein-4B-mflux-4bit)+- [BFL FLUX.2 [klein] launch blog](https://bfl.ai/blog/flux2-klein-towards-interactive-visual-intelligence)+- [Tongyi-MAI/Z-Image-Turbo on HF](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo)+- [filipstrand/Z-Image-Turbo-mflux-4bit on HF (~5.9 GB)](https://huggingface.co/filipstrand/Z-Image-Turbo-mflux-4bit)+- [filipstrand/FLUX.1-Krea-dev-mflux-4bit on HF (9.61 GB)](https://huggingface.co/filipstrand/FLUX.1-Krea-dev-mflux-4bit)+- [Apatero — Flux on Apple Silicon performance guide](https://www.apatero.com/blog/flux-apple-silicon-m1-m2-m3-m4-complete-performance-guide-2025)diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex 73a7b1b..d45db0a 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -4598,6 +4598,35 @@ class Handler(BaseHTTPRequestHandler):})return+ if parsed.path == "/agent/capabilities":+ # Structured tool catalog — drives the in-app /help sheet so+ # users discover what the agent can actually do (Phase 0 #0.5).+ try:+ catalog = agent_runtime.list_tool_catalog()+ except Exception as e: # noqa: BLE001+ self._json({"error": str(e)}, 500); return+ self._json({+ "tools": catalog,+ "engine_kinds": [+ {"id": "phosphene_local", "label": "Phosphene Local", "cost": "free · on-device"},+ {"id": "anthropic", "label": "Claude (Anthropic)", "cost": "paid · per token"},+ {"id": "ollama", "label": "Ollama bridge", "cost": "free · on-device"},+ {"id": "custom", "label": "Custom (OpenAI-compat)", "cost": "depends"},+ ],+ "image_kinds": [+ {"id": "mock", "label": "Mock", "cost": "free · placeholders"},+ {"id": "mflux", "label": "Local Flux (mflux)", "cost": "free · uses RAM + disk"},+ {"id": "bfl", "label": "Black Forest Labs API", "cost": "paid · per image"},+ ],+ "modes": [+ {"id": "plan_sleep", "label": "Plan & sleep", "desc": "Auto-stop engine on finish; frees RAM for renders"},+ {"id": "interactive", "label": "Interactive", "desc": "Engine stays resident across finishes"},+ ],+ "shot_modes": ["t2v", "i2v", "keyframe", "extend"],+ "quality_tiers": ["quick", "balanced", "standard", "high"],+ })+ return+if parsed.path == "/agent/sessions":self._json({"sessions": agent_runtime.list_sessions(STATE_DIR)})return@@ -5815,6 +5844,27 @@ HTML = r"""<!doctype html>}* { box-sizing: border-box; }html, body { margin: 0; height: 100%; }++ /* Phase 0 a11y floor —+ (a) Visible focus ring on every interactive element when reached+ via keyboard (mouse-click clears via :focus-visible). Today's+ inputs had ad-hoc focus styling but buttons/links had none.+ (b) Honor reduced-motion. Animations / transitions across the app+ use ms-scale durations; this collapses them to ~zero so motion-+ sensitive users don't get pulse / slide / fade. */+ :focus-visible {+ outline: 2px solid var(--accent-bright);+ outline-offset: 2px;+ border-radius: var(--r-xs);+ }+ @media (prefers-reduced-motion: reduce) {+ *, *::before, *::after {+ animation-duration: 0.01ms !important;+ animation-iteration-count: 1 !important;+ transition-duration: 0.01ms !important;+ scroll-behavior: auto !important;+ }+ }body {background: var(--bg); color: var(--text);font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;@@ -8050,6 +8100,99 @@ HTML = r"""<!doctype html>margin: 14px 0;}+ /* ---- Capabilities sheet (Phase 0 #0.5) ----+ Drives the /help slash-command output. Each tool is one row:+ monospaced name + first-line summary; click to expand the full+ docstring. Quiet typography — this is reference material. */+ .caps-section {+ margin: 14px 0;+ }+ .caps-section h3 {+ margin: 0 0 8px 0;+ font-size: 11px;+ letter-spacing: 0.5px;+ text-transform: uppercase;+ color: var(--muted);+ font-weight: 600;+ }+ .caps-row {+ display: flex;+ gap: 12px;+ padding: 10px 12px;+ border: 1px solid var(--border);+ border-radius: var(--r-sm);+ margin-bottom: 6px;+ background: rgba(255,255,255,0.025);+ }+ .caps-row .caps-name {+ font-family: ui-monospace, SFMono-Regular, Menlo, monospace;+ font-size: 11.5px;+ color: var(--accent-bright);+ white-space: nowrap;+ flex-shrink: 0;+ align-self: flex-start;+ padding-top: 1px;+ }+ .caps-row .caps-text {+ flex: 1; min-width: 0;+ font-size: 12px;+ color: var(--text);+ line-height: 1.5;+ }+ .caps-row .caps-text .summary {+ color: var(--muted);+ font-size: 11.5px;+ }+ .caps-row details {+ margin-top: 4px;+ }+ .caps-row details summary {+ cursor: pointer;+ font-size: 11px;+ color: var(--accent-bright);+ list-style: none;+ user-select: none;+ }+ .caps-row details summary::-webkit-details-marker { display: none; }+ .caps-row details[open] summary { color: var(--muted); }+ .caps-row pre {+ margin: 6px 0 0 0;+ padding: 10px 12px;+ background: var(--bg);+ border: 1px solid var(--border);+ border-radius: var(--r-xs);+ font-size: 11px;+ line-height: 1.55;+ max-height: 280px;+ overflow: auto;+ white-space: pre-wrap;+ word-break: break-word;+ color: rgba(255,255,255,0.8);+ }+ .caps-grid {+ display: grid;+ grid-template-columns: repeat(auto-fill, minmax(220px, 1fr));+ gap: 8px;+ }+ .caps-grid .caps-cell {+ padding: 9px 12px;+ border: 1px solid var(--border);+ border-radius: var(--r-sm);+ background: rgba(255,255,255,0.025);+ }+ .caps-grid .caps-cell .label {+ font-weight: 600; font-size: 12px; color: var(--text);+ }+ .caps-grid .caps-cell .meta {+ color: var(--muted); font-size: 11px;+ font-family: ui-monospace, SFMono-Regular, Menlo, monospace;+ letter-spacing: 0.2px;+ }+ .caps-grid .caps-cell .desc {+ color: var(--muted); font-size: 11.5px;+ margin-top: 2px;+ }+/* ---- Reasoning disclosure (chain-of-thought) ----Shown above the assistant content as a collapsed details block.Quiet by default so the answer stays the focus; expanding reveals@@ -9798,6 +9941,13 @@ HTML = r"""<!doctype html><line x1="3" y1="21" x2="10" y2="14"/></svg></button>+ <button type="button" class="icon-btn" onclick="openAgentCaps()" title="What can the agent do? · type /help in chat" aria-label="Show agent capabilities">+ <svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">+ <circle cx="12" cy="12" r="10"></circle>+ <path d="M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3"></path>+ <line x1="12" y1="17" x2="12.01" y2="17"></line>+ </svg>+ </button><button type="button" class="icon-btn" onclick="openProjectNotes()" title="Project notes — persistent memory across sessions"><svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 2H6a2 2 0 00-2 2v16a2 2 0 002 2h12a2 2 0 002-2V8z"/>@@ -9815,7 +9965,7 @@ HTML = r"""<!doctype html></header><div class="agent-chat-wrap">- <div class="agent-chat" id="agentChat"></div>+ <div class="agent-chat" id="agentChat" role="log" aria-live="polite" aria-relevant="additions" aria-label="Agent chat thread"></div><!-- "↓ new messages" pill — appears when content lands while theuser has scrolled up to read something. Clicking jumps tobottom and re-arms auto-scroll. -->@@ -9886,7 +10036,7 @@ HTML = r"""<!doctype html><polyline points="5 12 12 5 19 12"/></svg></button>- <span class="hint">Cmd/Ctrl + Enter to send · ⌘V to paste · drag files to attach</span>+ <span class="hint">⌘ Enter to send · ⌘V to paste · drag files to attach · type /help to see what the agent can do</span></div><!-- Drag-drop overlay shown only while a drag is over the chat surface. --><div class="agent-drop-overlay" id="agentDropOverlay">@@ -10723,6 +10873,28 @@ HTML = r"""<!doctype html></div></div>+<!-- ============== CAPABILITIES SHEET ==============+ Triggered by typing /help in the composer or clicking the ? button.+ Driven by /agent/capabilities (server-side enumeration of all+ registered tools + engine kinds + image kinds + modes). Lets users+ discover what the agent can do without grepping the system prompt. -->+<div class="agent-settings-modal" id="agentCapsModal"+ role="dialog" aria-modal="true" aria-labelledby="agentCapsTitle"+ onclick="if(event.target===this)closeAgentCaps()">+ <div class="agent-settings-card" style="max-width:780px">+ <h2 id="agentCapsTitle">What the agent can do+ <button type="button" onclick="closeAgentCaps()">Close</button>+ </h2>+ <div class="hint">+ Phosphene's agent is a director's assistant. It plans shots,+ generates anchor stills, queues LTX renders, writes a manifest.+ Below: every tool it has, plus the engine and image-backend+ options. Use this as a reference; you don't need to memorize it.+ </div>+ <div id="agentCapsBody" style="padding-top:8px"></div>+ </div>+</div>+<!-- ============== PROJECT NOTES MODAL ============== --><!-- Persistent memory across sessions — the agent reads the tail ofthis file every turn. Editable here too. -->@@ -15300,6 +15472,18 @@ async function agentSend() {const btn = document.getElementById('agentSendBtn');const text = (input.value || '').trim();+ // Slash commands handled client-side BEFORE engaging the engine.+ // /help opens the capabilities sheet; /notes opens project notes;+ // /queue triggers the batch; /clear starts a new session; etc.+ if (text && text.startsWith('/') &&+ typeof agentMaybeHandleSlashCommand === 'function' &&+ agentMaybeHandleSlashCommand(text)) {+ input.value = '';+ if (typeof agentAutoResize === 'function') agentAutoResize(input);+ if (typeof agentUpdateSendState === 'function') agentUpdateSendState();+ return;+ }+// Wait for any in-flight uploads so the message arrives WITH its// attachments. UX: don't block the user — if uploads error we surface// them in the chip row and the user can remove/retry.@@ -15827,6 +16011,134 @@ function closeAgentSettings() {}// ---- Project notes modal --------------------------------------------------+// Capabilities sheet — driven by /agent/capabilities. Surfaces every+// tool the agent has, plus engine/image/mode options, so users+// discover what they can ask for. (Phase 0 #0.5)+async function openAgentCaps() {+ const modal = document.getElementById('agentCapsModal');+ const body = document.getElementById('agentCapsBody');+ if (!modal || !body) return;+ body.innerHTML = '<div style="padding:24px; color:var(--muted); text-align:center">Loading…</div>';+ modal.classList.add('open');+ try {+ const r = await fetch('/agent/capabilities');+ const j = await r.json();+ body.innerHTML = '';+ // Tools+ if (Array.isArray(j.tools) && j.tools.length) {+ const sec = document.createElement('div');+ sec.className = 'caps-section';+ const h = document.createElement('h3');+ h.textContent = `Tools the agent can call · ${j.tools.length}`;+ sec.appendChild(h);+ for (const t of j.tools) {+ const row = document.createElement('div');+ row.className = 'caps-row';+ const name = document.createElement('div');+ name.className = 'caps-name';+ name.textContent = t.name;+ const txt = document.createElement('div');+ txt.className = 'caps-text';+ const sum = document.createElement('div');+ sum.className = 'summary';+ sum.textContent = t.summary || '(no summary)';+ txt.appendChild(sum);+ if (t.body) {+ const det = document.createElement('details');+ const dsum = document.createElement('summary');+ dsum.textContent = 'Show full doc';+ det.appendChild(dsum);+ const pre = document.createElement('pre');+ pre.textContent = t.body;+ det.appendChild(pre);+ txt.appendChild(det);+ }+ row.appendChild(name); row.appendChild(txt);+ sec.appendChild(row);+ }+ body.appendChild(sec);+ }+ // Engine kinds+ const _gridSection = (title, items, render) => {+ if (!Array.isArray(items) || !items.length) return;+ const sec = document.createElement('div');+ sec.className = 'caps-section';+ const h = document.createElement('h3'); h.textContent = title;+ sec.appendChild(h);+ const grid = document.createElement('div');+ grid.className = 'caps-grid';+ for (const it of items) grid.appendChild(render(it));+ sec.appendChild(grid);+ body.appendChild(sec);+ };+ _gridSection('Chat engine kinds', j.engine_kinds || [], (e) => {+ const c = document.createElement('div'); c.className = 'caps-cell';+ c.innerHTML = `<div class="label">${escapeHtml(e.label)}</div>` ++ `<div class="meta">${escapeHtml(e.id)}</div>` ++ `<div class="desc">${escapeHtml(e.cost)}</div>`;+ return c;+ });+ _gridSection('Image-engine backends', j.image_kinds || [], (e) => {+ const c = document.createElement('div'); c.className = 'caps-cell';+ c.innerHTML = `<div class="label">${escapeHtml(e.label)}</div>` ++ `<div class="meta">${escapeHtml(e.id)}</div>` ++ `<div class="desc">${escapeHtml(e.cost)}</div>`;+ return c;+ });+ _gridSection('Operating modes', j.modes || [], (e) => {+ const c = document.createElement('div'); c.className = 'caps-cell';+ c.innerHTML = `<div class="label">${escapeHtml(e.label)}</div>` ++ `<div class="meta">${escapeHtml(e.id)}</div>` ++ `<div class="desc">${escapeHtml(e.desc)}</div>`;+ return c;+ });+ } catch (e) {+ body.innerHTML = `<div style="padding:18px;color:#f49a9e">Couldn't load capabilities: ${escapeHtml(String(e))}</div>`;+ }+}++function closeAgentCaps() {+ const m = document.getElementById('agentCapsModal');+ if (m) m.classList.remove('open');+}++// Slash-command pre-handler. Called from agentSend BEFORE the send fires.+// Returns true if the slash command was handled (don't continue with+// the normal send), false otherwise.+function agentMaybeHandleSlashCommand(text) {+ const t = (text || '').trim();+ if (!t.startsWith('/')) return false;+ const cmd = t.split(/\s+/)[0].toLowerCase();+ switch (cmd) {+ case '/help':+ case '/?':+ openAgentCaps();+ return true;+ case '/notes':+ openProjectNotes();+ return true;+ case '/queue':+ case '/picks':+ // If anchor picks are pending, fire the existing batch flow.+ if (typeof agentBatchQueue === 'function') {+ agentBatchQueue();+ } else {+ alert('No anchors picked yet — generate some first.');+ }+ return true;+ case '/clear':+ case '/new':+ if (typeof agentNewSession === 'function') agentNewSession();+ return true;+ case '/settings':+ case '/engine':+ if (typeof openAgentSettings === 'function') openAgentSettings();+ return true;+ default:+ return false; // unknown slash — let it through+ }+}+async function openProjectNotes() {const modal = document.getElementById('agentNotesModal');const ta = document.getElementById('agentNotesTextarea');