station-announcer/SPEC.md

Here’s an updated, cleaner specification that incorporates your Immich URL and the api_keys file, and clarifies how configuration should work.

---

Overview

A small Flask web application that helps generate high-quality alt text for Mastodon posts. It retrieves recent photos from Immich, displays them as thumbnails, and lets the user request alt text from the OpenAI API, optionally guided by user-supplied notes. Generated alt text is cached and shown in the index view.

The app targets local development only and can run via the built-in Flask server with no authentication. Production deployment can be dealt with later.

Requirements

1. Photo retrieval (Immich)

• Immich is available at: https://photos.4angle.com/

• The app must connect to the Immich API using an API key.

• Fetch images created within the last three days.

• Store enough metadata to:

  • display a thumbnail,
  • retrieve the image for alt-text generation.

2. Index view

• Display a grid of thumbnails for the recent photos.
• Show cached alt text (if available) beneath each thumbnail.
• Each thumbnail should link to a detail view.

3. Photo detail view

• Display a larger version of the chosen image.

• Provide a text box for user notes (free text, optional).

• Include a button to trigger alt-text generation via the OpenAI API.

• The OpenAI request must include:

  • the selected image (as URL or binary data, depending on the chosen model),
  • the user notes,
  • a short system/user prompt instructing the model to produce concise, high-quality Mastodon alt text.

• Display the generated alt text and persist it to the cache.

4. Alt-text caching

• Cache alt text keyed by the Immich asset ID.

• Use a simple local store:

  • SQLite, or
  • a JSON file (fine for a prototype).

• The index view must reuse cached values rather than regenerating them.

5. Configuration

• API keys for Immich and OpenAI are currently stored in a file called api_keys.

• You may rename this file or relocate configuration. Suggested improvements:

  • rename to .env, and load via python-dotenv, or
  • rename to config.toml and parse with standard libraries.

• Configuration values should include:

  • IMMICH_API_URL (default: https://photos.4angle.com/)
  • IMMICH_API_KEY
  • OPENAI_API_KEY

• Flask should read these at startup.

6. Operation

• Just running flask run must start the app in development mode.
• Requests can be synchronous; no background workers needed.
• No user login or security layer required at this stage.

---

If you’d like, I can propose a directory layout, generate a config.py, a .env example, or scaffold the Flask app skeleton.