docs/field-notes.md

VoiceLedger Field Notes

Problem

VoiceLedger is built for an informal seller who records business activity in short spoken notes instead of spreadsheets. The recurring jobs are simple but easy to lose track of during a busy day: sales, expenses, customer dues, payments, and stock.

The anonymized target user is a local seller who needs to answer practical questions quickly:

• What did I sell today?
• Who still owes me money?
• How much stock do I have left?
• Did I make a profit today?
• Can I share a short summary without opening a spreadsheet?

Small-Model Fit

The app intentionally keeps the bookkeeping workflow narrow. Voice and messy text are converted into a small transaction schema, then deterministic ledger code handles balances, inventory, reports, and exports.

NVIDIA Nemotron is used through the Modal backend for transaction parsing when available. The local rule parser remains the fallback so the app stays reliable during a live demo or on a basic Hugging Face Space.

This is a good small-model problem because the output space is constrained: a transaction type, item, quantity, price, amount, customer, payment status, notes, and confidence. The model does not need to run a general accounting system; it only has to normalize everyday seller notes into structured records.

System Shape

• Gradio Space for the product UI.
• SQLite for local ledger persistence.
• faster-whisper for speech-to-text.
• Modal endpoint for speech and Nemotron parsing.
• Rule parser fallback for deterministic demo safety.
• Customer and inventory tables are derived from saved transactions and rebuilt after edits/deletes.

Demo Flow

1. Seed demo transactions from the first-screen Judge Demo Flow.
2. Record or type: Sold 12 mangoes, 20 each.
3. Show the parse source, review card, confidence, and warning badges.
4. Show price memory when a known item is missing price, then correct one inline review field before saving to show that sellers can fix model or rule-parser mistakes immediately.
5. Save the transaction and show the receipt with bookkeeping side effects.
6. Show Dashboard totals, the Insight Coach, sales/expense timeline, Ledger row, Customer Credit detail, and Inventory detail.
7. Open Field Test to show the seller checklist and anonymized feedback notes.
8. Edit or delete a transaction and show balances rebuilding.
9. Run Daily Closeout, then export CSV, PDF report, and WhatsApp daily summary.
10. Open Demo Health to show Modal, backend version, NVIDIA Nemotron parser status, SQLite, PDF, and endpoint checks.
11. Open Submission Story to show the visual AI pipeline and why the constrained transaction schema fits small models.

Submission Freeze

The hackathon version is intentionally frozen around the complete bookkeeping loop rather than adding more features:

• Voice and text capture.
• Modal/Nemotron parsing with local rule fallback.
• Seller setup for business name, currency, low-stock threshold, and language style.
• Currency presets and translated WhatsApp summaries for sellers who demo in INR, USD, EUR, GBP, MXN, BRL, English, Spanish, French, or Portuguese contexts.
• Hinglish/Hindi-lite/Gujarati-lite/Spanish/French/Portuguese fallback examples for common seller notes.
• Guided Judge Mode, first-run onboarding, multilingual examples, language/confidence chips, price memory, human-friendly review cards, inline review correction, mistake logging, warning badges, receipts, and save feedback.
• Command Center, dashboard timeline, seller-day timeline, debt reminder queue, customer follow-up, inventory reorder intelligence, ledger correction, Daily Closeout, PDF, CSV, and WhatsApp exports.
• Field Test Mode for the seller checklist and anonymized “who/tried/changed” feedback evidence.
• Richer Field Test Evidence for pain point, before/after workflow, useful moments, and changed-after-feedback notes.
• Demo Health for backend observability.
• Submission Story for the AI pipeline and small-model fit rationale.

This freeze keeps the demo reliable and makes the value proposition easier to judge.

What We Learned

The strongest product behavior is not the model call itself. It is the reliable loop around it: voice input, readable review, price memory, warning badges, save receipt, correction, reminders, restocking, and export. Informal sellers need speed, but they also need a way to spot mistakes and fix them. The correction log makes those mistakes measurable during field tests, while edit/delete, detail drilldowns, Daily Closeout, and CSV export make the app credible as a bookkeeping tool instead of a parser demo.

The small-model constraint helped keep the app honest. The model handles the fuzzy human input; the code owns the accounting state.

Screenshot Moments

• Record flow: Guided Judge Mode, first-run onboarding, multilingual examples, language/confidence chip, voice command shortcuts, price memory, review card, inline corrections, warning badges, source/status, save receipt.
• Dashboard: daily totals, Insight Coach, outstanding credit, sales/expense timeline, top seller, low-stock inventory.
• Field Test: workflow checklist, correction log, and anonymized feedback evidence.
• Reports and exports: Daily Closeout, PDF download, WhatsApp summary, CSV ledger export.