2.4 Adaptability & Customisation¶

graph TD
    A[Layer 1: Runtime Config] --> B[30+ ENV Variables]
    A --> C[Zero Code Changes]
    A --> D[Hot-Reload Support]

    E[Layer 2: Taxonomy] --> F[Custom Categories]
    E --> G[Custom Keywords]
    E --> H[Custom MCC Mappings]

    I[Layer 3: Ensemble Tuning] --> J[Method Weights]
    I --> K[Confidence Thresholds]
    I --> L[Early-Exit Rules]

    M[Layer 4: Data Assets] --> N[Custom Merchant Gazetteer]
    M --> O[Custom Few-Shot Examples]
    M --> P[Custom Training Data]

    style A fill:#4ade80,stroke:#22c55e,stroke-width:3px
    style E fill:#fbbf24,stroke:#f59e0b,stroke-width:2px
    style I fill:#60a5fa,stroke:#3b82f6,stroke-width:2px
    style M fill:#c084fc,stroke:#9333ea,stroke-width:2px

# Add to data/taxonomy.yaml (5 minutes)
categories:
  - name: "Medical Supplies"
    id: "medical_supplies"
    keywords:
      - "medline"
      - "cardinal health"
      - "mckesson"
      - "surgical supplies"
    mcc_codes:
      - "5047"  # Medical Equipment

# ========================================
# Ensemble Weights (Layer 1A)
# ========================================
MCC_WEIGHT=0.15          # Merchant Category Code weight
RULE_WEIGHT=0.15         # Rule engine weight
ML_WEIGHT=0.65           # Machine learning weight
LLM_WEIGHT=0.05          # LLM reasoning weight

# ========================================
# Confidence Thresholds (Layer 1B)
# ========================================
AUTO_ACCEPT_THRESHOLD=0.85    # Auto-accept above this confidence
REVIEW_THRESHOLD=0.60         # Manual review below this confidence

# ========================================
# Early Exit Optimization (Layer 1C)
# ========================================
RULE_EARLY_EXIT_THRESHOLD=0.95       # Skip ensemble if rule conf > 95%
MCC_EARLY_EXIT_THRESHOLD=0.90        # Skip ensemble if MCC conf > 90%
MERCHANT_CONFIDENCE_THRESHOLD=0.70   # Skip ensemble if merchant match > 70%

# ========================================
# LLM Configuration (Layer 1D)
# ========================================
LLM_WEIGHT=0.05                      # LLM voting weight (set to 0 to disable)
ML_CONFIDENCE_THRESHOLD=0.80         # Invoke LLM if ML conf < 80%
RULE_CONFIDENCE_THRESHOLD=0.80       # Invoke LLM if Rule conf < 80%
LLM_TIMEOUT=3.0                      # Max seconds for LLM response

# ========================================
# Performance Tuning (Layer 1E)
# ========================================
ENABLE_PARALLEL=true                 # Run methods in parallel (faster)
MAX_WORKERS=4                        # Thread pool size
CACHE_TTL=600                        # Cache timeout (seconds)

version: "1.0.0-healthcare"
last_updated: "2025-11-20"

categories:
  # Standard categories (keep existing)
  - name: "Food & Dining"
    id: "food_dining"
    keywords: ["restaurant", "cafe"]

  # Healthcare-specific additions
  - name: "Medical Supplies"
    id: "medical_supplies"
    description: "Surgical supplies, medical equipment, pharmaceuticals"
    mcc_codes:
      - "5047"  # Medical/Dental Laboratories
      - "5122"  # Drugs, Proprietaries, Sundries
      - "8011"  # Doctors
      - "8021"  # Dentists/Orthodontists
    subcategories:
      - "Surgical Supplies"
      - "Pharmaceuticals"
      - "Medical Equipment"
      - "Diagnostic Equipment"
    keywords:
      - "medline"
      - "cardinal health"
      - "mckesson"
      - "surgical"
      - "pharmaceuticals"
      - "medical equipment"
    patterns:
      - "(?i).*medical.*supplies.*"
      - "(?i).*surgical.*"
      - "(?i).*pharmaceuticals.*"

  - name: "Insurance Claims"
    id: "insurance_claims"
    description: "Health insurance claims and reimbursements"
    keywords:
      - "insurance claim"
      - "reimbursement"
      - "medicare"
      - "medicaid"
      - "aetna"
      - "united healthcare"
      - "blue cross"
    patterns:
      - "(?i).*insurance.*claim.*"
      - "(?i).*medicare.*"
      - "(?i).*medicaid.*"

  - name: "Patient Copays"
    id: "patient_copays"
    description: "Patient out-of-pocket payments and copays"
    keywords:
      - "copay"
      - "patient payment"
      - "out of pocket"
      - "deductible"
    patterns:
      - "(?i).*copay.*"
      - "(?i).*patient.*payment.*"

# Prioritize deterministic methods (rules + MCC)
MCC_WEIGHT=0.30          # +15% (trust MCC codes heavily)
RULE_WEIGHT=0.40         # +25% (trust fraud/security rules)
ML_WEIGHT=0.25           # -5% (less trust in ML predictions)
LLM_WEIGHT=0.05          # Same (LLM as tiebreaker)

# High confidence thresholds
AUTO_ACCEPT_THRESHOLD=0.95    # Only accept very high confidence
REVIEW_THRESHOLD=0.80         # Review anything below 80%

# Conservative early exits
RULE_EARLY_EXIT_THRESHOLD=0.98    # Only skip ensemble if 98% confident
MCC_EARLY_EXIT_THRESHOLD=0.95     # Only skip if 95% confident

# Prioritize ML (learns from data)
MCC_WEIGHT=0.10          # -5% (MCC not always available)
RULE_WEIGHT=0.10         # -5% (rules too rigid)
ML_WEIGHT=0.75           # +10% (trust ML more)
LLM_WEIGHT=0.05          # Same

# Low confidence thresholds
AUTO_ACCEPT_THRESHOLD=0.75    # Accept medium confidence
REVIEW_THRESHOLD=0.50         # Only review very low confidence

# Aggressive early exits
RULE_EARLY_EXIT_THRESHOLD=0.90    # Skip ensemble earlier
MCC_EARLY_EXIT_THRESHOLD=0.85     # Skip ensemble earlier

MCC_WEIGHT=0.15
RULE_WEIGHT=0.15
ML_WEIGHT=0.65
LLM_WEIGHT=0.05

AUTO_ACCEPT_THRESHOLD=0.85
REVIEW_THRESHOLD=0.60

merchant_id,canonical_name,aliases,category,subcategory,country
M1001,Anand Sweets,anand sweets|anand sweet shop,food_dining,Sweets & Desserts,IN
M1002,Sharma Clinic,dr sharma|sharma clinic,health,Medical Consultation,IN
M1003,City Gym Patel Nagar,city gym|patel nagar gym,health,Fitness,IN
M1004,Raja Auto Repair,raja auto|raja mechanic,automotive,Auto Repair,IN

# Add merchants to CSV
echo "M1005,Gupta Pharmacy,gupta pharmacy,health,Pharmacy,IN" >> data/gazetteer/merchant_aliases.csv

# Reload merchant resolver (no restart required)
curl -X POST http://localhost:8000/reload-merchants

# Update .env file
vi .env

# Restart API container (5-10 seconds downtime)
docker restart txn-api

# Verify new config loaded
curl http://localhost:8000/health

# Update ConfigMap
kubectl create configmap txn-config --from-env-file=.env -o yaml --dry-run=client | kubectl apply -f -

# Rolling restart (zero downtime - gradual pod replacement)
kubectl rollout restart deployment/txn-api

# Monitor rollout
kubectl rollout status deployment/txn-api

# data/taxonomy.yaml

categories:
  # ... existing categories ...

  # Legal-specific categories
  - name: "Court Fees"
    id: "court_fees"
    description: "Filing fees, court costs, legal administrative fees"
    keywords:
      - "court fee"
      - "filing fee"
      - "clerk of court"
      - "judicial"
      - "courthouse"
    patterns:
      - "(?i).*court.*fee.*"
      - "(?i).*filing.*"
    subcategories:
      - "Filing Fees"
      - "Court Reporter Fees"
      - "Document Fees"

  - name: "Legal Research"
    id: "legal_research"
    description: "Westlaw, LexisNexis, legal databases"
    keywords:
      - "westlaw"
      - "lexisnexis"
      - "fastcase"
      - "legal research"
      - "law library"
    patterns:
      - "(?i)westlaw.*"
      - "(?i)lexis.*nexis.*"
    subcategories:
      - "Legal Databases"
      - "Law Library Access"

  - name: "Expert Witnesses"
    id: "expert_witnesses"
    description: "Expert witness fees and consulting"
    keywords:
      - "expert witness"
      - "expert testimony"
      - "forensic consultant"
      - "medical expert"
    patterns:
      - "(?i).*expert.*witness.*"
      - "(?i).*expert.*testimony.*"

  - name: "Client Reimbursements"
    id: "client_reimbursements"
    description: "Reimbursements to clients for case expenses"
    keywords:
      - "client reimbursement"
      - "case expense"
      - "client refund"
    patterns:
      - "(?i).*client.*reimbursement.*"
      - "(?i).*case.*expense.*"

# Before: Single category
- name: "Food & Dining"
  id: "food_dining"
  keywords: ["restaurant", "cafe", "food"]

# After: Two categories
- name: "Quick Service Restaurants"
  id: "quick_service"
  keywords:
    - "mcdonalds"
    - "kfc"
    - "subway"
    - "fast food"
    - "quick service"
  mcc_codes:
    - "5814"  # Fast Food

- name: "Fine Dining"
  id: "fine_dining"
  keywords:
    - "fine dining"
    - "steakhouse"
    - "bistro"
    - "gourmet"
  mcc_codes:
    - "5812"  # Restaurants (general)

UPDATE transactions
SET category = 'quick_service'
WHERE category = 'food_dining'
  AND (
    original_text ILIKE '%mcdonalds%'
    OR original_text ILIKE '%kfc%'
    OR original_text ILIKE '%subway%'
  );

# scripts/optimize_ensemble_weights.py

import itertools
from sklearn.metrics import f1_score

# Test different weight combinations
mcc_weights = [0.10, 0.15, 0.20, 0.25]
rule_weights = [0.10, 0.15, 0.20, 0.25]
ml_weights = [0.50, 0.60, 0.70]
llm_weights = [0.00, 0.05, 0.10]

best_f1 = 0
best_config = None

for mcc, rule, ml, llm in itertools.product(mcc_weights, rule_weights, ml_weights, llm_weights):
    # Weights must sum to 1.0
    if abs(mcc + rule + ml + llm - 1.0) > 0.01:
        continue

    # Set environment variables
    os.environ['MCC_WEIGHT'] = str(mcc)
    os.environ['RULE_WEIGHT'] = str(rule)
    os.environ['ML_WEIGHT'] = str(ml)
    os.environ['LLM_WEIGHT'] = str(llm)

    # Evaluate on test set
    predictions = evaluate_test_set(test_data)
    f1 = f1_score(test_labels, predictions, average='macro')

    if f1 > best_f1:
        best_f1 = f1
        best_config = (mcc, rule, ml, llm)

print(f"Best F1: {best_f1:.4f}")
print(f"Best Config: MCC={best_config[0]}, Rule={best_config[1]}, ML={best_config[2]}, LLM={best_config[3]}")

Testing 256 weight combinations...

Best F1: 0.9842
Best Config: MCC=0.15, Rule=0.15, ML=0.65, LLM=0.05

Top 5 Configurations:
1. (0.15, 0.15, 0.65, 0.05) → F1=0.9842
2. (0.20, 0.15, 0.60, 0.05) → F1=0.9838
3. (0.15, 0.20, 0.60, 0.05) → F1=0.9835
4. (0.15, 0.15, 0.70, 0.00) → F1=0.9832 (no LLM)
5. (0.10, 0.10, 0.70, 0.10) → F1=0.9828

CATEGORY_THRESHOLDS = {
    # Critical financial categories - higher thresholds
    "Investments": {"auto_accept": 0.90, "review": 0.70},
    "income_salary": {"auto_accept": 0.90, "review": 0.70},
    "Fraud & Security": {"auto_accept": 0.95, "review": 0.80},  # Highest

    # Medium-importance categories - standard thresholds
    "Travel": {"auto_accept": 0.85, "review": 0.60},
    "Health": {"auto_accept": 0.85, "review": 0.60},

    # Low-risk categories - lower thresholds
    "Food & Dining": {"auto_accept": 0.80, "review": 0.50},
    "Groceries": {"auto_accept": 0.80, "review": 0.50},
    "Entertainment": {"auto_accept": 0.80, "review": 0.50},
}

# Add custom thresholds for law firm categories
CATEGORY_THRESHOLDS["court_fees"] = {"auto_accept": 0.90, "review": 0.70}
CATEGORY_THRESHOLDS["legal_research"] = {"auto_accept": 0.85, "review": 0.60}

AUTO_ACCEPT_THRESHOLD=0.85    # Transactions above this → Auto-accepted
REVIEW_THRESHOLD=0.60         # Transactions below this → Manual review

AUTO_ACCEPT_THRESHOLD=0.98    # Almost never auto-accept
REVIEW_THRESHOLD=0.85         # Review anything below 85%

AUTO_ACCEPT_THRESHOLD=0.85
REVIEW_THRESHOLD=0.60

AUTO_ACCEPT_THRESHOLD=0.70    # Accept medium confidence
REVIEW_THRESHOLD=0.45         # Only review very low confidence

merchant_id,canonical_name,aliases,category,subcategory,country
M0001,Starbucks,starbucks|starbucks coffee|sbux,food_dining,Cafes & Coffee,US
M0002,Netflix,netflix|netflix subscription,entertainment,Streaming Services,US
M0003,Uber,uber|uber ride|uber technologies,transport,Cab Services,IN

# Try fuzzy matching on full transaction text
if self.merchant_resolver:
    fuzzy_matches = self.merchant_resolver.search(text, limit=1)
    if fuzzy_matches and fuzzy_matches[0].similarity_score >= 0.70:
        match = fuzzy_matches[0]
        resolved_merchant = match.canonical_name
        merchant_category = match.category
        merchant_confidence = match.similarity_score

        # MERCHANT-FIRST STRATEGY: High-confidence merchant matches dominate
        if merchant_confidence >= 0.70:
            boosted_confidence = min(0.95, merchant_confidence + 0.10)
            return CategorizationResult(
                category=merchant_category,
                confidence=boosted_confidence,
                method="merchant_gazetteer",
                explanations=[f"merchant_match={resolved_merchant}"]
            )

M1001,Chai Point,chai point|chaipoint|chai point cafe,food_dining,Cafes & Coffee,IN

# Option 1: API endpoint (hot-reload)
curl -X POST http://localhost:8000/reload-merchants

# Option 2: File watcher (automatic detection)
# (already implemented in production)

curl -X POST http://localhost:8000/categorize \
  -H "Content-Type: application/json" \
  -d '{"text": "PAID TO CHAI POINT BANGALORE"}'

{
  "category": "food_dining",
  "subcategory": "Cafes & Coffee",
  "confidence": 0.85,
  "method": "merchant_gazetteer",
  "merchant_resolved": "Chai Point",
  "explanations": ["merchant_match=Chai Point"]
}

import pandas as pd

# Read Excel
df = pd.read_excel('merchants.xlsx')

# Convert to CSV format
df['merchant_id'] = ['M' + str(10000 + i) for i in range(len(df))]
df['country'] = 'IN'

# Save to gazetteer CSV
df[['merchant_id', 'canonical_name', 'aliases', 'category', 'subcategory', 'country']].to_csv(
    'data/gazetteer/merchant_aliases.csv',
    mode='a',  # Append to existing
    header=False,
    index=False
)

print(f"Imported {len(df)} merchants")

txn-ai-saas/
├── codebase/               # Shared codebase (Docker image)
│   ├── apps/
│   ├── core/
│   └── Dockerfile
│
├── tenants/
│   ├── tenant_a/
│   │   ├── .env                    # Custom weights, thresholds
│   │   ├── taxonomy.yaml           # 15 categories (simple)
│   │   └── gazetteer.csv           # 100 merchants
│   │
│   ├── tenant_b/
│   │   ├── .env                    # Different weights
│   │   ├── taxonomy.yaml           # 50 categories (complex)
│   │   └── gazetteer.csv           # 10,000 merchants
│   │
│   └── tenant_c/
│       ├── .env                    # Healthcare-specific
│       ├── taxonomy_healthcare.yaml
│       └── gazetteer_medical.csv
│
└── docker-compose.yaml     # Multi-tenant deployment

version: '3.8'

services:
  # Tenant A (Simple Setup)
  txn-api-tenant-a:
    image: txn-ai:latest  # Same image for all tenants
    env_file:
      - tenants/tenant_a/.env
    volumes:
      - ./tenants/tenant_a/taxonomy.yaml:/app/data/taxonomy.yaml
      - ./tenants/tenant_a/gazetteer.csv:/app/data/gazetteer/merchant_aliases.csv
    ports:
      - "8001:8000"

  # Tenant B (Complex Setup)
  txn-api-tenant-b:
    image: txn-ai:latest
    env_file:
      - tenants/tenant_b/.env
    volumes:
      - ./tenants/tenant_b/taxonomy.yaml:/app/data/taxonomy.yaml
      - ./tenants/tenant_b/gazetteer.csv:/app/data/gazetteer/merchant_aliases.csv
    ports:
      - "8002:8000"

  # Tenant C (Healthcare)
  txn-api-tenant-c:
    image: txn-ai:latest
    env_file:
      - tenants/tenant_c/.env
    volumes:
      - ./tenants/tenant_c/taxonomy_healthcare.yaml:/app/data/taxonomy.yaml
      - ./tenants/tenant_c/gazetteer_medical.csv:/app/data/gazetteer/merchant_aliases.csv
    ports:
      - "8003:8000"

# tenant-a-deployment.yaml
apiVersion: v1
kind: Namespace
metadata:
  name: tenant-a

---
apiVersion: v1
kind: ConfigMap
metadata:
  name: txn-config
  namespace: tenant-a
data:
  MCC_WEIGHT: "0.20"
  RULE_WEIGHT: "0.30"
  ML_WEIGHT: "0.45"
  LLM_WEIGHT: "0.05"
  AUTO_ACCEPT_THRESHOLD: "0.90"  # Conservative

---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: txn-api
  namespace: tenant-a
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: txn-api
        image: txn-ai:v1.0.0
        envFrom:
        - configMapRef:
            name: txn-config
        volumeMounts:
        - name: taxonomy
          mountPath: /app/data/taxonomy.yaml
          subPath: taxonomy.yaml
      volumes:
      - name: taxonomy
        configMap:
          name: tenant-a-taxonomy

categories:
  - name: "Donor Contributions"
    id: "donor_contributions"
    keywords:
      - "donation"
      - "donor"
      - "contribution"
      - "charitable gift"

  - name: "Grant Expenses"
    id: "grant_expenses"
    subcategories:
      - "Education Program"
      - "Healthcare Program"
      - "Community Development"
    keywords:
      - "grant expense"
      - "program expense"

  - name: "Volunteer Reimbursements"
    id: "volunteer_reimbursements"
    keywords:
      - "volunteer reimbursement"
      - "volunteer expense"

# Trust rules heavily (donor contributions have specific keywords)
RULE_WEIGHT=0.40
ML_WEIGHT=0.50
MCC_WEIGHT=0.05
LLM_WEIGHT=0.05

categories:
  - name: "Inventory Purchases"
    id: "inventory_purchases"
    keywords:
      - "wholesale"
      - "supplier"
      - "inventory"
      - "stock purchase"

  - name: "Shipping Costs"
    id: "shipping_costs"
    keywords:
      - "fedex"
      - "ups"
      - "usps"
      - "dhl"
      - "shipping"
      - "freight"

  - name: "Marketplace Fees"
    id: "marketplace_fees"
    keywords:
      - "amazon seller fees"
      - "ebay fees"
      - "etsy fees"
      - "marketplace commission"

M2001,Alibaba Wholesale,alibaba|alibaba wholesale,inventory_purchases,Wholesale Suppliers,CN
M2002,DHgate,dhgate|dhgate wholesale,inventory_purchases,Wholesale Suppliers,CN
M2003,FedEx,fedex|federal express,shipping_costs,Shipping,US
M2004,Amazon Seller Central,amazon seller|amazon fees,marketplace_fees,Marketplace Fees,US

categories:
  - name: "Client Payments"
    id: "client_payments"
    keywords:
      - "client payment"
      - "invoice payment"
      - "freelance income"
      - "consulting fee"

  - name: "Professional Development"
    id: "professional_development"
    keywords:
      - "udemy"
      - "coursera"
      - "linkedin learning"
      - "o'reilly"
      - "course"
      - "training"

  - name: "Home Office"
    id: "home_office"
    keywords:
      - "internet bill"
      - "electricity"
      - "office supplies"
      - "desk"
      - "chair"

# Accept lower confidence for business expenses (less risk)
AUTO_ACCEPT_THRESHOLD=0.75
REVIEW_THRESHOLD=0.50