🧾 Smart Receipt Assistant

Enterprise-Grade Receipt OCR & Extraction Powered by PaddleOCR-VL + LangChain

English | 中文

---

🎯 One Token. Full Stack OCR + LLM Pipeline.

Powered by langchain-paddleocr - The Official LangChain Integration for PaddleOCR

---

✨ Why Smart Receipt Assistant?

🔍 Seal Recognition PaddleOCR-VL-1.5 Exclusive Auto-detect seal types for authenticity verification

🤖 Intelligent Extraction ERINE 4.5 Powered Structured JSON output with smart categorization

🔗 LangChain Native Production Ready Tool-based architecture with Agent support

---

🏗️ Architecture

---

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• uv (recommended) or pip

1. Get Your API Token

Visit PaddleOCR Official Website and register:

1. Click "API" button on the model service page
2. Get and copy your PaddleOCR-VL-1.5 and PP-OCRv5 credentials:
   • TOKEN (Access Token) - for API authentication
   • API_URL - Service endpoint address

💡 Tip: PaddleOCR supports free parsing of tens of thousands of document pages per day!

2. Token Note

⚠️ Important: ERINE LLM Token is the same as PaddleOCR Token - no extra setup needed!

With a single PaddleOCR Token, you can use both:

• ✅ PaddleOCR-VL-1.5 (OCR Recognition + Seal Detection)
• ✅ ERINE 4.5 (Intelligent Information Extraction)

3. Installation

# Install uv (if not installed)
pip install uv

# Clone the repository
git clone https://github.com/AIwork4me/smart-receipt-assistant.git
cd smart-receipt-assistant

# Install dependencies
uv sync

# Configure environment
cp .env.example .env
# Edit .env and fill in your PaddleOCR TOKEN and API_URL

# Launch Web UI
uv run python app.py

4. Configuration

Edit .env:

# PaddleOCR Token (from www.paddleocr.com)
PADDLEOCR_ACCESS_TOKEN=your_token_here
PADDLEOCR_API_URL=your_api_url_here

# ERINE uses the same token as PaddleOCR - no extra config needed!

---

📖 Usage

Web UI (Recommended)

uv run python app.py

Open http://localhost:7860 in your browser.

CLI

# Recognize single receipt
uv run python -m src.main recognize invoice.jpg

# Save results to JSON
uv run python -m src.main recognize invoice.jpg --output result.json

# Batch processing
uv run python -m src.main batch ./invoices/ --output ./results/

LangChain Agent API

from src.agents import create_receipt_agent

# Create agent with your API key
agent = create_receipt_agent(api_key="your_token")

# Process receipt
result = agent.process("invoice.jpg")
print(result["output"])

LangChain Tools

from src.tools import ReceiptOCRTool, ReceiptExtractionTool

# Use as LangChain tools
ocr_tool = ReceiptOCRTool(api_key="your_token")
result = ocr_tool.invoke({"file_path": "invoice.jpg"})
print(result["text"])

---

🔖 Supported Receipt Types

Type	OCR	Extraction	Seal Detection
VAT Special Invoice (增值税专用发票)	✅	✅	✅
VAT General Invoice (增值税普通发票)	✅	✅	✅
Train Ticket (火车票)	✅	✅	-
Taxi Receipt (出租车票)	✅	✅	-
Fixed Amount Invoice (定额发票)	✅	✅	✅
Other Receipts	✅	✅	✅

---

🔍 Seal Recognition Guide

Seal Type	Description	Verification Value
发票专用章 (Invoice Seal)	Official invoice seal	⭐⭐⭐ High - Strong authenticity indicator
财务专用章 (Finance Seal)	Finance department seal	⭐⭐ Medium - Supporting evidence
公章 (Company Seal)	Official company seal	⭐⭐ Medium - Supporting evidence
发票监制章 (Tax Authority Seal)	Pre-printed tax seal	⭐ Low - Present on all invoices

⚠️ Note: Seal recognition is an auxiliary verification method. For official verification, use the National Tax Verification Platform.

---

📦 Project Structure

smart-receipt-assistant/
├── app.py                      # Gradio entry point
├── pyproject.toml              # Project config (uv)
├── src/
│   ├── main.py                 # CLI entry
│   ├── config.py               # Configuration
│   ├── langchain_compat.py     # LangChain compatibility layer
│   ├── chains/                 # LangChain Chains
│   │   ├── ocr_chain.py        # OCR chain (langchain-paddleocr)
│   │   ├── extraction_chain.py # Information extraction
│   │   └── classification_chain.py
│   ├── tools/                  # LangChain Tools
│   │   ├── ocr_tool.py         # ReceiptOCRTool
│   │   ├── extraction_tool.py  # ReceiptExtractionTool
│   │   └── classification_tool.py
│   ├── agents/                 # LangChain Agents
│   │   └── receipt_agent.py    # ReceiptAgentExecutor
│   ├── models/                 # Pydantic models
│   └── utils/                  # Utilities
├── examples/                   # Example code & samples
├── tests/                      # Test suite
└── docs/                       # Documentation

---

🧪 Development

Run Tests

uv run pytest tests/ -v

Code Style

This project uses:

• Type hints (Python 3.10+)
• Pydantic v2 for data validation
• LangChain 1.0+ API

---

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

---

📄 License

MIT License

---

🙏 Acknowledgements

• PaddleOCR - PaddlePaddle OCR Framework
• langchain-paddleocr - Official LangChain Integration
• LangChain - LLM Application Framework
• Baidu AIStudio - AI Development Platform

---

📞 Contact

Scan to follow for more AI productivity tips!

---

⬆ Back to Top

Made with ❤️ by AIwork4me