TAX_OPTIMIZATION_README.md

Tax Optimization Feature - Documentation

Overview

The Kaanta Tax Assistant now includes a Tax Optimization Engine that analyzes user transactions (from Mono API and manual entry) and provides personalized tax-saving recommendations based on Nigerian tax legislation.

Architecture

Mono API Transactions + Manual Entry
    ↓
Transaction Classifier (AI-powered categorization)
    ↓
Transaction Aggregator (Summarizes for tax calculation)
    ↓
Tax Engine (Calculates baseline tax)
    ↓
Strategy Extractor (RAG queries tax acts for strategies)
    ↓
Optimization Engine (Simulates scenarios)
    ↓
Ranked Recommendations (with savings & citations)

Key Features

✅ Automatic Transaction Classification - Uses pattern matching + LLM to categorize bank transactions
✅ Tax Act Integration - Extracts strategies directly from Nigeria Tax Acts via RAG
✅ Scenario Simulation - Runs multiple "what-if" scenarios using your tax engine
✅ Legal Citations - Every recommendation backed by specific tax law sections
✅ Risk Assessment - Classifies strategies as low/medium/high risk
✅ Mono API Compatible - Works seamlessly with existing transaction data

Modules

1. transaction_classifier.py

Classifies transactions into tax categories:

• Income: employment_income, business_income, rental_income, investment_income
• Deductions: pension_contribution, nhf_contribution, life_insurance, rent_paid, union_dues

Key Features:

• Pattern-based classification using Nigerian bank narration patterns
• LLM fallback for ambiguous transactions
• Confidence scoring for each classification

2. transaction_aggregator.py

Aggregates classified transactions into tax calculation inputs:

• Converts Mono transactions → TaxEngine inputs
• Identifies missing deductions
• Provides income/deduction breakdowns

3. tax_strategy_extractor.py

Extracts optimization strategies from tax legislation:

• Uses RAG to query tax PDFs
• Generates strategies for different taxpayer profiles
• Includes legal citations and implementation steps

4. tax_optimizer.py

Main optimization engine:

• Orchestrates the entire optimization workflow
• Generates and simulates scenarios
• Ranks recommendations by savings potential

API Endpoint

POST /v1/optimize

Request:

{
  "user_id": "user123",
  "transactions": [
    {
      "type": "credit",
      "amount": 500000,
      "narration": "SALARY PAYMENT FROM ABC LTD",
      "date": "2025-01-31",
      "balance": 750000,
      "metadata": {
        "basic_salary": 300000,
        "housing_allowance": 120000,
        "transport_allowance": 60000,
        "bonus": 20000
      }
    },
    {
      "type": "debit",
      "amount": 40000,
      "narration": "PENSION CONTRIBUTION TO XYZ PFA",
      "date": "2025-01-31",
      "balance": 710000
    }
  ],
  "taxpayer_profile": {
    "taxpayer_type": "individual",
    "employment_status": "employed",
    "location": "Lagos"
  },
  "tax_year": 2025,
  "tax_type": "PIT",
  "jurisdiction": "state"
}

Response:

{
  "user_id": "user123",
  "tax_year": 2025,
  "baseline_tax_liability": 850000,
  "optimized_tax_liability": 720000,
  "total_potential_savings": 130000,
  "savings_percentage": 15.3,
  "total_annual_income": 6000000,
  "current_deductions": {
    "pension": 288000,
    "nhf": 90000,
    "life_insurance": 50000,
    "total": 428000
  },
  "recommendations": [
    {
      "rank": 1,
      "strategy_name": "Maximize Pension Contributions",
      "description": "Increase pension to 20% of gross income (₦1,200,000/year)",
      "annual_tax_savings": 50000,
      "optimized_tax": 800000,
      "implementation_steps": [
        "Contact your Pension Fund Administrator (PFA)",
        "Set up Additional Voluntary Contribution (AVC)",
        "Contribute up to ₦100,000 per month"
      ],
      "legal_citations": [
        "PITA s.20(1)(g)",
        "Pension Reform Act 2014"
      ],
      "risk_level": "low",
      "complexity": "easy",
      "confidence_score": 0.95
    }
  ],
  "transaction_summary": {
    "total_transactions": 24,
    "categorized": 22,
    "high_confidence": 20
  }
}

Usage Examples

Example 1: Basic Usage

import requests

response = requests.post("http://localhost:8000/v1/optimize", json={
    "user_id": "user123",
    "transactions": [
        {
            "type": "credit",
            "amount": 500000,
            "narration": "SALARY PAYMENT",
            "date": "2025-01-31"
        }
    ],
    "tax_year": 2025
})

result = response.json()
print(f"Potential savings: ₦{result['total_potential_savings']:,.0f}")

Example 2: With Full Profile

payload = {
    "user_id": "user456",
    "transactions": [...],  # Your Mono transactions
    "taxpayer_profile": {
        "taxpayer_type": "individual",
        "employment_status": "employed",
        "annual_income": 6000000,
        "has_rental_income": True,
        "location": "Lagos"
    },
    "tax_year": 2025
}

response = requests.post("http://localhost:8000/v1/optimize", json=payload)

Example 3: Run Example Script

# Make sure API is running
uvicorn orchestrator:app --reload --port 8000

# In another terminal
python example_optimize.py

Integration with Mono API

The optimizer is designed to work with your existing Mono integration:

# Pseudo-code for your backend
def optimize_user_taxes(user_id):
    # 1. Fetch transactions from Mono
    mono_transactions = mono_client.get_transactions(user_id)
    
    # 2. Fetch manual transactions from your DB
    manual_transactions = db.get_manual_transactions(user_id)
    
    # 3. Combine and send to optimizer
    all_transactions = mono_transactions + manual_transactions
    
    response = requests.post("http://localhost:8000/v1/optimize", json={
        "user_id": user_id,
        "transactions": all_transactions,
        "tax_year": 2025
    })
    
    return response.json()

Transaction Classification Patterns

The classifier recognizes Nigerian bank narration patterns:

Income:

• SALARY, WAGES, PAYROLL, EMPLOYMENT → employment_income
• SALES, REVENUE, INVOICE, CLIENT → business_income
• RENT RECEIVED, TENANT → rental_income
• DIVIDEND, INTEREST → investment_income

Deductions:

• PENSION, PFA, RSA → pension_contribution
• NHF, HOUSING FUND → nhf_contribution
• LIFE INSURANCE, POLICY PREMIUM → life_insurance
• RENT, LANDLORD → rent_paid
• UNION DUES, PROFESSIONAL FEES → union_dues

Optimization Strategies

The system extracts and applies these strategies:

For Individuals (PIT)

1. Maximize Pension Contributions - Up to 20% of gross income
2. Life Insurance Premiums - Tax-deductible
3. NHF Contributions - 2.5% of basic salary
4. Rent Relief (2026+) - 20% of rent, max ₦500K under NTA 2025
5. Union/Professional Dues - Tax-deductible

For Companies (CIT)

1. Small Company Exemption - 0% CIT if turnover ≤ ₦25M
2. Capital Allowances - Depreciation on qualifying assets
3. Expense Timing - Accelerate deductible expenses

Timing Strategies

1. Income Deferral - Delay income to lower tax year
2. Expense Acceleration - Bring forward deductible expenses

Configuration

The optimizer uses these settings from orchestrator.py:

RULES_PATH = "rules/rules_all.yaml"  # Tax rules
PDF_SOURCE = "data"                  # Tax acts PDFs
EMBED_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
GROQ_MODEL = "llama-3.1-8b-instant"

Requirements

• GROQ_API_KEY environment variable must be set
• Tax act PDFs in data/ folder
• RAG pipeline initialized (happens automatically on startup)

Testing

# Start the API
uvicorn orchestrator:app --reload --port 8000

# Run example
python example_optimize.py

# Check API docs
# Open http://localhost:8000/docs

Error Handling

The optimizer returns appropriate HTTP status codes:

• 200 - Success
• 503 - Optimizer not available (RAG not initialized)
• 500 - Optimization failed (check error message)

Performance

• Classification: ~100ms per transaction
• Aggregation: ~50ms for 1000 transactions
• Strategy Extraction: ~2-5 seconds (RAG queries)
• Scenario Simulation: ~500ms per scenario
• Total: ~10-20 seconds for typical optimization request

Limitations

1. Transaction Classification: ~85-95% accuracy depending on narration quality
2. Strategy Extraction: Limited to strategies documented in tax PDFs
3. Scenario Simulation: Currently limited to 5-10 scenarios
4. Tax Types: Primarily optimized for PIT; CIT support is basic

Future Enhancements

• Multi-year optimization planning
• Company structure optimization (sole proprietor vs limited company)
• Capital gains tax optimization
• VAT optimization strategies
• Integration with tax filing APIs
• Machine learning for better transaction classification
• User feedback loop to improve recommendations

Support

For issues or questions:

1. Check API docs: http://localhost:8000/docs
2. Review example scripts: example_optimize.py
3. Check logs for detailed error messages

License

Same as main Kaanta Tax Assistant project.