Deploy AI Tax Reform API

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for caching
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application code
+COPY . .
+
+# Preload the sentence-transformers model during build
+RUN python -c "from sentence_transformers import SentenceTransformer; SentenceTransformer('sentence-transformers/all-mpnet-base-v2')"
+
+# Expose port
+EXPOSE 7860
+
+# Run with gunicorn
+CMD ["gunicorn", "--config", "gunicorn.conf.py", "app:app"]

app.py

@@ -0,0 +1,541 @@
+"""
+AI Tax Reform API - Backend Service
+
+A comprehensive Flask API for Nigerian tax calculations and AI-powered Q&A
+about Nigerian tax law based on the Nigeria Tax Act 2025.
+"""
+
+from flask import Flask, request, jsonify, g
+from flask_cors import CORS
+from flask_limiter import Limiter
+from flask_limiter.util import get_remote_address
+from dotenv import load_dotenv
+from pathlib import Path
+import os
+import time
+import logging
+import re
+from functools import wraps
+from typing import Any, Callable, Dict, Optional, Tuple
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
+)
+logger = logging.getLogger(__name__)
+
+load_dotenv()
+
+# ============================================================================
+# App Configuration
+# ============================================================================
+
+app = Flask(__name__)
+app.config['JSON_SORT_KEYS'] = False
+app.config['MAX_CONTENT_LENGTH'] = 1 * 1024 * 1024  # 1MB max request size
+
+# CORS Configuration - Secure defaults
+allowed_origins = os.getenv("CORS_ORIGINS", "").strip()
+if allowed_origins:
+    origins = [o.strip() for o in allowed_origins.split(",") if o.strip()]
+else:
+    origins = ["http://localhost:3000", "http://localhost:7860"]
+
+CORS(app, origins=origins, supports_credentials=True)
+
+# Rate Limiting
+limiter = Limiter(
+    app=app,
+    key_func=get_remote_address,
+    default_limits=["200 per day", "50 per hour"],
+    storage_uri="memory://",
+)
+
+# ============================================================================
+# Imports (after app initialization)
+# ============================================================================
+
+from src.tax_calculator import calculate_tax, get_tax_summary, TaxCalculationError
+from scripts.query_qa import load_vectorstore, query
+from scripts.qa_service import generate_answer, verify_answer
+import threading
+
+# ============================================================================
+# Vectorstore Cache
+# ============================================================================
+
+_vectorstore_cache: Optional[Tuple[Any, Any]] = None
+_vectorstore_loading = False
+_vectorstore_lock = threading.Lock()
+
+
+def preload_vectorstore():
+    """Preload vectorstore in background thread (embeddings use HF API, no local model)."""
+    global _vectorstore_cache, _vectorstore_loading
+    with _vectorstore_lock:
+        if _vectorstore_cache is None and not _vectorstore_loading:
+            _vectorstore_loading = True
+    
+    if _vectorstore_loading and _vectorstore_cache is None:
+        try:
+            logger.info("Background loading vectorstore...")
+            _vectorstore_cache = load_vectorstore()
+            logger.info("Vectorstore preloaded successfully (using HF API for embeddings)")
+        except Exception as e:
+            logger.error(f"Background preload failed: {e}")
+        finally:
+            _vectorstore_loading = False
+
+
+def get_vectorstore() -> Tuple[Any, Any]:
+    """Load and cache vectorstore with thread-safe initialization."""
+    global _vectorstore_cache
+    if _vectorstore_cache is None:
+        logger.info("Loading vectorstore...")
+        try:
+            _vectorstore_cache = load_vectorstore()
+            logger.info("Vectorstore loaded successfully")
+        except Exception as e:
+            logger.error(f"Failed to load vectorstore: {e}")
+            raise
+    return _vectorstore_cache
+
+
+# ============================================================================
+# Input Validation & Security
+# ============================================================================
+
+def sanitize_string(text: str, max_length: int = 2000) -> str:
+    """Sanitize user input string."""
+    if not isinstance(text, str):
+        return ""
+    # Remove null bytes and control characters (except newlines/tabs)
+    text = re.sub(r'[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]', '', text)
+    # Limit length
+    return text[:max_length].strip()
+
+
+def validate_numeric(value: Any, field_name: str, min_val: float = 0, max_val: float = 1e15) -> float:
+    """Validate and convert numeric input."""
+    if value is None:
+        raise ValueError(f"'{field_name}' is required")
+    try:
+        num = float(value)
+        if num < min_val or num > max_val:
+            raise ValueError(f"'{field_name}' must be between {min_val:,.0f} and {max_val:,.0f}")
+        return num
+    except (TypeError, ValueError):
+        raise ValueError(f"'{field_name}' must be a valid number")
+
+
+def validate_positive_int(value: Any, field_name: str, min_val: int = 1, max_val: int = 20) -> int:
+    """Validate positive integer input."""
+    try:
+        num = int(value)
+        if num < min_val or num > max_val:
+            raise ValueError(f"'{field_name}' must be between {min_val} and {max_val}")
+        return num
+    except (TypeError, ValueError):
+        raise ValueError(f"'{field_name}' must be a valid integer")
+
+
+# ============================================================================
+# Error Handlers
+# ============================================================================
+
+class APIError(Exception):
+    """Custom API exception with status code."""
+    def __init__(self, message: str, status_code: int = 400, details: Optional[str] = None):
+        self.message = message
+        self.status_code = status_code
+        self.details = details
+        super().__init__(message)
+
+
+@app.errorhandler(APIError)
+def handle_api_error(error: APIError):
+    """Handle custom API errors."""
+    response = {"error": error.message}
+    if error.details and app.debug:
+        response["details"] = error.details
+    return jsonify(response), error.status_code
+
+
+@app.errorhandler(429)
+def handle_rate_limit(e):
+    """Handle rate limit exceeded."""
+    return jsonify({
+        "error": "Rate limit exceeded",
+        "message": "Too many requests. Please try again later."
+    }), 429
+
+
+@app.errorhandler(413)
+def handle_large_request(e):
+    """Handle request too large."""
+    return jsonify({
+        "error": "Request too large",
+        "message": "The request payload exceeds the maximum allowed size."
+    }), 413
+
+
+@app.errorhandler(404)
+def handle_not_found(e):
+    """Handle page not found errors."""
+    return jsonify({
+        "error": "Endpoint not found",
+        "message": "The requested endpoint does not exist. Check the API documentation at the root endpoint.",
+        "available_endpoints": ["/health", "/calculate", "/retrieve", "/qa", "/aqa"]
+    }), 404
+
+
+@app.errorhandler(500)
+def handle_internal_error(e):
+    """Handle internal server errors."""
+    logger.exception("Internal server error")
+    return jsonify({
+        "error": "Internal server error",
+        "message": "An unexpected error occurred. Please try again later."
+    }), 500
+
+
+@app.errorhandler(Exception)
+def handle_unexpected_error(e):
+    """Catch-all handler for any unhandled exceptions."""
+    logger.exception(f"Unhandled exception: {e}")
+    return jsonify({
+        "error": "An unexpected error occurred",
+        "message": str(e) if app.debug else "Please try again later."
+    }), 500
+
+
+# ============================================================================
+# Request Logging Middleware
+# ============================================================================
+
+@app.before_request
+def before_request():
+    """Log request and set start time."""
+    g.start_time = time.time()
+
+
+@app.after_request
+def after_request(response):
+    """Log response time."""
+    if hasattr(g, 'start_time'):
+        elapsed = (time.time() - g.start_time) * 1000
+        logger.info(f"{request.method} {request.path} - {response.status_code} - {elapsed:.2f}ms")
+    return response
+
+
+# ============================================================================
+# API Routes
+# ============================================================================
+
+@app.route("/health", methods=["GET"])
+@limiter.exempt
+def health():
+    """Health check endpoint for monitoring."""
+    return jsonify({
+        "status": "healthy",
+        "service": "AI Tax Reform API",
+        "version": "2.0.0",
+        "timestamp": time.time()
+    }), 200
+
+
+@app.route("/calculate", methods=["POST"])
+@limiter.limit("30 per minute")
+def calculate_endpoint():
+    """
+    Calculate Nigerian personal income tax.
+    
+    Request JSON:
+        - income (float, required): Gross annual income in NGN
+        - allowances (float, optional): Non-taxable allowances
+        - reliefs (float, optional): Tax reliefs
+        - pension (float, optional): Pension contribution
+        - include_cra (bool, optional): Include Consolidated Relief Allowance (default: true)
+    
+    Returns:
+        JSON with tax calculation breakdown
+    """
+    try:
+        data = request.get_json() or {}
+        
+        # Validate inputs
+        income = validate_numeric(data.get("income"), "income")
+        allowances = validate_numeric(data.get("allowances", 0), "allowances", min_val=0)
+        reliefs = validate_numeric(data.get("reliefs", 0), "reliefs", min_val=0)
+        pension = validate_numeric(data.get("pension", 0), "pension", min_val=0)
+        include_cra = bool(data.get("include_cra", True))
+        
+        # Calculate tax using the improved calculator
+        result = calculate_tax(
+            annual_income=income,
+            allowances=allowances,
+            reliefs=reliefs,
+            pension_contribution=pension,
+            include_cra=include_cra
+        )
+        
+        return jsonify(get_tax_summary(result)), 200
+        
+    except ValueError as e:
+        raise APIError(str(e), 400)
+    except TaxCalculationError as e:
+        raise APIError(str(e), 400)
+    except Exception as e:
+        logger.exception("Tax calculation failed")
+        raise APIError("Tax calculation failed", 500)
+
+
+@app.route("/retrieve", methods=["POST"])
+@limiter.limit("20 per minute")
+def retrieve():
+    """
+    Retrieve relevant document chunks from the tax law knowledge base.
+    
+    Request JSON:
+        - query (string, required): Search query
+        - top_k (int, optional): Number of results to return (1-20, default: 5)
+    
+    Returns:
+        JSON with matching document chunks
+    """
+    try:
+        payload = request.get_json() or {}
+        
+        query_text = sanitize_string(payload.get("query", ""))
+        if not query_text or len(query_text) < 2:
+            raise APIError("Query must be at least 2 characters", 400)
+        
+        top_k = validate_positive_int(payload.get("top_k", 5), "top_k", min_val=1, max_val=20)
+        
+        index, docs = get_vectorstore()
+        results = query(index, docs, query_text, top_k=top_k)
+        
+        return jsonify({
+            "query": query_text,
+            "count": len(results),
+            "results": results
+        }), 200
+        
+    except APIError:
+        raise
+    except Exception as e:
+        logger.exception("Retrieval failed")
+        raise APIError("Document retrieval failed", 500)
+
+
+@app.route("/qa", methods=["POST"])
+@limiter.limit("15 per minute")
+def qa():
+    """
+    Answer questions about Nigerian tax law using RAG (Retrieval-Augmented Generation).
+    
+    Request JSON:
+        - query (string, required): Question to answer
+        - top_k (int, optional): Number of context documents (1-8, default: 3)
+        - prefer_grok (bool, optional): Prefer Groq/Grok model (default: true)
+        - fast_mode (bool, optional): Return sources without LLM generation (default: false)
+    
+    Returns:
+        JSON with AI-generated answer and source documents
+    """
+    try:
+        payload = request.get_json() or {}
+        
+        query_text = sanitize_string(payload.get("query", ""))
+        if not query_text or len(query_text) < 2:
+            raise APIError("Query must be at least 2 characters", 400)
+        
+        # Default to 3 docs instead of 5 for faster response
+        top_k = validate_positive_int(payload.get("top_k", 3), "top_k", min_val=1, max_val=8)
+        prefer_grok = bool(payload.get("prefer_grok", True))
+        fast_mode = bool(payload.get("fast_mode", False))
+        
+        # Retrieve relevant context with timeout handling
+        try:
+            index, docs = get_vectorstore()
+            results = query(index, docs, query_text, top_k=top_k)
+        except Exception as ve:
+            logger.error(f"Vectorstore query failed: {ve}")
+            raise APIError("Search service temporarily unavailable", 503)
+        
+        if not results:
+            return jsonify({
+                "answer": "I couldn't find relevant information about this topic in the tax documentation. Please try rephrasing your question.",
+                "model": "none",
+                "sources": []
+            }), 200
+        
+        # Fast mode: return sources with excerpt instead of calling slow LLM
+        if fast_mode:
+            top_text = results[0].get("text", "")[:800]
+            return jsonify({
+                "query": query_text,
+                "answer": f"**From the Nigeria Tax Act 2025:**\n\n{top_text}\n\n---\n*[Fast mode - showing direct excerpt from source documents]*",
+                "model": "fast",
+                "sources": results
+            }), 200
+        
+        # Generate answer with shorter timeout
+        try:
+            answer, model_used, _ = generate_answer(query_text, results, prefer_grok=prefer_grok, timeout=20)
+        except Exception as ge:
+            logger.error(f"Answer generation failed: {ge}")
+            # Return sources even if generation fails
+            return jsonify({
+                "answer": "I found relevant documents but couldn't generate a complete answer. Here are the key sections from the tax law that may help:",
+                "model": "fallback",
+                "sources": results
+            }), 200
+        
+        return jsonify({
+            "query": query_text,
+            "answer": answer,
+            "model": model_used,
+            "sources": results
+        }), 200
+        
+    except APIError:
+        raise
+    except Exception as e:
+        logger.exception("QA processing failed")
+        raise APIError("Question answering failed. Please try again.", 500)
+
+
+@app.route("/aqa", methods=["POST"])
+@limiter.limit("10 per minute")
+def aqa():
+    """
+    Answer questions with verification (Assured QA).
+    
+    Same as /qa but includes answer verification step for higher accuracy.
+    
+    Request JSON:
+        - query (string, required): Question to answer
+        - top_k (int, optional): Number of context documents (1-10, default: 5)
+        - prefer_grok (bool, optional): Prefer Groq/Grok model (default: true)
+    
+    Returns:
+        JSON with AI-generated answer, verification result, and source documents
+    """
+    try:
+        payload = request.get_json() or {}
+        
+        query_text = sanitize_string(payload.get("query", ""))
+        if not query_text or len(query_text) < 2:
+            raise APIError("Query must be at least 2 characters", 400)
+        
+        top_k = validate_positive_int(payload.get("top_k", 5), "top_k", min_val=1, max_val=10)
+        prefer_grok = bool(payload.get("prefer_grok", True))
+        
+        # Retrieve relevant context
+        index, docs = get_vectorstore()
+        results = query(index, docs, query_text, top_k=top_k)
+        
+        if not results:
+            return jsonify({
+                "answer": "I couldn't find relevant information about this topic in the tax documentation.",
+                "model": "none",
+                "verification": {"score": 0, "reason": "No relevant documents found"},
+                "verified": False,
+                "sources": []
+            }), 200
+        
+        # Generate answer
+        answer, model_used, _ = generate_answer(query_text, results, prefer_grok=prefer_grok)
+        
+        # Verify answer
+        try:
+            verification = verify_answer(answer, query_text, results, prefer_grok=prefer_grok)
+            
+            # Parse verification result
+            verified = False
+            if isinstance(verification, dict):
+                score = verification.get("score", 0)
+                verified = score >= 0.7 if isinstance(score, (int, float)) else False
+            elif isinstance(verification, str):
+                # Try to extract score from string response
+                import json
+                try:
+                    verification = json.loads(verification)
+                    score = verification.get("score", 0)
+                    verified = score >= 0.7 if isinstance(score, (int, float)) else False
+                except json.JSONDecodeError:
+                    verification = {"raw": verification, "score": 0}
+                    verified = "accurate" in verification.get("raw", "").lower()
+        except Exception as ve:
+            logger.warning(f"Verification failed: {ve}")
+            verification = {"error": "Verification unavailable"}
+            verified = False
+        
+        return jsonify({
+            "query": query_text,
+            "answer": answer,
+            "model": model_used,
+            "verification": verification,
+            "verified": verified,
+            "sources": results
+        }), 200
+        
+    except APIError:
+        raise
+    except Exception as e:
+        logger.exception("AQA processing failed")
+        raise APIError("Verified question answering failed. Please try again.", 500)
+
+
+# ============================================================================
+# API Documentation Endpoint
+# ============================================================================
+
+@app.route("/", methods=["GET"])
+@limiter.exempt
+def api_docs():
+    """Return API documentation."""
+    return jsonify({
+        "name": "AI Tax Reform API",
+        "version": "2.0.0",
+        "description": "AI-powered Nigerian tax calculator and Q&A service",
+        "endpoints": {
+            "GET /health": "Health check",
+            "POST /calculate": "Calculate personal income tax",
+            "POST /retrieve": "Retrieve relevant tax documents",
+            "POST /qa": "Ask questions about tax law",
+            "POST /aqa": "Ask questions with answer verification"
+        },
+        "documentation": "https://github.com/your-repo/AI-TAX-REFORM#readme"
+    }), 200
+
+
+# ============================================================================
+# Application Startup
+# ============================================================================
+
+def start_background_tasks():
+    """Start background tasks after app is ready."""
+    # Preload vectorstore in background after 2 seconds
+    def delayed_preload():
+        import time
+        time.sleep(2)
+        preload_vectorstore()
+    
+    thread = threading.Thread(target=delayed_preload, daemon=True)
+    thread.start()
+
+
+if __name__ == "__main__":
+    port = int(os.getenv("PORT", 7860))
+    debug = os.getenv("FLASK_ENV") == "development"
+    
+    logger.info(f"Starting AI Tax Reform API v2.0.0 on port {port}")
+    logger.info(f"Allowed origins: {origins}")
+    
+    # Start background preloading
+    start_background_tasks()
+    
+    app.run(host="0.0.0.0", port=port, debug=debug)

gunicorn.conf.py

@@ -0,0 +1,54 @@
+"""
+Gunicorn Configuration for AI Tax Reform API
+"""
+
+import multiprocessing
+import os
+
+# Server socket
+bind = f"0.0.0.0:{os.getenv('PORT', '7860')}"
+backlog = 2048
+
+# Worker processes
+workers = int(os.getenv('GUNICORN_WORKERS', min(multiprocessing.cpu_count() * 2 + 1, 4)))
+worker_class = "sync"
+worker_connections = 1000
+timeout = 120
+keepalive = 5
+
+# Request handling
+max_requests = 1000
+max_requests_jitter = 50
+
+# Logging
+accesslog = "-"
+errorlog = "-"
+loglevel = os.getenv('LOG_LEVEL', 'info')
+access_log_format = '%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s" %(D)s'
+
+# Process naming
+proc_name = "ai-tax-reform-api"
+
+# Server mechanics
+preload_app = True
+daemon = False
+
+# Security
+limit_request_line = 4094
+limit_request_fields = 100
+limit_request_field_size = 8190
+
+
+def on_starting(server):
+    """Preload models before workers fork."""
+    import logging
+    logger = logging.getLogger(__name__)
+    logger.info("Preloading sentence-transformers model...")
+    try:
+        from sentence_transformers import SentenceTransformer
+        model = SentenceTransformer("sentence-transformers/all-mpnet-base-v2")
+        # Warm up with a test encode
+        model.encode(["test"], show_progress_bar=False)
+        logger.info("Model preloaded successfully")
+    except Exception as e:
+        logger.error(f"Model preload failed: {e}")

requirements.txt

@@ -0,0 +1,18 @@
+# Core Framework
+flask==3.1.2
+flask-cors==4.0.0
+flask-limiter==3.5.0
+python-dotenv==1.0.0
+gunicorn==21.2.0
+
+# Vector Store & Embeddings
+faiss-cpu==1.13.2
+sentence-transformers==2.2.2
+
+# Document Processing
+PyPDF2==3.0.1
+
+# Utilities
+requests==2.31.0
+tqdm==4.66.1
+numpy>=1.24.0

scripts/ingest_pdf.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python
+"""Ingest PDF, chunk text, build FAISS index and save metadata using HF Inference API.
+Usage: python scripts/ingest_pdf.py --pdf data/raw/Nigeria-Tax-Act-2025.pdf
+"""
+import argparse
+import os
+import pickle
+from pathlib import Path
+
+from dotenv import load_dotenv, dotenv_values
+load_dotenv()
+
+import faiss
+import numpy as np
+import requests
+from PyPDF2 import PdfReader
+from tqdm import tqdm
+
+
+def chunk_text(text, chunk_size=500, overlap=100):
+    """Chunk text with overlap."""
+    start = 0
+    length = len(text)
+    while start < length:
+        end = min(start + chunk_size, length)
+        yield text[start:end]
+        start = end - overlap if end < length else end
+
+
+def embed_text_hf(texts, model_id="nvidia/llama-embed-nemotron-8b", api_token=None):
+    """Call HF Inference API to embed texts."""
+    if api_token is None:
+        raise Exception("HF_TOKEN not found. Please set HF_TOKEN in your .env or environment variables.")
+    api_url = f"https://router.huggingface.co/models/{model_id}"
+    headers = {"Authorization": f"Bearer {api_token}"}
+    
+    payload = {"inputs": texts}
+    response = requests.post(api_url, json=payload, headers=headers, timeout=60)
+    
+    if response.status_code != 200:
+        # Provide clearer error for 401 Unauthorized
+        if response.status_code == 401:
+            raise Exception("HF API error 401: Unauthorized. Check your HF_TOKEN and model access permissions.")
+        raise Exception(f"HF API error {response.status_code}: {response.text}")
+    
+    embeddings = response.json()
+    if isinstance(embeddings, dict) and "error" in embeddings:
+        raise Exception(f"HF API error: {embeddings['error']}")
+    
+    return np.array(embeddings, dtype=np.float32)
+
+
+# Local embedder using sentence-transformers
+def embed_text_local(texts, model_name="sentence-transformers/all-mpnet-base-v2"):
+    """Embed texts locally using sentence-transformers."""
+    try:
+        from sentence_transformers import SentenceTransformer
+    except Exception as e:
+        raise Exception("Local sentence-transformers not installed. Install it with `pip install sentence-transformers`.")
+    model = SentenceTransformer(model_name)
+    embs = model.encode(texts, show_progress_bar=False, convert_to_numpy=True)
+    return np.array(embs, dtype=np.float32)
+
+
+def main(pdf_path, persist_dir="vectorstore", model_id="sentence-transformers/all-mpnet-base-v2", batch_size=8, api_token=None):
+    pdf_path = Path(pdf_path)
+    assert pdf_path.exists(), f"PDF not found: {pdf_path}"
+    persist_dir = Path(persist_dir)
+    persist_dir.mkdir(parents=True, exist_ok=True)
+
+    # Allow explicit token via argument, otherwise use env or .env
+    if api_token is None:
+        env_vars = dotenv_values()
+        api_token = os.getenv("HF_TOKEN") or env_vars.get("HF_TOKEN")
+
+    reader = PdfReader(str(pdf_path))
+    pages = [p.extract_text() or "" for p in reader.pages]
+
+    docs = []
+    for i, page_text in enumerate(pages, start=1):
+        for j, chunk in enumerate(chunk_text(page_text)):
+            docs.append({
+                "text": chunk.strip(),
+                "source": pdf_path.name,
+                "page": i,
+                "chunk_id": f"p{i}_c{j}",
+            })
+
+    if not docs:
+        print("No text extracted from PDF.")
+        return
+
+    texts = [d["text"] for d in docs]
+    print(f"Creating embeddings for {len(texts)} chunks using {model_id}...")
+
+    # Embed in batches to avoid timeout
+    embeddings_list = []
+    for batch_start in tqdm(range(0, len(texts), batch_size)):
+        batch_end = min(batch_start + batch_size, len(texts))
+        batch_texts = texts[batch_start:batch_end]
+            # Use local sentence-transformers if model_id points to sentence-transformers namespace
+        if model_id.startswith("sentence-transformers/"):
+            batch_embs = embed_text_local(batch_texts, model_id)
+        else:
+            batch_embs = embed_text_hf(batch_texts, model_id, api_token)
+        embeddings_list.append(batch_embs)
+
+    embeddings = np.vstack(embeddings_list)
+
+    # Normalize for cosine-similarity via inner product
+    norms = (embeddings**2).sum(axis=1, keepdims=True) ** 0.5
+    norms[norms == 0] = 1.0
+    embeddings = embeddings / norms
+
+    dim = embeddings.shape[1]
+    index = faiss.IndexFlatIP(dim)
+    index.add(embeddings)
+
+    faiss.write_index(index, str(persist_dir / "faiss_index.bin"))
+
+    with open(persist_dir / "metadata.pkl", "wb") as f:
+        pickle.dump(docs, f)
+
+    print("Vectorstore saved to:", persist_dir)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--pdf", required=True, help="Path to PDF to ingest")
+    parser.add_argument("--persist_dir", default="vectorstore")
+    parser.add_argument("--model", default="nvidia/llama-embed-nemotron-8b")
+    parser.add_argument("--batch_size", type=int, default=8)
+    parser.add_argument("--hf_token", default=None, help="Hugging Face token (overrides HF_TOKEN env/.env)")
+    args = parser.parse_args()
+    main(args.pdf, args.persist_dir, args.model, args.batch_size, api_token=args.hf_token)

scripts/qa_service.py

@@ -0,0 +1,373 @@
+"""
+QA Service Module - AI-powered Question Answering for Nigerian Tax Law
+
+This module provides functions for generating and verifying answers to tax-related
+questions using Groq and Gemini APIs with retrieval-augmented generation (RAG).
+"""
+
+import os
+import json
+import logging
+import requests
+from typing import Tuple, Dict, Any, List, Optional
+
+logger = logging.getLogger(__name__)
+
+# API Configuration
+GROQ_API_URL = os.getenv("GROQ_API_URL") or "https://api.groq.com/openai/v1/chat/completions"
+GROQ_API_KEY = os.getenv("GROQ_API_KEY") or os.getenv("GROQ_API") or os.getenv("GROQ_API_TOKEN") or os.getenv("GROQ_KEY")
+GROK_API_URL = os.getenv("GROK_API_URL")  # Backwards compatibility
+GROK_API_KEY = os.getenv("GROK_API_KEY")  # Backwards compatibility
+GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
+
+# System prompts
+TAX_ASSISTANT_PROMPT = """You are an expert Nigerian tax consultant assistant with deep knowledge of the Nigeria Tax Act 2025 and related tax legislation.
+
+Your role is to:
+1. Provide accurate, helpful answers about Nigerian tax law
+2. Cite specific sources and sections when available
+3. Be clear about limitations and when to consult a professional
+4. Use Nigerian Naira (₦) for currency references
+5. Format responses for readability using markdown
+
+Guidelines:
+- Base your answers ONLY on the provided context
+- If the context doesn't contain enough information, say so clearly
+- Never make up tax rates, thresholds, or legal requirements
+- Recommend consulting FIRS or a tax professional for complex cases
+"""
+
+VERIFICATION_PROMPT = """You are a tax law fact-checker. Your task is to verify if an answer about Nigerian tax law is accurate and well-supported by the provided context.
+
+Evaluate the answer based on:
+1. Factual accuracy compared to the source documents
+2. Completeness of the response
+3. Proper citation of sources
+4. Absence of hallucinated information
+
+Return a JSON object with:
+- score: float between 0 and 1 (1 = fully accurate)
+- accurate: boolean (true if score >= 0.7)
+- confidence_reason: string explaining your assessment
+- issues: array of strings listing any inaccuracies or concerns (empty if none)
+"""
+
+
+class APIError(Exception):
+    """Custom exception for API errors."""
+    pass
+
+
+def call_groq(
+    prompt: str,
+    system_prompt: Optional[str] = None,
+    timeout: int = 25,
+    model: str = "llama-3.3-70b-versatile",
+    max_tokens: int = 800,
+    temperature: float = 0.3
+) -> str:
+    """
+    Call Groq API (OpenAI-compatible) for text generation.
+    
+    Args:
+        prompt: User message/prompt
+        system_prompt: Optional system message for context
+        timeout: Request timeout in seconds (default: 25)
+        model: Model identifier
+        max_tokens: Maximum tokens in response (default: 800)
+        temperature: Sampling temperature (0-1)
+    
+    Returns:
+        Generated text response
+    
+    Raises:
+        APIError: If API call fails
+    """
+    url = GROQ_API_URL or GROK_API_URL
+    key = GROQ_API_KEY or GROK_API_KEY
+    
+    if not key:
+        raise APIError("Groq API key not configured. Set GROQ_API_KEY environment variable.")
+    
+    messages = []
+    if system_prompt:
+        messages.append({"role": "system", "content": system_prompt})
+    messages.append({"role": "user", "content": prompt})
+    
+    headers = {
+        "Authorization": f"Bearer {key}",
+        "Content-Type": "application/json"
+    }
+    
+    payload = {
+        "model": model,
+        "messages": messages,
+        "max_tokens": max_tokens,
+        "temperature": temperature,
+        "top_p": 0.95,
+    }
+    
+    try:
+        resp = requests.post(url, json=payload, headers=headers, timeout=timeout)
+        
+        if resp.status_code == 401:
+            raise APIError("Groq API authentication failed. Check your API key.")
+        elif resp.status_code == 429:
+            raise APIError("Groq API rate limit exceeded. Please try again later.")
+        elif resp.status_code != 200:
+            raise APIError(f"Groq API error ({resp.status_code})")
+        
+        data = resp.json()
+        
+        if isinstance(data, dict) and "choices" in data and data["choices"]:
+            return data["choices"][0]["message"]["content"]
+        
+        raise APIError("Unexpected response format from Groq API")
+        
+    except requests.Timeout:
+        raise APIError("Groq API request timed out")
+    except requests.RequestException as e:
+        raise APIError(f"Network error calling Groq API: {str(e)}")
+
+
+# Alias for backwards compatibility
+call_grok = call_groq
+
+
+def call_gemini(
+    prompt: str,
+    model: str = "gemini-pro",
+    timeout: int = 25,
+    max_output_tokens: int = 800
+) -> str:
+    """
+    Call Google Gemini API for text generation.
+    
+    Args:
+        prompt: User prompt
+        model: Gemini model identifier
+        timeout: Request timeout in seconds (default: 25)
+        max_output_tokens: Maximum tokens in response (default: 800)
+    
+    Returns:
+        Generated text response
+    
+    Raises:
+        APIError: If API call fails
+    """
+    if not GEMINI_API_KEY:
+        raise APIError("Gemini API key not configured. Set GEMINI_API_KEY environment variable.")
+    
+    url = f"https://generativelanguage.googleapis.com/v1/models/{model}:generateContent?key={GEMINI_API_KEY}"
+    
+    headers = {"Content-Type": "application/json"}
+    
+    payload = {
+        "contents": [{"parts": [{"text": prompt}]}],
+        "generationConfig": {
+            "maxOutputTokens": max_output_tokens,
+            "temperature": 0.3,
+        }
+    }
+    
+    try:
+        resp = requests.post(url, json=payload, headers=headers, timeout=timeout)
+        
+        if resp.status_code == 401:
+            raise APIError("Gemini API authentication failed. Check your API key.")
+        elif resp.status_code == 429:
+            raise APIError("Gemini API rate limit exceeded. Please try again later.")
+        elif resp.status_code != 200:
+            raise APIError(f"Gemini API error ({resp.status_code})")
+        
+        data = resp.json()
+        
+        # Extract text from Gemini response
+        if isinstance(data, dict):
+            candidates = data.get("candidates", [])
+            if candidates:
+                content = candidates[0].get("content", {})
+                parts = content.get("parts", [])
+                if parts:
+                    return parts[0].get("text", "")
+        
+        raise APIError("Unexpected response format from Gemini API")
+        
+    except requests.Timeout:
+        raise APIError("Gemini API request timed out")
+    except requests.RequestException as e:
+        raise APIError(f"Network error calling Gemini API: {str(e)}")
+
+
+def format_context(contexts: List[Dict[str, Any]]) -> str:
+    """Format context documents for the prompt."""
+    formatted = []
+    for i, ctx in enumerate(contexts, 1):
+        page = ctx.get('page', 'N/A')
+        chunk_id = ctx.get('chunk_id', '')
+        text = ctx.get('text', '').strip()
+        formatted.append(f"[Source {i} | Page {page}]\n{text}")
+    return "\n\n---\n\n".join(formatted)
+
+
+def generate_answer(
+    query: str,
+    contexts: List[Dict[str, Any]],
+    prefer_grok: bool = True,
+    timeout: int = 25
+) -> Tuple[str, str, str]:
+    """
+    Generate an answer using RAG with the provided contexts.
+    
+    Args:
+        query: User's question
+        contexts: List of context documents with 'text', 'page', etc.
+        prefer_grok: Try Groq/Grok first if True
+        timeout: Timeout for API calls in seconds
+    
+    Returns:
+        Tuple of (answer_text, model_used, raw_response)
+    
+    Raises:
+        APIError: If all API calls fail
+    """
+    if not contexts:
+        return (
+            "I couldn't find relevant information to answer your question. "
+            "Please try rephrasing or ask about a different topic.",
+            "none",
+            ""
+        )
+    
+    context_text = format_context(contexts)
+    
+    prompt = f"""Based on the following excerpts from the Nigeria Tax Act 2025, please answer the question.
+
+CONTEXT:
+{context_text}
+
+QUESTION: {query}
+
+Please provide a clear, accurate answer based ONLY on the information provided above. 
+If the context doesn't contain enough information, clearly state that.
+List the source numbers you used at the end of your response."""
+
+    errors = []
+    
+    # Try Groq first if preferred
+    if prefer_grok:
+        try:
+            response = call_groq(prompt, system_prompt=TAX_ASSISTANT_PROMPT, timeout=timeout)
+            return response, "groq", response
+        except APIError as e:
+            errors.append(f"Groq: {str(e)}")
+            logger.warning(f"Groq API failed: {e}")
+    
+    # Try Gemini as fallback
+    try:
+        full_prompt = f"{TAX_ASSISTANT_PROMPT}\n\n{prompt}"
+        response = call_gemini(full_prompt, timeout=timeout - 5)
+        return response, "gemini", response
+    except APIError as e:
+        errors.append(f"Gemini: {str(e)}")
+        logger.warning(f"Gemini API failed: {e}")
+    
+    # If not preferring Grok, try it now
+    if not prefer_grok:
+        try:
+            response = call_groq(prompt, system_prompt=TAX_ASSISTANT_PROMPT, timeout=timeout)
+            return response, "groq", response
+        except APIError as e:
+            errors.append(f"Groq: {str(e)}")
+            logger.warning(f"Groq API failed: {e}")
+    
+    # All APIs failed
+    error_summary = "; ".join(errors)
+    raise APIError(f"All AI services unavailable. {error_summary}")
+
+
+def verify_answer(
+    answer: str,
+    query: str,
+    contexts: List[Dict[str, Any]],
+    prefer_grok: bool = True
+) -> Dict[str, Any]:
+    """
+    Verify an answer against the source contexts.
+    
+    Args:
+        answer: The generated answer to verify
+        query: Original question
+        contexts: Source documents used for generation
+        prefer_grok: Try Groq/Grok first if True
+    
+    Returns:
+        Dictionary with verification results including score, accuracy, and issues
+    """
+    context_text = format_context(contexts)
+    
+    prompt = f"""Verify the following answer about Nigerian tax law.
+
+CONTEXT DOCUMENTS:
+{context_text}
+
+QUESTION: {query}
+
+ANSWER TO VERIFY:
+{answer}
+
+Analyze the answer and return ONLY a valid JSON object (no markdown, no explanation) with these exact fields:
+{{
+    "score": <float 0-1>,
+    "accurate": <boolean>,
+    "confidence_reason": "<string>",
+    "issues": ["<string>", ...]
+}}"""
+
+    try:
+        # Try Groq first
+        if prefer_grok:
+            try:
+                response = call_groq(prompt, system_prompt=VERIFICATION_PROMPT, temperature=0.1)
+            except APIError:
+                response = call_gemini(f"{VERIFICATION_PROMPT}\n\n{prompt}")
+        else:
+            try:
+                response = call_gemini(f"{VERIFICATION_PROMPT}\n\n{prompt}")
+            except APIError:
+                response = call_groq(prompt, system_prompt=VERIFICATION_PROMPT, temperature=0.1)
+        
+        # Parse JSON from response
+        response = response.strip()
+        
+        # Handle markdown code blocks
+        if response.startswith("```"):
+            lines = response.split("\n")
+            response = "\n".join(lines[1:-1])
+        
+        result = json.loads(response)
+        
+        # Ensure required fields
+        return {
+            "score": float(result.get("score", 0)),
+            "accurate": bool(result.get("accurate", False)),
+            "confidence_reason": str(result.get("confidence_reason", "")),
+            "issues": list(result.get("issues", []))
+        }
+        
+    except json.JSONDecodeError:
+        logger.warning("Failed to parse verification response as JSON")
+        return {
+            "score": 0.5,
+            "accurate": False,
+            "confidence_reason": "Verification response could not be parsed",
+            "issues": ["Verification format error"]
+        }
+    except APIError as e:
+        logger.error(f"Verification API error: {e}")
+        return {
+            "score": 0,
+            "accurate": False,
+            "confidence_reason": f"Verification unavailable: {str(e)}",
+            "issues": ["Verification service unavailable"]
+        }

scripts/query_qa.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python
+"""Query the local FAISS vectorstore and return top-k chunks using HF Inference API.
+Usage: python scripts/query_qa.py --query "what is the personal income tax threshold" --top_k 5
+"""
+import argparse
+import json
+import os
+import pickle
+from pathlib import Path
+
+from dotenv import load_dotenv, dotenv_values
+load_dotenv()
+
+import faiss
+import numpy as np
+import requests
+
+
+def embed_text_hf(texts, model_id="sentence-transformers/all-mpnet-base-v2", api_token=None, timeout=15):
+    """Call HF Inference API to embed texts with timeout."""
+    if api_token is None:
+        raise Exception("HF_TOKEN not found. Please set HF_TOKEN in your .env or environment variables.")
+    
+    # Use the new router endpoint (api-inference is deprecated)
+    api_url = f"https://router.huggingface.co/hf-inference/models/{model_id}"
+    headers = {"Authorization": f"Bearer {api_token}"}
+    
+    payload = {"inputs": texts, "options": {"wait_for_model": True}}
+    response = requests.post(api_url, json=payload, headers=headers, timeout=timeout)
+    
+    if response.status_code != 200:
+        if response.status_code == 401:
+            raise Exception("HF API error 401: Unauthorized. Check your HF_TOKEN and model access permissions.")
+        if response.status_code == 503:
+            raise Exception("HF API: Model is loading, please retry in a moment.")
+        raise Exception(f"HF API error {response.status_code}: {response.text}")
+    
+    embeddings = response.json()
+    if isinstance(embeddings, dict) and "error" in embeddings:
+        raise Exception(f"HF API error: {embeddings['error']}")
+    
+    # HF returns list of embeddings, need to handle the format
+    # For feature-extraction, it returns token-level embeddings, we need to mean pool
+    emb_array = np.array(embeddings, dtype=np.float32)
+    if len(emb_array.shape) == 3:
+        # Mean pooling over tokens
+        emb_array = emb_array.mean(axis=1)
+    
+    return emb_array
+
+
+def load_vectorstore(persist_dir="vectorstore"):
+    persist_dir = Path(persist_dir)
+    index = faiss.read_index(str(persist_dir / "faiss_index.bin"))
+    with open(persist_dir / "metadata.pkl", "rb") as f:
+        docs = pickle.load(f)
+    return index, docs
+
+
+def query(index, docs, q, model_id="sentence-transformers/all-mpnet-base-v2", top_k=5, api_token=None):
+    """Query the vectorstore using local sentence-transformers model."""
+    # Use local model - HF API doesn't support direct embeddings for sentence-transformers
+    from sentence_transformers import SentenceTransformer
+    
+    # Cache model in module-level variable
+    global _st_model
+    if '_st_model' not in globals() or _st_model is None:
+        _st_model = SentenceTransformer(model_id)
+    
+    emb = _st_model.encode([q], show_progress_bar=False, convert_to_numpy=True)
+    emb = np.array(emb, dtype=np.float32)
+    emb = emb / (np.linalg.norm(emb, axis=1, keepdims=True) + 1e-12)
+    
+    D, I = index.search(emb, top_k)
+    results = []
+    for score, idx in zip(D[0], I[0]):
+        if idx < 0:
+            continue
+        meta = docs[idx]
+        results.append({"score": float(score), "text": meta["text"], "source": meta["source"], "page": meta["page"], "chunk_id": meta["chunk_id"]})
+    return results
+
+# Model cache
+_st_model = None
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--query", required=True)
+    parser.add_argument("--persist_dir", default="vectorstore")
+    parser.add_argument("--model", default="nvidia/llama-embed-nemotron-8b")
+    parser.add_argument("--top_k", type=int, default=5)
+    parser.add_argument("--hf_token", default=None, help="Hugging Face token (overrides HF_TOKEN env/.env)")
+    args = parser.parse_args()
+
+    index, docs = load_vectorstore(args.persist_dir)
+    res = query(index, docs, args.query, args.model, args.top_k, api_token=args.hf_token)
+    print(json.dumps(res, indent=2))

src/tax_calculator.py

@@ -0,0 +1,263 @@
+"""
+Nigerian Tax Calculator - Based on Nigeria Tax Act 2025
+
+This module provides comprehensive tax calculation functionality for Nigerian
+personal income tax, including progressive tax brackets, reliefs, and deductions.
+"""
+
+from dataclasses import dataclass
+from typing import List, Tuple, Optional
+from decimal import Decimal, ROUND_HALF_UP
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Tax brackets as per Nigeria Tax Act 2025
+# (upper_limit, rate) - amounts in NGN
+NIGERIA_TAX_BRACKETS: List[Tuple[Decimal, Decimal]] = [
+    (Decimal('300000'), Decimal('0.07')),    # First ₦300,000 at 7%
+    (Decimal('300000'), Decimal('0.11')),    # Next ₦300,000 at 11%
+    (Decimal('500000'), Decimal('0.15')),    # Next ₦500,000 at 15%
+    (Decimal('500000'), Decimal('0.19')),    # Next ₦500,000 at 19%
+    (Decimal('1600000'), Decimal('0.21')),   # Next ₦1,600,000 at 21%
+    (Decimal('Infinity'), Decimal('0.24')),  # Above ₦3,200,000 at 24%
+]
+
+# Minimum tax threshold
+MINIMUM_TAX_THRESHOLD = Decimal('30000000')  # ₦30 million
+MINIMUM_TAX_RATE = Decimal('0.01')  # 1% minimum tax
+
+# Consolidated Relief Allowance (CRA)
+CRA_FIXED_AMOUNT = Decimal('200000')  # ₦200,000 fixed
+CRA_PERCENTAGE = Decimal('0.20')  # 20% of gross income
+
+# Pension contribution limits
+PENSION_MAX_PERCENTAGE = Decimal('0.20')  # 20% max pension contribution
+PENSION_EMPLOYER_RATE = Decimal('0.10')  # 10% employer contribution
+PENSION_EMPLOYEE_RATE = Decimal('0.08')  # 8% employee contribution
+
+
+@dataclass
+class TaxBracketResult:
+    """Result for a single tax bracket calculation."""
+    bracket_range: str
+    rate_percentage: float
+    taxable_amount: Decimal
+    tax_amount: Decimal
+
+
+@dataclass
+class TaxCalculationResult:
+    """Complete tax calculation result."""
+    gross_income: Decimal
+    total_allowances: Decimal
+    total_reliefs: Decimal
+    consolidated_relief: Decimal
+    taxable_income: Decimal
+    tax_due: Decimal
+    effective_rate: Decimal
+    breakdown: List[TaxBracketResult]
+    minimum_tax_applies: bool
+    minimum_tax_amount: Decimal
+    net_income: Decimal
+    monthly_tax: Decimal
+
+
+class TaxCalculationError(Exception):
+    """Custom exception for tax calculation errors."""
+    pass
+
+
+def calculate_consolidated_relief(gross_income: Decimal) -> Decimal:
+    """
+    Calculate Consolidated Relief Allowance (CRA).
+    CRA = ₦200,000 OR 1% of gross income, whichever is higher
+    PLUS 20% of gross income
+    """
+    fixed_or_percentage = max(CRA_FIXED_AMOUNT, gross_income * Decimal('0.01'))
+    variable_relief = gross_income * CRA_PERCENTAGE
+    return fixed_or_percentage + variable_relief
+
+
+def calculate_pension_relief(gross_income: Decimal, pension_contribution: Decimal = Decimal('0')) -> Decimal:
+    """
+    Calculate pension contribution relief.
+    Employee pension contributions are tax-exempt up to 8% of basic salary.
+    """
+    max_exempt = gross_income * PENSION_EMPLOYEE_RATE
+    return min(pension_contribution, max_exempt)
+
+
+def is_taxable(annual_income: float, threshold: float = 0) -> bool:
+    """
+    Check if income is taxable.
+    In Nigeria, there's no specific threshold - all income above reliefs is taxable.
+    """
+    return Decimal(str(annual_income)) > Decimal(str(threshold))
+
+
+def calculate_tax_breakdown(taxable_income: Decimal) -> Tuple[Decimal, List[TaxBracketResult]]:
+    """
+    Calculate tax using progressive brackets.
+    Returns (total_tax, breakdown_list).
+    """
+    total_tax = Decimal('0')
+    remaining = taxable_income
+    breakdown: List[TaxBracketResult] = []
+    cumulative_lower = Decimal('0')
+    
+    for bracket_limit, rate in NIGERIA_TAX_BRACKETS:
+        if remaining <= 0:
+            break
+            
+        taxable_in_bracket = min(remaining, bracket_limit) if bracket_limit != Decimal('Infinity') else remaining
+        tax_in_bracket = (taxable_in_bracket * rate).quantize(Decimal('0.01'), rounding=ROUND_HALF_UP)
+        
+        if taxable_in_bracket > 0:
+            if bracket_limit == Decimal('Infinity'):
+                bracket_range = f"Above ₦{int(cumulative_lower):,}"
+            else:
+                bracket_range = f"₦{int(cumulative_lower):,} - ₦{int(cumulative_lower + bracket_limit):,}"
+            
+            breakdown.append(TaxBracketResult(
+                bracket_range=bracket_range,
+                rate_percentage=float(rate * 100),
+                taxable_amount=taxable_in_bracket,
+                tax_amount=tax_in_bracket
+            ))
+            
+            total_tax += tax_in_bracket
+            cumulative_lower += bracket_limit if bracket_limit != Decimal('Infinity') else Decimal('0')
+        
+        remaining -= taxable_in_bracket
+    
+    return total_tax, breakdown
+
+
+def calculate_minimum_tax(gross_income: Decimal) -> Decimal:
+    """
+    Calculate minimum tax if applicable.
+    Minimum tax is 1% of gross income if gross income > ₦30 million.
+    """
+    if gross_income > MINIMUM_TAX_THRESHOLD:
+        return (gross_income * MINIMUM_TAX_RATE).quantize(Decimal('0.01'), rounding=ROUND_HALF_UP)
+    return Decimal('0')
+
+
+def calculate_tax(
+    annual_income: float,
+    allowances: float = 0,
+    reliefs: float = 0,
+    pension_contribution: float = 0,
+    include_cra: bool = True
+) -> TaxCalculationResult:
+    """
+    Calculate comprehensive tax liability for Nigerian personal income tax.
+    
+    Args:
+        annual_income: Gross annual income in NGN
+        allowances: Non-taxable allowances (housing, transport, etc.)
+        reliefs: Additional tax reliefs (life insurance, etc.)
+        pension_contribution: Employee pension contribution
+        include_cra: Whether to automatically apply Consolidated Relief Allowance
+    
+    Returns:
+        TaxCalculationResult with complete breakdown
+    
+    Raises:
+        TaxCalculationError: If inputs are invalid
+    """
+    try:
+        # Convert to Decimal for precision
+        gross_income = Decimal(str(annual_income))
+        total_allowances = Decimal(str(allowances))
+        total_reliefs = Decimal(str(reliefs))
+        pension = Decimal(str(pension_contribution))
+        
+        # Validate inputs
+        if gross_income < 0:
+            raise TaxCalculationError("Annual income cannot be negative")
+        if total_allowances < 0:
+            raise TaxCalculationError("Allowances cannot be negative")
+        if total_reliefs < 0:
+            raise TaxCalculationError("Reliefs cannot be negative")
+        
+        # Calculate Consolidated Relief Allowance
+        cra = calculate_consolidated_relief(gross_income) if include_cra else Decimal('0')
+        
+        # Calculate pension relief
+        pension_relief = calculate_pension_relief(gross_income, pension)
+        total_reliefs += pension_relief
+        
+        # Calculate taxable income
+        taxable_income = max(Decimal('0'), gross_income - total_allowances - total_reliefs - cra)
+        
+        # Calculate tax using progressive brackets
+        tax_due, breakdown = calculate_tax_breakdown(taxable_income)
+        
+        # Check for minimum tax
+        minimum_tax = calculate_minimum_tax(gross_income)
+        minimum_tax_applies = minimum_tax > tax_due
+        
+        # Apply minimum tax if higher
+        final_tax = max(tax_due, minimum_tax) if gross_income > MINIMUM_TAX_THRESHOLD else tax_due
+        
+        # Calculate effective rate
+        effective_rate = (final_tax / gross_income * 100) if gross_income > 0 else Decimal('0')
+        effective_rate = effective_rate.quantize(Decimal('0.01'), rounding=ROUND_HALF_UP)
+        
+        # Calculate net income
+        net_income = gross_income - final_tax
+        
+        # Monthly tax
+        monthly_tax = (final_tax / 12).quantize(Decimal('0.01'), rounding=ROUND_HALF_UP)
+        
+        return TaxCalculationResult(
+            gross_income=gross_income,
+            total_allowances=total_allowances,
+            total_reliefs=total_reliefs,
+            consolidated_relief=cra,
+            taxable_income=taxable_income,
+            tax_due=final_tax,
+            effective_rate=effective_rate,
+            breakdown=breakdown,
+            minimum_tax_applies=minimum_tax_applies,
+            minimum_tax_amount=minimum_tax,
+            net_income=net_income,
+            monthly_tax=monthly_tax
+        )
+        
+    except (ValueError, TypeError) as e:
+        logger.error(f"Tax calculation error: {e}")
+        raise TaxCalculationError(f"Invalid input values: {e}")
+
+
+def format_currency(amount: Decimal) -> str:
+    """Format amount as Nigerian Naira."""
+    return f"₦{int(amount):,}"
+
+
+def get_tax_summary(result: TaxCalculationResult) -> dict:
+    """Convert TaxCalculationResult to API-friendly dictionary."""
+    return {
+        "gross_income": float(result.gross_income),
+        "total_allowances": float(result.total_allowances),
+        "total_reliefs": float(result.total_reliefs),
+        "consolidated_relief": float(result.consolidated_relief),
+        "taxable_income": float(result.taxable_income),
+        "tax_due": float(result.tax_due),
+        "effective_rate": float(result.effective_rate),
+        "breakdown": [
+            {
+                "bracket": br.bracket_range,
+                "rate": f"{br.rate_percentage}%",
+                "taxable_amount": float(br.taxable_amount),
+                "tax": float(br.tax_amount)
+            }
+            for br in result.breakdown
+        ],
+        "minimum_tax_applies": result.minimum_tax_applies,
+        "minimum_tax_amount": float(result.minimum_tax_amount),
+        "net_income": float(result.net_income),
+        "monthly_tax": float(result.monthly_tax)
+    }

vectorstore/faiss_index.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4fee8ae5a990882271c453a4d4302b96f60cd66944d951fdc3ccfce2ad45f280
+size 3511341

vectorstore/metadata.pkl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0615fceb03208665d769cdeec26af3683ab074d70f469258bc9f0e2e7254ec42
+size 567830