film-date-agent

What does film-date-agent do?

A tool to burn physical optical film camera quartz date stamps onto images, usable from an AI agent. The rendering is done by a physical optical simulation engine (FilmDateStamp), and this skill specifies 'when asked, unhesitatingly burn the optimal preset and date/time and correctly report the result'.

Tool

• Command: film-date-agent (or python -m film_date_agent)
• Setup verification: film-date-agent doctor must show all items as [OK]
• Preset: favorite is the default. The actual content is determined by favorites.json (default is Japanese Snap (Disposable): disposable camera style, orange glow, 5x7 capsule dots, hour and minute displayed).

If Not Installed / Command Not Found

• If film-date-agent is missing or doctor fails, first proceed with installation. If the repository (https://github.com/treeturtlefall-arch/FilmDateStamp-agent) is already cloned, run bash scripts/install_agent.sh, then run bash scripts/install_skill.sh to re-deploy this skill.
• After installation, run film-date-agent doctor --json again and confirm "ok": true before returning to this procedure.

Trigger Phrases (Activate Upon These Instructions)

• "Add a date stamp to the photo" / "Put a film-style date on it" / "Add a retro date"
• "Make it look like a disposable camera" / "Add a 90s-style date" / "Make it like an 80s SLR"
• "Burn the shooting date and time" / "Add the EXIF date"
• "Also include date and time"
• Also applicable when asked "Put a date stamp on it" right after generating/editing an image

Execution Steps

1. Identify the target image:

   • Identify the image mentioned in the conversation, or the one just generated/edited. If unclear, ask without guessing.

2. Select the preset and parameters:

   • If no specific instructions: Use the default favorite (favorite).

     film-date-agent apply <target_image> --json
     

   • If a specific atmosphere/era/style is requested:
     • "Disposable camera style" / "Look like a disposable": --preset japanese-snap-disposable (orange glow, 5x7 capsule dots, hour and minute displayed)
     • "90s Japan" / "Tokyo snap": --preset japanese-tokyo-90s (amber glow, 80s 7-seg)
     • "American style" / "West Coast": --preset american-west-coast (golden yellow, month-day-year order)
     • "80s motel" / "Red LED": --preset american-80s-red-quartz (quartz red, upright SLR 7-seg)
     • "Europe" / "Paris/Berlin": --preset european-classic-parisberlin (dot separator, subtle exposure)
     • "Early 2000s" / "Early compact digital": --preset y2k-digicam-early-2000s (monospace LCD font)
     • "70s" / "Classic camera": --preset monochrome-70s-canodate-e or --preset vintage-70s-color-datematic (mechanical engraved typeface)
     • "Cyber" / "Sci-fi movie": --preset cyber-telemetry-80s-sci-fi (cyber green HUD)
     • "Heisei retro" / "Purikura style": --preset y2k-pop-heisei-fancy (neon pink rounded characters)

3. Assemble the date/time options:

   • If no specific instructions (default): For favorite, the date setting in favorites.json (initial value is photo) automatically determines the date: EXIF shooting date/time → file creation/modification time → current time in that order. For non-favorite presets, the preset's default date is used.
   • To use the photo's shooting date/time:
     • "Use the shooting date/time" / "With the EXIF date" → Specify --date photo (automatically extracts EXIF shooting date/time).
   • To specify a particular date/time:
     • "Set it to December 24, 1998" → -d "'98 12 24" or --at 1998-12-24
     • "August 15, 2004, 2:30 PM" → --at 2004-08-15T14:30 --show-time
   • To use today's current time:
     • "Use today's date" / "With the current time" → --date auto
   • Show/hide time (HH:MM):
     • "Also include the time" / "Include hours and minutes" → --show-time
     • "Date only" / "No time needed" → --no-time
   • To use a random vintage date:
     • "Use some random old date" / "Randomize it" → --date random

4. Report the result:

   • Parse the --json output. If ok is true, present and report the image path stored in output to the user.
   • Add a brief note about the actual burned date string (date_text) and the applied style (preset_resolved).
   • Example: "Burned the shooting date/time '03 10 02 17:49 in 90s Tokyo snap style (Japanese Tokyo 90s)."

5. Error handling:

   • Exit code 2 (configuration error): Run film-date-agent presets list to check available presets and re-select.
   • Exit code 3 (input file missing): Verify the input image path.
   • Exit code 4 (output file conflict): By default, auto-sequencing (_stamped_1) is applied, but if overwriting is requested, use --overwrite.
   • Exit code 5 (engine failure): Check the result of film-date-agent doctor and report to the user.

If Asked "What can this do?"

1. Run film-date-agent capabilities --json and answer based on the latest capabilities list.
2. Explanation template:
   • It simulates light burning onto film emulsion (physical optical exposure, center core blowout, halation diffusion).
   • It has 12 era/region-specific presets (90s Tokyo snap, disposable camera style, West Coast, 80s red LED, early digicam, etc.).
   • The date can be selected from: photo EXIF shooting date/time, current date/time, retro random, or any custom string.
   • Users can create their own preferred settings and save them as "favorite".

Rules to Follow

• Do not overwrite the original image directly (do not specify the same path as the input image with -o).
• The report must rely on the output field from JSON. Do not guess the filename.