Deep dive

Weather Integration and Global Preferences

You can now persist user preferences like 'home_city' across sessions and safely fetch weather data. The flow engine handles missing state by prompting the user before calling external APIs.

riff

What was built & why

The weather flow stalled because it lacked state persistence and safe API integration. You added `riff/preferences.py` to save the home city to a JSON file without requiring user identity. `riff/weather_tools.py` injects the Open-Meteo fetcher, keeping external calls isolated from core logic. The `flows/weather.yaml` finite state machine checks for a saved city first. It prompts the user only if the city is missing, satisfying safety gates before fetching data.

Principles

Persist simple state in JSON files when caller identity is absent.
Inject external API clients to keep tool logic testable and isolated.
Validate required state inside the flow before executing side effects.
Auto-register tools and guards to reduce boilerplate in loaders.

Patterns

JSON-backed global preference store
Injectable external API fetcher
State-checking finite state machine
Auto-registration via loaders

How to apply

Save user timezone in `riff/preferences.py` to customize timestamp displays.
Inject a stock price fetcher in `riff/finance_tools.py` for market updates.
Add a guard in `flows/news.yaml` to check for saved topics before scraping.
Use `RIFF_PREFERENCES_PATH` in CI scripts to isolate test state.

Pitfalls

The global store lacks caller identity, breaking multi-user isolation.
Tests fail if `RIFF_PREFERENCES_PATH` is not set correctly.
Safety gates break if you move the save logic out of the ask state.
JSON file corruption crashes the preference loader without retry logic.