Deploy to HF Space

.env.example

@@ -0,0 +1,22 @@
+# Do not commit real values.
+# scripts/modal_deploy.sh writes real endpoint URLs to .env.
+
+# HF Hub
+HF_TOKEN=                          # write token for model push (modal run ...::push); not needed at inference if model is public
+HF_RECEIPT_MODEL_REPO=             # e.g. summerdevlin46/dukaan-saathi-receipt-lora
+
+# Hugging Face Space persistence
+# For the public Docker Space, set this to /data/dukaan.db only after enabling
+# persistent storage in Space settings. Without persistent storage, omit it and
+# the demo DB remains runtime-local.
+DB_PATH=
+RECEIPT_BACKEND=hf_inference
+
+# Modal endpoints (written automatically by scripts/modal_deploy.sh)
+MODAL_RECEIPT_ENDPOINT=
+MINICPM_RECEIPT_ENDPOINT=
+MODAL_RECEIPT_LLM_ENDPOINT=
+MODAL_RECEIPT_PARSER_ENDPOINT=
+MODAL_SPEECH_ENDPOINT=
+SPEECH_ASR_ENDPOINT=
+MODAL_NLU_ENDPOINT=

.gitignore

@@ -0,0 +1,240 @@
+# ignore screenshots for now
+*.jpeg
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+*.pyc
+.DS_Store
+
+# data stuff
+data/*.db
+data/*.sqlite
+data/*.sqlite3
+config/
+models/
+data/runs/
+data/finetune/generated/
+*-receipt-lora/
+*.gguf
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+benchmarks/results/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# modal stuff
+.modal.toml
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+samples/
+data/*.db-shm
+data/*.db-wal

.python-version

@@ -0,0 +1 @@
+3.13

AGENTS.md

@@ -0,0 +1,290 @@
+# Dukaan Saathi Agent Handoff
+
+This file is the starting context for future agents working in this repository.
+Use it to preserve the safety model, current architecture, and remaining task
+priorities.
+
+## Hard Rules
+
+- Use `uv` for all Python commands.
+- Run `uv run scripts/smoke_test.sh` before finishing code changes.
+- Do not commit secrets or local runtime files:
+  - `.env`
+  - Modal tokens
+  - Hugging Face tokens
+  - `data/*.db`
+  - `data/runs/`
+  - `models/`
+  - `__pycache__/`
+  - `.venv/`
+- Do not remove Modal scripts, benchmark scripts, `AGENTS.md`, or
+  `.env.example`.
+- Keep changes small and reviewable. Avoid broad rewrites unless the task
+  explicitly requires them.
+
+## Current App Shape
+
+Dukaan Saathi is a phone-friendly inventory copilot for a small Indian kirana
+store. It turns receipt photos, pasted receipt text, typed commands, and speech
+transcripts into reviewable inventory drafts.
+
+The core workflow is:
+
+```text
+receipt photo / text command
+-> AI draft or deterministic parser draft
+-> editable rows or pending action
+-> owner correction
+-> owner approval
+-> inventory update
+-> reorder suggestion
+```
+
+Important files:
+
+- `app.py` is the FastAPI/static app entry point.
+- `dukaan_saathi/ui/gradio_app.py` contains the Gradio UI path.
+- `dukaan_saathi/agent/react_agent.py` is the active lean ReAct router.
+- `dukaan_saathi/agent/tools.py` wraps parser, integration, and service tools.
+- `dukaan_saathi/agent/agent.py` contains the heavier smolagents
+  `ToolCallingAgent`; it is not the primary UI path.
+- `dukaan_saathi/services/inventory.py` is the required inventory write
+  boundary.
+- `dukaan_saathi/storage.py` owns SQLite access and demo seed data.
+- `dukaan_saathi/parsers/` contains deterministic fallback parsers.
+- `dukaan_saathi/integrations/` contains thin HTTP/model integration clients.
+- `modal_apps/` contains Modal-hosted model services and training jobs.
+- `kirana_db.py` is the custom FastAPI UI adapter over the Dukaan storage
+  layer. It must preserve the same owner-approval safety rules while this path
+  is migrated toward the canonical inventory service boundary.
+
+## Safety Architecture
+
+- Inventory writes must go through `dukaan_saathi/services/inventory.py`.
+  The current custom FastAPI path still writes through `kirana_db.py`, which
+  delegates to the Dukaan storage ledger; do not add new direct stock writes
+  elsewhere.
+- Model output must never update inventory directly.
+- Receipt extraction must populate an editable table first.
+- Stock command parsing must produce a pending owner action first.
+- Owner approval is required before stock changes.
+- Receipt row approval and command approval are the only places that should
+  write inventory.
+- Modal model services live in `modal_apps/`.
+- App-side Modal integration must stay as a thin HTTP client in
+  `dukaan_saathi/integrations/`.
+- Do not add heavy model inference directly to the Gradio or FastAPI runtime.
+- ReAct traces should explain `Thought`, `Action`, and `Observation` steps, but
+  traces are audit/UI context only; they are not permission to write stock.
+- ReAct is the orchestrator, not the model. It calls tools; model-backed tools
+  may call Modal, Hugging Face Inference, or local llama.cpp. The public Space
+  should rely on HF Inference plus optional Modal endpoints, not local model
+  servers.
+
+When reviewing changes, flag any code path that bypasses owner approval before
+stock changes.
+
+## Runtime And Environment
+
+The public Hugging Face Space is:
+
+```text
+https://huggingface.co/spaces/Zappandy/Kirana_AI
+```
+
+The root `Dockerfile` deploys the Space frontend/backend by running
+`uvicorn app:server`. Do not add a local model-server requirement to that path.
+
+Use these local run paths:
+
+```bash
+scripts/run_app.sh --hf-inference
+scripts/run_app.sh --deterministic
+scripts/run_app.sh --modal-llm
+scripts/dev.sh --hf-inference
+scripts/dev.sh --deterministic
+scripts/dev.sh --modal-llm
+```
+
+Supported receipt backends:
+
+- `hf_inference` is the preferred public Hugging Face Space path.
+- `modal_llm` calls the Modal-hosted receipt parser endpoint.
+- `llamacpp` uses local llama.cpp servers only; do not require it for HF Spaces.
+- `deterministic` uses rule-based parsers for smoke tests and offline
+  debugging.
+
+Important environment variables:
+
+```text
+RECEIPT_BACKEND
+HF_RECEIPT_MODEL_REPO
+HF_TOKEN
+MODAL_RECEIPT_ENDPOINT
+MODAL_RECEIPT_LLM_ENDPOINT
+MODAL_SPEECH_ENDPOINT
+SPEECH_ASR_ENDPOINT
+MODAL_NLU_ENDPOINT        # Qwen2.5-1.5B command slot extractor; optional, falls back to deterministic
+DB_PATH
+TRACE_DIR
+```
+
+Never write real secret values into tracked files. Keep `.env.example` as the
+only tracked env template.
+
+SQLite defaults to `data/dukaan.db`. Local tests and demos may mutate this file.
+Hosted HF Spaces state is not durable unless persistent storage is configured
+and `DB_PATH` points at that persistent location.
+
+For the public Space, use `DB_PATH=/data/dukaan.db` only when HF persistent
+storage is enabled. Otherwise leave `DB_PATH` unset and treat the DB as
+runtime-local demo state.
+
+Runtime manifests, when enabled, belong under `data/runs/` and are local
+evidence only. They must not contain tokens.
+
+## Model And Data Pipeline
+
+Receipt image flow:
+
+```text
+uploaded image
+-> ReAct router
+-> Modal MiniCPM-V OCR tool
+-> raw receipt text
+-> configured receipt parser tool/backend
+-> editable receipt table
+-> owner correction/approval
+-> inventory service
+-> SQLite stock ledger
+```
+
+Receipt text backends:
+
+- HF Inference calls the fine-tuned model in `HF_RECEIPT_MODEL_REPO`.
+- Modal LLM calls `MODAL_RECEIPT_LLM_ENDPOINT`.
+- llama.cpp uses local model servers.
+- deterministic parser uses `dukaan_saathi/parsers/receipt_text.py`.
+
+Speech flow:
+
+```text
+audio
+-> Modal speech endpoint
+-> transcript
+-> ReAct stock command tool
+-> pending owner action
+-> owner approval
+-> inventory service
+```
+
+Fine-tuning and model hosting stay in Modal:
+
+- `modal_apps/receipt_data_generator.py` generates synthetic receipt examples.
+- `modal_apps/receipt_llm_service.py` trains, serves, and pushes the receipt
+  parser model.
+- `modal_apps/receipt_vlm_service.py` serves receipt image OCR.
+- `modal_apps/speech_asr_service.py` serves speech transcription.
+
+Use `uv run modal ...` for Modal commands.
+
+## Remaining Task Backlog
+
+Prioritize safety and demo-critical correctness before polish.
+
+### Completed
+
+- Voice stock commands parse to a pending action and require explicit owner
+  approval before stock writes.
+- The custom FastAPI photo and voice paths use the lean ReAct router first, with
+  deterministic/configured fallback paths.
+- Dashboard "Add to order" and "Offer to route" create pending order rows.
+- Receipt rows are post-matched against inventory before display.
+- Stock ledger deltas migrate to `REAL` for fractional quantities.
+- Dashboard insights use deterministic inventory/expiry state.
+- Orders support "Mark received" after approval.
+- Analytics has a `7d` / `30d` / `90d` sales window.
+- Modal photo/speech flows expose cold-start loading hints and `/api/warm`.
+- ReAct agent trace surfaced in the UI as a collapsible "Agent reasoning" panel
+  on both the photo and voice result cards.
+- Unknown-product commands extract a suggested name and quantity and offer an
+  inline "Add new product" form instead of showing a blank result.
+- NLU slot extraction service (`modal_apps/command_nlu_service.py`) using
+  `Qwen/Qwen2.5-1.5B-Instruct`. Deployed; `MODAL_NLU_ENDPOINT` wired into
+  `.env` and HF Space secrets. `run_command_parse` tries NLU first, falls back
+  to ReAct/deterministic on failure or unknown intent.
+- Mocked NLU tests cover the happy path, unknown-product path, and
+  missing-endpoint fallback (`smoke_tests/test_custom_app_safety.py`).
+- `/api/warm` pings the NLU health endpoint (`nlu-health`) alongside the
+  receipt and speech endpoints.
+
+### Remaining
+
+- Add and maintain tests for every approval gate and order/receipt transition.
+- Migrate the custom FastAPI inventory writes from `kirana_db.py` toward
+  `dukaan_saathi/services/inventory.py`, or document the adapter boundary
+  explicitly until migration is done.
+- Keep fractional quantity behavior covered in tests when changing receipt,
+  stock, reorder, or sales flows.
+
+## UI And Demo Constraints
+
+- Keep the app phone-friendly.
+- Avoid raw JSON or developer-looking output in user-facing UI unless it is
+  explicitly a trace/debug panel.
+- Examples should map to seeded catalog items such as `Bun`, `OBM`,
+  `Happy Happy`, `Bingo (C)`, and `Parle (bulk)`.
+- Do not reintroduce confusing/non-rendering Telugu examples.
+- Do not use low-contrast dark text on green backgrounds.
+- Keep the approval step visible. Do not bypass it to make the demo look more
+  automatic.
+
+## Review Guidelines
+
+Flag these issues during review:
+
+- Any inventory write that does not go through owner approval.
+- Any direct database stock write outside `dukaan_saathi/services/inventory.py`.
+- Receipt model output updating inventory directly.
+- Voice command output updating inventory before confirmation.
+- Secrets, tokens, local DB files, runtime manifests, or generated model files
+  being committed.
+- Model inference added directly to Gradio/FastAPI runtime instead of an
+  integration client or Modal service.
+- App-side Modal code becoming more than a thin HTTP client.
+- Changes that delete Modal scripts, benchmark scripts, `AGENTS.md`, or
+  `.env.example`.
+- Broad rewrites where a small targeted change would satisfy the task.
+
+## Commands And Checks
+
+Install or sync dependencies:
+
+```bash
+uv sync
+```
+
+Run the required smoke test:
+
+```bash
+uv run scripts/smoke_test.sh
+```
+
+Useful focused checks:
+
+```bash
+uv run python -m unittest smoke_tests.test_agent_ui_integration
+uv run python -m pytest smoke_tests/test_receipt_parser_regression.py -q
+uv run python -m pytest smoke_tests/test_receipt_correction.py -q
+```
+
+Before finishing, inspect the diff:
+
+```bash
+git status --short
+git diff --stat
+git diff -- AGENTS.md
+```
+
+If there are unrelated user changes in the working tree, do not revert them.
+Work around them or ask only when they block the task.

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PORT=7860
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+RUN mkdir -p data/runs /data
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app:server", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,653 @@
+---
+title: Dukaan Saathi
+emoji: 🛒
+colorFrom: indigo
+colorTo: green
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+tags:
+- inventory
+- kirana
+- telugu
+- fastapi
+- minicpm-v
+- modal
+- speech-to-text
+- sqlite
+- human-in-the-loop
+- small-business
+- receipt-parsing
+- react-agent
+- approval-gated
+- llm-finetuning
+---
+
+# Dukaan Saathi · Small-Model Inventory Copilot for Kirana Stores
+
+Dukaan Saathi is a phone-friendly inventory copilot for a small Indian convenience store.
+
+The store owner uses Telugu/code-mixed commands during the day, sells products with English names, and receives messy supplier receipts on paper. The app helps turn those messy inputs into safe, reviewable inventory updates.
+
+The goal is **not perfect OCR**. Supplier receipts can be noisy, handwritten, folded, and inconsistent. Dukaan Saathi uses a small vision model to create a draft, then lets the owner quickly correct it before anything touches inventory.
+
+## Core workflow
+
+```text
+receipt photo / text command
+→ AI draft
+→ owner correction
+→ owner approval
+→ inventory update
+→ reorder suggestion
+```
+
+Inventory is never updated directly from model output. Every write is approval-gated.
+
+## Using this Space
+
+The app opens on the **Dashboard** tab. Navigate using the top menu:
+
+- **Dashboard** — current stock levels, expiry status, and AI-generated insights
+- **Inventory** — full product list; add or edit items
+- **Bill Desk** — upload a supplier receipt photo or paste receipt text, correct extracted rows, then approve to update stock
+- **Voice** — record or upload a stock command, transcribe it, then approve the proposed change
+- **Orders** — pending reorder suggestions; mark as received after stock arrives
+- **Analytics** — sales window (7 d / 30 d / 90 d)
+
+**Note on state:** This Space uses SQLite with in-container storage. Inventory changes are visible during your session but may reset when the Space rebuilds. The seeded catalog (Bun, OBM, Happy Happy, Bingo (C), Parle (bulk)) is always restored on restart.
+
+**Note on Modal services:** Receipt image OCR and speech transcription use Modal-hosted endpoints that may have a cold start of 10–30 seconds on first use. A warm-up call runs automatically on page load.
+
+## What it does
+
+### Stock commands
+
+Example:
+
+```text
+add Bun 12
+```
+
+The app detects that 12 buns arrived and proposes an inventory update. The owner must approve before the stock value changes.
+
+### Receipt photo extraction
+
+The owner uploads a supplier receipt photo. MiniCPM-V extracts likely product rows, quantities, and amounts into a review table.
+
+The extraction can be imperfect. That is expected.
+
+Example noisy draft:
+
+```text
+1. Port Ranges (c), qty 1, amount 2450
+2. Chocoly, qty 1, amount 8702
+```
+
+### Phone-friendly correction commands
+
+Instead of forcing spreadsheet-style editing on a phone, the owner can type a simple correction:
+
+```text
+first one Parle bulk, second one Bingo
+```
+
+The owner can also record or upload correction audio. The app sends the audio to the Modal speech ASR endpoint, fills the correction command textbox with the transcript, and still waits for the owner to apply the correction and approve rows.
+
+The app remaps the rows to known inventory products:
+
+```text
+row 1 → Parle (bulk)
+row 2 → Bingo (C)
+```
+
+Matched rows become candidates for approval.
+
+Supported correction examples:
+
+```text
+first one Parle bulk
+second one Bingo
+row 1 Parle bulk
+row 2 Bingo
+skip row 2
+quantity row 1 is 4
+```
+
+### Approval-gated inventory updates
+
+The owner must explicitly approve stock commands and receipt rows before SQLite inventory is updated.
+
+### Reorder suggestions
+
+When stock falls below threshold, the app drafts reorder suggestions grouped by supplier. Nothing is sent or purchased automatically.
+
+## Quick demo (text-only, no Modal needed)
+
+Paste this into the **Bill Desk** receipt text box:
+
+```text
+Mahalakshmi Marketing
+
+| S.No | Particulars | Qty | Rate | Amount |
+| 5/   | Port        | 1   | X2450 | 2450  |
+| 10/  | Rs.g/c      | 4   | X8702 | 3480  |
+```
+
+Click **Parse receipt text**, then type this correction:
+
+```text
+first one Parle bulk, second one Bingo
+```
+
+Click **Apply correction** → rows map to known products → click **Approve receipt rows** → inventory updates.
+
+See the full [demo flow](#demo-flow) section below for the complete step-by-step walkthrough including voice and photo paths.
+
+## Why small models fit this problem
+
+Small models are good enough to turn messy receipts and natural commands into useful drafts, but they should not be trusted to update business records directly.
+
+Dukaan Saathi uses the model for interpretation and deterministic Python for safety-critical inventory logic:
+
+```text
+MiniCPM-V output
+→ parsed candidate rows
+→ product matching
+→ owner correction
+→ owner approval
+→ SQLite write
+```
+
+This keeps the workflow useful even when the model makes mistakes.
+
+## Model lifecycle
+
+The receipt model is trained on Modal, then pushed to Hugging Face Hub for the
+public Space runtime.
+
+```text
+Modal synthetic data generation
+→ Modal LoRA fine-tuning
+→ LoRA adapter stored in a Modal Volume
+→ Modal push job merges adapter into the base model
+→ merged model pushed to Hugging Face Hub
+→ HF Space uses hf_inference to call that Hub model
+→ parsed receipt rows populate an editable table
+→ owner approval updates inventory
+```
+
+Modal is the training and optional serving environment. Hugging Face Hub is the
+public model artifact store. Hugging Face Inference is the public Space inference
+path.
+
+### Fine-tuned receipt model
+
+A LoRA adapter trained on Llama-3.2-3B-Instruct, stored in a Modal Volume:
+
+```text
+Modal app:    dukaan-saathi-receipt-llm
+Modal Volume: dukaan-saathi-receipt-lora
+Adapter path: /adapters/receipt-lora
+Base model:   unsloth/Llama-3.2-3B-Instruct-bnb-4bit
+```
+
+After training, push the merged model to Hugging Face Hub:
+
+```bash
+uv run modal run modal_apps/receipt_llm_service.py::push
+```
+
+That push reads these values from `.env`:
+
+```text
+HF_TOKEN=...
+HF_RECEIPT_MODEL_REPO=summerdevlin46/dukaan-saathi-receipt-lora
+```
+
+The public HF Space uses the pushed model through:
+
+```text
+RECEIPT_BACKEND=hf_inference
+HF_RECEIPT_MODEL_REPO=summerdevlin46/dukaan-saathi-receipt-lora
+```
+
+The same adapter can also be served directly through a Modal receipt parser
+endpoint for local or fallback runs. Deploying that endpoint writes this to
+`.env`:
+
+```text
+MODAL_RECEIPT_LLM_ENDPOINT=https://summerdevlin46--dukaan-saathi-receipt-llm-api.modal.run/parse
+```
+
+This is not a local GGUF file. Local llama.cpp use is a separate optional path.
+
+### Training data
+
+| File | Examples | Source |
+|------|----------|--------|
+| `data/finetune/receipt_examples.jsonl` | 6 | Hand-authored |
+| `data/finetune/generated/receipt_examples_modal_synthetic.jsonl` | 22 | Modal LLM-generated |
+
+To regenerate synthetic examples:
+
+```bash
+scripts/modal_generate_receipt_examples.sh \
+  --count 48 \
+  --output data/finetune/generated/receipt_examples_modal_synthetic.jsonl
+```
+
+To retrain the LoRA adapter on Modal:
+
+```bash
+scripts/modal_finetune_receipt.sh --modal-synthetic-count 48 --max-steps 60 --epochs 8
+```
+
+To redeploy the inference endpoint after retraining:
+
+```bash
+scripts/modal_deploy.sh modal_apps/receipt_llm_service.py
+```
+
+To update the public HF Space model after retraining, push again:
+
+```bash
+uv run modal run modal_apps/receipt_llm_service.py::push
+```
+
+## Current stack
+
+* **Gradio / Hugging Face Space** for the demo UI
+* **Lean ReAct tool router** for selecting the small set of inventory/receipt tools
+* **HF Inference API** for the public Hugging Face Space receipt parser path, using the model fine-tuned on Modal and pushed to HF Hub
+* **llama.cpp + smolagents tools** for the local model-backed receipt parser path
+* **MiniCPM-V 4.6** for receipt image extraction
+* **Distil-Whisper small English** for correction-command speech transcription
+* **Qwen2.5-1.5B-Instruct** for voice command NLU — semantic slot extraction (intent, product name, quantity, unit) from free-form and Telugu/English mixed commands
+* **Modal** for hosting model endpoints
+* **SQLite** for local inventory state
+* **uv** for Python environment and commands
+* **Deterministic Python services and fallback parsers** for:
+
+  * stock command parsing
+  * receipt text parsing
+  * receipt correction commands
+  * product matching
+  * inventory updates
+  * reorder drafts
+
+Modal integrations are optional remote model services. The app-side Modal code
+stays as thin HTTP clients; model serving code lives in `modal_apps/`.
+
+For the public Hugging Face Space, use `RECEIPT_BACKEND=hf_inference` with
+`HF_RECEIPT_MODEL_REPO` pointing at the published fine-tuned model. The
+deterministic parser path exists for smoke tests, offline debugging, and safety
+fallbacks; it is not the primary demo experience.
+
+Modal can also host the receipt parser model. This is useful when local or
+Hugging Face environments hit GPU/storage/runtime limits. With the current tiny
+fine-tuning set, treat Modal fine-tuning as a demo-oriented adapter that improves
+format following on known receipt styles, not as a generally reliable parser.
+
+## Runtime pipeline
+
+The local orchestrator is:
+
+```bash
+scripts/dev.sh
+```
+
+It selects one of four staged runtime paths:
+
+```text
+scripts/dev.sh --hf-inference
+→ scripts/run_app.sh --backend hf_inference
+  → uv run python app.py
+  → receipt text parsing calls the HF Inference API model in HF_RECEIPT_MODEL_REPO
+```
+
+```text
+scripts/dev.sh --llamacpp
+→ scripts/start_llamacpp.sh
+  → uv run python scripts/download_models.py
+  → uv run python -m llama_cpp.server on port 8080
+  → uv run python -m llama_cpp.server on port 8082
+→ scripts/run_app.sh --backend llamacpp
+  → uv run python app.py
+```
+
+```text
+scripts/dev.sh --modal-llm
+→ scripts/run_app.sh --backend modal_llm
+  ��� uv run python app.py
+  → receipt text parsing calls MODAL_RECEIPT_LLM_ENDPOINT
+```
+
+```text
+scripts/dev.sh --deterministic
+→ scripts/run_app.sh --backend deterministic
+  → uv run python app.py
+  → receipt text parsing uses dukaan_saathi/parsers/receipt_text.py
+```
+
+Receipt image and speech are separate optional Modal services:
+
+```text
+receipt image
+→ ReAct router
+→ extract_text_from_receipt_image tool
+→ dukaan_saathi/integrations/modal_receipt.py
+→ MODAL_RECEIPT_ENDPOINT
+→ modal_apps/receipt_vlm_service.py
+→ raw receipt text
+→ parse_receipt_text_tool
+→ configured receipt parser backend
+→ editable receipt table
+→ owner approval
+→ dukaan_saathi/services/inventory.py
+```
+
+```text
+voice or correction audio
+→ dukaan_saathi/integrations/speech.py
+→ MODAL_SPEECH_ENDPOINT
+→ transcript
+→ ReAct router for stock commands, or correction parser for receipt rows
+→ pending action / corrected editable rows
+→ owner approval
+```
+
+Inventory writes only happen after approval:
+
+```text
+approve command / approve receipt rows
+→ dukaan_saathi/services/inventory.py
+→ dukaan_saathi/storage.py
+→ SQLite stock ledger
+```
+
+## Agent status
+
+The active Gradio path uses a lean ReAct-style router in
+`dukaan_saathi/agent/react_agent.py`. It records `Thought`, `Action`, and
+`Observation` trace lines, chooses the correct existing tool for the small task
+set, and never writes inventory directly.
+
+ReAct is the orchestrator, not the model. It calls tools; some tools call remote
+models. For example, receipt-photo ReAct chooses the OCR tool, that tool calls
+the Modal MiniCPM-V endpoint, then ReAct chooses the receipt parser tool, which
+uses the configured backend:
+
+```text
+Receipt photo
+→ ReAct
+→ Modal OCR tool
+→ receipt parser tool
+   → HF Inference / Modal LLM / llama.cpp / deterministic parser
+→ editable rows
+→ owner approval
+→ inventory write
+```
+
+Voice follows the same approval-gated shape:
+
+```text
+Audio
+→ Modal ASR
+→ transcript
+→ ReAct stock-command tool
+→ pending stock action
+→ owner approval
+→ inventory write
+```
+
+This separation is intentional: Modal/HF/llama.cpp do expensive inference,
+ReAct sequences safe tools and exposes a trace, and deterministic inventory
+code performs approved writes.
+
+The heavier `smolagents.ToolCallingAgent` implementation remains in
+`dukaan_saathi/agent/agent.py`, but it is no longer the primary Gradio path. The
+ReAct router calls the existing tool layer directly, which keeps the app simpler
+while preserving the same approval gates.
+
+## Main files
+
+```text
+app.py                                      — FastAPI/Server entry point; routes dispatches and approval handlers
+frontend_backend.py                         — adapter between custom HTML frontend and dukaan_saathi backend
+dukaan_saathi/agent/react_agent.py          — lean ReAct tool router; records Thought/Action/Observation traces
+dukaan_saathi/agent/tools.py                — parser, integration, and service tools called by the ReAct router
+dukaan_saathi/parsers/stock_command.py      — deterministic stock command parser (keyword + fuzzy catalog match)
+dukaan_saathi/parsers/receipt_text.py       — deterministic receipt text parser
+dukaan_saathi/parsers/receipt_correction.py — row correction command parser
+dukaan_saathi/services/inventory.py         — canonical inventory write boundary (all stock writes go here)
+dukaan_saathi/services/reorder.py           — reorder suggestion generator
+dukaan_saathi/storage.py                    — SQLite access, seed data, find_product
+dukaan_saathi/integrations/command_nlu.py   — Qwen2.5-1.5B NLU HTTP client (MODAL_NLU_ENDPOINT)
+dukaan_saathi/integrations/modal_receipt.py — MiniCPM-V OCR HTTP client (MODAL_RECEIPT_ENDPOINT)
+dukaan_saathi/integrations/speech.py        — Distil-Whisper ASR HTTP client (MODAL_SPEECH_ENDPOINT)
+modal_apps/command_nlu_service.py           — Qwen2.5-1.5B slot extraction endpoint
+modal_apps/receipt_vlm_service.py           — MiniCPM-V receipt OCR endpoint
+modal_apps/speech_asr_service.py            — Distil-Whisper ASR endpoint
+modal_apps/receipt_llm_service.py           — receipt LLM train/serve/push
+modal_apps/receipt_data_generator.py        — synthetic receipt example generator
+scripts/dev.sh                              — local run entrypoint
+scripts/modal_deploy.sh                     — deploy a Modal service and write its URL to .env
+smoke_tests/test_custom_app_safety.py       — approval gate, NLU, and Modal integration tests
+smoke_tests/test_receipt_parser_regression.py
+smoke_tests/test_receipt_correction.py
+```
+
+## Run locally
+
+### Prerequisites
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/getting-started/installation/) (`pip install uv` or `curl -LsSf https://astral.sh/uv/install.sh | sh`)
+
+### 1 — Install dependencies
+
+```bash
+uv sync
+```
+
+### 2 — Configure environment
+
+```bash
+cp .env.example .env
+```
+
+Then edit `.env`. The minimum required value depends on which backend you run:
+
+| Backend | Required in `.env` |
+|---------|-------------------|
+| `hf_inference` (recommended) | `HF_RECEIPT_MODEL_REPO=summerdevlin46/dukaan-saathi-receipt-lora` |
+| `modal_llm` | `MODAL_RECEIPT_LLM_ENDPOINT=<url from modal_deploy.sh>` |
+| `deterministic` | nothing — no model calls |
+| `llamacpp` | nothing extra — models downloaded automatically |
+
+Optional Modal services (add when you have them; app runs without them):
+
+```text
+MODAL_RECEIPT_ENDPOINT=...   # receipt image OCR (MiniCPM-V)
+MODAL_SPEECH_ENDPOINT=...    # speech transcription (Distil-Whisper)
+MODAL_NLU_ENDPOINT=...       # voice command slot extraction (Qwen2.5-1.5B)
+```
+
+`HF_TOKEN` is only needed if `HF_RECEIPT_MODEL_REPO` is a private repo.
+
+**Running on the public HF Space?** Modal endpoints must be added as Space secrets in the HF UI — see [docs/deployment_setup.md](docs/deployment_setup.md) for the full walkthrough.
+
+### 3 — Run
+
+Pick one backend and start the app. It opens at **http://127.0.0.1:7860**.
+
+**HF Inference (recommended for full demo)**
+
+Calls the fine-tuned receipt model hosted on Hugging Face Hub. Requires
+`HF_RECEIPT_MODEL_REPO` in `.env`.
+
+```bash
+scripts/dev.sh --hf-inference
+```
+
+**Deterministic (fastest, no model needed)**
+
+Uses rule-based parsers only. Stock commands, receipt text, corrections, and
+approval all work. Use this to verify UI and approval flows without any model
+calls.
+
+```bash
+scripts/dev.sh --deterministic
+```
+
+**Modal LLM (fine-tuned model served on Modal)**
+
+Calls the LoRA-fine-tuned endpoint you deployed on Modal. Requires
+`MODAL_RECEIPT_LLM_ENDPOINT` in `.env`.
+
+```bash
+scripts/dev.sh --modal-llm
+```
+
+**Local llama.cpp (fully offline fallback)**
+
+Downloads GGUF models and starts two llama.cpp servers on ports 8080 and 8082,
+then starts the app. Slow first start; receipt quality depends on whether a
+fine-tuned GGUF is available via `HF_RECEIPT_GGUF_REPO`.
+
+```bash
+scripts/dev.sh --llamacpp
+```
+
+### 4 — Run tests
+
+```bash
+uv run scripts/smoke_test.sh
+```
+
+Focused test runs:
+
+```bash
+uv run python -m pytest smoke_tests/test_custom_app_safety.py -v
+uv run python -m pytest smoke_tests/test_receipt_parser_regression.py smoke_tests/test_receipt_correction.py -q
+```
+
+## Modal endpoints
+
+Deploy the MiniCPM-V receipt endpoint:
+
+```bash
+scripts/modal_deploy.sh modal_apps/receipt_vlm_service.py
+```
+
+Deploy the speech ASR endpoint:
+
+```bash
+scripts/modal_deploy.sh modal_apps/speech_asr_service.py
+```
+
+Deploy the voice command NLU endpoint:
+
+```bash
+scripts/modal_deploy.sh modal_apps/command_nlu_service.py
+```
+
+All three commands deploy the Modal app and write the generated endpoint URL to `.env`.
+`MODAL_RECEIPT_ENDPOINT`, `MODAL_SPEECH_ENDPOINT`, and `MODAL_NLU_ENDPOINT` are written automatically.
+
+Load the endpoint environment:
+
+```bash
+source scripts/_env.sh
+```
+
+Health check:
+
+```bash
+BASE_URL="${MODAL_RECEIPT_ENDPOINT%/extract}"
+curl "$BASE_URL/health"
+```
+
+Speech health check:
+
+```bash
+SPEECH_HEALTH_URL="${MODAL_SPEECH_ENDPOINT/speech-transcribe/speech-health}"
+curl "$SPEECH_HEALTH_URL"
+```
+
+Test receipt extraction directly (replace with your own receipt image):
+
+```bash
+curl -sS -X POST "$MODAL_RECEIPT_ENDPOINT" \
+  -F "image=@/path/to/receipt.jpeg"
+```
+
+Test speech transcription directly:
+
+```bash
+curl -sS -X POST "$MODAL_SPEECH_ENDPOINT" \
+  -F "audio=@path/to/audio.wav"
+```
+
+NLU health check:
+
+```bash
+curl "${MODAL_NLU_ENDPOINT}" \
+  -X POST -H "Content-Type: application/json" \
+  -d '{"command": "add Bun 12"}'
+```
+
+Stop Modal to save cost:
+
+```bash
+uv run modal app stop dukaan-saathi-receipt-vlm || true
+uv run modal app stop dukaan-saathi-speech-asr || true
+uv run modal app stop dukaan-saathi-command-nlu || true
+uv run modal app list
+```
+
+Look for:
+
+```text
+Tasks 0
+```
+
+## Demo flow
+
+Full walkthrough covering stock commands, receipt photo, and voice correction:
+
+```text
+1. Open Dukaan Saathi.
+2. Show current inventory.
+3. Enter: add Bun 12
+4. Click Parse command.
+5. Approve the proposed stock update.
+6. Show the updated inventory and reorder draft.
+7. Upload a supplier receipt photo.
+8. MiniCPM-V extracts imperfect rows.
+9. Type or record this correction: first one Parle bulk, second one Bingo
+10. If using audio, click Transcribe correction audio.
+11. Click Apply correction.
+12. Show rows mapped to known inventory products.
+13. Click Approve receipt rows.
+14. Show inventory updated.
+15. Show reorder draft updated.
+```
+
+## Safety rule
+
+Model output never writes inventory directly.
+
+The app always follows this flow:
+
+```text
+model output
+→ parsed draft
+→ owner review/correction
+→ owner approval
+→ inventory write
+```
+
+This is the core design principle of Dukaan Saathi.

app.py

@@ -0,0 +1,706 @@
+"""
+Kirana AI × Dukaan Saathi — gr.Server with hand-rolled HTML frontend.
+
+UI shell ported from kirana-ai; storage and parsers come from dukaan_saathi.
+"""
+
+import json
+import shutil
+import tempfile
+import threading
+from pathlib import Path
+
+from gradio import Server
+from fastapi import File, Form, UploadFile
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+
+import kirana_db as db
+import ui as ui_render
+from frontend_backend import run_analysis, run_command_parse
+from dukaan_saathi import config
+from dukaan_saathi.agent.react_agent import get_react_agent
+from dukaan_saathi.integrations.modal_receipt import _extract_receipt_result_with_modal
+from dukaan_saathi.integrations.speech import transcribe_audio
+from dukaan_saathi.parsers.receipt_text import parse_receipt_text
+from dukaan_saathi.traceability import new_run_id, utc_now_iso, write_manifest
+from dukaan_saathi.integrations.hub_traces import push_trace
+
+db.init_db()
+
+STATIC_DIR = Path(__file__).parent / "static"
+
+
+INITIAL_STATE = {
+    "page":           "dashboard",
+    "filters":        {"q": "", "category": "All", "status": "All"},
+    "analytics_days": 30,
+    "orders_filter":  "pending",
+    "active_method":  "manual",
+    "photo_result":   None,
+    "voice_result":   None,
+    "insights":       {"inventory": "", "seasonal": "", "expiry": ""},
+}
+
+
+def _new_state() -> dict:
+    return json.loads(json.dumps(INITIAL_STATE))
+
+
+def _parse_receipt_with_configured_backend(raw_text: str):
+    """Use the production receipt parser backend for OCR/plain text."""
+    if config.RECEIPT_BACKEND == "hf_inference":
+        from dukaan_saathi.integrations.hf_inference_receipt import parse_receipt_via_hf_inference
+        return parse_receipt_via_hf_inference(raw_text)
+
+    if config.RECEIPT_BACKEND == "modal_llm":
+        from dukaan_saathi.integrations.modal_receipt_llm import parse_receipt_with_modal_llm
+        return parse_receipt_with_modal_llm(raw_text)
+
+    if config.RECEIPT_BACKEND == "llamacpp":
+        from dukaan_saathi.integrations.llamacpp_receipt import parse_receipt_via_llm
+        return parse_receipt_via_llm(raw_text)
+
+    return parse_receipt_text(raw_text)
+
+
+def _match_receipt_rows(rows: list[dict], trace: list[str] | None = None) -> list[dict]:
+    matched_rows = []
+    trace = trace if trace is not None else []
+    for row in rows or []:
+        next_row = dict(row)
+        if next_row.get("matched_product_id"):
+            matched_rows.append(next_row)
+            continue
+
+        product_raw = (next_row.get("product_raw") or "").strip()
+        if not product_raw:
+            matched_rows.append(next_row)
+            continue
+
+        matches = db.find_by_name(product_raw)
+        if matches:
+            match = matches[0]
+            next_row["matched_product_id"] = match["id"]
+            next_row["matched_product_name"] = match["name"]
+            trace.append(f"[receipt_match] Matched '{product_raw}' to {match['name']}")
+        else:
+            trace.append(f"[receipt_match] No catalog match for '{product_raw}'")
+        matched_rows.append(next_row)
+    return matched_rows
+
+
+def _find_order(order_id: str) -> dict | None:
+    for order in db.get_all_orders(limit=500):
+        if str(order.get("id")) == str(order_id):
+            return order
+    return None
+
+
+def _extract_receipt_direct(tmp_path: str) -> tuple[list[dict], list[str], str, str]:
+    ocr_result = _extract_receipt_result_with_modal(tmp_path)
+    trace = list(getattr(ocr_result, "trace", []) or [])
+    raw_text = getattr(ocr_result, "raw_text", "") or ""
+    model = getattr(ocr_result, "model", "unknown")
+    if not trace:
+        trace = [
+            f"[receipt_ocr] OCR model: {model}",
+            f"[receipt_ocr] Raw text length: {len(raw_text)}",
+        ]
+
+    if not raw_text.strip():
+        return [], trace, raw_text, model
+
+    rows, parse_trace, raw_text, _ = _parse_receipt_rows_from_text(raw_text)
+    trace.extend(parse_trace)
+    return rows, trace, raw_text, model
+
+
+def _parse_receipt_rows_from_text(
+    raw_text: str,
+    backend_parser=_parse_receipt_with_configured_backend,
+) -> tuple[list[dict], list[str], str, str]:
+    trace: list[str] = []
+    try:
+        rows, parser_trace = backend_parser(raw_text)
+        trace.extend(parser_trace)
+    except Exception as exc:
+        trace.append(f"[receipt_parser] Configured backend failed: {exc}")
+        trace.append("[receipt_parser] Falling back to deterministic parser.")
+        rows, parser_trace = parse_receipt_text(raw_text)
+        trace.extend(parser_trace)
+    rows = _match_receipt_rows(rows, trace)
+    return rows, trace, raw_text, "text"
+
+
+def _service_status() -> dict:
+    import os
+
+    return {
+        "receipt_backend": config.RECEIPT_BACKEND,
+        "hf_receipt_model": bool(os.getenv("HF_RECEIPT_MODEL_REPO", "").strip()),
+        "modal_ocr": bool(
+            (os.getenv("MODAL_RECEIPT_ENDPOINT") or os.getenv("MINICPM_RECEIPT_ENDPOINT") or "").strip()
+        ),
+        "modal_speech": bool(
+            (os.getenv("MODAL_SPEECH_ENDPOINT") or os.getenv("SPEECH_ASR_ENDPOINT") or "").strip()
+        ),
+    }
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Traceability helper
+# ──────────────────────────────────────────────────────────────────────────────
+
+def _record_approval_manifest(source_doc: str, result: dict) -> None:
+    """Write a lightweight approval manifest for FastAPI-path stock writes."""
+    ts = utc_now_iso()
+    try:
+        write_manifest({
+            "run_id": new_run_id("inventory-approval"),
+            "kind": "inventory-approval",
+            "status": "succeeded",
+            "started_at": ts,
+            "ended_at": ts,
+            "metadata": {
+                "approval_type": source_doc,
+                "product_id": result.get("product_id", ""),
+                "product_name": result.get("product_name", ""),
+                "previous_stock": result.get("previous_stock"),
+                "new_stock": result.get("new_stock"),
+                "delta": result.get("delta"),
+            },
+        })
+    except Exception:
+        pass  # manifest writes must never break the approval flow
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Action handlers — each returns (state, toast)
+# ──────────────────────────────────────────────────────────────────────────────
+
+def _h_navigate(state, params):
+    state["page"] = params.get("to", "dashboard")
+    return state, ""
+
+
+def _h_refresh(state, _params):
+    return state, "success|Refreshed"
+
+
+def _h_run_analysis(state, _params):
+    result = run_analysis()
+    state["insights"] = {
+        "inventory": result.get("ai_inventory_analysis", ""),
+        "seasonal":  result.get("ai_seasonal_advice", ""),
+        "expiry":    result.get("ai_expiry_advice", ""),
+    }
+    ui_render.invalidate_insights()
+    n = len(result.get("suggested_orders", []))
+    state["page"] = "dashboard"
+    msg = f"AI analysis complete · {n} restock order(s) generated" if n else "AI analysis complete"
+    return state, f"success|{msg}"
+
+
+def _h_refresh_insights(state, _params):
+    ui_render.invalidate_insights()
+    state["page"] = "dashboard"
+    return state, "success|Refreshing AI insights…"
+
+
+def _h_add_to_order(state, params):
+    pid = params.get("pid")
+    try:
+        qty = float(params.get("qty"))
+    except (TypeError, ValueError):
+        return state, "danger|Could not queue this reorder"
+    p = db.get_product(pid)
+    if not p:
+        state["page"] = "dashboard"
+        return state, "danger|Product not found"
+    db.insert_orders([{
+        "product_id": pid,
+        "product_name": p["name"],
+        "qty_needed": qty,
+        "unit": p["unit"],
+        "reason": "Manual reorder from dashboard",
+        "ai_confidence": 0.95,
+    }])
+    state["page"] = "orders"
+    state["orders_filter"] = "pending"
+    return state, f"success|Reorder queued for {p['name']}"
+
+
+def _h_offer_to_route(state, params):
+    pid = params.get("pid")
+    p = db.get_product(pid)
+    if not p:
+        state["page"] = "dashboard"
+        return state, "danger|Product not found"
+    db.insert_orders([{
+        "product_id": pid,
+        "product_name": p["name"],
+        "qty_needed": p["quantity"],
+        "unit": p["unit"],
+        "reason": "Liquidation route offer for near-expiry or overstock item",
+        "ai_confidence": 0.7,
+    }])
+    state["page"] = "orders"
+    state["orders_filter"] = "pending"
+    return state, f"success|Liquidation offer logged for {p['name']}"
+
+
+def _h_plan_festival_stock(state, params):
+    key = (params.get("key") or "").strip()
+    state["page"] = "seasonal"
+    return state, f"info|Festival plan opened · {key or 'upcoming'}"
+
+
+def _h_filter_inventory(state, params):
+    state["filters"]["q"]        = params.get("q", "")
+    state["filters"]["category"] = params.get("category", "All")
+    state["filters"]["status"]   = params.get("status", "All")
+    state["page"] = "inventory"
+    return state, ""
+
+
+def _h_update_stock(state, params):
+    pid = params.get("pid")
+    try:
+        qty = float(params["qty"])
+    except (KeyError, ValueError, TypeError):
+        return state, "danger|Invalid product ID or quantity"
+    mode = params.get("mode", "add")
+    db.adjust_stock(pid, qty, mode=mode)
+    p = db.get_product(pid)
+    state["page"] = "inventory"
+    return state, ("success|" + (f"{p['name']} → {p['quantity']} {p['unit']}" if p else "Updated"))
+
+
+def _h_record_sale(state, params):
+    pid = params.get("pid")
+    try:
+        qty = float(params["qty"]); price = float(params["price"])
+    except (KeyError, ValueError, TypeError):
+        return state, "danger|Invalid sale input"
+    db.record_sale(pid, qty, price)
+    p = db.get_product(pid)
+    state["page"] = "inventory"
+    return state, "success|" + (f"Sale recorded · {p['name']} remaining {p['quantity']}" if p else "Sale recorded")
+
+
+def _h_delete_product(state, params):
+    pid = params.get("pid")
+    if not pid:
+        return state, "danger|Invalid ID"
+    p = db.get_product(pid)
+    if not p:
+        return state, "warn|Product not found"
+    db.delete_product(pid)
+    state["page"] = "inventory"
+    return state, f"success|'{p['name']}' deleted"
+
+
+def _h_add_product(state, params):
+    name = (params.get("name") or "").strip()
+    if not name:
+        return state, "danger|Product name is required"
+    try:
+        qty = float(params.get("qty") or 0)
+        min_stock = float(params.get("min_stock") or 0)
+        buy = float(params.get("buy_price") or 0)
+        sell = float(params.get("sell_price") or 0)
+    except (ValueError, TypeError):
+        return state, "danger|Quantity and prices must be numbers"
+    expiry = (params.get("expiry_date") or "").strip() or None
+    db.add_product(
+        name, params.get("category", "Other"), qty, params.get("unit", "kg"),
+        min_stock, buy, sell,
+        name_local=(params.get("name_local") or "").strip(),
+        expiry_date=expiry,
+        supplier=(params.get("supplier") or "").strip(),
+    )
+    state["page"] = "inventory"
+    state["filters"] = {"q": "", "category": "All", "status": "All"}
+    return state, f"success|'{name}' added to inventory"
+
+
+def _h_apply_receipt_row(state, params):
+    qty = params.get("quantity") or 0
+    try:
+        qty_f = float(qty)
+    except (ValueError, TypeError):
+        qty_f = 0.0
+    if qty_f <= 0:
+        state["page"] = "add"; state["active_method"] = "photo"
+        return state, "danger|Row has no usable quantity"
+
+    pid = params.get("matched_product_id")
+    if pid:
+        result = db.adjust_stock(pid, qty_f, mode="add")
+        _record_approval_manifest("receipt_row", result)
+        p = db.get_product(pid)
+        name = p["name"] if p else pid
+        msg = f"Added {qty_f:g} to {name}"
+    else:
+        name = (params.get("product_raw") or "").strip() or "Unknown item"
+        unit_price = float(params.get("unit_price") or 0)
+        db.add_product(
+            name, "Other", qty_f, "unit",
+            min_stock=0, buy_price=unit_price, sell_price=0,
+            supplier=(params.get("supplier") or "").strip(),
+        )
+        msg = f"Created '{name}' with {qty_f:g} units"
+
+    photo_result = state.get("photo_result") or {}
+    push_trace(
+        input_type="photo",
+        raw_command=name,
+        trace=photo_result.get("trace") or [],
+        action="add_stock",
+        product=name,
+        quantity=qty_f,
+    )
+    state["page"] = "add"; state["active_method"] = "photo"
+    return state, f"success|{msg}"
+
+
+def _h_voice_command(state, params):
+    text = (params.get("text") or "").strip()
+    if not text:
+        return state, "warn|Please type a command"
+    parsed = run_command_parse(text)
+    action = parsed.get("action", "unknown")
+    pid = parsed.get("product_id")
+    qty = parsed.get("quantity")
+    needs_approval = action in {"add_stock", "set_stock"} and bool(pid) and qty is not None
+
+    state["voice_result"] = {
+        "action":         action,
+        "product":        parsed.get("product", ""),
+        "product_id":     pid,
+        "quantity":       qty,
+        "unit":           parsed.get("unit", ""),
+        "confidence":     parsed.get("confidence", "low"),
+        "trace":          parsed.get("trace", []),
+        "applied":        None,
+        "needs_approval": needs_approval,
+        "suggested_name": parsed.get("suggested_name"),
+        "suggested_qty":  parsed.get("suggested_qty"),
+        "raw_command":    text,
+    }
+    state["page"] = "add"
+    state["active_method"] = "voice"
+    if needs_approval:
+        return state, "info|Command parsed — approve before stock changes"
+    return state, "warn|Could not parse a stock update"
+
+
+def _h_voice_apply(state, params):
+    action = params.get("action")
+    pid = params.get("product_id")
+    qty = params.get("quantity")
+    if action not in {"add_stock", "set_stock"} or not pid or qty is None:
+        state["page"] = "add"
+        state["active_method"] = "voice"
+        return state, "danger|No valid parsed command to apply"
+
+    try:
+        qty_f = float(qty)
+    except (TypeError, ValueError):
+        state["page"] = "add"
+        state["active_method"] = "voice"
+        return state, "danger|Invalid quantity"
+
+    mode = "add" if action == "add_stock" else "set"
+    result = db.adjust_stock(pid, qty_f, mode=mode)
+    _record_approval_manifest("voice_command", result)
+    p = db.get_product(pid)
+    name = p["name"] if p else params.get("product", "product")
+    applied = f"Added {qty_f:g} to {name}" if mode == "add" else f"Set {name} stock to {qty_f:g}"
+    push_trace(
+        input_type="voice",
+        raw_command=params.get("raw_command") or params.get("product", ""),
+        trace=params.get("trace") or [],
+        action=action,
+        product=name,
+        quantity=qty_f,
+    )
+
+    state["voice_result"] = {
+        "action": action,
+        "product": name,
+        "product_id": pid,
+        "quantity": qty_f,
+        "unit": params.get("unit", ""),
+        "confidence": params.get("confidence", "high"),
+        "trace": params.get("trace", []),
+        "applied": applied,
+        "needs_approval": False,
+    }
+    state["page"] = "inventory"
+    state["filters"] = {"q": "", "category": "All", "status": "All"}
+    return state, f"success|{applied}"
+
+
+def _h_generate_orders(state, _params):
+    result = run_analysis()
+    n = len(result.get("suggested_orders", []))
+    state["page"] = "orders"
+    state["orders_filter"] = "pending"
+    return state, ("success|" + (f"{n} order(s) generated" if n else "No restock needed"))
+
+
+def _h_filter_orders(state, params):
+    state["orders_filter"] = params.get("status", "pending")
+    state["page"] = "orders"
+    return state, ""
+
+
+def _h_filter_analytics(state, params):
+    try:
+        days = int(params.get("days", 30))
+    except (TypeError, ValueError):
+        days = 30
+    state["analytics_days"] = days if days in {7, 30, 90} else 30
+    state["page"] = "analytics"
+    return state, ""
+
+
+def _h_approve_order(state, params):
+    oid = params.get("oid")
+    if not oid:
+        return state, "danger|Invalid order ID"
+    db.update_order_status(oid, "approved")
+    state["page"] = "orders"
+    return state, f"success|Order #{oid} approved"
+
+
+def _h_mark_order_received(state, params):
+    oid = params.get("oid")
+    if not oid:
+        return state, "danger|Invalid order ID"
+    order = _find_order(str(oid))
+    if not order:
+        state["page"] = "orders"
+        return state, "danger|Order not found"
+    if order.get("status") != "approved":
+        state["page"] = "orders"
+        return state, "warn|Approve the order before marking it received"
+    if not order.get("product_id"):
+        state["page"] = "orders"
+        return state, "danger|Order has no product match"
+
+    db.adjust_stock(order["product_id"], float(order.get("qty_needed") or 0), mode="add")
+    db.update_order_status(oid, "received")
+    state["page"] = "orders"
+    state["orders_filter"] = "received"
+    return state, f"success|Order #{oid} received and stock updated"
+
+
+def _h_reject_order(state, params):
+    oid = params.get("oid")
+    if not oid:
+        return state, "danger|Invalid order ID"
+    db.update_order_status(oid, "rejected")
+    state["page"] = "orders"
+    return state, f"warn|Order #{oid} rejected"
+
+
+def _h_save_settings(state, params):
+    for key in ("shop_name", "owner_name", "region", "low_stock_days_ahead", "expiry_warn_days"):
+        if key in params:
+            db.set_setting(key, str(params[key]))
+    state["page"] = "settings"
+    return state, "success|Settings saved"
+
+
+HANDLERS = {
+    "navigate":            _h_navigate,
+    "refresh":             _h_refresh,
+    "run_analysis":        _h_run_analysis,
+    "refresh_insights":    _h_refresh_insights,
+    "add_to_order":        _h_add_to_order,
+    "offer_to_route":      _h_offer_to_route,
+    "plan_festival_stock": _h_plan_festival_stock,
+    "filter_inventory": _h_filter_inventory,
+    "update_stock":     _h_update_stock,
+    "record_sale":      _h_record_sale,
+    "delete_product":   _h_delete_product,
+    "add_product":      _h_add_product,
+    "apply_receipt_row": _h_apply_receipt_row,
+    "voice_command":    _h_voice_command,
+    "voice_apply":      _h_voice_apply,
+    "generate_orders":  _h_generate_orders,
+    "filter_orders":    _h_filter_orders,
+    "filter_analytics": _h_filter_analytics,
+    "approve_order":    _h_approve_order,
+    "mark_order_received": _h_mark_order_received,
+    "reject_order":     _h_reject_order,
+    "save_settings":    _h_save_settings,
+}
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# gr.Server engine
+# ──────────────────────────────────────────────────────────────────────────────
+server = Server(title="Kirana AI", docs_url=None, redoc_url=None)
+server.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
+
+
+INDEX_HTML = """<!doctype html>
+<html lang="en" data-theme="dark">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Kirana AI</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="/static/app.css">
+</head>
+<body>
+  <div class="page-host">{initial_html}</div>
+  <input type="file" id="kirana-photo-input" accept="image/*" style="position:absolute;left:-9999px;top:-9999px;">
+  <script>window.__KIRANA_STATE__ = {initial_state_json};</script>
+  <script src="/static/app.js" defer></script>
+</body>
+</html>"""
+
+
+@server.get("/", response_class=HTMLResponse)
+def index() -> str:
+    state = _new_state()
+    html = ui_render.render("dashboard", state)
+    return INDEX_HTML.format(
+        initial_html=html,
+        initial_state_json=json.dumps(state),
+    )
+
+
+@server.post("/api/dispatch")
+def api_dispatch(payload: dict) -> dict:
+    state = payload.get("state") or _new_state()
+    action = payload.get("action", "")
+    params = payload.get("params") or {}
+
+    handler = HANDLERS.get(action)
+    if not handler:
+        html = ui_render.render(state.get("page", "dashboard"), state,
+                                toast=f"warn|Unknown action: {action}")
+        return {"html": html, "state": state}
+
+    state, toast = handler(state, params)
+    html = ui_render.render(state["page"], state, toast=toast)
+    return {"html": html, "state": state}
+
+
+@server.post("/api/photo")
+async def api_photo(state: str = Form(...), image: UploadFile = File(...)) -> dict:
+    state_dict = json.loads(state) if state else _new_state()
+    suffix = Path(image.filename or "").suffix or ".jpg"
+    with tempfile.NamedTemporaryFile(delete=False, suffix=suffix) as tmp:
+        shutil.copyfileobj(image.file, tmp)
+        tmp_path = tmp.name
+
+    try:
+        react_result = get_react_agent().extract_receipt_image(tmp_path)
+        trace = list(react_result.trace)
+        rows = _match_receipt_rows(react_result.receipt_rows or [], trace)
+        raw_text = react_result.raw_text or ""
+        ocr_model = "react_agent"
+    except Exception as exc:
+        rows, trace, raw_text, ocr_model = _extract_receipt_direct(tmp_path)
+        trace.insert(0, f"[react_agent] Unavailable; used direct receipt path: {exc}")
+
+    if rows:
+        result = {
+            "rows": rows,
+            "trace": trace,
+            "raw_text": raw_text,
+            "ocr_model": ocr_model,
+        }
+        toast = f"info|Receipt parsed · {len(rows)} row(s)"
+    else:
+        result = {
+            "error": trace[-1] if trace else "No rows extracted",
+            "trace": trace,
+            "raw_text": raw_text,
+            "ocr_model": ocr_model,
+        }
+        toast = f"warn|{result['error']}"
+
+    state_dict["photo_result"] = result
+    state_dict["page"] = "add"
+    state_dict["active_method"] = "photo"
+    html = ui_render.render(state_dict["page"], state_dict, toast=toast)
+    return {"html": html, "state": state_dict}
+
+
+@server.post("/api/speech")
+async def api_speech(state: str = Form(...), audio: UploadFile = File(...)) -> dict:
+    state_dict = json.loads(state) if state else _new_state()
+    suffix = Path(audio.filename or "").suffix or ".wav"
+
+    with tempfile.NamedTemporaryFile(delete=False, suffix=suffix) as tmp:
+        shutil.copyfileobj(audio.file, tmp)
+        tmp_path = tmp.name
+
+    transcript, trace = transcribe_audio(tmp_path)
+
+    state_dict["voice_result"] = {
+        "transcript": transcript,
+        "trace": trace,
+    }
+    state_dict["page"] = "add"
+    state_dict["active_method"] = "voice"
+
+    toast = "success|Speech transcribed" if transcript else f"warn|{trace[-1] if trace else 'Speech transcription failed'}"
+    html = ui_render.render(state_dict["page"], state_dict, toast=toast)
+    return {"html": html, "state": state_dict}
+
+
+@server.get("/api/status")
+def api_status() -> dict:
+    return _service_status()
+
+
+@server.get("/api/warm")
+def api_warm() -> dict:
+    import os
+    import requests
+
+    endpoints = [
+        os.getenv("MODAL_RECEIPT_ENDPOINT", "").strip(),
+        os.getenv("MINICPM_RECEIPT_ENDPOINT", "").strip(),
+        os.getenv("MODAL_RECEIPT_LLM_ENDPOINT", "").strip(),
+        os.getenv("MODAL_SPEECH_ENDPOINT", "").strip(),
+        os.getenv("SPEECH_ASR_ENDPOINT", "").strip(),
+    ]
+
+    # NLU health endpoint — derive from extract URL by swapping the label
+    nlu_extract = os.getenv("MODAL_NLU_ENDPOINT", "").strip()
+    if nlu_extract:
+        endpoints.append(nlu_extract.replace("nlu-extract", "nlu-health"))
+
+    warmed = 0
+
+    def _ping(url: str) -> None:
+        try:
+            requests.get(url, timeout=5)
+        except Exception:
+            pass
+
+    for endpoint in sorted({e for e in endpoints if e}):
+        warmed += 1
+        threading.Thread(target=_ping, args=(endpoint,), daemon=True).start()
+
+    return {"ok": True, "warmed": warmed}
+
+
+if __name__ == "__main__":
+    server.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        show_error=True,
+    )

archive/legacy/asr.py

@@ -0,0 +1,26 @@
+"""Telugu ASR using Whisper — models/asr.py"""
+import logging
+logger = logging.getLogger(__name__)
+
+_whisper_model = None
+
+def _load_whisper():
+    global _whisper_model
+    if _whisper_model is None:
+        import whisper
+        # "small" is ~244M params, good Telugu accuracy, fast on CPU
+        _whisper_model = whisper.load_model("small")
+        logger.info("Whisper small loaded")
+    return _whisper_model
+
+def transcribe_telugu(audio_path: str) -> str:
+    """Transcribe Telugu audio file → Telugu text string."""
+    try:
+        model = _load_whisper()
+        result = model.transcribe(audio_path, language="te", task="transcribe")
+        text = result.get("text", "").strip()
+        logger.info(f"ASR: {text[:80]}")
+        return text
+    except Exception as e:
+        logger.error(f"ASR failed: {e}")
+        return ""

archive/legacy/database.py

@@ -0,0 +1,357 @@
+"""
+SQLite database layer.
+Schema initialised on first run. All writes use parameterised queries.
+"""
+
+import sqlite3
+import uuid
+from datetime import datetime, timedelta
+from pathlib import Path
+
+DB_PATH = Path(__file__).parent.parent / "dukaan.db"
+
+
+def _conn():
+    conn = sqlite3.connect(DB_PATH)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA journal_mode=WAL")
+    return conn
+
+
+# ---------------------------------------------------------------------------
+# Schema
+# ---------------------------------------------------------------------------
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS products (
+    id              TEXT PRIMARY KEY,
+    name            TEXT NOT NULL,
+    variant         TEXT,
+    supplier_id     TEXT,
+    unit_type       TEXT DEFAULT 'unit',
+    units_per_case  INTEGER DEFAULT 1,
+    reorder_threshold INTEGER DEFAULT 2,
+    last_unit_cost  REAL DEFAULT 0,
+    expiry_tracked  INTEGER DEFAULT 0,
+    created_at      TEXT DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS aliases (
+    alias       TEXT PRIMARY KEY,
+    product_id  TEXT NOT NULL,
+    FOREIGN KEY (product_id) REFERENCES products(id)
+);
+
+CREATE TABLE IF NOT EXISTS suppliers (
+    id              TEXT PRIMARY KEY,
+    name            TEXT NOT NULL,
+    gstin           TEXT,
+    phone           TEXT,
+    min_order_value REAL DEFAULT 0,
+    avg_lead_days   INTEGER DEFAULT 2
+);
+
+CREATE TABLE IF NOT EXISTS stock_ledger (
+    id          TEXT PRIMARY KEY,
+    product_id  TEXT NOT NULL,
+    delta       INTEGER NOT NULL,
+    event_type  TEXT NOT NULL,
+    source_doc  TEXT,
+    unit_cost   REAL DEFAULT 0,
+    recorded_at TEXT DEFAULT CURRENT_TIMESTAMP,
+    FOREIGN KEY (product_id) REFERENCES products(id)
+);
+
+CREATE TABLE IF NOT EXISTS sales_log (
+    id          TEXT PRIMARY KEY,
+    product_id  TEXT NOT NULL,
+    qty_sold    INTEGER NOT NULL,
+    unit_price  REAL DEFAULT 0,
+    note_ref    TEXT,
+    sold_date   TEXT DEFAULT CURRENT_DATE,
+    FOREIGN KEY (product_id) REFERENCES products(id)
+);
+
+CREATE TABLE IF NOT EXISTS purchase_orders (
+    id              TEXT PRIMARY KEY,
+    supplier_id     TEXT NOT NULL,
+    supplier_name   TEXT,
+    status          TEXT DEFAULT 'pending',
+    items_json      TEXT,
+    po_total        REAL DEFAULT 0,
+    created_at      TEXT DEFAULT CURRENT_TIMESTAMP,
+    approved_at     TEXT,
+    FOREIGN KEY (supplier_id) REFERENCES suppliers(id)
+);
+
+CREATE TABLE IF NOT EXISTS policies (
+    id          TEXT PRIMARY KEY,
+    rule_type   TEXT NOT NULL,
+    target      TEXT,
+    value_json  TEXT,
+    active      INTEGER DEFAULT 1
+);
+
+CREATE VIEW IF NOT EXISTS current_stock AS
+SELECT
+    p.id,
+    p.name,
+    p.supplier_id,
+    p.reorder_threshold,
+    p.units_per_case,
+    COALESCE(SUM(sl.delta), 0) AS current_units
+FROM products p
+LEFT JOIN stock_ledger sl ON sl.product_id = p.id
+GROUP BY p.id;
+"""
+
+SEED_DATA = """
+INSERT OR IGNORE INTO suppliers VALUES
+    ('sup_mahalakshmi', 'Mahalakshmi Marketing', '36RSLPS0259D1Z6', '7300000000', 2000, 1),
+    ('sup_venkateshwara', 'Sri Venkateshwara Marketing', '36AZLIPV6442K12M', '9959404640', 5000, 2);
+
+INSERT OR IGNORE INTO products VALUES
+    ('parle_g_100g',  'Parle-G 100g',    NULL, 'sup_venkateshwara', 'case', 24, 3, 8.625, 0, CURRENT_TIMESTAMP),
+    ('bingo_c',       'Bingo (C)',        NULL, 'sup_mahalakshmi',   'case', 12, 2, 870.0, 0, CURRENT_TIMESTAMP),
+    ('happy_24p',     'Happy (24P)',      NULL, 'sup_venkateshwara', 'case', 24, 3, 4.464, 0, CURRENT_TIMESTAMP),
+    ('parle_bulk',    'Parle (bulk)',     NULL, 'sup_mahalakshmi',   'case',  1, 1, 2450.0,0, CURRENT_TIMESTAMP);
+
+INSERT OR IGNORE INTO aliases VALUES
+    ('Bm',         'bingo_c'),
+    ('bingo',      'bingo_c'),
+    ('Bingo(C)',   'bingo_c'),
+    ('Bingo (C)',  'bingo_c'),
+    ('parle',      'parle_g_100g'),
+    ('parle-g',    'parle_g_100g'),
+    ('Parle-G',    'parle_g_100g'),
+    ('happy',      'happy_24p'),
+    ('Happy 2',    'happy_24p');
+
+INSERT OR IGNORE INTO policies VALUES
+    ('pol_min_order_maha',  'min_order', 'sup_mahalakshmi',   '{"value": 2000}', 1),
+    ('pol_min_order_venk',  'min_order', 'sup_venkateshwara', '{"value": 5000}', 1),
+    ('pol_price_spike',     'price_spike_alert_pct', NULL,    '{"value": 10}',   1);
+"""
+
+
+def init_db():
+    with _conn() as conn:
+        conn.executescript(SCHEMA)
+        conn.executescript(SEED_DATA)
+
+
+# ---------------------------------------------------------------------------
+# Reads
+# ---------------------------------------------------------------------------
+
+def get_stock_levels() -> list:
+    with _conn() as conn:
+        rows = conn.execute("""
+            SELECT
+                p.name,
+                s.name AS supplier,
+                cs.current_units || ' units' AS stock,
+                p.reorder_threshold || ' units' AS threshold,
+                CASE
+                    WHEN cs.current_units <= 0 THEN 'అయిపోయింది'
+                    WHEN cs.current_units <= p.reorder_threshold THEN 'తక్కువగా'
+                    ELSE 'OK'
+                END AS status
+            FROM current_stock cs
+            JOIN products p ON p.id = cs.id
+            LEFT JOIN suppliers s ON s.id = p.supplier_id
+            ORDER BY cs.current_units ASC
+        """).fetchall()
+        return [list(r) for r in rows]
+
+
+def get_products_below_threshold() -> list:
+    with _conn() as conn:
+        rows = conn.execute("""
+            SELECT cs.id AS product_id, p.name, p.supplier_id,
+                   cs.current_units AS current_stock,
+                   p.reorder_threshold, p.last_unit_cost
+            FROM current_stock cs
+            JOIN products p ON p.id = cs.id
+            WHERE cs.current_units <= p.reorder_threshold
+        """).fetchall()
+        return [dict(r) for r in rows]
+
+
+def get_product(product_id: str) -> dict | None:
+    with _conn() as conn:
+        row = conn.execute(
+            "SELECT * FROM products WHERE id = ?", (product_id,)
+        ).fetchone()
+        return dict(row) if row else None
+
+
+def get_supplier(supplier_id: str) -> dict | None:
+    with _conn() as conn:
+        row = conn.execute(
+            "SELECT * FROM suppliers WHERE id = ?", (supplier_id,)
+        ).fetchone()
+        return dict(row) if row else None
+
+
+def get_policies() -> dict:
+    with _conn() as conn:
+        rows = conn.execute(
+            "SELECT rule_type, target, value_json FROM policies WHERE active=1"
+        ).fetchall()
+    import json
+    result: dict = {"min_order_per_supplier": {}}
+    for r in rows:
+        val = json.loads(r["value_json"] or "{}").get("value")
+        if r["rule_type"] == "min_order" and r["target"]:
+            sup = get_supplier(r["target"])
+            if sup:
+                result["min_order_per_supplier"][sup["name"]] = val
+        else:
+            result[r["rule_type"]] = val
+    return result
+
+
+def get_last_unit_cost(product_id: str) -> float | None:
+    with _conn() as conn:
+        row = conn.execute(
+            """SELECT unit_cost FROM stock_ledger
+               WHERE product_id=? AND event_type='receipt' AND unit_cost > 0
+               ORDER BY recorded_at DESC LIMIT 1""",
+            (product_id,),
+        ).fetchone()
+        return row["unit_cost"] if row else None
+
+
+def get_pending_pos() -> list:
+    with _conn() as conn:
+        rows = conn.execute(
+            """SELECT id, supplier_name, items_json, po_total
+               FROM purchase_orders WHERE status='pending'
+               ORDER BY created_at DESC"""
+        ).fetchall()
+    result = []
+    import json
+    for r in rows:
+        items = json.loads(r["items_json"] or "[]")
+        item_summary = ", ".join(
+            f"{i.get('product_name','?')} ×{i.get('suggested_qty_cases','?')}"
+            for i in items
+        )
+        reason_te = "; ".join(i.get("reason_te", "") for i in items)
+        result.append([r["id"], r["supplier_name"], item_summary,
+                        f"₹{r['po_total']:.0f}", reason_te])
+    return result
+
+
+def get_weekly_summary() -> dict:
+    week_ago = (datetime.now() - timedelta(days=7)).isoformat()
+    with _conn() as conn:
+        purchases = conn.execute(
+            """SELECT COALESCE(SUM(delta * unit_cost), 0) as total
+               FROM stock_ledger WHERE event_type='receipt' AND recorded_at >= ?""",
+            (week_ago,),
+        ).fetchone()["total"]
+        sales_qty = conn.execute(
+            """SELECT COALESCE(SUM(ABS(delta)), 0) as qty
+               FROM stock_ledger WHERE event_type='sale' AND recorded_at >= ?""",
+            (week_ago,),
+        ).fetchone()["qty"]
+    return {"purchases_inr": purchases, "units_sold": sales_qty, "period": "7 days"}
+
+
+def get_shrinkage_report() -> dict:
+    with _conn() as conn:
+        received = conn.execute(
+            "SELECT COALESCE(SUM(delta),0) FROM stock_ledger WHERE event_type='receipt'"
+        ).fetchone()[0]
+        sold = abs(conn.execute(
+            "SELECT COALESCE(SUM(delta),0) FROM stock_ledger WHERE event_type='sale'"
+        ).fetchone()[0])
+        current = conn.execute(
+            "SELECT COALESCE(SUM(current_units),0) FROM current_stock"
+        ).fetchone()[0]
+    expected = received - sold
+    shrinkage = expected - current
+    pct = (shrinkage / received * 100) if received else 0
+    return {
+        "received": received, "sold": sold,
+        "expected_on_shelf": expected, "actual_on_shelf": current,
+        "shrinkage_units": shrinkage, "shrinkage_pct": round(pct, 2),
+    }
+
+
+def get_cost_vs_revenue() -> dict:
+    with _conn() as conn:
+        cost = conn.execute(
+            "SELECT COALESCE(SUM(ABS(delta)*unit_cost),0) FROM stock_ledger WHERE event_type='receipt'"
+        ).fetchone()[0]
+        revenue = conn.execute(
+            "SELECT COALESCE(SUM(qty_sold*unit_price),0) FROM sales_log"
+        ).fetchone()[0]
+    return {"total_cost_inr": cost, "estimated_revenue_inr": revenue,
+            "gross_margin_inr": revenue - cost}
+
+
+# ---------------------------------------------------------------------------
+# Writes
+# ---------------------------------------------------------------------------
+
+def update_stock(product_id, delta, event_type, source_doc, unit_cost=0):
+    with _conn() as conn:
+        conn.execute(
+            """INSERT INTO stock_ledger (id, product_id, delta, event_type, source_doc, unit_cost)
+               VALUES (?, ?, ?, ?, ?, ?)""",
+            (str(uuid.uuid4()), product_id, delta, event_type, source_doc, unit_cost),
+        )
+        if unit_cost > 0 and event_type == "receipt":
+            conn.execute(
+                "UPDATE products SET last_unit_cost=? WHERE id=?",
+                (unit_cost, product_id),
+            )
+
+
+def log_receipt(receipt: dict) -> str:
+    doc_id = str(uuid.uuid4())
+    import json
+    with _conn() as conn:
+        conn.execute(
+            """INSERT INTO stock_ledger (id, product_id, delta, event_type, source_doc)
+               VALUES (?, 'raw_receipt', 0, 'receipt_log', ?)""",
+            (doc_id, json.dumps(receipt, ensure_ascii=False)),
+        )
+    return doc_id
+
+
+def save_pending_po(po: dict) -> str:
+    import json
+    po_id = f"PO-{str(uuid.uuid4())[:8].upper()}"
+    with _conn() as conn:
+        conn.execute(
+            """INSERT INTO purchase_orders
+               (id, supplier_id, supplier_name, status, items_json, po_total)
+               VALUES (?, ?, ?, 'pending', ?, ?)""",
+            (
+                po_id,
+                po.get("supplier_id", "unknown"),
+                po.get("supplier_name", "Unknown"),
+                json.dumps(po.get("items", []), ensure_ascii=False),
+                po.get("po_total", 0),
+            ),
+        )
+    return po_id
+
+
+def approve_purchase_order(po_id: str):
+    with _conn() as conn:
+        conn.execute(
+            "UPDATE purchase_orders SET status='approved', approved_at=CURRENT_TIMESTAMP WHERE id=?",
+            (po_id,),
+        )
+
+
+def reject_purchase_order(po_id: str):
+    with _conn() as conn:
+        conn.execute(
+            "UPDATE purchase_orders SET status='rejected' WHERE id=?", (po_id,)
+        )

archive/legacy/finetune_receipt.py

@@ -0,0 +1,184 @@
+"""
+finetune_receipt.py — LoRA finetune Mistral-7B on receipt line-item extraction.
+
+Training data: photos/OCR text from Mahalakshmi Marketing and Sri Venkateshwara
+receipts, paired with correct structured JSON output.
+
+Run on HF free GPU (T4) or locally:
+    python finetune_receipt.py
+
+Output: ./mistral-7b-receipt-lora/  (merged GGUF exported at the end)
+
+Uses Unsloth for 2x faster training with 60% less VRAM.
+"""
+
+import json
+from pathlib import Path
+
+# ── Training dataset ─────────────────────────────────────────────────────────
+# Format: list of {"input": "<ocr_text>", "output": "<json_string>"}
+# Expand this with more receipts as you photograph them.
+
+TRAINING_EXAMPLES = [
+    {
+        "input": """MAHALAKSHMI MARKETING
+No. 2816  Date: 27/5/26
+M/s. Veerabala (Mulal)
+Parle  1 X 2450 = 2450
+Bingo(C)  4 X 870 = 3480
+Subtotal 5930
+Discount 612
+Total 6542""",
+        "output": json.dumps({
+            "supplier": "Mahalakshmi Marketing",
+            "invoice_no": "2816",
+            "date": "2026-05-27",
+            "items": [
+                {"product_raw": "Parle", "qty_cases": 1, "qty_units": 1,
+                 "unit_cost": 2450.0, "total": 2450.0},
+                {"product_raw": "Bingo(C)", "qty_cases": 4, "qty_units": 4,
+                 "unit_cost": 870.0, "total": 3480.0},
+            ],
+            "subtotal": 5930.0, "discount": 612.0, "gst": 0.0, "net_total": 6542.0,
+        }),
+    },
+    {
+        "input": """SRI VENKATESHWARA MARKETING
+GSTIN: 36AZLIPV6442K12M
+CUSTOMER: VEERA BHADRA WS
+Bill Date: 28/05/2026
+1 PARLE-G 100G  QTY: 5/0  MRP: 10  SALE RATE: 8.625
+2 HAPPY 2 (24P)*13  QTY: 10/0  MRP: 9  SALE RATE: 4.464
+GROSS SALES: 8569.032
+SCHEMES: 168.352
+CASH DISC: 420.034
+GST: 210.017  SGST: 210.017
+NET AMOUNT: 8821.00""",
+        "output": json.dumps({
+            "supplier": "Sri Venkateshwara Marketing",
+            "invoice_no": "SVM/26-27/2598",
+            "date": "2026-05-28",
+            "items": [
+                {"product_raw": "PARLE-G 100G", "qty_cases": 5, "qty_units": 120,
+                 "unit_cost": 8.625, "total": 1035.0},
+                {"product_raw": "HAPPY 2 (24P)", "qty_cases": 10, "qty_units": 240,
+                 "unit_cost": 4.464, "total": 1071.36},
+            ],
+            "subtotal": 8569.032, "discount": 588.386, "gst": 420.034, "net_total": 8821.0,
+        }),
+    },
+    {
+        "input": """Brundhna Boys - 28/05
+hne  30X28 = 840
+oam  50X9.5  450
+Bm   10X9.5  95
+Bm   5X12    50
+Total        1435""",
+        "output": json.dumps({
+            "supplier": "sales_note",
+            "invoice_no": None,
+            "date": "2026-05-28",
+            "items": [
+                {"product_raw": "hne",  "qty_cases": 0, "qty_units": 30, "unit_cost": 28.0, "total": 840.0},
+                {"product_raw": "oam",  "qty_cases": 0, "qty_units": 50, "unit_cost": 9.5,  "total": 450.0},
+                {"product_raw": "Bm",   "qty_cases": 0, "qty_units": 10, "unit_cost": 9.5,  "total": 95.0},
+                {"product_raw": "Bm",   "qty_cases": 0, "qty_units": 5,  "unit_cost": 12.0, "total": 50.0},
+            ],
+            "subtotal": 1435.0, "discount": 0.0, "gst": 0.0, "net_total": 1435.0,
+        }),
+    },
+]
+
+SYSTEM_PROMPT = """You are a receipt parser for an Indian convenience store.
+Extract all line items from the receipt text. Return ONLY valid JSON, no markdown."""
+
+INSTRUCTION_TEMPLATE = """### Instruction:
+{system}
+
+### Input:
+{input}
+
+### Response:
+{output}"""
+
+
+def build_dataset():
+    """Convert examples to Unsloth instruction format."""
+    return [
+        {
+            "text": INSTRUCTION_TEMPLATE.format(
+                system=SYSTEM_PROMPT,
+                input=ex["input"],
+                output=ex["output"],
+            )
+        }
+        for ex in TRAINING_EXAMPLES
+    ]
+
+
+def finetune():
+    from unsloth import FastLanguageModel
+    from trl import SFTTrainer
+    from transformers import TrainingArguments
+    from datasets import Dataset
+
+    print("Loading base model with Unsloth...")
+    model, tokenizer = FastLanguageModel.from_pretrained(
+        model_name="unsloth/mistral-7b-instruct-v0.2-bnb-4bit",
+        max_seq_length=2048,
+        dtype=None,
+        load_in_4bit=True,
+    )
+
+    # Apply LoRA
+    model = FastLanguageModel.get_peft_model(
+        model,
+        r=16,
+        target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
+                         "gate_proj", "up_proj", "down_proj"],
+        lora_alpha=16,
+        lora_dropout=0.05,
+        bias="none",
+        use_gradient_checkpointing=True,
+    )
+
+    dataset = Dataset.from_list(build_dataset())
+    print(f"Training on {len(dataset)} examples")
+
+    trainer = SFTTrainer(
+        model=model,
+        tokenizer=tokenizer,
+        train_dataset=dataset,
+        dataset_text_field="text",
+        max_seq_length=2048,
+        args=TrainingArguments(
+            per_device_train_batch_size=2,
+            gradient_accumulation_steps=4,
+            num_train_epochs=10,        # small dataset → more epochs
+            learning_rate=2e-4,
+            fp16=True,
+            logging_steps=1,
+            output_dir="./mistral-7b-receipt-lora",
+            save_strategy="epoch",
+            warmup_steps=5,
+            optim="adamw_8bit",
+        ),
+    )
+
+    trainer.train()
+    print("Training done. Saving LoRA weights...")
+    model.save_pretrained("./mistral-7b-receipt-lora")
+    tokenizer.save_pretrained("./mistral-7b-receipt-lora")
+
+    # Export merged GGUF for llama.cpp
+    print("Exporting merged GGUF (Q4_K_M)...")
+    model.save_pretrained_gguf(
+        "mistral-7b-receipt",
+        tokenizer,
+        quantization_method="q4_k_m",
+    )
+    print("Done! Upload mistral-7b-receipt-unsloth.Q4_K_M.gguf to your HF Space model dir.")
+
+
+if __name__ == "__main__":
+    finetune()

archive/legacy/graph.py

@@ -0,0 +1,103 @@
+"""
+LangGraph graph definition.
+
+Topology:
+    orchestrator
+        ├─(receipt_parse)──► receipt_parser ──► inventory_manager ──► po_check
+        ├─(reorder_trigger)─► inventory_manager ──► reorder_agent ──► po_check
+        ├─(sales_log)───────► inventory_manager ──► END
+        ├─(stock_query)─────► inventory_manager ──► END
+        └─(report)──────────► reporting_agent ──► END
+
+po_check:
+    if po_draft exists → HITL pause node (streams draft to UI, waits)
+    else              → END
+"""
+
+from langgraph.graph import StateGraph, END
+
+from state import AgentState
+from orchestrator import orchestrator_node
+from receipt_parser import receipt_parser_node
+from inventory_manager import inventory_manager_node
+from reorder_agent import reorder_agent_node
+from reporting_agent import reporting_agent_node
+from po_check import po_check_node
+
+
+def route_from_orchestrator(state: AgentState) -> str:
+    """Conditional edge: orchestrator → sub-agent based on classified intent."""
+    intent: str = state.get("intent") or "stock_query"
+    routes = {
+        "receipt_parse":    "receipt_parser",
+        "reorder_trigger":  "inventory_manager",
+        "sales_log":        "inventory_manager",
+        "stock_query":      "inventory_manager",
+        "report":           "reporting_agent",
+    }
+    return routes.get(intent, "inventory_manager")
+
+
+def route_after_inventory(state: AgentState) -> str:
+    """After inventory manager: go to reorder if that was the intent."""
+    intent: str = state.get("intent") or "stock_query"
+    if intent in ("reorder_trigger", "receipt_parse"):
+        return "reorder_agent"
+    return "po_check"
+
+
+def route_po_check(state: AgentState) -> str:
+    """If a PO draft exists, surface it; otherwise finish."""
+    if state.get("po_draft"):
+        return "po_check"
+    return END
+
+
+def build_graph() -> StateGraph:
+    g = StateGraph(AgentState)
+
+    # Register nodes
+    g.add_node("orchestrator",      orchestrator_node)
+    g.add_node("receipt_parser",    receipt_parser_node)
+    g.add_node("inventory_manager", inventory_manager_node)
+    g.add_node("reorder_agent",     reorder_agent_node)
+    g.add_node("reporting_agent",   reporting_agent_node)
+    g.add_node("po_check",          po_check_node)
+
+    # Entry point
+    g.set_entry_point("orchestrator")
+
+    # Orchestrator → sub-agents (conditional)
+    g.add_conditional_edges(
+        "orchestrator",
+        route_from_orchestrator,
+        {
+            "receipt_parser":    "receipt_parser",
+            "inventory_manager": "inventory_manager",
+            "reporting_agent":   "reporting_agent",
+        },
+    )
+
+    # Receipt parser always feeds inventory manager
+    g.add_edge("receipt_parser", "inventory_manager")
+
+    # Inventory manager branches
+    g.add_conditional_edges(
+        "inventory_manager",
+        route_after_inventory,
+        {
+            "reorder_agent": "reorder_agent",
+            "po_check":      "po_check",
+        },
+    )
+
+    # Reorder agent → po_check
+    g.add_edge("reorder_agent", "po_check")
+
+    # Reporting agent → END
+    g.add_edge("reporting_agent", END)
+
+    # po_check → END (HITL pause is handled inside the node)
+    g.add_edge("po_check", END)
+
+    return g.compile()

archive/legacy/inventory_manager.py

@@ -0,0 +1,112 @@
+"""
+Inventory manager node.
+
+Handles:
+- Updating stock levels from parsed receipts (delta = +qty received)
+- Updating stock levels from sales notes (delta = -qty sold)
+- Answering stock queries
+- Checking thresholds and flagging products needing reorder
+"""
+
+from state import AgentState
+from db.database import (
+    update_stock,
+    get_stock_levels,
+    get_products_below_threshold,
+)
+
+import logging
+logger = logging.getLogger(__name__)
+
+
+def inventory_manager_node(state: AgentState) -> AgentState:
+    trace = state.get("trace", [])
+    intent = state.get("intent", "stock_query")
+    policies = state.get("active_policies", {})
+
+    # ── Receipt parse: add incoming stock ────────────────────────────────────
+    if intent == "receipt_parse" and state.get("structured_data"):
+        items = state["structured_data"].get("items", [])
+        for item in items:
+            pid = item.get("product_id")
+            if not pid:
+                continue
+            # Convert cases → units using products table
+            qty_units = item.get("qty_units", 0) or (
+                item.get("qty_cases", 0) * _units_per_case(pid)
+            )
+            update_stock(
+                product_id=pid,
+                delta=+qty_units,
+                event_type="receipt",
+                source_doc=state["structured_data"].get("invoice_no", "unknown"),
+                unit_cost=item.get("unit_cost", 0),
+            )
+            trace.append(f"inventory_mgr: +{qty_units} units → {pid}")
+
+    # ── Sales log: subtract sold stock ──────────────────────────────────────
+    elif intent == "sales_log" and state.get("structured_data"):
+        items = state["structured_data"].get("items", [])
+        for item in items:
+            pid = item.get("product_id")
+            qty = item.get("qty_units", 0)
+            if pid and qty:
+                update_stock(
+                    product_id=pid,
+                    delta=-qty,
+                    event_type="sale",
+                    source_doc="sales_note",
+                    unit_cost=0,
+                )
+                trace.append(f"inventory_mgr: -{qty} units → {pid}")
+
+    # ── Stock query: build a natural-language response ───────────────────────
+    elif intent == "stock_query":
+        rows = get_stock_levels()
+        summary_lines = [f"{r[0]}: {r[2]} (threshold {r[3]})" for r in rows[:10]]
+        state = {
+            **state,
+            "response": "Current stock levels:\n" + "\n".join(summary_lines),
+        }
+        trace.append("inventory_mgr: stock query answered")
+
+    # ── Check thresholds → flag reorder candidates ───────────────────────────
+    below = get_products_below_threshold()
+    if below:
+        names = [p["name"] for p in below]
+        trace.append(f"inventory_mgr: {len(below)} products below threshold — {names}")
+        # Store for reorder agent to consume
+        state = {**state, "structured_data": {
+            **(state.get("structured_data") or {}),
+            "below_threshold": below,
+        }}
+
+    # Policy: flag if any price on this receipt is >10% above history
+    price_spike_pct = policies.get("price_spike_alert_pct", 10)
+    _check_price_spikes(state, price_spike_pct, trace)
+
+    return {**state, "trace": trace}
+
+
+def _units_per_case(product_id: str) -> int:
+    from db.database import get_product
+    p = get_product(product_id)
+    return p.get("units_per_case", 1) if p else 1
+
+
+def _check_price_spikes(state: dict, threshold_pct: float, trace: list):
+    from db.database import get_last_unit_cost
+    items = (state.get("structured_data") or {}).get("items", [])
+    for item in items:
+        pid = item.get("product_id")
+        new_cost = item.get("unit_cost", 0)
+        if not pid or not new_cost:
+            continue
+        last_cost = get_last_unit_cost(pid)
+        if last_cost and last_cost > 0:
+            pct_change = ((new_cost - last_cost) / last_cost) * 100
+            if pct_change > threshold_pct:
+                trace.append(
+                    f"inventory_mgr: PRICE SPIKE {pid} "
+                    f"₹{last_cost:.0f}→₹{new_cost:.0f} (+{pct_change:.1f}%)"
+                )

archive/legacy/llm.py

@@ -0,0 +1,161 @@
+"""
+LLM wrapper — calls the llama.cpp HTTP server running on localhost.
+
+llama.cpp is started as a background process in the HF Space via startup.sh.
+Each model is loaded as a separate server instance on different ports:
+
+  Port 8080 — llama-3.2-3b-instruct.Q4_K_M.gguf   (orchestrator)
+  Port 8081 — mistral-7b-instruct.Q4_K_M.gguf      (inventory, reorder, report)
+  Port 8082 — mistral-7b-receipt-lora.Q4_K_M.gguf  (finetuned receipt parser)
+
+All models are served via the OpenAI-compatible /v1/chat/completions endpoint.
+"""
+
+import json
+import logging
+from typing import Optional
+import urllib.request
+import urllib.error
+
+logger = logging.getLogger(__name__)
+
+MODEL_PORTS = {
+    "llama-3.2-3b":       8080,
+    "mistral-7b":         8081,
+    "mistral-7b-receipt": 8082,   # LoRA-merged GGUF
+}
+
+DEFAULT_MODEL = "mistral-7b"
+
+
+class Session:
+    """
+    Stateful conversation session.
+
+    Keeps the full inventory dict in the system prompt so the model always
+    sees current stock.  Only the last `history_turns` exchanges are sent as
+    message history — enough for follow-up questions without unbounded growth.
+    """
+
+    def __init__(
+        self,
+        model: str = DEFAULT_MODEL,
+        system: str = "",
+        inventory: Optional[dict] = None,
+        history_turns: int = 3,
+        **llm_kwargs,
+    ):
+        self.model = model
+        self._base_system = system
+        self.inventory: dict = inventory or {}
+        self.history_turns = history_turns
+        self.llm_kwargs = llm_kwargs
+        self._recent: list[dict] = []
+
+    # ------------------------------------------------------------------
+    # Inventory management
+    # ------------------------------------------------------------------
+
+    def set_inventory(self, inventory: dict) -> None:
+        """Replace the full inventory state."""
+        self.inventory = inventory
+
+    def update_inventory(self, updates: dict) -> None:
+        """Merge updates into the inventory (shallow merge by SKU key)."""
+        self.inventory.update(updates)
+
+    # ------------------------------------------------------------------
+    # Chat
+    # ------------------------------------------------------------------
+
+    def chat(self, user: str) -> str:
+        self._recent.append({"role": "user", "content": user})
+        history = self._recent[-(self.history_turns * 2):]
+        reply = _call_with_history(
+            self.model, self._system_prompt(), history, **self.llm_kwargs
+        )
+        self._recent.append({"role": "assistant", "content": reply})
+        return reply
+
+    def reset_history(self) -> None:
+        """Clear conversation history without touching the inventory."""
+        self._recent.clear()
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _system_prompt(self) -> str:
+        inventory_block = json.dumps(self.inventory, indent=2) if self.inventory else "empty"
+        parts = [self._base_system] if self._base_system else []
+        parts.append(f"Current inventory:\n{inventory_block}")
+        return "\n\n".join(parts)
+
+
+def _call_with_history(
+    model: str,
+    system: str,
+    history: list[dict],
+    max_tokens: int = 512,
+    json_mode: bool = False,
+    temperature: float = 0.1,
+) -> str:
+    port = MODEL_PORTS.get(model, MODEL_PORTS[DEFAULT_MODEL])
+    url = f"http://localhost:{port}/v1/chat/completions"
+
+    messages = ([{"role": "system", "content": system}] if system else []) + history
+
+    payload = {
+        "model": model,
+        "messages": messages,
+        "max_tokens": max_tokens,
+        "temperature": temperature,
+        "stream": False,
+    }
+    if json_mode:
+        payload["response_format"] = {"type": "json_object"}
+
+    try:
+        data = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=data,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            body = json.loads(resp.read().decode("utf-8"))
+            return body["choices"][0]["message"]["content"]
+
+    except urllib.error.URLError as e:
+        logger.error(f"llama.cpp unreachable at port {port}: {e}")
+        if port != MODEL_PORTS[DEFAULT_MODEL]:
+            logger.warning(f"Retrying with default model on port {MODEL_PORTS[DEFAULT_MODEL]}")
+            return _call_with_history(DEFAULT_MODEL, system, history, max_tokens, json_mode, temperature)
+        return '{"error": "llama.cpp server unavailable"}'
+
+    except (KeyError, json.JSONDecodeError) as e:
+        logger.error(f"Unexpected response from llama.cpp: {e}")
+        return '{"error": "malformed response"}'
+
+
+def call_llm(
+    model: str,
+    system: str,
+    user: str,
+    max_tokens: int = 512,
+    json_mode: bool = False,
+    temperature: float = 0.1,
+) -> str:
+    """
+    Call llama.cpp HTTP server (single-turn, stateless).
+    Returns the assistant message content string.
+    Falls back to DEFAULT_MODEL if the requested model port is unavailable.
+    """
+    return _call_with_history(
+        model, system,
+        [{"role": "user", "content": user}],
+        max_tokens=max_tokens,
+        json_mode=json_mode,
+        temperature=temperature,
+    )

archive/legacy/ocr.py

@@ -0,0 +1,86 @@
+"""
+Receipt image OCR using Qwen2.5-VL-7B-Instruct.
+Converts a photo of a receipt (handwritten or printed) into structured text,
+which is then passed to the receipt_parser LLM node.
+"""
+
+import base64
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+_vl_model = None
+_vl_processor = None
+
+OCR_PROMPT = """Look at this receipt image from an Indian convenience store supplier.
+Extract ALL text you can see, preserving:
+- Supplier name and GST number
+- Invoice/receipt number and date
+- Each line item: product name, quantity, rate/price, and amount
+- Any totals, discounts, GST amounts
+
+Write out the full text exactly as it appears. Product names will be in English.
+Numbers may be written as multiplications like '4×870=3480'."""
+
+
+def _load_vl_model():
+    global _vl_model, _vl_processor
+    if _vl_model is None:
+        from transformers import Qwen2VLForConditionalGeneration, AutoProcessor
+        name = "Qwen/Qwen2.5-VL-7B-Instruct"
+        _vl_processor = AutoProcessor.from_pretrained(name)
+        _vl_model = Qwen2VLForConditionalGeneration.from_pretrained(
+            name,
+            torch_dtype="auto",
+            device_map="auto",
+        )
+        logger.info("Qwen2.5-VL-7B loaded")
+    return _vl_processor, _vl_model
+
+
+def parse_receipt_image(image_path: str) -> dict:
+    """
+    Run vision model on receipt photo.
+    Returns dict with 'raw_text' (OCR output) and basic structured fields.
+    The receipt_parser LLM node does the full structured extraction from raw_text.
+    """
+    if not image_path or not Path(image_path).exists():
+        return {"raw_text": "", "error": "No image provided"}
+
+    try:
+        processor, model = _load_vl_model()
+
+        # Encode image as base64
+        with open(image_path, "rb") as f:
+            img_b64 = base64.b64encode(f.read()).decode("utf-8")
+
+        # Detect mime type
+        suffix = Path(image_path).suffix.lower()
+        mime = {"jpg": "image/jpeg", ".jpeg": "image/jpeg",
+                ".png": "image/png", ".webp": "image/webp"}.get(suffix, "image/jpeg")
+
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": f"data:{mime};base64,{img_b64}"},
+                    {"type": "text",  "text": OCR_PROMPT},
+                ],
+            }
+        ]
+
+        text_input = processor.apply_chat_template(
+            messages, tokenize=False, add_generation_prompt=True
+        )
+        inputs = processor(text=[text_input], return_tensors="pt").to(model.device)
+        output_ids = model.generate(**inputs, max_new_tokens=1024)
+        generated = output_ids[:, inputs["input_ids"].shape[1]:]
+        raw_text = processor.batch_decode(generated, skip_special_tokens=True)[0]
+
+        logger.info(f"OCR completed: {len(raw_text)} chars extracted")
+        return {"raw_text": raw_text, "source_image": image_path}
+
+    except Exception as e:
+        logger.error(f"Vision OCR failed: {e}")
+        return {"raw_text": "", "error": str(e)}

archive/legacy/orchestrator.py

@@ -0,0 +1,87 @@
+"""
+Orchestrator node.
+
+Responsibilities:
+1. Classify the intent of the (already English) input
+2. Load relevant policy rules from SQLite
+3. Resolve any product aliases via ChromaDB fuzzy match
+4. Inject both into state before routing
+
+Uses Llama-3.2-3B-Instruct via llama.cpp for fast intent classification.
+Structured output enforced via JSON mode.
+"""
+
+import json
+import logging
+from state import AgentState
+from db.database import get_policies
+from db.vector_store import resolve_aliases
+from models.llm import call_llm
+
+logger = logging.getLogger(__name__)
+
+ORCHESTRATOR_SYSTEM = """You are an inventory management orchestrator for a small
+Indian convenience store in Hyderabad. Your job is to classify the user's intent
+and extract key entities. Always respond with valid JSON only, no markdown.
+
+Valid intents:
+- receipt_parse   : user uploaded or described a supplier receipt
+- reorder_trigger : user says something is out of stock or wants to reorder
+- sales_log       : user is recording what was sold today
+- stock_query     : user wants to know current stock levels
+- report          : user wants a weekly/monthly report or shrinkage analysis
+
+Respond with:
+{
+  "intent": "<one of the above>",
+  "entities": {
+    "products": ["<product name>", ...],
+    "supplier": "<supplier name or null>",
+    "quantities": {"<product>": <number>, ...}
+  },
+  "confidence": 0.0–1.0
+}"""
+
+
+def orchestrator_node(state: AgentState) -> AgentState:
+    trace = state.get("trace", [])
+    input_text = state.get("input", "")
+
+    # 1. Classify intent via LLM
+    raw = call_llm(
+        model="llama-3.2-3b",
+        system=ORCHESTRATOR_SYSTEM,
+        user=input_text,
+        max_tokens=256,
+        json_mode=True,
+    )
+
+    try:
+        parsed = json.loads(raw)
+        intent = parsed.get("intent", "stock_query")
+        entities = parsed.get("entities", {})
+    except (json.JSONDecodeError, AttributeError):
+        logger.warning("Orchestrator JSON parse failed, defaulting to stock_query")
+        intent = "stock_query"
+        entities = {}
+
+    trace.append(f"orchestrator: intent={intent} confidence={parsed.get('confidence', '?')}")
+
+    # 2. Load policies from SQLite
+    policies = get_policies()
+    trace.append(f"orchestrator: loaded {len(policies)} policy rules")
+
+    # 3. Resolve product aliases via ChromaDB
+    product_mentions = entities.get("products", [])
+    resolved = {}
+    if product_mentions:
+        resolved = resolve_aliases(product_mentions)
+        trace.append(f"orchestrator: alias resolved {resolved}")
+
+    return {
+        **state,
+        "intent": intent,
+        "active_policies": policies,
+        "resolved_aliases": resolved,
+        "trace": trace,
+    }

archive/legacy/po_check.py

@@ -0,0 +1,41 @@
+"""
+po_check node — surfaces the PO draft and saves it as pending in SQLite.
+Actual approval/rejection happens via Gradio UI buttons (approve_po / reject_po).
+This node just persists the draft so the UI can display it.
+"""
+
+from state import AgentState
+from db.database import save_pending_po
+from models.translate import en_to_te
+
+
+def po_check_node(state: AgentState) -> AgentState:
+    trace = state.get("trace", [])
+    po_draft = state.get("po_draft")
+
+    if not po_draft:
+        trace.append("po_check: no PO draft, nothing to do")
+        return {**state, "trace": trace}
+
+    # Translate each item's reason into Telugu for the UI
+    for po in po_draft.get("purchase_orders", []):
+        for item in po.get("items", []):
+            reason_en = item.get("reason_en", "")
+            item["reason_te"] = en_to_te(reason_en) if reason_en else ""
+
+    # Persist as pending in SQLite (owner approves via UI)
+    po_ids = []
+    for po in po_draft.get("purchase_orders", []):
+        po_id = save_pending_po(po)
+        po_ids.append(po_id)
+        trace.append(
+            f"po_check: saved PO {po_id} for {po['supplier_name']} "
+            f"₹{po['po_total']:.0f} — awaiting owner approval"
+        )
+
+    response = (
+        f"{len(po_ids)} purchase order(s) ready for your approval. "
+        f"Check the approval panel to confirm or edit."
+    )
+
+    return {**state, "response": response, "trace": trace}

archive/legacy/receipt_parser.py

@@ -0,0 +1,113 @@
+"""
+Receipt parser node.
+
+Input:  state["input"] contains raw OCR text OR structured dict from vision model.
+Output: state["structured_data"] = validated receipt dict ready for DB write.
+
+Uses the LoRA-finetuned Mistral-7B (trained on Mahalakshmi / Sri Venkateshwara
+receipt formats) for line-item extraction and schema validation.
+
+Expected output schema:
+{
+  "supplier": str,
+  "invoice_no": str,
+  "date": "YYYY-MM-DD",
+  "items": [
+    {
+      "product_raw": str,   # as written on receipt
+      "product_id": str,    # resolved canonical ID
+      "qty_cases": int,
+      "qty_units": int,
+      "unit_cost": float,
+      "total": float
+    }
+  ],
+  "subtotal": float,
+  "discount": float,
+  "gst": float,
+  "net_total": float
+}
+"""
+
+import json
+import logging
+from state import AgentState
+from db.vector_store import resolve_aliases
+from db.database import log_receipt
+from models.llm import call_llm
+
+logger = logging.getLogger(__name__)
+
+PARSER_SYSTEM = """You are a receipt parser for an Indian convenience store.
+Extract all line items from the receipt text below. Product names will be in
+English. Quantities may be written as "4×870" or "4 cases" or "30X28=840".
+Prices are in Indian Rupees (₹). Dates are in DD/MM/YY format — convert to YYYY-MM-DD.
+
+Return ONLY valid JSON matching this exact schema:
+{
+  "supplier": "string",
+  "invoice_no": "string or null",
+  "date": "YYYY-MM-DD",
+  "items": [
+    {
+      "product_raw": "string",
+      "qty_cases": integer,
+      "qty_units": integer,
+      "unit_cost": number,
+      "total": number
+    }
+  ],
+  "subtotal": number,
+  "discount": number,
+  "gst": number,
+  "net_total": number
+}
+
+If a field is missing, use null for strings and 0 for numbers. Do not add markdown."""
+
+
+def receipt_parser_node(state: AgentState) -> AgentState:
+    trace = state.get("trace", [])
+    input_text = state.get("input", "")
+
+    # If vision model already returned structured dict, use it directly
+    if isinstance(state.get("structured_data"), dict):
+        raw_receipt = state["structured_data"]
+        trace.append("receipt_parser: using pre-parsed vision output")
+    else:
+        # Call finetuned Mistral-7B for text-based extraction
+        raw = call_llm(
+            model="mistral-7b-receipt",   # points to LoRA-merged GGUF
+            system=PARSER_SYSTEM,
+            user=input_text,
+            max_tokens=1024,
+            json_mode=True,
+        )
+        try:
+            raw_receipt = json.loads(raw)
+        except json.JSONDecodeError:
+            logger.warning("Receipt parser JSON decode failed")
+            raw_receipt = {"items": [], "net_total": 0}
+
+    trace.append(f"receipt_parser: found {len(raw_receipt.get('items', []))} line items")
+
+    # Resolve product aliases for each raw product name
+    raw_names = [i.get("product_raw", "") for i in raw_receipt.get("items", [])]
+    alias_map = resolve_aliases(raw_names) if raw_names else {}
+
+    for item in raw_receipt.get("items", []):
+        item["product_id"] = alias_map.get(item.get("product_raw", ""), None)
+
+    unresolved = [i["product_raw"] for i in raw_receipt["items"] if not i.get("product_id")]
+    if unresolved:
+        trace.append(f"receipt_parser: unresolved aliases — {unresolved} (needs owner mapping)")
+
+    # Persist to DB
+    doc_id = log_receipt(raw_receipt)
+    trace.append(f"receipt_parser: logged as receipt doc_id={doc_id}")
+
+    return {
+        **state,
+        "structured_data": raw_receipt,
+        "trace": trace,
+    }

archive/legacy/reorder_agent.py

@@ -0,0 +1,143 @@
+"""
+Reorder agent node.
+
+Takes the list of products below threshold, groups them by supplier,
+applies historical order quantity patterns from ChromaDB,
+and builds a draft PO for each supplier.
+
+Does NOT place orders — only produces po_draft for HITL approval.
+"""
+
+import json
+from state import AgentState
+from db.database import get_product, get_supplier, get_pending_pos
+from db.vector_store import get_order_pattern
+from models.llm import call_llm
+
+REORDER_SYSTEM = """You are a purchase order assistant for a small convenience store
+in Hyderabad, India. Given a list of low-stock products with their supplier and
+historical order quantities, generate a grouped purchase order suggestion.
+
+Apply these rules:
+1. Group all items from the same supplier into one PO
+2. Suggest quantity = max(reorder_threshold × 2, last_order_qty)
+3. Explain the suggestion reason in simple English (will be translated to Telugu)
+4. Check minimum order value policy per supplier
+
+Return ONLY valid JSON:
+{
+  "purchase_orders": [
+    {
+      "supplier_id": "str",
+      "supplier_name": "str",
+      "items": [
+        {
+          "product_id": "str",
+          "product_name": "str",
+          "suggested_qty_cases": int,
+          "unit_cost": float,
+          "total": float,
+          "reason_en": "str"
+        }
+      ],
+      "po_total": float,
+      "meets_min_order": bool
+    }
+  ]
+}"""
+
+
+def reorder_agent_node(state: AgentState) -> AgentState:
+    trace = state.get("trace", [])
+    policies = state.get("active_policies", {})
+
+    below = (state.get("structured_data") or {}).get("below_threshold", [])
+    if not below:
+        trace.append("reorder_agent: no products below threshold, skipping")
+        return {**state, "trace": trace}
+
+    # Enrich each product with supplier info and order history
+    enriched = []
+    for product in below:
+        pid = product.get("product_id") or product.get("id")
+        p = get_product(pid) or product
+        supplier = get_supplier(p.get("supplier_id", ""))
+        pattern = get_order_pattern(pid)   # from ChromaDB historical patterns
+
+        enriched.append({
+            "product_id": pid,
+            "product_name": p.get("name", pid),
+            "supplier_id": p.get("supplier_id", "unknown"),
+            "supplier_name": supplier.get("name", "Unknown") if supplier else "Unknown",
+            "current_stock": product.get("current_stock", 0),
+            "reorder_threshold": p.get("reorder_threshold", 2),
+            "last_order_qty_cases": pattern.get("avg_qty_cases", 2),
+            "unit_cost": p.get("last_unit_cost", 0),
+            "min_order_value": policies.get(
+                "min_order_per_supplier", {}
+            ).get(supplier.get("name", ""), 0) if supplier else 0,
+        })
+
+    trace.append(f"reorder_agent: enriched {len(enriched)} products for PO generation")
+
+    # Call LLM to generate grouped PO suggestions
+    raw = call_llm(
+        model="mistral-7b",
+        system=REORDER_SYSTEM,
+        user=json.dumps(enriched, ensure_ascii=False),
+        max_tokens=1024,
+        json_mode=True,
+    )
+
+    try:
+        result = json.loads(raw)
+        pos = result.get("purchase_orders", [])
+    except json.JSONDecodeError:
+        trace.append("reorder_agent: LLM JSON parse failed, building simple PO")
+        pos = _fallback_po(enriched)
+
+    # Flag POs that don't meet minimum order value
+    for po in pos:
+        if not po.get("meets_min_order", True):
+            trace.append(
+                f"reorder_agent: WARNING {po['supplier_name']} PO ₹{po['po_total']:.0f} "
+                f"below min order — flagged"
+            )
+
+    trace.append(f"reorder_agent: drafted {len(pos)} purchase orders for approval")
+
+    # Flatten into single po_draft structure
+    po_draft = {
+        "purchase_orders": pos,
+        "status": "pending_approval",
+    }
+
+    return {**state, "po_draft": po_draft, "trace": trace}
+
+
+def _fallback_po(enriched: list) -> list:
+    """Simple supplier-grouped PO without LLM, used as fallback."""
+    by_supplier: dict = {}
+    for item in enriched:
+        sid = item["supplier_id"]
+        if sid not in by_supplier:
+            by_supplier[sid] = {
+                "supplier_id": sid,
+                "supplier_name": item["supplier_name"],
+                "items": [],
+                "po_total": 0.0,
+                "meets_min_order": True,
+            }
+        qty = max(item["reorder_threshold"] * 2, item["last_order_qty_cases"])
+        total = qty * item["unit_cost"]
+        by_supplier[sid]["items"].append({
+            "product_id": item["product_id"],
+            "product_name": item["product_name"],
+            "suggested_qty_cases": qty,
+            "unit_cost": item["unit_cost"],
+            "total": total,
+            "reason_en": f"Stock at {item['current_stock']}, threshold {item['reorder_threshold']}",
+        })
+        by_supplier[sid]["po_total"] += total
+
+    return list(by_supplier.values())

archive/legacy/reporting_agent.py

@@ -0,0 +1,47 @@
+"""
+Reporting agent node — weekly/monthly summaries and shrinkage reports.
+Uses RAG: retrieves relevant stock_ledger records, then generates summary.
+"""
+
+from state import AgentState
+from db.database import (
+    get_weekly_summary,
+    get_shrinkage_report,
+    get_cost_vs_revenue,
+)
+from models.llm import call_llm
+
+REPORT_SYSTEM = """You are a reporting assistant for a small Indian convenience store.
+Summarize the provided inventory data clearly and concisely. Use simple English.
+Include: total stock purchased (₹), estimated revenue, shrinkage %, and top 3 alerts.
+Keep the response under 150 words. Do not use markdown headers."""
+
+
+def reporting_agent_node(state: AgentState) -> AgentState:
+    trace = state.get("trace", [])
+    input_text = state.get("input", "").lower()
+
+    # Determine report type from input
+    if "shrinkage" in input_text or "తేడా" in input_text:
+        data = get_shrinkage_report()
+        report_type = "shrinkage"
+    elif "weekly" in input_text or "week" in input_text or "వారం" in input_text:
+        data = get_weekly_summary()
+        report_type = "weekly"
+    else:
+        data = get_cost_vs_revenue()
+        report_type = "cost_revenue"
+
+    trace.append(f"reporting_agent: generating {report_type} report")
+
+    summary = call_llm(
+        model="mistral-7b",
+        system=REPORT_SYSTEM,
+        user=str(data),
+        max_tokens=300,
+        json_mode=False,
+    )
+
+    trace.append("reporting_agent: report generated")
+
+    return {**state, "response": summary, "trace": trace}

archive/legacy/state.py

@@ -0,0 +1,35 @@
+"""
+Shared state object threaded through every LangGraph node.
+All fields are Optional so nodes only populate what they produce.
+"""
+
+from typing import Any, Optional
+from typing_extensions import TypedDict
+
+
+class AgentState(TypedDict, total=False):
+    # Raw input from voice / receipt / text
+    input: str
+    source: str                  # "voice" | "receipt" | "query"
+
+    # Intent classified by orchestrator
+    intent: Optional[str]        # "receipt_parse" | "reorder_trigger" |
+                                 # "sales_log" | "stock_query" | "report"
+
+    # Structured data produced by receipt parser or inventory manager
+    structured_data: Optional[dict]
+
+    # Draft purchase order waiting for HITL approval
+    po_draft: Optional[dict]
+
+    # Final natural-language response (English; translated to Telugu in UI)
+    response: Optional[str]
+
+    # Step-by-step trace accumulated across nodes
+    trace: list[str]
+
+    # Policy rules injected by orchestrator before routing
+    active_policies: Optional[dict]
+
+    # Alias resolution result from vector DB lookup
+    resolved_aliases: Optional[dict]

archive/legacy/translate.py

@@ -0,0 +1,75 @@
+"""
+Telugu ↔ English translation using IndicTrans2 (ai4bharat).
+Runs fully locally — no API calls.
+
+Model: ai4bharat/indictrans2-indic-en-1B  (~1GB, CPU-friendly)
+       ai4bharat/indictrans2-en-indic-1B  for English → Telugu
+"""
+
+import logging
+logger = logging.getLogger(__name__)
+
+_te_en_model = None
+_te_en_tokenizer = None
+_en_te_model = None
+_en_te_tokenizer = None
+
+
+def _load_te_en():
+    global _te_en_model, _te_en_tokenizer
+    if _te_en_model is None:
+        from transformers import AutoModelForSeq2SeqLM, AutoTokenizer
+        name = "ai4bharat/indictrans2-indic-en-1B"
+        _te_en_tokenizer = AutoTokenizer.from_pretrained(name, trust_remote_code=True)
+        _te_en_model = AutoModelForSeq2SeqLM.from_pretrained(name, trust_remote_code=True)
+        logger.info("IndicTrans2 te→en loaded")
+    return _te_en_tokenizer, _te_en_model
+
+
+def _load_en_te():
+    global _en_te_model, _en_te_tokenizer
+    if _en_te_model is None:
+        from transformers import AutoModelForSeq2SeqLM, AutoTokenizer
+        name = "ai4bharat/indictrans2-en-indic-1B"
+        _en_te_tokenizer = AutoTokenizer.from_pretrained(name, trust_remote_code=True)
+        _en_te_model = AutoModelForSeq2SeqLM.from_pretrained(name, trust_remote_code=True)
+        logger.info("IndicTrans2 en→te loaded")
+    return _en_te_tokenizer, _en_te_model
+
+
+def te_to_en(text: str) -> str:
+    """Translate Telugu → English. Product names in English stay unchanged."""
+    if not text or not text.strip():
+        return text
+    # If text has no Telugu chars, return as-is
+    if not any("\u0C00" <= c <= "\u0C7F" for c in text):
+        return text
+    try:
+        tokenizer, model = _load_te_en()
+        # IndicTrans2 expects source language tag
+        tagged = f"<2en> {text}"
+        inputs = tokenizer(tagged, return_tensors="pt", padding=True)
+        outputs = model.generate(**inputs, max_new_tokens=256, num_beams=4)
+        result = tokenizer.decode(outputs[0], skip_special_tokens=True).strip()
+        logger.debug(f"te→en: '{text[:40]}' → '{result[:40]}'")
+        return result
+    except Exception as e:
+        logger.error(f"te_to_en failed: {e}")
+        return text
+
+
+def en_to_te(text: str) -> str:
+    """Translate English → Telugu. Numbers and product names kept in English."""
+    if not text or not text.strip():
+        return text
+    try:
+        tokenizer, model = _load_en_te()
+        tagged = f"<2te> {text}"
+        inputs = tokenizer(tagged, return_tensors="pt", padding=True)
+        outputs = model.generate(**inputs, max_new_tokens=256, num_beams=4)
+        result = tokenizer.decode(outputs[0], skip_special_tokens=True).strip()
+        logger.debug(f"en→te: '{text[:40]}' → '{result[:40]}'")
+        return result
+    except Exception as e:
+        logger.error(f"en_to_te failed: {e}")
+        return text

archive/legacy/vector_store.py

@@ -0,0 +1,167 @@
+"""
+ChromaDB vector store.
+
+Collections:
+  product_aliases  — embed product names/aliases; query to resolve fuzzy OCR text
+  receipt_chunks   — embed raw receipt text for price history RAG
+  order_patterns   — embed (product_id, month) → typical order qty
+"""
+
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+CHROMA_PATH = Path(__file__).parent.parent / "chroma_db"
+
+_client = None
+_alias_col = None
+_pattern_col = None
+
+
+def _get_client():
+    global _client
+    if _client is None:
+        import chromadb
+        _client = chromadb.PersistentClient(path=str(CHROMA_PATH))
+    return _client
+
+
+def _get_alias_collection():
+    global _alias_col
+    if _alias_col is None:
+        client = _get_client()
+        _alias_col = client.get_or_create_collection(
+            name="product_aliases",
+            metadata={"hnsw:space": "cosine"},
+        )
+        _seed_aliases()
+    return _alias_col
+
+
+def _seed_aliases():
+    """Seed alias collection from SQLite aliases table on first run."""
+    col = _alias_col
+    if col.count() > 0:
+        return
+    try:
+        from db.database import _conn
+        with _conn() as conn:
+            rows = conn.execute("SELECT alias, product_id FROM aliases").fetchall()
+        if rows:
+            col.upsert(
+                documents=[r["alias"] for r in rows],
+                ids=[f"alias_{i}" for i in range(len(rows))],
+                metadatas=[{"product_id": r["product_id"]} for r in rows],
+            )
+            logger.info(f"Seeded {len(rows)} aliases into ChromaDB")
+    except Exception as e:
+        logger.warning(f"Alias seed failed: {e}")
+
+
+def resolve_aliases(raw_names: list[str], threshold: float = 0.75) -> dict:
+    """
+    Given a list of raw product name strings (from OCR or voice),
+    return a dict mapping each raw name → canonical product_id.
+
+    Uses cosine similarity; returns None for names below threshold.
+    """
+    if not raw_names:
+        return {}
+
+    col = _get_alias_collection()
+    result = {}
+
+    for name in raw_names:
+        if not name.strip():
+            continue
+        try:
+            query_result = col.query(
+                query_texts=[name],
+                n_results=1,
+                include=["metadatas", "distances"],
+            )
+            distance = query_result["distances"][0][0] if query_result["distances"] else 1.0
+            similarity = 1 - distance   # cosine distance → similarity
+
+            if similarity >= threshold:
+                product_id = query_result["metadatas"][0][0].get("product_id")
+                result[name] = product_id
+                logger.debug(f"Alias resolved: '{name}' → {product_id} (sim={similarity:.2f})")
+            else:
+                result[name] = None
+                logger.debug(f"No alias match for '{name}' (best sim={similarity:.2f})")
+        except Exception as e:
+            logger.warning(f"Alias lookup failed for '{name}': {e}")
+            result[name] = None
+
+    return result
+
+
+def upsert_alias(alias: str, product_id: str):
+    """Add a new alias mapping (called when owner confirms an unresolved name)."""
+    col = _get_alias_collection()
+    col.upsert(
+        documents=[alias],
+        ids=[f"alias_{alias.lower().replace(' ', '_')}"],
+        metadatas=[{"product_id": product_id}],
+    )
+
+
+def get_order_pattern(product_id: str) -> dict:
+    """
+    Retrieve historical order pattern for a product.
+    Returns avg_qty_cases and seasonality hints.
+    Falls back to default if no history found.
+    """
+    try:
+        client = _get_client()
+        col = client.get_or_create_collection("order_patterns")
+        result = col.query(
+            query_texts=[product_id],
+            n_results=3,
+            include=["metadatas", "documents"],
+        )
+        if result["metadatas"] and result["metadatas"][0]:
+            meta = result["metadatas"][0][0]
+            return {
+                "avg_qty_cases": meta.get("avg_qty_cases", 2),
+                "last_qty_cases": meta.get("last_qty_cases", 2),
+            }
+    except Exception as e:
+        logger.warning(f"Order pattern lookup failed for {product_id}: {e}")
+
+    return {"avg_qty_cases": 2, "last_qty_cases": 2}
+
+
+def store_order_pattern(product_id: str, qty_cases: int):
+    """Update order pattern after a PO is approved."""
+    try:
+        client = _get_client()
+        col = client.get_or_create_collection("order_patterns")
+        from datetime import datetime
+        col.upsert(
+            documents=[f"{product_id} ordered {qty_cases} cases"],
+            ids=[f"pattern_{product_id}_{datetime.now().strftime('%Y%m')}"],
+            metadatas=[{
+                "product_id": product_id,
+                "avg_qty_cases": qty_cases,
+                "last_qty_cases": qty_cases,
+                "month": datetime.now().strftime("%Y-%m"),
+            }],
+        )
+    except Exception as e:
+        logger.warning(f"Failed to store order pattern: {e}")
+
+
+def embed_receipt_chunk(text: str, metadata: dict):
+    """Store a receipt text chunk for price history RAG."""
+    try:
+        client = _get_client()
+        col = client.get_or_create_collection("receipt_chunks")
+        import hashlib
+        chunk_id = hashlib.md5(text.encode()).hexdigest()
+        col.upsert(documents=[text], ids=[chunk_id], metadatas=[metadata])
+    except Exception as e:
+        logger.warning(f"Failed to embed receipt chunk: {e}")

benchmarks/benchmark_receipt_models.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import json
+import os
+import time
+from pathlib import Path
+
+import requests
+
+from dukaan_saathi.parsers.receipt_text import parse_receipt_text
+from dukaan_saathi.storage import init_db
+
+
+RECEIPT_IMAGES = [
+    Path("samples/receipts/printed_out_receipt.jpeg"),
+    Path("samples/receipts/receipt.jpeg"),
+    Path("samples/receipts/tally.jpeg"),
+]
+
+
+def post_image(endpoint: str, image_path: Path) -> dict:
+    start = time.perf_counter()
+
+    with image_path.open("rb") as f:
+        response = requests.post(
+            endpoint,
+            files={"image": (image_path.name, f, "image/jpeg")},
+            timeout=240,
+        )
+
+    elapsed = time.perf_counter() - start
+    response.raise_for_status()
+
+    payload = response.json()
+    payload["_client_latency_seconds"] = round(elapsed, 2)
+    return payload
+
+
+def score_payload(payload: dict) -> dict:
+    raw_text = payload.get("raw_text") or payload.get("text") or ""
+
+    rows, trace = parse_receipt_text(raw_text)
+
+    matched = [row for row in rows if row.get("matched_product_id")]
+    needs_review = [row for row in rows if not row.get("matched_product_id")]
+
+    return {
+        "model": payload.get("model", "unknown"),
+        "raw_text_chars": len(raw_text),
+        "parsed_row_count": len(rows),
+        "matched_row_count": len(matched),
+        "needs_review_count": len(needs_review),
+        "client_latency_seconds": payload.get("_client_latency_seconds"),
+        "server_latency_seconds": payload.get("latency_seconds"),
+        "trace": trace,
+        "raw_text": raw_text,
+        "rows": rows,
+    }
+
+
+def main() -> None:
+    init_db()
+
+    endpoints = {
+        "minicpm": os.getenv("MINICPM_RECEIPT_ENDPOINT", "").strip(),
+        "molmo": os.getenv("MOLMO_RECEIPT_ENDPOINT", "").strip(),
+    }
+
+    endpoints = {name: url for name, url in endpoints.items() if url}
+    if not endpoints:
+        raise SystemExit(
+            "Set at least one endpoint: MINICPM_RECEIPT_ENDPOINT or MOLMO_RECEIPT_ENDPOINT"
+        )
+
+    results = []
+
+    for model_name, endpoint in endpoints.items():
+        for image_path in RECEIPT_IMAGES:
+            print(f"\n=== {model_name} :: {image_path.name} ===")
+
+            try:
+                payload = post_image(endpoint, image_path)
+                score = score_payload(payload)
+                score["endpoint_name"] = model_name
+                score["image"] = image_path.name
+                results.append(score)
+
+                print(
+                    json.dumps(
+                        {
+                            "model": score["model"],
+                            "image": score["image"],
+                            "raw_text_chars": score["raw_text_chars"],
+                            "parsed_row_count": score["parsed_row_count"],
+                            "matched_row_count": score["matched_row_count"],
+                            "needs_review_count": score["needs_review_count"],
+                            "client_latency_seconds": score["client_latency_seconds"],
+                            "server_latency_seconds": score["server_latency_seconds"],
+                        },
+                        indent=2,
+                    )
+                )
+
+            except Exception as exc:
+                print(f"FAILED: {exc}")
+                results.append(
+                    {
+                        "endpoint_name": model_name,
+                        "image": image_path.name,
+                        "error": str(exc),
+                    }
+                )
+
+    out_dir = Path("benchmarks")
+    out_dir.mkdir(exist_ok=True)
+
+    out_path = out_dir / "receipt_model_benchmark.json"
+    out_path.write_text(json.dumps(results, indent=2, ensure_ascii=False))
+
+    print(f"\nWrote {out_path}")
+
+
+if __name__ == "__main__":
+    main()

data/finetune/receipt_examples.jsonl

@@ -0,0 +1,10 @@
+{"input": "MAHALAKSHMI MARKETING\nNo. 2816  Date: 27/5/26\nM/s. Veerabala (Mulal)\nParle  1 X 2450 = 2450\nBingo(C)  4 X 870 = 3480\nSubtotal 5930\nDiscount 612\nTotal 6542", "output": "{\"supplier\": \"Mahalakshmi Marketing\", \"invoice_no\": \"2816\", \"date\": \"2026-05-27\", \"items\": [{\"product_raw\": \"Parle\", \"qty_cases\": 1, \"qty_units\": 1, \"unit_cost\": 2450.0, \"total\": 2450.0}, {\"product_raw\": \"Bingo(C)\", \"qty_cases\": 4, \"qty_units\": 4, \"unit_cost\": 870.0, \"total\": 3480.0}], \"subtotal\": 5930.0, \"discount\": 612.0, \"gst\": 0.0, \"net_total\": 6542.0}"}
+{"input": "SRI VENKATESHWARA MARKETING\nGSTIN: 36AZLIPV6442K12M\nCUSTOMER: VEERA BHADRA WS\nBill Date: 28/05/2026\n1 PARLE-G 100G  QTY: 5/0  MRP: 10  SALE RATE: 8.625\n2 HAPPY 2 (24P)*13  QTY: 10/0  MRP: 9  SALE RATE: 4.464\nGROSS SALES: 8569.032\nSCHEMES: 168.352\nCASH DISC: 420.034\nGST: 210.017  SGST: 210.017\nNET AMOUNT: 8821.00", "output": "{\"supplier\": \"Sri Venkateshwara Marketing\", \"invoice_no\": \"SVM/26-27/2598\", \"date\": \"2026-05-28\", \"items\": [{\"product_raw\": \"PARLE-G 100G\", \"qty_cases\": 5, \"qty_units\": 120, \"unit_cost\": 8.625, \"total\": 1035.0}, {\"product_raw\": \"HAPPY 2 (24P)\", \"qty_cases\": 10, \"qty_units\": 240, \"unit_cost\": 4.464, \"total\": 1071.36}], \"subtotal\": 8569.032, \"discount\": 588.386, \"gst\": 420.034, \"net_total\": 8821.0}"}
+{"input": "Brundhna Boys - 28/05\nhne  30X28 = 840\noam  50X9.5  450\nBm   10X9.5  95\nBm   5X12    50\nTotal        1435", "output": "{\"supplier\": \"sales_note\", \"invoice_no\": null, \"date\": \"2026-05-28\", \"items\": [{\"product_raw\": \"hne\", \"qty_cases\": 0, \"qty_units\": 30, \"unit_cost\": 28.0, \"total\": 840.0}, {\"product_raw\": \"oam\", \"qty_cases\": 0, \"qty_units\": 50, \"unit_cost\": 9.5, \"total\": 450.0}, {\"product_raw\": \"Bm\", \"qty_cases\": 0, \"qty_units\": 10, \"unit_cost\": 9.5, \"total\": 95.0}, {\"product_raw\": \"Bm\", \"qty_cases\": 0, \"qty_units\": 5, \"unit_cost\": 12.0, \"total\": 50.0}], \"subtotal\": 1435.0, \"discount\": 0.0, \"gst\": 0.0, \"net_total\": 1435.0}"}
+{"input": "Mahalakshmi Marketing\nDocument Type: handwritten supplier bill\nBill No: 2816\nDate: 27/05/2026\n\nParle bulk 1 X 2450 = 2450\nBingo(C) 4 X 870 = 3480\nUnknown handwritten item 1 X 612 = 612\n\nTotal: 6542", "output": "{\"supplier\": \"Mahalakshmi Marketing\", \"invoice_no\": \"2816\", \"date\": \"2026-05-27\", \"items\": [{\"product_raw\": \"Parle bulk\", \"qty_cases\": 1, \"qty_units\": 1, \"unit_cost\": 2450.0, \"total\": 2450.0}, {\"product_raw\": \"Bingo(C)\", \"qty_cases\": 4, \"qty_units\": 4, \"unit_cost\": 870.0, \"total\": 3480.0}, {\"product_raw\": \"Unknown handwritten item\", \"qty_cases\": 0, \"qty_units\": 1, \"unit_cost\": 612.0, \"total\": 612.0, \"needs_review\": true}], \"subtotal\": 6542.0, \"discount\": 0.0, \"gst\": 0.0, \"net_total\": 6542.0}"}
+{"input": "Brundavan Buns\nDocument Type: handwritten tally note\nDate: 28/05\n\nItem one 30 X 28 = 840\nOBM 50 X 9.5 = 475\nBun 10 X 9.5 = 95\nBun 5 X 10 = 50\n\nTotal: 1435", "output": "{\"supplier\": \"Brundavan Buns\", \"invoice_no\": null, \"date\": \"2026-05-28\", \"items\": [{\"product_raw\": \"Item one\", \"qty_cases\": 0, \"qty_units\": 30, \"unit_cost\": 28.0, \"total\": 840.0}, {\"product_raw\": \"OBM\", \"qty_cases\": 0, \"qty_units\": 50, \"unit_cost\": 9.5, \"total\": 475.0}, {\"product_raw\": \"Bun\", \"qty_cases\": 0, \"qty_units\": 10, \"unit_cost\": 9.5, \"total\": 95.0}, {\"product_raw\": \"Bun\", \"qty_cases\": 0, \"qty_units\": 5, \"unit_cost\": 10.0, \"total\": 50.0}], \"subtotal\": 1460.0, \"discount\": 25.0, \"gst\": 0.0, \"net_total\": 1435.0}"}
+{"input": "Sri Venkateshwara Marketing\nDocument Type: printed tax invoice\nInvoice No: 6\nDate: 28/05/2026\n\nPARLE-G 60GM RS.72P | 5/0 | MRP 10.00 | RATE 8.625 | GST 5% | NET 3105.000\nHAPPY HAPPY 27.5G(24P)*13 | 10/0 | MRP 5.00 | RATE 4.464 | GST 5% | NET 5715.710\n\nGross Sales: 8759.032\nCGST: 210.017\nSGST: 210.017\nNet Amount: 8821.00", "output": "{\"supplier\": \"Sri Venkateshwara Marketing\", \"invoice_no\": \"6\", \"date\": \"2026-05-28\", \"items\": [{\"product_raw\": \"PARLE-G 60GM RS.72P\", \"qty_cases\": 5, \"qty_units\": 0, \"unit_cost\": 8.625, \"total\": 3105.0}, {\"product_raw\": \"HAPPY HAPPY 27.5G(24P)*13\", \"qty_cases\": 10, \"qty_units\": 0, \"unit_cost\": 4.464, \"total\": 5715.71}], \"subtotal\": 8759.032, \"discount\": 0.0, \"gst\": 420.034, \"net_total\": 8821.0}"}
+{"input": "MAHALAKSHMI MARKETING\nNo. 3105  Date: 3/6/26\nM/s. Veerabhadra WS\nBingo(C)  3 X 870 = 2610\nParle bulk  2 X 2450 = 4900\nHappy Happy  1 X 960 = 960\nSubtotal 8470\nDiscount 847\nTotal 7623", "output": "{\"supplier\": \"Mahalakshmi Marketing\", \"invoice_no\": \"3105\", \"date\": \"2026-06-03\", \"items\": [{\"product_raw\": \"Bingo(C)\", \"qty_cases\": 3, \"qty_units\": 3, \"unit_cost\": 870.0, \"total\": 2610.0}, {\"product_raw\": \"Parle bulk\", \"qty_cases\": 2, \"qty_units\": 2, \"unit_cost\": 2450.0, \"total\": 4900.0}, {\"product_raw\": \"Happy Happy\", \"qty_cases\": 1, \"qty_units\": 1, \"unit_cost\": 960.0, \"total\": 960.0}], \"subtotal\": 8470.0, \"discount\": 847.0, \"gst\": 0.0, \"net_total\": 7623.0}"}
+{"input": "VIKRAM AGENCIES\nInvoice: VA-2026-0445\nDate: 07-06-2026\nPARTY: VEERABHADRA STORES\n\n1  Parle-G 250g    QTY 4  RATE 180  AMT 720\n2  Bourbon Biscuit  QTY 6  RATE 105  AMT 630\n3  Monaco Salted    QTY 3  RATE 220  AMT 660\n\nGross: 2010\nDisc: 201\nNet: 1809", "output": "{\"supplier\": \"Vikram Agencies\", \"invoice_no\": \"VA-2026-0445\", \"date\": \"2026-06-07\", \"items\": [{\"product_raw\": \"Parle-G 250g\", \"qty_cases\": 0, \"qty_units\": 4, \"unit_cost\": 180.0, \"total\": 720.0}, {\"product_raw\": \"Bourbon Biscuit\", \"qty_cases\": 0, \"qty_units\": 6, \"unit_cost\": 105.0, \"total\": 630.0}, {\"product_raw\": \"Monaco Salted\", \"qty_cases\": 0, \"qty_units\": 3, \"unit_cost\": 220.0, \"total\": 660.0}], \"subtotal\": 2010.0, \"discount\": 201.0, \"gst\": 0.0, \"net_total\": 1809.0}"}
+{"input": "KRISHNA GENERAL STORES\nBill No: KGS/157\nDate: 08/06/2026\nCustomer: Veerabhadra\n\nParle Monaco 200g   5 pkt  @75   375\nKrack Jack Biscuit  4 pkt  @60   240\nHide & Seek Choco   3 pkt  @95   285\nSunfeast YiPPee     6 pkt  @40   240\n\nSub Total: 1140\nDisc @ 5%: 57\nNet Payable: 1083", "output": "{\"supplier\": \"Krishna General Stores\", \"invoice_no\": \"KGS/157\", \"date\": \"2026-06-08\", \"items\": [{\"product_raw\": \"Parle Monaco 200g\", \"qty_cases\": 0, \"qty_units\": 5, \"unit_cost\": 75.0, \"total\": 375.0}, {\"product_raw\": \"Krack Jack Biscuit\", \"qty_cases\": 0, \"qty_units\": 4, \"unit_cost\": 60.0, \"total\": 240.0}, {\"product_raw\": \"Hide & Seek Choco\", \"qty_cases\": 0, \"qty_units\": 3, \"unit_cost\": 95.0, \"total\": 285.0}, {\"product_raw\": \"Sunfeast YiPPee\", \"qty_cases\": 0, \"qty_units\": 6, \"unit_cost\": 40.0, \"total\": 240.0}], \"subtotal\": 1140.0, \"discount\": 57.0, \"gst\": 0.0, \"net_total\": 1083.0}"}
+{"input": "Brundavan - 10/6\npav  40X8 = 320\nbrd  25X32 = 800\nbns  15X35 = 525\ncake slc  10X45 = 450\nTTl  2095", "output": "{\"supplier\": \"Brundavan Buns\", \"invoice_no\": null, \"date\": \"2026-06-10\", \"items\": [{\"product_raw\": \"pav\", \"qty_cases\": 0, \"qty_units\": 40, \"unit_cost\": 8.0, \"total\": 320.0}, {\"product_raw\": \"brd\", \"qty_cases\": 0, \"qty_units\": 25, \"unit_cost\": 32.0, \"total\": 800.0}, {\"product_raw\": \"bns\", \"qty_cases\": 0, \"qty_units\": 15, \"unit_cost\": 35.0, \"total\": 525.0}, {\"product_raw\": \"cake slc\", \"qty_cases\": 0, \"qty_units\": 10, \"unit_cost\": 45.0, \"total\": 450.0}], \"subtotal\": 2095.0, \"discount\": 0.0, \"gst\": 0.0, \"net_total\": 2095.0}"}

docs/deployment_setup.md

@@ -0,0 +1,269 @@
+# Deployment Setup: Modal → HF Space
+
+This guide walks through deploying the three Modal model services and wiring
+their endpoint URLs into the public Hugging Face Space as secrets.
+
+---
+
+## What gets deployed
+
+| Service | Model | Env var | App name |
+|---------|-------|---------|----------|
+| Receipt OCR | MiniCPM-V 4.6 | `MODAL_RECEIPT_ENDPOINT` | `dukaan-saathi-receipt-vlm` |
+| Speech ASR | Distil-Whisper small | `MODAL_SPEECH_ENDPOINT` | `dukaan-saathi-speech-asr` |
+| Voice NLU | Qwen2.5-1.5B-Instruct | `MODAL_NLU_ENDPOINT` | `dukaan-saathi-command-nlu` |
+
+All three are optional — the app falls back to deterministic parsers when any
+endpoint is missing. Deploy whichever you want active on the Space.
+
+---
+
+## Part 1 — Prerequisites
+
+### 1.1 Modal account and CLI
+
+Create a free Modal account at https://modal.com if you do not have one.
+
+Install the Modal CLI and log in:
+
+```bash
+uv add modal                  # adds to this project's venv
+uv run modal setup            # opens a browser to authenticate
+```
+
+After `modal setup` completes, verify you are logged in:
+
+```bash
+uv run modal token show
+```
+
+You should see your workspace name (e.g., `zappandy`).
+
+### 1.2 Hugging Face account
+
+You need a Hugging Face account with write access to the Space at
+`https://huggingface.co/spaces/Zappandy/Kirana_AI`. If this is your Space
+you already have access.
+
+---
+
+## Part 2 — Deploy Modal services
+
+Run each deploy command from the project root. Each command:
+
+1. Deploys (or re-deploys) the Modal app
+2. Fetches the generated endpoint URL from Modal
+3. Writes it to your local `.env` file
+
+### 2.1 Receipt image OCR (MiniCPM-V)
+
+```bash
+scripts/modal_deploy.sh modal_apps/receipt_vlm_service.py
+```
+
+When done, `.env` will contain:
+
+```text
+MODAL_RECEIPT_ENDPOINT=https://<workspace>--dukaan-saathi-receipt-vlm-api.modal.run/extract
+```
+
+Verify it is responding (replace with your actual URL from `.env`):
+
+```bash
+source scripts/_env.sh
+curl "${MODAL_RECEIPT_ENDPOINT%/extract}/health"
+```
+
+Expected response:
+
+```json
+{"status": "ok", "model": "openbmb/MiniCPM-V-2_6"}
+```
+
+First call may take 30–60 seconds while the GPU container starts. Subsequent
+calls within the `scaledown_window` are fast.
+
+### 2.2 Speech transcription (Distil-Whisper)
+
+```bash
+scripts/modal_deploy.sh modal_apps/speech_asr_service.py
+```
+
+When done, `.env` will contain:
+
+```text
+MODAL_SPEECH_ENDPOINT=https://<workspace>--speech-transcribe.modal.run
+```
+
+Verify:
+
+```bash
+source scripts/_env.sh
+SPEECH_HEALTH="${MODAL_SPEECH_ENDPOINT/speech-transcribe/speech-health}"
+curl "$SPEECH_HEALTH"
+```
+
+Expected:
+
+```json
+{"status": "ok", "model": "distil-whisper/distil-small.en"}
+```
+
+### 2.3 Voice command NLU (Qwen2.5-1.5B-Instruct)
+
+```bash
+scripts/modal_deploy.sh modal_apps/command_nlu_service.py
+```
+
+When done, `.env` will contain:
+
+```text
+MODAL_NLU_ENDPOINT=https://<workspace>--nlu-extract.modal.run
+```
+
+Verify:
+
+```bash
+source scripts/_env.sh
+curl -s -X POST "$MODAL_NLU_ENDPOINT" \
+  -H "Content-Type: application/json" \
+  -d '{"command": "add Bun 12"}' | python3 -m json.tool
+```
+
+Expected:
+
+```json
+{
+  "intent": "add_stock",
+  "product_name": "Bun",
+  "quantity": 12,
+  "unit": null,
+  "confidence": "high",
+  "model": "Qwen/Qwen2.5-1.5B-Instruct"
+}
+```
+
+---
+
+## Part 3 — Add secrets to the HF Space
+
+The HF Space container does not read your local `.env` file. You must add each
+endpoint URL as a Space secret through the Hugging Face web UI.
+
+### 3.1 Open Space settings
+
+1. Go to https://huggingface.co/spaces/Zappandy/Kirana_AI
+2. Click the **Settings** tab (top of the Space page)
+3. Scroll down to **Variables and secrets**
+
+### 3.2 Add each secret
+
+Click **New secret** for each of the following. Use the exact variable names
+below — the app reads these from the environment at runtime.
+
+| Secret name | Value |
+|-------------|-------|
+| `MODAL_RECEIPT_ENDPOINT` | the URL written to `.env` in step 2.1 |
+| `MODAL_SPEECH_ENDPOINT` | the URL written to `.env` in step 2.2 |
+| `MODAL_NLU_ENDPOINT` | the URL written to `.env` in step 2.3 |
+| `HF_TOKEN` | your HF write token (only needed if `HF_RECEIPT_MODEL_REPO` is private) |
+| `HF_RECEIPT_MODEL_REPO` | e.g. `Zappandy/dukaan-saathi-receipt-lora` |
+
+Secrets are encrypted and only visible to the Space runtime — not to other
+users or in the Space logs.
+
+**Do not add** `DB_PATH` unless you have enabled persistent storage on the
+Space. Without persistent storage, leave it unset and the DB stays
+runtime-local (resets on restart).
+
+### 3.3 Restart the Space
+
+After adding secrets, click **Factory reset** or wait for the Space to rebuild
+on its own. The new environment variables take effect on the next container
+start.
+
+To force an immediate rebuild, push any change to the Space remote:
+
+```bash
+git checkout --orphan _hf_tmp
+git add -A
+git commit -m "trigger rebuild"
+git push space HEAD:main --force
+git checkout main
+git branch -D _hf_tmp
+```
+
+---
+
+## Part 4 — Verify end-to-end on the Space
+
+After the Space rebuilds:
+
+1. Open the Space URL and wait for the app to finish loading
+2. Go to **Voice** tab → type `add Bun 12` → click **Parse for approval**
+   - The agent reasoning panel should show NLU steps if `MODAL_NLU_ENDPOINT` is set
+3. Go to **Bill Desk** → upload a receipt photo
+   - Cold start message appears while MiniCPM-V loads (~30 s first time)
+   - Editable rows appear after extraction
+4. Go to **Voice** → click **Transcribe with Modal** and upload a `.wav` file
+   - Transcript fills in automatically
+
+If any Modal service times out or returns an error, the app falls back to the
+deterministic parser and shows a trace message explaining the fallback.
+
+---
+
+## Part 5 — Managing costs
+
+Modal charges only for GPU time. Each service has a `scaledown_window=300` (5
+minutes) — after 5 minutes of inactivity the container stops and you stop being
+charged.
+
+To stop all services immediately:
+
+```bash
+uv run modal app stop dukaan-saathi-receipt-vlm || true
+uv run modal app stop dukaan-saathi-speech-asr  || true
+uv run modal app stop dukaan-saathi-command-nlu || true
+uv run modal app list
+```
+
+Look for `Tasks 0` in the output to confirm containers are stopped.
+
+To redeploy after stopping (same commands as Part 2):
+
+```bash
+scripts/modal_deploy.sh modal_apps/receipt_vlm_service.py
+scripts/modal_deploy.sh modal_apps/speech_asr_service.py
+scripts/modal_deploy.sh modal_apps/command_nlu_service.py
+```
+
+The endpoint URLs do not change between deploys, so no HF Space secret update
+is needed unless you deploy under a different workspace.
+
+---
+
+## Troubleshooting
+
+**`modal setup` hangs or fails**
+Run `uv run modal token show`. If it shows no token, re-run `uv run modal setup`
+and complete the browser authentication flow.
+
+**Deploy command fails with "app not found"**
+Check you are in the project root (`ls modal_apps/` should list the service
+files) and that `uv` has Modal installed (`uv run modal --version`).
+
+**HF Space shows no NLU trace after rebuild**
+Confirm the secret name is exactly `MODAL_NLU_ENDPOINT` (no spaces, correct
+case). Check the Space logs (Settings → Logs) for any startup errors.
+
+**`curl` health check returns 502 or times out**
+The container is cold-starting. Wait 30–60 seconds and retry. Modal T4 GPU
+containers take longer on first cold start because the model weights are
+downloaded into the container volume.
+
+**Endpoint URL has extra `/extract` suffix**
+The `write_modal_endpoint.py` script derives the URL from the deployed function.
+If it appends a route that the endpoint doesn't use, edit `.env` and the HF
+Space secret to remove the suffix. Test the corrected URL with `curl` before
+updating the secret.

docs/plan_half_baked_features.md

@@ -0,0 +1,97 @@
+# Audit: Remaining Feature Gaps For Hugging Face Spaces
+
+Audit date: 2026-06-14. This document is now a status note for the current
+FastAPI/static app running toward a Hugging Face Spaces deployment.
+
+## Current HF Spaces Runtime Assumptions
+
+- Public demo runtime is the Docker Space defined by `README.md`.
+- The app should default to `RECEIPT_BACKEND=hf_inference` for receipt text
+  parsing with `HF_RECEIPT_MODEL_REPO` set in Space secrets/settings.
+- Receipt image OCR and speech transcription are optional Modal-hosted services
+  called through thin HTTP clients:
+  - `MODAL_RECEIPT_ENDPOINT`
+  - `MODAL_SPEECH_ENDPOINT` or `SPEECH_ASR_ENDPOINT`
+- ReAct is an app-side tool router. It is not a model; it calls tools, and
+  model-backed tools may call Modal, HF Inference, or local llama.cpp.
+- Inventory writes remain owner-approved. Model output can only create editable
+  receipt rows or pending stock actions.
+- SQLite state on HF Spaces is ephemeral unless persistent storage is enabled
+  and `DB_PATH` points at `/data/...`.
+
+## Completed Since Original Audit
+
+| Feature | Current status |
+|---------|----------------|
+| ReAct photo path | `POST /api/photo` uses `ReceiptReActAgent` first, with direct fallback. |
+| ReAct voice command path | `_h_voice_command` routes through `run_command_parse`, which uses ReAct first. |
+| Voice owner approval | Voice parse creates a pending action; `_h_voice_apply` writes only after explicit approval. |
+| Dashboard Add to order | `_h_add_to_order` inserts a pending order row. |
+| Dashboard Offer to route | `_h_offer_to_route` records a pending liquidation/order intent. |
+| Dashboard insights | `run_analysis` now builds deterministic inventory/expiry prose from DB state. |
+| Float quantity truncation | Immediate rounding fix added in `kirana_db.py` and `dukaan_saathi/storage.py`. |
+| Receipt product matching | Parsed receipt rows are post-matched against existing inventory before display. |
+| Orders Mark received | Approved orders can be marked received and stock is updated through the normal owner action. |
+| Analytics date range | Analytics supports `7d`, `30d`, and `90d` seller windows. |
+| Modal cold-start UX | UI copy explains cold starts; `/api/warm` fire-and-forgets Modal warm pings. |
+| Safety tests | `smoke_tests/test_custom_app_safety.py` covers key approval gates and order transitions. |
+
+## Still Worth Doing
+
+### 1. Canonical inventory write boundary
+
+The documented ideal is:
+
+```text
+owner approval -> dukaan_saathi/services/inventory.py -> storage ledger
+```
+
+The current custom FastAPI path still writes through `kirana_db.py`, which is a
+compatibility adapter over the Dukaan storage layer. It preserves the approval
+gate, but future code should either migrate these writes into
+`dukaan_saathi/services/inventory.py` or keep the adapter boundary explicitly
+documented.
+
+### 2. Fractional stock follow-through
+
+`stock_ledger.delta` now migrates to `REAL`, so fractional stock is supported at
+the storage layer. Keep checking UI formatting, reorder math, and tests whenever
+quantity semantics change.
+
+### 3. HF Spaces persistence decision
+
+For a hackathon demo, ephemeral SQLite may be acceptable. For a realistic public
+Space, decide whether to:
+
+- keep session-local state and reset on rebuild, or
+- enable HF persistent storage and set `DB_PATH=/data/dukaan.db`.
+
+Document the chosen behavior in the Space README/settings.
+
+### 4. Modal endpoint health and warmup
+
+`/api/warm` currently sends non-blocking `HEAD` requests. If Modal services
+expose dedicated health routes, use those instead. Keep page load non-blocking
+and avoid surfacing warmup failures as user-facing errors.
+
+### 5. Model endpoint test coverage
+
+Add mocked tests for:
+
+- Modal OCR success and malformed responses.
+- Modal speech success and failures.
+- HF Inference receipt parser success and malformed JSON fallback.
+- Modal receipt LLM success and malformed JSON fallback.
+
+### 6. Voice NLU quality
+
+The current parser is still deterministic/keyword-oriented. For stronger
+Telugu/code-mixed commands on Spaces, add an optional HF Inference voice-NLU
+path with deterministic fallback and the same owner approval gate.
+
+## Lower Priority Ideas
+
+- LLM-generated dashboard prose after deterministic insights are stable.
+- Expanded receipt fine-tuning data and benchmark reports.
+- Liquidation-agent routing through WhatsApp/SMS after the order-intent stub is
+  enough for the demo.

docs/plan_react_agent.md

@@ -0,0 +1,110 @@
+# ReAct Agent Status For Hugging Face Spaces
+
+This document describes the current role of the lean ReAct router in the
+HF Spaces-oriented runtime.
+
+## Role
+
+ReAct is the app-side orchestrator, not the model.
+
+It records:
+
+```text
+Thought -> Action -> Observation
+```
+
+and chooses the smallest safe tool chain for a task. The tools may call
+deterministic Python, Hugging Face Inference, Modal endpoints, or local
+llama.cpp depending on configuration.
+
+ReAct must never write inventory. It returns editable rows, pending actions, and
+trace lines. Owner approval remains the write boundary.
+
+## Current Live Paths
+
+### Receipt photo
+
+```text
+POST /api/photo
+-> ReceiptReActAgent.extract_receipt_image
+-> extract_text_from_receipt_image tool
+   -> dukaan_saathi/integrations/modal_receipt.py
+   -> MODAL_RECEIPT_ENDPOINT
+   -> modal_apps/receipt_vlm_service.py
+-> parse_receipt_text_tool
+   -> hf_inference / modal_llm / llamacpp / deterministic
+-> post-match rows to inventory catalog
+-> editable receipt rows in UI
+-> owner applies row
+-> inventory write
+```
+
+For HF Spaces, the preferred receipt text parser backend is
+`RECEIPT_BACKEND=hf_inference` with `HF_RECEIPT_MODEL_REPO` set.
+
+### Voice command
+
+```text
+POST /api/speech
+-> Modal ASR endpoint
+-> transcript
+-> _h_voice_command
+-> run_command_parse
+-> ReceiptReActAgent.parse_stock_command
+-> pending stock action
+-> owner clicks Approve stock change
+-> _h_voice_apply
+-> inventory write
+```
+
+The ASR step is separate from ReAct. ReAct starts after text exists.
+
+### Receipt text
+
+The Gradio path already routes text parsing through the ReAct agent with
+configured fallback behavior. The custom FastAPI path uses ReAct for photo OCR
+flows, then the parser tool for receipt text.
+
+## Tool Responsibilities
+
+- `extract_text_from_receipt_image`: calls the Modal OCR HTTP client.
+- `parse_receipt_text_tool`: respects `RECEIPT_BACKEND`.
+- `parse_stock_command_tool`: uses the deterministic stock parser today.
+- `draft_reorder_tool`: reads inventory and drafts reorder suggestions.
+- `propose_inventory_update`: stores a pending proposal only; no DB write.
+
+Modal/HF/llama.cpp inference belongs behind tools or integration clients, not
+inside UI handlers.
+
+## Completed
+
+- Custom FastAPI photo path calls `ReceiptReActAgent` first.
+- Custom FastAPI voice command path calls `ReceiptReActAgent` first.
+- Voice trace is shown in the parsed voice result panel.
+- Receipt rows are returned as editable rows and post-matched against inventory.
+- Voice actions are pending until owner approval.
+- Direct fallback paths remain for robustness if ReAct or a configured backend
+  fails.
+
+## Remaining Cleanup
+
+### 1. Heavier ToolCallingAgent
+
+`dukaan_saathi/agent/agent.py` still contains the heavier smolagents
+`ToolCallingAgent`. For HF Spaces, do not make this primary unless there is a
+clear demo need. If revived, it should use an HF-compatible model client and
+must preserve the same owner approval gate.
+
+### 2. Multi-step agent UX
+
+Do not add broad agent chat unless it has a concrete user workflow. The current
+demo benefits more from reliable receipt, voice, reorder, and approval flows
+than from open-ended agent chat.
+
+## HF Spaces Guidance
+
+- Prefer `hf_inference` for receipt text parsing in the public Space.
+- Use Modal for OCR and ASR only when endpoint env vars are configured.
+- Keep `/api/warm` best-effort and non-blocking.
+- Keep deterministic parser fallbacks for tests and graceful degradation.
+- Never require local llama.cpp in the Space runtime.

docs/plan_voice_command_agent.md

@@ -0,0 +1,120 @@
+# Voice Command Status For Hugging Face Spaces
+
+This document tracks the current voice command pipeline and the remaining work
+that matters for a public Hugging Face Space.
+
+## Current Pipeline
+
+Voice has two separate stages:
+
+```text
+audio
+-> POST /api/speech
+-> dukaan_saathi/integrations/speech.py
+-> MODAL_SPEECH_ENDPOINT or SPEECH_ASR_ENDPOINT
+-> transcript
+-> owner reviews/edits text
+-> _h_voice_command
+-> ReAct stock command tool
+-> pending stock action
+-> owner approves
+-> _h_voice_apply
+-> inventory write
+```
+
+The Modal ASR endpoint does speech-to-text only. ReAct starts after text exists.
+
+## Completed
+
+- Field names are normalized to the UI shape:
+  - `action`
+  - `product`
+  - `product_id`
+  - `quantity`
+  - `unit`
+  - `confidence`
+  - `trace`
+- `add_stock` and `set_stock` are both handled.
+- The parser uses the returned `product_id`; it does not re-match blindly.
+- Parsed commands no longer auto-apply.
+- The UI shows a pending parsed action and requires **Approve stock change**.
+- `_h_voice_apply` is the only custom FastAPI voice handler that writes stock.
+- Modal cold-start copy is visible and `/api/warm` runs best-effort on page load.
+- Safety tests cover parse-without-write and apply-with-write.
+
+## Current Limitations
+
+| Gap | Impact on HF Space |
+|-----|--------------------|
+| Deterministic command parser | Reliable for seeded/demo examples, weaker for natural Telugu/code-mix. |
+| Limited product aliases | Commands such as "tamatar" need aliases or NLU to map to seeded products. |
+| Modal ASR cold start | First request may take 10-30 seconds unless endpoint is warm. |
+| Ephemeral SQLite | Approved stock changes may reset on Space rebuild unless persistent storage is enabled. |
+
+## Recommended Next Steps
+
+### 1. Keep deterministic parser as the default
+
+For the hackathon/public Space, deterministic parsing is safer and easier to
+debug. Continue using seeded examples that map to inventory:
+
+```text
+add Bun 12
+set OBM stock 5
+add Bingo 4
+Happy Happy low
+```
+
+Do not bypass owner approval to make voice feel more automatic.
+
+### 2. Add optional HF Inference voice NLU
+
+If Telugu/code-mixed commands are important for the Space demo, add an optional
+HF Inference path behind a feature flag:
+
+```text
+VOICE_LLM_BACKEND=keyword | hf_inference
+HF_VOICE_NLU_MODEL_REPO=...
+```
+
+The output contract should stay the same:
+
+```json
+{
+  "action": "add_stock|set_stock|mark_out_of_stock|unknown",
+  "product_name": "string or null",
+  "product_id": "string or null",
+  "quantity": "number or null",
+  "unit": "string or null",
+  "confidence": "low|medium|high"
+}
+```
+
+Fallback to the deterministic parser on malformed JSON, low confidence, missing
+product match, timeout, or missing env vars.
+
+### 3. Improve aliases before adding broad NLU
+
+For a constrained demo, aliases often beat another model call:
+
+- Add common transliterations for seeded products.
+- Keep examples aligned to seeded inventory.
+- Add parser tests for each new alias.
+
+### 4. Preserve the approval gate
+
+Any voice NLU path must still produce only a pending action:
+
+```text
+model/parser output -> pending action -> owner approval -> inventory write
+```
+
+No model, parser, or ReAct step may write inventory directly.
+
+## Tests To Keep
+
+- Voice parse does not change stock.
+- Voice apply changes stock.
+- Unknown/low-confidence commands do not expose an approval button.
+- Malformed model output falls back or returns `unknown`.
+- Missing Modal ASR endpoint produces a useful UI error, not a crash.

dukaan_saathi/agent/agent.py

@@ -0,0 +1,96 @@
+"""
+agent.py — legacy smolagents ToolCallingAgent for Dukaan Saathi.
+
+The active Gradio path uses dukaan_saathi.agent.react_agent. This module is kept
+as an optional heavier agent implementation for experiments with model-driven
+tool calling.
+
+The agent proposes actions but never writes to the inventory database directly —
+all writes go through the Gradio approval step (approve_command_action /
+approve_receipt_rows called outside the agent loop).
+"""
+
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+
+from smolagents import ToolCallingAgent, OpenAIServerModel
+
+from dukaan_saathi import config
+from dukaan_saathi.agent.tools import (
+    get_inventory_snapshot,
+    parse_stock_command_tool,
+    extract_text_from_receipt_image,
+    parse_receipt_text_tool,
+    apply_correction_to_receipt,
+    transcribe_audio_tool,
+    draft_reorder_tool,
+    propose_inventory_update,
+)
+
+logger = logging.getLogger(__name__)
+
+SYSTEM_PROMPT = """You are Dukaan Saathi, an inventory assistant for a Telugu-speaking kirana (convenience store) owner.
+
+Your job:
+1. Understand the owner's request (stock commands in Telugu/English, receipt photos, reorder drafts).
+2. Call the appropriate tools to parse and structure the data.
+3. Always call propose_inventory_update before finishing — the owner must approve before any changes are written.
+
+Rules:
+- Never write to the inventory database directly. Only propose.
+- If a stock command is unclear, ask for clarification rather than guessing.
+- For receipt parsing: first extract text with extract_text_from_receipt_image, then parse with parse_receipt_text_tool.
+- Respond concisely in English (the owner reads English labels even if they speak Telugu).
+"""
+
+
+def _build_agent() -> ToolCallingAgent:
+    model = OpenAIServerModel(
+        model_id="llama-3.2-3b",
+        api_base=f"{config.LLAMACPP_HOST}:8080/v1",
+        api_key="none",
+    )
+    return ToolCallingAgent(
+        tools=[
+            get_inventory_snapshot,
+            parse_stock_command_tool,
+            extract_text_from_receipt_image,
+            parse_receipt_text_tool,
+            apply_correction_to_receipt,
+            transcribe_audio_tool,
+            draft_reorder_tool,
+            propose_inventory_update,
+        ],
+        model=model,
+        system_prompt=SYSTEM_PROMPT,
+        max_steps=6,
+    )
+
+
+# Module-level agent instance — created once at import.
+# Re-create if the llama.cpp server wasn't up on first import.
+_agent: ToolCallingAgent | None = None
+
+
+def get_agent() -> ToolCallingAgent:
+    """Return the module-level agent, building it on first call."""
+    global _agent
+    if _agent is None:
+        try:
+            _agent = _build_agent()
+        except Exception as exc:
+            logger.warning(f"Could not build agent (llama.cpp not running?): {exc}")
+            raise
+    return _agent
+
+
+def format_agent_trace(agent: ToolCallingAgent) -> str:
+    """Format agent.logs into a human-readable trace string for the UI."""
+    lines: list[str] = []
+    for step in agent.logs:
+        step_str = str(step)
+        if step_str.strip():
+            lines.append(step_str)
+    return "\n\n".join(lines) if lines else "(no agent trace)"

dukaan_saathi/agent/react_agent.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from dukaan_saathi.agent import tools
+
+
+@dataclass
+class ReactResult:
+    trace: list[str]
+    action: dict[str, Any] | None = None
+    receipt_rows: list[dict[str, Any]] | None = None
+    raw_text: str | None = None
+
+
+def _preview(value: Any, limit: int = 240) -> str:
+    text = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False)
+    if len(text) <= limit:
+        return text
+    return f"{text[:limit]}..."
+
+
+class ReceiptReActAgent:
+    """
+    Lean ReAct-style router for the small Dukaan Saathi task set.
+
+    It chooses from existing safe tools, records Thought/Action/Observation
+    traces, and never writes inventory. Approval functions remain outside the
+    agent path.
+    """
+
+    def _trace(self) -> list[str]:
+        tools.reset_state()
+        return ["Thought: Identify the user workflow and select the smallest safe tool chain."]
+
+    def parse_stock_command(self, command: str) -> ReactResult:
+        trace = self._trace()
+        trace.append("Thought: This is a stock command, so parse it into a pending owner action.")
+        trace.append("Action: parse_stock_command_tool")
+        output = tools.parse_stock_command_tool(command=command)
+        action = tools.get_last_action()
+        trace.append(f"Observation: {_preview(output)}")
+        trace.append("Thought: Return the proposed action for owner approval; do not write inventory.")
+        return ReactResult(trace=trace, action=action)
+
+    def parse_receipt_text(self, raw_text: str) -> ReactResult:
+        trace = self._trace()
+        trace.append("Thought: This is receipt text, so parse it into editable receipt rows.")
+        trace.append("Action: parse_receipt_text_tool")
+        output = tools.parse_receipt_text_tool(raw_text=raw_text)
+        rows = tools.get_last_receipt_rows() or []
+        trace.append(f"Observation: {_preview(output)}")
+        trace.append("Thought: Return editable rows; owner approval is required before stock changes.")
+        return ReactResult(trace=trace, receipt_rows=rows)
+
+    def extract_receipt_image(self, image_path: str) -> ReactResult:
+        trace = self._trace()
+        trace.append("Thought: This is a receipt image, so extract OCR text before parsing rows.")
+        trace.append("Action: extract_text_from_receipt_image")
+        raw_text = tools.extract_text_from_receipt_image(image_path=image_path)
+        trace.append(f"Observation: {_preview(raw_text)}")
+
+        if not raw_text.strip():
+            trace.append("Thought: No OCR text was returned; caller should use the image fallback path.")
+            return ReactResult(trace=trace, raw_text=raw_text, receipt_rows=[])
+
+        trace.append("Thought: OCR text is available, so parse it into editable receipt rows.")
+        trace.append("Action: parse_receipt_text_tool")
+        output = tools.parse_receipt_text_tool(raw_text=raw_text)
+        rows = tools.get_last_receipt_rows() or []
+        trace.append(f"Observation: {_preview(output)}")
+        trace.append("Thought: Return editable rows; owner approval is required before stock changes.")
+        return ReactResult(trace=trace, raw_text=raw_text, receipt_rows=rows)
+
+
+_react_agent: ReceiptReActAgent | None = None
+
+
+def get_react_agent() -> ReceiptReActAgent:
+    global _react_agent
+    if _react_agent is None:
+        _react_agent = ReceiptReActAgent()
+    return _react_agent

dukaan_saathi/agent/tools.py

@@ -0,0 +1,191 @@
+"""
+tools.py — smolagents @tool definitions for Dukaan Saathi.
+
+Each tool wraps an existing service/parser function and returns a JSON string
+so the active ReAct router or optional ToolCallingAgent can reason over results.
+
+Results are also stored in _state so Gradio handlers can access structured data
+after agent.run() without having to parse agent.logs internals.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from smolagents import tool
+
+# Shared session state — stores last structured result from each tool.
+# Single-user app (kirana owner's phone), so no concurrency concern.
+_state: dict[str, Any] = {
+    "last_action": None,
+    "last_proposal": None,
+    "last_receipt_rows": None,
+    "last_raw_text": None,
+}
+
+
+def reset_state() -> None:
+    _state.update(
+        {
+            "last_action": None,
+            "last_proposal": None,
+            "last_receipt_rows": None,
+            "last_raw_text": None,
+        }
+    )
+
+
+def get_last_action() -> dict | None:
+    return _state.get("last_action")
+
+
+def get_last_proposal() -> Any:
+    return _state.get("last_proposal")
+
+
+def get_last_receipt_rows() -> list[dict] | None:
+    return _state.get("last_receipt_rows")
+
+
+def get_last_raw_text() -> str | None:
+    return _state.get("last_raw_text")
+
+
+# ── Read-only tools ────────────────────────────────────────────────────────────
+
+@tool
+def get_inventory_snapshot() -> str:
+    """Returns the current inventory of the kirana store as a JSON string.
+
+    Use this before proposing any inventory changes.
+    """
+    from dukaan_saathi.storage import get_inventory
+    items = get_inventory()
+    return json.dumps(items)
+
+
+@tool
+def draft_reorder_tool() -> str:
+    """Generates a reorder purchase-order draft based on current low-stock items.
+
+    Returns a JSON list of suggested orders.
+    """
+    from dukaan_saathi.services.reorder import draft_reorder
+    rows, _ = draft_reorder()
+    return json.dumps(rows)
+
+
+# ── Parsing tools ──────────────────────────────────────────────────────────────
+
+@tool
+def parse_stock_command_tool(command: str) -> str:
+    """Parse a natural language stock command (Telugu/English code-mixed) into a
+    proposed inventory action. Input examples: "add Bun 12",
+    "set OBM stock 5", "Happy Happy low". Returns a JSON action dict.
+
+    Args:
+        command: The owner's raw stock command text.
+    """
+    from dukaan_saathi.parsers.stock_command import parse_stock_command
+    action, _ = parse_stock_command(command)
+    _state["last_action"] = action
+    return json.dumps(action)
+
+
+@tool
+def extract_text_from_receipt_image(image_path: str) -> str:
+    """Extract raw OCR text from a receipt image using MiniCPM-V 4.6 on the Modal
+    endpoint. Returns the raw pipe-separated text output from the vision model.
+    Must be followed by parse_receipt_text_tool to get structured rows.
+
+    Args:
+        image_path: Local filesystem path to the uploaded receipt image.
+    """
+    from dukaan_saathi.integrations.modal_receipt import _extract_receipt_result_with_modal
+    result = _extract_receipt_result_with_modal(image_path)
+    raw_text = result.raw_text or ""
+    _state["last_raw_text"] = raw_text
+    return raw_text
+
+
+@tool
+def parse_receipt_text_tool(raw_text: str) -> str:
+    """Parse OCR receipt text into structured line items. Uses the configured
+    receipt backend: HF Inference API, local llama.cpp, Modal-hosted LLM, or deterministic parser.
+    Returns a JSON list of row dicts with fields: product_raw,
+    matched_product_name, quantity, unit_price, total_price.
+
+    Args:
+        raw_text: Receipt OCR text or pasted receipt text to parse.
+    """
+    from dukaan_saathi import config
+    if config.RECEIPT_BACKEND == "hf_inference":
+        from dukaan_saathi.integrations.hf_inference_receipt import parse_receipt_via_hf_inference
+        rows, _ = parse_receipt_via_hf_inference(raw_text)
+    elif config.RECEIPT_BACKEND == "llamacpp":
+        from dukaan_saathi.integrations.llamacpp_receipt import parse_receipt_via_llm
+        rows, _ = parse_receipt_via_llm(raw_text)
+    elif config.RECEIPT_BACKEND == "modal_llm":
+        from dukaan_saathi.integrations.modal_receipt_llm import parse_receipt_with_modal_llm
+        rows, _ = parse_receipt_with_modal_llm(raw_text)
+    else:
+        from dukaan_saathi.parsers.receipt_text import parse_receipt_text
+        rows, _ = parse_receipt_text(raw_text)
+    _state["last_receipt_rows"] = rows
+    return json.dumps(rows)
+
+
+@tool
+def apply_correction_to_receipt(rows_json: str, correction_command: str) -> str:
+    """Apply a human correction command to receipt rows. Correction examples:
+    "first one Parle bulk, second one Bingo", "skip row 3", "row 2 quantity 10".
+    Returns updated rows as JSON.
+
+    Args:
+        rows_json: JSON array of editable receipt row dictionaries.
+        correction_command: Owner's typed correction command.
+    """
+    from dukaan_saathi.parsers.receipt_correction import apply_receipt_correction_command
+    rows = json.loads(rows_json)
+    updated_rows, _ = apply_receipt_correction_command(rows, correction_command)
+    _state["last_receipt_rows"] = updated_rows
+    return json.dumps(updated_rows)
+
+
+@tool
+def transcribe_audio_tool(audio_path: str) -> str:
+    """Transcribe a correction audio recording to text using Distil-Whisper via
+    the Modal ASR endpoint. Returns the transcription string.
+
+    Args:
+        audio_path: Local filesystem path to the audio file.
+    """
+    from dukaan_saathi.integrations.speech import transcribe_audio
+    transcript, _ = transcribe_audio(audio_path)
+    return transcript
+
+
+# ── Proposal tool (write-gate) ─────────────────────────────────────────────────
+
+@tool
+def propose_inventory_update(changes_json: str) -> str:
+    """Propose inventory changes for human review. This tool does NOT write to the
+    database — it formats the proposed changes and returns them for display.
+    The owner must click the Approve button in the UI to apply the changes.
+
+    Args:
+        changes_json: JSON object or array describing proposed inventory changes.
+    """
+    try:
+        changes = json.loads(changes_json)
+        _state["last_proposal"] = changes
+        if isinstance(changes, dict) and changes.get("status") == "pending_approval":
+            _state["last_action"] = changes
+        lines = [
+            "Proposed inventory update (pending owner approval):",
+            json.dumps(changes, indent=2, ensure_ascii=False),
+        ]
+        return "\n".join(lines)
+    except (json.JSONDecodeError, TypeError) as exc:
+        return f"Could not format proposal: {exc}\nRaw: {changes_json}"

dukaan_saathi/config.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+import os
+
+
+APP_NAME = "Dukaan Saathi"
+DB_PATH = os.getenv("DB_PATH", "data/dukaan.db")
+DATA_DIR = Path("data")
+SAMPLES_DIR = Path("samples")
+
+# Receipt parsing backend:
+# - "hf_inference" uses the fine-tuned model on Hugging Face Inference API.
+# - "llamacpp" uses local llama.cpp servers.
+# - "modal_llm" uses a Modal-hosted receipt parser endpoint.
+# - "deterministic" uses the rule-based Python parser.
+RECEIPT_BACKEND = os.getenv("RECEIPT_BACKEND", "hf_inference")
+
+# Base URL for the local llama.cpp HTTP servers (OpenAI-compatible).
+LLAMACPP_HOST = os.getenv("LLAMACPP_HOST", "http://localhost")
+
+# HF Hub model repo for the fine-tuned receipt model GGUF (used by scripts/download_models.py).
+HF_RECEIPT_MODEL_REPO = os.getenv("HF_RECEIPT_MODEL_REPO", "")
+
+# Modal endpoint for receipt text parsing with a hosted LoRA/base model.
+MODAL_RECEIPT_LLM_ENDPOINT = os.getenv("MODAL_RECEIPT_LLM_ENDPOINT", "")

dukaan_saathi/integrations/command_nlu.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import os
+
+import requests
+
+
+def extract_command_slots(command: str) -> dict | None:
+    """
+    Call the Modal NLU endpoint to extract structured slots from a raw command.
+
+    Returns a dict with keys: intent, product_name, quantity, unit, confidence, model.
+    Returns None if the endpoint is not configured, the request fails, or the
+    response cannot be parsed — callers must fall back to the deterministic parser.
+
+    Safety boundary:
+    - This only returns structured slots.
+    - It does not look up products.
+    - It does not apply inventory changes.
+    - It does not approve anything.
+    """
+    endpoint = os.getenv("MODAL_NLU_ENDPOINT", "").strip()
+    if not endpoint:
+        return None
+
+    try:
+        response = requests.post(
+            endpoint,
+            json={"command": command},
+            timeout=60,
+        )
+        response.raise_for_status()
+        slots = response.json()
+    except (requests.RequestException, ValueError):
+        return None
+
+    intent = slots.get("intent", "unknown")
+    if intent not in {"add_stock", "set_stock", "mark_low", "mark_out", "unknown"}:
+        return None
+
+    return {
+        "intent": intent,
+        "product_name": slots.get("product_name"),
+        "quantity": slots.get("quantity"),
+        "unit": slots.get("unit"),
+        "confidence": slots.get("confidence", "medium"),
+        "model": slots.get("model", "unknown"),
+    }

dukaan_saathi/integrations/hf_inference_receipt.py

@@ -0,0 +1,107 @@
+"""
+hf_inference_receipt.py — Receipt parsing via HF Inference API.
+
+Uses the fine-tuned model pushed to HF Hub after training.
+Requires no running Modal service — calls HF Serverless Inference directly.
+
+Push the model to Hub first:
+    modal run modal_apps/receipt_llm_service.py::push \\
+        --hf-repo-id summerdevlin46/dukaan-saathi-receipt-lora \\
+        --hf-token hf_...
+
+Then set HF_RECEIPT_MODEL_REPO (or rely on the default) and optionally HF_TOKEN.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from typing import Any
+
+from dukaan_saathi.storage import find_product
+
+logger = logging.getLogger(__name__)
+
+SYSTEM_PROMPT = (
+    "You are a receipt parser for an Indian convenience store. "
+    "Extract all line items from the receipt text. "
+    "Return ONLY valid JSON with this structure: "
+    '{"supplier": "...", "invoice_no": "...", "date": "YYYY-MM-DD", '
+    '"items": [{"product_raw": "...", "qty_cases": 0, "qty_units": 0, '
+    '"unit_cost": 0.0, "total": 0.0}], '
+    '"subtotal": 0.0, "discount": 0.0, "gst": 0.0, "net_total": 0.0}. '
+    "No markdown, no explanation."
+)
+
+INSTRUCTION_TEMPLATE = """### Instruction:
+{system}
+
+### Input:
+{input}
+
+### Response:
+"""
+
+
+def _item_to_row(item: dict[str, Any], supplier: str, document_type: str) -> dict[str, Any]:
+    from dukaan_saathi.integrations.llamacpp_receipt import _llm_item_to_row
+    return _llm_item_to_row(item, supplier, document_type)
+
+
+def parse_receipt_via_hf_inference(raw_text: str) -> tuple[list[dict[str, Any]], list[str]]:
+    """
+    Parse receipt OCR text using the fine-tuned model on HF Hub via Inference API.
+    Falls back to the deterministic parser only if the model repo is not configured.
+    Raises on endpoint errors so the caller sees a real failure, not silent determinism.
+    """
+    from huggingface_hub import InferenceClient
+    from dukaan_saathi.parsers.receipt_text import detect_document_type, detect_supplier
+
+    model_repo = os.getenv("HF_RECEIPT_MODEL_REPO", "").strip()
+    if not model_repo:
+        raise ValueError(
+            "HF_RECEIPT_MODEL_REPO is not set. "
+            "Push the model first: modal run modal_apps/receipt_llm_service.py::push "
+            "--hf-repo-id <repo> --hf-token <token>, "
+            "then set HF_RECEIPT_MODEL_REPO=<repo>."
+        )
+
+    trace: list[str] = [f"[hf_inference] Calling {model_repo} via HF Inference API"]
+
+    prompt = INSTRUCTION_TEMPLATE.format(system=SYSTEM_PROMPT, input=raw_text)
+    # token is only needed for private models; if the repo is public, omit it
+    token = os.getenv("HF_TOKEN", "").strip() or None
+    client = InferenceClient(token=token)
+
+    response_text = client.text_generation(
+        prompt,
+        model=model_repo,
+        max_new_tokens=768,
+        temperature=0.1,
+        do_sample=False,
+    )
+
+    response_text = response_text.strip()
+    parsed = json.loads(response_text)
+    items = parsed.get("items", [])
+    if not items:
+        raise ValueError("HF Inference API returned zero items")
+
+    supplier = parsed.get("supplier") or detect_supplier(raw_text)
+    document_type = detect_document_type(raw_text)
+
+    trace.append(f"[hf_inference] Parsed supplier: {supplier}")
+    trace.append(f"[hf_inference] Extracted {len(items)} items")
+
+    rows = []
+    for item in items:
+        row = _item_to_row(item, supplier, document_type)
+        rows.append(row)
+        if row["matched_product_name"]:
+            trace.append(f"[hf_inference] Matched '{row['product_raw']}' → {row['matched_product_name']}")
+        else:
+            trace.append(f"[hf_inference] Needs owner review: '{row['product_raw']}'")
+
+    trace.append(f"[hf_inference] {len(rows)} candidate line items")
+    return rows, trace

dukaan_saathi/integrations/hub_traces.py

@@ -0,0 +1,71 @@
+"""
+Push agent traces to a public HF dataset repo for the "Sharing is Caring"
+hackathon badge.
+
+Runs in a daemon thread — never blocks the approval flow.
+No-op when HF_TOKEN is unset.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+from datetime import datetime, timezone
+
+
+DATASET_REPO = "Zappandy/kirana-ai-agent-traces"
+
+
+def push_trace(
+    *,
+    input_type: str,
+    raw_command: str,
+    trace: list[str],
+    action: str,
+    product: str,
+    quantity: float | None,
+) -> None:
+    """Fire-and-forget: push one trace entry to the Hub dataset."""
+    token = os.getenv("HF_TOKEN", "").strip()
+    if not token:
+        return
+
+    payload = {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "input_type": input_type,
+        "raw_command": raw_command,
+        "trace": trace,
+        "action": action,
+        "product": product,
+        "quantity": quantity,
+    }
+    threading.Thread(target=_upload, args=(payload, token), daemon=True).start()
+
+
+def _upload(payload: dict, token: str) -> None:
+    try:
+        from huggingface_hub import HfApi
+
+        api = HfApi(token=token)
+
+        # Create repo on first use; no-op if it already exists.
+        api.create_repo(
+            repo_id=DATASET_REPO,
+            repo_type="dataset",
+            exist_ok=True,
+            private=False,
+        )
+
+        ts = payload["timestamp"].replace(":", "-").replace(".", "-")
+        path_in_repo = f"traces/{ts}.json"
+
+        api.upload_file(
+            path_or_fileobj=json.dumps(payload, ensure_ascii=False, indent=2).encode(),
+            path_in_repo=path_in_repo,
+            repo_id=DATASET_REPO,
+            repo_type="dataset",
+            commit_message=f"trace: {payload['input_type']} / {payload['action']}",
+        )
+    except Exception:
+        pass  # traces are best-effort; never break the approval flow

dukaan_saathi/integrations/llamacpp_llm.py

@@ -0,0 +1,159 @@
+"""
+LLM wrapper — calls the llama.cpp HTTP server running on localhost.
+
+llama.cpp is started as a background process in the HF Space via startup.sh.
+Each model is loaded as a separate server instance on different ports:
+
+  Port 8080 — llama-3.2-3b-instruct.Q4_K_M.gguf       (agent orchestrator)
+  Port 8082 — llama-3.2-3b-receipt.Q4_K_M.gguf         (fine-tuned receipt text parser)
+
+All models are served via the OpenAI-compatible /v1/chat/completions endpoint.
+"""
+
+import json
+import logging
+from typing import Optional
+import urllib.request
+import urllib.error
+
+logger = logging.getLogger(__name__)
+
+MODEL_PORTS = {
+    "llama-3.2-3b":         8080,   # base model, agent orchestrator
+    "llama-3.2-3b-receipt": 8082,   # fine-tuned receipt text parser
+}
+
+DEFAULT_MODEL = "llama-3.2-3b"
+
+
+class Session:
+    """
+    Stateful conversation session.
+
+    Keeps the full inventory dict in the system prompt so the model always
+    sees current stock.  Only the last `history_turns` exchanges are sent as
+    message history — enough for follow-up questions without unbounded growth.
+    """
+
+    def __init__(
+        self,
+        model: str = DEFAULT_MODEL,
+        system: str = "",
+        inventory: Optional[dict] = None,
+        history_turns: int = 3,
+        **llm_kwargs,
+    ):
+        self.model = model
+        self._base_system = system
+        self.inventory: dict = inventory or {}
+        self.history_turns = history_turns
+        self.llm_kwargs = llm_kwargs
+        self._recent: list[dict] = []
+
+    # ------------------------------------------------------------------
+    # Inventory management
+    # ------------------------------------------------------------------
+
+    def set_inventory(self, inventory: dict) -> None:
+        """Replace the full inventory state."""
+        self.inventory = inventory
+
+    def update_inventory(self, updates: dict) -> None:
+        """Merge updates into the inventory (shallow merge by SKU key)."""
+        self.inventory.update(updates)
+
+    # ------------------------------------------------------------------
+    # Chat
+    # ------------------------------------------------------------------
+
+    def chat(self, user: str) -> str:
+        self._recent.append({"role": "user", "content": user})
+        history = self._recent[-(self.history_turns * 2):]
+        reply = _call_with_history(
+            self.model, self._system_prompt(), history, **self.llm_kwargs
+        )
+        self._recent.append({"role": "assistant", "content": reply})
+        return reply
+
+    def reset_history(self) -> None:
+        """Clear conversation history without touching the inventory."""
+        self._recent.clear()
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _system_prompt(self) -> str:
+        inventory_block = json.dumps(self.inventory, indent=2) if self.inventory else "empty"
+        parts = [self._base_system] if self._base_system else []
+        parts.append(f"Current inventory:\n{inventory_block}")
+        return "\n\n".join(parts)
+
+
+def _call_with_history(
+    model: str,
+    system: str,
+    history: list[dict],
+    max_tokens: int = 512,
+    json_mode: bool = False,
+    temperature: float = 0.1,
+) -> str:
+    port = MODEL_PORTS.get(model, MODEL_PORTS[DEFAULT_MODEL])
+    url = f"http://localhost:{port}/v1/chat/completions"
+
+    messages = ([{"role": "system", "content": system}] if system else []) + history
+
+    payload = {
+        "model": model,
+        "messages": messages,
+        "max_tokens": max_tokens,
+        "temperature": temperature,
+        "stream": False,
+    }
+    if json_mode:
+        payload["response_format"] = {"type": "json_object"}
+
+    try:
+        data = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=data,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=60) as resp:
+            body = json.loads(resp.read().decode("utf-8"))
+            return body["choices"][0]["message"]["content"]
+
+    except urllib.error.URLError as e:
+        logger.error(f"llama.cpp unreachable at port {port}: {e}")
+        if port != MODEL_PORTS[DEFAULT_MODEL]:
+            logger.warning(f"Retrying with default model on port {MODEL_PORTS[DEFAULT_MODEL]}")
+            return _call_with_history(DEFAULT_MODEL, system, history, max_tokens, json_mode, temperature)
+        return '{"error": "llama.cpp server unavailable"}'
+
+    except (KeyError, json.JSONDecodeError) as e:
+        logger.error(f"Unexpected response from llama.cpp: {e}")
+        return '{"error": "malformed response"}'
+
+
+def call_llm(
+    model: str,
+    system: str,
+    user: str,
+    max_tokens: int = 512,
+    json_mode: bool = False,
+    temperature: float = 0.1,
+) -> str:
+    """
+    Call llama.cpp HTTP server (single-turn, stateless).
+    Returns the assistant message content string.
+    Falls back to DEFAULT_MODEL if the requested model port is unavailable.
+    """
+    return _call_with_history(
+        model, system,
+        [{"role": "user", "content": user}],
+        max_tokens=max_tokens,
+        json_mode=json_mode,
+        temperature=temperature,
+    )

dukaan_saathi/integrations/llamacpp_receipt.py

@@ -0,0 +1,116 @@
+"""
+llamacpp_receipt.py — Receipt text → structured rows via fine-tuned Llama-3.2-3B on llama.cpp.
+
+Calls the fine-tuned model on port 8082 to parse OCR receipt text into structured line items.
+Returns the same (rows, trace) signature as parsers.receipt_text.parse_receipt_text so it
+can be dropped in as an alternative backend.
+
+Falls back to the deterministic parser if the LLM server is unavailable or returns bad JSON.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+from dukaan_saathi.storage import find_product
+
+logger = logging.getLogger(__name__)
+
+SYSTEM_PROMPT = (
+    "You are a receipt parser for an Indian convenience store. "
+    "Extract all line items from the receipt text. "
+    "Return ONLY valid JSON with this structure: "
+    '{"supplier": "...", "invoice_no": "...", "date": "YYYY-MM-DD", '
+    '"items": [{"product_raw": "...", "qty_cases": 0, "qty_units": 0, '
+    '"unit_cost": 0.0, "total": 0.0}], '
+    '"subtotal": 0.0, "discount": 0.0, "gst": 0.0, "net_total": 0.0}. '
+    "No markdown, no explanation."
+)
+
+
+def _llm_item_to_row(item: dict[str, Any], supplier: str, document_type: str) -> dict[str, Any]:
+    product_raw = str(item.get("product_raw", "")).strip()
+    qty_units = int(item.get("qty_units") or item.get("qty_cases") or 0)
+    unit_price = float(item.get("unit_cost") or 0) or None
+    total_price = float(item.get("total") or 0) or None
+
+    matched = find_product(product_raw)
+    matched_product_id = matched["id"] if matched else ""
+    matched_product_name = matched["name"] if matched else ""
+
+    warning_parts = []
+    if not matched:
+        warning_parts.append("No catalog match; owner must map or skip.")
+    if item.get("needs_review"):
+        warning_parts.append("Flagged for review by parser.")
+
+    return {
+        "apply": bool(matched),
+        "document_type": document_type,
+        "supplier": supplier,
+        "product_raw": product_raw,
+        "matched_product_id": matched_product_id,
+        "matched_product_name": matched_product_name,
+        "quantity_raw": str(qty_units),
+        "quantity": qty_units,
+        "unit_price": unit_price,
+        "total_price": total_price,
+        "confidence": 0.85 if matched else 0.5,
+        "warning": " | ".join(warning_parts),
+    }
+
+
+def parse_receipt_via_llm(raw_text: str) -> tuple[list[dict[str, Any]], list[str]]:
+    """
+    Parse receipt OCR text using the fine-tuned Llama-3.2-3B model via llama.cpp.
+    Falls back to the deterministic parser on any failure.
+    """
+    from dukaan_saathi.integrations.llamacpp_llm import call_llm
+    from dukaan_saathi.parsers.receipt_text import parse_receipt_text, detect_supplier, detect_document_type
+
+    trace: list[str] = ["[llamacpp] Calling fine-tuned Llama-3.2-3B for receipt parsing"]
+
+    try:
+        response_text = call_llm(
+            model="llama-3.2-3b-receipt",
+            system=SYSTEM_PROMPT,
+            user=raw_text,
+            max_tokens=768,
+            json_mode=True,
+            temperature=0.1,
+        )
+
+        if '"error"' in response_text:
+            raise ValueError(f"LLM returned error: {response_text}")
+
+        parsed = json.loads(response_text)
+        items = parsed.get("items", [])
+
+        if not items:
+            raise ValueError("LLM returned zero items")
+
+        supplier = parsed.get("supplier", detect_supplier(raw_text))
+        document_type = detect_document_type(raw_text)
+
+        trace.append(f"[llamacpp] Parsed supplier: {supplier}")
+        trace.append(f"[llamacpp] Extracted {len(items)} items from LLM response")
+
+        rows = []
+        for item in items:
+            row = _llm_item_to_row(item, supplier, document_type)
+            rows.append(row)
+            if row["matched_product_name"]:
+                trace.append(f"[llamacpp] Matched '{row['product_raw']}' → {row['matched_product_name']}")
+            else:
+                trace.append(f"[llamacpp] Needs owner review: '{row['product_raw']}'")
+
+        trace.append(f"[llamacpp] Extracted {len(rows)} candidate line items")
+        return rows, trace
+
+    except Exception as exc:
+        logger.warning(f"llamacpp_receipt falling back to deterministic parser: {exc}")
+        trace.append(f"[llamacpp] Fallback to deterministic parser: {exc}")
+        fallback_rows, fallback_trace = parse_receipt_text(raw_text)
+        return fallback_rows, trace + fallback_trace

dukaan_saathi/integrations/modal_receipt.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+import requests
+
+from dukaan_saathi.integrations.vision import (
+    VisionBackendName,
+    VisionExtractionResult,
+    VisionRequest,
+    VisionRow,
+)
+from dukaan_saathi.parsers.receipt_text import parse_receipt_text
+
+
+BACKEND_NAME: VisionBackendName = "modal"
+UNKNOWN_MODEL = "unknown model"
+
+
+def _payload_text(payload: dict[str, Any]) -> str:
+    return str(payload.get("raw_text") or payload.get("text") or "")
+
+
+def _payload_latency(payload: dict[str, Any]) -> float | None:
+    value = payload.get("latency_seconds")
+    if isinstance(value, int | float):
+        return float(value)
+    return None
+
+
+def _coerce_rows(value: Any) -> list[VisionRow]:
+    if not isinstance(value, list):
+        return []
+    return [row for row in value if isinstance(row, dict)]
+
+
+def _result_from_modal_payload(payload: dict[str, Any], trace: list[str]) -> VisionExtractionResult:
+    model_name = str(payload.get("model") or UNKNOWN_MODEL)
+    raw_text = _payload_text(payload)
+    rows = _coerce_rows(payload.get("rows"))
+    latency_seconds = _payload_latency(payload)
+
+    return VisionExtractionResult(
+        backend_name=BACKEND_NAME,
+        model_name=model_name,
+        raw_text=raw_text,
+        rows=rows,
+        latency_seconds=latency_seconds,
+        trace_messages=trace,
+    )
+
+
+def _extract_receipt_result_with_modal(image_path: Any) -> VisionExtractionResult:
+    trace: list[str] = ["Starting receipt image extraction via Modal"]
+
+    endpoint = (os.getenv("MODAL_RECEIPT_ENDPOINT") or os.getenv("MINICPM_RECEIPT_ENDPOINT") or "").strip()
+    if not endpoint:
+        return VisionExtractionResult(
+            backend_name=BACKEND_NAME,
+            model_name=UNKNOWN_MODEL,
+            trace_messages=[
+                "MODAL_RECEIPT_ENDPOINT or MINICPM_RECEIPT_ENDPOINT is not set.",
+                "Model endpoint is not connected yet.",
+                "Use pasted/sample receipt text for the MVP path.",
+            ],
+        )
+
+    if not image_path:
+        return VisionExtractionResult(
+            backend_name=BACKEND_NAME,
+            model_name=UNKNOWN_MODEL,
+            trace_messages=["No receipt image provided."],
+        )
+
+    request = VisionRequest(image_path=Path(str(image_path)))
+    if not request.image_path.exists():
+        return VisionExtractionResult(
+            backend_name=BACKEND_NAME,
+            model_name=UNKNOWN_MODEL,
+            trace_messages=[f"Receipt image path does not exist: {request.image_path}"],
+        )
+
+    try:
+        with request.image_path.open("rb") as f:
+            response = requests.post(
+                endpoint,
+                files={"image": (request.image_path.name, f, "image/jpeg")},
+                timeout=180,
+            )
+        response.raise_for_status()
+    except requests.RequestException as exc:
+        return VisionExtractionResult(
+            backend_name=BACKEND_NAME,
+            model_name=UNKNOWN_MODEL,
+            trace_messages=[f"Modal request failed: {exc}"],
+        )
+
+    try:
+        payload = response.json()
+    except ValueError:
+        return VisionExtractionResult(
+            backend_name=BACKEND_NAME,
+            model_name=UNKNOWN_MODEL,
+            trace_messages=["Modal endpoint did not return valid JSON."],
+        )
+
+    if not isinstance(payload, dict):
+        return VisionExtractionResult(
+            backend_name=BACKEND_NAME,
+            model_name=UNKNOWN_MODEL,
+            trace_messages=["Modal endpoint JSON was not an object."],
+        )
+
+    return _result_from_modal_payload(payload, trace)
+
+
+def extract_receipt_with_modal(image_path: Any) -> tuple[list[dict], list[str]]:
+    result = _extract_receipt_result_with_modal(image_path)
+    trace = list(result.trace_messages)
+
+    if result.raw_text.strip():
+        latency = (
+            f" in {result.latency_seconds:.2f}s"
+            if result.latency_seconds is not None
+            else ""
+        )
+        trace.append(f"Modal returned raw text using {result.model_name}{latency}")
+        rows, parser_trace = parse_receipt_text(result.raw_text)
+        trace.extend(parser_trace)
+        return rows, trace
+
+    if result.rows:
+        trace.append(f"Modal returned {len(result.rows)} structured rows")
+        return result.rows, trace
+
+    return [], trace + [
+        "Modal endpoint returned no raw_text or rows.",
+    ]

dukaan_saathi/integrations/modal_receipt_llm.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import json
+import os
+import hashlib
+from typing import Any
+
+import requests
+
+from dukaan_saathi.integrations.llamacpp_receipt import _llm_item_to_row
+from dukaan_saathi.parsers.receipt_text import (
+    detect_document_type,
+    detect_supplier,
+    parse_receipt_text,
+)
+from dukaan_saathi.traceability import new_run_id, utc_now_iso, write_manifest
+
+
+def _text_sha256(value: str) -> str:
+    return hashlib.sha256(value.encode("utf-8")).hexdigest()
+
+
+def _extract_json_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    value = payload.get("parsed") or payload.get("raw_json") or payload.get("text") or ""
+    if isinstance(value, dict):
+        return value
+    if not isinstance(value, str):
+        raise ValueError("Modal parser response did not include JSON text")
+    return json.loads(value)
+
+
+def parse_receipt_with_modal_llm(raw_text: str) -> tuple[list[dict[str, Any]], list[str]]:
+    trace: list[str] = ["[modal_llm] Calling Modal receipt parser endpoint"]
+    run_id = new_run_id("receipt-inference")
+    started_at = utc_now_iso()
+    endpoint = (
+        os.getenv("MODAL_RECEIPT_LLM_ENDPOINT")
+        or os.getenv("MODAL_RECEIPT_PARSER_ENDPOINT")
+        or ""
+    ).strip()
+
+    if not endpoint:
+        rows, fallback_trace = parse_receipt_text(raw_text)
+        manifest_path = write_manifest({
+            "run_id": run_id,
+            "kind": "receipt-inference",
+            "status": "fallback",
+            "started_at": started_at,
+            "ended_at": utc_now_iso(),
+            "metadata": {
+                "backend": "modal_llm",
+                "fallback_backend": "deterministic",
+                "reason": "missing_endpoint",
+                "raw_text_sha256": _text_sha256(raw_text),
+                "raw_text_chars": len(raw_text),
+                "rows": len(rows),
+            },
+        })
+        return rows, trace + [
+            "[modal_llm] MODAL_RECEIPT_LLM_ENDPOINT is not set; using deterministic parser",
+            f"[trace] Wrote inference manifest: {manifest_path}",
+            *fallback_trace,
+        ]
+
+    try:
+        response = requests.post(
+            endpoint,
+            json={"raw_text": raw_text},
+            timeout=180,
+        )
+        response.raise_for_status()
+        payload = response.json()
+        if not isinstance(payload, dict):
+            raise ValueError("Modal parser response JSON was not an object")
+
+        parsed = _extract_json_payload(payload)
+        items = parsed.get("items") or []
+        if not items:
+            raise ValueError("Modal parser returned zero items")
+
+        supplier = parsed.get("supplier") or detect_supplier(raw_text)
+        document_type = detect_document_type(raw_text)
+        rows = [
+            _llm_item_to_row(item, supplier=supplier, document_type=document_type)
+            for item in items
+            if isinstance(item, dict)
+        ]
+        if not rows:
+            raise ValueError("Modal parser returned no valid item objects")
+
+        model = str(payload.get("model") or "unknown")
+        latency = payload.get("latency_seconds")
+        latency_note = f" in {latency:.2f}s" if isinstance(latency, int | float) else ""
+        manifest_path = write_manifest({
+            "run_id": run_id,
+            "kind": "receipt-inference",
+            "status": "succeeded",
+            "started_at": started_at,
+            "ended_at": utc_now_iso(),
+            "metadata": {
+                "backend": "modal_llm",
+                "endpoint": endpoint,
+                "model": model,
+                "latency_seconds": latency,
+                "raw_text_sha256": _text_sha256(raw_text),
+                "raw_text_chars": len(raw_text),
+                "parsed_items": len(items),
+                "editable_rows": len(rows),
+            },
+        })
+        trace.append(f"[modal_llm] Parsed {len(rows)} rows with {model}{latency_note}")
+        trace.append(f"[trace] Wrote inference manifest: {manifest_path}")
+        return rows, trace
+
+    except Exception as exc:
+        rows, fallback_trace = parse_receipt_text(raw_text)
+        manifest_path = write_manifest({
+            "run_id": run_id,
+            "kind": "receipt-inference",
+            "status": "fallback",
+            "started_at": started_at,
+            "ended_at": utc_now_iso(),
+            "metadata": {
+                "backend": "modal_llm",
+                "fallback_backend": "deterministic",
+                "endpoint": endpoint,
+                "raw_text_sha256": _text_sha256(raw_text),
+                "raw_text_chars": len(raw_text),
+                "rows": len(rows),
+            },
+            "error": str(exc),
+        })
+        return rows, trace + [
+            f"[modal_llm] Fallback to deterministic parser: {exc}",
+            f"[trace] Wrote inference manifest: {manifest_path}",
+            *fallback_trace,
+        ]

dukaan_saathi/integrations/speech.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import requests
+
+
+def transcribe_audio(audio_path: str | None) -> tuple[str, list[str]]:
+    """
+    Speech-to-text client for correction commands.
+
+    Contract:
+    - input: audio file path from Gradio
+    - output: transcript string + trace
+
+    Safety boundary:
+    - This only returns text.
+    - It does not apply corrections.
+    - It does not approve inventory updates.
+    """
+
+    trace: list[str] = []
+
+    if not audio_path:
+        return "", ["No audio provided."]
+
+    path = Path(audio_path)
+
+    if not path.exists():
+        return "", [f"Audio file not found: {audio_path}"]
+
+    endpoint = (
+        os.getenv("MODAL_SPEECH_ENDPOINT")
+        or os.getenv("SPEECH_ASR_ENDPOINT")
+        or ""
+    ).strip()
+
+    if not endpoint:
+        return "", [
+            "Speech ASR endpoint is not configured.",
+            "Run scripts/modal_deploy.sh modal_apps/speech_asr_service.py to generate it.",
+            "Typed correction still works.",
+        ]
+
+    trace.append(f"Sending audio to ASR endpoint: {endpoint}")
+    trace.append(f"Audio file: {path.name}")
+
+    try:
+        with path.open("rb") as audio_file:
+            response = requests.post(
+                endpoint,
+                files={
+                    "audio": (
+                        path.name,
+                        audio_file,
+                        "application/octet-stream",
+                    )
+                },
+                timeout=180,
+            )
+
+        if response.status_code >= 400:
+            return "", [
+                *trace,
+                f"ASR request failed with HTTP {response.status_code}.",
+                response.text[:500],
+            ]
+
+        payload = response.json()
+        transcript = str(payload.get("text") or "").strip()
+
+        if not transcript:
+            error = payload.get("error")
+            if error:
+                trace.append(f"ASR returned no transcript: {error}")
+            else:
+                trace.append("ASR returned no transcript.")
+            return "", trace
+
+        trace.append(f"ASR model: {payload.get('model', 'unknown')}")
+        trace.append(f"Transcript: {transcript}")
+
+        return transcript, trace
+
+    except requests.RequestException as exc:
+        return "", [
+            *trace,
+            f"ASR request error: {exc}",
+            "Typed correction still works.",
+        ]
+    except ValueError as exc:
+        return "", [
+            *trace,
+            f"Could not parse ASR response JSON: {exc}",
+            "Typed correction still works.",
+        ]

dukaan_saathi/integrations/vision.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal, Protocol, TypeAlias
+
+
+VisionBackendName: TypeAlias = Literal["modal"]
+VisionModelName: TypeAlias = str
+VisionTrace: TypeAlias = list[str]
+VisionRow: TypeAlias = dict[str, Any]
+
+
+@dataclass(frozen=True)
+class VisionRequest:
+    image_path: Path
+
+
+@dataclass(frozen=True)
+class VisionExtractionResult:
+    backend_name: VisionBackendName
+    model_name: VisionModelName
+    raw_text: str = ""
+    rows: list[VisionRow] = field(default_factory=list)
+    latency_seconds: float | None = None
+    trace_messages: VisionTrace = field(default_factory=list)
+
+
+class ReceiptVisionBackend(Protocol):
+    backend_name: VisionBackendName
+
+    def extract_receipt(self, request: VisionRequest) -> VisionExtractionResult:
+        ...

dukaan_saathi/parsers/receipt_correction.py

@@ -0,0 +1,234 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from dukaan_saathi.storage import find_product
+
+
+NO_MATCH_WARNING = "No catalog match; owner must map or skip."
+OWNER_SKIP_WARNING = "Skipped by owner."
+
+ORDINAL_TO_INDEX = {
+    "first": 0,
+    "1st": 0,
+    "second": 1,
+    "2nd": 1,
+    "third": 2,
+    "3rd": 2,
+}
+
+
+def _rows_to_records(rows: Any) -> list[dict[str, Any]]:
+    if rows is None:
+        return []
+
+    if hasattr(rows, "to_dict"):
+        return [dict(row) for row in rows.to_dict(orient="records")]
+
+    if isinstance(rows, dict) and "headers" in rows and "data" in rows:
+        headers = rows.get("headers") or []
+        return [dict(zip(headers, values)) for values in rows.get("data") or []]
+
+    return [dict(row) for row in rows]
+
+
+def _split_commands(command_text: str) -> list[str]:
+    text = command_text or ""
+
+    # Supports: "first one Parle bulk and second one Bingo"
+    text = re.sub(
+        r"\s+(?:and|then)\s+(?=(?:first|1st|second|2nd|third|3rd|row\s*\d+|skip|quantity|qty)\b)",
+        ", ",
+        text,
+        flags=re.I,
+    )
+
+    return [part.strip() for part in re.split(r"[,;\n]+", text) if part.strip()]
+
+
+def _parse_row_index(command: str) -> int | None:
+    lower = command.lower()
+
+    row_match = re.search(r"\brow\s*(\d+)\b", lower)
+    if row_match:
+        return int(row_match.group(1)) - 1
+
+    for word, index in ORDINAL_TO_INDEX.items():
+        if re.search(rf"\b{re.escape(word)}\b", lower):
+            return index
+
+    return None
+
+
+def _warning_parts(warning: Any) -> list[str]:
+    return [
+        part.strip()
+        for part in str(warning or "").split("|")
+        if part and part.strip()
+    ]
+
+
+def _set_warning_parts(row: dict[str, Any], parts: list[str]) -> None:
+    row["warning"] = " | ".join(dict.fromkeys(parts))
+
+
+def _append_warning(row: dict[str, Any], warning: str) -> None:
+    parts = _warning_parts(row.get("warning"))
+    if warning not in parts:
+        parts.append(warning)
+    _set_warning_parts(row, parts)
+
+
+def _remove_owner_resolution_warnings(row: dict[str, Any]) -> None:
+    parts = [
+        part
+        for part in _warning_parts(row.get("warning"))
+        if part not in {NO_MATCH_WARNING, OWNER_SKIP_WARNING}
+    ]
+    _set_warning_parts(row, parts)
+
+
+def _as_int(value: Any) -> int | None:
+    try:
+        return int(float(value))
+    except (TypeError, ValueError):
+        return None
+
+
+def _row_number(index: int) -> int:
+    return index + 1
+
+
+def _extract_product_text(command: str) -> str:
+    match = re.match(
+        r"^\s*(?:row\s*\d+|first|1st|second|2nd|third|3rd)(?:\s+one)?\s+(?P<product>.+?)\s*$",
+        command,
+        flags=re.I,
+    )
+    if not match:
+        return ""
+
+    product = match.group("product").strip()
+    product = re.sub(r"^(?:is|as|to|product|item|name)\s+", "", product, flags=re.I)
+    return product.strip(" .:-")
+
+
+def _apply_product_update(row: dict[str, Any], product_text: str) -> str:
+    row["product_raw"] = product_text
+
+    matched = find_product(product_text)
+
+    if matched:
+        row["matched_product_id"] = matched["id"]
+        row["matched_product_name"] = matched["name"]
+        row["apply"] = True
+        _remove_owner_resolution_warnings(row)
+
+        current_confidence = float(row.get("confidence") or 0)
+        row["confidence"] = round(max(current_confidence, 0.75), 2)
+
+        return f"matched {matched['name']}"
+
+    row["matched_product_id"] = ""
+    row["matched_product_name"] = ""
+    row["apply"] = False
+
+    current_confidence = float(row.get("confidence") or 0.55)
+    row["confidence"] = round(min(current_confidence, 0.55), 2)
+    _append_warning(row, NO_MATCH_WARNING)
+
+    return "no catalog match; apply=False"
+
+
+def _apply_skip(row: dict[str, Any]) -> None:
+    row["apply"] = False
+    _append_warning(row, OWNER_SKIP_WARNING)
+
+
+def _apply_quantity_update(row: dict[str, Any], quantity: int) -> None:
+    row["quantity"] = quantity
+    row["quantity_raw"] = str(quantity)
+
+
+def _parse_quantity_value(command: str, row_index: int | None) -> int | None:
+    numbers = re.findall(r"\d+(?:\.\d+)?", command)
+
+    if not numbers:
+        return None
+
+    # For "quantity row 1 is 4", the last number is the desired quantity.
+    if row_index is not None and len(numbers) == 1:
+        only_number = _as_int(numbers[0])
+        if only_number == _row_number(row_index):
+            return None
+
+    return _as_int(numbers[-1])
+
+
+def apply_receipt_correction_command(
+    rows: Any,
+    command_text: str,
+) -> tuple[list[dict[str, Any]], list[str]]:
+    """
+    Apply phone-friendly owner corrections to parsed receipt rows.
+
+    Supported examples:
+    - first one Parle bulk
+    - second one Bingo
+    - row 1 Parle bulk
+    - row 2 Bingo
+    - skip row 2
+    - quantity row 1 is 4
+    """
+
+    records = _rows_to_records(rows)
+    trace: list[str] = []
+
+    if not records:
+        return records, ["No receipt rows to correct."]
+
+    commands = _split_commands(command_text)
+
+    if not commands:
+        return records, ["No correction command provided."]
+
+    for command in commands:
+        row_index = _parse_row_index(command)
+
+        if row_index is None:
+            trace.append(f"Could not identify row in correction: {command}")
+            continue
+
+        if row_index < 0 or row_index >= len(records):
+            trace.append(f"Row {_row_number(row_index)} is out of range: {command}")
+            continue
+
+        row = records[row_index]
+        lower = command.lower()
+
+        if re.search(r"\bskip\b", lower):
+            _apply_skip(row)
+            trace.append(f"Skipped row {_row_number(row_index)} by owner command.")
+            continue
+
+        if re.search(r"\b(?:quantity|qty)\b", lower):
+            quantity = _parse_quantity_value(command, row_index)
+            if quantity is None or quantity <= 0:
+                trace.append(f"Could not parse positive quantity for row {_row_number(row_index)}: {command}")
+                continue
+
+            _apply_quantity_update(row, quantity)
+            trace.append(f"Updated row {_row_number(row_index)} quantity to {quantity}.")
+            continue
+
+        product_text = _extract_product_text(command)
+
+        if not product_text:
+            trace.append(f"Could not parse product correction for row {_row_number(row_index)}: {command}")
+            continue
+
+        result = _apply_product_update(row, product_text)
+        trace.append(f"Updated row {_row_number(row_index)} product to '{product_text}'; {result}.")
+
+    return records, trace

dukaan_saathi/parsers/receipt_text.py

@@ -0,0 +1,375 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from dukaan_saathi.storage import find_product
+
+
+SKIP_WORDS = {
+    "invoice",
+    "bill no",
+    "date",
+    "gstin",
+    "gst ",
+    "gross sales",
+    "cgst",
+    "sgst",
+    "net amount",
+    "total:",
+    "document type",
+    "phone",
+    "address",
+}
+
+def _looks_like_item_row(line: str) -> bool:
+    lower = line.lower()
+
+    # Pipe-separated invoice row:
+    # Product | 5/0 | MRP 10.00 | RATE 8.625 | GST 5% | NET 3105.000
+    if "|" in line and any(token in lower for token in ["rate", "net", "mrp"]):
+        return True
+
+    # Handwritten row:
+    # Bingo(C) 4 X 870 = 3480
+    if re.search(r"\d+(?:\.\d+)?\s*[xX*]\s*\d+(?:\.\d+)?", line):
+        return True
+
+    return False
+
+
+def _should_skip_line(line: str) -> bool:
+    lower = line.lower()
+
+    if _looks_like_item_row(line):
+        return False
+
+    return any(word in lower for word in SKIP_WORDS)
+
+
+def _to_float(value: str | None) -> float | None:
+    if value is None:
+        return None
+
+    cleaned = (
+        value.replace(",", "")
+        .replace("₹", "")
+        .replace("Rs.", "")
+        .replace("Rs", "")
+        .replace("%", "")
+        .strip()
+    )
+
+    try:
+        return float(cleaned)
+    except ValueError:
+        pass
+
+    # Model/OCR output often returns rates like "X2450" or "X8702".
+    number_match = re.search(r"\d+(?:\.\d+)?", cleaned)
+    if number_match:
+        return float(number_match.group(0))
+
+    return None
+
+
+def _clean_product_name(value: str) -> str:
+    value = re.sub(r"[^A-Za-z0-9 .&()'-]", " ", value)
+    return re.sub(r"\s+", " ", value).strip(" -:.")
+
+
+def _parse_quantity(value: str | None) -> tuple[int | None, str]:
+    if not value:
+        return None, ""
+
+    raw = value.strip()
+
+    # Printed invoice style: 5/0, 10/0
+    slash_match = re.match(r"^(\d+)\s*/\s*(\d+)$", raw)
+    if slash_match:
+        return int(slash_match.group(1)), raw
+
+    number_match = re.search(r"\d+(?:\.\d+)?", raw)
+    if number_match:
+        return int(float(number_match.group(0))), raw
+
+    return None, raw
+
+
+def detect_supplier(raw_text: str) -> str:
+    text = raw_text.lower()
+
+    if "mahalakshmi marketing" in text:
+        return "Mahalakshmi Marketing"
+
+    if "venkateshwara" in text or "venkatesh" in text:
+        return "Sri Venkateshwara Marketing"
+
+    if "brundavan" in text or "bundavan" in text or "buns" in text:
+        return "Brundavan Buns"
+
+    lines = [line.strip() for line in raw_text.splitlines() if line.strip()]
+    for line in lines:
+        match = re.search(r"(supplier|vendor|from)\s*[:\-]\s*(.+)", line, re.I)
+        if match:
+            return match.group(2).strip()
+
+    for line in lines:
+        lower = line.lower()
+        if not any(word in lower for word in SKIP_WORDS) and not re.search(r"\d+\s*[xX*]\s*\d+", line):
+            return line[:80]
+
+    return "Unknown Supplier"
+
+
+def detect_document_type(raw_text: str) -> str:
+    text = raw_text.lower()
+
+    explicit = re.search(r"document type\s*:\s*(.+)", raw_text, re.I)
+    if explicit:
+        return explicit.group(1).strip()
+
+    if "tax invoice" in text or "cash bill" in text or "gst" in text:
+        return "printed tax invoice"
+
+    if "tally" in text or "buns" in text:
+        return "handwritten tally note"
+
+    return "handwritten supplier bill"
+
+
+def _build_row(
+    *,
+    document_type: str,
+    supplier: str,
+    product_raw: str,
+    quantity_raw: str,
+    quantity: int,
+    unit_price: float | None,
+    total_price: float | None,
+    confidence: float,
+    warning: str,
+) -> dict[str, Any]:
+    product_raw = _clean_product_name(product_raw)
+    matched = find_product(product_raw)
+
+    matched_product_id = matched["id"] if matched else ""
+    matched_product_name = matched["name"] if matched else ""
+
+    if not matched:
+        confidence = min(confidence, 0.55)
+        warning = (warning + " | " if warning else "") + "No catalog match; owner must map or skip."
+
+    return {
+        "apply": True if matched else False,
+        "document_type": document_type,
+        "supplier": supplier,
+        "product_raw": product_raw,
+        "matched_product_id": matched_product_id,
+        "matched_product_name": matched_product_name,
+        "quantity_raw": quantity_raw,
+        "quantity": quantity,
+        "unit_price": unit_price,
+        "total_price": total_price,
+        "confidence": round(confidence, 2),
+        "warning": warning,
+    }
+
+
+def _validate_math(quantity: int, unit_price: float | None, total_price: float | None) -> tuple[float, str]:
+    if unit_price is None and total_price is None:
+        return 0.6, "Missing price; stock quantity only."
+
+    if unit_price is not None and total_price is None:
+        return 0.75, "Total inferred from quantity × unit price."
+
+    if unit_price is None and total_price is not None:
+        return 0.65, "Missing unit price; keeping receipt total."
+
+    expected = quantity * float(unit_price)
+    actual = float(total_price)
+
+    # Printed invoices often show per-piece rate but quantity is in cases,
+    # so we warn instead of failing when math does not match.
+    if abs(expected - actual) > max(1.0, 0.03 * max(expected, actual)):
+        return 0.62, f"Check math: qty × rate = {expected:.2f}, receipt says {actual:.2f}."
+
+    return 0.9, ""
+
+def _looks_like_table_separator(parts: list[str]) -> bool:
+    return all(not part or set(part) <= {"-"} for part in parts)
+
+
+def _looks_like_header_row(parts: list[str]) -> bool:
+    joined = " ".join(parts).lower()
+    return (
+        "particular" in joined
+        and "qty" in joined
+        and ("rate" in joined or "amount" in joined)
+    )
+
+
+def _looks_like_serial(value: str) -> bool:
+    cleaned = value.strip()
+    return bool(re.match(r"^\d+\s*/?\s*\d*$", cleaned))
+
+def _parse_pipe_row(line: str, document_type: str, supplier: str) -> dict[str, Any] | None:
+    if "|" not in line:
+        return None
+
+    parts = [part.strip() for part in line.split("|")]
+
+    if len(parts) < 2:
+        return None
+
+    if _looks_like_table_separator(parts) or _looks_like_header_row(parts):
+        return None
+
+    # Model-produced table style:
+    # serial | product | quantity | rate | amount
+    # Example:
+    # 5/ | Port | 1 | X2450 | 2450
+    # 10/ | Rs.g/c | 4 | X8702 | 3480
+    if len(parts) >= 5 and _looks_like_serial(parts[0]) and parts[1]:
+        product_raw = parts[1]
+        quantity, quantity_raw = _parse_quantity(parts[2])
+        unit_price = _to_float(parts[3])
+        total_price = _to_float(parts[4])
+
+        if quantity is None:
+            return None
+
+        confidence, warning = _validate_math(quantity, unit_price, total_price)
+
+        return _build_row(
+            document_type=document_type,
+            supplier=supplier,
+            product_raw=product_raw,
+            quantity_raw=quantity_raw,
+            quantity=quantity,
+            unit_price=unit_price,
+            total_price=total_price,
+            confidence=confidence,
+            warning=warning,
+        )
+
+    # Existing normalized style:
+    # product | quantity | rate | amount
+    product_raw = parts[0]
+    quantity, quantity_raw = _parse_quantity(parts[1])
+    if quantity is None:
+        return None
+
+    unit_price = None
+    total_price = None
+
+    for part in parts[2:]:
+        lower = part.lower()
+
+        if "rate" in lower:
+            unit_price = _to_float(part.split()[-1])
+        elif "net" in lower or "amount" in lower:
+            total_price = _to_float(part.split()[-1])
+        elif unit_price is None:
+            maybe = _to_float(part.split()[-1])
+            if maybe is not None:
+                unit_price = maybe
+        elif total_price is None:
+            maybe = _to_float(part.split()[-1])
+            if maybe is not None:
+                total_price = maybe
+
+    confidence, warning = _validate_math(quantity, unit_price, total_price)
+
+    return _build_row(
+        document_type=document_type,
+        supplier=supplier,
+        product_raw=product_raw,
+        quantity_raw=quantity_raw,
+        quantity=quantity,
+        unit_price=unit_price,
+        total_price=total_price,
+        confidence=confidence,
+        warning=warning,
+    )
+
+def _parse_multiply_row(line: str, document_type: str, supplier: str) -> dict[str, Any] | None:
+    pattern = re.compile(
+        r"^(?P<product>.+?)\s+"
+        r"(?P<quantity>\d+(?:\.\d+)?)\s*[xX*]\s*"
+        r"(?P<unit_price>\d+(?:\.\d+)?)"
+        r"(?:\s*(?:=|rs\.?|inr)?\s*(?P<total_price>\d+(?:\.\d+)?))?\s*$",
+        re.I,
+    )
+
+    match = pattern.match(line)
+    if not match:
+        return None
+
+    product_raw = match.group("product")
+    quantity, quantity_raw = _parse_quantity(match.group("quantity"))
+    unit_price = _to_float(match.group("unit_price"))
+    total_price = _to_float(match.group("total_price"))
+
+    if quantity is None:
+        return None
+
+    if unit_price is not None and total_price is None:
+        total_price = quantity * unit_price
+
+    confidence, warning = _validate_math(quantity, unit_price, total_price)
+
+    return _build_row(
+        document_type=document_type,
+        supplier=supplier,
+        product_raw=product_raw,
+        quantity_raw=quantity_raw,
+        quantity=quantity,
+        unit_price=unit_price,
+        total_price=total_price,
+        confidence=confidence,
+        warning=warning,
+    )
+
+
+def parse_receipt_text(raw_text: str) -> tuple[list[dict[str, Any]], list[str]]:
+    raw_text = raw_text or ""
+
+    supplier = detect_supplier(raw_text)
+    document_type = detect_document_type(raw_text)
+
+    trace: list[str] = [
+        f"Detected supplier: {supplier}",
+        f"Detected document type: {document_type}",
+    ]
+
+    lines = [line.strip() for line in raw_text.splitlines() if line.strip()]
+    trace.append(f"Read {len(lines)} non-empty lines")
+
+    rows: list[dict[str, Any]] = []
+
+    for line in lines:
+        if _should_skip_line(line):
+            continue
+
+        parsed = (
+            _parse_pipe_row(line, document_type, supplier)
+            or _parse_multiply_row(line, document_type, supplier)
+        )
+
+        if parsed is None:
+            trace.append(f"Skipped unparsed line: {line}")
+            continue
+
+        rows.append(parsed)
+
+        if parsed["matched_product_name"]:
+            trace.append(f"Matched '{parsed['product_raw']}' → {parsed['matched_product_name']}")
+        else:
+            trace.append(f"Needs owner review: '{parsed['product_raw']}'")
+
+        if parsed["warning"]:
+            trace.append(f"Warning for '{parsed['product_raw']}': {parsed['warning']}")
+
+    trace.append(f"Extracted {len(rows)} candidate line items")
+    return rows, trace

dukaan_saathi/parsers/stock_command.py

@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from dukaan_saathi.storage import find_product
+
+
+OUT_OF_STOCK_MARKERS = [
+    "out",
+    "finished",
+    "empty",
+    "khatam",
+    "ayipoyindi",
+    "అయిపోయింది",
+]
+
+LOW_STOCK_MARKERS = [
+    "low",
+    "less",
+    "తక్కువ",
+]
+
+ADD_STOCK_MARKERS = [
+    "add",
+    "received",
+    "arrived",
+    "stock add",
+    "add cheyyi",
+]
+
+
+def parse_stock_command(command: str) -> tuple[dict[str, Any], list[str]]:
+    command = (command or "").strip()
+    trace = [f"Received command: {command}"]
+
+    if not command:
+        return {"status": "error", "message": "No command provided."}, trace
+
+    product = find_product(command)
+    if product is None:
+        trace.append("No product matched.")
+        numbers = [int(n) for n in re.findall(r"\d+", command)]
+        stop_words = {"add", "set", "stock", "received", "arrived", "low", "out",
+                      "finished", "to", "the", "a", "an", "kg", "g", "ml", "l",
+                      "unit", "units", "piece", "pieces", "pack", "packs"}
+        words = [
+            w for raw in re.sub(r"\d+", "", command.lower()).split()
+            if (w := re.sub(r"[^a-z]", "", raw)) and w not in stop_words
+        ]
+        suggested_name = " ".join(words).title() if words else None
+        suggested_qty = numbers[-1] if numbers else None
+        return {
+            "status": "needs_review",
+            "message": "Could not match a known product.",
+            "raw_command": command,
+            "suggested_name": suggested_name,
+            "suggested_qty": suggested_qty,
+        }, trace
+
+    trace.append(f"Matched product: {product['name']}")
+
+    lower = command.lower()
+    numbers = [int(n) for n in re.findall(r"\d+", command)]
+
+    if any(marker in lower for marker in OUT_OF_STOCK_MARKERS) or "అయిపోయింది" in command:
+        trace.append("Detected intent: stockout")
+        trace.append("Proposed action: set stock to 0")
+        return {
+            "status": "pending_approval",
+            "type": "set_stock",
+            "product_id": product["id"],
+            "product_name": product["name"],
+            "new_stock": 0,
+            "reason": f"Owner said product is out of stock: {command}",
+        }, trace
+
+    if any(marker in lower for marker in ADD_STOCK_MARKERS):
+        qty = numbers[-1] if numbers else 1
+        trace.append("Detected intent: add stock")
+        trace.append(f"Proposed action: add {qty}")
+        return {
+            "status": "pending_approval",
+            "type": "add_stock",
+            "product_id": product["id"],
+            "product_name": product["name"],
+            "delta": qty,
+            "reason": f"Owner said stock arrived: {command}",
+        }, trace
+
+    if any(marker in lower for marker in LOW_STOCK_MARKERS):
+        trace.append("Detected intent: mark low stock")
+        trace.append("Proposed action: set stock to 1")
+        return {
+            "status": "pending_approval",
+            "type": "set_stock",
+            "product_id": product["id"],
+            "product_name": product["name"],
+            "new_stock": 1,
+            "reason": f"Owner said stock is low: {command}",
+        }, trace
+
+    if numbers:
+        qty = numbers[-1]
+        trace.append("Detected intent: set stock count")
+        trace.append(f"Proposed action: set stock to {qty}")
+        return {
+            "status": "pending_approval",
+            "type": "set_stock",
+            "product_id": product["id"],
+            "product_name": product["name"],
+            "new_stock": qty,
+            "reason": f"Owner provided stock count: {command}",
+        }, trace
+
+    trace.append("Product matched, but intent was unclear.")
+    return {
+        "status": "needs_review",
+        "message": "Product matched, but command intent was unclear.",
+        "product_id": product["id"],
+        "product_name": product["name"],
+        "raw_command": command,
+    }, trace