reverse-trace

Reverse Trace

Identify the source of images and videos by running multiple reverse search APIs in parallel and synthesizing results into a confidence-ranked report. Each engine contributes a different signal — web entity matching, AI geolocation, multimodal LLM identification — and the orchestrator merges them because no single API reliably covers all identification scenarios.

Prerequisites

At least one API credential must be set. Missing keys cause the orchestrator to skip that engine, not crash.

| Engine | Env Var | Free Tier | Signal | |--------|---------|-----------|--------| | Google Vision | GOOGLE_APPLICATION_CREDENTIALS or ADC | 1K/mo | Web entities, matching pages, similar images, best-guess labels | | Picarta (geospy) | PICARTA_API_KEY or GEOSPY_API_KEY | Yes | Lat/lng, city, country, confidence score | | Gemini | GOOGLE_API_KEY or GEMINI_API_KEY | Yes | Media type, title, season/episode, characters, actors |

To set up Vision ADC: gcloud auth application-default login

Workflow

Full pipeline (recommended default)

Run rt_trace.py to execute all available engines in parallel. For video input, keyframes are extracted first via ffmpeg.

python3 scripts/rt_trace.py image.jpg
python3 scripts/rt_trace.py video.mp4 --max-frames 3
python3 scripts/rt_trace.py image.jpg --json
python3 scripts/rt_trace.py image.jpg --skip geospy
python3 scripts/rt_trace.py image.jpg --engines vision gemini

Individual engines

Use a single engine when only one type of identification is needed, to conserve API quota, or to debug a specific engine's output.

python3 scripts/rt_vision.py image.jpg              # Web entities + matching pages
python3 scripts/rt_geospy.py photo.jpg --top-k 3    # AI geolocation
python3 scripts/rt_gemini.py frame.jpg               # LLM media identification
python3 scripts/rt_extract.py video.mp4 --keyframes  # Frame extraction only

Engine selection guide

| Goal | Engines to use | Why | |------|---------------|-----| | Identify TV show / movie | gemini + vision | Gemini recognizes characters from training data; Vision finds matching web pages that name the episode | | Find where an image was published | vision | Web Detection returns pages hosting the image with titles and URLs | | Geolocate a photo | geospy | Picarta AI geolocation from visual cues (architecture, vegetation, signage) | | Full automated identification | rt_trace.py (all) | Parallel execution, merged synthesis, confidence ranking |

Output format

Default output is a human-readable report with sections: BEST GUESS, MEDIA IDENTIFICATION, GEOLOCATION, WEB ENTITIES, MATCHING PAGES, ENGINE STATUS. Add --json for structured JSON suitable for piping or programmatic consumption.

Adding new engines

The orchestrator uses a single ENGINE_REGISTRY dict. To add an engine:

1. Create scripts/rt_<name>.py following the existing pattern (argparse CLI, --json flag, env var auth, engine field in JSON output)
2. Add an entry to ENGINE_REGISTRY in rt_trace.py with script and env keys
3. The engine is automatically included in the parallel pipeline

Planned Phase 2 engines (paid APIs): SerpAPI Google Lens, TinEye, Lenso.ai, Yandex. See references/expansion-roadmap.md for API details, pricing, and implementation notes.