abstract_identity

Identity pipeline for hugpy, merged from the former standalone char360 and identity-render dists into one src-layout package with two subpackages:

Install

Base (any box — coordinator, dev VM, CI):

pip install abstract_identity

Base is deliberately thin and wheels-only: flask + pydantic, nothing else. Every module still imports cleanly with no heavy deps present — heavy imports are lazy, inside the stage/job that needs them — so the service can boot anywhere and honestly report capabilities as not-ready.

ae render host (GPU box): run the installer instead of pip —

bash /srv/share/projects/hugpy/dev/py/abstract_identity/install/install_identity_render_ae.sh \
  --token <TOKEN>

It is idempotent (safe to re-run), refuses to run without --token or as root, and sets up: CUDA torch, the Hunyuan3D-2 checkout + weights, rembg, portable Blender 4.2, the char360 heavy deps, an editable install of this package into the venv, and the identity-render.service systemd user unit (ExecStart=venv/bin/python -m abstract_identity.render.service). See the script header and its PASS:/FAIL:/NOTE: output for details. One-time firewall opening on ae (verified 2026-07-14):

sudo ufw allow from 192.168.1.0/24 to any port 9750 proto tcp comment 'identity-render (hugpy central relay)'

Why the heavy deps are an extra, not base

pip install abstract_identity[render] pulls the char360 detection stack: scenedetect[opencv], ultralytics, insightface, onnxruntime-gpu==1.18.1, opencv-python, numpy, scikit-learn. They are not in base because they are

• heavy/native/CUDA — pointless on a coordinator box, and
• restrictively licensed — ultralytics is AGPL-3.0 (a deployed combination is an AGPL combined work) and the insightface pretrained packs (buffalo_l) are non-commercial research only. See the THIRD-PARTY OBLIGATIONS NOTICE in LICENSE before any commercial use or redistribution.

Hunyuan3D-2 is never a pip dep at all (restrictive Tencent community license — excludes EU/UK/South Korea including outputs). It is installed out-of-band, only on the render box, by install/install_identity_render_ae.sh (git checkout + pip install -e + weight pre-download); the code only reaches hy3dgen lazily inside a running mesh job. Same for torch, trimesh, and Blender.

Compat shims

The old import paths keep working — the wheel ships thin char360 and identity_render shim packages that re-export from their new homes:

import char360                      # -> abstract_identity.char360
from char360.pipeline import run_char360
import identity_render              # -> abstract_identity.render
from identity_render.jobstate import STAGE_DONE
python -m char360.cli <video> -o <outdir>
python -m identity_render.service   # old systemd ExecStart still boots

New code should import abstract_identity.char360 / abstract_identity.render directly. The log-capture contract is unchanged: service log records still flow through the literal "identity_render" logger name.

Service API (summary)

Every request, /health included, requires X-Identity-Render-Token: <TOKEN> (401 otherwise). Jobs run one at a time (single GPU, single worker thread).

Artifacts land under $IDENTITY_RENDER_HOME/<job_id>/; nothing is cleaned up automatically. Env vars (IDENTITY_RENDER_TOKEN/PORT/HOME, BLENDER_BIN, FFMPEG_BIN, HUNYUAN3D_*, HF_HOME, ...) are written to ~/identity-render/env by the installer. Background removal (mesh_params.remove_background) is ON by default; originals are never modified.

On ae: systemctl --user status identity-render.service, journalctl --user -u identity-render.service -f. Code-only update: re-run the installer (editable install — a restart alone picks up share changes), then systemctl --user restart identity-render.service.

char360 CLI

char360 <video> -o <outdir> [--stride 8] [--yolo yolov8m.pt] \
    [--min-h-frac 0.15] [--cluster-dist 0.55] [--min-faces 4]

Output: <outdir>/manifest.json + char_NN/view_MM_yaw±DDD.png crops (bin 0 frontal, 30° bins CCW; rear bins are yaw_source=rear_inferred via track-level identity propagation). Missing heavy deps fail loud at stage-run time with a pip install hint, never at import time.

Tests

python -m pytest tests/ -q     # or: python -m unittest discover tests

The suite never imports cv2/torch/insightface/sklearn/scenedetect — heavy stages are mocked — so it runs on a base install (plus numpy for the pipeline test's fixtures).

Publishing

cd py/abstract_identity
python -m build          # sdist + wheel
twine upload dist/*      # public PyPI

Order matters: publish abstract_identity before publishing abstract_hugpy_dev 0.1.234, which now base-depends on abstract_identity>=0.1.0. Version is single-sourced from src/abstract_identity/__init__.py:__version__ — bump it there.