Financial Insights

Bliss generates AI-powered financial reports that analyze your patterns across four cadences — monthly, quarterly, annual, and portfolio-specific.

How it works

Fifteen financial lenses organized into six categories (Spending, Income, Savings, Portfolio, Debt, Net Worth) examine your transaction and portfolio data. Each insight is generated by Gemini Pro and persisted additively — old insights are kept for historical context, not replaced. A data-completeness check runs before every generation so partial periods are never compared to full ones.

The four tiers

Monthly (2nd of each month)

A month-over-month and year-over-year health check. Covers spending velocity, category concentration, income stability, savings rate, and net worth trajectory for the previous month.

Quarterly (3 days after quarter close)

Seasonal trend analysis across a full quarter. Identifies patterns that monthly snapshots miss — holiday spending spikes, quarterly income cycles, and longer-term drift.

Annual (January 3rd)

A comprehensive year-in-review covering all six categories. Compares the full year against the prior year and highlights the biggest shifts in your financial profile.

Portfolio (every Monday)

Equity-specific intelligence powered by the SecurityMaster reference table. Analyzes sector concentration, valuation risk (P/E ratios), dividend opportunities, and geographic exposure across your stock holdings.

Enabling insights

Insights require the same Gemini API key used for transaction classification:

GEMINI_API_KEY=your_api_key

Optionally override the model (defaults to gemini-3.1-pro-preview):

INSIGHT_MODEL=gemini-3.1-pro-preview

A daily cron job at 6 AM UTC acts as a scheduling heartbeat — it checks each tier’s calendar window and only triggers generation when the window is open. The portfolio tier runs on its own cron at 5 AM UTC every Monday.

Without a Gemini key, the insights page remains accessible but empty.

Using the insights page

The insights page organizes your reports into browsable categories:

• Category tabs — Filter by Spending, Income, Savings, Portfolio, Debt, or Net Worth
• Severity chips — Focus on what matters: Positive, Info, Warning, or Critical
• Tier badges — Each insight shows which cadence generated it (Monthly, Quarterly, Annual, Portfolio)
• Period selector — Browse insights from any past period
• Manual refresh — Pick a tier and period, then generate on demand. Use the force option to bypass the completeness check for partial periods
• Dismiss and restore — Hide insights you’ve acted on. Dismissed state persists even when the same period is regenerated

Deduplication

Insights are deduplicated by (tier, periodKey, dataHash). If your underlying data hasn’t changed since the last generation, regenerating a period is a no-op — no duplicate insights are created.

Retention

Each tier has a different retention window:

Expired insights are cleaned up via the TTL retention service.

Next steps

• AI Classification — insight quality depends on accurate classification
• Investment Portfolios — the portfolio tier uses SecurityMaster fundamentals
• Explore the Insights spec for full technical details