How the daily story gets written

September 3, 2026 · about a 6-minute read

Tap once and PicLoom turns "what's in these photos, where they were taken, and what the weather was" into a short story. This post unpacks how it works and where each privacy boundary is drawn.

Step one: collect three kinds of facts

The raw material of a story is structured facts, not the photos themselves. Before writing anything about a day, the engine gathers three things:

• Content — photos are classified on device with the system Vision framework (VNClassifyImageRequest) into labels like "food / outfit / scenery / pet", which map to localized categories. Cloud image attachments require a separate opt-in.
• Place — GPS metadata embedded in the photos is reverse-geocoded. Note this needs no location permission: photo access already carries the metadata, the system CLGeocoder does the lookup, and results are cached at roughly 1 km granularity to avoid repeat requests.
• Weather — Open-Meteo's historical/forecast API. It's free and keyless; requests carry only rounded coordinates and a date, and results are cached per day.

DayFactsCollector
  ├─ Vision labels       (on device, no network)
  ├─ CLGeocoder place    (cached per ~1 km)
  └─ Open-Meteo weather  (rounded coords + date, cached per day)

Step two: three engines, one contract

With facts in hand, the selected "story engine" turns them into text. All three engines honor the same output contract, so you can switch anytime:

• Smart (default) — Apple's on-device large model (FoundationModels) writes directly on the phone on Apple Intelligence-capable devices; it falls back to the template engine automatically otherwise.
• Template — pure rule-based composition. Works on every iPhone, fully offline, and the fastest of the three.
• Cloud (bring your own key) — connects to the user's own OpenAI-compatible service, with the key stored in the on-device Keychain.

The cloud engine's default boundary

Cloud generation is optional and off by default: only structured text facts are sent (date, weather, place name, content labels) — no photos. Attaching compressed photos is a separate switch buried in settings, off by default, with an explicit confirmation before it can be enabled.

Caching and offline use

Opening a saved story reads its local copy. Regeneration may collect fresh facts and, when selected, make a new cloud request. A failed save retains the generated text for retry without another generation. The previous valid saved version is kept for recovery. Widget previews use the shared snapshot; its keep action also verifies StoreKit access.

Why the default engine is on-device

Baking the best out-of-box experience onto the device model means users without an API key still get natural, well-written stories, with the strongest privacy setting as the default. The template engine guarantees the feature always works, and the cloud engine is there for people who want to configure their own — three tiers of graceful degradation that leave nobody out.

Implementation details will keep evolving; the behavior contract lives in spec/001-day-story.md in the repo. Next post: widget design notes: five moments a day.