WeFinance: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

WeFinance Copilot is an AI-powered personal finance assistant. It uses Vision LLM (GPT-4o) for bill OCR, conversational AI for financial advice, and explainable AI for investment recommendations.

Key Architecture Decision: Originally used PaddleOCR, but migrated to GPT-4o Vision OCR for 100% recognition accuracy (vs 0% with synthetic images). This is the core technical innovation.

Project Status: Production-ready deployment. Live demo at https://wefinance-copilot.streamlit.app.

Deployment: Primary deployment on Streamlit Community Cloud with automatic CI/CD from main branch. See DEPLOY.md for container deployment options.

Essential Commands

Environment Setup

# Activate conda environment (REQUIRED before any command)
conda activate wefinance

# First-time setup
conda env create -f environment.yml  # Create environment
pip install -r requirements.txt      # Development tools (pytest-cov, etc.)

# Update environment after modifying environment.yml
conda env update -f environment.yml --prune

CRITICAL: Always activate conda activate wefinance before running any command. System Python won't have required packages.

Running the Application

# Standard mode (opens browser automatically)
streamlit run app.py --server.port 8501

# Background/headless mode
streamlit run app.py --server.port 8501 --server.headless true

Application opens at: http://localhost:8501

Testing

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_vision_ocr_service.py -v

# Run single test function
pytest tests/test_vision_ocr_service.py::test_extract_transactions_from_image_parses_mocked_response -v

# Run with coverage report
pytest --cov=modules --cov=services --cov=utils --cov-report=term-missing

# Generate HTML coverage report (opens htmlcov/index.html in browser)
pytest --cov=modules --cov=services --cov=utils --cov-report=html