cto-legends · module specification · infrastructure · v0.2.1
legends-jev: TypeSafe Jev 1.14 Optical Recognition (OCR), Signage & Typed Decision CLI
Zero-dependency Python CLI for TypeSafe Jev 1.14 optical recognition (OCR), storefront signage checks, pixel bounding boxes, and typed UI decisions.
GitHub Repository (https://github.com/avalonreset/legends-jev) · Handoff: cto-legends handoff legends-jev
legends-jev is a zero-dependency Python 3.11+ CLI adapter over the hosted TypeSafe System One model (pinned to jev-1.14.0 at POST /v1/systemone) that provides fast (~150-250ms) typed decision advice (decide), general-purpose optical character recognition and visual grounding (ocr), and Google Business Profile storefront signage verification (signage). Operators and agents supply bounded text observations (up to 16KB / 6,000 evidence characters and 1 to 8 candidates) or 1 to 6 local PNG/JPEG images to receive strictly validated Choice, Score, Noul, and Box primitives—including exact original-image pixel_box coordinates (left, top, right, bottom, width, height, center_x, center_y).
Architecturally, legends-jev enforces a strict separation between optical/semantic observation and desktop or browser actuation: it never captures screens, connects to desktops, navigates browsers, or executes clicks, leaving actuation to legends-shell-kit, legends-chrome-kit, or the operator's chosen automation tool. Before any network call, it runs deterministic preflight gates (rejecting observations older than 120 seconds or more than 5 seconds in the future, empty evidence, or unauthorized/disabled/wrong-surface candidates), automatically normalizes out-of-range screenshots (such as 1920x1080 desktops or small crops) into TypeSafe's required 280..1568 pixel bounds, and maps normalized 0..1 bounding boxes back to original pixel coordinates.
Deterministic Execution Boundary
Why Raw Frontier LLM Prompts Cannot Replace Deterministic Execution
Passing raw desktop screenshots or accessibility dumps to a general-purpose chat LLM for UI control or local SEO signage verification produces uncalibrated free-text guesses, drifted bounding-box math on resized images, and prompt-injection vulnerabilities from untrusted screen text. A raw LLM prompt does not enforce 120-second evidence freshness, validate probability distributions against score legends, or deterministically invert aspect-ratio padding back to native screen pixel coordinates.
- Automatic 280..1568px Image Normalization & Inverse Pixel Mapping: TypeSafe's /v1/systemone vision endpoint requires still PNG/JPEG images within 280..1568 pixels per side and header TypeSafe-Danger-Zone-Images: true. legends-jev parses PNG/JPEG headers, proportionally scales and center-pads out-of-range images (using a pure-Python 8-bit PNG codec, Pillow, or Windows .NET System.Drawing fallback), and runs pixel_box() to invert scale and pad offsets so returned 0..1 boxes map to exact original-image pixel coordinates and center_x/center_y click targets.
- Strict Mathematical Response Validation & Uncertainty Gates: validate_response() verifies that the response model matches pinned jev-1.14.0, checks that choice and score probability distributions sum to 1.0 within tight tolerance, verifies that score equals the expected value of its probability distribution within 0.05, and enforces conservative uncertainty gates (e.g., confidence >= 0.8, insufficient noul <= 0.2, support score >= 1.8 for decide; readability >= 1.2 and goal_supported >= 0.7 for ocr), returning status: operator_fallback whenever any gate fails.
- Offline Preflight & Candidate Eligibility Filtering: preflight() validates the legends-jev/evidence-v1 schema (bounded to 16KB text, 6,000 evidence chars, 1..8 candidates, and data_scope restricted to synthetic, public, or nonsecret-app-metadata) and immediately returns fallback without making a paid API call if the observation timestamp is >120s old or >5s in the future, or if no candidates match enabled: true, authorized: true, and the active surface_id.
- Redacted Receipts & Windows DPAPI Credential Hygiene: All decide, ocr, and signage runs default to offline preview (omitting raw base64 bytes in favor of byte counts and dimension metadata). When --execute is passed, written receipts (legends-jev/receipt-v1, ocr-receipt-v1, signage-receipt-v1) omit raw input text and image bytes—storing only a canonical input_sha256 digest and validated answers—while scripts/Invoke-Jev.ps1 scopes Windows DPAPI credential injection to a single --execute call and clears unmanaged plaintext memory afterward.
CLI Subcommands & Capability Surface
python -m legends_jev ocr --goal <str> --image label=path [--expect-text <str>] [--locate [label:]target] [--choice key=desc] [--execute] — General-Purpose Optical Recognition (OCR) & Visual Target Localization: Evaluates 1 to 6 PNG/JPEG images against an inspection goal using pinned jev-1.14.0. Supports verifying 1 to 12 expected text strings via case-insensitive noul questions (--expect-text), localizing 1 to 4 visual or text targets with visibility-gated 0..1 box and original-image pixel_box coordinates (--locate), and classifying visual state across 1 to 8 choices plus automatic unknown (--choice).python -m legends_jev signage --title <gbp_title> --suspect-term <term> --image label=path [--execute] — GBP Storefront & Street View Signage Verification: Compares physical storefront signage, building facades, awnings, and logos across Street View and business photos against a published Google Business Profile title and 1 to 12 suspect keyword-stuffed terms (used by legends-geogrid). Returns a typed legends-jev/signage-receipt-v1 with verdict (supports_full_title, omits_suspect_terms, or obstructed_or_no_sign), best_image, best_streetview, sign_visible, suspect_terms_shown, sign_box, and sign_pixel_box.python -m legends_jev decide --input evidence.json [--execute] [--output receipt.json] — Typed UI & Browser Action Selection (decide): Evaluates a validated legends-jev/evidence-v1 JSON envelope containing accessibility text, screen descriptions, app metadata, or optical images against 1 to 8 candidate actions across shell, chrome, direct, or operator routes. Returns a suggestion only when preflight freshness passes, action confidence >= 0.8, insufficiency noul <= 0.2, and support score >= 1.8; otherwise returns operator_fallback.python -m legends_jev doctor | guide | sample | readiness --input <json> | preview --input <json> | direct --input <json> — Offline Readiness, Preview & Exact-Match Baseline (direct): Provides zero-network readiness and baseline tools: doctor validates all bundled synthetic fixtures and environment state; sample emits a valid evidence-v1 template; readiness checks timestamp freshness and candidate eligibility; preview displays the exact TypeSafe payload offline; and direct runs a zero-latency deterministic case-insensitive exact match between goal and candidate description.load_image_entry | prepare_image_bytes | pixel_box [--no-normalize] — Pure-Python & Cross-Platform Image Normalization Pipeline: Inspects PNG and JPEG headers (rejecting animated PNGs and malformed segments) and automatically scales and center-pads images outside TypeSafe's 280..1568px window using a built-in pure-Python 8-bit PNG decoder/encoder, Pillow if present, or Windows .NET System.Drawing. Pass --no-normalize to strictly reject out-of-range dimensions instead.python -m legends_jev benchmark [--execute] | models [--execute] — Sequential Synthetic Benchmarking & Model Verification: Compares the deterministic direct exact-match baseline against live jev-1.14.0 decisions across at most 20 synthetic fixture cases sequentially, halting immediately on the first provider or protocol failure and reporting label matches, wrong suggestions, fallback counts, and mean/median latency in milliseconds.
Raw Frontier LLM vs. legends-jev Execution Matrix
- Out-of-Bounds Desktop Screenshots (e.g., 1920x1080): Raw LLM (Either fails provider dimension limits or resizes the image internally without exposing scale/pad math, returning shifted bounding-box coordinates.) vs. Module (Auto-normalizes PNG/JPEG images into 280..1568px with centered padding and maps returned 0..1 boxes back to exact original-image pixel_box coordinates.) — Receipt includes image_dimensions (original_width, original_height, width, height, normalized) alongside pixel_box (left, top, right, bottom, center_x, center_y).
- Ambiguous, Stale, or Prompt-Injected Screen Evidence: Raw LLM (Hallucinates hidden UI state, acts on stale screenshots, or follows adversarial instructions embedded inside untrusted image text.) vs. Module (Rejects observations >120s old offline, instructs System One to treat evidence/images as untrusted data, and gates suggestions on noul, score, and confidence thresholds.) — Any failed preflight check, malformed probability distribution, or low-confidence score returns status: operator_fallback and actuated: false.
- Actuation & Permission Boundaries: Raw LLM (Couples vision guessing directly to mouse clicks or shell execution without operator review.) vs. Module (Strictly read-only advice and optical recognition (actuation: false); filters out disabled, unauthorized, or wrong-surface candidates before calling the API.) — Every receipt enforces requires_operator_validation: true and actuated: false; actuation remains in legends-shell-kit or legends-chrome-kit.
- Network & Retry Determinism: Raw LLM (Silently falls back to unpinned model aliases or retries failed paid vision calls in background loops.) vs. Module (Pins model jev-1.14.0 on every request and response, enforces a single 30-second timeout with no redirects, no retries, and no alias fallback.) — Preview mode makes zero network calls; --execute performs at most one HTTP POST to /v1/systemone and verifies raw['model'] == 'jev-1.14.0'.
Explicit Safety Boundaries & Exclusions
Operator FAQ
- Does legends-jev click buttons or control my desktop or browser directly?
- No. legends-jev is strictly an observation and typed-advice adapter that returns validated Choice, Score, Noul, and Box (pixel_box) receipts with actuated: false. Desktop and browser actuation remain in legends-shell-kit, legends-chrome-kit, or your chosen automation tool after operator validation.
- What happens if I pass a 1920x1080 desktop screenshot or a tiny button crop to legends-jev ocr or signage?
- TypeSafe's /v1/systemone endpoint requires PNG or JPEG images between 280 and 1568 pixels per side. Unless --no-normalize is passed, legends-jev automatically scales and center-pads out-of-range images into 280..1568px before sending the request and maps returned 0..1 bounding boxes back to exact pixel_box coordinates (including center_x and center_y) on your original image.
- How does legends-jev prevent stale screenshots or low-confidence model outputs from triggering bad actions?
- Before calling the API, preflight() rejects evidence older than 120 seconds, more than 5 seconds in the future, or lacking eligible (enabled, authorized, matching surface_id) candidates. After the API call, validate_response() checks exact probability-distribution math and applies conservative uncertainty gates (such as action confidence >= 0.8, insufficiency noul <= 0.2, and support score >= 1.8), returning status: operator_fallback whenever any check fails.
All 19 CTO Legends Packages (1 Router + 18 Modules)
cto-legends (v0.2.5) — Single-skill Python CLI router and isolated environment manager that resolves 18 SHA-256-pinned modules on demand without MCP startup bloat.legends-empire (v0.3.2) — SHA-256 Markdown knowledge foundation with recoverable NTFS and POSIX transactions, .raw/ evidence quarantine, and read-only vault stewardship.legends-hetzner (v0.1.3) — Hetzner Cloud CLI toolkit with Cost-Optimized CX/CAX stock radar, Fractional CTO sizing, SHA-256 server plans, 10-check preflight, and VPS sniping.legends-coolify (v0.2.1) — Read-only Coolify PaaS CLI for self-hosted app inventory, secret-free env key inspection, backup schedule audits, deployment history, and runbooks.legends-cloudflare (v0.1.1) — Zero-dependency Cloudflare DNS CLI enforcing SHA-256 preview-first single-record upserts, exact-ID deletes, setting preservation, and API readback.legends-astro (v0.2.1) — Astro v7 migration CLI that extracts HTML and WordPress source contracts, scaffolds Content Layer collections, and verifies dist/ build parity.legends-gohighlevel (v0.3.0) — Python 3.11+ GoHighLevel CLI for API v2 CRM, Workflows v3, Agent Studio AI, and 5-layer agency RBAC/1.05x rebilling with SHA-256 preview and readback.legends-geogrid (v0.2.2) — Circular-lattice Google Maps rank tracker, GBP name-stuffing audit workbench, and 18-page vector PDF strategy studio for coding agents.legends-dataforseo (v0.1.6) — Zero-dependency Python API and CLI for DataForSEO v3 SERP, Maps, GBP, and keyword research with offline previews and evidence banking.legends-firecrawl (v0.3.2) — Agent-first CLI wrapper (lfc and lax) for official Firecrawl web extraction and Alexandria queries with full local JSON evidence banking.legends-github (v0.2.1) — Deterministic Python CLI for GitHub repository audits, DataForSEO keyword and SERP demand, 20-topic synthesis, non-destructive READMEs, and OG checks.legends-grant (v0.3.0) — Standard-library Python CLI for 56-jurisdiction US grant discovery, SQLite evidence banking, qualification checks, and proposal verification.legends-jev (v0.2.1) — Zero-dependency Python CLI for TypeSafe Jev 1.14 optical recognition (OCR), storefront signage checks, pixel bounding boxes, and typed UI decisions.legends-obs (v0.1.2) — Guarded Windows OBS Studio CLI over WebSocket v5 for hardware encoder planning, pre-mutation rollback snapshots, and FFprobe-verified recording canaries.legends-captions (v0.1.1) — Deterministic video caption QA and ASS rendering CLI with contextual ASR repair, NeMo Forced Aligner word timing, spoken acronym locks, and proof frames.legends-yt-dlp (v0.1.2) — Paced yt-dlp orchestration CLI with SHA-256 binary verification, channel item ledgers, opt-in Mullvad Lockdown guards, and Parakeet/NFA word-level search.legends-stable-audio-3 (v0.1.3) — Hardware-aware Stable Audio 3 CLI for VRAM-calibrated local Medium batches, guarded Large REST jobs, cue-trimmed streaming mixes, and float WAV mastering.legends-hyperyap (v0.1.1) — Offline desktop dictation runtime running INT8 ONNX NVIDIA Parakeet TDT 0.6B v2 locally with CUDA-first inference, active-window paste, and terminal hooks.legends-ambient-intelligence (v0.1.1) — Passive audio pipeline CLI for SHA-256 deduplicated USB recorder ingest, offline Whisper/NeMo Parakeet ASR, rollover recovery, and vault distillation.