v1.0.0 — Refactored CLI, PyPI-ready, ClawHub install spec

Major changes:
- Restructured identify_faces.py, enroll_face.py, face_db.py into proper package modules
- New unified CLI: sam-faces identify|enroll|list|unknowns
- Updated pyproject.toml: v1.0.0, proper entry point, dev dependencies
- Added metadata.openclaw.install spec for ClawHub (pip install)
- Updated README.md with PyPI badge, quick start, auto-behavior docs
- Updated SKILL.md with ClawHub frontmatter and pip installer spec

Fixes from code review:
- Database migration: init_db() adds crop_path column for pre-v1.0.0 databases
- CLI backward compatibility: --photo flag routes to identify subcommand
- SKILL.md requires.bins restored to [sam-faces]

Tests:
- test_database.py: 7 tests (person CRUD, encodings, migration)
- test_identify.py: 4 tests (no faces, position, file not found, llm_context)
- test_cli.py: 6 tests (help, identify, enroll, legacy flag, list, unknowns)

CI:
- GitHub Actions workflow for testing across Python 3.9-3.12
- Build verification on every PR

Closes openclaw/openclaw#52535

Author: jasonacox-sam

.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake build-essential
+
+      - name: Install setuptools (provides pkg_resources for face_recognition_models)
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install --force-reinstall 'setuptools>=68.0'
+
+      - name: Install package and test deps
+        run: |
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short
+
+      - name: Check formatting (black)
+        run: black --check sam_faces/ tests/
+        if: matrix.python-version == '3.13'
+
+  build:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: twine check dist/*

README.md

@@ -3,7 +3,7 @@
 **Face recognition and identity memory for AI assistants.**
 
 [![PyPI](https://img.shields.io/pypi/v/sam-faces)](https://pypi.org/project/sam-faces/)
-[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 Give your AI assistant a real face memory. Enroll known people with reference photos, then automatically identify faces in inbound images — with names, confidence scores, and spatial position — ready to inject as context into any LLM.
@@ -18,7 +18,7 @@ pip install sam-faces
 
 The `sam-faces` command is added to your PATH automatically.
 
-**Requirements:** Python 3.9+ with build tools (for dlib compilation):
+**Requirements:** Python 3.10+ with build tools (for dlib compilation):
 - Ubuntu/Debian: `sudo apt install cmake build-essential`
 - macOS: `xcode-select --install`
 
@@ -35,10 +35,10 @@ Output:
 {
   "face_count": 2,
   "faces": [
-    {"name": "Jane Smith", "confidence": 0.646, "position_desc": "middle"},
-    {"name": "John Smith", "confidence": 0.571, "position_desc": "middle-left"}
+    {"name": "Jane Smith", "confidence": 0.646, "center": [220, 330], "position_desc": "middle-left"},
+    {"name": "John Smith", "confidence": 0.571, "center": [920, 310], "position_desc": "middle-right"}
   ],
-  "llm_context": "2 faces detected: Jane Smith (middle, 64%); John Smith (middle-left, 57%)."
+  "llm_context": "2 faces detected: Jane Smith (at 22% left, 33% down, 64% confidence); John Smith (at 92% left, 31% down, 57% confidence)."
 }
 ```
 
@@ -54,6 +54,33 @@ sam-faces enroll --name "Jane Smith" --photo photo.jpg
 sam-faces list
 ```
 
+## Python API
+
+You can also use sam-faces as a library inside your Python scripts or agents:
+
+```python
+from sam_faces import identify, enroll, list_people
+
+# Identify faces in a photo
+result = identify("photo.jpg")
+print(result["llm_context"])
+# → "2 faces detected: Jane Smith (at 22% left, 33% down, 64% confidence); ..."
+
+# Enroll a new person
+enroll("Jane Smith", "photo.jpg", note="birthday party")
+
+# List all enrolled people
+for person in list_people():
+    print(f"{person['name']}: {person['encoding_count']} encodings")
+```
+
+### Lazy imports
+
+The package uses lazy loading for heavy vision dependencies. Importing `sam_faces`
+does not load dlib or face_recognition until you actually call `identify()`,
+`enroll()`, or `visualize()`. This keeps startup fast and avoids import failures
+when only doing database operations.
+
 ## For OpenClaw Agents
 
 When installed as an OpenClaw skill, sam-faces **automatically processes every inbound image**:

SKILL.md

@@ -11,7 +11,7 @@ metadata:
     "openclaw":
       {
         "emoji": "👤",
-        "requires": { "bins": ["python3"] },
+        "requires": { "bins": ["sam-faces"] },
         "install":
           [
             {
@@ -115,6 +115,6 @@ sam-faces unknowns
 - Database: `{workspaceDir}/faces/people.db`
 - Unknown face crops: `{workspaceDir}/faces/unknown/`
 - Face crop thumbnails (audit trail): `{workspaceDir}/faces/crops/`
-- Requires Python 3.9+ and build tools (cmake, C++ compiler) for dlib.
+- Requires Python 3.10+ and build tools (cmake, C++ compiler) for dlib.
   - On Ubuntu/Debian: `sudo apt install cmake build-essential`
   - On macOS: `xcode-select --install`

pyproject.toml

@@ -8,26 +8,27 @@ version = "1.0.0"
 description = "Face recognition and identity memory for AI assistants"
 readme = "README.md"
 license = {text = "MIT"}
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 authors = [
-    {name = "Sam Cox", email = "sam@jasonacox.com"}
+    {name = "Sam Cox"},
 ]
 keywords = ["face-recognition", "ai", "agent", "identity", "memory", "openclaw"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Operating System :: OS Independent",
 ]
 dependencies = [
     "face-recognition>=1.3.0",
     "Pillow>=9.0.0",
     "numpy>=1.21.0",
+    "setuptools>=40.0.0",
 ]
 
 [project.optional-dependencies]
@@ -36,6 +37,7 @@ dev = [
     "black",
     "build",
     "twine",
+    "setuptools>=40.0.0",
 ]
 
 [project.scripts]
@@ -49,3 +51,9 @@ Repository = "https://github.com/jasonacox-sam/sam-faces"
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["sam_faces*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "test_*.py"
+python_classes = "Test*"
+python_functions = "test_*"

sam_faces/__init__.py

@@ -1,19 +1,71 @@
-#!/usr/bin/env python3
 """
-sam_faces/__init__.py — Face recognition and identity memory for AI assistants.
+sam-faces — Face recognition and identity memory for AI assistants.
 
-Enroll known people with reference photos, then automatically identify faces
-in inbound images — with names, confidence scores, and an llm_context string
-ready to inject into any LLM prompt. 100% local, no cloud APIs.
+This package provides local face recognition capabilities for OpenClaw agents:
+- Enroll known people with reference photos
+- Identify faces in inbound images with confidence scores
+- Generate llm_context strings for enriched image descriptions
+- Draw bounding boxes and labels on photos for visualization
+
+All operations run 100% locally via dlib/face_recognition. No cloud APIs.
+
+Schema (SQLite):
+  people(id, name, created_at)
+  encodings(id, person_id, vector BLOB, note, added_at, crop_path)
+  unknown_candidates(id, image_path, face_crop_path, detected_at, resolved, resolved_as)
+
+Authors:
+  - Sam Cox (https://github.com/jasonacox-sam)
+  - Jason Cox (https://github.com/jasonacox)
 """
 
 __version__ = "1.0.0"
-__author__ = "Sam Cox <sam@jasonacox.com>"
+__author__ = "Sam Cox (https://github.com/jasonacox-sam), Jason Cox (https://github.com/jasonacox)"
+
+# Lazy imports - only load heavy dependencies when needed
+# Importing face_recognition at module load time triggers dlib init,
+# which can fail if pkg_resources is missing (Python 3.13+ without setuptools)
+
+
+def _lazy(name):
+    """Lazy module loader - imports on first attribute access."""
+    import importlib
+    return importlib.import_module(f"sam_faces.{name}")
 
+
+# Database operations are lightweight (SQLite only) - safe to import eagerly
 from .database import init_db, get_all_encodings, add_person, add_encoding
 from .database import find_person_by_name, list_people, add_unknown
-from .identify import identify, DEFAULT_THRESHOLD
-from .enroll import enroll
+
+# Heavy vision imports are deferred until actually used
+identify = None
+enroll = None
+visualize = None
+DEFAULT_THRESHOLD = 0.55
+
+
+def __getattr__(name):
+    """Lazy load heavy vision modules on first access."""
+    global identify, enroll, visualize, DEFAULT_THRESHOLD
+    if name == "identify":
+        from .identify import identify as _identify, DEFAULT_THRESHOLD as _thresh
+        identify = _identify
+        DEFAULT_THRESHOLD = _thresh
+        return identify
+    if name == "enroll":
+        from .enroll import enroll as _enroll
+        enroll = _enroll
+        return enroll
+    if name == "visualize":
+        from .visualize import visualize as _viz
+        visualize = _viz
+        return visualize
+    if name == "DEFAULT_THRESHOLD":
+        from .identify import DEFAULT_THRESHOLD as _thresh
+        DEFAULT_THRESHOLD = _thresh
+        return DEFAULT_THRESHOLD
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
 
 __all__ = [
     "init_db",
@@ -25,6 +77,7 @@
     "add_unknown",
     "identify",
     "enroll",
+    "visualize",
     "DEFAULT_THRESHOLD",
     "__version__",
 ]

sam_faces/cli.py

@@ -1,3 +1,16 @@
+"""
+sam_faces/cli.py — Unified command-line interface for sam-faces.
+
+Subcommands:
+  identify    — Detect and name faces in a photo
+  enroll      — Add a face to the people database
+  list        — Show all enrolled people
+  unknowns    — Review unresolved unknown faces
+  visualize   — Draw bounding boxes on detected faces
+
+Backward compatibility: sam-faces --photo image.jpg routes to identify.
+"""
+
 import argparse
 import json
 import sys
@@ -8,16 +21,20 @@
 from .enroll import enroll
 
 
+from .visualize import visualize
+
+
 def main():
     parser = argparse.ArgumentParser(
         prog="sam-faces",
         description="Face recognition and identity memory for AI assistants"
     )
+    parser.add_argument("--photo", dest="legacy_photo", help="Legacy: identify faces in a photo (backward compat)")
     sub = parser.add_subparsers(dest="command", help="Command to run")
 
     # identify
-    p_identify = sub.add_parser("identify", aliases=["--photo"], help="Identify faces in a photo")
-    p_identify.add_argument("photo", help="Path to photo")
+    p_identify = sub.add_parser("identify", help="Identify faces in a photo")
+    p_identify.add_argument("photo", nargs="?", help="Path to photo")
     p_identify.add_argument("--threshold", type=float, default=DEFAULT_THRESHOLD,
                               help=f"Match threshold (default: {DEFAULT_THRESHOLD})")
     p_identify.add_argument("--no-save-unknowns", action="store_true",
@@ -39,8 +56,23 @@ def main():
     # unknowns
     p_unknowns = sub.add_parser("unknowns", help="List unresolved unknown faces")
 
+    # visualize
+    p_viz = sub.add_parser("visualize", help="Draw bounding boxes on detected faces")
+    p_viz.add_argument("photo", help="Path to photo")
+    p_viz.add_argument("--output", "-o", help="Output path (default: <photo>_faces.jpg)")
+    p_viz.add_argument("--threshold", type=float, default=DEFAULT_THRESHOLD,
+                         help=f"Match threshold (default: {DEFAULT_THRESHOLD})")
+
     args = parser.parse_args()
 
+    # Handle legacy --photo flag
+    if args.legacy_photo and not args.command:
+        args.command = "identify"
+        args.photo = args.legacy_photo
+        args.threshold = DEFAULT_THRESHOLD
+        args.no_save_unknowns = False
+        args.no_crops = False
+
     if not args.command:
         parser.print_help()
         sys.exit(1)
@@ -81,6 +113,13 @@ def main():
         for u in unknowns:
             print(f"  [{u['id']}] {u['detected_at'][:10]}  {u['image_path']}")
 
+    elif args.command == "visualize":
+        result = visualize(args.photo, args.output, args.threshold)
+        if result.get("error"):
+            print(f"Error: {result['error']}", file=sys.stderr)
+            sys.exit(1)
+        print(json.dumps(result, indent=2))
+
 
 if __name__ == "__main__":
     main()