dinary 1.2.4__tar.gz → 1.3.0__tar.gz

{dinary-1.2.4 → dinary-1.3.0}/CLAUDE.md

@@ -57,6 +57,7 @@ These rules come from `AGENTS.md` and supplement the defaults in this file.
 - Correct spec content: "every expense created from a receipt must have a matching rule", "retry every 15 minutes on day 1, then once a day indefinitely."
 - Never put function signatures, argument lists, field names, or internal class structure in specs. The code is the source of truth for those.
 - Specs describe **current state only**. Motivation, experiments, and rationale are welcome. Never track implementation changes ("previously X, now Y", "approach Z was removed") — state only the current rule. Git history records the evolution.
+- **Specs must never link to plan files.** `specs/reference/` and `specs/ui/` may only link to other spec files.
 
 ### Tests
 - Every new function needs tests in the same session. Never skip.

{dinary-1.2.4 → dinary-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dinary
-Version: 1.2.4
+Version: 1.3.0
 Summary: Server for [Dinary - your dinar diary](https://github.com/andgineer/dinary). Track expenses, scan receipts, analyze spending with AI
 Project-URL: Homepage, https://andgineer.github.io/dinary/
 Project-URL: Documentation, https://andgineer.github.io/dinary/

{dinary-1.2.4 → dinary-1.3.0}/specs/plans/analytics-ai.md

@@ -15,34 +15,29 @@ strategy, invariants, and Analytics Views design.
 
 4. `get_config(key)` and `set_config(key, value)` tools in `mcp_server.py`.
 
-### PWA sync
-
-5. `PUT /api/analytics/config` endpoint in dinary server + `analytics_pwa_config`
-   migration (coordinated with `analytics-pwa.md` work).
-
 ---
 
 ### AI Views feature
 
-6. **`queries/spending_summary.sql`** — aggregates last-12-months expenses into
+5. **`queries/spending_summary.sql`** — aggregates last-12-months expenses into
    three result sets: events (id, name, total_amount, date_from, date_to),
    tags (id, name, expense_count, total_amount), category groups (id, name,
    total_amount). Used by the LLM before proposing a new view.
 
-7. **`queries/view_data.sql`** — given a basket config passed as a JSON parameter,
+6. **`queries/view_data.sql`** — given a basket config passed as a JSON parameter,
    assigns each expense to its first-matching basket (event match checked before
    tag match, unmatched → default basket name), then aggregates by
    (basket_name, year_month, group_name). Returns one row per
    (basket, month, group) triple.
 
-8. **`settings.py` extensions** — `list_view_ids() → list[str]`, `get_view(id)`,
+7. **`settings.py` extensions** — `list_view_ids() → list[str]`, `get_view(id)`,
    `save_view(config: dict)`, `delete_view(id)`. Keys in LMDB: `view:<uuid>`.
 
-9. **MCP server** — expose `list_views`, `get_view(id)`, `save_view(config)`,
+8. **MCP server** — expose `list_views`, `get_view(id)`, `save_view(config)`,
    `delete_view(id)` tools so Claude Desktop / Claude Code can manage views
    externally.
 
-10. **In-session LLM tools in `dashboard.py`** (Gemini chat tool definitions):
+9. **In-session LLM tools in `dashboard.py`** (Gemini chat tool definitions):
     - `query_spending_summary()` → runs `spending_summary.sql`, returns JSON
     - `propose_view(baskets, default_basket, chart_type)` → sets the in-memory
       draft view config and triggers chart re-render; does not save
@@ -52,19 +47,31 @@ strategy, invariants, and Analytics Views design.
     - `save_current_view(name)` → persists draft via `settings.save_view()`
     - `delete_view(id)` → removes a saved view via `settings.delete_view()`
 
-11. **Altair chart for basket views** — stacked bar: X = year_month, Y = amount,
+10. **Altair chart for basket views** — stacked bar: X = year_month, Y = amount,
     color = basket_name. On click of a bar segment: filter to that basket + period
     and show a secondary stacked bar by group_name as a drill-down panel below.
     Use `alt.selection_point` on basket + month for the drill-down interaction.
 
-12. **View selector UI in `dashboard.py`** — `mo.ui.dropdown` populated from
+11. **View selector UI in `dashboard.py`** — `mo.ui.dropdown` populated from
     `settings.list_view_ids()` + labels from stored configs; "New view" button
     clears the draft and triggers the LLM with the `query_spending_summary()`
     result plus instructions to propose baskets with chart. Period selector
     (year / custom range) shown alongside the chart.
 
-13. **"New view" LLM prompt** — system prompt instructs the LLM: (a) call
-    `query_spending_summary()` first, (b) produce a `propose_view()` call
-    immediately with a concrete basket set, (c) explain each basket choice with
-    the numbers from the summary, (d) invite the user to react — never to describe
-    what they want in terms of categories or tags.
+12. **"New view" LLM prompt** — system prompt instructs the LLM: (a) call
+    `query_spending_summary()` first, (b) aim for 5–10 top-level baskets that reveal
+    non-obvious actionable patterns — not obvious dominant items like rent; start from
+    PWA category groups but reorganise freely, extracting cross-cutting baskets by
+    event or tag (e.g. travel tag → one basket, relocation event → one basket),
+    merging negligible items into the default basket; (c) produce a `propose_view()`
+    call immediately with a concrete basket set; (d) justify each basket with concrete
+    numbers from the summary; (e) call `update_suggestions()` with 3–5 follow-up
+    questions based on what the data shows; (f) invite the user to react — never ask
+    them to name categories or tags.
+
+13. **Suggested questions feature** — add `update_suggestions(questions: list[str])`
+    to in-session LLM tools: stores the list in a reactive Marimo state variable.
+    Dashboard renders a `mo.hstack` of `mo.ui.button` chips above the chat input;
+    clicking a chip sets the chat input value and submits. On dashboard load, after
+    `query_spending_summary()` completes, send a lightweight prompt to generate the
+    initial suggestion set.

{dinary-1.2.4 → dinary-1.3.0}/specs/reference/analytics-ai.md

@@ -129,6 +129,22 @@ against current ledger data. The user selects the time period at open time.
 
 Multiple views can be saved, renamed, copied, and deleted.
 
+### Basket design goal
+
+The goal of a basket set is to surface non-obvious, actionable spending patterns —
+not to confirm obvious ones (e.g. rent dominates). A good top-level set has 5–10
+baskets where each basket is both meaningful in share and something the user can
+actually track or influence.
+
+The LLM starts from PWA category groups as a baseline and reorganises freely:
+splitting a group, merging negligible ones, or extracting a cross-cutting basket
+(e.g. "Travel" by tag, "Relocation" by event). Items that are each individually
+negligible and not worth tracking separately are merged into the default basket.
+
+Drill-down into any basket produces a second-level basket set (5–10 items) breaking
+down that basket by sub-category, sub-tag, or sub-event, generated by the LLM on
+demand using the same methodology.
+
 ### Basket structure
 
 A view contains an ordered list of baskets plus a default basket name for unmatched
@@ -162,6 +178,12 @@ View config stored in `analytics.db` under key `view:<uuid>`:
 
 The LLM is the analyst; the user is the client who reacts to proposals.
 
+**Suggested questions.** The dashboard shows a row of clickable question chips above
+the chat input. After every LLM turn the model emits an `update_suggestions` tool call
+with a new list — keeping chips that remain contextually relevant and replacing ones
+already answered or no longer useful. The initial set is generated immediately after
+`query_spending_summary()` loads.
+
 **Creating a new view.** The LLM calls `query_spending_summary()` to examine actual
 spending patterns before saying anything. It then presents an initial basket proposal
 with a rendered chart and justifies each basket with concrete data: "Релокация —

{dinary-1.2.4 → dinary-1.3.0}/specs/reference/architecture.md

@@ -198,6 +198,7 @@ For implementation detail on each subsystem see `specs/reference/`:
 | `timestamps.md` | Timezone storage policy |
 | `currencies.md` | PWA/server responsibility split |
 | `sql-tool.md` | `inv sql` design |
+| `pwa-analytics.md` | Analytics view: page content, API contract, cache policy |
 
 ---
 

dinary-1.3.0/specs/reference/pwa-analytics.md

@@ -0,0 +1,43 @@
+# PWA analytics view
+
+A dedicated `/analytics` route in the Vue PWA. Read-only summary of the ledger.
+Complements the standalone `dinary-analytics` desktop app — the PWA view is
+always-accessible and mobile-friendly; the desktop app is where deep exploration
+and AI interaction happen.
+
+## Page content
+
+A single page, no tabs. Three sections:
+
+1. **Period cards** — YTD savings as a hero card (with savings rate subtitle) + three
+   equal cards: current month total, last completed month total, year-to-date spent.
+   Savings rate = YTD savings / YTD income.
+
+2. **Events** — all events from the last 12 months (open and closed), sorted by
+   date_from descending, each showing its total cost in accounting currency. Open
+   events are visually distinguished from closed ones.
+
+3. **Basket trends** — top-5 category groups and tags ranked by absolute % change
+   between the last 3 months and the 3 months before that. Threshold filter:
+   items with `MAX(recent, prior) < per-kind AVG * 0.15` are excluded as noise.
+   Groups and tags are filtered against their own kind average so tag amounts are
+   not swamped by group amounts. Omitted entirely when data is insufficient.
+
+## Data source
+
+`GET /api/analytics/summary` — single endpoint, single page load:
+
+```
+summary: { this_month_total, last_month_total, ytd_total, ytd_savings,
+           savings_rate, currency }       # amounts preformatted "156 000"
+events:  [{ id, name, date_range, total, currency, open }]  # date_range preformatted
+trends:  [{ basket_name, direction, pct }] | null
+```
+
+All queries are plain SQLite GROUP BY aggregations. DuckDB is not used on the
+server (1 GB RAM constraint).
+
+## Client cache
+
+The PWA caches the summary response for 24 hours. Trends change on a
+month-to-month basis, making sub-day freshness unnecessary.

{dinary-1.2.4 → dinary-1.3.0}/specs/ui/components.md

@@ -34,16 +34,17 @@ Every shipped UI component, with its source file and one-line contract. The `.vu
 
 | Component | File | Contract |
 |---|---|---|
-| `HeaderSegmented` | `components/HeaderSegmented.vue` | Segmented control with two inline tabs and an overflow menu. **Inline**: Add (Plus, 56×38, `--expense` tint/fill) and Review (ListChecks, 56×38, sky-blue `#60a5fa` tint/fill, doubtful-count badge bottom-right). **Overflow `•••`** (MoreHorizontal, 36×30, muted; `--accent` fill when any rare tab is the current tab): on tap, drops a 200-px-wide menu listing every entry in the module-level `RARE_TABS` array — currently Income (TrendingUp) and LLM providers (Cpu). Esc / outside `pointerdown` closes the menu. `v-model:tab` with values `'add'`/`'income'`/`'review'`/`'llm'`. Future rare tabs: append to `RARE_TABS` only — no header restructure needed. |
+| `HeaderSegmented` | `components/HeaderSegmented.vue` | Five inline tabs, no overflow menu. Each tab is 40×36px, icon-only (20px lucide icon). Inactive: `color-mix(in srgb, <tabColor> 14%, transparent)` bg + tab color icon. Active: solid tab color fill + white icon + `0 4px 12px <tabColor>40` glow. Tabs in order: **Add** (Plus, `--expense`), **Review** (ListChecks, `--review`, doubtful-count badge bottom-right when `showBadge`), **Analytics** (BarChart3, `--stat`), **Income** (TrendingUp, `--income`), **LLM** (Cpu, `--llm`). `v-model:tab` with values `'add'`/`'review'`/`'analytics'`/`'income'`/`'llm'`. All five tabs are peers — no overflow menu. |
 
 ## App shell
 
 | Component | File | Contract |
 |---|---|---|
-| `App` | `App.vue` | Top-level shell — dev banner, sticky header (brand + version + queue badge + `HeaderSegmented` + offline notice strip), main view router by `tab`, queue modal, global toast. |
+| `App` | `App.vue` | Top-level shell — dev banner, sticky header (`Dinary` brand + `HeaderSegmented`), queue strip (amber full-width strip below header row, only when queue non-empty, tap → `QueueModal`), offline notice strip (below queue strip when offline), main view router by `tab`, `QueueModal`, global toast. Version string removed from header. |
 | `AddView` | `views/AddView.vue` | Mounts `ExpenseForm`, `QrScanner`, the sticky bottom action bar (Scan 48×48 orange + Save flex-1 48px orange), and `KeyboardSaveBar` (orange variant). |
 | `IncomeView` | `views/IncomeView.vue` | Mounts `IncomeForm` inline at top, `INCOMES` section grouped by year with year totals, `IncomeRow` list, scroll-sentinel pagination, edit sheet, sticky bottom Save bar (green), `KeyboardSaveBar` (green variant). |
 | `ReviewView` | `views/ReviewView.vue` | Two-section list (`NEEDS REVIEW` warning header + `EXPENSES` neutral header). Owns the scroll container, two `IntersectionObserver` sentinels, refresh control, Confirm-all bulk action, and `ExpenseEditSheet` open/close. |
+| `AnalyticsView` | `views/AnalyticsView.vue` | Read-only summary dashboard (see `specs/reference/pwa-analytics.md`). Hero savings card + 3 stat cards + auto trend chips (wrap, no scroll) + event list. Fetches from `GET /api/analytics/summary`; caches 24 h in localStorage. Skeleton on first load, graceful offline degradation. |
 | `LLMView` | `views/LLMView.vue` | Provider pool management. Renders `HealthSummaryCard`, an optional `RECEIPT QUEUE` chip strip, then `PROVIDER POOL` and a list of `ProviderCard`s. Owns the 30s polling refresh timer. |
 
 ## Add view

{dinary-1.2.4 → dinary-1.3.0}/specs/ui/design-language.md

@@ -47,6 +47,12 @@ These are alpha-on-white, so they tint with the underlying surface. Never use a
 | `--warning` | `#f59e0b` | Doubtful left-border (c2), rate-limit pill, queue badge, NEEDS REVIEW label, dev banner | Background fills (except low-alpha tints inside cards) |
 | `--error` / `--danger` | `#ef4444` / `#e94560` | Destructive confirm button, status-dot "error", inline error text, doubtful left-border (c1) | Anything that isn't an error or destructive action |
 | `--expense` | `#f97316` | **Add view's primary color** (Add tab, currency pill, Save & Scan buttons, selected event chip, selected category quick-pick) | Anything outside the expense-entry context |
+| `--review` | `#60a5fa` | **Review view's primary color** (Review tab fill, edit-sheet Save, sky-blue accent) | Anything outside the review context |
+| `--income` | `#22c55e` | **Income view's primary color** — alias for `--success` in nav context (Income tab fill) | Generic success states — use `--success` there |
+| `--stat` | `#818cf8` | **Analytics view's primary color** (Analytics tab fill, open-event accent, hero card gradient) | Anything outside the analytics context |
+| `--llm` | `#22d3ee` | **LLM view's primary color** (LLM tab fill) | Anything outside the LLM context |
+| `--up` | `#f87171` | Trend direction: spending increased (caution red) | General error states — use `--error` there |
+| `--down` | `#34d399` | Trend direction: spending decreased (good green) | General success states — use `--success` there |
 
 ### Per-context primary color — the rule
 
@@ -55,13 +61,12 @@ Every top-level view picks **one** primary color and uses it for its main commit
 | View | Primary | Where it shows |
 |---|---|---|
 | **Add** | `--expense` (orange) | Add tab fill, hero currency pill, bottom Save + Scan, KeyboardSaveBar, selected event chip, selected `CategoryQuickPicks` pill |
-| **Income** | `--success` (green) | Income overflow-menu icon, IncomeForm/IncomeEditSheet currency pill, hero amount focus underline, bottom Save bar, KeyboardSaveBar, IncomeRow left-border, year-total label, refresh focus, IncomeRow swipe-panel |
-| **Review** | dual: NEEDS REVIEW uses `--warning` + `--success` (approve chip); EXPENSES edit uses sky-blue `#60a5fa` for `ExpenseEditSheet`'s currency pill and Save button | Review tab fill (sky-blue), edit-sheet Save, Confirm-all button (green) |
-| **LLM** | `--accent` (red) for add, but the screen itself is mostly neutral | `HealthSummaryCard`'s `+`, refresh focus |
+| **Income** | `--income` / `--success` (green) | Income tab fill, IncomeForm currency pill, hero amount underline, bottom Save bar, KeyboardSaveBar, IncomeRow left-border, year-total label |
+| **Review** | `--review` (sky-blue) + `--success` (approve chip) | Review tab fill, edit-sheet Save, Confirm-all button (green) |
+| **Analytics** | `--stat` (indigo) | Analytics tab fill, open-event left-border + dot + OPEN pill, hero card gradient |
+| **LLM** | `--llm` (cyan) | LLM tab fill |
 
-**The Review edit-sheet sky-blue (`#60a5fa`)** is an inline literal (no token yet). If you find yourself needing it elsewhere, promote it to a `--review` token in `base.css` in the same PR.
-
-**Never invent a hue** beyond what's listed. If a new view needs a primary color, pick one of the four above and own it.
+**Never invent a hue** beyond what's listed. Each new view must pick one of the existing per-context tokens.
 
 ## Typography
 

{dinary-1.2.4 → dinary-1.3.0}/specs/ui/screens.md

@@ -1,40 +1,42 @@
 # Screen Anatomy
 
-The four top-level views, their layout, and how the segmented + overflow nav binds them together.
+The five top-level views, their layout, and how the header segmented control binds them together.
 
 ## Navigation
 
-A single **header segmented control** in `App.vue` switches between the four views. There is no bottom tab bar.
+A single **header segmented control** in `App.vue` switches between the five views. There is no bottom tab bar and no overflow menu.
 
 ```
-┌──────────────────────────────────────────────────────────────┐
-│ Dinary v0.10  [⚠ 2 queued]               [+ ] [☰●5] [···]  │ sticky header
-├──────────────────────────────────────────────────────────────┤
-│ Offline — expenses will be queued                            │ optional, sticky
-├──────────────────────────────────────────────────────────────┤
-│                                                              │
-│              active view body                                │
-│                                                              │
-└──────────────────────────────────────────────────────────────┘
+┌────────────────────────────────────────────┐
+│ Dinary        [+][≣][▩][↗][▦]              │  sticky header row
+├────────────────────────────────────────────┤
+│ ⏱ 2 receipts queued        tap to review → │  queue strip (amber), only when queued
+├────────────────────────────────────────────┤
+│ Offline — expenses will be queued          │  offline strip, only when offline
+├────────────────────────────────────────────┤
+│              active view body              │
+└────────────────────────────────────────────┘
 ```
 
 ### Tab inventory (`HeaderSegmented.vue`)
 
-| Tab | Glyph | Size | Inactive look | Active look | Where it lives |
-|---|---|---|---|---|---|
-| **Add** | Plus | 56×38 | `--expense` text on 12 %-alpha orange fill | Solid `--expense` fill + 0 4 12 orange glow | Inline (primary) |
-| **Review** | ListChecks | 56×38 | sky-blue `#60a5fa` on 12 %-alpha blue fill | Solid `#60a5fa` fill + 0 4 12 sky-blue glow | Inline (primary). Warning-amber count badge bottom-right when `doubtfulCount > 0` |
-| **•••** (overflow) | MoreHorizontal | 36×30 | Muted, transparent | `--accent` fill when any rare tab is current | Inline. On tap, opens a 200-px-wide dropdown listing every entry in the `RARE_TABS` const |
-| **Income** | TrendingUp | n/a | n/a — lives inside the dropdown menu only | menu row gets `--surface-2` background + bold | Behind `•••` |
-| **LLM providers** | Cpu | n/a | same | same | Behind `•••` |
+| Tab | key | Glyph (lucide) | Color token | Size |
+|---|---|---|---|---|
+| **Add** | `add` | `Plus` | `--expense` #f97316 | 40×36 |
+| **Review** | `review` | `ListChecks` | `--review` #60a5fa | 40×36 |
+| **Analytics** | `analytics` | `BarChart3` | `--stat` #818cf8 | 40×36 |
+| **Income** | `income` | `TrendingUp` | `--income` #22c55e | 40×36 |
+| **LLM providers** | `llm` | `Cpu` | `--muted` #94a3b8 | 40×36 |
 
-**Rule for the future:** when a rarely-used tab is added, append it to `RARE_TABS` — the header layout stays the same. When a *frequently* used tab is added, see "When to add a new screen" below.
+Each tab button: inactive = `color-mix(in srgb, <tabColor> 14%, transparent)` bg + tab color text. Active = solid tab color fill + `#fff` icon + `0 4px 12px <tabColor>66` glow.
+
+**Rule for the future:** all tabs are peers — no overflow menu. Every new top-level view gets an inline tab.
 
 ### Header chrome
 
-- **Brand + version** (`Dinary v0.10`) on the left.
-- **Queue badge** (`N queued`, warning-yellow pill) appears next to the brand when `queue.items.length + receiptQueue.items.length > 0`. Tap → `QueueModal`.
-- **Offline notice strip** (warning-color text on warning-tinted bg, 1-px border) slides in under the header row when `!isOnline`. Copy adapts by view: `Offline — expenses will be queued` on Add, `Offline — incomes can't be added or edited` on Income, generic `Offline — changes not available` elsewhere.
+- **Brand** (`Dinary`) on the left. Version string removed from header.
+- **Queue strip** — full-width amber strip below the header row, renders only when `queue.items.length + receiptQueue.items.length > 0`. Shows count + "tap to review →". Tap → `QueueModal`. Stacks above the offline strip when both present.
+- **Offline notice strip** — warning-color strip below the queue strip when `!isOnline`. Copy adapts by view: `Offline — expenses will be queued` on Add, `Offline — incomes can't be added or edited` on Income, generic `Offline — changes not available` elsewhere.
 
 ## Add view
 
@@ -111,9 +113,14 @@ Two ways to save:
 
 After save: the form resets but keeps the default group/category and currency. A toast confirms the saved amount.
 
+## Analytics view
+
+Read-only financial summary. Reached via the inline `analytics` tab.
+See `specs/reference/pwa-analytics.md` for content, API contract, and cache policy.
+
 ## Income view
 
-The income-tracking view. New since v0.8 — accessed via the `•••` overflow menu.
+The income-tracking view. Accessed via the inline `income` tab.
 
 ```
 ┌──────────────────────────────────────┐
@@ -316,8 +323,7 @@ Each chip is a thin outlined pill. The strip is informational — no actions.
 
 ## When to add a new view
 
-Adding a fifth segment to the segmented control is a major change — two inline tabs is already a deliberate choice. If the new view is:
+All five tabs are inline peers — icon-only at 40 px, fits at 340 px. A sixth tab would need design review. If the new view is:
 
-- **Heavy, persistent, primary** — promote it inline next to Add + Review (and shrink them slightly). 3 × 56 px is the upper bound that still fits one-handed.
-- **Secondary or rare** — append to `RARE_TABS` in `HeaderSegmented.vue`. Nothing else changes. Pick a glyph the dropdown menu can render at 22 px and an obvious label.
+- **A new primary workflow** — add an inline tab with its own `--<context>` color token.
 - **An admin / settings panel** — push it into the LLM view's pattern (a dedicated screen reachable from elsewhere) or into a sheet, not a top-level slot.

dinary-1.3.0/src/dinary/__about__.py

@@ -0,0 +1 @@
+__version__ = "1.3.0"

dinary-1.3.0/src/dinary/api/analytics.py

@@ -0,0 +1,80 @@
+"""Analytics API: GET /api/analytics/summary"""
+
+import sqlite3
+from datetime import date
+from pathlib import Path
+
+from fastapi import APIRouter, Depends
+
+from dinary.config import settings
+from dinary.db.storage import get_db
+
+router = APIRouter()
+
+_SQL_DIR = Path(__file__).resolve().parent.parent / "db" / "sql"
+_MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]
+
+
+def _sql(name: str) -> str:
+    return (_SQL_DIR / name).read_text()
+
+
+def _fmt(amount: float) -> str:
+    return f"{round(amount):,}".replace(",", " ")
+
+
+def _fmt_date_range(date_from: str | date, date_to: str | date) -> str:
+    df = date.fromisoformat(str(date_from)[:10]) if not isinstance(date_from, date) else date_from
+    dt = date.fromisoformat(str(date_to)[:10]) if not isinstance(date_to, date) else date_to
+    if df.year == dt.year and df.month == dt.month:
+        return f"{df.day}–{dt.day} {_MONTHS[df.month - 1]} {df.year}"
+    if df.year == dt.year:
+        return f"{df.day} {_MONTHS[df.month - 1]}–{dt.day} {_MONTHS[dt.month - 1]} {df.year}"
+    return f"{df.day} {_MONTHS[df.month - 1]} {df.year}–{dt.day} {_MONTHS[dt.month - 1]} {dt.year}"
+
+
+@router.get("/api/analytics/summary")
+def get_analytics_summary(con: sqlite3.Connection = Depends(get_db)) -> dict:  # noqa: B008
+    cur = con.cursor()
+    currency = settings.accounting_currency
+
+    this_month, last_month, ytd_expenses = cur.execute(_sql("analytics_summary.sql")).fetchone()
+    ytd_income = cur.execute(_sql("analytics_ytd_income.sql")).fetchone()[0]
+
+    ytd_savings = ytd_income - ytd_expenses
+    savings_rate = round(ytd_savings * 100 / ytd_income) if ytd_income > 0 else 0
+
+    events = [
+        {
+            "id": r[0],
+            "name": r[1],
+            "date_range": _fmt_date_range(r[2], r[3]),
+            "total": _fmt(r[4]),
+            "currency": currency,
+            "open": bool(r[5]),
+        }
+        for r in cur.execute(_sql("analytics_events.sql")).fetchall()
+    ]
+
+    trend_rows = cur.execute(_sql("analytics_auto_trends.sql")).fetchall()
+    trends = [
+        {
+            "basket_name": r[1],
+            "direction": r[5],
+            "pct": f"{abs(int(r[4]))}%",
+        }
+        for r in trend_rows
+    ] or None
+
+    return {
+        "summary": {
+            "this_month_total": _fmt(this_month),
+            "last_month_total": _fmt(last_month),
+            "ytd_total": _fmt(ytd_expenses),
+            "ytd_savings": _fmt(ytd_savings),
+            "savings_rate": f"{savings_rate}%",
+            "currency": currency,
+        },
+        "events": events,
+        "trends": trends,
+    }

dinary-1.3.0/src/dinary/db/sql/analytics_auto_trends.sql

@@ -0,0 +1,58 @@
+-- Top-5 category groups and tags by % change between the two most recent 3-month windows.
+-- Noise filter: items with MAX(recent, prior) below 15% of the average for their kind
+-- (groups vs tags compared separately so tag amounts aren't swamped by group amounts).
+WITH period_amounts AS (
+    SELECT
+        'group'   AS kind,
+        cg.id,
+        cg.name,
+        COALESCE(SUM(CASE WHEN date(e.datetime) >= date('now', '-3 months')
+                          THEN e.amount ELSE 0 END), 0) AS recent,
+        COALESCE(SUM(CASE WHEN date(e.datetime) <  date('now', '-3 months')
+                           AND date(e.datetime) >= date('now', '-6 months')
+                          THEN e.amount ELSE 0 END), 0) AS prior
+    FROM category_groups cg
+    JOIN categories c ON c.group_id = cg.id AND c.is_active = 1
+    JOIN expenses e    ON e.category_id = c.id
+    WHERE date(e.datetime) >= date('now', '-6 months')
+      AND cg.is_active = 1
+    GROUP BY cg.id, cg.name
+
+    UNION ALL
+
+    SELECT
+        'tag',
+        t.id,
+        t.name,
+        COALESCE(SUM(CASE WHEN date(e.datetime) >= date('now', '-3 months')
+                          THEN e.amount ELSE 0 END), 0),
+        COALESCE(SUM(CASE WHEN date(e.datetime) <  date('now', '-3 months')
+                           AND date(e.datetime) >= date('now', '-6 months')
+                          THEN e.amount ELSE 0 END), 0)
+    FROM tags t
+    JOIN expense_tags et ON et.tag_id = t.id
+    JOIN expenses e      ON e.id = et.expense_id
+    WHERE date(e.datetime) >= date('now', '-6 months')
+      AND t.is_active = 1
+    GROUP BY t.id, t.name
+),
+thresholds AS (
+    SELECT kind,
+           AVG(CASE WHEN recent > prior THEN recent ELSE prior END) * 0.15 AS min_amt
+    FROM period_amounts
+    WHERE recent > 0 OR prior > 0
+    GROUP BY kind
+)
+SELECT
+    p.kind,
+    p.name,
+    p.recent,
+    p.prior,
+    ROUND((p.recent - p.prior) * 100.0 / p.prior) AS pct_change,
+    CASE WHEN p.recent >= p.prior THEN 'up' ELSE 'down' END AS direction
+FROM period_amounts p
+JOIN thresholds t ON t.kind = p.kind
+WHERE p.prior > 0
+  AND (CASE WHEN p.recent > p.prior THEN p.recent ELSE p.prior END) >= t.min_amt
+ORDER BY ABS(p.recent - p.prior) * 1.0 / p.prior DESC
+LIMIT 5

dinary-1.3.0/src/dinary/db/sql/analytics_events.sql

@@ -0,0 +1,12 @@
+SELECT
+    ev.id,
+    ev.name,
+    ev.date_from,
+    ev.date_to,
+    COALESCE(SUM(e.amount), 0)                             AS total,
+    CASE WHEN ev.date_to >= date('now') THEN 1 ELSE 0 END  AS is_open
+FROM events ev
+LEFT JOIN expenses e ON e.event_id = ev.id
+WHERE ev.date_from >= date('now', '-12 months')
+GROUP BY ev.id, ev.name, ev.date_from, ev.date_to
+ORDER BY ev.date_from DESC

dinary-1.3.0/src/dinary/db/sql/analytics_summary.sql

@@ -0,0 +1,8 @@
+SELECT
+    COALESCE(SUM(CASE WHEN strftime('%Y-%m', datetime) = strftime('%Y-%m', 'now')
+                      THEN amount ELSE 0 END), 0) AS this_month,
+    COALESCE(SUM(CASE WHEN strftime('%Y-%m', datetime) = strftime('%Y-%m', 'now', '-1 month')
+                      THEN amount ELSE 0 END), 0) AS last_month,
+    COALESCE(SUM(CASE WHEN strftime('%Y', datetime) = strftime('%Y', 'now')
+                      THEN amount ELSE 0 END), 0) AS ytd_expenses
+FROM expenses

dinary-1.3.0/src/dinary/db/sql/analytics_ytd_income.sql

@@ -0,0 +1,3 @@
+SELECT COALESCE(SUM(amount), 0) AS ytd_income
+FROM income
+WHERE strftime('%Y', income_date) = strftime('%Y', 'now')

{dinary-1.2.4 → dinary-1.3.0}/src/dinary/main.py

@@ -16,6 +16,7 @@ from dinary import __version__
 from dinary.adapters.llm_storage import SqliteLLMBrokerStorage
 from dinary.adapters.llmbroker import LLMBroker
 from dinary.api import (
+    analytics,
     catalog,
     currencies,
     expense_corrections,
@@ -99,6 +100,7 @@ def create_app() -> FastAPI:
         lifespan=_lifespan,
     )
 
+    app.include_router(analytics.router)
     app.include_router(expenses.router)
     app.include_router(expense_corrections.router)
     app.include_router(income.router)