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/NMAC427/SwiftOCR 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.

GO — Healthy across all four use cases

• 20 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 5y ago
• ⚠ Concentrated ownership — top contributor handles 76% of recent commits

_{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 NMAC427/SwiftOCR repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/NMAC427/SwiftOCR.

What it runs against: a local clone of NMAC427/SwiftOCR — 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 NMAC427/SwiftOCR | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 2004 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of NMAC427/SwiftOCR. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/NMAC427/SwiftOCR.git
#   cd SwiftOCR
#
# 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 NMAC427/SwiftOCR and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 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"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 2004 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1974d)"
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/NMAC427/SwiftOCR"
  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).

SwiftOCR is a fast neural-network-based OCR library written in Swift, optimized for recognizing short alphanumeric codes (like gift card numbers or serial codes) from images. It uses connected-component labeling to segment characters and feeds them into a neural network for recognition, achieving 97.7% accuracy on alphanumeric codes in ~0.08 seconds per image. Single-target Swift framework with example apps: example/OS X/ contains two Xcode projects (Example and Debug variants) plus a Training project for model generation. The main library code resides in the root-level Swift source (inferred from the 1.7MB Swift total), with CocoaPods packaging via SwiftOCR.podspec.

iOS and macOS developers building apps that need to extract short alphanumeric codes (e.g., gift cards, inventory barcodes, license plates) who want a simpler, faster alternative to Tesseract OCR for this specific use case.

⚠️ Deprecated and unmaintained — the README explicitly states 'This Project is deprecated and no longer gets maintained' and recommends Apple's Vision framework instead. The codebase is complete (1.7MB of Swift code), but receives no active development.

High risk for new projects: the project is officially deprecated with maintainers recommending Apple's Vision framework as a replacement. Single-author maintenance (nicolas), no visible CI/CD in file list, and no test directory shown in top 60 files suggest limited test coverage. Using this in production would be betting against a dead project when Apple's own solution is now recommended.

Nothing — the project is deprecated. No active work, no recent commits indicated in the file structure, and the README is a deprecation notice pointing users to Vision framework.

git clone https://github.com/NMAC427/SwiftOCR.git
cd SwiftOCR
pod install  # if integrating via CocoaPods
open 'example/OS X/SwiftOCR Example OS X/SwiftOCR Example OS X.xcodeproj'

Then examine example/OS X/SwiftOCR Example OS X/ViewController.swift to see the 6-line usage example.

Daily commands: Open the .xcodeproj file in Xcode and build/run. The example app loads test images from example/OS X/SwiftOCR Example OS X/images/ (Test 1.png, Test 2.png). No command-line build tool indicated; requires Xcode and macOS/iOS deployment target.

• [example/OS X/SwiftOCR Example OS X/SwiftOCR Example OS X/ViewController.swift](https://github.com/NMAC427/SwiftOCR/blob/master/example/OS X/SwiftOCR Example OS X/SwiftOCR Example OS X/ViewController.swift): Demonstrates the 6-line usage pattern: let swiftOCRInstance = SwiftOCR(); swiftOCRInstance.recognize(myImage) { recognizedString in ... } — the canonical API entry point
• SwiftOCR.podspec: CocoaPods package definition; defines version, dependencies, and module structure for distribution to iOS/macOS projects
• [example/OS X/SwiftOCR Training/SwiftOCR Training.xcodeproj](https://github.com/NMAC427/SwiftOCR/blob/master/example/OS X/SwiftOCR Training/SwiftOCR Training.xcodeproj): Separate Xcode project for training neural network models — shows how to generate trained weights/models for character recognition
• [example/OS X/SwiftOCR Example OS X/images/](https://github.com/NMAC427/SwiftOCR/blob/master/example/OS X/SwiftOCR Example OS X/images/): Test images (Test 1.png, Test 2.png) used to validate OCR accuracy — good reference for expected input format (alphanumeric codes on single lines)
• README.md: Contains deprecation notice, architecture overview (thresholding → connected-component labeling → neural network), performance benchmarks vs Tesseract, and the rationale for choosing this over alternatives

1. Neural network training: see example/OS X/SwiftOCR Training/ — the Training project generates trained models. 2. Character recognition logic: examine the main Swift library source (path not fully listed, but inferred as root-level or in a Sources/ directory). 3. Image preprocessing: modify thresholding and connected-component labeling in the core library. 4. Test integration: add tests alongside the example projects (no Tests/ directory visible, so this is a gap).

1. Deprecated & unsupported: README explicitly discourages new usage in favor of Apple Vision framework — no bug fixes or feature work will happen. 2. Build config matters: README states 'set your Build Configuration to Release' for performance; Debug builds will be dramatically slower. 3. Training data required: The neural network must be trained on your specific character set using the Training project; default model only supports alphanumeric uppercase. 4. No test coverage visible: No Tests/ or test files in the top 60 file list — unclear what QA exists. 5. Xcode-only: No CocoaPods/SPM setup script shown; requires manual Xcode project configuration.

• Connected-Component Labeling (CCL) — SwiftOCR's core character segmentation technique — it identifies and isolates individual characters in an image before feeding them to the neural network; understanding CCL is essential to modify or debug character extraction
• Image Thresholding / Binarization — The first step in SwiftOCR's pipeline converts input images to black-and-white; this preprocessing directly impacts accuracy and understanding threshold tuning is critical for handling different lighting/image quality
• Neural Network (feedforward / multi-layer perceptron) — SwiftOCR implements a custom hand-written neural network (not Core ML) in pure Swift for character classification — understanding forward pass, activation functions, and weight matrices is needed to modify or retrain it
• Model Training & Weight Persistence — The separate Training project generates trained neural network weights; understanding how to serialize/load these weights and retrain on custom datasets is essential for supporting new character sets (lowercase, symbols)
• CocoaPods Package Distribution — SwiftOCR is distributed as a CocoaPods pod (see SwiftOCR.podspec); understanding .podspec files and CocoaPods integration is required to contribute back or fork the project
• Image Feature Extraction — Converting segmented characters into numeric vectors for neural network input requires feature extraction (pixel matrices, gradients, etc); this is a crucial bridge between image processing and ML in SwiftOCR

• apple/vision — Apple's official recommended replacement — modern, fast, and built into iOS/macOS; SwiftOCR's own README redirects users here
• tesseract-ocr/tesseract — The main alternative OCR engine; SwiftOCR was benchmarked against it (97.7% accuracy vs 45.2% on alphanumeric codes, but Tesseract excels at general text)
• hollance/CoreMLHelpers — Shows how to integrate Core ML models into Swift apps — relevant if rebuilding SwiftOCR's neural network as a Core ML model instead of hand-written Swift
• tzmartin/OpenCV — OpenCV Swift bindings for advanced image processing; SwiftOCR's thresholding and connected-component labeling could be replaced with OpenCV for more robust preprocessing
• Alamofire/Alamofire — Not directly related, but common dependency in iOS projects using CocoaPods that might also integrate SwiftOCR

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.

Migrate iOS example from incomplete 'SwiftOCR Camera' to functional app

The iOS example directory (example/iOS/SwiftOCR Camera) appears incomplete compared to the well-structured OS X examples. Since this is a deprecated but maintained library, providing a complete, working iOS example with camera integration would be valuable for users who haven't migrated to Vision framework yet. This would demonstrate real-world usage patterns.

• [ ] Complete the iOS camera example app structure in example/iOS/SwiftOCR Camera/
• [ ] Add ViewController.swift with camera permissions and OCR integration
• [ ] Add Info.plist with required privacy keys (NSCameraUsageDescription)
• [ ] Create a storyboard or SwiftUI interface for image capture and OCR display
• [ ] Test against the existing training data to ensure functionality

Add unit tests for character segmentation and neural network accuracy

The repository mentions 'fast and accurate character segmentation' and uses a neural network, but there's no visible test directory. Adding unit tests for the core OCR components (SWIFTOCR class, character segmentation logic, and neural network prediction) would improve code reliability and provide regression testing as the library is maintained.

• [ ] Create Tests/ directory with XCTest targets
• [ ] Add unit tests for character segmentation in the main OCR engine
• [ ] Add accuracy tests comparing neural network output against known training data
• [ ] Test image preprocessing pipeline with various input formats
• [ ] Include integration tests using the example images in example/OS X/SwiftOCR Example OS X/images/

Document training workflow and neural network structure

The README mentions an 'easy to use training class' and the file structure shows a 'SwiftOCR Training' Xcode project, but there's no documentation on how to use it or understand the neural network model. Adding comprehensive documentation would help users understand model capabilities and create their own trained models.

• [ ] Document the SwiftOCR Training app usage in a TRAINING.md file
• [ ] Explain the neural network architecture (layers, input size, output format)
• [ ] Add example code showing how to train a custom model
• [ ] Document the model file format and how models are loaded in the main library
• [ ] Include troubleshooting section for common training issues

• Add unit test coverage for the character segmentation algorithm (connected-component labeling logic) — currently no Tests/ directory visible in the repo structure, making it a major gap for maintenance.
• Document the neural network training pipeline: create a guide with code examples showing how to retrain the model for custom character sets (lowercase, symbols, etc) — the Training project exists but is undocumented in the README beyond a stub.
• Migrate examples to use Apple Vision framework and add a compatibility layer showing SwiftOCR-to-Vision API mapping — this would help users transition off the deprecated library gracefully.

SwiftOCR presents significant security concerns primarily due to its deprecated and unmaintained status. No security patches will be provided for any discovered vulnerabilities. Additionally, user-specific Xcode data files are committed to version control, which may leak developer environment information. The project should not be used in new applications. Existing implementations should migrate to Apple's Vision framework. Overall security posture is poor due to the lack of active maintenance and configuration management issues.

• High · Deprecated Project with No Maintenance — README.md, SwiftOCR.podspec. The project is explicitly marked as deprecated and no longer maintained. This means security vulnerabilities discovered in the codebase will not be patched, and the project will not receive updates to address emerging security threats or compatibility issues with newer Swift/iOS versions. Fix: Migrate to Apple's Vision framework as recommended in the README. If continuation is necessary, fork the project and establish a maintenance plan with regular security audits.
• Medium · User Data in Version Control — example/OS X/*/SwiftOCR*/xcuserdata/, example/iOS/*/xcuserdata/. Multiple Xcode user data files (.xcuserdatad directories, xcschememanagement.plist, Breakpoints_v2.xcbkptlist) are committed to the repository. These may contain sensitive information such as local file paths, debug settings, and user-specific configurations that could leak developer environment details. Fix: Add .xcuserdatad/ and individual user data patterns to .gitignore. Remove these files from git history using git-filter-branch or BFG Repo-Cleaner if sensitive data was exposed.
• Low · Missing Dependency Information — SwiftOCR.podspec, Dependencies section. No package dependency file (Podfile, Cartfile, Package.swift) content was provided for analysis. The podspec file exists but its contents were not included, making it impossible to verify if the project uses known vulnerable dependencies. Fix: Provide complete dependency manifests and regularly audit them using tools like CocoaPods audit or Snyk. Keep all dependencies updated to their latest secure versions.
• Low · No Security Policy or Vulnerability Disclosure Process — Repository root. There is no evidence of a SECURITY.md file or vulnerability disclosure policy in the repository. Given the deprecated status, there is no clear process for reporting security issues. Fix: Although deprecated, consider adding a SECURITY.md file that directs users to migrate to Apple Vision framework and explains that no security patches will be provided.

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.