# 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.