bolade
447 lines
16 KiB
Python
447 lines
16 KiB
Python
import json
|
||
import logging
|
||
from typing import Any, Dict
|
||
|
||
import groq
|
||
from config import settings
|
||
from schemas import Receipt, Transaction
|
||
|
||
logger = logging.getLogger(__name__)
|
||
|
||
|
||
class LLMTaxAnalyzer:
|
||
"""
|
||
Uses LLM to intelligently apply tax rules based on context.
|
||
|
||
Implements four core tax rules:
|
||
1. Sales Tax Rule - Based on receipt location (shipping/billing address)
|
||
2. Foreign Exchange Rule - Handles currency mismatches
|
||
3. Depreciation Rule - Capital assets (based on user location)
|
||
4. Meals & Entertainment Rule - 50% tax deduction, 100% accounting deduction
|
||
"""
|
||
|
||
# Provincial tax rates for reference
|
||
PROVINCIAL_TAX_RATES = {
|
||
"ON": {"rate": 0.13, "name": "HST", "type": "Harmonized"},
|
||
"QC": {"rate": 0.14975, "name": "QST + GST", "type": "Combined"},
|
||
"BC": {"rate": 0.12, "name": "PST + GST", "type": "Combined"},
|
||
"AB": {"rate": 0.05, "name": "GST", "type": "Federal only"},
|
||
"SK": {"rate": 0.11, "name": "PST + GST", "type": "Combined"},
|
||
"MB": {"rate": 0.12, "name": "PST + GST", "type": "Combined"},
|
||
"NS": {"rate": 0.15, "name": "HST", "type": "Harmonized"},
|
||
"NB": {"rate": 0.15, "name": "HST", "type": "Harmonized"},
|
||
"NL": {"rate": 0.15, "name": "HST", "type": "Harmonized"},
|
||
"PE": {"rate": 0.15, "name": "HST", "type": "Harmonized"},
|
||
"NT": {"rate": 0.05, "name": "GST", "type": "Federal only"},
|
||
"NU": {"rate": 0.05, "name": "GST", "type": "Federal only"},
|
||
"YT": {"rate": 0.05, "name": "GST", "type": "Federal only"},
|
||
}
|
||
|
||
# CCA rates by asset class (simplified)
|
||
CCA_RATES = {
|
||
"vehicles": 0.30, # Class 10
|
||
"computer_equipment": 0.55, # Class 50
|
||
"furniture": 0.20, # Class 8
|
||
"buildings": 0.04, # Class 1
|
||
"machinery": 0.20, # Class 8
|
||
}
|
||
|
||
def __init__(self):
|
||
self.client = groq.Groq(api_key=settings.GROQ_API_KEY)
|
||
self.model = "llama-3.1-8b-instant"
|
||
self.max_retries = 3
|
||
|
||
def analyze_and_apply_tax_rules(
|
||
self,
|
||
receipt: Receipt,
|
||
transaction: Transaction,
|
||
user_location: str = "ON", # Default to Ontario
|
||
) -> Dict[str, Any]:
|
||
"""
|
||
Use LLM to intelligently analyze and apply all tax rules:
|
||
1. Sales tax based on receipt location (shipping/billing address priority)
|
||
2. Foreign exchange rules for currency mismatches
|
||
3. Depreciation rules for capital assets (based on user location)
|
||
4. Meals & Entertainment deduction rules
|
||
"""
|
||
|
||
# Prepare context for LLM
|
||
analysis_context = self._build_analysis_context(
|
||
receipt, transaction, user_location
|
||
)
|
||
|
||
# Get LLM analysis
|
||
llm_analysis = self._get_llm_tax_analysis(analysis_context)
|
||
|
||
# Parse and structure the results
|
||
structured_results = self._structure_analysis_results(
|
||
llm_analysis, receipt, transaction, user_location
|
||
)
|
||
|
||
return structured_results
|
||
|
||
def _build_analysis_context(
|
||
self, receipt: Receipt, transaction: Transaction, user_location: str
|
||
) -> str:
|
||
"""Build comprehensive context for LLM analysis"""
|
||
|
||
# Extract location information
|
||
receipt_location = self._extract_receipt_location(receipt)
|
||
user_province = user_location.upper()
|
||
|
||
# Build tax rates reference
|
||
tax_rates_info = json.dumps(self.PROVINCIAL_TAX_RATES, indent=2)
|
||
cca_rates_info = json.dumps(self.CCA_RATES, indent=2)
|
||
|
||
context = f"""
|
||
RECEIPT DETAILS:
|
||
- Vendor: {receipt.vendor}
|
||
- Amount: ${receipt.amount:.2f}
|
||
- Tax: ${receipt.tax:.2f}
|
||
- Currency: {receipt.currency}
|
||
- Date: {receipt.receipt_date.strftime("%Y-%m-%d")}
|
||
- Category: {receipt.category}
|
||
- Description: {receipt.description}
|
||
- Billing Address: {self._format_address(receipt.billing_address)}
|
||
- Shipping Address: {self._format_address(receipt.shipping_address)}
|
||
- Is Meals & Entertainment: {receipt.is_meals_entertainment}
|
||
|
||
TRANSACTION DETAILS:
|
||
- Vendor: {transaction.vendor}
|
||
- Amount: ${transaction.amount:.2f}
|
||
- Currency: {transaction.currency}
|
||
- Date: {transaction.transaction_date.strftime("%Y-%m-%d")}
|
||
- Notes: {transaction.notes}
|
||
- FX Rate: {transaction.fx_rate if transaction.fx_rate else "N/A"}
|
||
|
||
USER CONTEXT:
|
||
- User Location (Province): {user_province}
|
||
- User Province Tax Rate: {self.PROVINCIAL_TAX_RATES.get(user_province, {}).get("rate", 0.13) * 100}%
|
||
- User Tax Type: {self.PROVINCIAL_TAX_RATES.get(user_province, {}).get("name", "HST")}
|
||
|
||
RECEIPT LOCATION DETECTED:
|
||
{receipt_location}
|
||
|
||
PROVINCIAL TAX RATES REFERENCE:
|
||
{tax_rates_info}
|
||
|
||
CCA DEPRECIATION RATES BY ASSET CLASS:
|
||
{cca_rates_info}
|
||
"""
|
||
return context
|
||
|
||
def _extract_receipt_location(self, receipt: Receipt) -> str:
|
||
"""Extract and format receipt location information"""
|
||
|
||
# Priority: Use shipping address if available, then billing
|
||
location = (
|
||
receipt.shipping_address
|
||
if receipt.shipping_address
|
||
else receipt.billing_address
|
||
)
|
||
|
||
if location:
|
||
return f"""
|
||
- Province: {location.province}
|
||
- City: {location.city}
|
||
- Country: {location.country}
|
||
- Postal Code: {location.postal_code}
|
||
"""
|
||
else:
|
||
return "- No address information available (will use user location)"
|
||
|
||
def _format_address(self, address) -> str:
|
||
"""Format address for display"""
|
||
if address:
|
||
return f"{address.city}, {address.province}, {address.country} ({address.postal_code})"
|
||
return "Not provided"
|
||
|
||
def _get_llm_tax_analysis(self, context: str) -> str:
|
||
"""Get tax rule analysis from LLM"""
|
||
|
||
prompt = f"""
|
||
You are a Canadian tax expert analyzing a receipt-transaction match. Apply the following tax rules intelligently:
|
||
|
||
{context}
|
||
|
||
=== FOUR CORE TAX RULES ===
|
||
|
||
### 1. SALES TAX RULE
|
||
**Purpose**: Calculate and apply correct sales tax based on shipping and billing addresses.
|
||
|
||
**Key Principles**:
|
||
- When billing and shipping addresses are THE SAME: Apply sales tax based on that address location.
|
||
- When billing and shipping addresses are DIFFERENT: Apply sales tax based on the SHIPPING address.
|
||
- Tax rate is determined by the RECEIPT'S location, NOT the user's location (unless no receipt location).
|
||
|
||
**Scenario Examples**:
|
||
a) User in Ontario, Receipt from Quebec:
|
||
- Apply Quebec's tax rate (14.975% QST+GST), not Ontario's 13% HST
|
||
- The user's location is only for depreciation purposes
|
||
|
||
b) User in Ontario, Receipt from USA (New York):
|
||
- DO NOT apply Canadian sales tax
|
||
- This is an international transaction
|
||
- Flag for FX review instead
|
||
|
||
c) User in USA (New York), Receipt from California:
|
||
- Apply California's sales tax rate (receipt location)
|
||
- Not New York's rate (user location)
|
||
|
||
d) User in Ontario, Receipt has NO address information:
|
||
- DEFAULT to user's location (Ontario 13% HST)
|
||
- This is the fallback when receipt location is unknown
|
||
|
||
**Tax Calculation**:
|
||
- Compare calculated tax vs stated tax on receipt
|
||
- Flag discrepancies for review
|
||
|
||
### 2. FOREIGN EXCHANGE (FX) RULE
|
||
**Purpose**: Handle currency mismatches between receipts and transactions.
|
||
|
||
**Actions**:
|
||
- Identify when receipt currency ≠ transaction currency (e.g., USD vs CAD)
|
||
- Calculate the absolute discrepancy: |receipt_amount - transaction_amount|
|
||
- ALWAYS flag for manual review - DO NOT fetch exchange rates automatically
|
||
- If FX rate is provided in transaction data, note it but still require manual review
|
||
|
||
**Examples**:
|
||
- Transaction: USD $100, Receipt: CAD $125 → Discrepancy: $25, Flag for review
|
||
- The user must manually approve or adjust the FX difference
|
||
|
||
### 3. DEPRECIATION RULE
|
||
**Purpose**: Calculate depreciation for assets using two methods.
|
||
|
||
**Key Principle**: Depreciation is ALWAYS based on USER'S location, NOT receipt location.
|
||
|
||
**Asset Identification**:
|
||
- Only applies to capital assets: vehicles, equipment, furniture, buildings, machinery
|
||
- Identify from receipt category and description
|
||
- Typical threshold: Assets generally > $500
|
||
|
||
**Two Methods Required**:
|
||
a) **Straight-Line Depreciation** (for accounting purposes):
|
||
Formula: (Cost - Residual Value) / Useful Life
|
||
Example: Asset $10,000, 5-year life, $1,000 residual = $1,800/year
|
||
|
||
b) **CCA Depreciation** (for tax purposes - Canada):
|
||
Method: Declining Balance
|
||
Formula: Book Value × CCA Rate each year
|
||
Example: Truck $20,000, 30% CCA:
|
||
- Year 1: $20,000 × 30% = $6,000
|
||
- Year 2: ($20,000 - $6,000) × 30% = $4,200
|
||
- Continues declining each year
|
||
|
||
**CCA Classes** (Canada):
|
||
- Vehicles: 30% (Class 10)
|
||
- Computer Equipment: 55% (Class 50)
|
||
- Furniture/Machinery: 20% (Class 8)
|
||
- Buildings: 4% (Class 1)
|
||
|
||
### 4. MEALS & ENTERTAINMENT TAX DEDUCTION RULE
|
||
**Purpose**: Apply correct deductions for meals and entertainment expenses.
|
||
|
||
**Deduction Rules**:
|
||
- **For Tax Purposes**: Only 50% of total receipt amount is deductible
|
||
- **For Accounting Purposes**: 100% of total receipt amount is deductible
|
||
- **Sales Tax**: Full sales tax amount is deductible for accounting
|
||
|
||
**Example**:
|
||
- Receipt: $100 meal + $12 sales tax = $112 total
|
||
- **Tax Deduction**: $50 (50% of meal) + $12 (full tax) = $62
|
||
- **Accounting Deduction**: $100 (full meal) + $12 (full tax) = $112
|
||
|
||
=== LOCATION-BASED SCENARIO HANDLING ===
|
||
|
||
**When Receipt Location ≠ User Location**:
|
||
|
||
1. **Sales Tax**: Use RECEIPT's location for tax calculation
|
||
- Exception: If international (different country), no Canadian sales tax + flag FX
|
||
- Exception: If no location on receipt, use user's location as default
|
||
|
||
2. **Depreciation**: ALWAYS use USER's location for depreciation rules
|
||
- Receipt location is irrelevant for depreciation
|
||
- Apply user's country/province depreciation methods
|
||
|
||
3. **FX Handling**:
|
||
- If receipt currency ≠ transaction currency: Flag for manual review
|
||
- Do NOT automatically fetch or apply exchange rates
|
||
|
||
4. **Missing Location**:
|
||
- If receipt has no address: Default to user's location for sales tax
|
||
- Still apply user's location for depreciation
|
||
|
||
=== ANALYSIS REQUIRED ===
|
||
|
||
Provide a structured JSON response with the following format:
|
||
|
||
{{
|
||
"sales_tax": {{
|
||
"applicable_province": "XX",
|
||
"applicable_rate": 0.XX,
|
||
"tax_name": "HST/GST/PST/QST",
|
||
"calculated_tax": XX.XX,
|
||
"stated_tax": XX.XX,
|
||
"discrepancy": XX.XX,
|
||
"reason": "Detailed explanation: which address used (billing/shipping), why this location, which scenario applies",
|
||
"requires_review": true/false
|
||
}},
|
||
"foreign_exchange": {{
|
||
"currency_mismatch": true/false,
|
||
"receipt_currency": "XXX",
|
||
"transaction_currency": "XXX",
|
||
"receipt_amount": XX.XX,
|
||
"transaction_amount": XX.XX,
|
||
"discrepancy": XX.XX,
|
||
"requires_manual_review": true/false,
|
||
"reason": "Explanation of FX situation"
|
||
}},
|
||
"depreciation": {{
|
||
"is_capital_asset": true/false,
|
||
"asset_class": "category name or N/A",
|
||
"suggested_cca_rate": 0.XX,
|
||
"straight_line_applicable": true/false,
|
||
"cca_applicable": true/false,
|
||
"straight_line_example": "Brief calculation example if applicable",
|
||
"cca_example": "Brief calculation example if applicable",
|
||
"reason": "Why this is/isn't a capital asset, which CCA class, and why depreciation based on user's location"
|
||
}},
|
||
"meals_entertainment": {{
|
||
"is_meals_entertainment": true/false,
|
||
"tax_deduction_amount": XX.XX,
|
||
"accounting_deduction_amount": XX.XX,
|
||
"sales_tax_included": XX.XX,
|
||
"reason": "Explanation of M&E rule application"
|
||
}},
|
||
"confidence_adjustment": {{
|
||
"boost": 0.XX,
|
||
"reduce": 0.XX,
|
||
"reason": "Why confidence should be adjusted based on tax analysis"
|
||
}},
|
||
"overall_assessment": "Comprehensive summary: which rules applied, why, what location used for what purpose, and any required actions"
|
||
}}
|
||
|
||
**Critical Reminders**:
|
||
- Sales tax uses RECEIPT location (or user location if receipt has none)
|
||
- Depreciation ALWAYS uses USER location
|
||
- For different addresses, use SHIPPING address for sales tax
|
||
- International transactions: no Canadian tax + FX flag
|
||
- Be precise with all calculations
|
||
- Always explain your reasoning clearly
|
||
"""
|
||
|
||
try:
|
||
response = self.client.chat.completions.create(
|
||
model=self.model,
|
||
messages=[
|
||
{
|
||
"role": "system",
|
||
"content": "You are a Canadian tax expert. Analyze transactions and apply tax rules accurately. Always return valid JSON.",
|
||
},
|
||
{"role": "user", "content": prompt},
|
||
],
|
||
temperature=0.1, # Low temperature for consistent, factual responses
|
||
max_tokens=2000,
|
||
)
|
||
|
||
content = response.choices[0].message.content.strip()
|
||
logger.info(f"LLM tax analysis received: {len(content)} characters")
|
||
return content
|
||
|
||
except Exception as e:
|
||
logger.error(f"Error getting LLM tax analysis: {str(e)}")
|
||
return self._get_fallback_analysis()
|
||
|
||
def _get_fallback_analysis(self) -> str:
|
||
"""Return fallback analysis if LLM fails"""
|
||
return json.dumps(
|
||
{
|
||
"sales_tax": {
|
||
"applicable_province": "ON",
|
||
"applicable_rate": 0.13,
|
||
"tax_name": "HST",
|
||
"calculated_tax": 0.0,
|
||
"stated_tax": 0.0,
|
||
"discrepancy": 0.0,
|
||
"reason": "LLM analysis failed - using defaults",
|
||
"requires_review": True,
|
||
},
|
||
"foreign_exchange": {
|
||
"currency_mismatch": False,
|
||
"requires_manual_review": False,
|
||
"reason": "Analysis not available",
|
||
},
|
||
"depreciation": {
|
||
"is_capital_asset": False,
|
||
"reason": "Analysis not available",
|
||
},
|
||
"meals_entertainment": {
|
||
"is_meals_entertainment": False,
|
||
"reason": "Analysis not available",
|
||
},
|
||
"confidence_adjustment": {
|
||
"boost": 0.0,
|
||
"reduce": 0.1,
|
||
"reason": "LLM analysis failed - recommend manual review",
|
||
},
|
||
"overall_assessment": "Automatic analysis failed. Manual review recommended.",
|
||
}
|
||
)
|
||
|
||
def _structure_analysis_results(
|
||
self,
|
||
llm_response: str,
|
||
receipt: Receipt,
|
||
transaction: Transaction,
|
||
user_location: str,
|
||
) -> Dict[str, Any]:
|
||
"""Parse LLM response and structure it for application"""
|
||
|
||
try:
|
||
# Extract JSON from LLM response (may have markdown code blocks)
|
||
json_str = llm_response
|
||
if "```json" in llm_response:
|
||
json_str = llm_response.split("```json")[1].split("```")[0].strip()
|
||
elif "```" in llm_response:
|
||
json_str = llm_response.split("```")[1].split("```")[0].strip()
|
||
|
||
analysis = json.loads(json_str)
|
||
|
||
# Add metadata
|
||
analysis["metadata"] = {
|
||
"user_location": user_location,
|
||
"receipt_id": receipt.id,
|
||
"transaction_id": transaction.id,
|
||
"analysis_method": "LLM-based",
|
||
"model": self.model,
|
||
}
|
||
|
||
return analysis
|
||
|
||
except json.JSONDecodeError as e:
|
||
logger.error(f"Failed to parse LLM response as JSON: {str(e)}")
|
||
logger.error(f"LLM response was: {llm_response}")
|
||
|
||
# Return structured fallback
|
||
return {
|
||
"sales_tax": {
|
||
"requires_review": True,
|
||
"reason": "Failed to parse LLM response",
|
||
},
|
||
"foreign_exchange": {
|
||
"requires_manual_review": receipt.currency != transaction.currency
|
||
},
|
||
"depreciation": {"is_capital_asset": False},
|
||
"confidence_adjustment": {
|
||
"boost": 0.0,
|
||
"reduce": 0.15,
|
||
"reason": "Analysis parsing failed",
|
||
},
|
||
"overall_assessment": "Analysis failed. Manual review required.",
|
||
"error": str(e),
|
||
"metadata": {
|
||
"user_location": user_location,
|
||
"analysis_method": "fallback",
|
||
},
|
||
}
|