Athena OCR Admin Prototype

This public repository contains a local prototype for matching Chinese package-label recipient information to an office directory.

package-label image
-> OCR text regions
-> spatial candidate extraction
-> recipient/contact/address evidence
-> directory matching
-> unique match, confirmation, or manual review

The OCR prototype is one component of a larger office-delivery robot project. It does not automatically dispatch or control a robot.

Public And Internal Documentation

This repository is the public, privacy-safe source for the general OCR prototype:

• source code and synthetic data
• installation and local startup
• tests and technical design notes
• generic configuration examples

Company employees continuing the physical Athena robot deployment should also use the internal Feishu handoff document. That document requires company access and is the source for private operational material such as MU access, SLAMWARE networking, real maps, service recovery, office-specific address hints, and the real employee directory.

See Documentation Index for the full document map and the boundary between public and internal material.

Included

• office-admin-ui/: browser Admin UI and OCR prototype.
• packageMatcher.js: parsing, spatial candidate ranking, address evidence, and directory matching.
• ocr_server.py: adaptive PaddleOCR pipeline, Chinese Tesseract fallback, and HEIC/HEIF conversion through FFmpeg.
• address-hints.sample.json: privacy-safe example for deployment-specific address evidence.
• docs/tech-blog/: evidence-based design and evaluation documentation.

Privacy Boundary

The public copy intentionally excludes or replaces:

• real employee names and phone numbers
• real package photos
• real office addresses
• private robot and MU addresses
• office maps and map cache data
• passwords, tokens, and service environment files

real-directory.json contains synthetic demonstration records. Never commit a real directory or address-hints.local.json; both belong in company-controlled storage described by the internal handoff.

Prerequisites

The verified development environment uses Python 3.9. Other supported Python versions may work, but Python 3.9 is the safest reproduction target for the pinned PaddleOCR stack.

On macOS:

brew install python@3.9 tesseract tesseract-lang ffmpeg

Node.js 18 or newer is needed only for the matcher tests.

Clean Installation

git clone https://github.com/TTdragoAlex/athena-ocr-admin-prototype.git
cd athena-ocr-admin-prototype/office-admin-ui
PYTHON_BIN=python3.9 ./setup_ocr_env.sh
./start_admin_ui.sh

Open:

http://127.0.0.1:8765

start_admin_ui.sh starts the OCR API on 127.0.0.1:8767 when needed and then starts the static Admin UI on 127.0.0.1:8765.

Check OCR health:

curl -fsS http://127.0.0.1:8767/ocr_health

PaddleOCR may download model files on first use. The advanced orientation and document-unwarping attempt is optional: if its models are unavailable, the pipeline records a warning and continues with standard PaddleOCR, rotations, image enhancement, and Chinese Tesseract.

Address Configuration

The matcher ships with synthetic address hints. To use deployment-specific address evidence:

cp address-hints.sample.json address-hints.local.json

Edit the local file with relevant building, road, floor, or unit variants. address-hints.local.json is ignored by Git and loaded automatically by the UI. Address evidence ranks likely recipient regions; it is not treated as a person's identity.

OCR Behavior

The server starts with a fast standard PaddleOCR pass. If the result lacks useful recipient/contact evidence, it can try:

• EXIF-corrected orientation
• Paddle document orientation, unwarping, and text-line orientation
• 90, 180, and 270 degree rotations
• OpenCV/Pillow upscale, contrast, denoise, and sharpening
• Chinese Tesseract fallback

The browser runs each OCR attempt through the same package matcher and prefers:

• a unique directory match
• surname plus phone-last-four evidence
• recipient/contact or recipient-anchor regions
• address-supported regions
• stronger candidate scores

Covered information is never invented. A unique phone suffix can identify one directory entry; ties require confirmation; no usable match remains manual review.

Tests

cd office-admin-ui
npm test
python3 -m py_compile ocr_server.py

The tests use synthetic names, phone suffixes, addresses, and OCR boxes.

Static UI Only

This starts the webpage without photo OCR:

python3 -m http.server 8765

For the Photo OCR button, also run ./start_ocr_server.sh, or use ./start_admin_ui.sh.

Production Notes

This is a working local prototype, not a production service. Before deployment:

• add authentication and access controls
• store private directory/address configuration outside the public repository
• build a representative evaluation dataset
• measure false positives, false negatives, confirmation rate, and latency
• define a validated human-confirmation and robot-dispatch policy
• add monitoring and durable server-side storage