# BillProds AI — Technical Specification & Case Study

> Granular product intelligence ledger and receipt vision parsing system. Transforms unformatted paper receipts and wholesale invoices into structured, item-level price history time-series using Google Gemini Multimodal Vision, FastAPI, and an offline-first Progressive Web App (PWA).

- **Status:** Active // Cloud Staging
- **Repository:** https://github.com/asimansari-git/billprods-ai
- **HTML Case Study:** https://asimansari.com/projects/billprods-ai.html
- **Canonical Domain:** https://billprods-ai.asimansari.com

---

## 1. Problem & Architecture Overview

Retail consumers and independent shopkeepers struggle to track fluctuating inventory and wholesale costs over time because traditional expense apps record only total invoice sums (e.g., "$142.50 at Wholesale Depo"). They discard the granular item-level breakdown: SKU names, pack sizes, unit quantities, and per-item pricing.

### The BillProds AI Pipeline
```
[Physical Receipt / Bill]
          │
          ▼
[Camera / File Upload (PWA Client)]
          │
          ▼
[Asynchronous Vision Extraction (Gemini Multimodal API)]
          │ (JSON Schema Structured Output)
          ▼
[Deduplication & Entity Resolution (Levenshtein + Embedding Cosine)]
          │
          ▼
[Relational Storage & Indexing (PostgreSQL / SQLite + SQLAlchemy)]
          │
          ▼
[Item-Level Price History Ledger & Ingestion Dashboard]
```

---

## 2. Technical Stack & Ingestion Pipeline

- **Backend Framework:** Python 3.12, FastAPI (Asynchronous ASGI endpoints).
- **Vision Extraction:** Google Gemini Multimodal Vision API with strict Pydantic v2 structured output schemas.
- **Relational Ledger:** PostgreSQL (Production) / SQLite (Local development) with SQLAlchemy ORM and Alembic migrations.
- **Entity Resolution:** Levenshtein string distance heuristics paired with embedding similarity to unify noisy merchant abbreviations (e.g., `"ORG MILK 1GAL"` vs `"ORGANIC WHOLE MILK 1 GALLON"`).
- **Frontend Client:** Progressive Web App (PWA) with responsive mobile interface, service worker offline caching, and native camera capture.

---

## 3. Data Schema & Core Invariants

```json
{
  "invoice_id": "inv_20260927_0845a",
  "merchant": "Metro Wholesale Logistics",
  "timestamp": "2026-09-27T08:15:00Z",
  "currency": "USD",
  "total_amount": 184.20,
  "line_items": [
    {
      "raw_name": "ROASTED ALMONDS 500G",
      "canonical_sku": "sku_almonds_roasted_500g",
      "category": "dry_fruits_nuts",
      "quantity": 4,
      "unit_price": 6.50,
      "line_total": 26.00
    }
  ]
}
```

### System Invariants
1. **Mathematical Ledger Balance:** `sum(line_items.line_total) + tax + tips == total_amount` validated before insertion; flagged for manual review if variance exceeds $0.05.
2. **Immutable Price History:** Ingestion records are append-only. Unit price alterations create new timestamped points in the pricing time-series without mutating historical logs.
3. **Local Self-Hostability:** Complete codebase runs locally with single-command Docker Compose orchestration (`docker-compose up -d`).