Files · xAI Grok Expense Report Extraction for SMB Finance

# xAI Grok Expense Report Extraction for SMB Finance
 
> Automatically extract line items, totals, and merchant names from scanned receipts and invoices using xAI Grok, then export to CSV and store in S3.
 
Small and medium businesses often manage expenses through paper receipts and PDF invoices. Manually entering this data into spreadsheets is error-prone and time-consuming. This application provides an API endpoint that accepts scanned documents, extracts structured expense data using Grok's AI, validates quality, and exports to CSV — all within a configurable budget.
 
## Architecture
 
```
Upload (JPEG/PNG/PDF) → OCR (tesseract.js / unpdf) → Grok extraction → JSON repair → Quality gate → CSV export → S3 storage
```
 
1. **POST /api/upload** accepts a multipart file upload
2. **OCR pipeline** extracts raw text using tesseract.js (images) or unpdf (PDFs) via the REAA media pipeline
3. **Grok extraction** parses the text into structured expenses using `@ai-sdk/xai` + `ai`
4. **JSON repair** fixes malformed Grok output via `@reaatech/structured-repair-core`
5. **Quality gate** validates accuracy against a golden reference dataset
6. **CSV export** flattens expenses into spreadsheet-ready rows
7. **S3 storage** persists results and originals (non-fatal on failure)
 
## Prerequisites
 
| Requirement | Version |
|-------------|---------|
| Node.js | >= 22 |
| pnpm | 10.x |
| xAI API key | — |
| AWS S3 bucket | — |
 
## Environment Variables
 
| Variable | Description | Default |
|----------|-------------|---------|
| `XAI_API_KEY` | xAI API key for Grok access | — |
| `AWS_REGION` | AWS region for S3 | `us-east-1` |
| `AWS_ACCESS_KEY_ID` | AWS access key | — |
| `AWS_SECRET_ACCESS_KEY` | AWS secret key | — |
| `S3_BUCKET_NAME` | S3 bucket for uploads | — |
| `DEFAULT_DAILY_BUDGET` | Daily Grok API budget in USD | `5.0` |
 
## Quick Start
 
```bash
pnpm install
cp .env.example .env
# Edit .env with your credentials
pnpm dev
```
 
Upload a test receipt:
 
```bash
curl -X POST http://localhost:3000/api/upload \
  -F "file=@receipt.jpg"
```
 
Check pipeline metrics:
 
```bash
curl http://localhost:3000/api/upload
```
 
## Packages
 
| Package | Version | Role |
|---------|---------|------|
| `@ai-sdk/xai` | 3.0.92 | xAI Grok model provider |
| `ai` | 6.0.192 | AI SDK — `generateObject` for structured output |
| `@aws-sdk/client-s3` | 3.1056.0 | S3 upload/download |
| `@reaatech/media-pipeline-mcp-doc-extraction` | 0.3.0 | Document OCR pipeline framework |
| `@reaatech/structured-repair-core` | 1.0.0 | Malformed JSON repair |
| `@reaatech/classifier-evals` | 0.1.0 | Quality gate evaluation and PII redaction |
| `@reaatech/llm-cost-telemetry` | 0.1.0 | Cost tracking and budget enforcement |
| `sharp` | 0.34.5 | Image preprocessing (resize, grayscale) |
| `tesseract.js` | 7.0.0 | OCR engine for images |
| `unpdf` | 1.6.2 | PDF text extraction |
| `zod` | 3.25.76 | Runtime schema validation |
| `next` | 16.2.6 | Web framework |
 
## API Reference
 
### POST /api/upload
 
Upload a receipt or invoice document for expense extraction.
 
**Request:** multipart/form-data with a `file` field.
 
**Supported MIME types:** `image/jpeg`, `image/png`, `image/tiff`, `application/pdf`
 
**Size limit:** 20 MB
 
**Response (200):**
```json
{
  "success": true,
  "data": {
    "expenses": [{ "merchantName": "...", "total": 123.45, ... }],
    "rawGrokResponse": "...",
    "repairApplied": false,
    "qualityPassed": true,
    "costUsd": 0.042,
    "processingTimeMs": 2345,
    "csvContent": "merchantName,invoiceDate,..."
  }
}
```
 
**Error responses:** 400 (missing/bad file), 413 (too large), 500 (pipeline failure)
 
### GET /api/upload
 
Return pipeline metrics.
 
```json
{ "totalProcessed": 5, "totalCost": 0.21 }
```
 
## License
 
MIT — see [LICENSE](./LICENSE).