alchemyface 0.1.0__tar.gz

alchemyface-0.1.0/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+_Nothing yet._
+
+## [0.1.0] — 2026-08-28
+
+First release. Extracted from an earlier prototype into a typed, installable library.
+
+### Added
+
+- `Recognizer` facade sequencing three protocols — `Detector`, `Embedder` and
+  `FaceStore` — so a different gallery or embedding model is a drop-in.
+- `YuNetDetector` for detection and `SFaceEmbedder` for 128-d embeddings, via
+  OpenCV's DNN runtime. Embeddings are L2-normalised, making cosine similarity
+  a dot product.
+- `InMemoryStore`: a numpy gallery with `.npz` save/load. No database required.
+- Runtime model resolution — explicit path, `$ALCHEMYFACE_MODEL_DIR`,
+  `~/.cache/alchemyface/models/`, then a SHA256-verified download from the
+  OpenCV Zoo. Weights are never vendored, keeping the wheel at ~20 KB.
+- `VideoSource`, a context-managed wrapper over `cv2.VideoCapture`.
+- CLI: `alchemyface download-models | enroll | identify | version`.
+- Inline type information (`py.typed`), checked with mypy under
+  `disallow_untyped_defs`.
+
+### Notes
+
+- Depends on `opencv-python-headless` rather than `opencv-python`: the package
+  makes no GUI calls, and the headless build installs cleanly on CI, in Docker
+  and on servers without `libGL`.
+- 88 tests at 91% coverage. The default suite needs no models, camera or
+  network; model-backed tests are marked and skip when weights are absent.
+
+[Unreleased]: https://github.com/kouya-marino/AlchemyFace/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/kouya-marino/AlchemyFace/releases/tag/v0.1.0

alchemyface-0.1.0/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/MANIFEST.in

@@ -0,0 +1,16 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include requirements.txt
+include requirements-dev.txt
+include src/alchemyface/py.typed
+
+# Never ship: personal data, model weights, developer scaffolding.
+prune _local
+prune examples
+prune tests
+prune docs
+prune htmlcov
+global-exclude *.npy *.npz *.onnx *.mp3 *.pt
+global-exclude *.py[cod]
+global-exclude .DS_Store

alchemyface-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,160 @@
+# 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/pyproject.toml

@@ -0,0 +1,95 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "alchemyface"
+version = "0.1.0"
+description = "Face detection and recognition built on YuNet and SFace — a small, typed, dependency-light Python library."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "Prashant Rawat", email = "prashantrawatmailbox@gmail.com"},
+]
+keywords = ["face-recognition", "face-detection", "yunet", "sface", "opencv", "embeddings"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+    "Typing :: Typed",
+]
+# Deliberately minimal. Model weights are fetched at runtime rather than
+# vendored, and everything the original prototype needed for its own deployment
+# (SQLAlchemy, psycopg2, pgvector, pandas, scikit-learn, ultralytics, pygame)
+# belongs to the application, not to this library.
+#
+# headless, not the GUI build: the package makes no imshow/waitKey calls, and
+# plain opencv-python needs libGL, which breaks CI, Docker and headless servers.
+dependencies = [
+    "opencv-python-headless>=4.9,<5",
+    "numpy>=1.24,<3",
+    "typer>=0.12,<1",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.4.0",
+    "mypy>=1.11",
+]
+
+[project.urls]
+Homepage = "https://github.com/kouya-marino/AlchemyFace"
+Repository = "https://github.com/kouya-marino/AlchemyFace"
+Issues = "https://github.com/kouya-marino/AlchemyFace/issues"
+
+[project.scripts]
+alchemyface = "alchemyface.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["alchemyface*"]
+
+[tool.setuptools.package-data]
+alchemyface = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+markers = [
+    "models: requires the real ONNX weights on disk (skipped when absent)",
+    "camera: requires an attached camera (skipped in CI)",
+]
+
+[tool.coverage.run]
+source = ["src/alchemyface"]
+branch = true
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+
+[tool.mypy]
+python_version = "3.10"
+packages = ["alchemyface"]
+mypy_path = "src"
+warn_unused_ignores = true
+warn_redundant_casts = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+
+# cv2 ships partial stubs. Use the `FaceDetectorYN.create` / `FaceRecognizerSF.create`
+# class-method form, which they declare; the module-level `*_create` aliases are not.
+[[tool.mypy.overrides]]
+module = ["cv2.*"]
+ignore_missing_imports = true

alchemyface-0.1.0/requirements-dev.txt

@@ -0,0 +1,10 @@
+# Development-only dependencies. Install with:
+#   pip install -r requirements-dev.txt
+# Production deps stay in requirements.txt.
+#
+# Kept in step with pyproject.toml's [project.optional-dependencies] dev extra —
+# CI gates on ruff and mypy, so both belong here.
+pytest>=8.0
+pytest-cov>=5.0
+ruff>=0.4.0
+mypy>=1.11

alchemyface-0.1.0/requirements.txt

@@ -0,0 +1,6 @@
+# Runtime dependencies, kept in step with pyproject.toml's [project] dependencies.
+# Installing the package itself (`pip install -e .`) is the usual route; this
+# file exists for environments that pin from a requirements file.
+opencv-python-headless>=4.9,<5
+numpy>=1.24,<3
+typer>=0.12,<1

alchemyface-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

alchemyface-0.1.0/src/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-0.1.0/src/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()