Submit Small Shop Ledger to Build Small Hackathon

.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.gguf
+*.csv
+*.log
+modal-volume/

.gitmessage

@@ -0,0 +1,3 @@
+Subject line
+
+Co-authored-by: OpenAI Codex <codex@openai.com>

ARCHITECTURE.md

@@ -0,0 +1,259 @@
+# Architecture
+
+Small Shop Ledger is a small-model Gradio app that turns messy shop
+notes into structured ledger rows, insights, and follow-up actions.
+
+## System Overview
+
+```text
+User text/audio/document
+    |
+    v
+Gradio UI (`shop_ledger/ui.py`)
+    |
+    +--> local mode: `LedgerProcessor`
+    |
+    +--> Modal mode: `LedgerAgent().process.remote(...)`
+              |
+              v
+       `LedgerProcessor`
+              |
+              +--> llama.cpp backend (`LlamaLedgerBackend`)
+              |
+              +--> heuristic fallback
+              |
+              v
+       `LedgerResult`
+              |
+              v
+Dashboard, ledger table, automation queue, CSV export
+```
+
+## Code Map
+
+| File | Responsibility |
+| --- | --- |
+| `app.py` | Local Gradio entrypoint. |
+| `modal_app.py` | Modal image, volume, GPU worker, ASGI app, model download, smoke tests. |
+| `shop_ledger/ui.py` | Gradio Blocks UI, input selection, callbacks, CSV export. |
+| `shop_ledger/schema.py` | Pydantic models for ledger entries and model results. |
+| `shop_ledger/llama_backend.py` | llama.cpp prompt, model loading, JSON parsing. |
+| `shop_ledger/processor.py` | Runtime mode selection and fallback handling. |
+| `shop_ledger/heuristics.py` | Deterministic parser for mock/dev/fallback mode. |
+| `shop_ledger/insights.py` | Dashboard metrics, risk flags, follow-up queue, breakdown tables. |
+| `tests/` | Unit tests for extraction, processor fallback, input-choice behavior, and insights. |
+
+## Data Flow
+
+1. The user enters a written note, records/uploads a voice note, or uploads a
+   receipt/bill image or PDF.
+2. If multiple inputs are present and `Auto` is selected, the UI asks the user
+   to choose which input to analyze.
+3. Audio input is transcribed locally with `faster-whisper` when available.
+4. Documents are prepared locally: PDFs are rendered into page images with
+   PyMuPDF, uploaded images are resized with Pillow, and both become base64
+   data URLs.
+5. The chosen note text is sent to `LedgerProcessor`.
+6. In Modal production, `LedgerProcessor` uses `LlamaLedgerBackend`.
+7. `LlamaLedgerBackend` asks Gemma through llama.cpp to return strict JSON,
+   using multimodal `image_url` message parts when document images are present.
+8. The result is validated by `LedgerResult` and `LedgerEntry`, then tagged
+   with the readable `LLAMA_MODEL_LABEL` when llama.cpp was used.
+9. Rows are appended to Gradio state.
+10. The app recomputes:
+   - ledger table
+   - dashboard metrics
+   - field intelligence
+   - dynamic insight graph plan
+   - daily shop-pulse brief
+   - local ledger question answer
+   - shop pulse timeline
+   - counterparty memory
+   - anomaly scan
+   - closing checklist
+   - Plotly insight figures
+   - automation queue
+   - review queue
+   - category and party tables
+   - CSV export
+11. The analyzed input is cleared so the next note starts cleanly.
+
+## Model Contract
+
+The model must return JSON shaped like:
+
+```json
+{
+  "entries": [
+    {
+      "date": "YYYY-MM-DD or empty",
+      "direction": "expense|income|transfer|unknown",
+      "counterparty": "person or business",
+      "item": "what changed hands",
+      "quantity": "quantity if known",
+      "amount": 0,
+      "currency": "LKR",
+      "category": "inventory|utilities|rent|wages|transport|maintenance|sales|general expense|uncategorized",
+      "payment_status": "paid|due|partial|unknown",
+      "due_date": "",
+      "reminder": "short follow-up reminder or empty",
+      "confidence": 0.0,
+      "original_note": "source fragment"
+    }
+  ],
+  "reminders": ["short reminders"],
+  "questions": ["only ask if an amount, person, or due date is unclear"],
+  "cleaned_note": "normalized note"
+}
+```
+
+The schema intentionally tolerates `null` for text fields by converting it to an
+empty string. This prevents valid model intent from failing because of minor
+JSON style differences.
+
+## Fallback Design
+
+The app keeps a deterministic heuristic parser for three reasons:
+
+1. Local UI development should work without downloading a 12B model.
+2. The live demo should never go completely blank if model loading fails.
+3. Tests can verify app behavior quickly.
+
+Fallback is visible. If llama.cpp fails, `model_used` becomes something like:
+
+```text
+heuristic fallback (ValidationError)
+```
+
+The exception details are added to `questions` so the UI and smoke tests expose
+the reason.
+
+## Insights Engine
+
+`shop_ledger/insights.py` is pure Python and deterministic. It computes:
+
+- net cash
+- paid income
+- paid expenses
+- due income
+- due expenses
+- open follow-ups
+- average extraction confidence
+- top categories
+- top parties
+- high-value due risk flags
+- low-confidence risk flags
+- chart plan selection
+- daily brief generation with Gemma or local fallback
+- Ask My Ledger answers from structured rows with Gemma or local fallback
+- voice questions for Ask My Ledger
+- command palette actions
+- counterparty memory cards
+- anomaly detection
+- daily closing checklist
+- timeline events and pulse chart
+- Plotly figures for due radar, spend pressure, cashflow, confidence review,
+  category mix, and party exposure
+- follow-up queue with cadence and scripts
+- reply studio variants for polite, friendly, and firm reminders
+- review queue for low-confidence or incomplete rows
+- daily field note
+
+The chart planner is deterministic first. It asks what matters most right now:
+unpaid money, expense pressure, cashflow timeline, review risk, or overall
+category mix. Keeping insights separate from the Gradio UI makes the dashboard
+testable and leaves room for a later local-LLM chart selector.
+
+## UI Structure
+
+The UI is a dark, custom-styled Gradio Blocks app organized as a small-shop
+operating cockpit.
+
+Top status strip:
+
+- model status
+- row count
+
+Shop OS Cockpit:
+
+- `Capture` rail: written note, voice note, document upload, input selector,
+  currency, add/clear actions, conflict notice, and examples.
+- `Shop Pulse` center: live KPIs, chart composer, chart director, themed Plotly
+  graph wall, pulse timeline, and field intelligence.
+- `Ledger Assistant` rail: running totals, reminders, Gemma daily brief, full
+  Ask My Ledger chat, voice questions, prompt suggestions, command palette, and
+  daily closing ritual.
+
+Action Inbox:
+
+- follow-up automation cards
+- review desk cards
+- anomaly lantern cards
+- reply/review/anomaly tables inside a secondary accordion
+
+Workbenches:
+
+- `People`: counterparty memory, trust pulse, party totals, and next-message
+  suggestions.
+- `Ledger Archive`: raw ledger rows, CSV export, category heatmap, closing
+  checklist table, and timeline event table.
+
+See `UI_DESIGN.md` for the layout rationale, CSS hooks, and demo flow.
+
+## Modal Production Path
+
+The live Modal path is:
+
+```text
+fastapi_app
+  -> build_demo(process_fn=process_remote)
+  -> LedgerAgent().process.remote(note, currency)
+  -> LedgerProcessor.from_env()
+  -> LlamaLedgerBackend(...)
+  -> llama_cpp.Llama.create_chat_completion(...)
+```
+
+The model worker is configured with:
+
+```text
+gpu=A10
+cpu=8
+memory=32768
+timeout=1800
+LLAMA_N_GPU_LAYERS=-1
+LLAMA_N_CTX=2048
+LLAMA_MODEL_LABEL=unsloth/gemma-4-12b-it-GGUF / gemma-4-12b-it-UD-Q4_K_XL.gguf / llama.cpp
+```
+
+## Testing Strategy
+
+Current tests cover:
+
+- heuristic parsing
+- processor fallback behavior
+- text/audio input-choice rules
+- field-clearing callback behavior
+- dashboard metrics
+- chart-plan selection
+- Plotly figure generation
+- follow-up queue priority
+- reply studio message variants
+- review queue generation
+- risk flags
+
+Run:
+
+```bash
+python3 -m unittest discover -s tests
+python3 -m compileall shop_ledger app.py modal_app.py tests
+```
+
+## Known Constraints
+
+- Gradio state is session-local. This is enough for the hackathon demo but not a
+  multi-user accounting product.
+- CSV export is generated per session.
+- Voice transcription uses local `faster-whisper` only when available.
+- The app is not a replacement for accounting, tax, legal, or financial advice.
+- The app should not store sensitive customer data without adding auth and
+  persistence controls.

DEPLOYMENT.md

@@ -0,0 +1,255 @@
+# Deployment And Modal Runbook
+
+Small Shop Ledger runs as a Gradio web app on Modal. The UI is served by a
+lightweight ASGI web function, while llama.cpp inference runs in a separate GPU
+worker that keeps the GGUF model warm between requests.
+
+## Production URLs
+
+- Live app: <https://keshan--voice-notes-shop-ledger-fastapi-app.modal.run>
+- Modal app name: `voice-notes-shop-ledger`
+- Modal model volume: `voice-notes-shop-ledger-models`
+- GitHub repo: <https://github.com/keshan/voice-notes-shop-ledger>
+
+The Modal and GitHub slugs still use the original project identifier so the
+existing deployment URL and model volume remain stable.
+
+## Modal Architecture
+
+`modal_app.py` defines four Modal objects:
+
+| Object | Type | Purpose |
+| --- | --- | --- |
+| `download_model` | `@app.function` | Downloads the GGUF from Hugging Face into the persistent Modal volume. |
+| `LedgerAgent` | `@app.cls` | GPU-backed llama.cpp worker used for extraction. |
+| `smoke_test_model` | `@app.function` | Runs one extraction inside Modal and reports model/runtime metadata. |
+| `fastapi_app` | `@app.function` + `@modal.asgi_app()` | Serves the Gradio UI and calls `LedgerAgent`. |
+
+The web function and model worker are separated intentionally:
+
+- The web layer stays responsive and cheap.
+- The model worker gets GPU, CPU, and memory resources.
+- The GGUF can stay loaded in a warm worker between Gradio requests.
+- The UI can still render even if model inference is cold-starting.
+
+## Runtime Choices
+
+| Setting | Value | Why |
+| --- | --- | --- |
+| Base image | `nvidia/cuda:12.8.1-devel-ubuntu24.04` | CUDA-compatible runtime for llama.cpp GPU inference. |
+| Python | `3.12` | Matches local development and Modal image setup. |
+| GPU | Modal `A10` | Enough VRAM for a 12B-class quantized GGUF demo. |
+| Model repo | `unsloth/gemma-4-12b-it-GGUF` | Gemma 4 12B GGUF distribution. |
+| Model file | `gemma-4-12b-it-UD-Q4_K_XL.gguf` | Good quality/performance quant for the hackathon demo. |
+| Runtime | `llama-cpp-python` CUDA wheel | Avoids source-building llama.cpp during deploy. |
+| Charts | `plotly>=6.0,<7` | Renders dynamic Gradio `Plot` dashboards. |
+| Documents | PyMuPDF + Pillow + Gemma vision | Renders PDFs/images locally, then sends data URLs to llama.cpp multimodal chat. |
+| GPU layers | `LLAMA_N_GPU_LAYERS=-1` | Offload all possible layers to GPU. |
+| Context | `LLAMA_N_CTX=2048` | Keeps ledger extraction responsive. |
+
+The source-build path for CUDA llama.cpp was tested, but it failed during image
+build because `libcuda.so.1` is only available on GPU runtime machines, not
+during the Modal image build. The prebuilt CUDA wheel is therefore the reliable
+deployment path for this app.
+
+## First-Time Setup
+
+Install and authenticate Modal:
+
+```bash
+pip install modal
+modal setup
+```
+
+Download the model into the persistent Modal volume:
+
+```bash
+modal run modal_app.py::download_model
+```
+
+This downloads:
+
+```text
+repo: unsloth/gemma-4-12b-it-GGUF
+file: gemma-4-12b-it-UD-Q4_K_XL.gguf
+target: /models/model.gguf
+```
+
+You can confirm the volume contents:
+
+```bash
+modal volume ls voice-notes-shop-ledger-models
+```
+
+Expected files include:
+
+```text
+model.gguf
+gemma-4-12b-it-UD-Q4_K_XL.gguf
+```
+
+## Deploy
+
+Stop the currently deployed app when you want a clean redeploy:
+
+```bash
+modal app stop voice-notes-shop-ledger
+```
+
+Deploy the app:
+
+```bash
+modal deploy modal_app.py
+```
+
+Modal prints the live `.modal.run` URL after deployment.
+
+## Smoke Test
+
+Run the Modal smoke test:
+
+```bash
+modal run modal_app.py::smoke
+```
+
+A healthy run should print a result shaped like:
+
+```text
+{
+  "model_used": "unsloth/gemma-4-12b-it-GGUF / gemma-4-12b-it-UD-Q4_K_XL.gguf / llama.cpp",
+  "entry_count": 2,
+  "amounts": [1200.0, 750.0],
+  "questions": [],
+  "gpu_type": "A10"
+}
+```
+
+If `model_used` starts with `heuristic fallback`, the app is not using the
+llama.cpp model for that request. Check the `questions` field; fallback errors
+are deliberately surfaced there.
+
+## Logs
+
+View app logs:
+
+```bash
+modal app logs voice-notes-shop-ledger
+```
+
+Useful signals:
+
+- `llama_context` lines mean llama.cpp loaded the GGUF.
+- `model_used` showing `unsloth/gemma-4-12b-it-GGUF` means model extraction
+  succeeded and the UI is showing the human model label rather than the mounted
+  filename.
+- `heuristic fallback (missing GGUF model)` means the volume does not contain
+  `/models/model.gguf`.
+- `heuristic fallback (ValidationError)` usually means the model returned JSON
+  that did not match the schema.
+- Blank charts usually mean Plotly is missing from the image or the deployed UI
+  has not been refreshed after a code push.
+- Empty document extraction usually means the uploaded file type was unsupported
+  or multimodal llama.cpp inference failed.
+
+## Local Development
+
+Run without a model:
+
+```bash
+python app.py
+```
+
+This uses heuristic mode by default. It is useful for UI work and tests.
+
+Run locally with a GGUF:
+
+```bash
+export LEDGER_MODEL_MODE=llama
+export LLAMA_GGUF_PATH=/path/to/gemma-4-12b-it-UD-Q4_K_XL.gguf
+export LLAMA_N_GPU_LAYERS=0
+python app.py
+```
+
+On a laptop without GPU-compatible llama.cpp, keep `LLAMA_N_GPU_LAYERS=0`.
+
+## Environment Variables
+
+| Variable | Used by | Default on Modal | Purpose |
+| --- | --- | --- | --- |
+| `LEDGER_MODEL_MODE` | `LedgerProcessor` | `llama` | Selects `llama` or `mock` mode. |
+| `LLAMA_GGUF_PATH` | `LlamaLedgerBackend` | `/models/model.gguf` | Path to the model file. |
+| `LLAMA_MODEL_LABEL` | `LlamaLedgerBackend` | `unsloth/gemma-4-12b-it-GGUF / gemma-4-12b-it-UD-Q4_K_XL.gguf / llama.cpp` | Human-readable label shown in the UI and smoke tests. |
+| `LLAMA_N_GPU_LAYERS` | `LlamaLedgerBackend` | `-1` | Number of layers to offload to GPU. |
+| `LLAMA_N_CTX` | `LlamaLedgerBackend` | `2048` | llama.cpp context window. |
+| `WHISPER_MODEL_SIZE` | `transcribe_audio` | `tiny` | Local faster-whisper model size for voice notes. |
+
+## Operational Notes
+
+- The app intentionally does not call cloud LLM APIs.
+- Modal is infrastructure only; inference happens inside the deployed
+  llama.cpp worker.
+- The `A10` worker may cold-start. The UI can load before the first model
+  request finishes.
+- The Gradio web function uses `max_containers=1` so the UI state and queue are
+  easier to reason about during the demo.
+- The model volume is persistent. Redeploying the app does not redownload the
+  GGUF unless you run `download_model` again.
+
+## Troubleshooting
+
+### The app says heuristics were used
+
+Run:
+
+```bash
+modal run modal_app.py::smoke
+```
+
+Then check:
+
+- Does `model_used` include `unsloth/gemma-4-12b-it-GGUF`?
+- Does `modal volume ls voice-notes-shop-ledger-models` show `model.gguf`?
+- Does the printed `questions` list include a schema or validation error?
+
+### CPU inference is too slow
+
+Make sure the deployed code has:
+
+```python
+gpu="A10"
+```
+
+on `LedgerAgent` and `smoke_test_model`, plus:
+
+```text
+LLAMA_N_GPU_LAYERS=-1
+```
+
+### CUDA wheel crashes
+
+The deployed version currently uses the prebuilt CUDA `llama-cpp-python` wheel
+from:
+
+```text
+https://abetlen.github.io/llama-cpp-python/whl/cu125
+```
+
+If that wheel becomes incompatible, the fallback plan is:
+
+1. Try a different CUDA wheel index supported by `llama-cpp-python`.
+2. Build from source inside an image with the CUDA driver stub library available
+   at link time.
+3. Temporarily use CPU mode only for UI demos while debugging.
+
+## Hackathon Submission Checklist
+
+- Live Modal URL works.
+- GitHub repo is public.
+- Demo video shows text or voice note -> ledger -> dashboard -> automation
+  queue -> CSV export.
+- Submission mentions:
+  - Gemma 4 12B parameter count.
+  - GGUF quantization.
+  - llama.cpp runtime.
+  - No external LLM API.
+  - Modal GPU deployment.

FIELD_NOTES.md

@@ -0,0 +1,113 @@
+# Field Notes
+
+## Person
+
+Primary user to validate with before submission:
+
+- Role: small shop owner, family-run store operator, market seller, or parent
+  tracking small household/shop dues.
+- Current tool: notebook scraps, WhatsApp messages, voice notes, memory, or a
+  rough spreadsheet.
+- Evidence to add: first name or pseudonym, shop/context, one quote, and one
+  screenshot or short clip of them trying the app.
+
+## Problem
+
+They track small purchases, supplier payments, customer dues, and reminders in
+messy notes or voice messages. The problem is not accounting complexity; it is
+the daily friction of turning rough notes into something they can review later.
+
+## What We Built
+
+Tagline: Messy notes in. Clear books by closing time.
+
+Small Shop Ledger turns a note like:
+
+```text
+paid Ravi 1200 for rice bags, customer Nimal owes 750 for tea packets, remind me Friday
+```
+
+into ledger rows, totals, and follow-up reminders.
+
+It also accepts receipts, bills, note photos, and PDFs. PDFs are rendered into
+page images locally, and Gemma reads the document visually through llama.cpp's
+multimodal chat input.
+
+The current version is organized as a Shop OS Cockpit:
+
+- Net cash, cash in, cash out, due amount, open follow-ups, and average
+  extraction confidence.
+- A chart director that chooses the most useful graph for the current ledger:
+  dues, expenses, cashflow, confidence review, or category mix.
+- A Gemma-generated daily shop pulse that summarizes cash position, pressure,
+  and the next follow-up from structured rows.
+- Ask My Ledger for natural questions such as who owes the most or where cash
+  went, grounded in the structured rows.
+- Voice questions for Ask My Ledger, so the shopkeeper can speak a question
+  after entering the day’s notes.
+- A command palette for fast unpaid scans, WhatsApp follow-ups, risk checks,
+  cash summaries, and QuickBooks-style export planning.
+- People Memory cards that summarize trust, due balances, usual categories, and
+  the next message per customer or supplier.
+- Anomaly Lantern warnings for unusually large amounts, missing values,
+  high-value dues, repeat unpaid parties, and low-confidence rows.
+- A Shop Pulse Timeline that turns raw rows into the story of the day.
+- A Daily Closing Ritual that turns the ledger into an end-of-day checklist.
+- Category and counterparty breakdowns.
+- Risk flags for high-value dues and low-confidence extraction.
+- Ready-to-send follow-up scripts with suggested cadence and three tones:
+  polite, friendly, and firm.
+- A Review Desk for low-confidence or incomplete rows, with simple questions
+  the shopkeeper can answer before exporting.
+
+## Small Model Fit
+
+This is a structured extraction and rewriting task. A 12B-class model is enough
+when the schema is narrow and the UI keeps the workflow grounded.
+
+## What To Test With The User
+
+- Can they enter a note faster than opening a spreadsheet?
+- Do the extracted rows match what they meant?
+- Are the categories useful?
+- Do reminders feel helpful or annoying?
+- Would they use the CSV export?
+
+## Real-User Evidence Checklist
+
+Before the final hackathon submission, capture:
+
+- 3 raw notes from the user, with private details anonymized.
+- 1 voice note or receipt/photo if they naturally use those.
+- Extraction accuracy before correction: rows right, rows needing review, rows
+  wrong.
+- Time-to-ledger compared with their current method.
+- One thing they would actually use tomorrow.
+- One thing they found confusing or unnecessary.
+- One quote that explains why this helps in their words.
+
+## Demo Video Beats
+
+1. Show the messy note or voice note.
+2. Click "Add to ledger".
+3. Show the Shop Pulse center updating clean rows, totals, charts, and the
+   timeline without leaving the cockpit.
+4. Generate the daily shop pulse and read the short practical summary.
+5. Ask "Who owes me most?" and show the answer.
+6. Ask the same question by voice.
+7. Run the command palette for unpaid rows or QuickBooks export planning.
+8. Show the Action Inbox with follow-ups, review rows, and anomalies.
+9. Open People and show a counterparty profile.
+10. Open the Ledger Archive and show the raw table, closing checklist, and CSV
+   export.
+11. Point out the model badge showing the actual Gemma GGUF model label.
+12. Export CSV.
+
+## Lessons
+
+To fill after testing:
+
+- What the small model handled well:
+- What the human correction loop caught:
+- What changed in the app because of the user:
+- What should not be automated:

README.md

@@ -1,13 +1,235 @@
 ---
 title: Small Shop Ledger
-emoji: 🐨
-colorFrom: red
-colorTo: blue
+emoji: 🧾
+colorFrom: green
+colorTo: yellow
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
+sdk_version: 5.50.0
 app_file: app.py
 pinned: false
+license: mit
+short_description: Messy shopkeeper notes in. Clear books by closing time.
+tags:
+  - build-small-hackathon
+  - gradio
+  - llama-cpp
+  - local-first
+  - finance
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Small Shop Ledger
+
+Messy notes in. Clear books by closing time.
+
+A small-model Gradio app for turning messy shopkeeper notes into a clean ledger.
+
+The app accepts pasted notes and optional voice notes, extracts expenses/income,
+assigns categories, tracks due items, and drafts follow-up reminders. It is built
+for the Build Small hackathon's Backyard AI trail: a specific, practical helper
+for a real person who keeps money notes in scraps, voice messages, or memory.
+
+## Why This Fits The Brief
+
+- **Specific problem:** small shop owners and parents often record purchases,
+  credit, supplier payments, and customer dues in unstructured notes.
+- **Small-model fit:** extraction, categorization, and reminder drafting fit well
+  inside a 12B-class instruction model.
+- **No cloud inference APIs:** the language model runs through `llama.cpp` via
+  `llama-cpp-python`.
+- **Gradio canvas:** the whole interface is a Gradio app.
+- **Custom cockpit UI:** the app uses a dark Shop OS layout with persistent
+  capture, pulse, and assistant zones instead of default Gradio tabs.
+- **Modal GPU deployment:** `modal_app.py` serves the Gradio UI and runs
+  llama.cpp inference on a Modal `A10` GPU worker.
+
+## Features
+
+- Paste messy notes such as `paid Ravi 1200 for rice bags, remind me Friday`.
+- Record or upload a voice note; optional local Whisper transcription handles it.
+- Upload receipts, bills, note photos, or PDFs; PDFs are rendered to page
+  images and Gemma reads the visual document content through llama.cpp.
+- Work inside a custom Shop OS Cockpit: a capture rail, live Shop Pulse center,
+  sticky ledger assistant, Action Inbox, People workbench, and Ledger Archive.
+- Extract structured ledger rows with amount, party, item, category, status, and
+  confidence.
+- See the actual Gemma/GGUF model label in the app instead of the internal
+  mounted filename.
+- See a live dashboard for net cash, cash in, cash out, due amount, follow-ups,
+  and average extraction confidence.
+- Let the app pick an insight graph based on the ledger state: unpaid dues,
+  expense pressure, cashflow over time, confidence review, or category mix. The
+  Plotly charts use the same dark ledger theme as the rest of the app.
+- Generate a Gemma-powered "today's shop pulse" from the structured ledger rows.
+- Ask local ledger questions in a dedicated chat such as "Who owes me most?",
+  "What should I follow up today?", and "Where did cash go?"
+- Ask the ledger by voice; local transcription turns a spoken question into a
+  grounded ledger answer.
+- Run a Ledger Command Palette for unpaid rows, WhatsApp follow-ups, risk scan,
+  cash summary, and QuickBooks-style export planning.
+- Compose charts from plain-language questions with a safe Gemma/local chart
+  selector.
+- Review People Memory cards for customers and suppliers, with due status,
+  usual category, and suggested next message.
+- Scan the Anomaly Lantern for high-value dues, missing amounts, repeat unpaid
+  parties, and low-confidence rows.
+- View a Shop Pulse Timeline that turns rows into a visual story of cash in,
+  cash out, dues, and logged events.
+- Close the day with a Daily Closing Ritual checklist before export.
+- Review field intelligence: top category, most active party, biggest entry,
+  watch-list risks, and a daily field note.
+- Use the automation queue to turn due items into follow-up actions, reminder
+  cadence, and ready-to-send polite, friendly, or firm message scripts.
+- Review low-confidence or incomplete rows in a dedicated Review Desk before
+  exporting the CSV.
+- Export the ledger as CSV.
+- Run with a heuristic dev fallback before downloading a large GGUF model.
+
+## Project Layout
+
+```text
+app.py                 Local Gradio entrypoint
+modal_app.py           Modal deployment entrypoint
+shop_ledger/           App logic, UI, model backends
+tests/                 Unit tests for parsing and processing
+ARCHITECTURE.md        System architecture and data flow
+UI_DESIGN.md           Custom Gradio cockpit layout and UX rules
+ROADMAP.md             Future feature ideas and next sprint options
+FIELD_NOTES.md         Hackathon report starter
+DEPLOYMENT.md          Modal deployment notes
+```
+
+## Local Setup
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python3 app.py
+```
+
+By default the app runs in `mock` mode. Set `LEDGER_MODEL_MODE=llama` and point
+`LLAMA_GGUF_PATH` at a local GGUF file to use llama.cpp:
+
+```bash
+export LEDGER_MODEL_MODE=llama
+export LLAMA_GGUF_PATH=/path/to/gemma-4-12b-it-UD-Q4_K_XL.gguf
+python3 app.py
+```
+
+## Tests
+
+```bash
+python3 -m unittest discover -v
+```
+
+Install `requirements.txt` first so the Plotly-backed insight tests can import
+the dashboard code.
+
+## Hugging Face Space Setup
+
+The hackathon submission should point to a Hugging Face Gradio Space. This repo
+can run directly as a Space because `app.py` launches the Gradio Blocks app.
+
+For a lightweight Space demo, leave `LEDGER_MODEL_MODE=mock`. For the full
+small-model path on a GPU Space, set:
+
+| Variable | Example |
+| --- | --- |
+| `LEDGER_MODEL_MODE` | `llama` |
+| `LLAMA_GGUF_REPO` | `unsloth/gemma-4-12b-it-GGUF` |
+| `LLAMA_GGUF_FILE` | `gemma-4-12b-it-UD-Q4_K_XL.gguf` |
+| `LLAMA_MODEL_LABEL` | `unsloth/gemma-4-12b-it-GGUF / gemma-4-12b-it-UD-Q4_K_XL.gguf / llama.cpp` |
+| `LLAMA_N_GPU_LAYERS` | `-1` |
+| `LLAMA_N_CTX` | `2048` |
+
+If `LLAMA_GGUF_PATH` is set, it wins. That keeps the Modal deployment using its
+mounted model volume while allowing a Space to resolve the GGUF from Hugging
+Face Hub.
+
+## Modal Deployment
+
+See [DEPLOYMENT.md](DEPLOYMENT.md) for the full Modal runbook.
+
+Short version:
+
+```bash
+pip install modal
+modal setup
+modal run modal_app.py::download_model
+modal deploy modal_app.py
+```
+
+The production Modal deployment uses a GPU worker for llama.cpp inference:
+
+- GPU: Modal `A10`
+- Runtime: `llama-cpp-python` CUDA wheel
+- Model: `unsloth/gemma-4-12b-it-GGUF`
+- Quant: `gemma-4-12b-it-UD-Q4_K_XL.gguf`
+
+Smoke test the GPU model path:
+
+```bash
+modal run modal_app.py::smoke
+```
+
+Expected signal:
+
+```text
+model_used: unsloth/gemma-4-12b-it-GGUF / gemma-4-12b-it-UD-Q4_K_XL.gguf / llama.cpp
+gpu_type: A10
+```
+
+The app reads these environment variables:
+
+| Variable | Purpose |
+| --- | --- |
+| `LEDGER_MODEL_MODE` | `mock` or `llama` |
+| `LLAMA_GGUF_PATH` | Local path to a GGUF model |
+| `LLAMA_GGUF_REPO` | Optional Hugging Face repo to download a GGUF on startup |
+| `LLAMA_GGUF_FILE` | Optional GGUF filename inside `LLAMA_GGUF_REPO` |
+| `LLAMA_MODEL_LABEL` | Human-readable model label shown in the UI |
+| `LLAMA_N_GPU_LAYERS` | Number of llama.cpp layers to offload, `-1` on Modal |
+| `LLAMA_N_CTX` | llama.cpp context window, `2048` on Modal |
+| `WHISPER_MODEL_SIZE` | Optional faster-whisper model size, defaults to `tiny` |
+
+The Gradio dashboard uses Plotly figures, so Modal installs `plotly>=6.0,<7`
+inside the same image as the UI.
+
+Document upload stays off-grid too: PDFs are rendered with PyMuPDF, images are
+encoded as local data URLs, and Gemma 4 12B receives them through llama.cpp's
+multimodal `image_url` chat message format.
+
+## Model Notes
+
+The configured Modal model is
+[`unsloth/gemma-4-12b-it-GGUF`](https://huggingface.co/unsloth/gemma-4-12b-it-GGUF)
+with `gemma-4-12b-it-UD-Q4_K_XL.gguf`. The model card lists Gemma 4 12B
+Unified at 11.95B parameters, which is inside the hackathon's <=32B constraint.
+
+The implementation deliberately avoids external LLM APIs so the demo can earn
+the local-first/off-grid spirit of the hackathon. Modal is used for deployment,
+not as a hosted inference API.
+
+## Demo Flow
+
+1. Add a messy text or voice note.
+2. Upload a receipt/photo/PDF and show it entering the same ledger flow.
+3. Point to the Shop Pulse center: net cash, due amount, dynamic chart, and
+   timeline update without leaving the cockpit.
+4. Ask "Who owes me most?" in the sticky ledger assistant rail.
+5. Generate the daily brief and run a command palette action.
+6. Show the Action Inbox with follow-ups, review items, and anomaly signals.
+7. Open People to show counterparty memory.
+8. Open Ledger Archive and export the CSV.
+
+## More Docs
+
+- [Architecture](ARCHITECTURE.md): code map, data flow, model contract,
+  fallback behavior, and testing strategy.
+- [UI Design](UI_DESIGN.md): Shop OS Cockpit layout, workbench model, CSS hooks,
+  and demo flow.
+- [Deployment](DEPLOYMENT.md): Modal GPU deployment, model volume, smoke tests,
+  logs, and troubleshooting.
+- [Roadmap](ROADMAP.md): dynamic graphs, modern dashboard layout, daily briefs,
+  review mode, counterparty cards, and other future ideas.
+- [Field Notes](FIELD_NOTES.md): hackathon report starter and demo beats.

ROADMAP.md

@@ -0,0 +1,276 @@
+# Roadmap And Feature Ideas
+
+This app is strongest when it feels like a tiny night-shift co-pilot for a real
+shopkeeper: practical, tactile, and a little magical. The ideas below keep that
+theme while pushing the demo toward a more modern, world-class experience.
+
+## Highest-Impact Next Features
+
+### 1. Dynamic Insight Graphs
+
+Status: shipped in the first enhancement sprint.
+
+Generate charts based on the ledger rows and the current question the app thinks
+is most important. The app now has a deterministic chart planner and Plotly
+graphs for due radar, spend pressure, cashflow, confidence review, category mix,
+and people exposure.
+
+Examples:
+
+- If dues are high: show a due-by-counterparty bar chart.
+- If expenses dominate: show expense category breakdown.
+- If many rows exist across dates: show cashflow over time.
+- If confidence is low: show a review queue chart.
+
+Implemented path:
+
+- Added a chart planner in `shop_ledger/insights.py`.
+- Let deterministic rules pick a chart first.
+- Rendered charts with Gradio `Plot` and Plotly.
+
+Future path:
+
+- Optionally ask the local LLM to choose between safe chart specs.
+- Add user-selectable chart questions such as "who owes me most?" or "what is
+  eating cash?"
+
+### 2. Ledger Command Center Layout
+
+Status: shipped in the Shop OS Cockpit sprint.
+
+Rearrange the UI into a more modern operational console:
+
+- Left rail: input capture and session status.
+- Center: active dashboard cards and chart.
+- Right rail: follow-up queue and risk alerts.
+- Bottom: raw ledger table.
+
+The app now has a three-zone cockpit:
+
+- Capture rail for text, audio, documents, currency, examples, and conflict
+  handling.
+- Shop Pulse center for KPIs, dynamic charts, timeline, and field intelligence.
+- Ledger Assistant rail for daily brief, Ask My Ledger, voice questions,
+  command palette, reminders, and closing ritual.
+
+Supporting workflows are grouped into an Action Inbox plus People and Ledger
+Archive workbenches instead of one tab per feature.
+
+### 3. LLM-Generated Daily Brief
+
+Status: shipped in the Daily Brief enhancement sprint.
+
+After every few entries, generate a short "shopkeeper briefing":
+
+```text
+Today cash is negative because inventory spend is high. Nimal and Saman need
+follow-up. Tea packets are the biggest open due item.
+```
+
+The dashboard now has a "Today's Shop Pulse" panel. It shows a local fallback
+brief immediately and can call Gemma through the Modal llama.cpp worker for a
+short practical summary from structured rows.
+
+### 4. Voice Reply Studio
+
+Status: shipped in the second enhancement sprint.
+
+For every due item, generate three reply styles:
+
+- polite
+- firm
+- friendly/local
+
+The automation queue now generates polite, friendly, and firm scripts for each
+due item. The user can copy the right tone into WhatsApp or SMS. This is very
+demoable and directly useful.
+
+### 5. Mistake Review Mode
+
+Status: shipped in the third enhancement sprint.
+
+Add a "Review low-confidence rows" panel:
+
+- show rows below confidence threshold
+- ask simple correction questions
+- update the row in session state
+
+The app now has a Review Desk tab that shows low-confidence or incomplete rows
+and asks simple correction questions. A future version can make those questions
+editable and write corrections back into session state.
+
+## Futuristic But Still Practical
+
+### 6. Shop Pulse Timeline
+
+Status: shipped in the Pulse Timeline enhancement sprint.
+
+Convert the ledger into a visual day timeline:
+
+```text
+09:20 inventory spend
+10:45 sale logged
+13:10 customer due
+17:30 utility bill
+```
+
+The app now includes a Pulse Timeline tab with story cards, a Plotly pulse
+chart, and a structured event table. This makes messy notes feel like a story
+of the day.
+
+### 7. Counterparty Memory Cards
+
+Status: shipped in the memory-card enhancement sprint.
+
+Create small profiles for each person or supplier:
+
+- total paid
+- total due
+- last interaction
+- usual category
+- suggested next message
+
+This is useful for small shops where trust and memory matter more than formal
+accounting.
+
+The app now includes People Memory cards and a counterparty table with trust
+pulse, due amount, usual category, last item, and suggested next message.
+
+### 8. What Changed Since Yesterday?
+
+If persistence is added, the app can summarize:
+
+- new dues
+- cleared dues
+- rising expense categories
+- repeat late payers
+- unusual entries
+
+This becomes a daily habit rather than a one-off tool.
+
+### 9. "Ask My Ledger"
+
+Status: shipped in the Ask My Ledger enhancement sprint.
+
+A local natural-language query box:
+
+```text
+Who owes me the most?
+What did I spend on inventory?
+What should I follow up today?
+```
+
+The dashboard now includes a question box. Common questions are answered
+deterministically from structured rows, and Modal production can route the same
+rows to Gemma for a concise local/off-grid answer.
+
+### 10. Tiny Forecasts
+
+Use simple local forecasting, not a big ML system:
+
+- expected cash-in if dues are paid
+- likely week-end cash position
+- category spend trend
+
+This adds value without leaving the small-model spirit.
+
+## Additional Shipped Ideas
+
+### Ledger Command Palette
+
+Status: shipped.
+
+The dashboard now has a command palette for unpaid rows, WhatsApp follow-ups,
+risk scans, cash summaries, and QuickBooks-style export planning.
+
+### AI Chart Composer
+
+Status: shipped.
+
+The chart wall now accepts plain-language chart questions. Modal production can
+ask Gemma to choose from safe chart specs; local mode uses deterministic rules.
+
+### Anomaly Lantern
+
+Status: shipped.
+
+The app now flags high-value dues, missing amounts, low-confidence rows,
+unusually large entries, and repeat unpaid parties.
+
+### Shopkeeper Voice Mode
+
+Status: shipped.
+
+Ask My Ledger now supports spoken questions using the same local transcription
+path as voice notes.
+
+### Daily Closing Ritual
+
+Status: shipped.
+
+The app now includes an end-of-day checklist and closing summary for cash,
+dues, review items, anomalies, and export readiness.
+
+## Hackathon Merit Badge Opportunities
+
+### Off The Grid
+
+Already aligned:
+
+- no cloud LLM API
+- llama.cpp runtime
+- GGUF model
+
+### Llama Champion
+
+Already aligned:
+
+- `llama-cpp-python`
+- GGUF model
+- Modal GPU worker
+
+### Off-Brand
+
+Aligned:
+
+- custom dark UI
+- Shop OS Cockpit layout
+- persistent assistant rail
+- action inbox
+- themed Plotly graph wall
+- People and Ledger Archive workbenches
+
+Next step:
+
+- richer CSS
+- possible custom Gradio frontend layer if the installed Gradio version exposes
+  the needed APIs in the future
+
+### Field Notes
+
+Already started:
+
+- `FIELD_NOTES.md`
+
+Next step:
+
+- add real user interview notes
+- add before/after screenshots
+- add demo observations
+
+## Recommended Next Sprint
+
+Build these in order:
+
+1. Dynamic charts in the Dashboard tab.
+2. Right-side automation queue preview beside the note input.
+3. LLM-generated daily brief.
+4. Review mode for low-confidence rows.
+5. Counterparty memory cards.
+
+That gives the app an impressive demo arc:
+
+```text
+messy note -> clean ledger -> live dashboard -> smart chart -> follow-up script
+-> daily brief -> CSV export
+```

UI_DESIGN.md

@@ -0,0 +1,147 @@
+# UI Design And Layout System
+
+Small Shop Ledger is organized as a small-shop operating cockpit, not a
+generic Gradio demo. The layout is designed for a shopkeeper who wants to move
+from messy capture to concrete action without hunting through many equal tabs.
+
+Product tagline: Messy notes in. Clear books by closing time.
+
+## Product Shape
+
+The screen is split into four operating zones:
+
+```text
+Status strip
+  Model status, row count, and session health
+
+Shop OS Cockpit
+  Capture rail | Shop Pulse center | Ledger Assistant rail
+
+Action Inbox
+  Follow-ups, review items, and anomaly signals
+
+Workbenches
+  People memory and ledger archive
+```
+
+This keeps the most common loop visible:
+
+1. Capture a note, voice clip, or document.
+2. Watch the ledger pulse update.
+3. Ask the assistant what matters.
+4. Clear actions before exporting.
+
+## Cockpit Layout
+
+### Capture Rail
+
+The left rail owns all intake:
+
+- written note
+- voice note
+- document upload
+- input conflict selector
+- currency
+- add and clear controls
+- example notes
+
+The rail stays sticky on desktop because the user should always be able to add
+the next note without scrolling back to the top. On mobile it becomes a normal
+stack.
+
+### Shop Pulse Center
+
+The center column is the primary attention area:
+
+- live KPI dashboard
+- chart composer
+- chart director
+- main Plotly graph
+- supporting signal graphs
+- shop pulse timeline
+- field intelligence
+
+This is where the app turns ledger rows into a story. The chart composer lets
+Gemma or the deterministic fallback pick a safe chart spec from a plain-language
+question, while the timeline makes the day feel visible.
+
+### Ledger Assistant Rail
+
+The right rail is a persistent co-pilot:
+
+- running totals and reminders
+- LLM Daily Brief
+- full Ask My Ledger chat
+- voice question mode
+- prompt suggestions
+- command palette
+- daily closing ritual
+
+The assistant rail is sticky on desktop because questions and actions should be
+available while the user scans charts, reminders, or the archive.
+
+## Action Inbox
+
+The Action Inbox merges three previously separate areas:
+
+- follow-up automation
+- review desk
+- anomaly lantern
+
+The user-facing cards appear first. The heavier operational tables are tucked
+inside an accordion for demos and deeper inspection. This avoids making the app
+look like a spreadsheet while preserving the export/review detail.
+
+## Workbenches
+
+The remaining tabs are intentionally few:
+
+| Workbench | Purpose |
+| --- | --- |
+| People | Counterparty memory, trust pulse, and party totals. |
+| Ledger Archive | Raw ledger rows, CSV export, categories, closing checklist, and event table. |
+
+This replaces the older one-tab-per-feature structure. Features now live where
+the user expects them rather than competing as top-level destinations.
+
+## Styling Rules
+
+- Dark theme is the default.
+- Cards use an 8px radius and thin ledger-colored borders.
+- The app avoids a single-hue palette: green means money/healthy, gold means
+  attention, red means risk, and blue means insight.
+- Plotly figures inherit the same background, grid, and hover label treatment.
+- Raw data tables are secondary surfaces, not the first thing the user sees.
+- Desktop uses a three-zone cockpit; mobile collapses into one column.
+
+## Demo Flow
+
+For the hackathon video, the recommended flow is:
+
+1. Add a messy text note.
+2. Upload a bill or receipt.
+3. Point to the Shop Pulse center: KPIs, graph, and timeline update.
+4. Ask "Who owes me most?" in the assistant rail.
+5. Generate the daily brief.
+6. Show the Action Inbox with follow-up/review/anomaly cards.
+7. Open People to show memory cards.
+8. Open Ledger Archive and export CSV.
+
+## Implementation Map
+
+The layout lives in `shop_ledger/ui.py`.
+
+Important CSS hooks:
+
+- `#cockpit-shell`
+- `#input-dock`
+- `#pulse-core`
+- `#assistant-rail`
+- `#action-inbox`
+- `#action-grid`
+- `#workbench-tabs`
+- `#people-workbench`
+- `#ledger-archive`
+
+The insight content still comes from `shop_ledger/insights.py`, which keeps
+layout and business logic separated.

app.py

@@ -0,0 +1,9 @@
+import os
+
+from shop_ledger.ui import build_demo
+
+
+if __name__ == "__main__":
+    demo = build_demo()
+    port = int(os.getenv("PORT") or os.getenv("GRADIO_SERVER_PORT") or "8051")
+    demo.launch(server_port=port)

modal_app.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import modal
+
+
+APP_NAME = "voice-notes-shop-ledger"
+MODEL_DIR = "/models"
+DEFAULT_MODEL_FILE = "model.gguf"
+DEFAULT_GGUF_REPO = "unsloth/gemma-4-12b-it-GGUF"
+DEFAULT_GGUF_FILE = "gemma-4-12b-it-UD-Q4_K_XL.gguf"
+MODEL_LABEL = f"{DEFAULT_GGUF_REPO} / {DEFAULT_GGUF_FILE} / llama.cpp"
+GPU_TYPE = "A10"
+
+app = modal.App(APP_NAME)
+volume = modal.Volume.from_name("voice-notes-shop-ledger-models", create_if_missing=True)
+
+image = (
+    modal.Image.from_registry("nvidia/cuda:12.8.1-devel-ubuntu24.04", add_python="3.12")
+    .entrypoint([])
+    .apt_install("build-essential", "cmake", "git", "libsndfile1", "ninja-build")
+    .pip_install(
+        "fastapi[standard]>=0.115,<0.116",
+        "gradio>=5.5,<6",
+        "huggingface-hub>=0.36,<1",
+        "pandas>=2.2,<3",
+        "plotly>=6.0,<7",
+        "PyMuPDF>=1.24,<2",
+        "Pillow>=10,<12",
+        "pydantic>=2.9,<3",
+        "faster-whisper>=1.1,<2",
+    )
+    .run_commands(
+        "pip install --no-cache-dir --force-reinstall --prefer-binary --only-binary=:all: "
+        "'llama-cpp-python>=0.3.16,<0.4' "
+        "--extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu125"
+    )
+    .env(
+        {
+            "PYTHONPATH": "/root",
+            "LEDGER_MODEL_MODE": "llama",
+            "LLAMA_GGUF_PATH": f"{MODEL_DIR}/{DEFAULT_MODEL_FILE}",
+            "LLAMA_MODEL_LABEL": MODEL_LABEL,
+            "LLAMA_N_GPU_LAYERS": "-1",
+            "LLAMA_N_CTX": "2048",
+            "WHISPER_MODEL_SIZE": "tiny",
+        }
+    )
+    .add_local_dir("shop_ledger", remote_path="/root/shop_ledger")
+)
+
+
+@app.function(image=image, volumes={MODEL_DIR: volume}, timeout=3600)
+def download_model(repo_id: str = DEFAULT_GGUF_REPO, filename: str = DEFAULT_GGUF_FILE) -> str:
+    """Download a GGUF model from Hugging Face into a persistent Modal volume."""
+    from huggingface_hub import hf_hub_download
+
+    target_path = Path(MODEL_DIR) / DEFAULT_MODEL_FILE
+    downloaded_path = hf_hub_download(
+        repo_id=repo_id,
+        filename=filename,
+        local_dir=MODEL_DIR,
+        local_dir_use_symlinks=False,
+    )
+    source = Path(downloaded_path)
+    if source != target_path:
+        target_path.write_bytes(source.read_bytes())
+    volume.commit()
+    return f"Downloaded {repo_id}/{filename} to {target_path}"
+
+
+@app.cls(
+    image=image,
+    volumes={MODEL_DIR: volume},
+    gpu=GPU_TYPE,
+    cpu=8,
+    memory=32768,
+    timeout=1800,
+)
+class LedgerAgent:
+    @modal.enter()
+    def load(self) -> None:
+        from shop_ledger.processor import LedgerProcessor
+
+        volume.reload()
+        self.processor = LedgerProcessor.from_env()
+
+    @modal.method()
+    def process(self, note: str, currency: str = "LKR", image_urls: list[str] | None = None) -> dict:
+        result = self.processor.process(note, currency=currency, image_urls=image_urls)
+        return result.model_dump(mode="json")
+
+    @modal.method()
+    def daily_brief(self, rows: list[dict], currency: str = "LKR") -> dict:
+        return self.processor.daily_brief(rows, currency=currency)
+
+    @modal.method()
+    def ask_ledger(self, rows: list[dict], question: str, currency: str = "LKR") -> dict:
+        return self.processor.ask_ledger(rows, question, currency=currency)
+
+    @modal.method()
+    def choose_chart(self, rows: list[dict], question: str) -> dict:
+        return self.processor.choose_chart(rows, question)
+
+
+@app.function(image=image, volumes={MODEL_DIR: volume}, gpu=GPU_TYPE, cpu=8, memory=32768, timeout=1800)
+def smoke_test_model() -> dict:
+    """Run a sample ledger extraction inside Modal and return model metadata."""
+    from shop_ledger.processor import LedgerProcessor
+
+    volume.reload()
+    processor = LedgerProcessor.from_env()
+    result = processor.process(
+        "paid Ravi 1200 for rice bags, customer Nimal owes 750 for tea packets",
+        currency="LKR",
+    )
+    return {
+        "model_used": result.model_used,
+        "entry_count": len(result.entries),
+        "amounts": [entry.amount for entry in result.entries],
+        "statuses": [entry.payment_status for entry in result.entries],
+        "questions": result.questions,
+        "gpu_type": GPU_TYPE,
+    }
+
+
+@app.function(image=image, max_containers=1, timeout=600)
+@modal.concurrent(max_inputs=50)
+@modal.asgi_app()
+def fastapi_app():
+    from fastapi import FastAPI
+    from gradio.routes import mount_gradio_app
+    from shop_ledger.ui import build_demo
+
+    web_app = FastAPI(title="Small Shop Ledger")
+
+    def process_remote(note: str, currency: str, image_urls: list[str] | None = None) -> dict:
+        return LedgerAgent().process.remote(note, currency, image_urls)
+
+    def daily_brief_remote(rows: list[dict], currency: str) -> dict:
+        return LedgerAgent().daily_brief.remote(rows, currency)
+
+    def ask_ledger_remote(rows: list[dict], question: str, currency: str) -> dict:
+        return LedgerAgent().ask_ledger.remote(rows, question, currency)
+
+    def choose_chart_remote(rows: list[dict], question: str) -> dict:
+        return LedgerAgent().choose_chart.remote(rows, question)
+
+    demo = build_demo(
+        process_fn=process_remote,
+        daily_brief_fn=daily_brief_remote,
+        ask_ledger_fn=ask_ledger_remote,
+        chart_composer_fn=choose_chart_remote,
+    )
+    return mount_gradio_app(app=web_app, blocks=demo, path="/")
+
+
+@app.local_entrypoint()
+def main(repo_id: str = DEFAULT_GGUF_REPO, filename: str = DEFAULT_GGUF_FILE) -> None:
+    print(download_model.remote(repo_id, filename))
+
+
+@app.local_entrypoint()
+def smoke() -> None:
+    print(smoke_test_model.remote())

requirements.txt

@@ -0,0 +1,10 @@
+fastapi[standard]>=0.115,<0.116
+gradio>=5.5,<6
+huggingface-hub>=0.36,<1
+llama-cpp-python>=0.3.16,<0.4
+pandas>=2.2,<3
+plotly>=6.0,<7
+PyMuPDF>=1.24,<2
+Pillow>=10,<12
+pydantic>=2.9,<3
+faster-whisper>=1.1,<2

shop_ledger/__init__.py

@@ -0,0 +1,5 @@
+"""Small Shop Ledger."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

shop_ledger/heuristics.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import re
+from datetime import date
+
+from shop_ledger.schema import Direction, LedgerEntry, LedgerResult, PaymentStatus
+
+
+AMOUNT_RE = re.compile(
+    r"(?:(?:rs\.?|lkr|රු)\s*)?(\d[\d,]*(?:\.\d{1,2})?)", re.IGNORECASE
+)
+SPLIT_RE = re.compile(
+    r"\s*(?:[.;\n]|,\s*(?=(?:paid|bought|sold|got|received|customer|supplier|owes|owe|due)\b))\s*",
+    re.IGNORECASE,
+)
+
+CATEGORY_KEYWORDS = {
+    "inventory": ("rice", "tea", "milk", "flour", "sugar", "packet", "bags", "stock", "goods"),
+    "utilities": ("electric", "water", "wifi", "internet", "phone", "bill"),
+    "rent": ("rent", "lease"),
+    "wages": ("salary", "wage", "helper", "staff", "worker"),
+    "transport": ("bus", "fuel", "petrol", "diesel", "delivery", "transport", "tuk"),
+    "maintenance": ("repair", "fix", "paint", "clean", "replace"),
+    "sales": ("sold", "sale", "customer", "received", "got"),
+}
+
+DUE_WORDS = ("owes", "owe", "due", "credit", "later", "unpaid", "balance")
+PAID_WORDS = ("paid", "bought", "spent", "gave", "settled")
+INCOME_WORDS = ("sold", "received", "got", "collected", "customer paid")
+
+
+def heuristic_extract(note: str, currency: str = "LKR") -> LedgerResult:
+    cleaned = " ".join(note.strip().split())
+    if not cleaned:
+        return LedgerResult(cleaned_note="", questions=["Add a note first."])
+
+    parts = [part.strip(" ,") for part in SPLIT_RE.split(note) if part.strip(" ,")]
+    entries: list[LedgerEntry] = []
+    reminders: list[str] = []
+
+    for part in parts:
+        amount_match = AMOUNT_RE.search(part)
+        amount = float(amount_match.group(1).replace(",", "")) if amount_match else 0.0
+        lowered = part.lower()
+        direction = infer_direction(lowered)
+        status = infer_status(lowered, direction)
+        counterparty = infer_counterparty(part)
+        item = infer_item(part)
+        category = infer_category(lowered, direction)
+        reminder = infer_reminder(part, counterparty, amount, currency, status)
+
+        if reminder:
+            reminders.append(reminder)
+
+        entries.append(
+            LedgerEntry(
+                date=date.today().isoformat(),
+                direction=direction,
+                counterparty=counterparty,
+                item=item,
+                amount=amount,
+                currency=currency,
+                category=category,
+                payment_status=status,
+                reminder=reminder,
+                confidence=0.58 if amount else 0.34,
+                original_note=part,
+            )
+        )
+
+    questions = []
+    if any(entry.amount == 0 for entry in entries):
+        questions.append("Some rows have no amount. Ask the user to confirm the missing value.")
+    if any(not entry.counterparty for entry in entries):
+        questions.append("Some rows have no person or business name.")
+
+    return LedgerResult(
+        entries=entries,
+        reminders=reminders,
+        questions=questions,
+        cleaned_note=cleaned,
+        model_used="heuristic",
+    )
+
+
+def infer_direction(text: str) -> Direction:
+    if any(word in text for word in INCOME_WORDS):
+        return Direction.income
+    if any(word in text for word in PAID_WORDS):
+        return Direction.expense
+    if any(word in text for word in DUE_WORDS):
+        return Direction.income
+    return Direction.unknown
+
+
+def infer_status(text: str, direction: Direction) -> PaymentStatus:
+    if any(word in text for word in DUE_WORDS):
+        return PaymentStatus.due
+    if direction in (Direction.expense, Direction.income):
+        return PaymentStatus.paid
+    return PaymentStatus.unknown
+
+
+def infer_category(text: str, direction: Direction) -> str:
+    for category, keywords in CATEGORY_KEYWORDS.items():
+        if any(keyword in text for keyword in keywords):
+            return category
+    if direction == Direction.income:
+        return "sales"
+    if direction == Direction.expense:
+        return "general expense"
+    return "uncategorized"
+
+
+def infer_counterparty(text: str) -> str:
+    patterns = [
+        r"\b(?:paid|gave|from|to|customer|supplier)\s+([A-Z][A-Za-z.'-]+)",
+        r"\b([A-Z][A-Za-z.'-]+)\s+(?:owes|paid|gave|bought|sold)",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, text)
+        if match:
+            return match.group(1).strip()
+    return ""
+
+
+def infer_item(text: str) -> str:
+    without_amount = AMOUNT_RE.sub("", text)
+    match = re.search(r"\bfor\s+(.+)$", without_amount, re.IGNORECASE)
+    if match:
+        return cleanup_item(match.group(1))
+    for phrase in ("bought", "sold", "paid", "received"):
+        match = re.search(rf"\b{phrase}\b\s+(.+)$", without_amount, re.IGNORECASE)
+        if match:
+            return cleanup_item(match.group(1))
+    return cleanup_item(without_amount)
+
+
+def cleanup_item(text: str) -> str:
+    cleaned = re.sub(r"\b(?:rs\.?|lkr|paid|gave|from|to|customer|supplier)\b", "", text, flags=re.IGNORECASE)
+    cleaned = re.sub(r"\s+", " ", cleaned).strip(" ,-")
+    return cleaned[:80]
+
+
+def infer_reminder(
+    text: str,
+    counterparty: str,
+    amount: float,
+    currency: str,
+    status: PaymentStatus,
+) -> str:
+    if status != PaymentStatus.due:
+        if "remind" not in text.lower():
+            return ""
+
+    who = counterparty or "the customer"
+    amount_text = f"{currency} {amount:,.0f}" if amount else "the amount"
+    return f"Follow up with {who} about {amount_text}."

shop_ledger/insights.py

@@ -0,0 +1,1177 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import date, datetime
+from html import escape
+from typing import Any
+
+import plotly.graph_objects as go
+
+
+PALETTE = {
+    "bg": "#080c12",
+    "plot": "#0b1017",
+    "panel": "#10151d",
+    "grid": "rgba(157, 177, 154, 0.16)",
+    "axis": "rgba(243, 244, 236, 0.58)",
+    "ink": "#f3f4ec",
+    "muted": "#a8b3a5",
+    "green": "#8bdc8b",
+    "gold": "#e6b450",
+    "red": "#ff7a68",
+    "blue": "#8ab4ff",
+    "violet": "#b8a6ff",
+}
+
+
+def money(value: float, currency: str = "LKR") -> str:
+    return f"{currency} {value:,.0f}"
+
+
+def h(value: Any) -> str:
+    return escape(str(value or ""), quote=True)
+
+
+def amount(row: dict[str, Any]) -> float:
+    try:
+        return float(row.get("amount") or 0)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def primary_currency(rows: list[dict[str, Any]]) -> str:
+    for row in rows:
+        currency = row.get("currency")
+        if currency:
+            return str(currency)
+    return "LKR"
+
+
+def compute_metrics(rows: list[dict[str, Any]]) -> dict[str, Any]:
+    currency = primary_currency(rows)
+    paid_expense = sum(amount(row) for row in rows if row.get("direction") == "expense" and row.get("payment_status") == "paid")
+    paid_income = sum(amount(row) for row in rows if row.get("direction") == "income" and row.get("payment_status") == "paid")
+    due_income = sum(amount(row) for row in rows if row.get("direction") == "income" and row.get("payment_status") == "due")
+    due_expense = sum(amount(row) for row in rows if row.get("direction") == "expense" and row.get("payment_status") == "due")
+    reminders = [row for row in rows if row.get("reminder") or row.get("payment_status") == "due"]
+    confidence_values = [float(row.get("confidence") or 0) for row in rows]
+
+    return {
+        "currency": currency,
+        "row_count": len(rows),
+        "paid_expense": paid_expense,
+        "paid_income": paid_income,
+        "net_cash": paid_income - paid_expense,
+        "due_income": due_income,
+        "due_expense": due_expense,
+        "open_followups": len(reminders),
+        "avg_confidence": sum(confidence_values) / len(confidence_values) if confidence_values else 0,
+    }
+
+
+def parse_row_date(value: Any) -> date:
+    if isinstance(value, datetime):
+        return value.date()
+    if isinstance(value, date):
+        return value
+    text = str(value or "").strip()
+    if not text:
+        return date.today()
+    for fmt in ("%Y-%m-%d", "%d/%m/%Y", "%d-%m-%Y", "%b %d", "%B %d"):
+        try:
+            parsed = datetime.strptime(text, fmt)
+            if fmt in ("%b %d", "%B %d"):
+                return parsed.replace(year=date.today().year).date()
+            return parsed.date()
+        except ValueError:
+            continue
+    try:
+        return datetime.fromisoformat(text).date()
+    except ValueError:
+        return date.today()
+
+
+def top_counter(rows: list[dict[str, Any]], key: str) -> tuple[str, float]:
+    totals: dict[str, float] = defaultdict(float)
+    for row in rows:
+        value = str(row.get(key) or "").strip() or "uncategorized"
+        totals[value] += amount(row)
+    if not totals:
+        return "none", 0.0
+    return max(totals.items(), key=lambda item: item[1])
+
+
+def biggest_transaction(rows: list[dict[str, Any]]) -> dict[str, Any] | None:
+    if not rows:
+        return None
+    return max(rows, key=amount)
+
+
+def followup_rows(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    queue = []
+    for index, row in enumerate(rows, start=1):
+        if row.get("payment_status") != "due" and not row.get("reminder"):
+            continue
+        who = row.get("counterparty") or "Unknown"
+        value = amount(row)
+        currency = row.get("currency") or primary_currency(rows)
+        item = row.get("item") or "ledger item"
+        reminder = row.get("reminder") or f"Follow up with {who} about {money(value, currency)}."
+        variants = reply_variants(who, value, currency, item)
+        queue.append(
+            {
+                "priority": "High" if value >= 5000 else "Normal",
+                "counterparty": who,
+                "amount": money(value, currency),
+                "item": item,
+                "next_action": reminder,
+                "cadence": "Today, then every 2 days" if value >= 5000 else "Tomorrow",
+                "script": variants["polite"],
+                "polite_script": variants["polite"],
+                "friendly_script": variants["friendly"],
+                "firm_script": variants["firm"],
+                "source_row": index,
+            }
+        )
+    return sorted(queue, key=lambda row: (row["priority"] != "High", row["counterparty"]))
+
+
+def reply_variants(who: str, value: float, currency: str, item: str) -> dict[str, str]:
+    amount_text = money(value, currency)
+    return {
+        "polite": f"Hi {who}, just checking on {amount_text} for {item}. Can you confirm when it will be settled?",
+        "friendly": f"Hi {who}, quick reminder from the shop ledger: {amount_text} is still open for {item}. Tell me what works for you.",
+        "firm": f"Hi {who}, {amount_text} for {item} is still pending. Please settle it today or send a clear payment time.",
+    }
+
+
+def category_breakdown(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    totals: dict[str, float] = defaultdict(float)
+    currency = primary_currency(rows)
+    for row in rows:
+        totals[str(row.get("category") or "uncategorized")] += amount(row)
+    return [
+        {"category": category, "total": total, "display": money(total, currency)}
+        for category, total in sorted(totals.items(), key=lambda item: item[1], reverse=True)
+    ]
+
+
+def party_breakdown(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    totals: dict[str, float] = defaultdict(float)
+    due: dict[str, float] = defaultdict(float)
+    currency = primary_currency(rows)
+    for row in rows:
+        party = str(row.get("counterparty") or "Unknown")
+        totals[party] += amount(row)
+        if row.get("payment_status") == "due":
+            due[party] += amount(row)
+    return [
+        {"party": party, "total": money(total, currency), "due": money(due[party], currency)}
+        for party, total in sorted(totals.items(), key=lambda item: item[1], reverse=True)
+    ]
+
+
+def counterparty_memory_cards(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    currency = primary_currency(rows)
+    profiles: dict[str, dict[str, Any]] = {}
+    for index, row in enumerate(rows, start=1):
+        party = str(row.get("counterparty") or "Unknown").strip() or "Unknown"
+        profile = profiles.setdefault(
+            party,
+            {
+                "party": party,
+                "total_moved": 0.0,
+                "paid": 0.0,
+                "due": 0.0,
+                "row_count": 0,
+                "last_row": index,
+                "last_item": "",
+                "categories": defaultdict(int),
+                "items": defaultdict(int),
+            },
+        )
+        value = amount(row)
+        profile["total_moved"] += value
+        profile["row_count"] += 1
+        profile["last_row"] = index
+        profile["last_item"] = row.get("item") or "ledger item"
+        profile["categories"][str(row.get("category") or "uncategorized")] += 1
+        profile["items"][str(row.get("item") or "ledger item")] += 1
+        if row.get("payment_status") == "due":
+            profile["due"] += value
+        elif row.get("payment_status") == "paid":
+            profile["paid"] += value
+
+    cards = []
+    for profile in profiles.values():
+        category = max(profile["categories"].items(), key=lambda item: item[1])[0] if profile["categories"] else "uncategorized"
+        usual_item = max(profile["items"].items(), key=lambda item: item[1])[0] if profile["items"] else "ledger item"
+        trust = "Clear" if profile["due"] == 0 else "Watch" if profile["due"] < 5000 else "Collect first"
+        next_message = (
+            f"Thank {profile['party']} and keep trading."
+            if profile["due"] == 0
+            else f"Follow up with {profile['party']} about {money(profile['due'], currency)} before the next sale."
+        )
+        cards.append(
+            {
+                "party": profile["party"],
+                "trust_pulse": trust,
+                "total_moved": money(profile["total_moved"], currency),
+                "paid": money(profile["paid"], currency),
+                "due": money(profile["due"], currency),
+                "usual_category": category,
+                "usual_item": usual_item,
+                "last_item": profile["last_item"],
+                "row_count": profile["row_count"],
+                "next_message": next_message,
+            }
+        )
+    return sorted(cards, key=lambda card: (card["trust_pulse"] != "Collect first", card["trust_pulse"] != "Watch", card["party"]))
+
+
+def build_counterparty_memory_markdown(rows: list[dict[str, Any]]) -> str:
+    cards = counterparty_memory_cards(rows)
+    if not cards:
+        return "### Counterparty Memory\nPeople and supplier memory cards appear after the first ledger entry."
+
+    blocks = ["### Counterparty Memory", "<div class='memory-grid'>"]
+    for card in cards[:9]:
+        tone = "risk" if card["trust_pulse"] == "Collect first" else "watch" if card["trust_pulse"] == "Watch" else "clear"
+        blocks.append(
+            f"<div class='memory-card {tone}'>"
+            f"<strong>{h(card['party'])}</strong>"
+            f"<span>{h(card['trust_pulse'])}</span>"
+            f"<p>{h(card['total_moved'])} moved · {h(card['due'])} due</p>"
+            f"<small>Usually: {h(card['usual_category'])} / {h(card['usual_item'])}</small>"
+            f"<code>{h(card['next_message'])}</code>"
+            "</div>"
+        )
+    blocks.append("</div>")
+    return "\n".join(blocks)
+
+
+def review_rows(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    review = []
+    for index, row in enumerate(rows, start=1):
+        confidence = float(row.get("confidence") or 0)
+        missing = [
+            label
+            for label, value in {
+                "counterparty": row.get("counterparty"),
+                "item": row.get("item"),
+                "amount": row.get("amount"),
+                "payment status": row.get("payment_status"),
+            }.items()
+            if value in (None, "", 0)
+        ]
+        if confidence >= 0.6 and not missing:
+            continue
+        amount_text = money(amount(row), row.get("currency") or primary_currency(rows))
+        issue = "Low confidence" if confidence < 0.6 else "Missing detail"
+        if missing:
+            issue += f": {', '.join(missing)}"
+        review.append(
+            {
+                "source_row": index,
+                "issue": issue,
+                "confidence": f"{confidence:.0%}",
+                "counterparty": row.get("counterparty") or "Unknown",
+                "item": row.get("item") or "Unknown item",
+                "amount": amount_text,
+                "question": review_question(row, missing),
+            }
+        )
+    return review
+
+
+def review_question(row: dict[str, Any], missing: list[str]) -> str:
+    who = row.get("counterparty") or "this person"
+    item = row.get("item") or "this item"
+    if missing:
+        return f"Can you confirm the {', '.join(missing)} for {item}?"
+    return f"Can you confirm {who}, {item}, and the amount before exporting?"
+
+
+def build_dashboard_markdown(rows: list[dict[str, Any]]) -> str:
+    metrics = compute_metrics(rows)
+    currency = metrics["currency"]
+    if not rows:
+        return (
+            "### Command Center\n"
+            "No entries yet. Add one note to light up the cash desk, chart board, and follow-up radar."
+        )
+
+    return (
+        "### Command Center\n"
+        f"<div class='metric-grid'>"
+        f"<div class='metric-card'><span>Net cash</span><strong>{money(metrics['net_cash'], currency)}</strong></div>"
+        f"<div class='metric-card'><span>Cash in</span><strong>{money(metrics['paid_income'], currency)}</strong></div>"
+        f"<div class='metric-card'><span>Cash out</span><strong>{money(metrics['paid_expense'], currency)}</strong></div>"
+        f"<div class='metric-card'><span>Still due</span><strong>{money(metrics['due_income'], currency)}</strong></div>"
+        f"<div class='metric-card'><span>Follow-ups</span><strong>{metrics['open_followups']}</strong></div>"
+        f"<div class='metric-card'><span>Avg confidence</span><strong>{metrics['avg_confidence']:.0%}</strong></div>"
+        f"</div>"
+    )
+
+
+def build_chart_plan(rows: list[dict[str, Any]]) -> dict[str, str]:
+    if not rows:
+        return {
+            "chart": "empty",
+            "title": "Waiting for ledger signal",
+            "question": "What will the first note reveal?",
+            "reason": "The graph board wakes up after the first extracted row.",
+        }
+
+    metrics = compute_metrics(rows)
+    low_confidence = sum(1 for row in rows if float(row.get("confidence") or 0) < 0.6)
+    dated_rows = {parse_row_date(row.get("date")) for row in rows}
+    due_parties = {str(row.get("counterparty") or "Unknown") for row in rows if row.get("payment_status") == "due"}
+
+    if metrics["due_income"] > 0 and len(due_parties) >= 1:
+        return {
+            "chart": "due_by_party",
+            "title": "Who needs a follow-up first?",
+            "question": "Where is unpaid money concentrated?",
+            "reason": f"{money(metrics['due_income'], metrics['currency'])} is still due across {len(due_parties)} contact(s).",
+        }
+    if metrics["paid_expense"] > metrics["paid_income"] and metrics["paid_expense"] > 0:
+        return {
+            "chart": "expense_categories",
+            "title": "What is pulling cash out?",
+            "question": "Which spend category is dominating today?",
+            "reason": "Paid expenses are currently higher than collected income.",
+        }
+    if len(dated_rows) > 1:
+        return {
+            "chart": "cashflow",
+            "title": "How is cash moving over time?",
+            "question": "Which days changed the cash position?",
+            "reason": f"The ledger spans {len(dated_rows)} dates, so a timeline is now useful.",
+        }
+    if low_confidence > 0:
+        return {
+            "chart": "confidence_review",
+            "title": "Which rows need human eyes?",
+            "question": "Where might the extractor be uncertain?",
+            "reason": f"{low_confidence} row(s) are below 60% confidence.",
+        }
+    return {
+        "chart": "category_mix",
+        "title": "What shape is today's trade?",
+        "question": "Which categories are carrying the ledger?",
+        "reason": "No urgent risk dominates, so the board shows category mix.",
+    }
+
+
+CHART_SPECS = {
+    "due_by_party": "Due radar",
+    "expense_categories": "Spend pressure",
+    "cashflow": "Cashflow trail",
+    "confidence_review": "Review queue",
+    "category_mix": "Category mix",
+    "party_exposure": "People ledger",
+    "timeline": "Shop pulse timeline",
+}
+
+
+def chart_spec_from_question(rows: list[dict[str, Any]], question: str) -> dict[str, str]:
+    text = question.strip().lower()
+    if not rows:
+        return {"chart": "empty", "reason": "Add ledger rows before composing charts.", "model_used": "local rules"}
+    if any(word in text for word in ("owe", "due", "unpaid", "collect")):
+        chart = "due_by_party"
+        reason = "The question is about unpaid money and collections."
+    elif any(word in text for word in ("spend", "spent", "expense", "cash go", "cash out")):
+        chart = "expense_categories"
+        reason = "The question is about where cash went."
+    elif any(word in text for word in ("time", "trend", "flow", "day", "cash low")):
+        chart = "cashflow"
+        reason = "The question is about movement over time or cash position."
+    elif any(word in text for word in ("confidence", "wrong", "review", "mistake", "uncertain")):
+        chart = "confidence_review"
+        reason = "The question is about extraction quality."
+    elif any(word in text for word in ("person", "people", "supplier", "customer", "party")):
+        chart = "party_exposure"
+        reason = "The question is about people and suppliers."
+    elif any(word in text for word in ("story", "timeline", "happened")):
+        chart = "timeline"
+        reason = "The question asks for the story of the day."
+    else:
+        plan = build_chart_plan(rows)
+        chart = plan["chart"]
+        reason = plan["reason"]
+    return {"chart": chart, "reason": reason, "model_used": "local rules"}
+
+
+def figure_for_chart_id(rows: list[dict[str, Any]], chart: str) -> go.Figure:
+    builders = {
+        "due_by_party": due_by_party_figure,
+        "expense_categories": expense_category_figure,
+        "cashflow": cashflow_figure,
+        "confidence_review": confidence_review_figure,
+        "category_mix": category_mix_figure,
+        "party_exposure": party_exposure_figure,
+        "timeline": timeline_figure,
+    }
+    return builders.get(chart, category_mix_figure)(rows) if rows else empty_figure()
+
+
+def build_chart_composer_markdown(question: str, spec: dict[str, str]) -> str:
+    chart = spec.get("chart", "category_mix")
+    title = CHART_SPECS.get(chart, "Category mix")
+    reason = spec.get("reason") or "The ledger shape makes this view useful."
+    model_used = spec.get("model_used", "local rules")
+    prompt = question.strip() or "Auto-compose from the ledger."
+    return (
+        "### AI Chart Composer\n"
+        f"**Question:** {prompt}\n\n"
+        f"**Chart:** {title}\n\n"
+        f"**Why:** {reason}\n\n"
+        f"<small>Composer: {model_used}</small>"
+    )
+
+
+def build_chart_markdown(rows: list[dict[str, Any]]) -> str:
+    plan = build_chart_plan(rows)
+    if not rows:
+        return (
+            "### Chart Director\n"
+            f"**Question:** {plan['question']}\n\n"
+            f"{plan['reason']}"
+        )
+    return (
+        "### Chart Director\n"
+        f"**Question:** {plan['question']}\n\n"
+        f"**Graph chosen:** {plan['title']}\n\n"
+        f"**Why now:** {plan['reason']}"
+    )
+
+
+def build_insights_markdown(rows: list[dict[str, Any]]) -> str:
+    if not rows:
+        return "### Field Intelligence\nInsights appear after the first ledger entry."
+
+    metrics = compute_metrics(rows)
+    currency = metrics["currency"]
+    top_category, top_category_total = top_counter(rows, "category")
+    top_party, top_party_total = top_counter(rows, "counterparty")
+    biggest = biggest_transaction(rows)
+    risks = risk_flags(rows)
+    risk_text = "\n".join(f"- {risk}" for risk in risks) if risks else "- No urgent risks detected."
+    biggest_text = "none"
+    if biggest:
+        biggest_text = f"{money(amount(biggest), currency)} for {biggest.get('item') or 'unknown item'}"
+
+    return (
+        "### Field Intelligence\n"
+        f"- Top category: **{top_category}** ({money(top_category_total, currency)})\n"
+        f"- Most active party: **{top_party}** ({money(top_party_total, currency)})\n"
+        f"- Biggest entry: **{biggest_text}**\n"
+        f"- Open follow-up value: **{money(metrics['due_income'], currency)}**\n\n"
+        "### Watch List\n"
+        f"{risk_text}\n\n"
+        "### Field Note\n"
+        f"{daily_field_note(rows)}"
+    )
+
+
+def build_daily_brief_markdown(rows: list[dict[str, Any]], brief: str | None = None, model_used: str = "local rules") -> str:
+    if not rows:
+        return "### Today's Shop Pulse\nAdd a few entries, then ask Gemma for the day's pulse."
+    text = brief or daily_brief_fallback(rows)
+    return f"### Today's Shop Pulse\n{text}\n\n<small>Brief: {model_used}</small>"
+
+
+def daily_brief_fallback(rows: list[dict[str, Any]]) -> str:
+    metrics = compute_metrics(rows)
+    currency = metrics["currency"]
+    top_category, top_category_total = top_counter(rows, "category")
+    queue = followup_rows(rows)
+    if queue:
+        lead_followup = f"{queue[0]['counterparty']} needs the first follow-up for {queue[0]['amount']}."
+    else:
+        lead_followup = "No urgent follow-up is waiting."
+    return (
+        f"{len(rows)} row(s) logged today. Net cash is {money(metrics['net_cash'], currency)}. "
+        f"Money moved most through {top_category} ({money(top_category_total, currency)}). "
+        f"{lead_followup}"
+    )
+
+
+def answer_ledger_question(rows: list[dict[str, Any]], question: str) -> str:
+    text = question.strip().lower()
+    if not rows:
+        return "No ledger rows yet. Add a note, voice memo, or document first."
+    if not text:
+        return "Ask something like: who owes me most, what should I follow up today, or where did cash go?"
+
+    currency = primary_currency(rows)
+    if any(phrase in text for phrase in ("owe", "owes", "due", "who owes")):
+        due_by_party: dict[str, float] = defaultdict(float)
+        for row in rows:
+            if row.get("payment_status") == "due":
+                due_by_party[str(row.get("counterparty") or "Unknown")] += amount(row)
+        if not due_by_party:
+            return "No due items are open right now."
+        party, total = max(due_by_party.items(), key=lambda item: item[1])
+        return f"{party} owes the most: {money(total, currency)}."
+
+    if any(phrase in text for phrase in ("follow up", "followup", "remind", "today")):
+        queue = followup_rows(rows)
+        if not queue:
+            return "No follow-ups are waiting right now."
+        first = queue[0]
+        return f"Follow up with {first['counterparty']} first about {first['amount']} for {first['item']}. Suggested cadence: {first['cadence']}."
+
+    if any(phrase in text for phrase in ("cash go", "spent", "expense", "cash out", "where did cash")):
+        expenses = [row for row in rows if row.get("direction") == "expense"]
+        if not expenses:
+            return "No paid expenses are logged yet."
+        top_category, total = top_counter(expenses, "category")
+        return f"Cash went mostly to {top_category}: {money(total, currency)}."
+
+    metrics = compute_metrics(rows)
+    return (
+        f"Ledger snapshot: {len(rows)} row(s), net cash {money(metrics['net_cash'], currency)}, "
+        f"{money(metrics['due_income'], currency)} due, and {metrics['open_followups']} follow-up(s) open."
+    )
+
+
+COMMAND_ACTIONS = [
+    "Show unpaid",
+    "Draft WhatsApp follow-ups",
+    "Find risky rows",
+    "Summarize cash",
+    "Prepare QuickBooks export",
+]
+
+
+def run_ledger_command(rows: list[dict[str, Any]], command: str) -> str:
+    if not rows:
+        return "### Command Palette\nAdd ledger rows first, then run a command."
+
+    action = (command or "").strip() or COMMAND_ACTIONS[0]
+    currency = primary_currency(rows)
+    if action == "Show unpaid":
+        due_rows = [row for row in rows if row.get("payment_status") == "due"]
+        if not due_rows:
+            return "### Unpaid\nNo unpaid rows are open."
+        lines = [
+            f"- **{row.get('counterparty') or 'Unknown'}** owes {money(amount(row), currency)} for {row.get('item') or 'ledger item'}."
+            for row in due_rows[:8]
+        ]
+        return "### Unpaid\n" + "\n".join(lines)
+
+    if action == "Draft WhatsApp follow-ups":
+        queue = followup_rows(rows)
+        if not queue:
+            return "### WhatsApp Follow-ups\nNo follow-up messages are waiting."
+        lines = [f"- **{item['counterparty']}**: {item['friendly_script']}" for item in queue[:6]]
+        return "### WhatsApp Follow-ups\n" + "\n".join(lines)
+
+    if action == "Find risky rows":
+        risks = risk_flags(rows)
+        reviews = review_rows(rows)
+        lines = [f"- {risk}" for risk in risks]
+        lines.extend(f"- Row {item['source_row']}: {item['issue']}." for item in reviews[:5])
+        return "### Risk Scan\n" + ("\n".join(lines) if lines else "No obvious risks found.")
+
+    if action == "Prepare QuickBooks export":
+        lines = [
+            "- Map `income` rows to Sales Receipt or Invoice import.",
+            "- Map `expense` rows to Expense import.",
+            "- Use `counterparty` as Customer/Vendor.",
+            "- Use `category` as Account/Category.",
+            "- Use `item`, `amount`, `date`, and `payment_status` as transaction details.",
+            f"- Rows ready for review: **{len(rows)}**.",
+        ]
+        return "### QuickBooks Export Plan\n" + "\n".join(lines)
+
+    metrics = compute_metrics(rows)
+    return (
+        "### Cash Summary\n"
+        f"- Net cash: **{money(metrics['net_cash'], currency)}**\n"
+        f"- Cash in: **{money(metrics['paid_income'], currency)}**\n"
+        f"- Cash out: **{money(metrics['paid_expense'], currency)}**\n"
+        f"- Still due: **{money(metrics['due_income'], currency)}**"
+    )
+
+
+def anomaly_lantern_rows(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    if not rows:
+        return []
+
+    currency = primary_currency(rows)
+    values = [amount(row) for row in rows if amount(row) > 0]
+    avg_value = sum(values) / len(values) if values else 0
+    due_counts: dict[str, int] = defaultdict(int)
+    anomalies = []
+    for index, row in enumerate(rows, start=1):
+        party = row.get("counterparty") or "Unknown"
+        value = amount(row)
+        if row.get("payment_status") == "due":
+            due_counts[str(party)] += 1
+        if value == 0:
+            anomalies.append(make_anomaly(index, "Missing amount", "Check", party, row, "No amount was captured."))
+        if float(row.get("confidence") or 0) < 0.6:
+            anomalies.append(make_anomaly(index, "Low confidence", "Review", party, row, "Extraction confidence is below 60%."))
+        if avg_value and value > avg_value * 2.5 and value >= 5000:
+            anomalies.append(
+                make_anomaly(
+                    index,
+                    "Unusually large amount",
+                    "Watch",
+                    party,
+                    row,
+                    f"{money(value, currency)} is much larger than the current average entry.",
+                )
+            )
+        if row.get("payment_status") == "due" and value >= 5000:
+            anomalies.append(
+                make_anomaly(index, "High-value due", "Collect", party, row, f"{party} owes {money(value, currency)}.")
+            )
+
+    for party, count in due_counts.items():
+        if count > 1:
+            anomalies.append(
+                {
+                    "source_row": "",
+                    "severity": "Watch",
+                    "signal": "Repeat unpaid party",
+                    "counterparty": party,
+                    "item": "multiple due rows",
+                    "amount": "",
+                    "reason": f"{party} appears in {count} unpaid rows.",
+                }
+            )
+    severity_order = {"Collect": 0, "Watch": 1, "Review": 2, "Check": 3}
+    return sorted(anomalies, key=lambda item: (severity_order.get(item["severity"], 9), str(item["counterparty"])))[:12]
+
+
+def make_anomaly(
+    index: int,
+    signal: str,
+    severity: str,
+    party: Any,
+    row: dict[str, Any],
+    reason: str,
+) -> dict[str, Any]:
+    return {
+        "source_row": index,
+        "severity": severity,
+        "signal": signal,
+        "counterparty": party or "Unknown",
+        "item": row.get("item") or "ledger item",
+        "amount": money(amount(row), row.get("currency") or primary_currency([row])),
+        "reason": reason,
+    }
+
+
+def build_anomaly_lantern_markdown(rows: list[dict[str, Any]]) -> str:
+    anomalies = anomaly_lantern_rows(rows)
+    if not rows:
+        return "### Anomaly Lantern\nSignals appear after ledger rows are added."
+    if not anomalies:
+        return "### Anomaly Lantern\nNo bright warnings found. Still review before export."
+
+    blocks = ["### Anomaly Lantern", "<div class='lantern-grid'>"]
+    for item in anomalies[:8]:
+        tone = item["severity"].lower()
+        blocks.append(
+            f"<div class='lantern-card {tone}'>"
+            f"<strong>{h(item['severity'])} · {h(item['signal'])}</strong>"
+            f"<p>{h(item['counterparty'])} · {h(item['item'])} · {h(item['amount'])}</p>"
+            f"<code>{h(item['reason'])}</code>"
+            "</div>"
+        )
+    blocks.append("</div>")
+    return "\n".join(blocks)
+
+
+def closing_checklist(rows: list[dict[str, Any]]) -> list[dict[str, str]]:
+    metrics = compute_metrics(rows)
+    followups = followup_rows(rows)
+    reviews = review_rows(rows)
+    anomalies = anomaly_lantern_rows(rows)
+    return [
+        {
+            "step": "Count cash",
+            "status": "Ready" if rows else "Waiting",
+            "detail": f"Net cash is {money(metrics['net_cash'], metrics['currency'])}.",
+        },
+        {
+            "step": "Collect dues",
+            "status": "Action" if followups else "Clear",
+            "detail": f"{len(followups)} follow-up(s) waiting.",
+        },
+        {
+            "step": "Review uncertain rows",
+            "status": "Action" if reviews else "Clear",
+            "detail": f"{len(reviews)} row(s) need a human check.",
+        },
+        {
+            "step": "Check anomalies",
+            "status": "Action" if anomalies else "Clear",
+            "detail": f"{len(anomalies)} signal(s) found.",
+        },
+        {
+            "step": "Export ledger",
+            "status": "Ready" if rows and not reviews else "Review first",
+            "detail": "Download CSV after review for accountant or QuickBooks handoff.",
+        },
+    ]
+
+
+def build_closing_ritual_markdown(rows: list[dict[str, Any]]) -> str:
+    if not rows:
+        return "### Daily Closing Ritual\nAdd today’s notes, then close the shop with a guided checklist."
+
+    metrics = compute_metrics(rows)
+    currency = metrics["currency"]
+    top_category, top_total = top_counter(rows, "category")
+    followups = followup_rows(rows)
+    next_followup = (
+        f"First follow-up: {followups[0]['counterparty']} for {followups[0]['amount']}."
+        if followups
+        else "No follow-ups waiting."
+    )
+    checklist = closing_checklist(rows)
+    items = "\n".join(f"- **{item['step']}** · {item['status']}: {item['detail']}" for item in checklist)
+    return (
+        "### Daily Closing Ritual\n"
+        f"Today closes with **{money(metrics['net_cash'], currency)}** net cash, "
+        f"**{money(metrics['due_income'], currency)}** still due, and **{len(rows)}** ledger row(s). "
+        f"Most movement was in **{top_category}** ({money(top_total, currency)}). {next_followup}\n\n"
+        "### Closing Checklist\n"
+        f"{items}"
+    )
+
+
+def risk_flags(rows: list[dict[str, Any]]) -> list[str]:
+    metrics = compute_metrics(rows)
+    currency = metrics["currency"]
+    flags = []
+    if metrics["due_income"] > metrics["paid_income"] and metrics["due_income"] > 0:
+        flags.append(f"Due income ({money(metrics['due_income'], currency)}) is higher than collected cash.")
+    for row in rows:
+        if row.get("payment_status") == "due" and amount(row) >= 5000:
+            flags.append(f"High-value due item: {row.get('counterparty') or 'Unknown'} owes {money(amount(row), currency)}.")
+    if metrics["avg_confidence"] and metrics["avg_confidence"] < 0.55:
+        flags.append("Average extraction confidence is low. Review recent rows before using the CSV.")
+    return flags[:5]
+
+
+def daily_field_note(rows: list[dict[str, Any]]) -> str:
+    metrics = compute_metrics(rows)
+    currency = metrics["currency"]
+    categories = [item["category"] for item in category_breakdown(rows)[:2]]
+    category_text = " and ".join(categories) if categories else "general trade"
+    return (
+        f"{date.today().isoformat()}: {len(rows)} entries logged. "
+        f"Money moved mostly through {category_text}. "
+        f"Net cash is {money(metrics['net_cash'], currency)} with {metrics['open_followups']} follow-up(s) open."
+    )
+
+
+def build_reminder_markdown(rows: list[dict[str, Any]]) -> str:
+    queue = followup_rows(rows)
+    if not queue:
+        return "### Automation Queue\nNo follow-ups waiting. The desk is clear."
+
+    cards = ["### Automation Queue"]
+    for item in queue[:8]:
+        cards.append(
+            "<div class='followup-card'>"
+            f"<strong>{h(item['priority'])} · {h(item['counterparty'])} · {h(item['amount'])}</strong>"
+            f"<p>{h(item['next_action'])}</p>"
+            f"<small>Cadence: {h(item['cadence'])}</small>"
+            "<div class='reply-grid'>"
+            f"<code><span>Polite</span>{h(item['polite_script'])}</code>"
+            f"<code><span>Friendly</span>{h(item['friendly_script'])}</code>"
+            f"<code><span>Firm</span>{h(item['firm_script'])}</code>"
+            "</div>"
+            "</div>"
+        )
+    return "\n".join(cards)
+
+
+def build_review_markdown(rows: list[dict[str, Any]]) -> str:
+    queue = review_rows(rows)
+    if not rows:
+        return "### Review Desk\nRows that need a human check will appear here."
+    if not queue:
+        return "### Review Desk\nNo low-confidence rows waiting. Export still deserves a quick glance."
+
+    cards = ["### Review Desk"]
+    for item in queue[:8]:
+        cards.append(
+            "<div class='review-card'>"
+            f"<strong>Row {h(item['source_row'])} · {h(item['issue'])} · {h(item['confidence'])}</strong>"
+            f"<p>{h(item['counterparty'])} · {h(item['item'])} · {h(item['amount'])}</p>"
+            f"<code>{h(item['question'])}</code>"
+            "</div>"
+        )
+    return "\n".join(cards)
+
+
+def timeline_rows(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    events = []
+    currency = primary_currency(rows)
+    for index, row in enumerate(rows, start=1):
+        value = amount(row)
+        direction = row.get("direction") or "unknown"
+        status = row.get("payment_status") or "unknown"
+        party = row.get("counterparty") or "Unknown"
+        item = row.get("item") or "ledger item"
+        signed = value
+        if direction == "expense":
+            signed = -value
+        elif status == "due":
+            signed = 0
+        badge = "Cash in" if direction == "income" and status == "paid" else "Cash out" if direction == "expense" else "Due" if status == "due" else "Logged"
+        story = f"{badge}: {party} · {item} · {money(value, currency)}"
+        events.append(
+            {
+                "source_row": index,
+                "date": str(row.get("date") or date.today().isoformat()),
+                "badge": badge,
+                "direction": direction,
+                "counterparty": party,
+                "item": item,
+                "amount": money(value, currency),
+                "signed_amount": signed,
+                "status": status,
+                "story": story,
+            }
+        )
+    return sorted(events, key=lambda event: (parse_row_date(event["date"]), event["source_row"]))
+
+
+def build_timeline_markdown(rows: list[dict[str, Any]]) -> str:
+    events = timeline_rows(rows)
+    if not events:
+        return "### Shop Pulse Timeline\nThe day's story appears after the first ledger entry."
+
+    cards = ["### Shop Pulse Timeline", "<div class='timeline-rail'>"]
+    for event in events[:12]:
+        tone = "income" if event["direction"] == "income" else "expense" if event["direction"] == "expense" else "due"
+        cards.append(
+            f"<div class='timeline-card {tone}'>"
+            f"<strong>Row {h(event['source_row'])} · {h(event['badge'])} · {h(event['date'])}</strong>"
+            f"<p>{h(event['counterparty'])} · {h(event['item'])}</p>"
+            f"<code>{h(event['amount'])} · {h(event['status'])}</code>"
+            "</div>"
+        )
+    cards.append("</div>")
+    return "\n".join(cards)
+
+
+def timeline_figure(rows: list[dict[str, Any]]) -> go.Figure:
+    events = timeline_rows(rows)
+    figure = base_figure("Shop pulse timeline", "Rows become the story of the day")
+    if not events:
+        return empty_figure()
+
+    labels = [f"Row {event['source_row']}" for event in events]
+    values = [event["signed_amount"] for event in events]
+    colors = [
+        PALETTE["green"] if event["direction"] == "income" and event["status"] == "paid"
+        else PALETTE["red"] if event["direction"] == "expense"
+        else PALETTE["gold"] if event["status"] == "due"
+        else PALETTE["blue"]
+        for event in events
+    ]
+    hover = [event["story"] for event in events]
+    figure.add_trace(
+        go.Bar(
+            x=labels,
+            y=values,
+            marker={"color": colors},
+            marker_line={"color": "rgba(243, 244, 236, 0.28)", "width": 1},
+            text=[event["badge"] for event in events],
+            textposition="auto",
+            hovertext=hover,
+            hovertemplate="%{hovertext}<extra></extra>",
+        )
+    )
+    figure.add_hline(y=0, line_color="rgba(243, 244, 236, 0.28)", line_width=1)
+    return figure
+
+
+def build_tables(
+    rows: list[dict[str, Any]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]], list[dict[str, Any]]]:
+    return category_breakdown(rows), party_breakdown(rows), followup_rows(rows), review_rows(rows)
+
+
+def base_figure(title: str, subtitle: str = "") -> go.Figure:
+    figure = go.Figure()
+    figure.update_layout(
+        title={
+            "text": title if not subtitle else f"{title}<br><sup>{subtitle}</sup>",
+            "x": 0.02,
+            "xanchor": "left",
+            "font": {"size": 17, "color": PALETTE["ink"]},
+        },
+        paper_bgcolor=PALETTE["bg"],
+        plot_bgcolor=PALETTE["plot"],
+        font={"color": PALETTE["ink"], "family": "Inter, ui-sans-serif, system-ui, sans-serif", "size": 12},
+        margin={"l": 48, "r": 24, "t": 78, "b": 48},
+        height=350,
+        legend={
+            "orientation": "h",
+            "y": -0.22,
+            "x": 0,
+            "font": {"color": PALETTE["muted"], "size": 11},
+            "bgcolor": "rgba(8, 12, 18, 0)",
+        },
+        hoverlabel={
+            "bgcolor": "#10151d",
+            "bordercolor": "rgba(157, 177, 154, 0.32)",
+            "font": {"color": PALETTE["ink"], "size": 12},
+        },
+        bargap=0.34,
+        transition={"duration": 240, "easing": "cubic-in-out"},
+    )
+    figure.update_xaxes(
+        gridcolor=PALETTE["grid"],
+        zerolinecolor=PALETTE["grid"],
+        linecolor="rgba(157, 177, 154, 0.22)",
+        tickfont={"color": PALETTE["axis"], "size": 11},
+        title_font={"color": PALETTE["muted"], "size": 11},
+        ticks="outside",
+        tickcolor="rgba(157, 177, 154, 0.22)",
+    )
+    figure.update_yaxes(
+        gridcolor=PALETTE["grid"],
+        zerolinecolor=PALETTE["grid"],
+        linecolor="rgba(157, 177, 154, 0.22)",
+        tickfont={"color": PALETTE["axis"], "size": 11},
+        title_font={"color": PALETTE["muted"], "size": 11},
+        ticks="outside",
+        tickcolor="rgba(157, 177, 154, 0.22)",
+    )
+    return figure
+
+
+def empty_figure() -> go.Figure:
+    figure = base_figure("Ledger signal board", "Add a note to generate the first graph")
+    figure.add_annotation(
+        text="No rows yet",
+        x=0.5,
+        y=0.5,
+        showarrow=False,
+        font={"size": 24, "color": PALETTE["muted"]},
+        xref="paper",
+        yref="paper",
+    )
+    figure.update_xaxes(visible=False)
+    figure.update_yaxes(visible=False)
+    return figure
+
+
+def due_by_party_figure(rows: list[dict[str, Any]]) -> go.Figure:
+    currency = primary_currency(rows)
+    totals: dict[str, float] = defaultdict(float)
+    for row in rows:
+        if row.get("payment_status") == "due":
+            totals[str(row.get("counterparty") or "Unknown")] += amount(row)
+    items = sorted(totals.items(), key=lambda item: item[1], reverse=True)[:8]
+    figure = base_figure("Due radar", "Highest-value follow-ups first")
+    if not items:
+        return empty_figure()
+    parties, values = zip(*items)
+    figure.add_trace(
+        go.Bar(
+            x=list(values),
+            y=list(parties),
+            orientation="h",
+            marker={"color": PALETTE["gold"], "line": {"color": "rgba(243, 244, 236, 0.22)", "width": 1}},
+            opacity=0.94,
+            text=[money(value, currency) for value in values],
+            textposition="auto",
+            hovertemplate="%{y}<br>%{text}<extra></extra>",
+        )
+    )
+    figure.update_yaxes(autorange="reversed")
+    return figure
+
+
+def expense_category_figure(rows: list[dict[str, Any]]) -> go.Figure:
+    currency = primary_currency(rows)
+    totals: dict[str, float] = defaultdict(float)
+    for row in rows:
+        if row.get("direction") == "expense":
+            totals[str(row.get("category") or "uncategorized")] += amount(row)
+    items = sorted(totals.items(), key=lambda item: item[1], reverse=True)[:8]
+    figure = base_figure("Spend pressure", "Expense categories ranked by amount")
+    if not items:
+        return empty_figure()
+    categories, values = zip(*items)
+    figure.add_trace(
+        go.Bar(
+            x=list(categories),
+            y=list(values),
+            marker={
+                "color": [PALETTE["red"], PALETTE["gold"], PALETTE["blue"], PALETTE["violet"]] * 2,
+                "line": {"color": "rgba(243, 244, 236, 0.22)", "width": 1},
+            },
+            opacity=0.94,
+            text=[money(value, currency) for value in values],
+            textposition="auto",
+            hovertemplate="%{x}<br>%{text}<extra></extra>",
+        )
+    )
+    return figure
+
+
+def cashflow_figure(rows: list[dict[str, Any]]) -> go.Figure:
+    currency = primary_currency(rows)
+    income: dict[date, float] = defaultdict(float)
+    expense: dict[date, float] = defaultdict(float)
+    for row in rows:
+        day = parse_row_date(row.get("date"))
+        if row.get("direction") == "income" and row.get("payment_status") == "paid":
+            income[day] += amount(row)
+        if row.get("direction") == "expense" and row.get("payment_status") == "paid":
+            expense[day] += amount(row)
+    days = sorted(set(income) | set(expense))
+    figure = base_figure("Cashflow trail", "Paid income and expenses by date")
+    if not days:
+        return empty_figure()
+    labels = [day.isoformat() for day in days]
+    income_values = [income[day] for day in days]
+    expense_values = [-expense[day] for day in days]
+    net_values = [income[day] - expense[day] for day in days]
+    figure.add_trace(
+        go.Bar(
+            name="Cash in",
+            x=labels,
+            y=income_values,
+            marker={"color": PALETTE["green"], "line": {"color": "rgba(243, 244, 236, 0.18)", "width": 1}},
+            opacity=0.92,
+        )
+    )
+    figure.add_trace(
+        go.Bar(
+            name="Cash out",
+            x=labels,
+            y=expense_values,
+            marker={"color": PALETTE["red"], "line": {"color": "rgba(243, 244, 236, 0.18)", "width": 1}},
+            opacity=0.92,
+        )
+    )
+    figure.add_trace(
+        go.Scatter(
+            name="Net",
+            x=labels,
+            y=net_values,
+            mode="lines+markers",
+            line={"color": PALETTE["blue"], "width": 3},
+            marker={"size": 9, "color": PALETTE["blue"], "line": {"color": PALETTE["bg"], "width": 2}},
+            hovertemplate=f"%{{x}}<br>{currency} %{{y:,.0f}}<extra></extra>",
+        )
+    )
+    figure.update_layout(barmode="relative")
+    return figure
+
+
+def confidence_review_figure(rows: list[dict[str, Any]]) -> go.Figure:
+    figure = base_figure("Review queue", "Lower bars deserve a quick check")
+    labels = [f"Row {index}" for index, _ in enumerate(rows, start=1)]
+    values = [float(row.get("confidence") or 0) for row in rows]
+    colors = [PALETTE["red"] if value < 0.6 else PALETTE["green"] for value in values]
+    figure.add_trace(
+        go.Bar(
+            x=labels,
+            y=values,
+            marker={"color": colors, "line": {"color": "rgba(243, 244, 236, 0.22)", "width": 1}},
+            opacity=0.94,
+            text=[f"{value:.0%}" for value in values],
+            textposition="auto",
+            hovertext=[row.get("item") or "ledger item" for row in rows],
+            hovertemplate="%{x}<br>%{hovertext}<br>%{text}<extra></extra>",
+        )
+    )
+    figure.update_yaxes(range=[0, 1], tickformat=".0%")
+    return figure
+
+
+def category_mix_figure(rows: list[dict[str, Any]]) -> go.Figure:
+    breakdown = category_breakdown(rows)
+    figure = base_figure("Category mix", "A quick map of where money moved")
+    if not breakdown:
+        return empty_figure()
+    figure.add_trace(
+        go.Pie(
+            labels=[item["category"] for item in breakdown[:8]],
+            values=[item["total"] for item in breakdown[:8]],
+            hole=0.55,
+            marker={
+                "colors": [PALETTE["green"], PALETTE["gold"], PALETTE["blue"], PALETTE["red"], PALETTE["violet"]],
+                "line": {"color": PALETTE["bg"], "width": 2},
+            },
+            textinfo="label+percent",
+            textfont={"color": PALETTE["ink"], "size": 12},
+            hovertemplate="%{label}<br>%{value:,.0f}<extra></extra>",
+        )
+    )
+    figure.update_xaxes(visible=False)
+    figure.update_yaxes(visible=False)
+    return figure
+
+
+def party_exposure_figure(rows: list[dict[str, Any]]) -> go.Figure:
+    currency = primary_currency(rows)
+    totals: dict[str, float] = defaultdict(float)
+    due: dict[str, float] = defaultdict(float)
+    for row in rows:
+        party = str(row.get("counterparty") or "Unknown")
+        totals[party] += amount(row)
+        if row.get("payment_status") == "due":
+            due[party] += amount(row)
+    items = sorted(totals.items(), key=lambda item: item[1], reverse=True)[:8]
+    figure = base_figure("People ledger", "Total movement vs unpaid exposure")
+    if not items:
+        return empty_figure()
+    parties = [party for party, _ in items]
+    figure.add_trace(
+        go.Bar(
+            name="Total",
+            x=parties,
+            y=[totals[party] for party in parties],
+            marker={"color": PALETTE["blue"], "line": {"color": "rgba(243, 244, 236, 0.18)", "width": 1}},
+            opacity=0.92,
+            hovertemplate=f"%{{x}}<br>{currency} %{{y:,.0f}} total<extra></extra>",
+        )
+    )
+    figure.add_trace(
+        go.Bar(
+            name="Due",
+            x=parties,
+            y=[due[party] for party in parties],
+            marker={"color": PALETTE["gold"], "line": {"color": "rgba(243, 244, 236, 0.18)", "width": 1}},
+            opacity=0.92,
+            hovertemplate=f"%{{x}}<br>{currency} %{{y:,.0f}} due<extra></extra>",
+        )
+    )
+    figure.update_layout(barmode="group")
+    return figure
+
+
+def build_insight_figures(rows: list[dict[str, Any]]) -> tuple[go.Figure, go.Figure, go.Figure]:
+    if not rows:
+        empty = empty_figure()
+        return empty, empty_figure(), empty_figure()
+
+    plan = build_chart_plan(rows)
+    primary_builders = {
+        "due_by_party": due_by_party_figure,
+        "expense_categories": expense_category_figure,
+        "cashflow": cashflow_figure,
+        "confidence_review": confidence_review_figure,
+        "category_mix": category_mix_figure,
+    }
+    primary = primary_builders.get(plan["chart"], category_mix_figure)(rows)
+    return primary, cashflow_figure(rows), party_exposure_figure(rows)

shop_ledger/llama_backend.py

@@ -0,0 +1,208 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+from shop_ledger.heuristics import heuristic_extract
+from shop_ledger.schema import LedgerResult
+
+
+SYSTEM_PROMPT = """You turn messy shopkeeper notes, receipts, bills, and ledger images into a clean ledger.
+Return only valid JSON with this exact shape:
+{
+  "entries": [
+    {
+      "date": "YYYY-MM-DD or empty",
+      "direction": "expense|income|transfer|unknown",
+      "counterparty": "person or business",
+      "item": "what changed hands",
+      "quantity": "quantity if known",
+      "amount": 0,
+      "currency": "LKR",
+      "category": "inventory|utilities|rent|wages|transport|maintenance|sales|general expense|uncategorized",
+      "payment_status": "paid|due|partial|unknown",
+      "due_date": "",
+      "reminder": "short follow-up reminder or empty",
+      "confidence": 0.0,
+      "original_note": "source fragment"
+    }
+  ],
+  "reminders": ["short reminders"],
+  "questions": ["only ask if an amount, person, or due date is unclear"],
+  "cleaned_note": "normalized note"
+}
+Use the user's currency. Do not invent amounts. Split multiple transactions into multiple entries.
+For images, read visible receipt/bill/note text and infer only clear ledger facts."""
+
+
+class LlamaLedgerBackend:
+    def __init__(
+        self,
+        model_path: str | None = None,
+        n_ctx: int | None = None,
+        n_threads: int | None = None,
+        n_gpu_layers: int | None = None,
+    ) -> None:
+        self.model_path = model_path or os.getenv("LLAMA_GGUF_PATH", "")
+        self.model_label = os.getenv("LLAMA_MODEL_LABEL", "").strip() or self._default_model_label()
+        self.n_ctx = n_ctx or int(os.getenv("LLAMA_N_CTX", "4096"))
+        self.n_threads = n_threads or max(2, (os.cpu_count() or 4) - 1)
+        self.n_gpu_layers = n_gpu_layers if n_gpu_layers is not None else int(os.getenv("LLAMA_N_GPU_LAYERS", "0"))
+        self._llm: Any | None = None
+
+    def _default_model_label(self) -> str:
+        model_file = Path(self.model_path).name if self.model_path else "GGUF model"
+        return f"llama.cpp / {model_file}"
+
+    @property
+    def available(self) -> bool:
+        return bool(self.model_path and Path(self.model_path).exists())
+
+    def load(self) -> None:
+        if self._llm is not None:
+            return
+        if not self.available:
+            raise FileNotFoundError(f"GGUF model not found: {self.model_path}")
+
+        from llama_cpp import Llama
+
+        self._llm = Llama(
+            model_path=self.model_path,
+            n_ctx=self.n_ctx,
+            n_threads=self.n_threads,
+            n_gpu_layers=self.n_gpu_layers,
+            verbose=False,
+        )
+
+    def extract(self, note: str, currency: str = "LKR", image_urls: list[str] | None = None) -> LedgerResult:
+        if not self.available:
+            return heuristic_extract(note, currency=currency)
+
+        self.load()
+        assert self._llm is not None
+        image_urls = image_urls or []
+        user_content: str | list[dict[str, Any]]
+        prompt = f"Currency: {currency}\nNote or document context:\n{note or 'Read the uploaded document image(s).'}"
+        if image_urls:
+            user_content = [{"type": "text", "text": prompt}]
+            user_content.extend({"type": "image_url", "image_url": {"url": image_url}} for image_url in image_urls)
+        else:
+            user_content = prompt
+
+        response = self._llm.create_chat_completion(
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user", "content": user_content},
+            ],
+            max_tokens=900,
+            temperature=0.1,
+            top_p=0.9,
+        )
+        text = response["choices"][0]["message"]["content"]
+        data = parse_json_object(text)
+        result = LedgerResult.model_validate(data)
+        result.model_used = self.model_label
+        return result
+
+    def daily_brief(self, rows: list[dict[str, Any]], currency: str = "LKR") -> str:
+        if not self.available:
+            return ""
+
+        self.load()
+        assert self._llm is not None
+
+        response = self._llm.create_chat_completion(
+            messages=[
+                {
+                    "role": "system",
+                    "content": (
+                        "You write a short shopkeeper daily brief from structured ledger rows. "
+                        "Be specific, practical, and under 80 words. Mention cash position, dues, "
+                        "largest pressure, and the next follow-up when relevant."
+                    ),
+                },
+                {"role": "user", "content": f"Currency: {currency}\nRows JSON:\n{json.dumps(rows, ensure_ascii=True)}"},
+            ],
+            max_tokens=180,
+            temperature=0.3,
+            top_p=0.9,
+        )
+        return str(response["choices"][0]["message"]["content"]).strip()
+
+    def answer_ledger_question(self, rows: list[dict[str, Any]], question: str, currency: str = "LKR") -> str:
+        if not self.available:
+            return ""
+
+        self.load()
+        assert self._llm is not None
+
+        response = self._llm.create_chat_completion(
+            messages=[
+                {
+                    "role": "system",
+                    "content": (
+                        "Answer questions about a small shop ledger using only the provided structured rows. "
+                        "Be concise, practical, and mention amounts/counterparties when relevant. "
+                        "If the rows do not contain the answer, say what is missing."
+                    ),
+                },
+                {
+                    "role": "user",
+                    "content": (
+                        f"Currency: {currency}\nQuestion: {question}\nRows JSON:\n"
+                        f"{json.dumps(rows, ensure_ascii=True)}"
+                    ),
+                },
+            ],
+            max_tokens=220,
+            temperature=0.2,
+            top_p=0.9,
+        )
+        return str(response["choices"][0]["message"]["content"]).strip()
+
+    def choose_chart_spec(self, rows: list[dict[str, Any]], question: str, allowed_charts: dict[str, str]) -> dict[str, str]:
+        if not self.available:
+            return {}
+
+        self.load()
+        assert self._llm is not None
+
+        response = self._llm.create_chat_completion(
+            messages=[
+                {
+                    "role": "system",
+                    "content": (
+                        "Choose the best chart for a small shop ledger question. "
+                        "Return only JSON with keys chart and reason. "
+                        f"Allowed chart ids: {', '.join(allowed_charts)}."
+                    ),
+                },
+                {
+                    "role": "user",
+                    "content": (
+                        f"Question: {question}\nAllowed charts: {json.dumps(allowed_charts, ensure_ascii=True)}\n"
+                        f"Rows JSON:\n{json.dumps(rows, ensure_ascii=True)}"
+                    ),
+                },
+            ],
+            max_tokens=160,
+            temperature=0.1,
+            top_p=0.9,
+        )
+        data = parse_json_object(str(response["choices"][0]["message"]["content"]))
+        return {"chart": str(data.get("chart") or ""), "reason": str(data.get("reason") or "")}
+
+
+def parse_json_object(text: str) -> dict[str, Any]:
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+
+    match = re.search(r"\{.*\}", text, flags=re.DOTALL)
+    if not match:
+        raise ValueError(f"Model did not return JSON: {text[:240]}")
+    return json.loads(match.group(0))

shop_ledger/processor.py

@@ -0,0 +1,225 @@
+from __future__ import annotations
+
+import os
+import base64
+from io import BytesIO
+from pathlib import Path
+from typing import Any
+
+from shop_ledger.heuristics import heuristic_extract
+from shop_ledger.insights import CHART_SPECS, answer_ledger_question, chart_spec_from_question, daily_brief_fallback
+from shop_ledger.llama_backend import LlamaLedgerBackend
+from shop_ledger.schema import LedgerResult
+
+_WHISPER_MODELS: dict[str, Any] = {}
+
+
+class LedgerProcessor:
+    def __init__(self, mode: str = "mock", model_path: str | None = None) -> None:
+        self.mode = mode
+        self.backend = LlamaLedgerBackend(model_path=model_path)
+
+    @classmethod
+    def from_env(cls) -> "LedgerProcessor":
+        mode = os.getenv("LEDGER_MODEL_MODE", "mock").strip().lower()
+        return cls(mode=mode, model_path=resolve_model_path_from_env())
+
+    def process(self, note: str, currency: str = "LKR", image_urls: list[str] | None = None) -> LedgerResult:
+        if self.mode == "llama":
+            if not self.backend.available:
+                fallback = heuristic_extract(note, currency=currency)
+                fallback.model_used = "heuristic fallback (missing GGUF model)"
+                fallback.questions.append("No GGUF model was found, so heuristics were used.")
+                if image_urls:
+                    fallback.questions.append("Document images need the multimodal GGUF model.")
+                return fallback
+            try:
+                return self.backend.extract(note, currency=currency, image_urls=image_urls)
+            except Exception as exc:
+                fallback = heuristic_extract(note, currency=currency)
+                fallback.model_used = f"heuristic fallback ({type(exc).__name__})"
+                fallback.questions.append(f"The llama.cpp model was unavailable, so heuristics were used: {exc}")
+                if image_urls:
+                    fallback.questions.append("Document images were not analyzed because multimodal inference failed.")
+                return fallback
+        result = heuristic_extract(note, currency=currency)
+        result.model_used = "mock heuristic"
+        if image_urls:
+            result.questions.append("Document images need llama.cpp multimodal mode; mock mode only reads extracted text.")
+        return result
+
+    def daily_brief(self, rows: list[dict[str, Any]], currency: str = "LKR") -> dict[str, str]:
+        if not rows:
+            return {"brief": "Add a few entries, then ask Gemma for the day's pulse.", "model_used": "local rules"}
+        if self.mode == "llama" and self.backend.available:
+            try:
+                brief = self.backend.daily_brief(rows, currency=currency)
+                if brief:
+                    return {"brief": brief, "model_used": self.backend.model_label}
+            except Exception as exc:
+                return {
+                    "brief": daily_brief_fallback(rows),
+                    "model_used": f"local rules fallback ({type(exc).__name__})",
+                }
+        return {"brief": daily_brief_fallback(rows), "model_used": "local rules"}
+
+    def ask_ledger(self, rows: list[dict[str, Any]], question: str, currency: str = "LKR") -> dict[str, str]:
+        fallback = answer_ledger_question(rows, question)
+        if self.mode == "llama" and self.backend.available and rows and question.strip():
+            try:
+                answer = self.backend.answer_ledger_question(rows, question, currency=currency)
+                if answer:
+                    return {"answer": answer, "model_used": self.backend.model_label}
+            except Exception as exc:
+                return {"answer": fallback, "model_used": f"local rules fallback ({type(exc).__name__})"}
+        return {"answer": fallback, "model_used": "local rules"}
+
+    def choose_chart(self, rows: list[dict[str, Any]], question: str) -> dict[str, str]:
+        fallback = chart_spec_from_question(rows, question)
+        if self.mode == "llama" and self.backend.available and rows:
+            try:
+                spec = self.backend.choose_chart_spec(rows, question, CHART_SPECS)
+                if spec.get("chart") in CHART_SPECS:
+                    spec["model_used"] = self.backend.model_label
+                    return spec
+            except Exception as exc:
+                fallback["model_used"] = f"local rules fallback ({type(exc).__name__})"
+                return fallback
+        return fallback
+
+
+def resolve_model_path_from_env() -> str | None:
+    model_path = os.getenv("LLAMA_GGUF_PATH")
+    if model_path:
+        return model_path
+
+    repo_id = os.getenv("LLAMA_GGUF_REPO", "").strip()
+    filename = os.getenv("LLAMA_GGUF_FILE", "").strip()
+    if not repo_id or not filename:
+        return None
+
+    try:
+        from huggingface_hub import hf_hub_download
+    except Exception:
+        return None
+
+    try:
+        return hf_hub_download(repo_id=repo_id, filename=filename)
+    except Exception:
+        return None
+
+
+def transcribe_audio(audio_path: str | None) -> str:
+    if not audio_path:
+        return ""
+
+    path = Path(audio_path)
+    if not path.exists():
+        return ""
+
+    try:
+        from faster_whisper import WhisperModel
+    except Exception:
+        return ""
+
+    size = os.getenv("WHISPER_MODEL_SIZE", "tiny")
+    model = _WHISPER_MODELS.get(size)
+    if model is None:
+        model = WhisperModel(size, device="cpu", compute_type="int8")
+        _WHISPER_MODELS[size] = model
+    segments, _ = model.transcribe(str(path), beam_size=3)
+    return " ".join(segment.text.strip() for segment in segments).strip()
+
+
+def prepare_document_input(document_path: Any, max_pages: int = 3) -> dict[str, Any]:
+    path = normalize_document_path(document_path)
+    if not path or not path.exists():
+        return {"text": "", "image_urls": [], "page_count": 0, "kind": "missing"}
+
+    suffix = path.suffix.lower()
+    if suffix in {".txt", ".csv", ".md"}:
+        return {
+            "text": path.read_text(encoding="utf-8", errors="ignore").strip(),
+            "image_urls": [],
+            "page_count": 1,
+            "kind": "text",
+        }
+    if suffix == ".pdf":
+        return prepare_pdf_input(path, max_pages=max_pages)
+    if suffix in {".png", ".jpg", ".jpeg", ".webp", ".tif", ".tiff", ".bmp"}:
+        return {"text": "", "image_urls": [image_file_to_data_url(path)], "page_count": 1, "kind": "image"}
+    return {"text": "", "image_urls": [], "page_count": 0, "kind": "unsupported"}
+
+
+def extract_document_text(document_path: Any) -> str:
+    return str(prepare_document_input(document_path).get("text") or "")
+
+
+def normalize_document_path(document_path: Any) -> Path | None:
+    if not document_path:
+        return None
+    if isinstance(document_path, (list, tuple)):
+        if not document_path:
+            return None
+        return normalize_document_path(document_path[0])
+    if isinstance(document_path, dict):
+        value = document_path.get("path") or document_path.get("name")
+        return Path(value) if value else None
+    value = getattr(document_path, "name", document_path)
+    return Path(str(value)) if value else None
+
+
+def prepare_pdf_input(path: Path, max_pages: int = 3) -> dict[str, Any]:
+    try:
+        import fitz
+    except Exception:
+        return {"text": "", "image_urls": [], "page_count": 0, "kind": "pdf"}
+
+    chunks = []
+    image_urls = []
+    with fitz.open(path) as document:
+        page_indexes = range(min(len(document), max_pages))
+        for page_index in page_indexes:
+            page = document[page_index]
+            text = page.get_text("text").strip()
+            if text:
+                chunks.append(text)
+
+        for page_index in page_indexes:
+            page = document[page_index]
+            pixmap = page.get_pixmap(dpi=180)
+            image_urls.append(bytes_to_data_url(pixmap.tobytes("png"), "image/png"))
+
+    return {"text": "\n".join(chunks).strip(), "image_urls": image_urls, "page_count": len(image_urls), "kind": "pdf"}
+
+
+def image_file_to_data_url(path: Path) -> str:
+    try:
+        from PIL import Image
+    except Exception:
+        mime = mime_for_path(path)
+        return bytes_to_data_url(path.read_bytes(), mime)
+
+    with Image.open(path) as image:
+        image.thumbnail((1600, 1600))
+        buffer = BytesIO()
+        image.convert("RGB").save(buffer, format="JPEG", quality=88)
+    return bytes_to_data_url(buffer.getvalue(), "image/jpeg")
+
+
+def bytes_to_data_url(data: bytes, mime: str) -> str:
+    encoded = base64.b64encode(data).decode("ascii")
+    return f"data:{mime};base64,{encoded}"
+
+
+def mime_for_path(path: Path) -> str:
+    suffix = path.suffix.lower()
+    if suffix in {".jpg", ".jpeg"}:
+        return "image/jpeg"
+    if suffix == ".webp":
+        return "image/webp"
+    if suffix in {".tif", ".tiff"}:
+        return "image/tiff"
+    if suffix == ".bmp":
+        return "image/bmp"
+    return "image/png"

shop_ledger/schema.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+from datetime import date
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class Direction(str, Enum):
+    expense = "expense"
+    income = "income"
+    transfer = "transfer"
+    unknown = "unknown"
+
+
+class PaymentStatus(str, Enum):
+    paid = "paid"
+    due = "due"
+    partial = "partial"
+    unknown = "unknown"
+
+
+class LedgerEntry(BaseModel):
+    date: str = Field(default_factory=lambda: date.today().isoformat())
+    direction: Direction = Direction.unknown
+    counterparty: str = ""
+    item: str = ""
+    quantity: str = ""
+    amount: float = 0.0
+    currency: str = "LKR"
+    category: str = "uncategorized"
+    payment_status: PaymentStatus = PaymentStatus.unknown
+    due_date: str = ""
+    reminder: str = ""
+    confidence: float = 0.5
+    original_note: str = ""
+
+    @field_validator(
+        "date",
+        "counterparty",
+        "item",
+        "quantity",
+        "currency",
+        "category",
+        "due_date",
+        "reminder",
+        "original_note",
+        mode="before",
+    )
+    @classmethod
+    def parse_optional_text(cls, value: Any) -> str:
+        if value is None:
+            return ""
+        return str(value)
+
+    @field_validator("amount", mode="before")
+    @classmethod
+    def parse_amount(cls, value: Any) -> float:
+        if value in (None, ""):
+            return 0.0
+        if isinstance(value, (int, float)):
+            return float(value)
+        cleaned = str(value).replace(",", "").strip()
+        try:
+            return float(cleaned)
+        except ValueError:
+            return 0.0
+
+    @field_validator("confidence", mode="before")
+    @classmethod
+    def clamp_confidence(cls, value: Any) -> float:
+        try:
+            number = float(value)
+        except (TypeError, ValueError):
+            return 0.5
+        return max(0.0, min(1.0, number))
+
+
+class LedgerResult(BaseModel):
+    entries: list[LedgerEntry] = Field(default_factory=list)
+    reminders: list[str] = Field(default_factory=list)
+    questions: list[str] = Field(default_factory=list)
+    cleaned_note: str = ""
+    model_used: str = "heuristic"
+
+    def as_rows(self) -> list[dict[str, Any]]:
+        return [entry.model_dump(mode="json") for entry in self.entries]

shop_ledger/ui.py

@@ -0,0 +1,1615 @@
+from __future__ import annotations
+
+import csv
+import tempfile
+from collections.abc import Callable
+from html import escape
+from typing import Any
+
+import gradio as gr
+import pandas as pd
+
+from shop_ledger.insights import (
+    build_chart_markdown,
+    build_chart_composer_markdown,
+    build_counterparty_memory_markdown,
+    build_dashboard_markdown,
+    build_daily_brief_markdown,
+    build_insight_figures,
+    build_insights_markdown,
+    build_reminder_markdown,
+    build_review_markdown,
+    build_timeline_markdown,
+    build_tables,
+    counterparty_memory_cards,
+    chart_spec_from_question,
+    figure_for_chart_id,
+    COMMAND_ACTIONS,
+    anomaly_lantern_rows,
+    build_anomaly_lantern_markdown,
+    build_closing_ritual_markdown,
+    closing_checklist,
+    run_ledger_command,
+    timeline_figure,
+    timeline_rows,
+)
+from shop_ledger.processor import LedgerProcessor, prepare_document_input, transcribe_audio
+
+
+ProcessFn = Callable[[str, str, list[str] | None], dict[str, Any]]
+DailyBriefFn = Callable[[list[dict[str, Any]], str], dict[str, str]]
+AskLedgerFn = Callable[[list[dict[str, Any]], str, str], dict[str, str]]
+ChartComposerFn = Callable[[list[dict[str, Any]], str], dict[str, str]]
+ChatHistory = list[dict[str, str]]
+
+COLUMNS = [
+    "date",
+    "direction",
+    "counterparty",
+    "item",
+    "quantity",
+    "amount",
+    "currency",
+    "category",
+    "payment_status",
+    "due_date",
+    "confidence",
+    "reminder",
+]
+
+EXAMPLES = [
+    "paid Ravi 1200 for rice bags, customer Nimal owes 750 for tea packets, remind me Friday",
+    "bought milk packets 3600 cash from Sunil. sold biscuits 950 to school canteen",
+    "electric bill 8400 due next Monday, paid helper Kamal 2500 salary",
+]
+
+CORRECTION_FIELDS = [
+    "counterparty",
+    "item",
+    "amount",
+    "category",
+    "payment_status",
+    "direction",
+    "due_date",
+    "reminder",
+    "confidence",
+]
+
+CSS = """
+:root {
+  --ledger-bg: #090b0f;
+  --ledger-panel: #10151d;
+  --ledger-panel-2: #151b25;
+  --ledger-line: rgba(157, 177, 154, 0.22);
+  --ledger-ink: #f3f4ec;
+  --ledger-muted: #a8b3a5;
+  --ledger-green: #8bdc8b;
+  --ledger-gold: #e6b450;
+  --ledger-red: #ff7a68;
+  --ledger-blue: #8ab4ff;
+}
+
+.gradio-container {
+  background:
+    linear-gradient(120deg, rgba(139, 220, 139, 0.08), transparent 32%),
+    linear-gradient(180deg, #090b0f 0%, #11171f 54%, #0c1015 100%);
+  color: var(--ledger-ink) !important;
+}
+
+.gradio-container .block,
+.gradio-container .form,
+.gradio-container .panel {
+  background: var(--ledger-panel) !important;
+  border-color: var(--ledger-line) !important;
+}
+
+.gradio-container textarea,
+.gradio-container input,
+.gradio-container select {
+  background: #0b1017 !important;
+  color: var(--ledger-ink) !important;
+  border-color: var(--ledger-line) !important;
+}
+
+.gradio-container label,
+.gradio-container .wrap,
+.gradio-container .prose,
+.gradio-container p,
+.gradio-container span {
+  color: var(--ledger-ink);
+}
+
+#hero {
+  padding: 22px 0 8px;
+}
+
+#hero h1 {
+  font-size: 38px;
+  line-height: 1.08;
+  margin-bottom: 8px;
+  color: var(--ledger-ink);
+}
+
+#hero p {
+  color: var(--ledger-muted);
+  font-size: 16px;
+  max-width: 760px;
+}
+
+#status-strip {
+  border: 1px solid var(--ledger-line);
+  background: rgba(16, 21, 29, 0.8);
+  border-radius: 8px;
+  padding: 8px 12px;
+}
+
+#status-strip .prose {
+  margin: 0;
+}
+
+#status-strip code {
+  white-space: normal;
+  overflow-wrap: anywhere;
+}
+
+#cockpit-shell {
+  display: grid !important;
+  grid-template-columns: minmax(270px, 0.9fr) minmax(430px, 1.65fr) minmax(310px, 1fr);
+  gap: 12px;
+  align-items: start;
+}
+
+.cockpit-pane {
+  min-width: 0;
+}
+
+#input-dock,
+#output-dock,
+#pulse-core,
+#assistant-rail,
+#action-inbox,
+#people-workbench,
+#ledger-archive {
+  border: 1px solid var(--ledger-line);
+  background: rgba(16, 21, 29, 0.86);
+  border-radius: 8px;
+  padding: 14px;
+}
+
+#input-dock,
+#assistant-rail {
+  position: sticky;
+  top: 12px;
+}
+
+#cockpit-shell h3,
+#action-inbox h3,
+#people-workbench h3,
+#ledger-archive h3 {
+  margin-top: 0;
+}
+
+#input-notice,
+#correction-status {
+  min-height: 42px;
+  border-left: 4px solid var(--ledger-gold);
+  background: rgba(230, 180, 80, 0.1);
+  border-radius: 6px;
+  padding: 10px 12px;
+}
+
+.summary-card {
+  border-left: 4px solid var(--ledger-green);
+  background: rgba(139, 220, 139, 0.08);
+  border-radius: 6px;
+  padding: 12px;
+}
+
+.reminder-card {
+  border-left: 4px solid var(--ledger-blue);
+  background: rgba(138, 180, 255, 0.08);
+  border-radius: 6px;
+  padding: 12px;
+}
+
+button.primary {
+  border-radius: 8px !important;
+  background: linear-gradient(180deg, #92e693 0%, #5fbf73 100%) !important;
+  color: #07100b !important;
+  border: 0 !important;
+  font-weight: 700 !important;
+}
+
+#ledger-table {
+  border: 1px solid var(--ledger-line);
+  border-radius: 8px;
+}
+
+#download-box {
+  min-height: 70px;
+}
+
+.metric-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 10px;
+  margin-top: 10px;
+}
+
+.metric-card {
+  background: rgba(8, 12, 18, 0.88);
+  border: 1px solid var(--ledger-line);
+  border-radius: 8px;
+  padding: 14px;
+}
+
+.metric-card span {
+  display: block;
+  color: var(--ledger-muted) !important;
+  font-size: 12px;
+  text-transform: uppercase;
+}
+
+.metric-card strong {
+  display: block;
+  color: var(--ledger-green);
+  font-size: 22px;
+  margin-top: 6px;
+}
+
+.dashboard-grid {
+  display: grid;
+  grid-template-columns: minmax(300px, 0.9fr) minmax(520px, 1.7fr);
+  gap: 12px;
+  align-items: start;
+}
+
+.ops-stack {
+  display: grid;
+  gap: 12px;
+}
+
+.ops-card,
+.chat-panel {
+  border: 1px solid var(--ledger-line);
+  background: rgba(8, 12, 18, 0.88);
+  border-radius: 8px;
+  padding: 14px;
+}
+
+#chart-director,
+#daily-brief-panel,
+#ask-ledger-panel {
+  min-height: 128px;
+  border-left: 4px solid var(--ledger-blue);
+}
+
+#chart-wall {
+  border: 1px solid var(--ledger-line);
+  background:
+    linear-gradient(180deg, rgba(16, 21, 29, 0.92), rgba(8, 12, 18, 0.88));
+  border-radius: 8px;
+  padding: 12px;
+}
+
+#pulse-core #dashboard-panel {
+  margin-bottom: 10px;
+}
+
+#pulse-core #chart-director {
+  margin-bottom: 10px;
+}
+
+#pulse-core #timeline-panel {
+  margin-top: 10px;
+}
+
+#chart-wall .block,
+#signal-row .block {
+  background: rgba(8, 12, 18, 0.34) !important;
+  border-color: rgba(157, 177, 154, 0.18) !important;
+  border-radius: 8px !important;
+}
+
+#signal-row {
+  margin-top: 10px;
+}
+
+#ask-chat-panel {
+  border-left: 4px solid var(--ledger-green);
+}
+
+#ask-chat-panel .wrap {
+  background: transparent !important;
+}
+
+#ask-chatbot {
+  min-height: 340px;
+  border: 1px solid rgba(157, 177, 154, 0.18);
+  border-radius: 8px;
+  background: rgba(6, 10, 15, 0.72);
+}
+
+#ask-chatbot .message {
+  border-radius: 8px !important;
+}
+
+#ask-chatbot .user {
+  background: rgba(138, 180, 255, 0.14) !important;
+  border: 1px solid rgba(138, 180, 255, 0.22) !important;
+}
+
+#ask-chatbot .bot {
+  background: rgba(139, 220, 139, 0.12) !important;
+  border: 1px solid rgba(139, 220, 139, 0.22) !important;
+}
+
+#ask-row {
+  align-items: end;
+}
+
+#command-panel {
+  border-left: 4px solid var(--ledger-gold);
+}
+
+#command-output {
+  min-height: 96px;
+  border: 1px solid rgba(157, 177, 154, 0.18);
+  border-radius: 8px;
+  background: rgba(6, 10, 15, 0.64);
+  padding: 12px;
+}
+
+#chart-compose-row {
+  align-items: end;
+  margin-bottom: 10px;
+}
+
+#action-grid {
+  display: grid !important;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 12px;
+  align-items: start;
+}
+
+#archive-grid,
+.people-grid {
+  display: grid !important;
+  grid-template-columns: minmax(0, 1.2fr) minmax(0, 1fr);
+  gap: 12px;
+  align-items: start;
+}
+
+#rail-stack {
+  display: grid;
+  gap: 10px;
+}
+
+#workbench-tabs {
+  margin-top: 12px;
+}
+
+#workbench-tabs .tab-nav {
+  background: rgba(8, 12, 18, 0.72) !important;
+  border: 1px solid rgba(157, 177, 154, 0.18) !important;
+  border-radius: 8px !important;
+  padding: 4px !important;
+}
+
+#workbench-tabs button {
+  border-radius: 6px !important;
+}
+
+.followup-card {
+  background: rgba(8, 12, 18, 0.88);
+  border: 1px solid var(--ledger-line);
+  border-left: 4px solid var(--ledger-gold);
+  border-radius: 8px;
+  margin: 10px 0;
+  padding: 12px;
+}
+
+.review-card {
+  background: rgba(8, 12, 18, 0.88);
+  border: 1px solid var(--ledger-line);
+  border-left: 4px solid var(--ledger-red);
+  border-radius: 8px;
+  margin: 10px 0;
+  padding: 12px;
+}
+
+.review-card code {
+  display: block;
+  white-space: normal;
+  margin-top: 8px;
+  color: var(--ledger-ink);
+  background: rgba(255, 122, 104, 0.08);
+  border: 1px solid rgba(255, 122, 104, 0.22);
+  border-radius: 6px;
+  padding: 8px;
+}
+
+.timeline-rail {
+  border-left: 1px solid var(--ledger-line);
+  margin-left: 10px;
+  padding-left: 14px;
+}
+
+.timeline-card {
+  background: rgba(8, 12, 18, 0.88);
+  border: 1px solid var(--ledger-line);
+  border-left: 4px solid var(--ledger-blue);
+  border-radius: 8px;
+  margin: 10px 0;
+  padding: 12px;
+}
+
+.timeline-card.income {
+  border-left-color: var(--ledger-green);
+}
+
+.timeline-card.expense {
+  border-left-color: var(--ledger-red);
+}
+
+.timeline-card.due {
+  border-left-color: var(--ledger-gold);
+}
+
+.timeline-card code {
+  color: var(--ledger-muted);
+  background: rgba(157, 177, 154, 0.08);
+  border-radius: 6px;
+  padding: 5px 7px;
+}
+
+.memory-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 10px;
+}
+
+.memory-card {
+  background: rgba(8, 12, 18, 0.88);
+  border: 1px solid var(--ledger-line);
+  border-left: 4px solid var(--ledger-green);
+  border-radius: 8px;
+  padding: 12px;
+}
+
+.memory-card.watch {
+  border-left-color: var(--ledger-gold);
+}
+
+.memory-card.risk {
+  border-left-color: var(--ledger-red);
+}
+
+.memory-card strong,
+.memory-card span {
+  display: block;
+}
+
+.memory-card span {
+  color: var(--ledger-gold) !important;
+  font-size: 12px;
+  margin-top: 4px;
+  text-transform: uppercase;
+}
+
+.memory-card code {
+  display: block;
+  white-space: normal;
+  margin-top: 8px;
+  color: var(--ledger-green);
+  background: rgba(139, 220, 139, 0.08);
+  border: 1px solid rgba(139, 220, 139, 0.22);
+  border-radius: 6px;
+  padding: 8px;
+}
+
+.lantern-grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 10px;
+}
+
+.lantern-card {
+  background: rgba(8, 12, 18, 0.88);
+  border: 1px solid var(--ledger-line);
+  border-left: 4px solid var(--ledger-blue);
+  border-radius: 8px;
+  padding: 12px;
+}
+
+.lantern-card.collect,
+.lantern-card.watch {
+  border-left-color: var(--ledger-red);
+}
+
+.lantern-card.review {
+  border-left-color: var(--ledger-gold);
+}
+
+.lantern-card code {
+  display: block;
+  white-space: normal;
+  color: var(--ledger-ink);
+  background: rgba(255, 122, 104, 0.08);
+  border: 1px solid rgba(255, 122, 104, 0.2);
+  border-radius: 6px;
+  margin-top: 8px;
+  padding: 8px;
+}
+
+.followup-card code {
+  display: block;
+  white-space: normal;
+  color: var(--ledger-green);
+  background: rgba(139, 220, 139, 0.08);
+  border: 1px solid rgba(139, 220, 139, 0.22);
+  border-radius: 6px;
+  padding: 8px;
+}
+
+.reply-grid {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 8px;
+  margin-top: 10px;
+}
+
+.reply-grid code span {
+  display: block;
+  color: var(--ledger-gold) !important;
+  font-family: inherit;
+  font-size: 11px;
+  font-weight: 700;
+  margin-bottom: 4px;
+  text-transform: uppercase;
+}
+
+#dashboard-panel,
+#automation-panel,
+#review-panel,
+#daily-brief-panel,
+#ask-ledger-panel,
+#command-panel,
+#timeline-panel,
+#memory-panel,
+#lantern-panel,
+#closing-panel,
+#insight-panel {
+  border: 1px solid var(--ledger-line);
+  background: rgba(16, 21, 29, 0.86);
+  border-radius: 8px;
+  padding: 14px;
+}
+
+@media (max-width: 760px) {
+  #cockpit-shell,
+  #action-grid,
+  #archive-grid,
+  .people-grid {
+    grid-template-columns: 1fr !important;
+  }
+
+  #input-dock,
+  #assistant-rail {
+    position: static;
+  }
+
+  .metric-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .dashboard-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .reply-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .memory-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .lantern-grid {
+    grid-template-columns: 1fr;
+  }
+}
+"""
+
+
+def build_demo(
+    process_fn: ProcessFn | None = None,
+    daily_brief_fn: DailyBriefFn | None = None,
+    ask_ledger_fn: AskLedgerFn | None = None,
+    chart_composer_fn: ChartComposerFn | None = None,
+) -> gr.Blocks:
+    processor = LedgerProcessor.from_env()
+
+    def local_process(note: str, currency: str, image_urls: list[str] | None = None) -> dict[str, Any]:
+        return processor.process(note, currency=currency, image_urls=image_urls).model_dump(mode="json")
+
+    active_process = process_fn or local_process
+
+    def local_daily_brief(rows: list[dict[str, Any]], currency: str) -> dict[str, str]:
+        return processor.daily_brief(rows, currency=currency)
+
+    active_daily_brief = daily_brief_fn or local_daily_brief
+
+    def local_ask_ledger(rows: list[dict[str, Any]], question: str, currency: str) -> dict[str, str]:
+        return processor.ask_ledger(rows, question, currency=currency)
+
+    active_ask_ledger = ask_ledger_fn or local_ask_ledger
+
+    def local_chart_composer(rows: list[dict[str, Any]], question: str) -> dict[str, str]:
+        return chart_spec_from_question(rows, question)
+
+    active_chart_composer = chart_composer_fn or local_chart_composer
+
+    with gr.Blocks(
+        css=CSS,
+        title="Small Shop Ledger",
+        theme=gr.themes.Soft(primary_hue="green", secondary_hue="amber", neutral_hue="slate"),
+    ) as demo:
+        ledger_state = gr.State([])
+
+        gr.Markdown(
+            """
+            # Small Shop Ledger
+            Messy notes in. Clear books by closing time.
+            """,
+            elem_id="hero",
+        )
+
+        with gr.Row(elem_id="status-strip"):
+            model_badge = gr.Markdown("Model: not run yet")
+            row_count = gr.Markdown("Rows: 0")
+
+        with gr.Row(elem_id="cockpit-shell"):
+            with gr.Column(scale=3, elem_id="input-dock", elem_classes=["cockpit-pane"]):
+                gr.Markdown("### Capture")
+                note_box = gr.Textbox(
+                    label="Written note",
+                    placeholder="paid Ravi 1200 for rice bags, customer Nimal owes 750 for tea packets",
+                    lines=6,
+                )
+                audio_box = gr.Audio(label="Voice note", sources=["microphone", "upload"], type="filepath")
+                document_box = gr.File(
+                    label="Receipt, bill, or note image",
+                    file_types=[".pdf", ".png", ".jpg", ".jpeg", ".webp", ".tif", ".tiff", ".bmp", ".txt", ".csv"],
+                    type="filepath",
+                )
+                input_choice = gr.Radio(
+                    label="Input to analyze",
+                    choices=["Auto", "Text note", "Voice note", "Document"],
+                    value="Auto",
+                    interactive=True,
+                )
+                input_notice = gr.Markdown("Ready for one note.", elem_id="input-notice")
+                with gr.Row():
+                    currency = gr.Dropdown(
+                        label="Currency",
+                        choices=["LKR", "USD", "INR", "GBP", "EUR"],
+                        value="LKR",
+                        allow_custom_value=True,
+                    )
+                    add_button = gr.Button("Add to ledger", variant="primary")
+                    clear_button = gr.Button("Clear")
+                gr.Examples(
+                    examples=EXAMPLES,
+                    inputs=note_box,
+                    label="Try a messy shop note",
+                )
+
+            with gr.Column(scale=6, elem_id="pulse-core", elem_classes=["cockpit-pane"]):
+                gr.Markdown("### Shop Pulse")
+                dashboard = gr.Markdown(build_dashboard_markdown([]), elem_id="dashboard-panel")
+                with gr.Column(elem_id="chart-wall"):
+                    with gr.Row(elem_id="chart-compose-row"):
+                        chart_question = gr.Textbox(
+                            label="Compose chart",
+                            placeholder="Show me why cash feels low today",
+                            lines=1,
+                            scale=5,
+                        )
+                        chart_compose_button = gr.Button("Compose", variant="secondary", scale=1)
+                    chart_director = gr.Markdown(build_chart_markdown([]), elem_id="chart-director")
+                    primary_chart, secondary_chart, tertiary_chart = build_insight_figures([])
+                    primary_plot = gr.Plot(value=primary_chart, label="Insight graph")
+                    with gr.Row(elem_id="signal-row"):
+                        secondary_plot = gr.Plot(value=secondary_chart, label="Cash trail")
+                        tertiary_plot = gr.Plot(value=tertiary_chart, label="People ledger")
+                timeline = gr.Markdown(build_timeline_markdown([]), elem_id="timeline-panel")
+                timeline_plot = gr.Plot(value=timeline_figure([]), label="Shop pulse")
+                insights = gr.Markdown(build_insights_markdown([]), elem_id="insight-panel")
+
+            with gr.Column(scale=4, elem_id="assistant-rail", elem_classes=["cockpit-pane"]):
+                gr.Markdown("### Ledger Assistant")
+                summary = gr.Markdown("No ledger rows yet.", elem_classes=["summary-card"])
+                reminders = gr.Markdown("No reminders yet.", elem_classes=["reminder-card"])
+                with gr.Column(elem_id="rail-stack"):
+                    daily_brief = gr.Markdown(build_daily_brief_markdown([]), elem_id="daily-brief-panel")
+                    daily_brief_button = gr.Button("Generate daily brief", variant="secondary")
+                    with gr.Column(elem_id="ask-chat-panel", elem_classes=["chat-panel"]):
+                        ask_chatbot = gr.Chatbot(
+                            value=initial_ask_chat(),
+                            label="Ask My Ledger",
+                            type="messages",
+                            height=320,
+                            elem_id="ask-chatbot",
+                        )
+                        with gr.Row(elem_id="ask-row"):
+                            ask_question = gr.Textbox(
+                                label="Ask my ledger",
+                                placeholder="Who owes me most?",
+                                lines=1,
+                                scale=5,
+                            )
+                            ask_button = gr.Button("Ask", variant="primary", scale=1)
+                        with gr.Row():
+                            ask_voice = gr.Audio(
+                                label="Ask by voice",
+                                sources=["microphone", "upload"],
+                                type="filepath",
+                                scale=3,
+                            )
+                            ask_voice_button = gr.Button("Ask voice", variant="secondary", scale=1)
+                            ask_clear = gr.Button("Reset", scale=1)
+                        gr.Markdown(
+                            """
+                            ### Good questions
+                            - Who owes me most?
+                            - What should I follow up today?
+                            - Where did cash go?
+                            - Give me the current ledger snapshot.
+                            """,
+                            elem_id="ask-ledger-panel",
+                        )
+                    with gr.Column(elem_id="command-panel", elem_classes=["chat-panel"]):
+                        command_choice = gr.Dropdown(
+                            label="Ledger command",
+                            choices=COMMAND_ACTIONS,
+                            value=COMMAND_ACTIONS[0],
+                            interactive=True,
+                        )
+                        command_button = gr.Button("Run command", variant="secondary")
+                        command_output = gr.Markdown(
+                            "### Command Palette\nChoose a command to run against the current ledger.",
+                            elem_id="command-output",
+                        )
+                    closing = gr.Markdown(build_closing_ritual_markdown([]), elem_id="closing-panel")
+
+        with gr.Row(elem_id="action-inbox"):
+            with gr.Column():
+                gr.Markdown("### Action Inbox")
+                with gr.Row(elem_id="action-grid"):
+                    automation = gr.Markdown(build_reminder_markdown([]), elem_id="automation-panel")
+                    review = gr.Markdown(build_review_markdown([]), elem_id="review-panel")
+                    lantern = gr.Markdown(build_anomaly_lantern_markdown([]), elem_id="lantern-panel")
+                with gr.Row():
+                    correction_row = gr.Number(label="Row to correct", value=1, precision=0, scale=1)
+                    correction_field = gr.Dropdown(
+                        label="Field",
+                        choices=CORRECTION_FIELDS,
+                        value="counterparty",
+                        interactive=True,
+                        scale=2,
+                    )
+                    correction_value = gr.Textbox(
+                        label="Correct value",
+                        placeholder="Type the value that should be stored",
+                        lines=1,
+                        scale=4,
+                    )
+                    correction_button = gr.Button("Apply correction", variant="secondary", scale=1)
+                correction_status = gr.Markdown(
+                    "Corrections update the ledger, review queue, charts, and CSV export.",
+                    elem_id="correction-status",
+                )
+                with gr.Accordion("Operational tables", open=False):
+                    gr.Markdown("Follow-ups, verification rows, and anomaly signals live here for review before export.")
+                    with gr.Row():
+                        automation_table = gr.Dataframe(
+                            headers=[
+                                "priority",
+                                "counterparty",
+                                "amount",
+                                "item",
+                                "next_action",
+                                "cadence",
+                                "polite_script",
+                                "friendly_script",
+                                "firm_script",
+                                "source_row",
+                            ],
+                            datatype=["str", "str", "str", "str", "str", "str", "str", "str", "str", "number"],
+                            label="Reply studio",
+                            interactive=False,
+                            wrap=True,
+                        )
+                    with gr.Row():
+                        review_table = gr.Dataframe(
+                            headers=["source_row", "issue", "confidence", "counterparty", "item", "amount", "question"],
+                            datatype=["number", "str", "str", "str", "str", "str", "str"],
+                            label="Rows to verify",
+                            interactive=False,
+                            wrap=True,
+                        )
+                        lantern_table = gr.Dataframe(
+                            headers=["source_row", "severity", "signal", "counterparty", "item", "amount", "reason"],
+                            datatype=["str", "str", "str", "str", "str", "str", "str"],
+                            label="Anomaly signals",
+                            interactive=False,
+                            wrap=True,
+                        )
+
+        with gr.Tabs(elem_id="workbench-tabs"):
+            with gr.Tab("People"):
+                with gr.Row(elem_id="people-workbench"):
+                    with gr.Column():
+                        gr.Markdown("### People Memory")
+                        memory = gr.Markdown(build_counterparty_memory_markdown([]), elem_id="memory-panel")
+                    with gr.Column():
+                        memory_table = gr.Dataframe(
+                            headers=[
+                                "party",
+                                "trust_pulse",
+                                "total_moved",
+                                "paid",
+                                "due",
+                                "usual_category",
+                                "usual_item",
+                                "last_item",
+                                "row_count",
+                                "next_message",
+                            ],
+                            datatype=["str", "str", "str", "str", "str", "str", "str", "str", "number", "str"],
+                            label="Counterparty memory",
+                            interactive=False,
+                            wrap=True,
+                        )
+                        party_table = gr.Dataframe(
+                            headers=["party", "total", "due"],
+                            datatype=["str", "str", "str"],
+                            label="People and suppliers",
+                            interactive=False,
+                            wrap=True,
+                        )
+            with gr.Tab("Ledger Archive"):
+                with gr.Row(elem_id="ledger-archive"):
+                    with gr.Column(scale=3):
+                        ledger = gr.Dataframe(
+                            headers=COLUMNS,
+                            datatype=["str"] * len(COLUMNS),
+                            label="Ledger",
+                            interactive=False,
+                            wrap=True,
+                            elem_id="ledger-table",
+                        )
+                        download = gr.File(label="Download CSV", elem_id="download-box")
+                    with gr.Column(scale=2):
+                        category_table = gr.Dataframe(
+                            headers=["category", "total", "display"],
+                            datatype=["str", "number", "str"],
+                            label="Category heatmap",
+                            interactive=False,
+                            wrap=True,
+                        )
+                        closing_table = gr.Dataframe(
+                            headers=["step", "status", "detail"],
+                            datatype=["str", "str", "str"],
+                            label="Closing checklist",
+                            interactive=False,
+                            wrap=True,
+                        )
+                with gr.Accordion("Timeline event table", open=False):
+                    timeline_table = gr.Dataframe(
+                        headers=[
+                            "source_row",
+                            "date",
+                            "badge",
+                            "direction",
+                            "counterparty",
+                            "item",
+                            "amount",
+                            "signed_amount",
+                            "status",
+                            "story",
+                        ],
+                        datatype=["number", "str", "str", "str", "str", "str", "str", "number", "str", "str"],
+                        label="Timeline events",
+                        interactive=False,
+                        wrap=True,
+                    )
+
+        add_button.click(
+            fn=lambda note, audio, document, source_choice, currency_value, state: add_to_ledger(
+                note,
+                audio,
+                document,
+                source_choice,
+                currency_value,
+                state,
+                active_process,
+            ),
+            inputs=[note_box, audio_box, document_box, input_choice, currency, ledger_state],
+            outputs=[
+                ledger,
+                summary,
+                reminders,
+                model_badge,
+                row_count,
+                download,
+                ledger_state,
+                note_box,
+                audio_box,
+                document_box,
+                input_choice,
+                input_notice,
+                dashboard,
+                chart_director,
+                daily_brief,
+                primary_plot,
+                secondary_plot,
+                tertiary_plot,
+                insights,
+                automation,
+                category_table,
+                party_table,
+                automation_table,
+                review,
+                review_table,
+                timeline,
+                timeline_plot,
+                timeline_table,
+                memory,
+                memory_table,
+                lantern,
+                lantern_table,
+                closing,
+                closing_table,
+            ],
+        )
+        clear_button.click(
+            fn=lambda: (
+                *clear_ledger(),
+                "### Command Palette\nChoose a command to run against the current ledger.",
+                initial_ask_chat(),
+                "",
+                "Corrections update the ledger, review queue, charts, and CSV export.",
+            ),
+            outputs=[
+                ledger,
+                summary,
+                reminders,
+                model_badge,
+                row_count,
+                download,
+                ledger_state,
+                note_box,
+                audio_box,
+                document_box,
+                input_choice,
+                input_notice,
+                dashboard,
+                chart_director,
+                daily_brief,
+                primary_plot,
+                secondary_plot,
+                tertiary_plot,
+                insights,
+                automation,
+                category_table,
+                party_table,
+                automation_table,
+                review,
+                review_table,
+                timeline,
+                timeline_plot,
+                timeline_table,
+                memory,
+                memory_table,
+                lantern,
+                lantern_table,
+                closing,
+                closing_table,
+                command_output,
+                ask_chatbot,
+                ask_question,
+                correction_status,
+            ],
+        )
+        daily_brief_button.click(
+            fn=lambda state, currency_value: generate_daily_brief(state, currency_value, active_daily_brief),
+            inputs=[ledger_state, currency],
+            outputs=[daily_brief],
+        )
+        ask_button.click(
+            fn=lambda state, question, history, currency_value: ask_ledger_chat(
+                state,
+                question,
+                history,
+                currency_value,
+                active_ask_ledger,
+            ),
+            inputs=[ledger_state, ask_question, ask_chatbot, currency],
+            outputs=[ask_chatbot, ask_question],
+        )
+        ask_question.submit(
+            fn=lambda state, question, history, currency_value: ask_ledger_chat(
+                state,
+                question,
+                history,
+                currency_value,
+                active_ask_ledger,
+            ),
+            inputs=[ledger_state, ask_question, ask_chatbot, currency],
+            outputs=[ask_chatbot, ask_question],
+        )
+        ask_clear.click(
+            fn=lambda: (initial_ask_chat(), ""),
+            outputs=[ask_chatbot, ask_question],
+        )
+        ask_voice_button.click(
+            fn=lambda state, audio, history, currency_value: ask_ledger_voice_chat(
+                state,
+                audio,
+                history,
+                currency_value,
+                active_ask_ledger,
+            ),
+            inputs=[ledger_state, ask_voice, ask_chatbot, currency],
+            outputs=[ask_chatbot, ask_question, ask_voice],
+        )
+        command_button.click(
+            fn=run_command_palette,
+            inputs=[ledger_state, command_choice],
+            outputs=[command_output],
+        )
+        correction_button.click(
+            fn=apply_row_correction,
+            inputs=[ledger_state, correction_row, correction_field, correction_value, currency],
+            outputs=[
+                ledger,
+                summary,
+                reminders,
+                model_badge,
+                row_count,
+                download,
+                ledger_state,
+                input_notice,
+                dashboard,
+                chart_director,
+                daily_brief,
+                primary_plot,
+                secondary_plot,
+                tertiary_plot,
+                insights,
+                automation,
+                category_table,
+                party_table,
+                automation_table,
+                review,
+                review_table,
+                timeline,
+                timeline_plot,
+                timeline_table,
+                memory,
+                memory_table,
+                lantern,
+                lantern_table,
+                closing,
+                closing_table,
+                correction_status,
+            ],
+        )
+        chart_compose_button.click(
+            fn=lambda state, question: compose_chart(state, question, active_chart_composer),
+            inputs=[ledger_state, chart_question],
+            outputs=[chart_director, primary_plot, chart_question],
+        )
+        chart_question.submit(
+            fn=lambda state, question: compose_chart(state, question, active_chart_composer),
+            inputs=[ledger_state, chart_question],
+            outputs=[chart_director, primary_plot, chart_question],
+        )
+
+    return demo
+
+
+def add_to_ledger(
+    note: str,
+    audio_path: str | None,
+    document_path: Any,
+    source_choice: str,
+    currency: str,
+    state: list[dict[str, Any]] | None,
+    process_fn: ProcessFn,
+) -> tuple[Any, ...]:
+    rows = state or []
+    choice = choose_input(note, audio_path, document_path, source_choice)
+    if choice["status"] != "ready":
+        frame = pd.DataFrame(rows, columns=COLUMNS)
+        return (
+            frame,
+            build_summary(rows, {}),
+            build_reminders(rows, {}),
+            "Model: waiting for input",
+            f"Rows: {len(rows)}",
+            write_csv(rows) if rows else None,
+            rows,
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            gr.update(),
+            choice["notice"],
+            *render_intelligence(rows),
+        )
+
+    if choice["source"] == "audio":
+        combined_note = transcribe_audio(audio_path)
+        image_urls = None
+        if not combined_note:
+            frame = pd.DataFrame(rows, columns=COLUMNS)
+            return (
+                frame,
+                build_summary(rows, {}),
+                build_reminders(rows, {}),
+                "Model: waiting for audio transcript",
+                f"Rows: {len(rows)}",
+                write_csv(rows) if rows else None,
+                rows,
+                gr.update(),
+                gr.update(),
+                gr.update(),
+                gr.update(value="Voice note"),
+                "I could not transcribe that voice note. Try another recording or paste the note.",
+                *render_intelligence(rows),
+            )
+    elif choice["source"] == "document":
+        document = prepare_document_input(document_path)
+        combined_note = build_document_prompt(document)
+        image_urls = document.get("image_urls") or None
+        if not combined_note and not image_urls:
+            frame = pd.DataFrame(rows, columns=COLUMNS)
+            return (
+                frame,
+                build_summary(rows, {}),
+                build_reminders(rows, {}),
+                "Model: waiting for document text",
+                f"Rows: {len(rows)}",
+                write_csv(rows) if rows else None,
+                rows,
+                gr.update(),
+                gr.update(),
+                gr.update(),
+                gr.update(value="Document"),
+                "I could not prepare that document. Try a PDF, receipt image, or pasted note.",
+                *render_intelligence(rows),
+            )
+    else:
+        combined_note = (note or "").strip()
+        image_urls = None
+
+    result = process_fn(combined_note, currency or "LKR", image_urls)
+    rows = rows + compact_rows(result.get("entries", []))
+
+    frame = pd.DataFrame(rows, columns=COLUMNS)
+    summary = build_summary(rows, result)
+    reminder_text = build_reminders(rows, result)
+    csv_path = write_csv(rows) if rows else None
+    model = result.get("model_used", "unknown")
+    notice = f"Added {len(result.get('entries', []))} row(s) from the {choice['label'].lower()}."
+    next_note = gr.update(value="") if choice["source"] == "text" else gr.update()
+    next_audio = gr.update(value=None) if choice["source"] == "audio" else gr.update()
+    next_document = gr.update(value=None) if choice["source"] == "document" else gr.update()
+
+    return (
+        frame,
+        summary,
+        reminder_text,
+        f"Model: `{model}`",
+        f"Rows: {len(rows)}",
+        csv_path,
+        rows,
+        next_note,
+        next_audio,
+        next_document,
+        gr.update(value="Auto"),
+        notice,
+        *render_intelligence(rows),
+    )
+
+
+def choose_input(note: str | None, audio_path: str | None, document_path: Any, source_choice: str | None) -> dict[str, str]:
+    has_text = bool((note or "").strip())
+    has_audio = bool(audio_path)
+    has_document = bool(document_path)
+    choice = source_choice or "Auto"
+    present = [
+        label
+        for label, exists in (
+            ("written note", has_text),
+            ("voice note", has_audio),
+            ("document", has_document),
+        )
+        if exists
+    ]
+
+    if len(present) > 1 and choice == "Auto":
+        return {
+            "status": "conflict",
+            "notice": f"Multiple inputs are present ({', '.join(present)}). Choose Text note, Voice note, or Document, then add it to the ledger.",
+        }
+    if choice == "Text note" and not has_text:
+        return {"status": "missing", "notice": "Text note is selected, but the written note is empty."}
+    if choice == "Voice note" and not has_audio:
+        return {"status": "missing", "notice": "Voice note is selected, but no audio is attached."}
+    if choice == "Document" and not has_document:
+        return {"status": "missing", "notice": "Document is selected, but no file is attached."}
+    if not has_text and not has_audio and not has_document:
+        return {"status": "missing", "notice": "Add a written note, record a voice note, or upload a document first."}
+    if choice == "Voice note" or (choice == "Auto" and has_audio):
+        return {"status": "ready", "source": "audio", "label": "Voice note"}
+    if choice == "Document" or (choice == "Auto" and has_document):
+        return {"status": "ready", "source": "document", "label": "Document"}
+    return {"status": "ready", "source": "text", "label": "Text note"}
+
+
+def build_document_prompt(document: dict[str, Any]) -> str:
+    kind = document.get("kind") or "document"
+    page_count = document.get("page_count") or 0
+    text = str(document.get("text") or "").strip()
+    parts = [
+        f"Uploaded {kind} with {page_count} page/image(s).",
+        "Extract shop ledger entries from the visible document content.",
+    ]
+    if text:
+        parts.append(f"Text extracted from the document:\n{text}")
+    return "\n".join(parts).strip()
+
+
+def h(value: Any) -> str:
+    return escape(str(value or ""), quote=True)
+
+
+def compact_rows(entries: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    for entry in entries:
+        row = {column: entry.get(column, "") for column in COLUMNS}
+        row["amount"] = float(row["amount"] or 0)
+        row["confidence"] = round(float(row["confidence"] or 0), 2)
+        rows.append(row)
+    return rows
+
+
+def apply_row_correction(
+    state: list[dict[str, Any]] | None,
+    row_number: float | int | None,
+    field: str,
+    value: str,
+    currency: str,
+) -> tuple[Any, ...]:
+    rows = [dict(row) for row in (state or [])]
+    if not rows:
+        return render_local_edit(rows, currency, "Add ledger rows before applying a correction.")
+
+    try:
+        index = int(row_number or 0) - 1
+    except (TypeError, ValueError):
+        return render_local_edit(rows, currency, "Choose a valid row number.")
+
+    if index < 0 or index >= len(rows):
+        return render_local_edit(rows, currency, f"Row {row_number} is not in the current ledger.")
+
+    if field not in CORRECTION_FIELDS:
+        return render_local_edit(rows, currency, "Choose a field that can be corrected.")
+
+    raw_value = (value or "").strip()
+    if not raw_value:
+        return render_local_edit(rows, currency, "Type the corrected value first.")
+
+    try:
+        rows[index][field] = normalize_correction_value(field, raw_value)
+    except ValueError as exc:
+        return render_local_edit(rows, currency, str(exc))
+
+    if field != "confidence":
+        rows[index]["confidence"] = max(float(rows[index].get("confidence") or 0), 0.9)
+    if not rows[index].get("currency"):
+        rows[index]["currency"] = currency or "LKR"
+
+    return render_local_edit(rows, currency, f"Updated row {index + 1}: {field} = {h(raw_value)}.")
+
+
+def normalize_correction_value(field: str, value: str) -> Any:
+    if field == "amount":
+        cleaned = value.replace(",", "")
+        try:
+            return float(cleaned)
+        except ValueError as exc:
+            raise ValueError("Amount corrections need a number, like 1200 or 1,200.") from exc
+    if field == "confidence":
+        try:
+            number = float(value)
+        except ValueError as exc:
+            raise ValueError("Confidence corrections need a number from 0 to 1.") from exc
+        return round(max(0.0, min(1.0, number)), 2)
+    if field == "payment_status":
+        normalized = value.lower()
+        if normalized not in {"paid", "due", "partial", "unknown"}:
+            raise ValueError("Payment status must be paid, due, partial, or unknown.")
+        return normalized
+    if field == "direction":
+        normalized = value.lower()
+        if normalized not in {"expense", "income", "transfer", "unknown"}:
+            raise ValueError("Direction must be expense, income, transfer, or unknown.")
+        return normalized
+    return value
+
+
+def render_local_edit(rows: list[dict[str, Any]], currency: str, message: str) -> tuple[Any, ...]:
+    frame = pd.DataFrame(rows, columns=COLUMNS)
+    return (
+        frame,
+        build_summary(rows, {}),
+        build_reminders(rows, {}),
+        "Model: local correction",
+        f"Rows: {len(rows)}",
+        write_csv(rows) if rows else None,
+        rows,
+        message,
+        *render_intelligence(rows),
+        message,
+    )
+
+
+def build_summary(rows: list[dict[str, Any]], result: dict[str, Any]) -> str:
+    if not rows:
+        return "No ledger rows yet."
+
+    expenses = sum_amount(rows, "expense", "paid")
+    income = sum_amount(rows, "income", "paid")
+    due = sum(float(row.get("amount") or 0) for row in rows if row.get("payment_status") == "due")
+    categories = category_totals(rows)
+    category_text = ", ".join(f"{h(name)}: {amount:,.0f}" for name, amount in categories[:4])
+    questions = result.get("questions") or []
+    question_text = "\n".join(f"- {h(question)}" for question in questions)
+
+    summary = (
+        f"### Totals\n"
+        f"- Expenses paid: **{expenses:,.0f}**\n"
+        f"- Income received: **{income:,.0f}**\n"
+        f"- Still due: **{due:,.0f}**\n"
+    )
+    if category_text:
+        summary += f"- Top categories: {category_text}\n"
+    if question_text:
+        summary += f"\n### Check With User\n{question_text}\n"
+    return summary
+
+
+def build_reminders(rows: list[dict[str, Any]], result: dict[str, Any]) -> str:
+    reminders = list(result.get("reminders") or [])
+    reminders.extend(row["reminder"] for row in rows if row.get("reminder"))
+    unique = []
+    for reminder in reminders:
+        if reminder and reminder not in unique:
+            unique.append(reminder)
+    if not unique:
+        return "No reminders yet."
+    return "### Follow-ups\n" + "\n".join(f"- {h(reminder)}" for reminder in unique[:8])
+
+
+def sum_amount(rows: list[dict[str, Any]], direction: str, status: str) -> float:
+    return sum(
+        float(row.get("amount") or 0)
+        for row in rows
+        if row.get("direction") == direction and row.get("payment_status") == status
+    )
+
+
+def category_totals(rows: list[dict[str, Any]]) -> list[tuple[str, float]]:
+    totals: dict[str, float] = {}
+    for row in rows:
+        category = row.get("category") or "uncategorized"
+        totals[category] = totals.get(category, 0.0) + float(row.get("amount") or 0)
+    return sorted(totals.items(), key=lambda item: item[1], reverse=True)
+
+
+def write_csv(rows: list[dict[str, Any]]) -> str:
+    handle = tempfile.NamedTemporaryFile("w", suffix=".csv", delete=False, newline="")
+    with handle:
+        writer = csv.DictWriter(handle, fieldnames=COLUMNS)
+        writer.writeheader()
+        writer.writerows(rows)
+    return handle.name
+
+
+def render_intelligence(rows: list[dict[str, Any]]) -> tuple[Any, ...]:
+    categories, parties, followups, reviews = build_tables(rows)
+    primary_chart, secondary_chart, tertiary_chart = build_insight_figures(rows)
+    return (
+        build_dashboard_markdown(rows),
+        build_chart_markdown(rows),
+        build_daily_brief_markdown(rows),
+        primary_chart,
+        secondary_chart,
+        tertiary_chart,
+        build_insights_markdown(rows),
+        build_reminder_markdown(rows),
+        pd.DataFrame(categories, columns=["category", "total", "display"]),
+        pd.DataFrame(parties, columns=["party", "total", "due"]),
+        pd.DataFrame(
+            followups,
+            columns=[
+                "priority",
+                "counterparty",
+                "amount",
+                "item",
+                "next_action",
+                "cadence",
+                "polite_script",
+                "friendly_script",
+                "firm_script",
+                "source_row",
+            ],
+        ),
+        build_review_markdown(rows),
+        pd.DataFrame(
+            reviews,
+            columns=["source_row", "issue", "confidence", "counterparty", "item", "amount", "question"],
+        ),
+        build_timeline_markdown(rows),
+        timeline_figure(rows),
+        pd.DataFrame(
+            timeline_rows(rows),
+            columns=[
+                "source_row",
+                "date",
+                "badge",
+                "direction",
+                "counterparty",
+                "item",
+                "amount",
+                "signed_amount",
+                "status",
+                "story",
+            ],
+        ),
+        build_counterparty_memory_markdown(rows),
+        pd.DataFrame(
+            counterparty_memory_cards(rows),
+            columns=[
+                "party",
+                "trust_pulse",
+                "total_moved",
+                "paid",
+                "due",
+                "usual_category",
+                "usual_item",
+                "last_item",
+                "row_count",
+                "next_message",
+            ],
+        ),
+        build_anomaly_lantern_markdown(rows),
+        pd.DataFrame(
+            anomaly_lantern_rows(rows),
+            columns=["source_row", "severity", "signal", "counterparty", "item", "amount", "reason"],
+        ),
+        build_closing_ritual_markdown(rows),
+        pd.DataFrame(closing_checklist(rows), columns=["step", "status", "detail"]),
+    )
+
+
+def clear_ledger() -> tuple[Any, ...]:
+    return (
+        pd.DataFrame([], columns=COLUMNS),
+        "No ledger rows yet.",
+        "No reminders yet.",
+        "Model: not run yet",
+        "Rows: 0",
+        None,
+        [],
+        "",
+        None,
+        None,
+        "Auto",
+        "Ready for one note.",
+        *render_intelligence([]),
+    )
+
+
+def generate_daily_brief(
+    state: list[dict[str, Any]] | None,
+    currency: str,
+    daily_brief_fn: DailyBriefFn,
+) -> str:
+    rows = state or []
+    result = daily_brief_fn(rows, currency or "LKR")
+    return build_daily_brief_markdown(rows, result.get("brief"), result.get("model_used", "unknown"))
+
+
+def ask_ledger(
+    state: list[dict[str, Any]] | None,
+    question: str,
+    currency: str,
+    ask_ledger_fn: AskLedgerFn,
+) -> str:
+    rows = state or []
+    result = ask_ledger_fn(rows, question or "", currency or "LKR")
+    answer = result.get("answer") or "No answer available."
+    model_used = result.get("model_used", "unknown")
+    return f"### Ask My Ledger\n{answer}\n\n<small>Answer: {model_used}</small>"
+
+
+def initial_ask_chat() -> ChatHistory:
+    return [
+        {
+            "role": "assistant",
+            "content": "Ask me about dues, follow-ups, spending, or today’s cash position after you add ledger rows.",
+        }
+    ]
+
+
+def ask_ledger_chat(
+    state: list[dict[str, Any]] | None,
+    question: str,
+    history: ChatHistory | None,
+    currency: str,
+    ask_ledger_fn: AskLedgerFn,
+) -> tuple[ChatHistory, str]:
+    clean_question = (question or "").strip()
+    next_history: ChatHistory = list(history or initial_ask_chat())
+    if not clean_question:
+        next_history.append({"role": "assistant", "content": "Ask a question first, then I’ll answer from the ledger rows."})
+        return next_history, ""
+
+    rows = state or []
+    result = ask_ledger_fn(rows, clean_question, currency or "LKR")
+    answer = result.get("answer") or "No answer available."
+    model_used = result.get("model_used", "unknown")
+    next_history.append({"role": "user", "content": clean_question})
+    next_history.append({"role": "assistant", "content": f"{answer}\n\nAnswer source: {model_used}"})
+    return next_history, ""
+
+
+def ask_ledger_voice_chat(
+    state: list[dict[str, Any]] | None,
+    audio_path: str | None,
+    history: ChatHistory | None,
+    currency: str,
+    ask_ledger_fn: AskLedgerFn,
+    transcribe_fn: Callable[[str | None], str] = transcribe_audio,
+) -> tuple[ChatHistory, str, Any]:
+    transcript = transcribe_fn(audio_path).strip()
+    next_history: ChatHistory = list(history or initial_ask_chat())
+    if not transcript:
+        next_history.append(
+            {
+                "role": "assistant",
+                "content": "I could not hear a question clearly. Try recording again or type the question.",
+            }
+        )
+        return next_history, "", None
+    history_with_answer, _ = ask_ledger_chat(state, transcript, next_history, currency, ask_ledger_fn)
+    return history_with_answer, "", None
+
+
+def run_command_palette(state: list[dict[str, Any]] | None, command: str) -> str:
+    return run_ledger_command(state or [], command)
+
+
+def compose_chart(
+    state: list[dict[str, Any]] | None,
+    question: str,
+    chart_composer_fn: ChartComposerFn,
+) -> tuple[str, Any, str]:
+    rows = state or []
+    spec = chart_composer_fn(rows, question or "")
+    return build_chart_composer_markdown(question or "", spec), figure_for_chart_id(rows, spec.get("chart", "")), ""

tests/__init__.py

@@ -0,0 +1 @@
+

tests/test_heuristics.py

@@ -0,0 +1,27 @@
+import unittest
+
+from shop_ledger.heuristics import heuristic_extract
+
+
+class HeuristicExtractionTests(unittest.TestCase):
+    def test_extracts_multiple_rows_and_due_reminder(self):
+        result = heuristic_extract(
+            "paid Ravi 1200 for rice bags, customer Nimal owes 750 for tea packets"
+        )
+
+        self.assertEqual(len(result.entries), 2)
+        self.assertEqual(result.entries[0].amount, 1200)
+        self.assertEqual(result.entries[0].direction, "expense")
+        self.assertEqual(result.entries[1].amount, 750)
+        self.assertEqual(result.entries[1].payment_status, "due")
+        self.assertTrue(result.reminders)
+
+    def test_missing_amount_adds_question(self):
+        result = heuristic_extract("paid Ravi for rice bags")
+
+        self.assertEqual(result.entries[0].amount, 0)
+        self.assertTrue(result.questions)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_insights.py

@@ -0,0 +1,230 @@
+import unittest
+
+from shop_ledger.insights import (
+    answer_ledger_question,
+    anomaly_lantern_rows,
+    build_anomaly_lantern_markdown,
+    build_chart_plan,
+    build_chart_composer_markdown,
+    build_closing_ritual_markdown,
+    build_counterparty_memory_markdown,
+    build_daily_brief_markdown,
+    build_insight_figures,
+    build_timeline_markdown,
+    compute_metrics,
+    closing_checklist,
+    counterparty_memory_cards,
+    chart_spec_from_question,
+    daily_brief_fallback,
+    followup_rows,
+    review_rows,
+    risk_flags,
+    run_ledger_command,
+    timeline_figure,
+    timeline_rows,
+)
+
+
+ROWS = [
+    {
+        "direction": "expense",
+        "payment_status": "paid",
+        "amount": 1200,
+        "currency": "LKR",
+        "counterparty": "Ravi",
+        "item": "rice bags",
+        "category": "inventory",
+        "confidence": 0.9,
+    },
+    {
+        "direction": "income",
+        "payment_status": "due",
+        "amount": 7500,
+        "currency": "LKR",
+        "counterparty": "Nimal",
+        "item": "tea packets",
+        "category": "sales",
+        "confidence": 0.8,
+        "reminder": "Follow up with Nimal about LKR 7,500.",
+    },
+]
+
+
+class InsightTests(unittest.TestCase):
+    def test_metrics_include_cash_and_followups(self):
+        metrics = compute_metrics(ROWS)
+
+        self.assertEqual(metrics["paid_expense"], 1200)
+        self.assertEqual(metrics["due_income"], 7500)
+        self.assertEqual(metrics["open_followups"], 1)
+
+    def test_followup_rows_include_script_and_priority(self):
+        queue = followup_rows(ROWS)
+
+        self.assertEqual(queue[0]["priority"], "High")
+        self.assertIn("Nimal", queue[0]["script"])
+        self.assertIn("polite_script", queue[0])
+        self.assertIn("friendly_script", queue[0])
+        self.assertIn("firm_script", queue[0])
+        self.assertIn("settle", queue[0]["firm_script"])
+
+    def test_risk_flags_include_high_value_due(self):
+        flags = risk_flags(ROWS)
+
+        self.assertTrue(any("High-value due item" in flag for flag in flags))
+
+    def test_chart_plan_prioritizes_due_followups(self):
+        plan = build_chart_plan(ROWS)
+
+        self.assertEqual(plan["chart"], "due_by_party")
+        self.assertIn("unpaid", plan["question"].lower())
+
+    def test_insight_figures_return_plotly_figures(self):
+        figures = build_insight_figures(ROWS)
+
+        self.assertEqual(len(figures), 3)
+        self.assertTrue(all(hasattr(figure, "to_plotly_json") for figure in figures))
+
+    def test_review_rows_include_low_confidence_entries(self):
+        rows = ROWS + [
+            {
+                "direction": "expense",
+                "payment_status": "",
+                "amount": 0,
+                "currency": "LKR",
+                "counterparty": "",
+                "item": "unknown",
+                "category": "uncategorized",
+                "confidence": 0.42,
+            }
+        ]
+
+        queue = review_rows(rows)
+
+        self.assertEqual(queue[0]["source_row"], 3)
+        self.assertIn("Low confidence", queue[0]["issue"])
+        self.assertIn("confirm", queue[0]["question"])
+
+    def test_daily_brief_fallback_mentions_cash_and_followup(self):
+        brief = daily_brief_fallback(ROWS)
+
+        self.assertIn("Net cash", brief)
+        self.assertIn("Nimal", brief)
+
+    def test_daily_brief_markdown_wraps_model_name(self):
+        model_label = "unsloth/gemma-4-12b-it-GGUF / gemma-4-12b-it-UD-Q4_K_XL.gguf / llama.cpp"
+        markdown = build_daily_brief_markdown(ROWS, "Cash is tight today.", model_label)
+
+        self.assertIn("Today's Shop Pulse", markdown)
+        self.assertIn("unsloth/gemma-4-12b-it-GGUF", markdown)
+
+    def test_answer_ledger_question_answers_dues(self):
+        answer = answer_ledger_question(ROWS, "Who owes me most?")
+
+        self.assertIn("Nimal", answer)
+        self.assertIn("LKR 7,500", answer)
+
+    def test_answer_ledger_question_answers_cash_spend(self):
+        answer = answer_ledger_question(ROWS, "Where did cash go?")
+
+        self.assertIn("inventory", answer)
+
+    def test_timeline_rows_turn_entries_into_story_events(self):
+        events = timeline_rows(ROWS)
+
+        self.assertEqual(events[0]["source_row"], 1)
+        self.assertIn("Ravi", events[0]["story"])
+        self.assertEqual(events[1]["badge"], "Due")
+
+    def test_timeline_markdown_and_figure_render(self):
+        markdown = build_timeline_markdown(ROWS)
+        figure = timeline_figure(ROWS)
+
+        self.assertIn("Shop Pulse Timeline", markdown)
+        self.assertTrue(hasattr(figure, "to_plotly_json"))
+
+    def test_counterparty_memory_cards_surface_due_profile(self):
+        cards = counterparty_memory_cards(ROWS)
+
+        self.assertEqual(cards[0]["party"], "Nimal")
+        self.assertEqual(cards[0]["trust_pulse"], "Collect first")
+        self.assertIn("Follow up", cards[0]["next_message"])
+
+    def test_counterparty_memory_markdown_renders_cards(self):
+        markdown = build_counterparty_memory_markdown(ROWS)
+
+        self.assertIn("Counterparty Memory", markdown)
+        self.assertIn("Nimal", markdown)
+
+    def test_run_ledger_command_shows_unpaid(self):
+        output = run_ledger_command(ROWS, "Show unpaid")
+
+        self.assertIn("Unpaid", output)
+        self.assertIn("Nimal", output)
+
+    def test_run_ledger_command_prepares_quickbooks_plan(self):
+        output = run_ledger_command(ROWS, "Prepare QuickBooks export")
+
+        self.assertIn("QuickBooks", output)
+        self.assertIn("Customer/Vendor", output)
+
+    def test_chart_spec_from_question_selects_expense_chart(self):
+        spec = chart_spec_from_question(ROWS, "Where did cash go?")
+
+        self.assertEqual(spec["chart"], "expense_categories")
+
+    def test_chart_composer_markdown_names_chart(self):
+        markdown = build_chart_composer_markdown("Who owes?", {"chart": "due_by_party", "reason": "Dues", "model_used": "fake"})
+
+        self.assertIn("AI Chart Composer", markdown)
+        self.assertIn("Due radar", markdown)
+
+    def test_anomaly_lantern_flags_high_due_and_missing_amount(self):
+        rows = ROWS + [{"counterparty": "Saman", "item": "unknown", "amount": 0, "currency": "LKR", "confidence": 0.4}]
+
+        anomalies = anomaly_lantern_rows(rows)
+
+        self.assertTrue(any(item["signal"] == "High-value due" for item in anomalies))
+        self.assertTrue(any(item["signal"] == "Missing amount" for item in anomalies))
+
+    def test_anomaly_lantern_markdown_renders_cards(self):
+        markdown = build_anomaly_lantern_markdown(ROWS)
+
+        self.assertIn("Anomaly Lantern", markdown)
+        self.assertIn("High-value due", markdown)
+
+    def test_html_values_are_escaped_in_cards(self):
+        rows = [
+            {
+                "direction": "income",
+                "payment_status": "due",
+                "amount": 7500,
+                "currency": "LKR",
+                "counterparty": "<script>alert(1)</script>",
+                "item": "tea",
+                "category": "sales",
+                "confidence": 0.8,
+                "reminder": "Follow <script>alert(1)</script>",
+            }
+        ]
+
+        markdown = build_anomaly_lantern_markdown(rows) + build_counterparty_memory_markdown(rows)
+
+        self.assertNotIn("<script>", markdown)
+        self.assertIn("&lt;script&gt;", markdown)
+
+    def test_closing_checklist_includes_export_step(self):
+        checklist = closing_checklist(ROWS)
+
+        self.assertTrue(any(item["step"] == "Export ledger" for item in checklist))
+        self.assertTrue(any(item["status"] == "Action" for item in checklist))
+
+    def test_closing_ritual_markdown_summarizes_day(self):
+        markdown = build_closing_ritual_markdown(ROWS)
+
+        self.assertIn("Daily Closing Ritual", markdown)
+        self.assertIn("Closing Checklist", markdown)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_processor.py

@@ -0,0 +1,44 @@
+import unittest
+from unittest.mock import patch
+
+from shop_ledger.llama_backend import LlamaLedgerBackend
+from shop_ledger.processor import LedgerProcessor, resolve_model_path_from_env
+
+
+class ProcessorTests(unittest.TestCase):
+    def test_mock_processor_returns_rows(self):
+        processor = LedgerProcessor(mode="mock")
+        result = processor.process("paid Ravi 1200 for rice bags")
+
+        self.assertEqual(result.model_used, "mock heuristic")
+        self.assertEqual(len(result.entries), 1)
+        self.assertEqual(result.entries[0].amount, 1200)
+
+    def test_llama_mode_falls_back_without_model(self):
+        processor = LedgerProcessor(mode="llama", model_path="/missing/model.gguf")
+        result = processor.process("customer Nimal owes 750")
+
+        self.assertIn("fallback", result.model_used)
+        self.assertEqual(result.entries[0].amount, 750)
+
+    def test_llama_backend_uses_readable_model_label(self):
+        label = "unsloth/gemma-4-12b-it-GGUF / gemma-4-12b-it-UD-Q4_K_XL.gguf / llama.cpp"
+        with patch.dict("os.environ", {"LLAMA_MODEL_LABEL": label}):
+            backend = LlamaLedgerBackend(model_path="/models/model.gguf")
+
+        self.assertEqual(backend.model_label, label)
+
+    def test_env_model_path_wins_for_modal_mounts(self):
+        with patch.dict(
+            "os.environ",
+            {
+                "LLAMA_GGUF_PATH": "/models/model.gguf",
+                "LLAMA_GGUF_REPO": "unused/repo",
+                "LLAMA_GGUF_FILE": "unused.gguf",
+            },
+        ):
+            self.assertEqual(resolve_model_path_from_env(), "/models/model.gguf")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_ui_input_choice.py

@@ -0,0 +1,273 @@
+import unittest
+from tempfile import NamedTemporaryFile
+
+from shop_ledger.processor import extract_document_text, prepare_document_input
+from shop_ledger.ui import (
+    add_to_ledger,
+    apply_row_correction,
+    ask_ledger,
+    ask_ledger_chat,
+    ask_ledger_voice_chat,
+    choose_input,
+    compose_chart,
+    generate_daily_brief,
+    initial_ask_chat,
+    run_command_palette,
+)
+
+
+class InputChoiceTests(unittest.TestCase):
+    def test_auto_asks_when_text_and_audio_exist(self):
+        choice = choose_input("paid Ravi 1200", "/tmp/audio.wav", None, "Auto")
+
+        self.assertEqual(choice["status"], "conflict")
+        self.assertIn("Multiple inputs", choice["notice"])
+
+    def test_text_choice_uses_text_when_audio_exists(self):
+        choice = choose_input("paid Ravi 1200", "/tmp/audio.wav", None, "Text note")
+
+        self.assertEqual(choice["status"], "ready")
+        self.assertEqual(choice["source"], "text")
+
+    def test_auto_uses_audio_when_audio_is_only_input(self):
+        choice = choose_input("", "/tmp/audio.wav", None, "Auto")
+
+        self.assertEqual(choice["status"], "ready")
+        self.assertEqual(choice["source"], "audio")
+
+    def test_auto_uses_document_when_document_is_only_input(self):
+        choice = choose_input("", None, "/tmp/receipt.pdf", "Auto")
+
+        self.assertEqual(choice["status"], "ready")
+        self.assertEqual(choice["source"], "document")
+
+    def test_document_text_extraction_reads_plain_text_files(self):
+        with NamedTemporaryFile("w", suffix=".txt") as handle:
+            handle.write("paid Ravi 1200 for rice bags")
+            handle.flush()
+
+            text = extract_document_text(handle.name)
+
+        self.assertIn("Ravi", text)
+
+    def test_document_image_preparation_creates_data_url(self):
+        from PIL import Image
+
+        with NamedTemporaryFile(suffix=".png") as handle:
+            Image.new("RGB", (8, 8), color="white").save(handle.name)
+
+            document = prepare_document_input(handle.name)
+
+        self.assertEqual(document["kind"], "image")
+        self.assertTrue(document["image_urls"][0].startswith("data:image/jpeg;base64,"))
+
+    def test_successful_text_add_clears_written_note(self):
+        def fake_process(note, currency, image_urls=None):
+            return {
+                "entries": [
+                    {
+                        "date": "2026-06-11",
+                        "direction": "expense",
+                        "counterparty": "Ravi",
+                        "item": "rice bags",
+                        "quantity": "",
+                        "amount": 1200,
+                        "currency": currency,
+                        "category": "inventory",
+                        "payment_status": "paid",
+                        "due_date": "",
+                        "confidence": 0.9,
+                        "reminder": "",
+                    }
+                ],
+                "reminders": [],
+                "questions": [],
+                "model_used": "fake",
+            }
+
+        output = add_to_ledger("paid Ravi 1200", None, None, "Auto", "LKR", [], fake_process)
+
+        self.assertEqual(len(output[6]), 1)
+        self.assertEqual(output[7]["value"], "")
+        self.assertEqual(output[10]["value"], "Auto")
+        self.assertIn("Added 1 row", output[11])
+
+    def test_successful_document_add_sends_image_urls_and_clears_file(self):
+        captured = {}
+
+        def fake_process(note, currency, image_urls=None):
+            captured["note"] = note
+            captured["image_urls"] = image_urls
+            return {
+                "entries": [
+                    {
+                        "date": "2026-06-11",
+                        "direction": "expense",
+                        "counterparty": "Ravi",
+                        "item": "rice bags",
+                        "quantity": "",
+                        "amount": 1200,
+                        "currency": currency,
+                        "category": "inventory",
+                        "payment_status": "paid",
+                        "due_date": "",
+                        "confidence": 0.9,
+                        "reminder": "",
+                    }
+                ],
+                "reminders": [],
+                "questions": [],
+                "model_used": "fake",
+            }
+
+        with NamedTemporaryFile("w", suffix=".txt") as handle:
+            handle.write("paid Ravi 1200 for rice bags")
+            handle.flush()
+
+            output = add_to_ledger("", None, handle.name, "Document", "LKR", [], fake_process)
+
+        self.assertIn("paid Ravi", captured["note"])
+        self.assertIsNone(captured["image_urls"])
+        self.assertEqual(output[9]["value"], None)
+        self.assertIn("Added 1 row", output[11])
+
+    def test_generate_daily_brief_uses_supplied_function(self):
+        rows = [{"amount": 1200, "currency": "LKR", "direction": "expense", "payment_status": "paid"}]
+
+        markdown = generate_daily_brief(
+            rows,
+            "LKR",
+            lambda supplied_rows, currency: {"brief": f"{len(supplied_rows)} rows in {currency}", "model_used": "fake"},
+        )
+
+        self.assertIn("1 rows in LKR", markdown)
+        self.assertIn("fake", markdown)
+
+    def test_ask_ledger_uses_supplied_function(self):
+        rows = [{"amount": 7500, "currency": "LKR", "payment_status": "due"}]
+
+        markdown = ask_ledger(
+            rows,
+            "Who owes me most?",
+            "LKR",
+            lambda supplied_rows, question, currency: {"answer": f"{question} / {len(supplied_rows)}", "model_used": "fake"},
+        )
+
+        self.assertIn("Who owes me most?", markdown)
+        self.assertIn("fake", markdown)
+
+    def test_ask_ledger_chat_appends_messages_and_clears_input(self):
+        rows = [{"amount": 7500, "currency": "LKR", "payment_status": "due"}]
+
+        history, next_question = ask_ledger_chat(
+            rows,
+            "Who owes me most?",
+            initial_ask_chat(),
+            "LKR",
+            lambda supplied_rows, question, currency: {"answer": "Nimal owes LKR 7,500.", "model_used": "fake"},
+        )
+
+        self.assertEqual(next_question, "")
+        self.assertEqual(history[-2]["role"], "user")
+        self.assertEqual(history[-1]["role"], "assistant")
+        self.assertIn("Nimal", history[-1]["content"])
+
+    def test_ask_ledger_voice_chat_transcribes_and_answers(self):
+        history, next_question, next_audio = ask_ledger_voice_chat(
+            [{"counterparty": "Nimal", "amount": 7500, "payment_status": "due", "currency": "LKR"}],
+            "/tmp/question.wav",
+            initial_ask_chat(),
+            "LKR",
+            lambda rows, question, currency: {"answer": f"Answered: {question}", "model_used": "fake"},
+            transcribe_fn=lambda path: "Who owes me most?",
+        )
+
+        self.assertEqual(next_question, "")
+        self.assertIsNone(next_audio)
+        self.assertIn("Who owes me most?", history[-2]["content"])
+        self.assertIn("Answered", history[-1]["content"])
+
+    def test_ask_ledger_voice_chat_handles_empty_transcript(self):
+        history, _, next_audio = ask_ledger_voice_chat(
+            [],
+            "/tmp/question.wav",
+            initial_ask_chat(),
+            "LKR",
+            lambda rows, question, currency: {"answer": "unused", "model_used": "fake"},
+            transcribe_fn=lambda path: "",
+        )
+
+        self.assertIsNone(next_audio)
+        self.assertIn("could not hear", history[-1]["content"])
+
+    def test_run_command_palette_uses_current_rows(self):
+        rows = [{"payment_status": "due", "counterparty": "Nimal", "amount": 7500, "currency": "LKR", "item": "tea"}]
+
+        output = run_command_palette(rows, "Show unpaid")
+
+        self.assertIn("Nimal", output)
+
+    def test_compose_chart_returns_markdown_figure_and_clears_input(self):
+        rows = [{"payment_status": "due", "counterparty": "Nimal", "amount": 7500, "currency": "LKR"}]
+
+        markdown, figure, next_question = compose_chart(
+            rows,
+            "Who owes me?",
+            lambda supplied_rows, question: {"chart": "due_by_party", "reason": "Dues", "model_used": "fake"},
+        )
+
+        self.assertIn("Due radar", markdown)
+        self.assertTrue(hasattr(figure, "to_plotly_json"))
+        self.assertEqual(next_question, "")
+
+    def test_apply_row_correction_updates_state_and_confidence(self):
+        rows = [
+            {
+                "date": "2026-06-11",
+                "direction": "income",
+                "counterparty": "",
+                "item": "tea packets",
+                "quantity": "",
+                "amount": 750,
+                "currency": "LKR",
+                "category": "sales",
+                "payment_status": "due",
+                "due_date": "",
+                "confidence": 0.42,
+                "reminder": "",
+            }
+        ]
+
+        output = apply_row_correction(rows, 1, "counterparty", "Nimal", "LKR")
+
+        updated_rows = output[6]
+        self.assertEqual(updated_rows[0]["counterparty"], "Nimal")
+        self.assertEqual(updated_rows[0]["confidence"], 0.9)
+        self.assertIn("Updated row 1", output[-1])
+
+    def test_apply_row_correction_rejects_bad_amount(self):
+        rows = [
+            {
+                "date": "2026-06-11",
+                "direction": "income",
+                "counterparty": "Nimal",
+                "item": "tea packets",
+                "quantity": "",
+                "amount": 750,
+                "currency": "LKR",
+                "category": "sales",
+                "payment_status": "due",
+                "due_date": "",
+                "confidence": 0.42,
+                "reminder": "",
+            }
+        ]
+
+        output = apply_row_correction(rows, 1, "amount", "many rupees", "LKR")
+
+        self.assertEqual(output[6][0]["amount"], 750)
+        self.assertIn("need a number", output[-1])
+
+
+if __name__ == "__main__":
+    unittest.main()