* RemoteAiDatasource in features/ai_suggestions/data/datasources/ communicates with Google's Gemini API (or equivalent) for creative habit suggestions beyond the rules engine's capacity.
* This datasource is only invoked when the user has explicitly opted in via a toggle in settings.
* Data sent to the API is a UserProfileSnapshot: anonymized summary of habit categories and counts, completion rate percentages, usage category ratios (not raw durations), dopamine score range (bucketed, not exact), and time zone (for time-aware suggestions).
* No personal names, habit names, or raw usage data are sent.
* API communication uses dio with retrofit_generator for type-safe HTTP client generation.
* Responses are parsed into HabitSuggestion entities with SuggestionReason.aiGenerated(rationale).
* The datasource handles network errors, rate limiting, and timeout gracefully, returning an empty list on failure without affecting the local engine's results.
* Results from the remote AI are merged with local engine results, deduplicated, and re-ranked.
* API key management uses build-time environment variables, not hardcoded strings.
gherkin
Given the user has opted in to AI suggestions
When the suggestion engine runs
Then both the local rules engine and remote AI datasource are invoked and their results are merged
Given the remote AI datasource constructs the API request payload
When the payload is serialized
Then it contains only anonymized category counts, completion rate percentages, usage ratios, and bucketed score range with no personal identifiers
Given the remote AI API returns 3 creative suggestions
When the results are parsed
Then 3 HabitSuggestion entities are created each with SuggestionReason.aiGenerated containing the AI's rationale
Given the remote AI API returns an error or times out after 10 seconds
When the error is caught
Then the datasource returns an empty list and the local engine's results are displayed without interruption
Given the local engine generates 8 suggestions and the remote AI generates 3 suggestions
When the results are merged and deduplicated
Then up to 10 unique suggestions are returned sorted by confidence
Given the user has not opted in to AI suggestions
When the suggestion generation runs
Then the remote AI datasource is never invoked and no network calls are made
Given the app is built
When the API key is resolved
Then it is read from a build-time environment variable and not present as a string literal in the source code
Details and Assumptions
Acceptance Criteria