dinary 1.2.3__tar.gz → 1.2.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dinary
-Version: 1.2.3
+Version: 1.2.4
 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.2.4}/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.2.4}/docs/mkdocs.yml

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

dinary-1.2.4/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.2.4}/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.2.4}/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.2.4/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.2.4}/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.2.4}/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.2.4}/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.2.4/specs/plans/analytics-ai.md

@@ -0,0 +1,70 @@
+# 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`.
+
+### 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
+   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,
+   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)`,
+   `save_view(config: dict)`, `delete_view(id)`. Keys in LMDB: `view:<uuid>`.
+
+9. **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):
+    - `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()`
+
+11. **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
+    `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.

dinary-1.2.4/specs/plans/analytics-pwa.md

@@ -0,0 +1,78 @@
+# Analytics — PWA embedded view
+
+## Scope
+
+A dedicated `/analytics` route in the existing Vue PWA. Shows a summary of the
+ledger drawn from the dinary server. Complements the standalone `dinary-analytics`
+app (`analytics-ai.md`) — the PWA view is always-accessible and mobile-friendly;
+the standalone app is where deep exploration and AI interaction happen.
+
+Out of scope: OLTP writes, sheet logging, imports, migrations.
+
+## Data source
+
+New FastAPI endpoints reading dinary SQLite directly. DuckDB is not used on the
+server (1 GB RAM constraint — see `architecture.md`). All queries are plain SQLite
+GROUP BY aggregations.
+
+## Default views (zero configuration)
+
+These views are always present regardless of whether analytics-ai has ever been run.
+
+1. **Monthly trend** — total expenses per month for the selected year, broken down
+   by category group. Query: expenses JOIN categories JOIN category_groups,
+   GROUP BY year_month, group_name.
+
+2. **Events** — all events with total cost in accounting currency, sorted by date
+   descending. Query: expenses JOIN events, GROUP BY event_id.
+
+## Config-driven basket views
+
+When the user has run analytics-ai and saved one or more Analytics Views, those
+views appear as additional tabs in `/analytics`. The PWA has no view editor — the
+standalone app is the only configuration tool.
+
+Config is written by analytics-ai via `PUT /api/analytics/config` and stored in
+`analytics_pwa_config` as a JSON blob under key `views`. The server executes basket
+assignment on request using a parameterised SQLite query; no basket logic lives in
+Python. Basket assignment: for each expense, check event triggers first, then tag
+triggers, first match wins, unmatched go to the default basket.
+
+## Config table
+
+`analytics_pwa_config` in dinary SQLite:
+
+```
+key        TEXT  PRIMARY KEY
+value      JSON
+updated_at TIMESTAMP
+```
+
+Only key in use: `views` — JSON array of view config objects (same schema as
+stored in analytics.db, see `analytics-ai.md`). The server never writes this
+table; only `PUT /api/analytics/config` does.
+
+## Implementation outline
+
+**Backend**
+
+- New FastAPI router `api/analytics.py`.
+- New migration: `analytics_pwa_config` table.
+- `GET /api/analytics/config` — returns current `analytics_pwa_config` rows as JSON.
+- `PUT /api/analytics/config` — replaces one or more keys; called by analytics-ai only.
+- `GET /api/analytics/monthly?year=<year>` — monthly trend data.
+- `GET /api/analytics/events` — events with totals.
+- `GET /api/analytics/view/<view_id>?year=<year>` — executes basket assignment for
+  the named view config stored in `analytics_pwa_config.views`, returns
+  (basket_name, year_month, group_name, amount) rows.
+- New SQL files: `db/sql/analytics_monthly.sql`, `db/sql/analytics_events.sql`,
+  `db/sql/analytics_view.sql` (parameterised basket assignment).
+
+**Frontend**
+
+- New Vue route `/analytics`, new `AnalyticsView.vue`.
+- On load: fetches config + default view data in parallel.
+- Tab bar: "Monthly" tab + "Events" tab always present; one tab per basket view
+  from config (if any).
+- Period selector (year) applies to all tabs.
+- Chart library: to be decided at implementation time — keep it lightweight.