alchemyface 0.1.0__py3-none-any.whl

alchemyface/__init__.py

@@ -0,0 +1,38 @@
+"""AlchemyFace — face detection and recognition on YuNet and SFace.
+
+The public surface is deliberately small::
+
+    from alchemyface import Recognizer
+
+    r = Recognizer()
+    r.enroll("prashant", image)
+    r.identify(frame)
+
+Everything else is a seam. ``Detector``, ``Embedder`` and ``FaceStore`` are
+protocols, so any conforming object can be substituted without touching the
+pipeline.
+"""
+
+from alchemyface.errors import (
+    AlchemyFaceError,
+    ModelDownloadError,
+    ModelNotFoundError,
+    NoFaceDetectedError,
+)
+from alchemyface.pipeline import DEFAULT_THRESHOLD, Recognizer
+from alchemyface.types import Face, Match, Recognition
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AlchemyFaceError",
+    "DEFAULT_THRESHOLD",
+    "Face",
+    "Match",
+    "ModelDownloadError",
+    "ModelNotFoundError",
+    "NoFaceDetectedError",
+    "Recognition",
+    "Recognizer",
+    "__version__",
+]

alchemyface/capture.py

@@ -0,0 +1,68 @@
+"""Reading frames from a camera or a video file.
+
+A thin wrapper over ``cv2.VideoCapture`` that fails loudly when the device
+will not open, releases itself on the way out of a ``with`` block, and offers
+an iterator so callers do not have to write the read-check-read loop by hand.
+"""
+
+from __future__ import annotations
+
+from types import TracebackType
+from typing import Iterator
+
+import cv2
+import numpy as np
+from numpy.typing import NDArray
+
+
+class VideoSource:
+    """A camera index or a path to a video file, as a context manager."""
+
+    def __init__(
+        self,
+        source: int | str = 0,
+        *,
+        width: int | None = None,
+        height: int | None = None,
+    ) -> None:
+        self._capture = cv2.VideoCapture(source)
+        if not self._capture.isOpened():
+            self._capture.release()
+            raise RuntimeError(f"could not open video source {source!r}")
+        if width is not None:
+            self._capture.set(cv2.CAP_PROP_FRAME_WIDTH, float(width))
+        if height is not None:
+            self._capture.set(cv2.CAP_PROP_FRAME_HEIGHT, float(height))
+        self._released = False
+
+    def read(self) -> NDArray[np.uint8] | None:
+        """The next frame, or ``None`` once the stream is exhausted."""
+        ok, frame = self._capture.read()
+        if not ok:
+            return None
+        return np.asarray(frame, dtype=np.uint8)
+
+    def frames(self) -> Iterator[NDArray[np.uint8]]:
+        """Yield frames until the stream ends."""
+        while True:
+            frame = self.read()
+            if frame is None:
+                return
+            yield frame
+
+    def release(self) -> None:
+        """Release the device. Safe to call more than once."""
+        if not self._released:
+            self._capture.release()
+            self._released = True
+
+    def __enter__(self) -> "VideoSource":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.release()

alchemyface/cli.py

@@ -0,0 +1,140 @@
+"""Command line entry point for AlchemyFace."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import typer
+from numpy.typing import NDArray
+
+from alchemyface import __version__
+from alchemyface.errors import AlchemyFaceError
+from alchemyface.models import MODELS, download, find_local
+from alchemyface.pipeline import DEFAULT_THRESHOLD, Recognizer
+from alchemyface.store.memory import InMemoryStore
+
+app = typer.Typer(
+    name="alchemyface",
+    help="Face detection and recognition on YuNet and SFace.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+# Typer promotes a lone command to the top level, which would make `alchemyface
+# version` an unexpected argument. An explicit callback keeps subcommand mode on
+# regardless of how many commands are registered.
+@app.callback()
+def main() -> None:
+    """Face detection and recognition on YuNet and SFace."""
+
+
+def _build_recognizer(**kwargs: object) -> Recognizer:
+    """Indirection so tests can substitute a fake-backed Recognizer."""
+    return Recognizer(**kwargs)  # type: ignore[arg-type]
+
+
+def _read_image(path: Path) -> NDArray[np.uint8]:
+    # Imported lazily so `alchemyface version` does not pay for loading cv2.
+    import cv2  # pylint: disable=import-outside-toplevel
+
+    image = cv2.imread(str(path))
+    if image is None:
+        typer.echo(f"could not read an image from {path}", err=True)
+        raise typer.Exit(code=2)
+    # imread's default IMREAD_COLOR always yields 8-bit 3-channel BGR, so this
+    # is a no-op at runtime; it is here to state the dtype for the type checker.
+    return np.asarray(image, dtype=np.uint8)
+
+
+def _load_gallery(recognizer: Recognizer, gallery: Path) -> None:
+    store = recognizer.store
+    if gallery.exists() and isinstance(store, InMemoryStore):
+        store.load(gallery)
+
+
+def _save_gallery(recognizer: Recognizer, gallery: Path) -> None:
+    store = recognizer.store
+    if isinstance(store, InMemoryStore):
+        gallery.parent.mkdir(parents=True, exist_ok=True)
+        store.save(gallery)
+
+
+@app.command()
+def version() -> None:
+    """Print the installed AlchemyFace version."""
+    typer.echo(__version__)
+
+
+@app.command("download-models")
+def download_models(
+    model_dir: Path | None = typer.Option(
+        None, "--model-dir", help="Where to write the weights (defaults to the cache)."
+    ),
+) -> None:
+    """Fetch the ONNX weights ahead of first use."""
+    for spec in MODELS.values():
+        existing = find_local(spec, model_dir)
+        if existing is not None:
+            typer.echo(f"{spec.key}: already present at {existing}")
+            continue
+        typer.echo(f"{spec.key}: downloading {spec.filename} …")
+        try:
+            path = download(spec, dest_dir=model_dir)
+        except AlchemyFaceError as exc:
+            typer.echo(f"{spec.key}: {exc}", err=True)
+            raise typer.Exit(code=1) from exc
+        typer.echo(f"{spec.key}: saved to {path}")
+
+
+@app.command()
+def enroll(
+    name: str = typer.Option(..., "--name", help="Label to store the face under."),
+    image: Path = typer.Option(..., "--image", exists=True, dir_okay=False, help="Photo containing one face."),
+    gallery: Path = typer.Option(..., "--gallery", help="Gallery .npz to create or extend."),
+    model_dir: Path | None = typer.Option(None, "--model-dir", help="Directory holding the weights."),
+) -> None:
+    """Add the most prominent face in an image to a gallery."""
+    recognizer = _build_recognizer(model_dir=model_dir)
+    _load_gallery(recognizer, gallery)
+    try:
+        recognizer.enroll(name, _read_image(image))
+    except AlchemyFaceError as exc:
+        typer.echo(f"could not enroll {name}: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+    _save_gallery(recognizer, gallery)
+    typer.echo(f"enrolled {name} — gallery now holds {len(recognizer.store)} face(s)")
+
+
+@app.command()
+def identify(
+    image: Path = typer.Option(..., "--image", exists=True, dir_okay=False, help="Image to search."),
+    gallery: Path = typer.Option(
+        ...,
+        "--gallery",
+        exists=True,
+        dir_okay=False,
+        help="Gallery .npz to search against.",
+    ),
+    threshold: float = typer.Option(DEFAULT_THRESHOLD, "--threshold", help="Cosine score required to accept."),
+    model_dir: Path | None = typer.Option(None, "--model-dir", help="Directory holding the weights."),
+) -> None:
+    """Report who each face in an image looks like."""
+    recognizer = _build_recognizer(model_dir=model_dir, threshold=threshold)
+    recognizer.threshold = threshold
+    _load_gallery(recognizer, gallery)
+    recognitions = recognizer.identify(_read_image(image))
+    if not recognitions:
+        typer.echo("no faces detected")
+        return
+    for recognition in recognitions:
+        x, y, w, h = recognition.face.bbox
+        if recognition.match is None:
+            typer.echo(f"unknown          at ({x},{y},{w},{h})")
+        else:
+            typer.echo(f"{recognition.match.label:<16} at ({x},{y},{w},{h}) score={recognition.match.score:.3f}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

alchemyface/detection/__init__.py

@@ -0,0 +1,6 @@
+"""Face detection. See ``base`` for the protocol these implement."""
+
+from alchemyface.detection.base import Detector
+from alchemyface.detection.yunet import YuNetDetector, face_from_row, row_from_face
+
+__all__ = ["Detector", "YuNetDetector", "face_from_row", "row_from_face"]

alchemyface/detection/base.py

@@ -0,0 +1,18 @@
+"""The detection seam."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+from numpy.typing import NDArray
+
+from alchemyface.types import Face
+
+
+@runtime_checkable
+class Detector(Protocol):
+    """Finds faces in a BGR image."""
+
+    def detect(self, image: NDArray[np.uint8]) -> list[Face]:
+        """Every face found, in the detector's own order. Empty list if none."""

alchemyface/detection/yunet.py

@@ -0,0 +1,82 @@
+"""YuNet face detection through OpenCV's DNN runtime.
+
+OpenCV hands back an ``(N, 15) float32`` array — bounding box in columns 0-3,
+five landmarks in 4-13, score in 14 — or ``None`` when nothing is found. The
+box is not clamped to the image, so it can start at a negative coordinate or
+run off the right edge; ``face_from_row`` fixes that before anyone slices an
+array with it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import cv2
+import numpy as np
+from numpy.typing import NDArray
+
+from alchemyface.models import DETECTOR, resolve
+from alchemyface.types import Face
+
+_ROW_WIDTH = 15
+
+
+def face_from_row(row: NDArray[np.float32], image_shape: tuple[int, ...]) -> Face:
+    """Convert one OpenCV detection row into a :class:`Face`, clamped."""
+    height, width = int(image_shape[0]), int(image_shape[1])
+    x = max(0, int(row[0]))
+    y = max(0, int(row[1]))
+    w = max(0, min(int(row[2]), width - x))
+    h = max(0, min(int(row[3]), height - y))
+    return Face(
+        bbox=(x, y, w, h),
+        landmarks=np.asarray(row[4:14], dtype=np.float32).reshape(5, 2),
+        confidence=float(row[14]),
+    )
+
+
+def row_from_face(face: Face) -> NDArray[np.float32]:
+    """Rebuild the 15-column row OpenCV needs for ``alignCrop``."""
+    row = np.zeros(_ROW_WIDTH, dtype=np.float32)
+    row[:4] = face.bbox
+    row[4:14] = face.landmarks.reshape(-1)
+    row[14] = face.confidence
+    return row
+
+
+class YuNetDetector:
+    """Implements :class:`~alchemyface.detection.base.Detector` with YuNet."""
+
+    def __init__(
+        self,
+        *,
+        model_path: Path | str | None = None,
+        model_dir: Path | str | None = None,
+        score_threshold: float = 0.9,
+        nms_threshold: float = 0.3,
+        top_k: int = 5000,
+    ) -> None:
+        path = Path(model_path) if model_path else resolve(DETECTOR, model_dir)
+        # The `Xxx.create` class-method form is what cv2's bundled type stubs
+        # declare; the module-level `FaceDetectorYN_create` alias is not, and
+        # trips mypy with "Module has no attribute".
+        self._detector = cv2.FaceDetectorYN.create(str(path), "", (320, 320), score_threshold, nms_threshold, top_k)
+        self._input_size = (320, 320)
+
+    def detect(self, image: NDArray[np.uint8]) -> list[Face]:
+        """Every face found in a BGR image, with boxes clamped to its bounds."""
+        if image.ndim != 3 or image.shape[2] != 3:
+            raise ValueError(f"expected a three-channel BGR image, got shape {image.shape}")
+        height, width = image.shape[:2]
+        # The network is built for a fixed input size; it must be told
+        # whenever the frame dimensions change or OpenCV raises.
+        if (width, height) != self._input_size:
+            self._detector.setInputSize((width, height))
+            self._input_size = (width, height)
+
+        _, rows = self._detector.detect(image)
+        if rows is None:
+            return []
+        # Iterating a 2-D ndarray yields rows, but the numpy stubs type the
+        # element as a scalar, so each row is re-asserted as a float32 array.
+        return [face_from_row(np.asarray(row, dtype=np.float32), image.shape) for row in rows]

alchemyface/embedding/__init__.py

@@ -0,0 +1,6 @@
+"""Face embedding. See ``base`` for the protocol these implement."""
+
+from alchemyface.embedding.base import Embedder
+from alchemyface.embedding.sface import SFaceEmbedder
+
+__all__ = ["Embedder", "SFaceEmbedder"]

alchemyface/embedding/base.py

@@ -0,0 +1,26 @@
+"""The embedding seam."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+import numpy as np
+from numpy.typing import NDArray
+
+from alchemyface.types import Face
+
+
+@runtime_checkable
+class Embedder(Protocol):
+    """Turns a detected face into a comparable vector."""
+
+    dim: int
+    """Length of the vectors this embedder produces."""
+
+    def embed(self, image: NDArray[np.uint8], face: Face) -> NDArray[np.float32]:
+        """A unit-length embedding of ``face`` as it appears in ``image``.
+
+        Implementations MUST return an L2-normalised, one-dimensional array of
+        length ``dim``, so that a dot product between two of them is their
+        cosine similarity.
+        """

alchemyface/embedding/sface.py

@@ -0,0 +1,48 @@
+"""SFace embeddings through OpenCV's DNN runtime.
+
+``alignCrop`` warps the face to a canonical 112x112 using the five landmarks,
+and ``feature`` turns that into a ``(1, 128) float32`` row. That row is *not*
+normalised — its L2 norm is around 10 — so this class flattens and normalises
+it. Once every vector is unit length, cosine similarity is a dot product, which
+is exactly what OpenCV's own ``FaceRecognizerSF.match`` computes and why
+scikit-learn is not a dependency.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import cv2
+import numpy as np
+from numpy.typing import NDArray
+
+from alchemyface.detection import row_from_face
+from alchemyface.models import EMBEDDER, resolve
+from alchemyface.types import Face
+
+
+class SFaceEmbedder:
+    """Implements :class:`~alchemyface.embedding.base.Embedder` with SFace."""
+
+    dim: int = 128
+
+    def __init__(
+        self,
+        *,
+        model_path: Path | str | None = None,
+        model_dir: Path | str | None = None,
+    ) -> None:
+        path = Path(model_path) if model_path else resolve(EMBEDDER, model_dir)
+        # The `Xxx.create` class-method form is what cv2's bundled type stubs
+        # declare; the module-level `FaceRecognizerSF_create` alias is not.
+        self._recognizer = cv2.FaceRecognizerSF.create(str(path), "")
+
+    def embed(self, image: NDArray[np.uint8], face: Face) -> NDArray[np.float32]:
+        """A unit-length 128-d embedding of one detected face."""
+        aligned = self._recognizer.alignCrop(image, row_from_face(face))
+        raw = self._recognizer.feature(aligned)
+        flat = np.asarray(raw, dtype=np.float32).ravel()
+        norm = float(np.linalg.norm(flat))
+        if norm == 0.0:
+            raise ValueError("SFace returned a zero embedding for this face")
+        return (flat / norm).astype(np.float32)

alchemyface/errors.py

@@ -0,0 +1,21 @@
+"""Every exception AlchemyFace raises descends from AlchemyFaceError, so a
+caller can wrap the library in one except clause and never see a bare
+cv2.error or urllib exception leak through."""
+
+from __future__ import annotations
+
+
+class AlchemyFaceError(Exception):
+    """Base class for every error AlchemyFace raises."""
+
+
+class ModelNotFoundError(AlchemyFaceError):
+    """Weights were not on disk and downloading them was not permitted."""
+
+
+class ModelDownloadError(AlchemyFaceError):
+    """A download failed, or what arrived did not match its checksum."""
+
+
+class NoFaceDetectedError(AlchemyFaceError):
+    """An operation required a face and the image had none."""

alchemyface/models.py

@@ -0,0 +1,155 @@
+"""Locating the ONNX weights AlchemyFace runs on.
+
+Weights are not vendored: a 37 MB wheel is slow to install and re-uploads on
+every release. They are resolved at runtime, first hit wins:
+
+1. an explicit ``model_dir`` argument
+2. ``$ALCHEMYFACE_MODEL_DIR``
+3. ``~/.cache/alchemyface/models/`` (honours ``$XDG_CACHE_HOME``)
+4. downloaded from the OpenCV Zoo and verified against a pinned SHA256
+
+Files already on disk are trusted and not checksummed — they may legitimately
+be a different build. Downloads always are.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import shutil
+import tempfile
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterator
+
+from alchemyface.errors import ModelDownloadError, ModelNotFoundError
+
+# The zoo keeps its weights in Git LFS. raw.githubusercontent.com serves the
+# ~130-byte pointer file instead of the model; the media host serves the model.
+_ZOO = "https://media.githubusercontent.com/media/opencv/opencv_zoo/main/models"
+
+_CHUNK = 1 << 20
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    """Where a model lives, what it is called, and how to know it arrived intact."""
+
+    key: str
+    filename: str
+    url: str
+    sha256: str
+
+    aliases: tuple[str, ...] = ()
+    """Other filenames the same architecture ships under. The prototype's
+    weights use different names, and should resolve without being renamed."""
+
+    @property
+    def candidates(self) -> tuple[str, ...]:
+        """Filenames to look for on disk, canonical name first."""
+        return (self.filename, *self.aliases)
+
+
+DETECTOR = ModelSpec(
+    key="detector",
+    filename="face_detection_yunet_2023mar.onnx",
+    url=f"{_ZOO}/face_detection_yunet/face_detection_yunet_2023mar.onnx",
+    sha256="8f2383e4dd3cfbb4553ea8718107fc0423210dc964f9f4280604804ed2552fa4",
+    aliases=("yunet_n_640_640.onnx",),
+)
+
+EMBEDDER = ModelSpec(
+    key="embedder",
+    filename="face_recognition_sface_2021dec.onnx",
+    url=f"{_ZOO}/face_recognition_sface/face_recognition_sface_2021dec.onnx",
+    sha256="0ba9fbfa01b5270c96627c4ef784da859931e02f04419c829e83484087c34e79",
+    aliases=("face_recognizer_fast.onnx",),
+)
+
+MODELS: dict[str, ModelSpec] = {spec.key: spec for spec in (DETECTOR, EMBEDDER)}
+
+
+def cache_dir() -> Path:
+    """Where downloaded weights are kept between runs."""
+    root = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(root) / "alchemyface" / "models"
+
+
+def _search_paths(model_dir: Path | str | None = None) -> Iterator[Path]:
+    if model_dir is not None:
+        yield Path(model_dir)
+    env = os.environ.get("ALCHEMYFACE_MODEL_DIR")
+    if env:
+        yield Path(env)
+    yield cache_dir()
+
+
+def find_local(spec: ModelSpec, model_dir: Path | str | None = None) -> Path | None:
+    """First existing file matching any of the spec's names, or None."""
+    for directory in _search_paths(model_dir):
+        for name in spec.candidates:
+            candidate = directory / name
+            if candidate.is_file():
+                return candidate
+    return None
+
+
+def sha256_of(path: Path | str) -> str:
+    """Hex digest of a file, read in chunks so a 37 MB model is not slurped."""
+    digest = hashlib.sha256()
+    with open(path, "rb") as handle:
+        for chunk in iter(lambda: handle.read(_CHUNK), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def download(spec: ModelSpec, dest_dir: Path | str | None = None) -> Path:
+    """Fetch a model, verify it, and place it atomically.
+
+    The download goes to a ``.part`` file in the destination directory and is
+    renamed only after the checksum passes, so an interrupted or corrupted
+    download can never be mistaken for a usable cache entry.
+    """
+    directory = Path(dest_dir) if dest_dir is not None else cache_dir()
+    directory.mkdir(parents=True, exist_ok=True)
+    handle, raw_tmp = tempfile.mkstemp(dir=directory, suffix=".part")
+    os.close(handle)
+    tmp = Path(raw_tmp)
+
+    try:
+        with urllib.request.urlopen(spec.url, timeout=60) as response:
+            with open(tmp, "wb") as out:
+                shutil.copyfileobj(response, out, _CHUNK)
+    except (urllib.error.URLError, OSError, ValueError) as exc:
+        tmp.unlink(missing_ok=True)
+        raise ModelDownloadError(f"could not download {spec.filename} from {spec.url}: {exc}") from exc
+
+    actual = sha256_of(tmp)
+    if actual != spec.sha256:
+        tmp.unlink(missing_ok=True)
+        raise ModelDownloadError(f"checksum mismatch for {spec.filename}: expected {spec.sha256}, got {actual}")
+
+    destination = directory / spec.filename
+    tmp.replace(destination)
+    return destination
+
+
+def resolve(
+    spec: ModelSpec,
+    model_dir: Path | str | None = None,
+    allow_download: bool = True,
+) -> Path:
+    """Path to usable weights, downloading them if that is permitted."""
+    local = find_local(spec, model_dir)
+    if local is not None:
+        return local
+    if not allow_download:
+        raise ModelNotFoundError(
+            f"{spec.filename} was not found in any of "
+            f"{[str(p) for p in _search_paths(model_dir)]}, "
+            "and downloading was disabled. Set ALCHEMYFACE_MODEL_DIR, pass "
+            "model_dir=, or run `alchemyface download-models`."
+        )
+    return download(spec)

alchemyface/pipeline.py

@@ -0,0 +1,98 @@
+"""The facade that sequences detection, embedding and storage.
+
+Recognizer deliberately contains no algorithm. It decides *order* and applies
+the *threshold*; everything else is delegated to whichever Detector, Embedder
+and FaceStore it was handed. That is what makes a pgvector gallery or a
+different embedding model a drop-in rather than a rewrite.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+import numpy as np
+from numpy.typing import NDArray
+
+from alchemyface.detection.base import Detector
+from alchemyface.embedding.base import Embedder
+from alchemyface.errors import NoFaceDetectedError
+from alchemyface.store.base import FaceStore
+from alchemyface.types import Face, Recognition
+
+DEFAULT_THRESHOLD = 0.363
+"""SFace's published cosine operating point. A tunable, not a constant:
+validate it against your own data before relying on it."""
+
+
+class Recognizer:
+    """Detect, embed, enroll and identify faces."""
+
+    def __init__(
+        self,
+        *,
+        detector: Detector | None = None,
+        embedder: Embedder | None = None,
+        store: FaceStore | None = None,
+        model_dir: Path | str | None = None,
+        threshold: float = DEFAULT_THRESHOLD,
+    ) -> None:
+        """Any component left as ``None`` gets the default implementation.
+
+        Constructing the defaults loads the ONNX weights, downloading them on
+        first use. Pass all three components to build a Recognizer that touches
+        neither disk nor network.
+        """
+        # Imported here rather than at module scope so that injecting fakes
+        # never pays the cost of importing cv2-backed modules.
+        # pylint: disable=import-outside-toplevel
+        from alchemyface.detection.yunet import YuNetDetector
+        from alchemyface.embedding.sface import SFaceEmbedder
+        from alchemyface.store.memory import InMemoryStore
+
+        self.detector: Detector = detector if detector is not None else YuNetDetector(model_dir=model_dir)
+        self.embedder: Embedder = embedder if embedder is not None else SFaceEmbedder(model_dir=model_dir)
+        self.store: FaceStore = store if store is not None else InMemoryStore(dim=self.embedder.dim)
+        self.threshold = threshold
+
+    def detect(self, image: NDArray[np.uint8]) -> list[Face]:
+        """Every face in the image."""
+        return self.detector.detect(image)
+
+    def embed(self, image: NDArray[np.uint8], face: Face) -> NDArray[np.float32]:
+        """The unit-length embedding of one already-detected face."""
+        return self.embedder.embed(image, face)
+
+    def enroll(
+        self,
+        label: str,
+        image: NDArray[np.uint8],
+        metadata: Mapping[str, Any] | None = None,
+    ) -> str:
+        """Add the most prominent face in the image to the gallery.
+
+        Raises :class:`NoFaceDetectedError` if there is no face. Enrolling the
+        largest face is a deliberate choice: an enrolment photo with a
+        bystander in the background should not silently enrol the bystander.
+        """
+        faces = self.detect(image)
+        if not faces:
+            raise NoFaceDetectedError(f"no face found in the image supplied for {label!r}")
+        face = max(faces, key=lambda candidate: candidate.area)
+        return self.store.add(label, self.embed(image, face), metadata)
+
+    def identify(self, image: NDArray[np.uint8]) -> list[Recognition]:
+        """One :class:`Recognition` per detected face.
+
+        ``Recognition.match`` is ``None`` when the best candidate falls below
+        the threshold, or when the gallery is empty — the caller decides what
+        "unknown" should mean rather than the library guessing a label.
+        """
+        recognitions: list[Recognition] = []
+        for face in self.detect(image):
+            candidates = self.store.search(self.embed(image, face), k=1)
+            best = candidates[0] if candidates else None
+            if best is not None and best.score < self.threshold:
+                best = None
+            recognitions.append(Recognition(face=face, match=best))
+        return recognitions

alchemyface/store/__init__.py

@@ -0,0 +1,6 @@
+"""Gallery backends. See ``base`` for the protocol they implement."""
+
+from alchemyface.store.base import FaceStore
+from alchemyface.store.memory import InMemoryStore
+
+__all__ = ["FaceStore", "InMemoryStore"]

alchemyface/store/base.py

@@ -0,0 +1,37 @@
+"""The gallery seam.
+
+A store owns enrolled embeddings and answers nearest-neighbour queries. It is
+a Protocol rather than a base class so a pgvector or SQLite implementation can
+be added later without inheriting from anything in this package.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Protocol, runtime_checkable
+
+import numpy as np
+from numpy.typing import NDArray
+
+from alchemyface.types import Match
+
+
+@runtime_checkable
+class FaceStore(Protocol):
+    """Holds labelled embeddings and finds the closest ones."""
+
+    def add(
+        self,
+        label: str,
+        vector: NDArray[np.float32],
+        metadata: Mapping[str, Any] | None = None,
+    ) -> str:
+        """Store an embedding under a label. Returns its opaque entry id."""
+
+    def search(self, vector: NDArray[np.float32], k: int = 1) -> list[Match]:
+        """The ``k`` most similar entries, best first. Empty if the store is."""
+
+    def remove(self, entry_id: str) -> None:
+        """Delete one entry. Raises ``KeyError`` if it is not there."""
+
+    def __len__(self) -> int:
+        """How many entries are stored."""

alchemyface/store/memory.py

@@ -0,0 +1,129 @@
+"""A gallery held in a single numpy matrix.
+
+Every vector is stored L2-normalised, which makes cosine similarity a matrix
+product: ``vectors @ query``. That is why scikit-learn is not a dependency.
+Brute force over a few thousand faces is well under a millisecond, and it
+keeps the default install free of any database.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+from uuid import uuid4
+
+import numpy as np
+from numpy.typing import NDArray
+
+from alchemyface.types import Match
+
+
+@dataclass(frozen=True)
+class _Entry:
+    entry_id: str
+    label: str
+    metadata: dict[str, Any]
+
+
+def _as_unit_row(vector: NDArray[np.float32], dim: int) -> NDArray[np.float32]:
+    """Validate, flatten and normalise. Accepts ``(dim,)`` or ``(1, dim)``."""
+    flat = np.asarray(vector, dtype=np.float32).ravel()
+    if flat.shape != (dim,):
+        raise ValueError(f"expected a vector of dimension {dim}, got shape {np.shape(vector)}")
+    norm = float(np.linalg.norm(flat))
+    if norm == 0.0:
+        raise ValueError("cannot store a zero vector: it has no direction")
+    return (flat / norm).astype(np.float32)
+
+
+class InMemoryStore:
+    """Implements :class:`~alchemyface.store.base.FaceStore` with numpy."""
+
+    def __init__(self, dim: int = 128) -> None:
+        self._dim = dim
+        self._vectors: NDArray[np.float32] = np.empty((0, dim), dtype=np.float32)
+        self._entries: list[_Entry] = []
+
+    @property
+    def dim(self) -> int:
+        """Length of the vectors this gallery holds."""
+        return self._dim
+
+    def __len__(self) -> int:
+        """How many entries are stored."""
+        return len(self._entries)
+
+    def add(
+        self,
+        label: str,
+        vector: NDArray[np.float32],
+        metadata: Mapping[str, Any] | None = None,
+    ) -> str:
+        """Store an embedding under a label. Returns its opaque entry id."""
+        row = _as_unit_row(vector, self._dim)
+        entry = _Entry(uuid4().hex, label, dict(metadata or {}))
+        self._vectors = np.vstack([self._vectors, row])
+        self._entries.append(entry)
+        return entry.entry_id
+
+    def search(self, vector: NDArray[np.float32], k: int = 1) -> list[Match]:
+        """The ``k`` most similar entries, best first."""
+        if not self._entries:
+            return []
+        query = _as_unit_row(vector, self._dim)
+        scores = self._vectors @ query
+        take = min(max(k, 1), len(self._entries))
+        # argpartition finds the top-k in O(n); only those k are then sorted.
+        top = np.argpartition(-scores, take - 1)[:take]
+        top = top[np.argsort(-scores[top])]
+        return [
+            Match(
+                label=self._entries[i].label,
+                score=float(scores[i]),
+                entry_id=self._entries[i].entry_id,
+                metadata=dict(self._entries[i].metadata),
+            )
+            for i in top
+        ]
+
+    def remove(self, entry_id: str) -> None:
+        """Delete one entry. Raises ``KeyError`` if it is not there."""
+        for index, entry in enumerate(self._entries):
+            if entry.entry_id == entry_id:
+                del self._entries[index]
+                self._vectors = np.delete(self._vectors, index, axis=0)
+                return
+        raise KeyError(entry_id)
+
+    def save(self, path: Path | str) -> None:
+        """Write the gallery to a ``.npz`` file.
+
+        Metadata goes in as one JSON blob rather than an object array, so the
+        file loads without ``allow_pickle`` and cannot execute anything.
+        """
+        np.savez(
+            path,
+            vectors=self._vectors,
+            labels=np.array([e.label for e in self._entries], dtype="U"),
+            entry_ids=np.array([e.entry_id for e in self._entries], dtype="U"),
+            metadata=np.array(json.dumps([e.metadata for e in self._entries])),
+            dim=np.array(self._dim),
+        )
+
+    def load(self, path: Path | str) -> None:
+        """Replace the gallery with the contents of a ``.npz`` file."""
+        with np.load(path, allow_pickle=False) as data:
+            dim = int(data["dim"])
+            if dim != self._dim:
+                raise ValueError(f"gallery dimension {dim} does not match store dimension {self._dim}")
+            vectors = np.asarray(data["vectors"], dtype=np.float32)
+            labels: list[str] = np.asarray(data["labels"]).tolist()
+            entry_ids: list[str] = np.asarray(data["entry_ids"]).tolist()
+            metadata = json.loads(str(data["metadata"]))
+
+        self._vectors = vectors.reshape(-1, self._dim)
+        self._entries = [
+            _Entry(entry_id, label, dict(meta)) for entry_id, label, meta in zip(entry_ids, labels, metadata)
+        ]

alchemyface/types.py

@@ -0,0 +1,59 @@
+"""Value types shared across AlchemyFace. NumPy is the only import."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+@dataclass(frozen=True, eq=False)
+class Face:
+    """A detected face: where it is, how to align it, how sure the detector was.
+
+    ``eq=False`` is deliberate. ``landmarks`` is an ndarray, and a generated
+    ``__eq__`` would compare element-wise and return an array, so any ``==``
+    between two Faces would raise "truth value of an array is ambiguous".
+    Identity comparison is the useful default here.
+    """
+
+    bbox: tuple[int, int, int, int]
+    """Pixel bounding box as ``(x, y, width, height)``, clamped to the image."""
+
+    landmarks: NDArray[np.float32]
+    """``(5, 2)`` array: right eye, left eye, nose tip, right and left mouth corner."""
+
+    confidence: float
+    """Detector score. Not a recognition score — see :class:`Match`."""
+
+    @property
+    def area(self) -> int:
+        """Pixel area, used to pick the most prominent face in a frame."""
+        return self.bbox[2] * self.bbox[3]
+
+
+@dataclass(frozen=True)
+class Match:
+    """A gallery entry that resembles a query embedding."""
+
+    label: str
+
+    score: float
+    """Cosine similarity in ``[-1, 1]``. Higher is more alike."""
+
+    entry_id: str
+    """Opaque id of the stored entry, as returned by ``FaceStore.add``."""
+
+    metadata: Mapping[str, Any]
+
+
+@dataclass(frozen=True, eq=False)
+class Recognition:
+    """One detected face and the best gallery entry for it, if any cleared
+    the threshold. ``match is None`` means unknown — the library does not
+    invent a label for it."""
+
+    face: Face
+    match: Match | None

alchemyface-0.1.0.dist-info/METADATA

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: alchemyface
+Version: 0.1.0
+Summary: Face detection and recognition built on YuNet and SFace — a small, typed, dependency-light Python library.
+Author-email: Prashant Rawat <prashantrawatmailbox@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/kouya-marino/AlchemyFace
+Project-URL: Repository, https://github.com/kouya-marino/AlchemyFace
+Project-URL: Issues, https://github.com/kouya-marino/AlchemyFace/issues
+Keywords: face-recognition,face-detection,yunet,sface,opencv,embeddings
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opencv-python-headless<5,>=4.9
+Requires-Dist: numpy<3,>=1.24
+Requires-Dist: typer<1,>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Dynamic: license-file
+
+# AlchemyFace
+
+[![PyPI](https://img.shields.io/pypi/v/alchemyface.svg)](https://pypi.org/project/alchemyface/)
+[![CI](https://github.com/kouya-marino/AlchemyFace/actions/workflows/ci.yml/badge.svg)](https://github.com/kouya-marino/AlchemyFace/actions/workflows/ci.yml)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+
+Face detection and recognition built on [YuNet](https://github.com/opencv/opencv_zoo/tree/main/models/face_detection_yunet)
+and [SFace](https://github.com/opencv/opencv_zoo/tree/main/models/face_recognition_sface).
+Small, typed, and dependency-light: OpenCV, NumPy, Typer. Nothing else.
+
+## Why
+
+Most Python face-recognition libraries pull in dlib, PyTorch or TensorFlow.
+AlchemyFace uses two small ONNX models through OpenCV's own DNN runtime, so a
+working install is a few megabytes of Python and about 37 MB of weights fetched
+once, on first use.
+
+## Install
+
+```bash
+pip install alchemyface
+```
+
+## Use
+
+```python
+import cv2
+from alchemyface import Recognizer
+
+r = Recognizer()                       # weights download once, then cached
+
+r.enroll("prashant", cv2.imread("me.jpg"))
+r.enroll("alice",    cv2.imread("alice.jpg"))
+
+for recognition in r.identify(cv2.imread("group.jpg")):
+    face, match = recognition.face, recognition.match
+    if match:
+        print(f"{match.label} at {face.bbox} ({match.score:.2f})")
+    else:
+        print(f"unknown face at {face.bbox}")
+```
+
+Enrolled faces live in memory. Persist them when you are done:
+
+```python
+r.store.save("gallery.npz")
+r.store.load("gallery.npz")
+```
+
+### Bring your own components
+
+`Recognizer` is a thin facade over three protocols — `Detector`, `Embedder` and
+`FaceStore`. Any object satisfying the protocol can be substituted, which is how
+a pgvector-backed store or a different embedding model will slot in later
+without touching the pipeline.
+
+```python
+from alchemyface import Recognizer
+from alchemyface.detection import YuNetDetector
+from alchemyface.embedding import SFaceEmbedder
+from alchemyface.store import InMemoryStore
+
+r = Recognizer(
+    detector=YuNetDetector(score_threshold=0.8),
+    embedder=SFaceEmbedder(),
+    store=InMemoryStore(),
+    threshold=0.363,
+)
+```
+
+### Live video
+
+```python
+from alchemyface import Recognizer
+from alchemyface.capture import VideoSource
+
+r = Recognizer()
+r.store.load("gallery.npz")
+
+with VideoSource(0, width=1280, height=720) as camera:
+    for frame in camera.frames():
+        for recognition in r.identify(frame):
+            match = recognition.match
+            print(match.label if match else "unknown", recognition.face.bbox)
+```
+
+### CLI
+
+```bash
+alchemyface download-models          # pre-fetch weights
+alchemyface enroll  --name prashant --image me.jpg --gallery g.npz
+alchemyface identify --image group.jpg --gallery g.npz
+```
+
+## Model weights
+
+Weights are resolved in this order, first hit wins:
+
+1. `model_dir=` passed to `Recognizer`
+2. `$ALCHEMYFACE_MODEL_DIR`
+3. `~/.cache/alchemyface/models/`
+4. downloaded from the OpenCV Zoo and SHA256-verified
+
+To work fully offline, point at a directory you already have:
+
+```bash
+export ALCHEMYFACE_MODEL_DIR=/path/to/onnx
+```
+
+## The recognition threshold
+
+The default cosine threshold is `0.363`, SFace's published operating point:
+above it, two embeddings are treated as the same person. Raise it for fewer
+false accepts, lower it for fewer false rejects. It is a tunable, not a
+constant — validate it against your own data before relying on it.
+
+## Development
+
+Requires [`pyenv`](https://github.com/pyenv/pyenv) with
+[`pyenv-virtualenv`](https://github.com/pyenv/pyenv-virtualenv).
+
+```bash
+pyenv install 3.10.6                      # if not already present
+pyenv virtualenv 3.10.6 alchemyface       # .python-version activates it here
+pip install -e ".[dev]"
+```
+
+| Command | Does |
+|---|---|
+| `pytest tests/ -m "not models and not camera"` | the fast suite — no models, camera or network |
+| `pytest tests/ -m "not camera"` | adds the tests that load the real ONNX weights |
+| `ruff check src tests` | lint |
+| `ruff format src tests` | format |
+| `mypy src/alchemyface` | type check |
+| `python -m build` | build the wheel and sdist |
+
+Tests that need the real weights are marked `models` and skip unless
+`ALCHEMYFACE_MODEL_DIR` points at a directory containing them:
+
+```bash
+export ALCHEMYFACE_MODEL_DIR="$PWD/_local/onnx"
+```
+
+## A note on data
+
+This repository contains a `_local/` directory that is **git-ignored and must
+stay that way**. It holds face embeddings, name recordings and captured images
+of real, identifiable people, carried over from the internal prototype this
+library grew out of. Under Japan's APPI and GDPR Article 9 those are sensitive
+personal data. They are development fixtures only: they are excluded from the
+wheel, the sdist and version control, and they must never be published.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE).
+
+The ONNX weights are distributed by the [OpenCV Zoo](https://github.com/opencv/opencv_zoo)
+under their own terms — YuNet under MIT, SFace under Apache-2.0 — and are
+downloaded at runtime rather than redistributed here.

alchemyface-0.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+alchemyface/__init__.py,sha256=wR_u7sUmoAJK8IY42bh5WoLGIOJkFMgm56HiF_a_rLQ,893
+alchemyface/capture.py,sha256=dpVgoTjGhQVAvZCtepAw807N_C97ZsbdtA_xasaam7c,2073
+alchemyface/cli.py,sha256=em0fXJL1aBpdIqkMrla96R8E23iIdpPjNmcDgxs4dCE,5127
+alchemyface/errors.py,sha256=G4y_WkSe1s5QylUW9-jcWlqNA4gYIM5P8SIwjfYGgsY,672
+alchemyface/models.py,sha256=XFu5DQAuiU8vkYS3gYQ_r0-pzOjuMuuFghCjmwBi7HQ,5346
+alchemyface/pipeline.py,sha256=MiAlOcrl8W5lGdXCcLvYdXWX9k9-t3t_7JOSE3vvI0w,4113
+alchemyface/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+alchemyface/types.py,sha256=_Wj347H25n_6vTx0Sf8c-5MUlx83Z2uUY-8Ic6BV_9M,1746
+alchemyface/detection/__init__.py,sha256=UfTU-TFcFvLLovivIdo8tunqKScgLu2Z0oTwPxC5S4o,277
+alchemyface/detection/base.py,sha256=nO23sz_FLedoqM1lHvtuQ7HF1CqEI01dOv5B1XTCn8c,428
+alchemyface/detection/yunet.py,sha256=YFpAxJRgTNRKyBjbZZBaqa9F0sRifEWLYWVfdzBT6RA,3180
+alchemyface/embedding/__init__.py,sha256=hp6-DTTk3OeB-i_PpX9eJGtalbdJvjaQDciwnGhySqo,213
+alchemyface/embedding/base.py,sha256=886cl7KnfCW96UUTgCtpAAV0XxBTfwHxEqlWrD8Ey2I,726
+alchemyface/embedding/sface.py,sha256=WGA_xenYtaD-dzO9ehX1QqNbwJXxMlF8NY0bsdWQaUs,1835
+alchemyface/store/__init__.py,sha256=YSCJXHLtiWa4RkVaU7x8aMfBYANXe6y76Ayx5rcl8jg,209
+alchemyface/store/base.py,sha256=044pDe86y6DWlfMeCh_slbQUjG2dLbzDc7vsIc7Jszg,1127
+alchemyface/store/memory.py,sha256=ovQbyVSYcOE3KLQ1aonoWEABn4w50fifYsR-EQVZcDw,4782
+alchemyface-0.1.0.dist-info/licenses/LICENSE,sha256=ubEdDj3_clTEY-8HCiV9OeF-q2jtElWDhIYdLWWdcD0,1069
+alchemyface-0.1.0.dist-info/METADATA,sha256=je83lHMqNg39b7YFcbCrwdpskIJliShLMXJO9QaOg54,6672
+alchemyface-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+alchemyface-0.1.0.dist-info/entry_points.txt,sha256=IQyiMwb2lqnPVY9QlL_QMhMPDdFSKD0hQA2uNBP8NEI,52
+alchemyface-0.1.0.dist-info/top_level.txt,sha256=G8ftfh2cZe1n-U6avWo62EZf89dI5b1Z7bXmM0umc4A,12
+alchemyface-0.1.0.dist-info/RECORD,,

alchemyface-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

alchemyface-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+alchemyface = alchemyface.cli:app

alchemyface-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kouya-marino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

alchemyface-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+alchemyface