inline-core 1.2.69__tar.gz → 1.2.71__tar.gz

{inline_core-1.2.69 → inline_core-1.2.71}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: inline-core
-Version: 1.2.69
+Version: 1.2.71
 Summary: The generation engine behind Inline Studio.
 License-Expression: GPL-3.0-or-later
 Requires-Python: >=3.11

{inline_core-1.2.69 → inline_core-1.2.71}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 # PyPI name; the import package is `inline_core` (src/inline_core).
 name = "inline-core"
-version = "1.2.69"
+version = "1.2.71"
 description = "The generation engine behind Inline Studio."
 readme = "README.md"
 license = "GPL-3.0-or-later"

inline_core-1.2.71/src/inline_core/characters/__init__.py

@@ -0,0 +1,35 @@
+"""Persistent characters: the ``.char`` container, its compiled payloads, and identity scoring."""
+
+from .charfile import (
+    FORMAT_VERSION,
+    MAGIC,
+    SIGNATURE,
+    CharDoc,
+    CharFileError,
+    Manifest,
+    centroid_valid,
+    looks_like_char,
+    member_name,
+    payload_valid,
+    read,
+    refs_fingerprint,
+    sha256_bytes,
+    write,
+)
+
+__all__ = [
+    "FORMAT_VERSION",
+    "MAGIC",
+    "SIGNATURE",
+    "CharDoc",
+    "CharFileError",
+    "Manifest",
+    "centroid_valid",
+    "looks_like_char",
+    "member_name",
+    "payload_valid",
+    "read",
+    "refs_fingerprint",
+    "sha256_bytes",
+    "write",
+]

inline_core-1.2.71/src/inline_core/characters/apply.py

@@ -0,0 +1,145 @@
+"""``char_apply``: a character turned into the references and prompt text a run needs.
+
+Payload PNGs are extracted from the zip once, keyed by content hash so an edit lands in a new
+directory rather than mutating one a running graph is reading.
+"""
+
+from __future__ import annotations
+
+import logging
+import shutil
+from pathlib import Path
+from typing import Any
+
+from ..config import data_dir
+from ..takes import AssetRef
+from . import charfile as cf
+from . import encode, library
+
+logger = logging.getLogger("inline_core.characters")
+
+#: Extracted payload bytes to keep. Tiny next to a checkpoint, so this holds many characters.
+_CACHE_LIMIT_BYTES = 2 * 1024**3
+
+
+class AppliedCharacter:
+    """What a runner needs: ordered reference handles, plus the prompt text that names them."""
+
+    def __init__(self, name: str, refs: list[AssetRef], description: str) -> None:
+        self.name = name
+        self.refs = refs
+        self.description = description
+
+    def prompt_prefix(self, first_position: int) -> str:
+        """Text naming the positions the character lands on, so ordinal prompting resolves."""
+        if not self.refs:
+            return ""
+        positions = [str(first_position + i) for i in range(len(self.refs))]
+        if len(positions) == 1:
+            which = f"Image {positions[0]} shows"
+        else:
+            which = f"Images {', '.join(positions[:-1])} and {positions[-1]} show"
+        line = f"{which} {self.name}, the same character in every image."
+        detail = " ".join(self.description.split())
+        if not detail:
+            return f"{line} "
+        # Prose, not comma tags: without this it runs into the user's prompt unpunctuated.
+        if detail[-1] not in ".!?":
+            detail += "."
+        return f"{line} {detail} "
+
+
+def _cache_root() -> Path:
+    return data_dir() / "characters"
+
+
+def char_apply(chosen: str) -> AppliedCharacter | None:
+    """References and prompt text for a pick, or None when none. An unreadable pick raises rather
+    than silently generating the wrong person."""
+    name = str(chosen or "").strip()
+    if not name:
+        return None
+    path = library.resolve(name)
+    if path is None:
+        raise FileNotFoundError(
+            f"Character {name!r} is not in models/characters/. Pick another in the node's settings."
+        )
+
+    doc = cf.read(path)
+    digest = library.content_hash(path)
+    arch = encode.FLUX2_KLEIN_ARCH
+
+    if not cf.payload_valid(doc.manifest, arch, encode.PAYLOAD_ENCODER_VERSION):
+        doc = _recompile(doc, path)
+        digest = library.content_hash(path)
+
+    refs = _extract(doc, digest, arch)
+    description = _description(doc)
+    return AppliedCharacter(doc.manifest.name or path.stem, refs, description)
+
+
+def _description(doc: cf.CharDoc) -> str:
+    raw = doc.members.get(str(doc.manifest.text.get("path") or ""))
+    return raw.decode("utf-8", errors="replace") if raw else ""
+
+
+def _recompile(doc: cf.CharDoc, path: Path) -> cf.CharDoc:
+    """Rebuild a stale payload from ``refs/``. Payloads are cache, so this always works."""
+    logger.info("Recompiling the %s payload for %s", encode.FLUX2_KLEIN_ARCH, path.name)
+    import io
+
+    from PIL import Image
+
+    images: list[Any] = []
+    for ref in doc.manifest.refs:
+        raw = doc.members.get(str(ref.get("path")))
+        if raw is None:
+            raise cf.CharFileError(
+                f"{path.name} is missing reference {ref.get('path')}, so it cannot be rebuilt."
+            )
+        images.append(Image.open(io.BytesIO(raw)).convert("RGB"))
+
+    encode.build_payload(doc.manifest, doc.members, images)
+    cf.write(path, doc)
+    return doc
+
+
+def _extract(doc: cf.CharDoc, digest: str, arch: str) -> list[AssetRef]:
+    payload = doc.manifest.payloads.get(arch) or {}
+    files = [str(entry.get("path")) for entry in payload.get("files") or []]
+    if not files:
+        return []
+
+    root = _cache_root() / digest
+    marker = root / ".complete"
+    if not marker.is_file():
+        staging = root.with_name(f"{digest}.part")
+        shutil.rmtree(staging, ignore_errors=True)
+        staging.mkdir(parents=True, exist_ok=True)
+        for member in files:
+            data = doc.members.get(member)
+            if data is None:
+                raise cf.CharFileError(f"Character payload is missing {member}.")
+            (staging / Path(member).name).write_bytes(data)
+        (staging / ".complete").write_text("ok")
+        shutil.rmtree(root, ignore_errors=True)
+        staging.replace(root)
+        _prune(_cache_root())
+
+    return [AssetRef(ref="path", path=str(root / Path(member).name)) for member in files]
+
+
+def _prune(root: Path) -> None:
+    """Oldest-first eviction against a size cap, the same shape as the prompt-embed cache."""
+    if not root.is_dir():
+        return
+    entries = sorted(
+        (p for p in root.iterdir() if p.is_dir()),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    total = 0
+    for entry in entries:
+        total += sum(f.stat().st_size for f in entry.rglob("*") if f.is_file())
+        if total > _CACHE_LIMIT_BYTES:
+            shutil.rmtree(entry, ignore_errors=True)

inline_core-1.2.71/src/inline_core/characters/charfile.py

@@ -0,0 +1,216 @@
+"""The ``.char`` container: a persistent character as one portable zip.
+
+::
+
+    Ada.char
+      manifest.json           first member; the signature is at byte 0
+      refs/000.png            user-provided reference images, immutable
+      derived/face_000.png    auto-generated crops
+      text/description.md     the locked character description
+      payloads/<arch>/        compiled per model family, pure cache
+      scoring/                identity centroids, one per scoring encoder
+
+Refs and text are truth; payloads and centroids are cache, and must be regenerable from ``refs/``.
+Torch-free and network-free, so a core install can read a character.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+#: A reader refuses anything above this rather than half-loading the wrong face.
+FORMAT_VERSION = 1
+
+MAGIC = "INLINECHAR"
+
+#: Valid JSON *and* a signature, so a file is identifiable from 32 bytes without parsing.
+SIGNATURE = f'{{"magic":"{MAGIC}","format_version":'.encode()
+
+MANIFEST_NAME = "manifest.json"
+
+#: Fixed so the signature lands at byte 0 and two writes produce identical bytes.
+_KEY_ORDER = (
+    "magic", "format_version", "char_id", "name", "created_at", "modified_at", "app",
+    "app_version", "refs", "derived", "text", "payloads", "scoring", "hints", "reserved",
+)
+
+
+class CharFileError(Exception):
+    """A ``.char`` that cannot be trusted. The message is shown to the user."""
+
+
+@dataclass
+class Manifest:
+    char_id: str
+    name: str
+    created_at: int
+    modified_at: int
+    app_version: str = ""
+    refs: list[dict[str, Any]] = field(default_factory=list)
+    derived: list[dict[str, Any]] = field(default_factory=list)
+    text: dict[str, Any] = field(default_factory=dict)
+    payloads: dict[str, Any] = field(default_factory=dict)
+    scoring: dict[str, Any] = field(default_factory=dict)
+    hints: list[str] = field(default_factory=list)
+    reserved: dict[str, Any] = field(
+        default_factory=lambda: {"adapters": {}, "video_payloads": {}, "members": []}
+    )
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "magic": MAGIC,
+            "format_version": FORMAT_VERSION,
+            "char_id": self.char_id,
+            "name": self.name,
+            "created_at": self.created_at,
+            "modified_at": self.modified_at,
+            "app": "inline-studio",
+            "app_version": self.app_version,
+            "refs": self.refs,
+            "derived": self.derived,
+            "text": self.text,
+            "payloads": self.payloads,
+            "scoring": self.scoring,
+            "hints": self.hints,
+            "reserved": self.reserved,
+        }
+
+    @classmethod
+    def from_json(cls, raw: dict[str, Any]) -> Manifest:
+        return cls(
+            char_id=str(raw.get("char_id", "")),
+            name=str(raw.get("name", "")),
+            created_at=int(raw.get("created_at", 0)),
+            modified_at=int(raw.get("modified_at", 0)),
+            app_version=str(raw.get("app_version", "")),
+            refs=list(raw.get("refs") or []),
+            derived=list(raw.get("derived") or []),
+            text=dict(raw.get("text") or {}),
+            payloads=dict(raw.get("payloads") or {}),
+            scoring=dict(raw.get("scoring") or {}),
+            hints=list(raw.get("hints") or []),
+            reserved=dict(raw.get("reserved") or {}),
+        )
+
+
+@dataclass
+class CharDoc:
+    """A whole character in memory: the manifest plus every member's bytes."""
+
+    manifest: Manifest
+    members: dict[str, bytes] = field(default_factory=dict)
+
+
+def sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def member_name(prefix: str, index: int, suffix: str) -> str:
+    """``refs/000.png`` - always ASCII, since a user's filename may not extract on Windows."""
+    return f"{prefix}/{index:03d}{suffix}"
+
+
+def dumps_manifest(manifest: Manifest) -> bytes:
+    """Manifest bytes with the signature at byte 0."""
+    raw = manifest.to_json()
+    ordered = {key: raw[key] for key in _KEY_ORDER if key in raw}
+    data = json.dumps(ordered, ensure_ascii=True, separators=(",", ":")).encode()
+    if not data.startswith(SIGNATURE):
+        raise CharFileError("Character manifest lost its signature; the key order is wrong.")
+    return data
+
+
+def looks_like_char(data: bytes) -> bool:
+    """Whether a manifest blob carries our signature. Cheap enough for an upload gate."""
+    return data.startswith(SIGNATURE)
+
+
+def read(path: Path | str) -> CharDoc:
+    """Load a ``.char``. Raises `CharFileError` with user-facing copy on anything unreadable."""
+    target = Path(path)
+    try:
+        with zipfile.ZipFile(target, "r") as archive:
+            names = archive.namelist()
+            if MANIFEST_NAME not in names:
+                raise CharFileError(f"{target.name} is not a character file (no manifest).")
+            raw = archive.read(MANIFEST_NAME)
+            members = {
+                n: archive.read(n)
+                for n in names
+                if n != MANIFEST_NAME and not n.endswith("/")
+            }
+    except zipfile.BadZipFile as error:
+        raise CharFileError(f"{target.name} is not a readable character file.") from error
+
+    if not looks_like_char(raw):
+        raise CharFileError(f"{target.name} is not a character file (bad signature).")
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as error:
+        raise CharFileError(f"{target.name} has a corrupt manifest.") from error
+
+    version = int(parsed.get("format_version", 0))
+    if version > FORMAT_VERSION:
+        raise CharFileError(
+            f"{target.name} was written by a newer version of Inline Studio "
+            f"(character format {version}, this build reads {FORMAT_VERSION}). Update to open it."
+        )
+    return CharDoc(manifest=Manifest.from_json(parsed), members=members)
+
+
+def write(path: Path | str, doc: CharDoc) -> Path:
+    """Write atomically. The archive closes before the replace, or Windows refuses it."""
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    staging = target.with_name(target.name + ".part")
+    try:
+        with zipfile.ZipFile(staging, "w", zipfile.ZIP_DEFLATED) as archive:
+            # Manifest first so a reader can identify the file from the front of the stream.
+            archive.writestr(MANIFEST_NAME, dumps_manifest(doc.manifest))
+            for name in sorted(doc.members):
+                # PNGs are already compressed; deflating them again costs time and saves nothing.
+                compress = zipfile.ZIP_STORED if name.endswith(".png") else zipfile.ZIP_DEFLATED
+                archive.writestr(name, doc.members[name], compress_type=compress)
+        os.replace(staging, target)
+    except Exception:
+        staging.unlink(missing_ok=True)
+        raise
+    return target
+
+
+def refs_fingerprint(manifest: Manifest, policy: dict[str, Any]) -> str:
+    """Ordered ref hashes plus policy, so a reorder or a resize-budget change both invalidate."""
+    parts = [str(ref.get("sha256", "")) for ref in manifest.refs]
+    parts.append(json.dumps(policy, sort_keys=True, separators=(",", ":")))
+    return hashlib.sha256("\x1f".join(parts).encode()).hexdigest()
+
+
+def payload_valid(manifest: Manifest, arch: str, encoder_version: str) -> bool:
+    """Whether ``payloads/<arch>/`` can be used as-is, or must be recompiled from ``refs/``."""
+    payload = manifest.payloads.get(arch)
+    if not isinstance(payload, dict):
+        return False
+    encoder = payload.get("encoder")
+    if not isinstance(encoder, dict) or str(encoder.get("version", "")) != encoder_version:
+        return False
+    policy = payload.get("policy")
+    if not isinstance(policy, dict):
+        return False
+    return str(payload.get("source_sha256", "")) == refs_fingerprint(manifest, policy)
+
+
+def centroid_valid(manifest: Manifest, encoder_id: str, encoder_version: str) -> bool:
+    """Cosine similarity across two encoder builds is meaningless, so the version must match."""
+    encoders = manifest.scoring.get("encoders")
+    if not isinstance(encoders, list):
+        return False
+    for entry in encoders:
+        if isinstance(entry, dict) and str(entry.get("id")) == encoder_id:
+            return str(entry.get("version", "")) == encoder_version
+    return False

inline_core-1.2.71/src/inline_core/characters/encode.py

@@ -0,0 +1,232 @@
+"""``char_encode``: reference images plus a description compiled into one ``.char``.
+
+Refs go in untouched apart from EXIF rotation, because everything else is derived from them.
+"""
+
+from __future__ import annotations
+
+import io
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+from . import charfile as cf
+from . import scoring
+
+#: The payload compiler's version. Bumping it recompiles every character's ref set on next use.
+PAYLOAD_ENCODER_VERSION = "1"
+PAYLOAD_ENCODER_ID = "flux2-klein-refset"
+FLUX2_KLEIN_ARCH = "flux2-klein"
+
+#: Done here so the pixels the pipeline sees are the pixels we hashed, once per character.
+PAYLOAD_POLICY: dict[str, Any] = {"max_pixels": 1024 * 1024, "multiple_of": 16}
+
+#: Enough pixels for SFace without carrying a full reference into the file.
+FACE_CROP_SIZE = 512
+
+_FACE_EMBEDS = f"scoring/embeds_{scoring.SFACE_ID}.json"
+
+
+def _open(path: Path) -> Any:
+    from PIL import Image, ImageOps
+
+    with Image.open(path) as handle:
+        # Without EXIF rotation every downstream crop and centroid is wrong the same invisible way.
+        return ImageOps.exif_transpose(handle).convert("RGB")
+
+
+def _png_bytes(image: Any) -> bytes:
+    buffer = io.BytesIO()
+    image.save(buffer, format="PNG")
+    return buffer.getvalue()
+
+
+def normalise_reference(image: Any, policy: dict[str, Any] | None = None) -> Any:
+    """A reference resized into FLUX.2's budget, on the grid, preserving aspect."""
+    rules = policy or PAYLOAD_POLICY
+    max_pixels = int(rules["max_pixels"])
+    grid = int(rules["multiple_of"])
+    width, height = image.width, image.height
+    if width * height > max_pixels:
+        scale = (max_pixels / (width * height)) ** 0.5
+        width, height = int(width * scale), int(height * scale)
+    width = max(grid, (width // grid) * grid)
+    height = max(grid, (height // grid) * grid)
+    if (width, height) == (image.width, image.height):
+        return image
+    from PIL import Image
+
+    return image.resize((width, height), Image.LANCZOS)
+
+
+def strength_hints(sizes: list[tuple[int, int]]) -> list[str]:
+    """One nudge per distinct gap. Creation is never gated on any of these.
+
+    Takes sizes rather than images so it can be recomputed from a manifest, which is what keeps a
+    rule change from leaving every existing character showing the advice it was encoded with.
+    """
+    hints: list[str] = []
+    # Escalating, never stacked: at one reference "add another angle" and "add a profile view" are
+    # the same request worded twice, which reads as two chores instead of one.
+    if len(sizes) == 1:
+        hints.append("Add a second angle")
+    elif len(sizes) == 2:
+        hints.append("Add a profile view")
+    elif len(sizes) < 4:
+        hints.append("Add a different outfit or setting")
+    ratios = [w / h for w, h in sizes if h]
+    if len(sizes) >= 2 and ratios and abs(max(ratios) - min(ratios)) < 0.05:
+        hints.append("Add a wider or tighter crop")
+    return hints
+
+
+def flags_for(doc: cf.CharDoc) -> dict[str, Any]:
+    """Reference agreement recomputed from the stored embeddings, so a floor change reaches
+    characters already on disk. Falls back to what was recorded at encode time."""
+    refs = scoring.load_embeds(doc.members, str(doc.manifest.scoring.get("faceEmbeds") or ""))
+    if not refs:
+        return {
+            "refAgreement": list(doc.manifest.scoring.get("refAgreement") or []),
+            "flaggedRefs": list(doc.manifest.scoring.get("flaggedRefs") or []),
+        }
+    return {
+        "refAgreement": scoring.reference_agreement(refs),
+        "flaggedRefs": scoring.flagged_references(refs),
+    }
+
+
+def hints_for(manifest: cf.Manifest) -> list[str]:
+    """Hints recomputed from the manifest, so they never go stale against the current rules."""
+    return strength_hints(
+        [(int(r.get("width") or 0), int(r.get("height") or 0)) for r in manifest.refs]
+    )
+
+
+def char_encode(
+    refs: list[Path | str],
+    *,
+    name: str,
+    description: str = "",
+    app_version: str = "",
+    char_id: str | None = None,
+    created_at: int | None = None,
+) -> cf.CharDoc:
+    """Compile reference images into a `CharDoc`. The caller writes it wherever it belongs."""
+    paths = [Path(p) for p in refs]
+    if not paths:
+        raise ValueError("A character needs at least one reference image.")
+    missing = [p.name for p in paths if not p.is_file()]
+    if missing:
+        raise ValueError(f"Reference image not found: {', '.join(missing)}")
+
+    now = int(time.time())
+    images = [_open(p) for p in paths]
+    members: dict[str, bytes] = {}
+    manifest = cf.Manifest(
+        char_id=char_id or str(uuid.uuid4()),
+        name=name.strip() or "Character",
+        created_at=created_at or now,
+        modified_at=now,
+        app_version=app_version,
+    )
+
+    for index, (path, image) in enumerate(zip(paths, images, strict=True)):
+        member = cf.member_name("refs", index, ".png")
+        data = _png_bytes(image)
+        members[member] = data
+        manifest.refs.append(
+            {
+                "path": member,
+                "sha256": cf.sha256_bytes(data),
+                "width": image.width,
+                "height": image.height,
+                "source_name": path.name,
+            }
+        )
+
+    text_member = "text/description.md"
+    text_bytes = (description or "").encode("utf-8")
+    members[text_member] = text_bytes
+    manifest.text = {"path": text_member, "sha256": cf.sha256_bytes(text_bytes)}
+
+    crops: list[Any | None] = []
+    for index, image in enumerate(images):
+        crop = scoring.face_crop(image)
+        crops.append(crop)
+        if crop is None:
+            continue
+        crop = crop.resize((FACE_CROP_SIZE, FACE_CROP_SIZE))
+        member = f"derived/face_{index:03d}.png"
+        data = _png_bytes(crop)
+        members[member] = data
+        manifest.derived.append(
+            {
+                "path": member,
+                "kind": "face_crop",
+                "from": cf.member_name("refs", index, ".png"),
+                "producer": "yunet",
+                "producer_version": scoring.weights.YUNET_VERSION,
+                "sha256": cf.sha256_bytes(data),
+            }
+        )
+
+    build_payload(manifest, members, images)
+    _build_centroids(manifest, members, images, crops)
+    manifest.hints = strength_hints([(im.width, im.height) for im in images])
+    return cf.CharDoc(manifest=manifest, members=members)
+
+
+def build_payload(manifest: cf.Manifest, members: dict[str, bytes], images: list[Any]) -> None:
+    """(Re)compile the flux2-klein reference set. Public because ``apply`` rebuilds stale ones."""
+    for stale in [m for m in members if m.startswith(f"payloads/{FLUX2_KLEIN_ARCH}/")]:
+        members.pop(stale, None)
+    files: list[dict[str, Any]] = []
+    for index, image in enumerate(images):
+        member = f"payloads/{FLUX2_KLEIN_ARCH}/ref_{index:03d}.png"
+        data = _png_bytes(normalise_reference(image))
+        members[member] = data
+        files.append({"path": member, "sha256": cf.sha256_bytes(data)})
+    manifest.payloads[FLUX2_KLEIN_ARCH] = {
+        "payload_version": 1,
+        "encoder": {"id": PAYLOAD_ENCODER_ID, "version": PAYLOAD_ENCODER_VERSION},
+        "source_sha256": cf.refs_fingerprint(manifest, PAYLOAD_POLICY),
+        "policy": dict(PAYLOAD_POLICY),
+        "files": files,
+    }
+
+
+def _build_centroids(
+    manifest: cf.Manifest,
+    members: dict[str, bytes],
+    images: list[Any],
+    crops: list[Any | None],
+) -> None:
+    centroids: dict[str, str] = {}
+
+    # Whole frame, not the crop: SFace self-aligns, and mismatching the two sides costs ~10 points.
+    face_vectors = [v for image in images if (v := scoring.embed_face(image))]
+    face_centroid = scoring.mean_vector(face_vectors)
+    if face_centroid:
+        member = f"scoring/centroid_{scoring.SFACE_ID}.json"
+        members[member] = scoring.dump_centroid(face_centroid, len(face_vectors))
+        centroids[scoring.SFACE_ID] = member
+        # Every view kept, not just their mean: the face term matches the best-fitting one.
+        members[_FACE_EMBEDS] = scoring.dump_embeds(face_vectors)
+
+    subject_vectors = [v for image in images if (v := scoring.embed_subject(image))]
+    subject_centroid = scoring.mean_vector(subject_vectors)
+    if subject_centroid:
+        member = f"scoring/centroid_{scoring.DINOV2_ID}.json"
+        members[member] = scoring.dump_centroid(subject_centroid, len(subject_vectors))
+        centroids[scoring.DINOV2_ID] = member
+
+    manifest.scoring = {
+        "encoders": scoring.encoder_versions(),
+        "centroids": centroids,
+        "faceEmbeds": _FACE_EMBEDS if face_centroid else "",
+        "refAgreement": scoring.reference_agreement(face_vectors),
+        "flaggedRefs": scoring.flagged_references(face_vectors),
+        "face_bearing": bool(face_centroid),
+        "blend": {"face": scoring.FACE_WEIGHT, "subject": scoring.SUBJECT_WEIGHT},
+    }