feat: Implement conditional AI client initialization, rename core engine, refine transaction classification with new essential list, update risk scoring details, enhance NBO actions and report narrative, and adjust visualization labels.

app.py

@@ -7,40 +7,27 @@ from google import genai
 
 # --- CONFIG AI ---
 GOOGLE_API_KEY = os.getenv("GOOGLE_API_KEY")
-client_ai = genai.Client(api_key=GOOGLE_API_KEY)
+client_ai = genai.Client(api_key=GOOGLE_API_KEY) if GOOGLE_API_KEY else None
 
-# --- UI STYLE BANK NAGARI PREMIUM ---
+# --- UI STYLE: BANK NAGARI PREMIUM (BLUE-GOLD) ---
 custom_css = """
 @import url('https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@400;600;700;800&display=swap');
 body, .gradio-container { font-family: 'Plus Jakarta Sans', sans-serif !important; background-color: #f8fafc !important; }
-
-.nagari-header { 
-    background: linear-gradient(135deg, #0514DE 0%, #82C3EB 100%); 
-    padding: 35px; border-radius: 15px; border-bottom: 6px solid #F7BD87; 
-    margin-bottom: 25px; text-align: center;
-}
+.nagari-header { background: linear-gradient(135deg, #0514DE 0%, #82C3EB 100%); padding: 35px; border-radius: 15px; border-bottom: 6px solid #F7BD87; margin-bottom: 25px; text-align: center; }
 .nagari-header h1 { color: #FFFFFF !important; font-weight: 800 !important; margin: 0; font-size: 2.2em; }
-
-.card-sidebar { 
-    background: #E0EDF4; border-radius: 15px; padding: 25px; 
-    border: 1.5px solid #82C3EB; box-shadow: 0 4px 12px rgba(5, 20, 222, 0.1); 
-}
+.card-sidebar { background: #E0EDF4; border-radius: 15px; padding: 25px; border: 1.5px solid #82C3EB; box-shadow: 0 4px 12px rgba(5, 20, 222, 0.1); }
 .health-badge { background: white; padding: 12px; border-radius: 8px; margin-bottom: 12px; border-left: 5px solid #0514DE; font-size: 0.95em; }
-
-.report-card { 
-    background: white; border-radius: 12px; padding: 30px; 
-    border: 1px solid #E2E8F0; line-height: 1.8; color: #1e293b; 
-}
+.report-card { background: white; border-radius: 12px; padding: 30px; border: 1px solid #E2E8F0; line-height: 1.8; color: #1e293b; }
 .nbo-box { background: #fffdf0; border: 2px solid #F7BD87; padding: 20px; border-radius: 10px; margin-top: 20px; }
 .viz-explanation { background: #f1f5f9; padding: 15px; border-radius: 8px; margin-top: 10px; font-size: 0.9em; border-left: 4px solid #82C3EB; }
 """
 
-class ArchonExecutiveEngine:
+class ArchonPrecisionEngine:
     def __init__(self):
         self.load_data()
 
     def load_data(self):
-        # FASE 1: Data Foundation
+        # FASE 1: DATA FOUNDATION [cite: 1, 3]
         try:
             self.df_txn = pd.read_csv('transactions.csv', parse_dates=['date']).sort_values('date')
             self.df_cust = pd.read_csv('customers.csv')
@@ -58,117 +45,119 @@ class ArchonExecutiveEngine:
         if u_txn.empty or u_info_df.empty: return None
         u_info = u_info_df.iloc[0]
 
-        # --- FASE 2: TRANSACTION INTELLIGENCE (Logic Only) ---
-        essential_cats = {'groceries', 'utilities', 'transport', 'healthcare', 'education'}
-        essential_purposes = {'bill_payment', 'salary_deduction', 'loan_repayment'}
-        disc_cats = {'restaurant', 'cafe', 'entertainment', 'fashion', 'online_shopping', 'travel'}
+        # --- FASE 2: TRANSACTION INTELLIGENCE (Refined Keywords)  ---
+        essential_list = {'groceries', 'utilities', 'transport', 'healthcare', 'education', 'bill', 'loan', 'salary'}
         
         def classify_exp(row):
-            desc = str(row.get('raw_description', '')).lower()
+            # Cek merchant_category, purpose_code, dan deskripsi secara case-insensitive [cite: 20, 21, 23]
             cat = str(row.get('merchant_category', '')).lower()
             purp = str(row.get('purpose_code', '')).lower()
-            if cat in essential_cats or purp in essential_purposes or any(k in desc for k in essential_cats):
+            desc = str(row.get('raw_description', '')).lower()
+            
+            if any(k in cat for k in essential_list) or any(k in purp for k in essential_list) or any(k in desc for k in essential_list):
                 return 'essential'
             return 'discretionary'
 
         u_txn['expense_type'] = u_txn.apply(classify_exp, axis=1)
 
-        # --- FASE 3 & 4: AGGREGATION & RISK ---
+        # --- FASE 3 & 4: RISK SCORING (STRICT 30/20/20/20/10) [cite: 141-145] ---
         inc_txn = u_txn[u_txn['transaction_type'] == 'credit']['amount'].sum()
         ref_inc = max(inc_txn, u_info['monthly_income'])
         exp_total = u_txn[u_txn['transaction_type'] == 'debit']['amount'].sum()
         er = min(exp_total / ref_inc, 1.0) if ref_inc > 0 else 1.0
         
-        # Risk Weights (30/20/20/20/10)
+        # Normalisasi Skor [cite: 132]
         er_s = 1.0 if er > 0.8 else (0.5 if er > 0.5 else 0.0)
         bt_s = 1.0 if len(u_bal) >= 2 and u_bal.iloc[-1]['avg_balance'] < u_bal.iloc[-2]['avg_balance'] else 0.0
         od_s = 1.0 if (u_bal['min_balance'] <= 0).any() else 0.0
         mp_s = 1.0 if (u_rep['status'] == 'late').any() else 0.0
         
+        # Rumus Final Risk Score [cite: 147]
         score = (0.3 * er_s) + (0.2 * bt_s) + (0.2 * od_s) + (0.2 * mp_s) + 0.1
-        risk_lv = "HIGH" if score >= 0.7 else ("MEDIUM" if score >= 0.4 else "LOW")
+        risk_lv = "HIGH" if score >= 0.70 else ("MEDIUM" if score >= 0.40 else "LOW")
 
-        # --- FASE 5: NBO ENGINE ---
+        # --- FASE 5: NBO ENGINE (Actionable Detail) [cite: 178] ---
         if risk_lv == "HIGH" or mp_s == 1:
-            action = "Restructuring Suggestion"
-            desc = "Langkah darurat untuk mengatur ulang jadwal cicilan agar nasabah tidak gagal bayar."
-            steps = ["Penurunan bunga sementara", "Perpanjangan tenor", "Konsolidasi utang."]
+            action, desc = "Restructuring Suggestion", "Fokus penyelamatan kredit untuk menghindari gagal bayar."
+            steps = ["Penjadwalan ulang tenor", "Konsolidasi kewajiban", "Review bunga."] [cite: 220]
         elif er > 0.6:
-            action = "Spending Control"
-            desc = "Langkah strategis membatasi pengeluaran gaya hidup untuk menyelamatkan kas harian."
-            steps = ["Limit QRIS harian Rp500rb", "Non-aktifkan auto-debit non-esensial", "Evaluasi belanja online."]
+            action, desc = "Spending Control", "Pengendalian langsung pada pos belanja non-esensial."
+            steps = ["Setting limit QRIS Nagari", "Blokir sementara merchant gaya hidup", "Budgeting manual."] [cite: 207]
         elif risk_lv == "LOW":
-            action = "Promote Investment"
-            desc = "Optimalisasi kelebihan dana nasabah ke produk investasi yang memberikan bagi hasil."
-            steps = ["Deposito Nagari Gold", "Tabungan Berjangka", "Pilihan Reksa Dana."]
+            action, desc = "Promote Investment", "Optimalisasi dana surplus ke produk aset produktif."
+            steps = ["Tabungan Berjangka", "Deposito Gold", "Investasi Reksa Dana."] [cite: 194]
         else:
-            action = "Financial Education"
-            desc = "Edukasi berkala agar nasabah bisa mempertahankan stabilitas keuangannya."
-            steps = ["Modul Budgeting", "Tips belanja cerdas", "Webinar Perencanaan Keuangan."]
+            action, desc = "Financial Education", "Edukasi berkala untuk stabilitas jangka panjang."
+            steps = ["Modul cerdas belanja", "Webinar Perencanaan", "Tips Cashflow."] [cite: 214]
 
         return risk_lv, score, er, u_bal, u_txn, exp_total, ref_inc, action, desc, steps, er_s, bt_s, od_s, mp_s
 
-    def create_narrative(self, risk_lv, score, er, u_bal, exp, inc, action, desc, steps, cid, u_txn):
-        # Fase 6: Narrative Summary
-        txt = f"### ANALISIS EKSEKUTIF ARCHON: NASABAH {cid}\n\n"
-        txt += f"Hasil evaluasi hibrida menunjukkan tingkat resiliensi **{risk_lv}** (Skor: {score:.2f}).\n\n"
+    def build_report(self, risk_lv, score, er, u_bal, exp, inc, action, desc, steps, cid, u_txn):
+        # FASE 6: INSIGHT VISUALIZATION [cite: 280]
+        txt = f"### ANALISIS EKSEKUTIF: {risk_lv} RISK\n\n"
+        txt += f"**Identitas**: {cid} | **Skor Risiko**: {score:.2f}\n\n"
         
-        txt += f"**Mengapa Hasil Ini Muncul?**\n"
-        txt += f"* **Rasio Belanja ({er:.1%})**: Bapak/Ibu menggunakan Rp{exp:,.0f} dari pendapatan Rp{inc:,.0f}. "
-        txt += "Rasio di atas 80% sangat kritis karena hampir tidak menyisakan dana darurat." if er > 0.8 else "Angka ini menunjukkan kontrol belanja yang sangat baik."
+        txt += f"**1. Mengapa Level Ini?**\n"
+        txt += f"* **Rasio Pengeluaran ({er:.1%})**: Anda menghabiskan Rp{exp:,.0f} dari pendapatan Rp{inc:,.0f}. "
+        txt += "Rasio di atas 80% sangat kritis." if er > 0.8 else "Angka ini menunjukkan manajemen yang sehat."
         
         if not u_bal.empty:
-            txt += f"\n* **Analisis Saldo**: Saldo terakhir Rp{u_bal.iloc[-1]['avg_balance']:,.0f}. "
-            txt += "Waspada, tren saldo sedang menurun, yang artinya nasabah sedang melakukan 'pemakanan tabungan'." if len(u_bal) > 1 and u_bal.iloc[-1]['avg_balance'] < u_bal.iloc[-2]['avg_balance'] else "Tren saldo tumbuh stabil."
+            txt += f"\n* **Analisis Saldo**: Saldo saat ini Rp{u_bal.iloc[-1]['avg_balance']:,.0f}. "
+            txt += "Tren saldo sedang menurun (Drawdown)." if len(u_bal) > 1 and u_bal.iloc[-1]['avg_balance'] < u_bal.iloc[-2]['avg_balance'] else "Pertumbuhan saldo positif."
 
         txt += f"\n\n<div class='nbo-box'>REKOMENDASI TINDAKAN (NBO): {action}\n\n"
-        txt += f"**Bagaimana:** {desc}\n\n"
-        txt += f"**Langkah-Langkah:**\n"
+        txt += f"**Langkah Implementasi:**\n"
         for i, s in enumerate(steps, 1): txt += f"{i}. {s}\n"
         txt += f"</div>"
         return txt
 
     def create_viz(self, u_bal, u_txn):
-        # 1. Arus Kas (Inflow vs Outflow)
+        # 1. Cashflow
         u_txn['m'] = u_txn['date'].dt.to_period('M').dt.to_timestamp()
         cf = u_txn.groupby(['m', 'transaction_type'])['amount'].sum().unstack().fillna(0)
         f1 = go.Figure()
-        f1.add_trace(go.Bar(x=cf.index, y=cf.get('credit', 0), name='Pemasukan (Inflow)', marker_color='#82C3EB'))
-        f1.add_trace(go.Bar(x=cf.index, y=cf.get('debit', 0), name='Pengeluaran (Outflow)', marker_color='#0514DE'))
-        f1.update_layout(title="Laporan Arus Kas Bulanan", barmode='group', template='plotly_white')
+        f1.add_trace(go.Bar(x=cf.index, y=cf.get('credit', 0), name='Pemasukan (Light Blue)', marker_color='#82C3EB'))
+        f1.add_trace(go.Bar(x=cf.index, y=cf.get('debit', 0), name='Pengeluaran (Deep Blue)', marker_color='#0514DE'))
+        f1.update_layout(title="Arus Kas Bulanan", barmode='group', template='plotly_white')
 
         # 2. Tren Saldo
         f2 = go.Figure()
-        f2.add_trace(go.Scatter(x=u_bal['month'], y=u_bal['avg_balance'], name='Saldo Rata-rata', line=dict(color='#F7BD87', width=4)))
+        f2.add_trace(go.Scatter(x=u_bal['month'], y=u_bal['avg_balance'], name='Rata-rata Saldo', line=dict(color='#F7BD87', width=4)))
         f2.update_layout(title="Kesehatan Pertumbuhan Saldo", template='plotly_white')
         
-        # 3. Komposisi Belanja (New: Essential vs Discretionary)
-        exp_dist = u_txn[u_txn['transaction_type'] == 'debit'].groupby('expense_type')['amount'].sum()
-        f3 = go.Figure(data=[go.Pie(labels=exp_dist.index, values=exp_dist.values, hole=.4, marker_colors=['#0514DE', '#F7BD87'])])
-        f3.update_layout(title="Komposisi Pengeluaran (Gaya Hidup vs Kebutuhan)")
+        # 3. FIXED Pie Chart: Explicit Color Mapping 
+        exp_dist = u_txn[u_txn['transaction_type'] == 'debit'].groupby('expense_type')['amount'].sum().reset_index()
+        color_map = {'essential': '#0514DE', 'discretionary': '#F7BD87'} # Biru=Essential, Emas=Disc
+        
+        f3 = go.Figure(data=[go.Pie(
+            labels=exp_dist['expense_type'], 
+            values=exp_dist['amount'], 
+            hole=.4,
+            marker=dict(colors=[color_map[x] for x in exp_dist['expense_type']])
+        )])
+        f3.update_layout(title="Komposisi Gaya Hidup vs Kebutuhan")
         
         return f1, f2, f3
 
 # --- UI LOGIC ---
-engine = ArchonExecutiveEngine()
+engine = ArchonPrecisionEngine()
 
 def run_app(cust_id):
     res = engine.analyze(cust_id)
-    if not res: return "## ❌ ID Tidak Valid", "Gunakan ID C0001 - C0120", None, None, None
+    if not res: return "❌ ID Tidak Valid", "Gunakan C0001 - C0120", None, None, None
     
     risk_lv, score, er, u_bal, u_txn, exp, inc, action, desc, steps, er_s, bt_s, od_s, mp_s = res
-    report = engine.create_narrative(risk_lv, score, er, u_bal, exp, inc, action, desc, steps, cust_id, u_txn)
+    report = engine.build_report(risk_lv, score, er, u_bal, exp, inc, action, desc, steps, cust_id, u_txn)
     p1, p2, p3 = engine.create_viz(u_bal, u_txn)
     
     color = "#ef4444" if risk_lv == "HIGH" else ("#f59e0b" if risk_lv == "MEDIUM" else "#10b981")
     sidebar = f"""
     <div class='card-sidebar'>
-        <h2 style='color: #0514DE; margin:0;'>Summary Report</h2>
-        <div style='background:{color}; color:white; padding:10px 20px; border-radius:30px; font-weight:bold; display:inline-block; margin:15px 0;'>{risk_lv} RISK LEVEL</div>
-        <div class='health-badge'><b>Risk Score:</b> {score:.2f} / 1.00</div>
-        <div class='health-badge'><b>Expense Ratio:</b> {er:.1%} {'⚠️' if er > 0.8 else '✅'}</div>
-        <div class='health-badge'><b>Balance Trend:</b> {'🔻 Menurun' if bt_s == 1 else '🔺 Stabil'}</div>
-        <div class='health-badge'><b>Credit History:</b> {'⚠️ Late' if mp_s == 1 else '✔️ Lancar'}</div>
+        <h2 style='color: #0514DE; margin:0;'>Archon Quick Look</h2>
+        <div style='background:{color}; color:white; padding:10px 20px; border-radius:30px; font-weight:bold; display:inline-block; margin:15px 0;'>{risk_lv} RISK</div>
+        <div class='health-badge'><b>Score:</b> {score:.2f} / 1.00</div>
+        <div class='health-badge'><b>ER:</b> {er:.1%} {'⚠️' if er > 0.8 else '✔️'}</div>
+        <div class='health-badge'><b>Trend:</b> {'🔻 Turun' if bt_s == 1 else '🔺 Stabil'}</div>
     </div>
     """
     return sidebar, report, p1, p2, p3
@@ -185,19 +174,17 @@ with gr.Blocks(css=custom_css) as demo:
                 with gr.Tab("Audit Summary"):
                     out_report = gr.Markdown(elem_classes="report-card")
                 with gr.Tab("Visual Analytics"):
-                    gr.Markdown("### 1. Analisis Arus Kas")
+                    gr.Markdown("### 1. Inflow vs Outflow")
                     plot_cf = gr.Plot()
-                    gr.HTML("<div class='viz-explanation'><b>Cara Baca:</b> Batang Muda (Pemasukan) harus lebih tinggi dari Batang Tua (Pengeluaran). Jika Batang Tua dominan, likuiditas nasabah dalam bahaya.</div>")
-                    
+                    gr.HTML("<div class='viz-explanation'><b>Arus Kas:</b> Batang muda (Pemasukan) harus lebih tinggi dari batang tua (Pengeluaran).</div>")
                     gr.Markdown("---")
-                    gr.Markdown("### 2. Tren Pertumbuhan Saldo")
+                    gr.Markdown("### 2. Tren Saldo")
                     plot_bal = gr.Plot()
-                    gr.HTML("<div class='viz-explanation'><b>Cara Baca:</b> Garis yang naik menunjukkan nasabah memiliki daya tahan (resiliensi) terhadap krisis ekonomi.</div>")
-                    
+                    gr.HTML("<div class='viz-explanation'><b>Resiliensi:</b> Garis naik menunjukkan nasabah kuat menghadapi krisis.</div>")
                     gr.Markdown("---")
-                    gr.Markdown("### 3. Komposisi Gaya Hidup")
+                    gr.Markdown("### 3. Gaya Hidup (Essential vs Discretionary)")
                     plot_dist = gr.Plot()
-                    gr.HTML("<div class='viz-explanation'><b>Cara Baca:</b> Semakin besar porsi Biru (Essential), semakin sehat keuangan nasabah. Porsi Emas (Discretionary) yang besar menunjukkan gaya hidup boros.</div>")
+                    gr.HTML("<div class='viz-explanation'><b>Warna:</b> Biru = Kebutuhan Pokok (Essential). Emas = Gaya Hidup (Discretionary).</div>")
 
     btn.click(fn=run_app, inputs=id_in, outputs=[out_side, out_report, plot_cf, plot_bal, plot_dist])