feat: add Dozer + LangChain + Vector RAG banking advisor sample (fixes #1690)

[iprasen]

Summary

Resolves #1690.
Closes #1690
Fixes #1690
/claim #1690

Implements a complete, production-grade banking advisor sample inspired by Dozer's article on hyper-personalization using LLMs, Vector Databases, and LangChain.

---

Architecture & Implementation

┌─────────────────────────────────┐
│     Multi-Source Datasets       │
│  - Customer Profiles (CSV)      │
│  - Real-time Transactions (CSV) │
│  - Card Product Catalog (CSV)   │
└────────────────┬────────────────┘
                 │
                 ▼
┌────────────────────────────────────────────────────────┐
│                      DOZER CORE                        │
│  - Ingests via !LocalStorage (connections)             │
│  - Streaming SQL: Computes real-time customer profile   │
│    JOINing profiles + transactions with GROUP BY       │
│  - Exposes queryable endpoints:                        │
│      • /customer_profile (REST port 8080 / gRPC 50051) │
│      • /card_catalog                                   │
└────────────────┬───────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────┐
│   Financial & Risk Guardrails   │
│  - Minimum Age Validation (18+) │
│  - FICO Score Thresholds        │
│  - Minimum Income Requirements  │
│  - Risk Tolerance Alignment     │
└────────────────┬────────────────┘
                 │ (Eligible Products Only)
                 ▼
┌─────────────────────────────────┐
│      LangChain Vector RAG       │
│  - Chroma Vector Store          │
│  - Semantic Catalog Embeddings  │
│  - Category Spend Weighting     │
└────────────────┬────────────────┘
                 │
                 ▼
┌─────────────────────────────────┐
│     Personalized Advisory       │
│  - Grounded Rationale           │
│  - Spend Alignment Highlights   │
│  - Dual LLM (OpenAI/Local Rule) │
└─────────────────────────────────┘

Key Components Added in examples/llm-banking-advisor/:

1. Modern Schema-Valid Dozer Configuration (dozer-config.yaml):

   • Conforms strictly to Dozer's dozer.json schema without obsolete endpoints: syntax.
   • Streaming SQL INTO customer_profile dynamically aggregates total_spend_usd, transaction_count, and max_single_transaction_usd by joining customer_profiles and transactions.
   • Exposes REST (port: 8080) and gRPC (port: 50051) with sink configurations.

2. Dual-Mode Dozer Client (dozer_client.py):

   • Live Mode: Queries running Dozer REST API (POST /customer_profile/query and GET /card_catalog).
   • Offline Mode: Seamlessly emulates the exact Dozer SQL streaming aggregation directly from local storage with zero external dependencies, enabling deterministic CI and local testing without requiring a compiled Dozer binary.

3. Financial Underwriting Guardrails (guardrails.py):

   • Evaluates hard bank eligibility rules (minimum age 18+, FICO credit score floors, minimum annual income, and risk tolerance vs. annual fees) before vector ranking and LLM prompting.
   • Prevents recommending products the customer is legally or financially unqualified for.

4. LangChain Vector RAG & Spend Weighting (vector_rag.py):

   • Semantic vector embeddings over card rewards, fees, perks, and terms.
   • Enhances similarity scoring with dynamic weights calculated from the customer's actual spending concentrations (e.g. travel, dining, groceries).

5. Advisor Orchestrator & CLI (advisor.py, app.py):

   • Synthesizes personalized advisory notes (using OpenAI when OPENAI_API_KEY is present, or a deterministic rule-based explainer when offline).
   • Interactive terminal chat mode (--interactive) and machine-readable JSON output (--json).

6. Automated Test Suite (tests/):

   • 19 unit and integration tests covering schema validity, SQL profile aggregation, underwriting guardrails, vector retrieval, and end-to-end recommendation pipelines.
   • Clean zero-dependency test runner (python3 -m unittest discover -s tests -v).

---

Verification

All 19 unit tests pass in 0.12s:

test_recommendation_cust_001_travel (test_advisor.TestBankingAdvisorIntegration) ... ok
test_recommendation_cust_002_credit_builder (test_advisor.TestBankingAdvisorIntegration) ... ok
test_recommendation_cust_003_cashback_groceries (test_advisor.TestBankingAdvisorIntegration) ... ok
test_recommendation_cust_005_luxury_executive (test_advisor.TestBankingAdvisorIntegration) ... ok
test_no_obsolete_endpoints_field (test_config.TestDozerConfig) ... ok
test_required_top_level_fields (test_config.TestDozerConfig) ... ok
test_sinks_match_sql_targets (test_config.TestDozerConfig) ... ok
test_sources_reference_connections (test_config.TestDozerConfig) ... ok
test_streaming_sql_targets (test_config.TestDozerConfig) ... ok
test_customer_profile_aggregation (test_dozer_client.TestDozerClient) ... ok
test_load_products (test_dozer_client.TestDozerClient) ... ok
test_unknown_customer_raises_keyerror (test_dozer_client.TestDozerClient) ... ok
test_conservative_risk_tolerance_filters_high_fee (test_guardrails.TestFinancialGuardrails) ... ok
test_eligible_customer_passes (test_guardrails.TestFinancialGuardrails) ... ok
test_low_credit_score_rejection (test_guardrails.TestFinancialGuardrails) ... ok
test_underage_rejection (test_guardrails.TestFinancialGuardrails) ... ok
test_retriever_ranks_grocery_card_for_family_shopper (test_vector_rag.TestVectorRAG) ... ok
test_retriever_ranks_travel_for_traveler (test_vector_rag.TestVectorRAG) ... ok
test_semantic_embedder_properties (test_vector_rag.TestVectorRAG) ... ok

----------------------------------------------------------------------
Ran 19 tests in 0.120s

OK

CLI Sample Run:

$ python3 app.py --customer-id CUST_001

======================================================================
🏦 Dozer AI Banking Advisor Report | Customer: CUST_001
Source Provenance: DOZER_LOCAL_SQL_EMULATION
======================================================================
Top Recommendation : Voyager Horizon Travel Elite
Product Tier       : Premium Travel
Annual Fee         : $250
Fit Score          : 2.706
Eligibility Status : VERIFIED_ELIGIBLE
----------------------------------------------------------------------
Advisor Rationale:
Based on Elena Rostova's recent transaction profile totaling $2,016.95, the Voyager Horizon Travel Elite is the optimal product (with a $250 annual fee). The customer's highest spending concentration aligns directly with Travel and Flights (Travel ($1,870.70)), while satisfying all creditworthiness standards (FICO 750 vs 720 min). Key benefits include: 5x points on flights and hotels; Priority Pass lounge access; $100 annual TSA PreCheck credit; Zero foreign transaction fees.
======================================================================

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

Prasenjit seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}