README.md

metadata

title: NEXUS Visual Weaver
emoji: 🧵
colorFrom: red
colorTo: gray
sdk: gradio
sdk_version: 6.12.0
app_file: app.py
pinned: false
license: apache-2.0
short_description: Governed gothic couture visual creation command center
models:
  - black-forest-labs/FLUX.2-klein-9B
  - black-forest-labs/FLUX.2-klein-4B
  - Brunobkr/OFFELLIA_Q4_0_gemma-4-12B-it.gguf
  - nvidia/LocateAnything-3B
  - openbmb/MiniCPM-V-4.6
  - nvidia/NVIDIA-Nemotron-Parse-v1.2
  - openbmb/MiniCPM5-1B
  - onnx-community/functiongemma-270m-it-ONNX
  - hexgrad/Kokoro-82M
  - netflix/void-model
tags:
  - gradio
  - mcp-server
  - build-small
  - visual-creation
  - hackathon
  - off-brand
  - best-agent
  - best-demo
  - openbmb
  - nvidia
  - modal
  - codex

NEXUS Visual Weaver

Dark creative-operations command center for the Hugging Face Build Small Hackathon.

NEXUS Visual Weaver is a Gradio Space prototype for governed image and video creation. It combines a couture-oriented workflow dashboard, outfit and lore planning, model-lane governance, and an always-on defensive export gate.

The current Space path is intentionally direct for judges: enter a creative brief, run the active weave, inspect the generated FLUX.2 artifact, review ST3GG evidence, approve the human checkpoint, and prepare a governed export packet.

Direction

The interface is built around a command-center surface:

• workflow graph for Seed Prompt -> Refine -> Judge -> Locate -> Generate -> Video Path -> Human Checkpoint
• contextual inspector with taste rings, material checks, model stack, relay status, and ST3GG evidence
• wardrobe drawer for garments, materials, footwear, accessories, locks, and reference-region intent
• lore-to-video timeline for compact cinematic beats
• provider handoff cards for dry-run visibility before any paid, gated, or quota-limited call

Model Governance

Pinned lanes do not rotate:

• image_generation: Raven Quality Stack with black-forest-labs/FLUX.2-klein-9B as the flagship image/edit lane
• grounding: NVIDIA LocateAnything-3B grounding anchor
• security: ST3GG defensive scanner/export gate

Sponsor/evidence lanes are optional but first-class when secrets are configured:

• Brunobkr/OFFELLIA_Q4_0_gemma-4-12B-it.gguf (11.91B): quality/taste/lore critique lane for private or configured judge use.
• openbmb/MiniCPM-V-4.6 (1.30B): visual judge for wardrobe, footwear, material drift, lore continuity, and export notes.
• nvidia/NVIDIA-Nemotron-Parse-v1.2 (0.94B): structured evidence/parser lane for NVIDIA/Nemotron claim support.
• hexgrad/Kokoro-82M (0.082B): optional lore narration lane.
• netflix/void-model (5B CogVideoX-based): Modal/offline video repair sample lane, not a blocking Space runtime default.

Helper lanes may rotate with quota, license, health, and parameter-budget checks:

• prompt routing
• taste judging
• audio lore TTS
• video repair
• HF catalog research
• Modal job runner

The default preset is Raven Quality Stack. black-forest-labs/FLUX.2-klein-4B remains available only as a Tiny Titan/public-safe sidecar and fallback if the gated 9B lane is unavailable. OFFELLIA heretic/obliterated-style variants stay private research only and never disable consent, provenance, ST3GG, export, or dataset-partition gates.

Current Features

• Gradio Blocks dashboard with split update regions.
• Real FLUX.2 Klein 9B-first image generation on Hugging Face ZeroGPU when runtime access is configured, with an honest 4B sidecar fallback.
• Above-fold ST3GG trust strip with safe-vs-blocked fixture evidence.
• Generated artifact ST3GG scan and checkpoint/export state.
• Optional MiniCPM-V and Nemotron provider evidence lanes with explicit configured/missing-secret status.
• Active workflow graph and checkpointed run record.
• Taste profile scoring from assets/taste_profile.json.
• Wardrobe slot planning for couture, gothic, fantasy, footwear, accessories, and material control.
• HF model and LoRA catalog with Adult Mode hidden by default.
• GMR/ModelRelay-inspired helper model selection.
• ST3GG-inspired scan adapter with magic detection, mismatch review, purification actions, and export-gate state.
• Focused regression tests for catalog scope, workflow planning, ModelRelay behavior, and scanner evidence.

Build Small Prize Mapping

Target	Evidence status
Gradio Space	App runs as a public Hugging Face Gradio Space with mcp_server=True.
<=32B models	Raven Quality Stack is 28.50B: FLUX.2 Klein 9B + OFFELLIA Q4 Gemma 12B + LocateAnything 3.83B + MiniCPM-V 1.30B + Nemotron Parse 0.94B + MiniCPM5 1.08B + FunctionGemma 0.27B + Kokoro 0.082B.
Off Brand	Custom command-center UI, dense inspector, workflow graph, wardrobe/lore drawer, and provider cards.
Best Agent	Multi-step prompt, generation, scan, judge, checkpoint, export workflow.
OpenBMB	Claimed only when MiniCPM-V returns success status in an export packet.
NVIDIA	Claimed only when Nemotron returns success status in an export packet. LocateAnything remains visible but is not the Nemotron claim by itself.
Modal	Sidecar-only until a real Modal job is documented; target lane is netflix/void-model video repair.
OpenAI Codex	Development branch and PR include Codex-authored implementation commits.
Demo / social	Add final links here before submission: DEMO_VIDEO_URL and SOCIAL_POST_URL.

Tiny Titan is not the flagship story. It can be claimed only from a successful sidecar export packet where every active sidecar model is <=4B.

Local Setup

python -m pip install -r requirements.txt
$env:NEXUS_DISABLE_REAL_HF='1'
python app.py

The app reads NEXUS_PORT or PORT when present, otherwise it launches on 7860.

Verification

python -m compileall app.py src tests
$env:NEXUS_DISABLE_REAL_HF='1'
$env:PYTEST_DISABLE_PLUGIN_AUTOLOAD='1'
python -m pytest -q tests -p no:cacheprovider --basetemp=C:\tmp\pytest-nvw-full

Secret Policy

Do not commit provider credentials. Use Hugging Face Space secrets or local .env files for:

• HF_TOKEN
• MINICPM_BASE_URL
• MINICPM_API_KEY
• MINICPM_MODEL
• NEMOTRON_BASE_URL
• NEMOTRON_API_KEY or NVIDIA_API_KEY
• NEMOTRON_MODEL
• MODAL_TOKEN_ID
• MODAL_TOKEN_SECRET
• OPENAI_API_KEY
• provider-specific API keys or bearer tokens

Generated outputs, local moodboards, logs, caches, auth folders, and preview artifacts are intentionally ignored.

Review Workflow

• Bootstrap commit establishes the public GitHub repository baseline.
• Future substantial changes should use codex/specimba/<scope> branches and draft pull requests.
• GitHub Actions runs compile and pytest.
• CodeRabbit is configured to focus review on Gradio runtime correctness, model governance, security gates, Adult Mode behavior, and regression coverage.

See docs/RELEASE_WORKFLOW.md for the push and review gate.

License

Apache-2.0. See LICENSE.