dinary 1.2.3__tar.gz → 1.3.0__tar.gz

{dinary-1.2.3 → dinary-1.3.0}/.github/workflows/ci.yml

@@ -25,6 +25,7 @@ env:
     --junitxml=pytest.xml
     --cov-report=term-missing:skip-covered
     --cov=src
+    --ignore=tests/analytics
     tests/
 
 on:
@@ -90,7 +91,6 @@ jobs:
       with:
         python-version: ${{ env.PRIMARY_PYTHON_VERSION }}
 
-
     - name: Install uv environment
       uses: andgineer/uv-venv@v3
 
@@ -108,8 +108,28 @@ jobs:
     - name: Run JS tests with Allure
       run: npm --prefix webapp test
 
-    - name: Test with pytest and Allure report
-      run: "${{ env.PYTEST_CMD }} --alluredir=./allure-results"
+    - name: Test server with pytest and Allure
+      run: >-
+        python -m pytest
+        --junitxml=pytest.xml
+        --cov=src
+        --cov-report=term-missing:skip-covered
+        --ignore=tests/analytics
+        --alluredir=./allure-results
+        tests/
+
+    - name: Install analytics dependencies
+      run: uv sync --frozen --group analytics
+
+    - name: Test analytics with pytest and Allure
+      run: >-
+        python -m pytest
+        --junitxml=pytest-analytics.xml
+        --cov=src
+        --cov-append
+        --cov-report=term-missing:skip-covered
+        --alluredir=./allure-results
+        tests/analytics/
 
     - name: Load Allure test report history
       uses: actions/checkout@v4

{dinary-1.2.3 → dinary-1.3.0}/.github/workflows/static.yml

@@ -30,5 +30,5 @@ jobs:
         uses: andgineer/uv-venv@v3
 
       - name: Install dependencies
-        run: uv sync --frozen
+        run: uv sync --frozen --group analytics
       - run: pre-commit run --verbose --all-files

{dinary-1.2.3 → 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.3 → dinary-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dinary
-Version: 1.2.3
+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.3 → dinary-1.3.0}/activate.sh

@@ -41,7 +41,7 @@ if [[ ! -d ${VENV_FOLDER} ]] ; then
         if uv venv ${VENV_FOLDER} --python=python${PRIMARY_PYTHON_VERSION}; then
 
             . ${VENV_FOLDER}/bin/activate
-            uv sync --frozen
+            uv sync --frozen --group analytics
             END_TIME=$(date +%s)
             echo "Environment created in $((END_TIME - $START_TIME)) seconds"
         else

{dinary-1.2.3 → dinary-1.3.0}/docs/mkdocs.yml

@@ -49,6 +49,7 @@ extra:
 
 nav:
   - index.md
+  - analytics.md
   - installation.md
   - google-sheets-setup.md
   - pwa-install.md

dinary-1.3.0/docs/src/en/analytics.md

@@ -0,0 +1,33 @@
+# Your Personal Financial Analyst
+
+```bash
+inv analytics
+```
+
+Opens a browser page at `http://localhost:2718` where you can **chat with your own spending data** in plain language — and browse interactive charts while you do it.
+
+Ask things like:
+
+- *"What did I spend most on last month?"*
+- *"How does my food spending compare to last year?"*
+- *"How much did the Italy trip cost, broken down by category?"*
+- *"What's my savings rate for 2025?"*
+
+The analyst knows your full expense history, categories, events, and tags. It queries your local database live — nothing leaves your machine.
+
+## Charts
+
+Alongside the chat, four visual summaries give you the big picture at a glance:
+
+| | What it shows |
+|---|---|
+| **12-month rolling** | Top-10 categories stacked by month, with income and monthly savings |
+| **Year comparison** | Any previous year overlaid on the rolling view |
+| **Event** | Where the money went during a trip or project |
+| **Tag** | Spending pattern for a label (e.g. "work", "dog") across a chosen year |
+
+## Setup
+
+The chat requires a Gemini API key configured as a provider in `.deploy/llm_providers.toml`. Without it, the charts still work — only the chat shows a warning.
+
+The **year comparison**, **tag**, and **tag year** selectors remember your last choice across restarts. The **event** selector always opens on the most recent completed event.

{dinary-1.2.3 → dinary-1.3.0}/docs/src/en/index.md

@@ -18,3 +18,4 @@ Dinary server is a FastAPI backend that:
       - [Your own computer](deploy-selfhost.md) — $0 (Tailscale Funnel or Cloudflare Tunnel)
 3. Set up HTTPS access — see deployment guides above.
 4. [Install the PWA](pwa-install.md) on your phone.
+5. Run `inv analytics` to talk to [your personal financial analyst](analytics.md).

{dinary-1.2.3 → dinary-1.3.0}/docs/src/en/operations.md

@@ -333,7 +333,7 @@ within hours rather than the next morning.
 
 ### Local Yandex.Disk access: `inv setup-yadisk`
 
-`restore-cloud-backup` reads from `yandex:` on whichever machine it
+`restore-yadisk` reads from `yandex:` on whichever machine it
 runs. `inv setup-yadisk` configures that remote locally — on VM 1
 during disaster recovery, or on the operator laptop for debug
 bootstraps:
@@ -346,16 +346,16 @@ Uses the same WebDAV + app-password flow as `inv setup-replica` (no
 browser OAuth needed). Idempotent: skips the prompt if `yandex:` is
 already configured and healthy.
 
-`restore-cloud-backup` calls this automatically when `yandex:` is
+`restore-yadisk` calls this automatically when `yandex:` is
 absent, so running it beforehand is optional.
 
 ## Point-in-time restore from Yandex.Disk
 
 ```bash
-inv restore-cloud-backup --list-only                     # show inventory
-inv restore-cloud-backup                                 # restore latest
-inv restore-cloud-backup --snapshot 2026-03-15           # specific date
-inv restore-cloud-backup --yes                           # skip confirm
+inv restore-yadisk --list-only                     # show inventory
+inv restore-yadisk                                 # restore latest
+inv restore-yadisk --snapshot 2026-03-15           # specific date
+inv restore-yadisk --yes                           # skip confirm
 ```
 
 ### Two intended use cases
@@ -369,10 +369,10 @@ inv restore-cloud-backup --yes                           # skip confirm
   (via SSH) when both the local DB and the Litestream replica on
   VM 2 are unusable. The SSH + `cd ~/dinary` + interactive
   confirmation hops are intentional friction so a one-word
-  `inv restore-cloud-backup` on the wrong terminal cannot silently
+  `inv restore-yadisk` on the wrong terminal cannot silently
   overwrite prod.
 
-`restore-cloud-backup` is **local-only** — it writes to
+`restore-yadisk` is **local-only** — it writes to
 `./data/dinary.db` relative to the cwd and has no `--remote` mode.
 There is no way to invoke it against a remote host from the
 operator machine.
@@ -391,7 +391,7 @@ operator machine.
   present on VM 1 via `inv setup-server`. On macOS: `brew install
   rclone sqlite zstd`.
 - A `yandex:` rclone remote configured locally. If it is absent,
-  **`restore-cloud-backup` prompts automatically** (same WebDAV +
+  **`restore-yadisk` prompts automatically** (same WebDAV +
   app-password flow as `inv setup-replica`). To pre-configure before
   the first restore run: `inv setup-yadisk`.
 
@@ -415,7 +415,7 @@ unusable:
 ssh ubuntu@dinary                       # or the public IP / Tailscale IP
 sudo systemctl stop dinary litestream   # avoid a half-written DB
 cd ~/dinary
-inv restore-cloud-backup --snapshot 2026-03-15
+inv restore-yadisk --snapshot 2026-03-15
 # confirmation prompt: shows row count / size / mtime of the
 # current DB plus compressed size of the incoming snapshot, then
 # asks for literal 'yes'.
@@ -430,7 +430,7 @@ directory (so `./data/dinary.db` is the snapshot, not prod):
 ```bash
 cd /tmp/restore-preview
 mkdir -p data
-inv restore-cloud-backup --snapshot 2026-03-15 --yes
+inv restore-yadisk --snapshot 2026-03-15 --yes
 sqlite3 data/dinary.db 'SELECT COUNT(*) FROM expense'
 ```
 
@@ -448,7 +448,7 @@ To deploy a specific version with a DB restore (e.g. rollback after a bad deploy
 
 ```bash
 inv deploy --ref=v0.4.0 --no-start   # deploy code but skip service start
-inv restore-cloud-backup              # restore DB from Yandex.Disk
+inv restore-yadisk              # restore DB from Yandex.Disk
 inv restart-server                    # start; yoyo applies forward migrations
 ```
 

dinary-1.3.0/docs/src/ru/analytics.md

@@ -0,0 +1,33 @@
+# Персональный финансовый аналитик
+
+```bash
+inv analytics
+```
+
+Открывает страницу в браузере на `http://localhost:2718`, где можно **разговаривать со своими данными о расходах** на обычном языке — и параллельно смотреть интерактивные графики.
+
+Спрашивайте что угодно:
+
+- *«На что я потратил больше всего в прошлом месяце?»*
+- *«Как изменились траты на еду по сравнению с прошлым годом?»*
+- *«Сколько стоила поездка в Белград по категориям?»*
+- *«Какая у меня норма сбережений за 2025 год?»*
+
+Аналитик знает полную историю расходов, категории, события и теги. Запросы выполняются к локальной базе данных — данные никуда не уходят.
+
+## Визуальные сводки
+
+Рядом с чатом — четыре диаграммы для быстрого взгляда на картину в целом:
+
+| | Что показывает |
+|---|---|
+| **Скользящие 12 месяцев** | Топ-10 категорий по месяцам, доходы и ежемесячная экономия |
+| **Сравнение по годам** | Любой прошлый год рядом с текущим |
+| **По событию** | Куда ушли деньги во время поездки или проекта |
+| **По тегу** | Структура трат по метке («работа», «собака» и т.д.) за выбранный год |
+
+## Настройка
+
+Чат требует API-ключ Gemini, настроенный как провайдер в `.deploy/llm_providers.toml`. Без него диаграммы работают в штатном режиме — только в области чата появляется предупреждение.
+
+Селекторы **сравнения лет**, **тега** и **года тега** запоминают выбор между запусками. Селектор **события** всегда открывается на последнем завершённом событии.

{dinary-1.2.3 → dinary-1.3.0}/docs/src/ru/index.md

@@ -19,3 +19,4 @@ Dinary server — бэкенд на FastAPI, который:
 3. Первоначально загружается [Классификатор](taxonomy.md) который вы далее можете корректировать
 4. Настройте HTTPS-доступ — см. инструкции по деплою выше.
 4. [Установите PWA](pwa-install.md) на телефон.
+5. Запустите `inv analytics` — своего [персонального финансового аналитика](analytics.md).

{dinary-1.2.3 → dinary-1.3.0}/docs/src/ru/operations.md

@@ -346,7 +346,7 @@ UTC уже через несколько часов, а не следующим
 
 ### Локальный доступ к Яндекс.Диску: `inv setup-yadisk`
 
-`restore-cloud-backup` читает из `yandex:` на той машине, где
+`restore-yadisk` читает из `yandex:` на той машине, где
 запущена. `inv setup-yadisk` настраивает этот remote локально — на
 VM 1 при disaster recovery или на ноутбуке для отладочного
 бутстрапа:
@@ -359,16 +359,16 @@ inv setup-yadisk
 setup-replica`, — браузерный OAuth не нужен. Идемпотентна:
 пропускает промпт, если `yandex:` уже настроен и работает.
 
-`restore-cloud-backup` вызывает её автоматически при отсутствии
+`restore-yadisk` вызывает её автоматически при отсутствии
 `yandex:`, так что ручной запуск заранее необязателен.
 
 ## Восстановление на конкретную дату из Яндекс.Диска
 
 ```bash
-inv restore-cloud-backup --list-only                     # список снапшотов
-inv restore-cloud-backup                                 # восстановить самый свежий
-inv restore-cloud-backup --snapshot 2026-03-15           # конкретную дату
-inv restore-cloud-backup --yes                           # без подтверждения
+inv restore-yadisk --list-only                     # список снапшотов
+inv restore-yadisk                                 # восстановить самый свежий
+inv restore-yadisk --snapshot 2026-03-15           # конкретную дату
+inv restore-yadisk --yes                           # без подтверждения
 ```
 
 ### Два предполагаемых сценария
@@ -382,10 +382,10 @@ inv restore-cloud-backup --yes                           # без подтвер
   (через SSH), когда и локальная БД, и Litestream-реплика на VM 2
   непригодны. Тройная защита «SSH + `cd ~/dinary` + интерактивное
   подтверждение» — это намеренное трение, чтобы одним словом
-  `inv restore-cloud-backup` в случайном терминале нельзя было
+  `inv restore-yadisk` в случайном терминале нельзя было
   молча затереть прод.
 
-`restore-cloud-backup` — **local-only**: пишет в `./data/dinary.db`
+`restore-yadisk` — **local-only**: пишет в `./data/dinary.db`
 относительно cwd, режима `--remote` нет. Запустить задачу на
 удалённом хосте с операторской машины невозможно.
 
@@ -403,7 +403,7 @@ inv restore-cloud-backup --yes                           # без подтвер
   есть через `inv setup-server`. На macOS: `brew install rclone
   sqlite zstd`.
 - Настроен удалённый `yandex:` в rclone. Если его нет,
-  **`restore-cloud-backup` сам запросит авторизацию** (та же схема
+  **`restore-yadisk` сам запросит авторизацию** (та же схема
   WebDAV + app-пароль, что у `inv setup-replica`). Для
   предварительной настройки до первого restore: `inv setup-yadisk`.
 
@@ -427,7 +427,7 @@ inv restore-cloud-backup --yes                           # без подтвер
 ssh ubuntu@dinary                       # или публичный IP / Tailscale IP
 sudo systemctl stop dinary litestream   # чтобы не получить наполовину переписанную БД
 cd ~/dinary
-inv restore-cloud-backup --snapshot 2026-03-15
+inv restore-yadisk --snapshot 2026-03-15
 # промпт подтверждения: печатает row count / size / mtime текущей
 # БД плюс сжатый размер входящего снапшота и требует напечатать
 # буквально 'yes'.
@@ -442,7 +442,7 @@ inv verify-db                           # integrity + FK check
 ```bash
 cd /tmp/restore-preview
 mkdir -p data
-inv restore-cloud-backup --snapshot 2026-03-15 --yes
+inv restore-yadisk --snapshot 2026-03-15 --yes
 sqlite3 data/dinary.db 'SELECT COUNT(*) FROM expense'
 ```
 
@@ -461,7 +461,7 @@ sqlite3 data/dinary.db 'SELECT COUNT(*) FROM expense'
 
 ```bash
 inv deploy --ref=v0.4.0 --no-start   # задеплоить код, сервис не запускать
-inv restore-cloud-backup              # восстановить БД с Яндекс.Диска
+inv restore-yadisk              # восстановить БД с Яндекс.Диска
 inv restart-server                    # запустить; yoyo применит прямые миграции
 ```
 

{dinary-1.2.3 → dinary-1.3.0}/pyproject.toml

@@ -57,6 +57,9 @@ search_path = ["src", "."]
 [tool.ruff]
 line-length = 99
 
+[tool.ruff.lint]
+per-file-ignores = { "src/dinary_analytics/notebooks/*.py" = ["PLC0415", "N803", "N806", "B018"] }
+
 [tool.ruff.lint.pylint]
 max-args = 8
 
@@ -82,6 +85,15 @@ dev = [
     "pytest-timeout>=2.3.1",
     "zensical>=0.0.41",
 ]
+analytics = [
+    "duckdb>=1.2.0",
+    "lmdb>=1.6.0",
+    "marimo>=0.10.0",
+    "google-genai>=1.0.0",
+    "mcp>=1.9.0",
+    "altair>=5.0.0",
+    "polars>=1.0.0",
+]
 
 [project.scripts]
 dinary = "dinary.main:main"

dinary-1.3.0/specs/plans/analytics-ai.md

@@ -0,0 +1,77 @@
+# Analytics AI — implementation plan
+
+See `specs/reference/analytics-ai.md` for architecture, storage design, LLM
+strategy, invariants, and Analytics Views design.
+
+## Remaining deliverables
+
+### Template notebooks and extended dashboard
+
+1. `notebooks/events.py` — event/trip cost breakdown notebook.
+2. `notebooks/tags.py` — tag-bucket comparison notebook.
+3. `dashboard.py` extended to full configurable widget set.
+
+### MCP server extensions
+
+4. `get_config(key)` and `set_config(key, value)` tools in `mcp_server.py`.
+
+---
+
+### AI Views feature
+
+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.
+
+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.
+
+7. **`settings.py` extensions** — `list_view_ids() → list[str]`, `get_view(id)`,
+   `save_view(config: dict)`, `delete_view(id)`. Keys in LMDB: `view:<uuid>`.
+
+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.
+
+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
+    - `update_basket(name, event_ids, tag_ids)` → modifies a basket in the draft
+    - `remove_basket(name)` → removes a basket from the draft
+    - `set_chart_type(type)` → updates draft chart type
+    - `save_current_view(name)` → persists draft via `settings.save_view()`
+    - `delete_view(id)` → removes a saved view via `settings.delete_view()`
+
+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.
+
+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.
+
+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.3.0/specs/reference/analytics-ai.md

@@ -0,0 +1,201 @@
+# Analytics standalone app
+
+## Scope
+
+A standalone application installed locally by each user. Opens a browser dashboard
+(Marimo in `run` mode — no code visible), provides a natural-language AI chat, and
+connects to the dinary ledger via a local read-only replica. Non-technical users
+see a clean web app; power users additionally connect Claude Code or Claude Desktop
+via the MCP server.
+
+Out of scope: OLTP writes, sheet logging, imports, migrations, API surface.
+
+## Repository placement
+
+`src/dinary_analytics/` alongside `src/dinary/` in the monorepo root. One-way
+dependency: `dinary_analytics` imports from `dinary`; `dinary` never imports
+from `dinary_analytics`. Heavy deps (DuckDB, Polars, Marimo, LLM SDKs) live in
+the `analytics` dependency group in the root `pyproject.toml`.
+
+`uv sync` on the laptop installs everything. The deploy task runs
+`uv sync --no-dev --no-group analytics` on VM 1, keeping the server image lean.
+
+## Package structure
+
+```
+src/dinary_analytics/
+  connection.py       # read-only DuckDB ATTACH to ledger-replica.db
+  mcp_server.py       # MCP server: DuckDB queries + analytics.db writes
+  settings.py         # analytics.db read/write (LMDB)
+  backup.py           # analytics.db backup/restore CLI
+  queries/            # named .sql files for reusable analytical queries
+  notebooks/
+    dashboard.py      # main app: charts + Gemini chat + AI views
+    events.py         # event/trip cost breakdown
+    tags.py           # tag-bucket comparison
+```
+
+## Runtime directory
+
+`.analytics/` at the repo root, gitignored. Created on first `inv analytics`.
+
+```
+.analytics/
+  ledger-replica.db     # read-only SQLite replica of dinary ledger
+  analytics.db          # app database: view configs, history (LMDB)
+```
+
+## Storage
+
+### ledger-replica.db
+
+Read-only SQLite replica of the dinary server DB. Synced on every `inv analytics`
+run before Marimo starts. DuckDB opens it with `ATTACH ... (READ_ONLY)` — never
+writable.
+
+### analytics.db — LMDB
+
+Holds: analytics view configs, dashboard configurations, LLM conversation history.
+DuckDB never stores application state; any materialized caches there are disposable
+and regenerated from the replica.
+
+`analytics.db` must be backed up. `ledger-replica.db` is reproducible and excluded
+from backup.
+
+## SQL-first design
+
+Analytical business logic lives in SQL executed by DuckDB, not in Python DataFrames.
+Python owns orchestration, plotting, and LLM glue. Keeps queries portable to
+DuckDB-WASM without rewrite.
+
+## LLM strategy
+
+**Default — Gemini Free API.** Built into the Marimo dashboard chat. User provides
+a Google AI Studio API key. The model receives the ledger schema and executes DuckDB
+queries via tool calls.
+
+**Power users — Claude Code / Claude Desktop via MCP.** User connects their Claude
+subscription to the `dinary-analytics` MCP server. Claude can answer arbitrary
+questions and reconfigure dashboards (view configs, widget order) by writing to
+`analytics.db`.
+
+## inv analytics
+
+Single entry point. On every run:
+
+1. Syncs `ledger-replica.db` from the dinary server.
+2. Starts the MCP server.
+3. Opens `notebooks/dashboard.py` via `marimo run`.
+
+## MCP server
+
+- `query(sql)` — read-only DuckDB query against the ledger replica, returns JSON.
+- `schema()` — ledger schema for LLM context.
+- `get_config(key)` — reads a config entry from `analytics.db`.
+- `set_config(key, value)` — writes a config entry to `analytics.db`.
+- `list_views()`, `get_view(id)`, `save_view(config)`, `delete_view(id)` — manage analytics view configs.
+
+`set_config` and the view management tools are the only write paths to `analytics.db`.
+
+## PWA integration
+
+View configs and tag bucket definitions sync to the PWA via `PUT /api/analytics/config`
+on the dinary server (see `analytics-pwa.md`).
+
+## Runtime tiers
+
+**Tier 1 — laptop/desktop (primary).** `inv analytics` opens Marimo in the browser.
+Full AI integration. Zero extra services.
+
+**Tier 2 — DuckDB-WASM in browser (deferred).** SQL-first design keeps this
+achievable without rewrite.
+
+## Invariants
+
+- Analytics is strictly read-only against `ledger.*`. `ATTACH (READ_ONLY)` enforced at connection level.
+- `dinary` server package never depends on `dinary_analytics`.
+- DuckDB is a query engine only — no application state stored there.
+- `analytics.db` is the sole write target for configs and history.
+
+---
+
+## Analytics Views
+
+### Concept
+
+An analytics view is a named, reusable grouping configuration that organises expenses
+into user-defined baskets for charting. Each view is live: when opened it re-executes
+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
+expenses. A basket matches an expense if any of its trigger conditions are met (OR
+logic within triggers). Priority is first-match: an expense is assigned to the first
+basket whose triggers match it.
+
+Basket triggers:
+- `events` — list of event IDs: matches any expense belonging to those events.
+- `tags` — list of tag IDs: matches any expense carrying any of those tags.
+
+Within each basket the breakdown by category group is always available as a
+drill-down.
+
+View config stored in `analytics.db` under key `view:<uuid>`:
+
+```json
+{
+  "id": "<uuid>",
+  "name": "По смыслу жизни",
+  "baskets": [
+    { "name": "Релокация", "triggers": { "events": [3], "tags": [] } },
+    { "name": "Путешествия", "triggers": { "events": [], "tags": [7] } }
+  ],
+  "default_basket": "Основное",
+  "chart_type": "stacked_bar_monthly"
+}
+```
+
+### LLM interaction model
+
+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: "Релокация —
+45k за 3 мес (40% квартала), выделил в отдельный блок." The user never has to name
+categories, events, or tags.
+
+**Refining a view.** The user expresses dissatisfaction about what they see in the
+chart ("поездки выглядят странно"). The LLM consults the data and proposes specific
+alternatives: "Могу объединить все поездки в один блок Путешествия — тогда видна
+общая сумма за год. Или оставить детализацию с итоговой строкой. Что ближе?" The
+user only approves or redirects; the LLM modifies the config via in-session tools
+and the chart re-renders immediately.
+
+Users never compose basket definitions by naming categories or writing rules. The
+LLM does this from data.