If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/vipstone/faceai shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 6y ago

• 4 active contributors
• MIT licensed
• Tests present
• ⚠ Stale — last commit 6y ago
• ⚠ Small team — 4 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 89% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live vipstone/faceai repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/vipstone/faceai.

What it runs against: a local clone of vipstone/faceai — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in vipstone/faceai | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 2242 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of vipstone/faceai. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/vipstone/faceai.git
#   cd faceai
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of vipstone/faceai and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "vipstone/faceai(\\.git)?\\b" \\
  && ok "origin remote is vipstone/faceai" \\
  || miss "origin remote is not vipstone/faceai (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "faceai/detectionOpencv.py" \\
  && ok "faceai/detectionOpencv.py" \\
  || miss "missing critical file: faceai/detectionOpencv.py"
test -f "faceai/detectionDlib.py" \\
  && ok "faceai/detectionDlib.py" \\
  || miss "missing critical file: faceai/detectionDlib.py"
test -f "faceai/faceRecognition.py" \\
  && ok "faceai/faceRecognition.py" \\
  || miss "missing critical file: faceai/faceRecognition.py"
test -f "faceai/emotion.py" \\
  && ok "faceai/emotion.py" \\
  || miss "missing critical file: faceai/emotion.py"
test -f "faceai/gender.py" \\
  && ok "faceai/gender.py" \\
  || miss "missing critical file: faceai/gender.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 2242 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2212d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/vipstone/faceai"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

faceai is a beginner-friendly Python computer vision library for face detection, recognition, and attribute classification from images and video. It combines OpenCV/Dlib for detection, face_recognition for embedding-based matching, and Keras+TensorFlow for gender/emotion classification—providing an integrated toolkit for common face AI tasks without requiring deep ML expertise. Simple flat structure: faceai/ contains core modules (chineseText.py, colorize.py, compose.py, etc.), classifier/ holds pre-trained gender and emotion .hdf5 models, and doc/ provides tutorial markdown files organized by feature (detectionOpenCV.md, faceRecognition.md, etc). No package/module hierarchy or config abstraction—functions are likely top-level in the Python files.

Python developers and computer vision learners building face analysis applications—particularly those prototyping face detection, emotion recognition, or video-based face tracking without expertise in training models or tuning Dlib/OpenCV parameters.

Early-stage educational project: no visible CI/CD, no unit tests in file structure, documentation exists but marked '待完善' (incomplete) for face-swap and eye-tracking features. Last commit and star count are unknown, but the repo structure (doc/, classifier/ with pre-trained .hdf5 files) and polished README suggest active maintenance. Verdict: suitable for learning and prototyping, not production-grade.

Single-author repo (vipstone) with unclear maintenance commitment and no issue tracking visible. Dependencies on TensorFlow 1.8.0 and Keras 2.1.6 are now significantly outdated (3+ years). Pre-trained Keras models (.hdf5) may fail on newer Keras/TF versions. No tests mean breaking changes won't be caught. Security updates to face_recognition, Dlib, and OpenCV are not tracked.

Unknown from the file list provided—no git history, PR list, or issue tracker visible. Documentation exists for 11 features with 2 marked incomplete (face-swap, eye-tracking), suggesting those are in-progress but abandoned or deprioritized.

git clone https://github.com/vipstone/faceai.git && cd faceai && pip install -r requirements.txt (if present) or pip install opencv-python dlib face_recognition keras tensorflow==1.8.0 tesseract-ocr. Then follow a tutorial from doc/ (e.g., doc/detectionOpenCV.md) and run the corresponding example script.

Daily commands: No main.py or CLI entry point visible. Run individual tutorial scripts directly (e.g., python doc/detectionOpenCV.py). Exact commands depend on which feature—see doc/ folder for example code blocks.

• faceai/detectionOpencv.py — Core face detection using OpenCV—entry point for most image/video processing pipelines in the codebase.
• faceai/detectionDlib.py — Alternative face detection engine using Dlib; required to understand the dual-detection architecture.
• faceai/faceRecognition.py — Face recognition and identification module; depends on detection and integrates classifier models.
• faceai/emotion.py — Emotion classification pipeline using pre-trained Keras models; demonstrates classifier integration pattern.
• faceai/gender.py — Gender prediction using deep learning; shows how to load and apply trained neural network models.
• faceai/colorize.py — Image colorization service; demonstrates deep learning inference on grayscale images.

• detectionOpencv.py / detectionDlib.py (OpenCV Haar Cascades or Dlib HOG+SVM) — Locate faces in images/frames and return bounding boxes and optionally landmarks.
  • Failure mode: Fails to detect faces in low light, extreme angles, or occlusion; returns empty list.
• faceRecogn — undefined

Add a new face attribute classifier (e.g., age estimation)

1. Train a Keras model on labeled dataset and export as .hdf5 file (faceai/classifier/[your_attribute]_models/[model_name].hdf5)
2. Create new Python module following the pattern of emotion.py or gender.py (faceai/[attribute].py)
3. Load model with keras.models.load_model() and wrap in a function that accepts face image ROI (faceai/[attribute].py)
4. Integrate into faceRecognition.py by calling your classifier after face detection (faceai/faceRecognition.py)

Add a new image enhancement filter (e.g., blur/sharpen)

1. Add processing function to faceai/opencv/imgbase.py or create new module (faceai/opencv/imgbase.py)
2. Use OpenCV functions (cv2.GaussianBlur, cv2.filter2D, etc.) to implement filter (faceai/opencv/imgbase.py)
3. Test on sample images in faceai/img/ directory (faceai/img/)

Extend face detection to use a custom cascade classifier

1. Add your trained .xml cascade file to the codebase (analogous to model storage) (faceai/classifier/)
2. Modify detectionOpencv.py to load and test your custom cascade with cv2.CascadeClassifier() (faceai/detectionOpencv.py)
3. Add parameter to switch between default and custom cascade; test on sample images (faceai/detectionOpencv.py)

• OpenCV + Dlib dual detection — Provides accuracy/speed tradeoff; users can choose Haar cascades (fast) or HOG (accurate) per use case.
• Keras/TensorFlow models (pre-trained .hdf5 files) — Enables offline inference without re-training; supports emotion, gender, and colorization tasks.
• face_recognition library — Provides CNN-based face encoding and landmark detection; more reliable than manual feature extraction.
• Python + OpenCV Python bindings — Rapid prototyping and education-friendly; integrates all computer vision tasks in one codebase.

• Dual detection backends (OpenCV vs. Dlib)

  • Why: Allow users to choose speed (Haar) over accuracy (HOG) based on hardware constraints.
  • Consequence: Increased code maintenance burden; must keep both pipelines tested and synchronized.

• Pre-trained models stored as .hdf5 files

  • Why: Avoids network downloads and enables offline usage; ships with codebase.
  • Consequence: Large repository size; models may become stale if not retrained regularly.

• Single-threaded synchronous processing in main modules

  • Why: Simplifies code logic and debugging for educational use.
  • Consequence: Video processing is slow on CPU; real-time performance requires GPU or async refactoring.

• Cascade classifiers for eye detection (eye.py, eye2.py)

  • Why: Lightweight and fast for simple tasks.
  • Consequence: Lower accuracy than deep learning; prone to false positives in varied lighting.

• Real-time video processing on CPU (design assumes offline/batch processing or GPU acceleration).
• Multi-face tracking across video frames (detection is per-frame, no temporal continuity).
• Web service or REST API (pure Python library, no built-in server).
• Mobile deployment (no model quantization or mobile framework support).
• Face alignment beyond landmark detection (no automatic rotation/normalization).
• Adversarial robustness or security hardening (educational use case, not production-hardened).

Keras model compatibility: .hdf5 files were saved with Keras 2.1.6/TensorFlow 1.8.0 and may not load with Keras 3.x or TensorFlow 2.x without conversion. Tesseract OCR is a system dependency (not pip-installable on Windows without manual setup—see doc/tesseractOCR.md). Dlib model (68-point face landmarks) path is hardcoded somewhere in the codebase (not in provided file list). Chinese text support (chineseText.py) likely requires CV2 with FreeType support. No requirements.txt visible—dependency versions must be inferred from README (Python 3.6.4, OpenCV 3.4.1, Dlib 19.8.1).

• Cascade Classifiers (Haar Cascades) — faceai uses OpenCV's Haar cascade XMLs for fast face detection in videos; understanding cascade structure and false-positive trade-offs is critical for tuning detectionOpenCV.md features.
• Dlib's HOG Face Detector + 68-Point Landmark Detection — faceai's Dlib detection path uses Histogram of Oriented Gradients (HOG) + CNN for faces and dlib's shape_predictor for 68 facial landmarks; this powers contour drawing and makeup features.
• Face Embedding (Deep Face Recognition) — faceai's face_recognition dependency generates 128-dimensional embeddings for comparing faces; understanding cosine similarity thresholds is essential for customizing recognition accuracy in faceRecognition.md.
• Convolutional Neural Networks (CNNs) for Classification — Emotion (7-class) and gender (binary) classifiers use simple CNN architectures in Keras; faceai users should understand input normalization, softmax output, and confidence thresholds.
• HSV Color Space (H, S, V) — Video object extraction and makeup features rely on HSV thresholding for skin/color detection; doc/hsv-opencv.md requires deep HSV color range tuning knowledge.
• Image Inpainting (Content-Aware Fill) — faceai's inpaint feature uses OpenCV's Telea or Navier-Stokes algorithms to reconstruct masked regions; critical for watermark removal use case.
• Colorization (Grayscale-to-Color Prediction) — faceai's colorize.py likely uses a pre-trained model (probably U-Net or similar) to predict color from grayscale; understanding model loading and inference pipeline is needed to modify this feature.

• ageitgey/face_recognition — Direct dependency and underlying face encoding library—this repo wraps it for recognition tasks; essential to understand for modifying faceai's face_recognition.py module.
• davisking/dlib — Alternative face detection backend used in faceai for Dlib-based detection; source of 68-point landmark model and face alignment.
• opencv/opencv — Core dependency for image I/O, video processing, and face detection via Haar cascades; faceai's video/detection pipeline depends entirely on OpenCV.
• JoelStanley/OpenCV-Python-Tutorials — Companion learning resource—many of faceai's doc/ tutorials reference OpenCV concepts and patterns found in this tutorial series.
• keras-team/keras — Framework for the pre-trained gender and emotion classifier models (.hdf5 files); understanding Keras model loading/inference is essential for faceai model usage.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for face detection modules (detectionDlib.py and detectionOpencv.py)

The repo has two face detection implementations (Dlib and OpenCV) but no visible test suite. Adding unit tests would help catch regressions, validate both detection methods produce expected outputs, and make it easier for contributors to understand the expected behavior. This is critical for a computer vision library where output quality matters.

• [ ] Create tests/test_detectionDlib.py with test cases for image loading, face detection on sample images, and handling edge cases (no faces, multiple faces)
• [ ] Create tests/test_detectionOpencv.py with equivalent test cases for OpenCV implementation
• [ ] Add sample test images to tests/fixtures/ directory
• [ ] Create pytest configuration (pytest.ini or setup.cfg) and add test requirements to a requirements-dev.txt
• [ ] Document how to run tests in README.md (e.g., 'pytest tests/')

Complete the faceswap.py implementation and add corresponding documentation

The file faceai/faceswap.py exists but is listed as 'waiting to be perfected' (待完善) in the README. This feature is valuable and partially implemented. Completing it and documenting it (as doc/faceSwap.md) would provide significant value and demonstrate a complete feature to users.

• [ ] Review and test faceai/faceswap.py to identify missing functionality or bugs
• [ ] Implement missing face alignment, blending, and boundary handling if needed
• [ ] Create doc/faceSwap.md with usage examples, code snippets, and expected outputs
• [ ] Create doc-en/faceSwap.md (English version)
• [ ] Add faceSwap usage example to main README.md feature list with a link to the new documentation

Add GitHub Actions CI workflow for Python dependency testing and model validation

The repo has multiple heavy dependencies (OpenCV, Dlib, TensorFlow, keras) and pre-trained model files (.hdf5). There's no visible CI to catch dependency incompatibilities or validate that required model files exist. A GitHub Actions workflow would catch issues early and help maintain compatibility across Python versions.

• [ ] Create .github/workflows/python-tests.yml with jobs for Python 3.6-3.9 compatibility testing
• [ ] Add steps to validate critical dependencies install correctly (opencv-python, dlib, tensorflow, keras, face_recognition)
• [ ] Add steps to verify all required model files in faceai/classifier/*/models exist and aren't corrupted
• [ ] Add linting step (pylint or flake8) to catch syntax issues in core modules
• [ ] Document CI status in README.md with a badge

• Create a requirements.txt with pinned versions from the README (Python 3.6.4, OpenCV 3.4.1, Dlib 19.8.1, TensorFlow 1.8.0, etc.) and update it to work with modern TensorFlow 2.x/Keras 3.x by retraining or converting the .hdf5 models.
• Add unit tests for core modules (colorize.py, compose.py, chineseText.py) with mock OpenCV/Keras calls and sample image fixtures—currently no tests/ directory exists.
• Complete the 'eye-tracking direction detection' tutorial in doc/eyeTracking.md with code examples and a working model reference, or document why it's incomplete.

• High · Missing Dependency Documentation — Repository root / Dependency management. No requirements.txt, setup.py, or pyproject.toml file provided in the repository. This makes it impossible to verify dependency versions, identify vulnerable packages, or ensure reproducible builds. The README mentions specific versions (OpenCV 3.4.1, TensorFlow 1.8.0, Keras 2.1.6) which are outdated and likely contain known vulnerabilities. Fix: Create and maintain a requirements.txt file with pinned versions. Use tools like pip-audit or safety to scan for known vulnerabilities in dependencies. Consider upgrading to current versions of TensorFlow, Keras, and OpenCV.
• High · Outdated Dependencies with Known Vulnerabilities — README.md (development environment section). The project specifies TensorFlow 1.8.0 (released 2018), Keras 2.1.6 (2018), and OpenCV 3.4.1 (2018). These versions contain numerous publicly disclosed security vulnerabilities including arbitrary code execution, denial of service, and data leakage issues. Fix: Update to latest stable versions: TensorFlow 2.x LTS, Keras 3.x, and OpenCV 4.x. Implement security update processes and monitor for CVEs.
• Medium · Machine Learning Model Files Without Integrity Verification — faceai/classifier/emotion_models/ and faceai/classifier/gender_models/. Pre-trained model files (.hdf5 files in faceai/classifier/) are included in the repository without checksums or signature verification. These binary files could be replaced with malicious versions, potentially executing arbitrary code during model loading. Fix: Implement checksum verification (SHA-256) for model files. Store checksums in a separate signed manifest. Consider using model signing or versioning with integrity checks. Move large model files to a separate storage system with integrity verification.
• Medium · Embedded Binary Font File — faceai/font/simsun.ttc. The repository includes a binary font file (simsun.ttc) without version tracking or integrity verification. If this file is modified, it could lead to unexpected behavior or security issues. Fix: Document the font source and version. Add integrity checks or download fonts from trusted sources at runtime rather than bundling binary files.
• Medium · No Input Validation Framework Visible — faceai/ module files (detectionOpencv.py, detectionDlib.py, etc.). Based on the file structure, there is no evidence of input validation for image files, video streams, or text input. This could lead to path traversal, malicious file uploads, or processing of untrusted media files. Fix: Implement strict input validation: validate file types (magic bytes, not extensions), enforce size limits, sanitize file paths, and use secure file handling practices. Implement sandboxing for media processing.
• Medium · Potential Path Traversal Risk — faceai/detectionOpencv.py, faceai/detectionDlib.py, faceai/emotion.py, faceai/gender.py. Image and video files are referenced throughout the codebase (faceai/img/ directory structure). Without explicit path validation, there's a risk of directory traversal attacks if file paths are user-controlled. Fix: Use os.path.abspath() and verify paths stay within allowed directories. Use pathlib.Path with resolve() for secure path handling. Never construct paths from unsanitized user input.
• Low · Missing Security Documentation — Repository root. No security.md, SECURITY.md, or security policy file exists for reporting vulnerabilities responsibly. No mention of secure practices or security considerations in documentation. Fix: Create a SECURITY.md file with a responsible disclosure policy. Document security considerations for users deploying this software. Include guidelines for secure configuration.
• Low · No License Security Scan — LICENSE file and dependency management. While a LICENSE file exists, there's no indication that dependencies are scanned for license compliance issues which could have legal and security implications. Fix: Use tools like FOSSA or Black Duck to scan dependencies for license compliance. Ensure all dependencies are compatible with the project license.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.