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:
- Create
scripts/rt_<name>.py following the existing pattern (argparse CLI, --json flag, env var auth, engine field in JSON output)
- Add an entry to
ENGINE_REGISTRY in rt_trace.py with script and env keys
- 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.
1---2name: reverse-trace3description: Identify the source of an image or video frame — TV show episode, movie scene, geographic location, or original publication. This skill should be used when the user asks to identify where an image is from, trace a screenshot back to its source, geolocate a photo, find what show or movie a frame is from, or do a reverse image search. Chains Google Vision, Picarta geolocation, and Gemini in parallel with graceful degradation. Triggers on: reverse image search, identify source, what show is this, where was this taken, trace image, identify video, what movie, which episode, geolocate photo, image source.4---5
6# Reverse Trace
7
8Identify 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.
9
10## Prerequisites
11
12At least one API credential must be set. Missing keys cause the orchestrator to skip that engine, not crash.
13
14| Engine | Env Var | Free Tier | Signal |
15|--------|---------|-----------|--------|
16| Google Vision | `GOOGLE_APPLICATION_CREDENTIALS` or ADC | 1K/mo | Web entities, matching pages, similar images, best-guess labels |
17| Picarta (geospy) | `PICARTA_API_KEY` or `GEOSPY_API_KEY` | Yes | Lat/lng, city, country, confidence score |
18| Gemini | `GOOGLE_API_KEY` or `GEMINI_API_KEY` | Yes | Media type, title, season/episode, characters, actors |
19
20To set up Vision ADC: `gcloud auth application-default login`
21
22## Workflow
23
24### Full pipeline (recommended default)
25
26Run `rt_trace.py` to execute all available engines in parallel. For video input, keyframes are extracted first via ffmpeg.
27
28```bash
29python3 scripts/rt_trace.py image.jpg
30python3 scripts/rt_trace.py video.mp4 --max-frames 3
31python3 scripts/rt_trace.py image.jpg --json
32python3 scripts/rt_trace.py image.jpg --skip geospy
33python3 scripts/rt_trace.py image.jpg --engines vision gemini
34```
35
36### Individual engines
37
38Use a single engine when only one type of identification is needed, to conserve API quota, or to debug a specific engine's output.
39
40```bash
41python3 scripts/rt_vision.py image.jpg # Web entities + matching pages
42python3 scripts/rt_geospy.py photo.jpg --top-k 3 # AI geolocation
43python3 scripts/rt_gemini.py frame.jpg # LLM media identification
44python3 scripts/rt_extract.py video.mp4 --keyframes # Frame extraction only
45```
46
47### Engine selection guide
48
49| Goal | Engines to use | Why |
50|------|---------------|-----|
51| Identify TV show / movie | `gemini` + `vision` | Gemini recognizes characters from training data; Vision finds matching web pages that name the episode |
52| Find where an image was published | `vision` | Web Detection returns pages hosting the image with titles and URLs |
53| Geolocate a photo | `geospy` | Picarta AI geolocation from visual cues (architecture, vegetation, signage) |
54| Full automated identification | `rt_trace.py` (all) | Parallel execution, merged synthesis, confidence ranking |
55
56## Output format
57
58Default 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.
59
60## Adding new engines
61
62The orchestrator uses a single `ENGINE_REGISTRY` dict. To add an engine:
63
641. Create `scripts/rt_<name>.py` following the existing pattern (argparse CLI, `--json` flag, env var auth, `engine` field in JSON output)
652. Add an entry to `ENGINE_REGISTRY` in `rt_trace.py` with `script` and `env` keys
663. The engine is automatically included in the parallel pipeline
67
68Planned Phase 2 engines (paid APIs): SerpAPI Google Lens, TinEye, Lenso.ai, Yandex. See `references/expansion-roadmap.md` for API details, pricing, and implementation notes.
majiayu000