README.md

---
title: VoiceLedger
emoji: 📉
colorFrom: yellow
colorTo: green
sdk: gradio
sdk_version: 6.17.3
python_version: '3.13'
app_file: app.py
pinned: false
short_description: voice bookkeeping for informal sellers
tags:
  - track:backyard
  - sponsor:openai
  - sponsor:nvidia
  - sponsor:modal
  - achievement:offgrid
  - achievement:welltuned
  - achievement:offbrand
  - achievement:llama
  - achievement:sharing
  - achievement:fieldnotes
---

# VoiceLedger

VoiceLedger is a voice-first bookkeeping app for informal sellers, street vendors, home businesses, and small shop owners who track sales, customer dues, stock, and daily profit from quick spoken or typed notes.

The submission version is feature-frozen around the complete demo loop:

- Record a transaction with your microphone and transcribe it with faster-whisper.
- Configure seller context: business name, currency label, low-stock threshold, and language style.
- Pick common currency presets for INR, USD, EUR, GBP, MXN, and BRL, or enter a custom currency label.
- Follow a Guided Judge Mode path for health check, seeded data, sale capture, save, dashboard, and reports.
- Use a first-run “Start in 60 seconds” guide for setup, first transaction, review, and closeout.
- Type or paste a transaction note.
- Bulk import multiple pasted notes for review and editing.
- Parse it with Modal-hosted NVIDIA Nemotron when configured, with local rules as a deterministic fallback.
- Parse common English, Hinglish, Hindi-lite, Gujarati-lite, Spanish, French, and Portuguese seller phrases with deterministic fallback rules.
- Review a human-friendly transaction card with warning badges before saving.
- See a language/confidence chip after parsing so multilingual notes are visibly handled.
- Use price memory to fill missing sale price/amount from the latest saved item sale.
- Correct transaction type, item, customer, quantity, price, amount, notes, and confidence directly before saving.
- Keep a correction log for review edits so model/rule mistakes become visible field-test evidence.
- Choose `Cloud AI first` or `Local fallback only` from the Record screen to make the AI route explicit during demos.
- Save the structured transaction to SQLite.
- See a “Saved just now” receipt with bookkeeping side effects.
- View the ledger, customer credit book, and inventory in a Gradio interface.
- Monitor business insights, an Insight Coach, a Command Center, a seller-day activity timeline, and a daily sales/expense chart.
- Use a mobile-first, business-style Gradio interface with custom styling.
- Run a Daily Closeout that prepares PDF, WhatsApp summary, and CSV exports together.
- Download a Daily Summary PDF report.
- Generate WhatsApp-ready daily business summaries in English, Spanish, French, or Portuguese.
- Run shortcut commands like `close today`, `show Amit`, or `stock mangoes`.
- Generate customer follow-up reminders and an inventory reorder list.
- Use a debt reminder queue sorted by highest customer balance.
- Use reorder intelligence that combines stock threshold with recent sold quantity.
- Capture field-test evidence with a seller checklist and anonymized feedback notes.
- Offload speech transcription and LLM parsing to optional Modal endpoints.
- Edit or delete saved transactions while keeping customer credit and inventory balances consistent.
- Export the ledger as CSV for spreadsheet sharing.

Social Media post:
X - https://x.com/SagarPa65006244/status/2066664195769438554?s=20


When Modal endpoints are configured, parsing runs through the Modal backend using `nvidia/NVIDIA-Nemotron-3-Nano-4B` via Hugging Face Inference. If Modal is unavailable or returns an invalid response, VoiceLedger falls back to the local rule parser for demo reliability. The `Local fallback only` mode intentionally skips Modal for local-first demos and reliability checks.

VoiceLedger is designed for the Build Small Hackathon Backyard AI track: a concrete, real-world bookkeeping problem for informal sellers and home businesses. The demo story is anonymized around a local seller who tracks sales, customer dues, stock, and daily profit from short voice notes.

## Judge Demo Flow

Use the `Sections` navigation in the Space:

1. `Record Text & Voice`: click `Seed Demo Transactions`, then type or speak `Sold 12 mangoes, 20 each`.
2. Parse and inspect the review card; warning badges show missing fields, low confidence, duplicate risk, or negative stock.
3. Edit the inline review fields before saving to show correction UX for real sellers.
4. Toggle `Cloud AI first` versus `Local fallback only` to show the Modal/Nemotron path and deterministic backup.
5. Save the reviewed transaction and show the “Saved just now” receipt.
6. Open `Dashboard`, `Customer Credit`, `Inventory`, and `Ledger` to show the Insight Coach, timeline, details, and automatic bookkeeping updates.
7. Open `Field Test` to show the seller checklist and anonymized feedback notes.
8. Open `Reports & PDF` to run Daily Closeout, download the PDF/CSV, and generate the WhatsApp summary.
9. Open `Demo Health` to show Modal backend status, deployed backend version, NVIDIA Nemotron parser status, SQLite, PDF support, and configured endpoints.

## Example Inputs

Try these in `Record Text & Voice` or paste them together in `Bulk Import`. The Record page groups examples by English, Hinglish, Gujarati-lite, Spanish, French, and Portuguese so the local seller language story is visible in the UI.

```text
Sold 12 mangoes, 20 each
Paid 500 for supplies
Amit owes 100
Bought 50 mangoes
Amit ne 100 dene hai
50 mango kharida
Vendí 12 mangos, 20 cada uno
Vendu 12 mangues, 20 chacun
Vendi 12 mangas, 20 cada
```

The same examples are available in `sample_data/demo_transactions.txt`.

## Examples

| Input | Parsed result |
| --- | --- |
| `Sold 12 mangoes, 20 each` | Sale, quantity `12`, item `mangoes`, unit price `20`, amount `240` |
| `mango 12 x 20` | Sale, quantity `12`, item `mango`, unit price `20`, amount `240` |
| `Paid 500 for supplies` | Expense, amount `500`, item `supplies` |
| `rent 300` | Expense, amount `300`, item `rent` |
| `Bought 50 mangoes` | Inventory purchase, quantity `50`, item `mangoes` |
| `Amit owes 100` | Customer credit, customer `Amit`, amount `100` |
| `Amit paid 50` | Customer payment, customer `Amit`, amount `50` |
| `Amit ne 100 dene hai` | Customer credit, customer `Amit`, amount `100` |
| `Amit ne 50 diya` | Customer payment, customer `Amit`, amount `50` |
| `50 mango kharida` | Inventory purchase, quantity `50`, item `mango` |
| `50 mango lidha` | Inventory purchase, quantity `50`, item `mango` |
| `Vendí 12 mangos, 20 cada uno` | Sale, quantity `12`, item `mangos`, unit price `20`, amount `240` |
| `Pagué 500 por suministros` | Expense, amount `500`, item `suministros` |
| `Amit debe 100` | Customer credit, customer `Amit`, amount `100` |
| `Vendu 12 mangues, 20 chacun` | Sale, quantity `12`, item `mangues`, unit price `20`, amount `240` |
| `Amit doit 100` | Customer credit, customer `Amit`, amount `100` |
| `Vendi 12 mangas, 20 cada` | Sale, quantity `12`, item `mangas`, unit price `20`, amount `240` |
| `Amit deve 100` | Customer credit, customer `Amit`, amount `100` |

## Demo Script

1. Use `Seller Setup` to show business name, currency, low-stock threshold, and language style.
2. Use the `Hackathon Demo Launchpad` on the first screen to seed demo transactions.
3. Open `Record Text & Voice`, speak or type `Sold 12 mangoes, 20 each`, parse it, and review the human-readable transaction card.
4. Correct one inline review field before saving, such as quantity or amount, to show the seller correction loop.
5. Show the parse status, language/confidence chip, and warning badges: Modal/NVIDIA Nemotron when available, local fallback when needed.
6. Save the transaction and show the Command Center plus the receipt with stock, customer, or amount side effects.
7. Open `Dashboard`, `Customer Credit`, and `Inventory` to show the Insight Coach, timeline charts, customer detail, follow-up message, inventory detail, reorder list, and automatic bookkeeping updates.
8. Open `Field Test` to show what a seller tried and what changed after feedback.
9. Open `Ledger`, load a transaction by id, update or delete it, then show refreshed balances.
10. Run Daily Closeout from `Reports & PDF`, then download CSV/PDF and generate the WhatsApp summary.
11. Click `Check Demo Health` from the launchpad, or open `Demo Health`, to show Modal health, deployed backend version, Nemotron status, database, PDF, and endpoint checks.

## Screenshot and GIF Moments

Capture these three moments for the Space README, demo video, or social post:

- `Record Text & Voice`: Guided Judge Mode, Today’s Work quick actions, review card, warning badges, price memory, and save receipt.
- `Dashboard`: Insight Coach, metrics, seller-day activity timeline, sales/expense timeline, top-selling item, low-stock table, and outstanding credit.
- `Field Test`: seller checklist, anonymized “who/tried/changed” notes, and saved evidence status.
- `Reports & PDF` plus `Ledger`: Daily Closeout, PDF/WhatsApp export, CSV download, and ledger correction.
- `Submission Story`: AI pipeline strip and “Why small models fit” card for the Modal/Nemotron story.

Supporting submission assets:

- `docs/demo-video-script.md`
- `docs/submission-checklist.md`
- `docs/social-post.md`
- `docs/field-notes.md`

## Repository Structure

```text
.
├── app.py
├── requirements.txt
├── README.md
├── voiceledger/
│   ├── speech/
│   ├── parser/
│   ├── ledger/
│   ├── reports/
│   ├── ui/
│   └── config.py
└── tests/
```

## Local Setup

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python app.py
```

By default, the SQLite database is created at `data/voiceledger.sqlite3`. Override it with:

```bash
export VOICELEDGER_DB_PATH=/path/to/voiceledger.sqlite3
```

## Run Tests

```bash
env PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python3 -m pytest
```

## Modal Backend Checks

After deploying `backend/modal_deploy.py`, verify the live backend:

```bash
curl https://sagarpat3199--voiceledger-api.modal.run/health
curl https://sagarpat3199--voiceledger-api.modal.run/version
curl -X POST https://sagarpat3199--voiceledger-api.modal.run/parse \
  -H "Content-Type: application/json" \
  -d '{"text":"Sold 12 mangoes, 20 each"}'
```

## Notes

- Speech transcription uses the faster-whisper `small` model and loads lazily on first use.
- LLM parsing is wired through the optional Modal backend using NVIDIA Nemotron, with rule parsing as fallback.
- The parser is intentionally transparent and easy to extend for hackathon iteration.
- Customer credit balances are updated when parsed customer credit or payment transactions are saved.
- Inventory stock is updated when parsed inventory purchases or sales are saved.
- PDF reports are generated with fpdf2 from the current SQLite ledger state.
- Parser architecture supports rule-based and Hugging Face Inference API compatible LLM parsers, with rule fallback on LLM failure.
- The dashboard shows daily sales, expenses, profit, outstanding credit, top sellers, and low-stock alerts from saved data.
- The Insight Coach turns those dashboard signals into next actions, such as credit follow-up, restocking, and daily closeout.
- Customer and inventory detail views show transaction history for one customer or item.
- Smart review warnings flag low confidence, missing fields, duplicate risk, and negative stock before save.
- Price memory fills missing sale prices from the latest matching saved sale and marks the review with a `Price memory used` badge.
- Inline review editing lets sellers correct the parsed transaction before the save touches the ledger.
- Seller setup persists business name, currency label, low-stock threshold, and language style in SQLite.
- Currency presets make the app easier to demo for INR, USD, EUR, GBP, MXN, BRL, and custom local labels.
- Field Test persists anonymized seller evidence and a workflow checklist in SQLite.
- Field Test evidence includes pain point, before/after story, useful moments, and changed-after-feedback notes.
- The Field Test mistake log records corrected fields before save so product feedback is visible.
- Local fallback rules include common English, Hinglish, Hindi-lite, Gujarati-lite, Spanish, French, and Portuguese seller notes.
- Parse status includes a lightweight language/confidence chip for multilingual seller notes.
- Customer follow-up and inventory reorder helpers generate WhatsApp-ready action messages.
- Debt reminder queue sorts customers with outstanding balances by highest amount due.
- Inventory reorder intelligence adds recent sold quantity, low-stock/selling-fast status, and suggested actions.
- WhatsApp summaries provide short copyable daily recaps in English, Spanish, French, or Portuguese.
- Voice command shortcuts provide quick access to daily closeout, customer detail, and inventory detail.
- Bulk import splits pasted notes by line, parses each line, supports review edits, and saves all reviewed transactions.
- Modal integration lives in `backend/`; if endpoint URLs are not configured, local fallback stays active.
- The Record screen includes a local-only AI mode that skips Modal while preserving the same transaction review and save flow.
- NVIDIA Nemotron 3 Nano 4B is used by the Modal parser endpoint and is also available as a local `transformers` parser provider for strict JSON transaction extraction.
- The Demo Health section checks Modal reachability, deployed backend version, NVIDIA Nemotron parser status, SQLite availability, PDF support, and configured endpoint status.
- The Submission Story section shows the AI pipeline and explains why a constrained transaction schema is a strong small-model fit.
- Ledger edits and deletes rebuild customer balances and inventory from saved transactions to avoid stale side effects.
- CSV export downloads all ledger rows in the same column order as the app table.
- The UI uses a custom theme, responsive spacing, and dashboard cards instead of the default Gradio look.