Cameron CordesandClaude Opus 5.5
09b9e87396
README, CLAUDE.md and .env.example now point at llm.toml for LLM settings (OPENROUTER_API_KEY stays in env) and describe the legacy env override window, the discovered picker and the startup cross-check. ADR-0003 records the move and amends ADR-0002's deployment-config home; CONTEXT.md's Deployment config / Hard default entries follow. Source comments and the "set LLAMA_SWAP_URL" error strings name the llm.toml keys. Also fixes README's AGENTIC_MAX_ITERATIONS default (10 -> 12, what the code uses). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
88 lines
4.3 KiB
Markdown
88 lines
4.3 KiB
Markdown
# ImageApi
|
|
|
|
A photo/video memory system: it ingests media from one or more libraries, derives metadata
|
|
(hashes, dates, faces, insights) that follows the bytes rather than the path, and serves it
|
|
to two consumers (the Apollo web UI and the FileViewer mobile app) plus a message store (SMS-API).
|
|
|
|
## Language
|
|
|
|
### Dates & time
|
|
|
|
**True instant**:
|
|
The actual moment a photo or video was captured, as Unix seconds. The one clock the whole
|
|
system matches against — SMS messages, location track points, and photo dates are all true
|
|
instants, so they compare directly with no conversion.
|
|
_Avoid_: epoch, real UTC, wall time
|
|
|
|
**Wall clock**:
|
|
The local time the capturing device showed (e.g. "14:30 on the beach"), independent of where
|
|
the owner is. A wall clock is not an instant until paired with a zone; it is what the UI's
|
|
metadata line and insight prompts show so memories read the way the camera remembered them.
|
|
_Avoid_: local time, naive date, camera time, date_taken
|
|
|
|
**Camera offset**:
|
|
The zone offset that converts a photo's wall clock into its true instant, resolved per photo
|
|
at ingest from the most specific evidence available (an explicit EXIF offset tag, then GPS
|
|
position, then the server's zone as a flagged assumption). Recorded on the row so the
|
|
conversion is auditable.
|
|
_Avoid_: timezone, tz, server offset
|
|
|
|
**Display zone**:
|
|
The IANA zone name of the owner, used for day-level grouping (memories buckets, timelines,
|
|
daily summaries) and for rendering wall clocks when a photo carries no camera offset. Stored
|
|
as a zone name, never a fixed minute offset, so DST changes stay correct.
|
|
_Avoid_: timezone_offset, tz_offset_minutes, client offset
|
|
|
|
**Date source**:
|
|
Which step of the ingest waterfall filled a photo's date — EXIF tag, external metadata
|
|
tool, filename, filesystem time, or a manual edit. Recorded per row so weak entries can be
|
|
re-resolved when a better tool arrives and so any row's date can be explained.
|
|
_Avoid_: provenance, origin
|
|
|
|
**Filename date class**:
|
|
Filenames whose name itself carries the capture date (screenshots, timestamp-named exports).
|
|
For this class the filename is the original date of record and outranks EXIF, even though
|
|
EXIF wins everywhere else. Each pattern in the class carries its own convention: some names
|
|
encode a wall clock, others encode a true instant.
|
|
_Avoid_: regex dates, name parsing
|
|
|
|
**Manual date**:
|
|
A date the operator sets by hand, expressed as a wall clock in the display zone at edit time
|
|
and stored as the resulting true instant. The prior value is kept as the original date.
|
|
_Avoid_: corrected date, user date
|
|
|
|
**Re-anchoring (legacy)**:
|
|
The pre-instant habit of storing wall clocks as if they were UTC and having every consumer
|
|
shift them back by a zone. Survives only in the frozen legacy column and in the consumer
|
|
code that migrates off it; new code never re-anchors.
|
|
_Avoid_: tz fix, offset correction, naive handling
|
|
|
|
**Derived day data**:
|
|
Insights and pre-computed artifacts grouped by calendar day (daily message summaries,
|
|
reel pre-generation). Because it is keyed on the day, re-dating a photo across a day
|
|
boundary invalidates the derived data for that day, which regenerates on its normal schedule.
|
|
_Avoid_: cache, nightly output
|
|
|
|
### Configuration
|
|
|
|
**Owner default**:
|
|
A per-request default the owner sets for the whole deployment — the model, backend,
|
|
persona, reel span, or segment cap a client gets when it omits the field. Stored in the
|
|
single `user_ai_prefs` row, hot-tunable without a redeploy, and global: every client that
|
|
omits the field gets it, on every device. Never holds secrets.
|
|
_Avoid_: user prefs, user settings, preferences (ambiguous with device-local client state)
|
|
|
|
**Deployment config**:
|
|
Values the server needs before it can start serving — bind address, database path, media
|
|
roots, the URLs used to build clients — plus every secret. Lives in `.env`, except LLM
|
|
settings, which live in `llm.toml` (ADR-0003); secrets stay in `.env` only. Changing it
|
|
is a restart, by design.
|
|
_Avoid_: environment config, system config
|
|
|
|
**Hard default**:
|
|
The config/code fallback (`.env`, `llm.toml` or a code constant) a request lands on when neither an explicit param nor a stored
|
|
owner default supplies the field (e.g. backend `local`, persona `default`, reel span
|
|
day). It is the floor under the owner-default layer: config changes keep working whenever a
|
|
default column is NULL.
|
|
_Avoid_: fallback value, env default
|