name: ai-model-reference-pack-framework description: Build or upgrade a JBNX Design model (jbnx.io/design/m/NNN) to the model 001 standard at the highest available quality — restored anchors, 4K references, scene frames, motion baselines, an audio-driven voice proof, QA and a published page. Use for a new model or when a model renders soft or blurry in video.
Portal: https://projects.jbnx.io/framework/ai-model-reference-pack-framework Markdown for agents: https://projects.jbnx.io/framework/ai-model-reference-pack-framework?format=md Source: AI_MODEL_REFERENCE_PACK_FRAMEWORK.md · job schema AI_MODEL_REFERENCE_PACK_JOB.schema.json · worked example AI_MODEL_REFERENCE_PACK_JOB.example.json · rates AI_MODEL_REFERENCE_PACK_RATES.json · tools scripts/model_reference_pack/ Updated: 2026-11-11 · version 1.4.0 Status: Tested end to end four times: model 003 Darren v0.3.0 (compressed sources, one outfit), model 002 Joey v0.3.0 (sharp but casual group photos, three variants; rejected by the subject), model 002 Joey v0.4.0 (re-anchored on photos the subject chose) and model 004 Bethany v0.1.0 (fictional, cheap 1K pilot before 4K finals). Every live asset matched its manifest hash each time. Rates are list quotes, not reconciled bills.
Produce a complete, versioned reference pack for one model so every later image or video starts from sharp, consistent, verified references. The pack is the baseline: anything soft here is soft in every video.
Completion requires the parity checklist, source and likeness QA, subject approval for real-person finals, and verification of the exact production release. Use the release gate in §9 to decide whether the pack is ready.
jbnx.io/design/m/.Do not use it to change who the person is. Real-person identity changes need the subject's approval and a major version.
| Authority | Reuse |
|---|---|
| hi.jbnx.io core (v93 at writing) | Claim scoped work, evidence, follow-up list, verify-then-release, record usage |
| AI Media Cost Framework v3 | Short pilots, two attempts per shot, reconcile before retry, cost per accepted deliverable, unknown cost stays unknown |
| AI Model Motion Transfer Framework | Identity locks and route selection when a reference performance is involved |
| Credentials policy | Keys only by name in runtime stores; never print values |
| Human Framework, Textbook Teacher | Page copy: one clear action, plain words |
| Model 001 page and files | The parity standard: sections, files and QA depth |
The model's own model.json and framework.md | Identity, consent and use rules; the originals win any conflict |
| Item | Files (vNNN = new version number) | Page section |
|---|---|---|
| Face anchor | <slug>-face-000-vNNN.jpg | Hero, Identity, Files |
| Body anchor | <slug>-body-000-vNNN.jpg | Hero, 360°, Files |
| 8-angle turn (000–315 every 45°) | <slug>-body-{000..315}-vNNN.jpg | 360° reference |
| 360° sheet | <slug>-360-vNNN.jpg | 360° reference, Files |
| Face turns (000, 045, 090, 270, 315) | <slug>-face-{yaw}-vNNN.jpg | Face & expression |
| Expressions (smile, eyes closed, speaking) | <slug>-expression-{e}-vNNN.jpg | Face & expression |
| Variant anchors (multi-variant models) | <slug>-anchor-{a,b,c}-vNNN.jpg, 16:9 | Variants viewport, Files |
| Scene first frames (floor, chair) | <slug>-motion-{floor,chair}-vNNN.jpg | Production → Scene first frames |
| Motion baselines (turn, walk, sit, talk) | <slug>-motion-{turn,walk,sit,talk}-vNNN.mp4 | Production → motion grid |
| Voice sample | existing approved sample | Production |
| Audio-driven voice proof | <slug>-voice-proof-vNNN.mp4 | Production → voice proof |
| Likeness report | Jev + face-ID table in model.json likeness and qa.json | Identity → Likeness scores |
| QA report | qa.json (hash recorded in model.json) | Production → QA link, Files |
| Manifest, config, ledger | model.json, production.json, production-ledger.json | Files, Budget ledger |
| Framework text and prompts | framework.md, prompts.txt | Files, Prompts |
| Rerunnable job file | reference-pack-job.json (validated against the schema) | Files |
| Planning helper | production-helper.py (offline) | Budget ledger, Files |
| Previous versions | earlier files kept, marked archived or preserved | Versions → previous references |
| Routing and tests | model_design.py allowlist, catalog card, tests/test_model_NNN.py | — |
Copy AI_MODEL_REFERENCE_PACK_JOB.example.json and fill it in. Validate it against the schema before spending.
Required: model ID, slug, character type, target version, source images, identity lock text, still jobs (at least 14), motion jobs (4), approved voice and line, spending cap, attempts per shot, broker name.
Real person: consent must be attested (who, when, scope) and the subject must review new references and any speaking clip before release. Only use lines the subject approved, in the voice the subject approved. A line the agent drafts may be rendered for review, labeled "awaiting approval", and never used downstream until approved.
Real person: confirm the target age or era and use the subject's selected source photos as the identity authority. If the owner specifies Google Photos or another collection, retrieve the actual photo files and use those files or documented subject-only crops. Record the source filename or private ID, source hash, crop coordinates and derivative hash. Keep private album URLs and unrelated people out of the public pack. A filename or upload timestamp alone does not establish capture date.
Use an approved real photo as the face authority when the owner asks to use their photos. An owner-approved source can advance intake without a separate choice among generated face candidates. Use another approved angle to resolve features when available. Mark body proportions or views reconstructed without corresponding source coverage as generated interpretations. Keep any candidate or derived restoration subordinate to the real source. Subject review still governs the generated finals and speaking clips.
Model 002 v0.3.0 drifted because it used album-scored photos with a misleading angle and outfit. Choose sources by subject approval and target-era evidence. Use metrics to check derived results.
Casual or group photos: prepare subject-only inputs with crop_sources.py (EXIF-upright crops; fill any other person who touches the subject). Only the subject may be identifiable in anything sent to a provider. Record each crop's box, masks and SHA-256 as an unpublished working input.
Budget: about $8–9 for a full pack at list rates (see the rates file). A missing cap leaves paid steps pending; prepare everything else.
Measure before changing anything (qa_tools.py sharpness):
Write the root cause into sources.diagnosis. In both runs the video model was not the problem; the inputs were. Sharp sources can still be the gap: model 002's 12 MP photos were sharp but casual (selfies, other people, caps), and no studio references existed.
Real person: never regenerate the face from scratch. Restore it.
fal-ai/topaz/upscale/image), face enhancement on, face creativity 0 (the schema enforces it).preserved_original. Restorations are derived assets (derived_from) and never override the originals."upload:<id>" and uploaded first.flip: true.Fictional model: generate the neutral full-body anchor first, approve it, then continue at step 3 with it as both inputs.
Cheap pilot first (fictional). Before any 4K work, make three 1K drafts on a low-cost edit model (face front, body front, body side; model 004 used Nano Banana 2.1 edit at about $0.044 each). Score them with Jev and face-ID, show the owner, and change only text and seeds until they approve. The approved face and body drafts, restored 2x, then become image 1 and image 2 for the 4K finals. Model 004's pilot cost about $0.21, and the full pack came in at $8.21. A body reference that shows another person is described in text only; never upload it.
Adult appearance. Every fictional model must clearly read as an adult in every image. Put the age direction in the identity lock, never younger than the approved face anchor, and review each still and clip for it.
fal-ai/nano-banana-pro/edit), resolution: "4K", PNG output, fixed seed. Chosen for closest same-person likeness (comparison published 2026-10-06).<job>-r2. Record the reject reason. For a seed-only re-roll, run_jobs.py stills <job> --seed-offset N (seed + 1000 x N) needs no redeploy; the receipt is <job>-sN.stills.extra_reference_count (0–4) appends more of the subject's real photos after images 1 and 2. A real profile photo anchors the 090/270 views.kling-3.0/video, mode: "pro", 5 s, sound: false, with one kling_elements entry named after the model (2–4 identity images: face 000, face 045, body 000) and @name in the prompt.verified: false before the host propagates; re-download and compare the hash.run_jobs.py voices lists voice names and IDs through the broker (key read by name). Model 002's manifest said "not enrolled", but the clone "Joey v4.0" was already in the account. run_jobs.py tts renders the job's fixed line in the job's fixed voice.fal-ai/sync-lipsync/v2, model: "lipsync-2-pro", sync_mode: "cut_off"). Only the mouth is edited, so identity cannot drift. Pick a line shorter than the clip.kling/ai-avatar-pro for this: it painted invented caption text into 3 of 3 attempts on model 003 and repeatedly in the FedM8 promo. If it is used anyway, scan every frame.scribe_v1) against the line, waveform correlation and offset against the source take (qa_tools.py voiceproof), and visual articulation review. Use calibrated SyncNet when available; otherwise say lip sync is visually reviewed, not machine-scored. A crude mouth-motion proxy is not evidence.| Check | Method | Fail → |
|---|---|---|
| Identity (face, glasses, beard, hairline, skin, build) | Contact sheet against the face anchor | Re-roll once, then stop and report |
| Direction / expression matches the label | Zoomed head crops; nose edge and visible ear | Re-roll with stricter wording |
| Sharpness | 4K stills (long edge ≥ 4608 for generated) | Regenerate at 4K |
| Framing | Whole subject and props inside frame | Re-roll framing |
| Invented text, captions, logos | 12–16-frame sheets plus qa_tools.py captions (first-frame ratio; clean ≤ 1.4, captioned 2.1–2.4). OCR misses stylized fake captions. | Reject the clip |
| Motion anatomy | First, middle, final frames: hands, feet, ground contact, final pose | Reject or re-roll once |
| Voice proof | ASR exact, waveform ≥ 0.99 at ~0 s, no captions | Reject; change route, not just seed |
Record every rejection in the ledger and qa.json with its reason. Two attempts per shot by default; a third needs a stated reason.
Likeness gate (real person). Before the full run, make a pilot of three stills (face 000, body 000, the primary variant anchor) and score them:
qa_tools.py faceid (ArcFace). Calibrate with the subject's own photos (model 002: 0.63–0.67, each real photo against his others) and a different person (about 0). Score held-out real photos that were not inputs, so the input photo cannot flatter the result.jev_likeness.py (TypeSafe System One): same-person probability, a 0–4 likeness score with confidence, and checks for face shape, fuller cheeks, under-eye bags and hair. Jev separates a different person well (model 002: 24% same person vs 86–88% for his real photos) but barely separates close likenesses, and its confidence stayed near 0.5 even on his real photos (0.51–0.53). Treat it as a hint.Caption scan floor: when the first-frame level sits at the 0.5 floor, ratios inflate (model 002 turn: 4.34 from a lapel pin, buttons and an ear highlight, 112 px). Open the flagged frame before rejecting.
archived with superseded_by; mark owner originals preserved_original.model.json: every asset with path, role, origin, size, dimensions, SHA-256, provider request or task ID, prompt hash, seed, inputs and QA status; updated authority, turnaround, faces, expressions, scene references, motion baselines, voice proof, production completion (with the qa.json hash) and a release-history entry.production.json: renderer (with selection basis and observed outputs), reference generation, caps, workflow, motion tests, voice proof (with ASR, waveform and attempt history), next validation step.production-ledger.json: helper-compatible entries (status, estimated_external_cost_usd_micros, cost_components with unknown amounts as null) and a summary from production-helper.py summarize plus rejected jobs, quoted total and observed credits.build_manifests_m003_v030.py), never by hand-typing hashes. Keep the repo's JSON format (2-space indent).Record the status of every parity row as pass, pending, or fail in qa.json. Each pass needs the asset or section, the verification result and the commit or artifact hash. A genuinely inapplicable item needs a documented reason and owner-approved scope. Empty sections, placeholders, unscored results, and promises to finish later are pending.
model_design.py: allowlist every new file; unknown files must still return 404.source and preview point to the full-body anchor (the card slot is full-body).lp-jbnx, [scope:repo]), commit, push to main (the site's release lane), wait for the live version, re-download every asset and compare hashes, release the claim.Quote before each paid step from the rates file and record it. Spend on 1K drafts until the owner approves the look; 4K only for finals. After each job, record the request or task ID, credits when the provider reports them, QA status and reason. Raising the cap needs the owner's word; write who and when into the ledger notes. Report cost per accepted deliverable as unknown until bills are reconciled.
make_broker.py from the job JSON. It holds a fixed job list; callers pass only job IDs and provider-hosted media URLs on an allowlist. A random token is the gate; only its SHA-256 is deployed.prompt_sha256 with make_broker.py --print-prompt-hashes to prove the deployed prompts are the job's.IDENTITY LOCK (append to every still)
Image 1 is the face authority: keep his/her exact face shape, eyes, brows, nose, mouth, {facial hair}, {hair and hairline} and {eyewear}.
Image 2 is the body authority: keep the exact build, shoulder width, chest and midsection volume, torso and leg length, and the outfit: {outfit}.
Same real person, photorealistic, natural skin texture, no beauty filter. Professional photograph in sharp focus with fine natural detail:
skin pores, individual hairs, fabric weave; no blur, no smoothing, no plastic skin. Do not change age, skin tone, face, {hair/eyewear} or body shape.
One person only, no text, no watermark.
DIRECTION (example, 045)
Front three-quarter view: whole body, head and nose turned 45 degrees toward IMAGE LEFT. The nose points toward the LEFT edge of the image;
the left ear shows on the image-right side of the head and the right ear is hidden. Must NOT face the camera straight on and must NOT face image right.
MOTION (Kling 3.0 with element @{name})
Animate the attached accepted scene first frame. Action: {action} Camera: locked, no camera movement. Duration: 5 seconds.
@{name} is this same person: keep the existing face, {hair/eyewear}, body proportions, outfit, lighting, scene and ground contact stable throughout.
Use natural movement and continuous anatomy. Do not add scene changes, new people, text, captions, logos or wardrobe changes. No dialogue.
Avoid flicker, face drift, warped frames, body drift, floating heels, extra fingers and sliding feet.A fictional adult AI actress built from the owner's own AI-generated face image. The pilot was three 1K drafts on Nano Banana 2.1 edit, about $0.21, scored with Jev; the owner approved it. The finals were 19 4K stills from the two approved drafts, then a 3-still gate, four Kling baselines and a voice proof in ElevenLabs Lily, all within the $10 cap ($8.21 quoted). One Kling job failed with a character upload error (0 credits) and passed on retry. Manifests come from build_manifests_m004_v010.py.
v0.3.0 was rejected by Joey as heavier than him, with the wrong anchors. v0.4.0 used only the four photos he sent: a balcony selfie (face anchor, his choice), a mirror photo (slim build and spiked hair, flipped) and cap selfies. Two scored likeness tests turned his feedback (face structure, cheeks, hair, under-eye bags) into the identity lock, and the cap went to $21 on his word. Face-ID caught an identity swap on the Variant C anchor (0.004); its re-roll scored 0.567. Manifests from build_manifests_m002_v040.py.
Root cause: 13 sharp owner photos, all casual (selfies, other people in 8, caps in 5), and no generated references. Four Joey-only crops (one other person masked), face restored with Topaz Recovery V2, 23 stills at 4K with two extra identity photos (2 re-rolled: body-045 head-only turn; scene-chair armchair, r2 accepted with a deviation), 4 Kling 3.0 pro baselines (turn mirrored, accepted), voice proof in the cloned voice Joey v4.0 (ASR exact, waveform 0.994). 33 jobs, 4 rejected, $9.35 quoted against a $12 cap, 360 kie credits. Job file: static/design/m/002/reference-pack-job.json; manifests from build_manifests_m002_v030.py.
Root cause: owner photos at 103 KB and 54 KB, references made at 1K. Result: 43 jobs (10 rejected: 2 restoration variants not chosen, 4 stills re-rolled for direction or framing, 3 Kling Avatar Pro voice proofs with invented captions, 1 from v0.2), $9.76 quoted against a $12 cap raised by the owner, 600 kie credits observed. Commit 72493fd; every live asset matched its manifest hash.
Every change to this framework: who, when, why. Source: agent_ops.catalog_changelog.
| When (UTC) | Who | Version | What | Why |
|---|---|---|---|---|
| 2026-11-11 18:24 | 1099:codex-young-joey | v5 | Require original-photo provenance and a complete independently verified model pack | Prevent partial model releases and source drift |