media-manager

Media management for the agentic era: organize photos and other personal media, then link them to documents to create a helpful knowledge base.

Start with:

• AGENTS.md for agent guidance, boundaries, privacy rules, and relevant skill mapping.
• WORKFLOW.md for .cache, memory, knowledge_base, specifications, and plans conventions.
• knowledge_base/data-sources.md for the initial source map.
• specifications/codebase-shape/spec.md for the draft codebase-shape specification.
• catalog.yaml for the exposure-independent private media catalog schema.
• models.md for default/station install profiles and Ollama model management.

Implementation Readiness

The current plan is ready for implementation planning. There are no drastic open design decisions blocking the first phase.

The first implementation should start with the repo-local CLI scaffold, catalog-aware on-demand table creation, machine profiling, and bounded source inventory. It should not require remote APIs, station-only dependencies, documents-manager, agents-cli, .agents/.venv, or a full media scan.

CLI Contract

The media-manager CLI is private to this repo and to a future repo-specific skill/operator. It is not a lower-layer or sibling-repo API.

There is no init catalog command. Any producer that writes catalog data must load catalog.yaml, create missing tables through the central catalog-aware writer, then write rows. Runtime code should avoid hardcoded table schemas.

Planned command surface:

media-manager inventory scan --limit <n> --out <jsonl>
media-manager metadata extract --sample <jsonl> --batch-size <n>
media-manager bench profile-machine --out <json>
media-manager bench sample --limit <n> --strategy <strategy> --out <jsonl>
media-manager bench embeddings --provider <provider> --model <model> --sample <jsonl> --batch-size <n>
media-manager bench faces --engine insightface --sample <jsonl> --batch-size <n>
media-manager bench vlm --provider <local|openai> --model <model> --sample <jsonl> --batch-size <n> --dry-run
media-manager bench vlm --provider <local|openai> --model <model> --sample <jsonl> --batch-size <n>
media-manager bench evaluate --run <run-id> --review-file <jsonl>
media-manager bench report --since <date> --out <md>
media-manager search <query> --limit <n>
media-manager search <query> --limit <n> --jsonl

Any benchmark that can call a remote API or create external cost must support --dry-run. The dry run must estimate cost, planned item count, model, batch size, and output rows without calling the remote API. A real hosted run is allowed only after that estimate is reviewed.

Minimum search result fields:

rank
media_asset_id
path
capture_started_at
score
match_modes
match_reasons
description_snippet
labels_or_entities
gps_or_place
thumbnail_path
review_task_ids

Dependency Shape

pyproject.toml installs the laptop/default runtime by default: CLI, catalog parsing, media metadata tools, LanceDB, local image-text embedding libraries, CPU ONNX runtime, Streamlit, and OpenAI client support.

Install default/laptop:

uv sync

Install station additions:

uv sync --extra station

station adds only what differs from the default profile: GPU ONNX runtime, direct Hugging Face / Transformers VLM runtime libraries, and the station-only face_recognition fallback.

The only machine-profile extra is station. The remaining extra is dev for tests, linting, and type checks:

uv sync --extra dev

Model weights are not installed by pip or uv. Use models.md for the split between uv-installed Python libraries, Ollama-managed local VLMs, Python/Hugging Face model caches, InsightFace face models, and hosted VLMs.

Manual EXIF Example

For one-off metadata fixes on existing JPEG photos, prefer the native Windows ExifTool install instead of adding a Python wrapper to this repo.

Install on Windows:

winget install --id OliverBetz.ExifTool -e

Safe sample-copy example:

copy "C:\Users\<you>\OneDrive\Media\Photos\<folder>\photo.jpg" ".cache\sample.jpg"
"C:\Users\<you>\AppData\Local\Programs\ExifTool\ExifTool.exe" ^
  -overwrite_original ^
  -AllDates="2026:06:17 00:00:00" ^
  -GPSLatitude="48 16 08.8" ^
  -GPSLatitudeRef=N ^
  -GPSLongitude="11 34 59.5" ^
  -GPSLongitudeRef=E ^
  ".cache\sample.jpg"

Folder-wide JPEG example:

"C:\Users\<you>\AppData\Local\Programs\ExifTool\ExifTool.exe" ^
  -overwrite_original ^
  -P ^
  -AllDates="2026:06:17 00:00:00" ^
  -GPSLatitude="48 16 08.8" ^
  -GPSLatitudeRef=N ^
  -GPSLongitude="11 34 59.5" ^
  -GPSLongitudeRef=E ^
  -ext jpg ^
  "C:\Users\<you>\OneDrive\Media\Photos\2026 - Jasmin Kita"

Notes:

• -P preserves filesystem modified times while updating EXIF fields in place.
• This edits original files and will trigger OneDrive sync.
• If only a date is known, setting midnight is acceptable, but a real capture time is better when available.