Upload folder using huggingface_hub

.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# App outputs (generated files — not needed in the image)
+outputs/
+test_outputs/
+*.xlsx
+*.docx
+*.pptx
+
+# Secrets & env
+.env
+
+# GUI (desktop-only, not needed for web deployment)
+gui/
+build/
+dist/
+*.spec
+build_exe.py
+
+# Database (ephemeral, let the container create it fresh)
+storage/history.db
+web_app/financial_audit.db
+
+# IDE
+.vscode/
+.idea/
+*.swp

Dockerfile

@@ -0,0 +1,39 @@
+# ── Base ───────────────────────────────────────────────────────────────────────
+FROM python:3.11-slim
+
+# ── System dependencies ────────────────────────────────────────────────────────
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    libxml2-dev \
+    libxslt-dev \
+    zlib1g-dev \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# ── App directory ──────────────────────────────────────────────────────────────
+WORKDIR /app
+
+# ── Install Python dependencies ────────────────────────────────────────────────
+COPY web_app/requirements.txt ./requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+# ── Copy full application source ───────────────────────────────────────────────
+COPY . .
+
+# ── Create writable directories ────────────────────────────────────────────────
+RUN mkdir -p outputs storage web_app/__pycache__ \
+    && chmod -R 777 /app
+
+# ── Streamlit config — disable telemetry, set port ────────────────────────────
+RUN mkdir -p /root/.streamlit
+COPY web_app/streamlit_config.toml /root/.streamlit/config.toml
+
+# ── HF Spaces: port 7860 ──────────────────────────────────────────────────────
+EXPOSE 7860
+
+# ── Launch Streamlit ───────────────────────────────────────────────────────────
+CMD ["streamlit", "run", "web_app/app.py", \
+     "--server.port=7860", \
+     "--server.address=0.0.0.0", \
+     "--server.headless=true", \
+     "--browser.gatherUsageStats=false"]

README.md

@@ -1,10 +1,64 @@
 ---
-title: Financial2API
-emoji: 🌍
-colorFrom: yellow
-colorTo: purple
+title: Financial Statement Analyzer
+emoji: 📈
+colorFrom: blue
+colorTo: green
 sdk: docker
 pinned: false
+app_port: 7860
+short_description: AI financial analysis portal with free BYOK models.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 📈 Financial Statement Analyzer
+
+Cloud-hosted AI analysis portal. Fetches financial statements for any listed company (Indian NSE/BSE or global NYSE/NASDAQ), computes ratios, generates AI narratives, and produces downloadable Excel, Word, and PowerPoint reports.
+
+**Bring Your Own Key (BYOK)** — keys stay in your browser session only, never stored.
+
+## 🆓 Free AI Options (No Credit Card Needed)
+
+| Provider | Model | Where to get key |
+|---|---|---|
+| **Groq** *(recommended)* | Llama 3.3 70B | [console.groq.com](https://console.groq.com/keys) — instant signup |
+| **Google Gemini** | Gemini 2.0 Flash | [aistudio.google.com](https://aistudio.google.com/app/apikey) — free tier |
+
+## 💳 Optional Paid AIs
+
+| Provider | Model | Where to get key |
+|---|---|---|
+| Anthropic Claude | Claude Haiku | [console.anthropic.com](https://console.anthropic.com/) |
+| OpenAI | GPT-4o mini | [platform.openai.com](https://platform.openai.com/api-keys) |
+
+## How to Use
+
+1. Open the app → paste a **free Groq or Gemini key** in the sidebar
+2. Enter a company name/ticker (e.g. TCS, Reliance, AAPL)
+3. Pick formats (Excel / Word / PowerPoint) and click **Analyze**
+4. Download your reports instantly
+
+## Features
+
+- 🔍 **Smart Ticker Resolution** — resolves company names via yfinance + FMP
+- 📊 **Financial Data** — Income statement, balance sheet, cash flow, 5–10 year history
+- 🧮 **Ratio Engine** — 30+ ratios + DuPont decomposition
+- 🤖 **Multi-Model AI** — Use multiple providers simultaneously; outputs combined with attribution
+- 📥 **Export Reports** — Excel workbook, Word summary, PowerPoint pitch deck
+- 📜 **Audit Trail** — Every run logged with user, ticker, formats, and AI models used
+
+## Optional: Persistent Audit Logs (Supabase)
+
+Without Supabase, logs reset on redeploy. To persist them:
+
+| Secret | Value |
+|---|---|
+| `SUPABASE_URL` | Your Supabase project URL |
+| `SUPABASE_KEY` | Supabase anon public key |
+
+## Tech Stack
+
+- **Frontend**: Streamlit with custom dark glassmorphism CSS
+- **Data**: yfinance (primary), FMP API (secondary), screener.in (Indian fallback)  
+- **AI**: Groq/Llama (free), Gemini (free tier), Claude, ChatGPT
+- **Reports**: openpyxl (Excel), python-docx (Word), python-pptx (PowerPoint)
+- **Audit**: SQLite (local) or Supabase (cloud persistent)
+- **Container**: Docker on Python 3.11-slim

builders/__init__.py

@@ -0,0 +1 @@
+# builders package

builders/build_docx.py

@@ -0,0 +1,379 @@
+#!/usr/bin/env python3
+"""
+builders/build_docx.py — Enhanced Word report builder.
+Sections: Cover, Executive Summary, Company Profile, Industry Profile,
+SWOT, Industry Trends, Financial Trends, Ratios, DuPont, Peer Comparison,
+Key Insights, Risks, Things to Watch, Limitations, Sources.
+"""
+import json, sys, datetime
+from pathlib import Path
+from typing import Dict, List, Optional
+
+try:
+    from docx import Document
+    from docx.shared import Pt, Cm, RGBColor, Inches
+    from docx.enum.text import WD_ALIGN_PARAGRAPH
+    from docx.enum.table import WD_ALIGN_VERTICAL, WD_TABLE_ALIGNMENT
+    from docx.oxml.ns import qn
+    from docx.oxml import OxmlElement
+except ImportError:
+    print("ERROR: pip install python-docx", file=sys.stderr); sys.exit(1)
+
+# ── Colors ────────────────────────────────────────────────────────────────────
+NAVY = RGBColor(0x1F, 0x4E, 0x78)
+GRAY = RGBColor(0x59, 0x59, 0x59)
+GREEN_DARK = RGBColor(0x37, 0x5A, 0x3D)
+
+# ── Formatting helpers ────────────────────────────────────────────────────────
+
+def _shd(cell, hex_color):
+    tcp = cell._tc.get_or_add_tcPr()
+    s = OxmlElement("w:shd")
+    s.set(qn("w:val"), "clear"); s.set(qn("w:color"), "auto"); s.set(qn("w:fill"), hex_color)
+    tcp.append(s)
+
+def _borders(cell, color="BFBFBF", sz="4"):
+    tcp = cell._tc.get_or_add_tcPr()
+    tb = OxmlElement("w:tcBorders")
+    for edge in ("top","left","bottom","right"):
+        b = OxmlElement(f"w:{edge}")
+        b.set(qn("w:val"),"single"); b.set(qn("w:sz"),sz); b.set(qn("w:color"),color)
+        tb.append(b)
+    tcp.append(tb)
+
+def _hdr_repeat(row):
+    trp = row._tr.get_or_add_trPr()
+    th = OxmlElement("w:tblHeader"); th.set(qn("w:val"),"true"); trp.append(th)
+
+def _add_heading(doc, text, level=1):
+    sizes = {0:28, 1:18, 2:14, 3:12}
+    p = doc.add_paragraph()
+    r = p.add_run(text)
+    r.font.size = Pt(sizes.get(level, 12)); r.font.bold = True
+    r.font.color.rgb = NAVY; r.font.name = "Calibri"
+    p.paragraph_format.space_before = Pt(12); p.paragraph_format.space_after = Pt(6)
+    return p
+
+def _add_text(doc, text, size=11):
+    if not text: return
+    for block in [b.strip() for b in str(text).split("\n\n") if b.strip()]:
+        p = doc.add_paragraph()
+        r = p.add_run(block.replace("\n"," "))
+        r.font.size = Pt(size); r.font.name = "Calibri"
+        p.paragraph_format.space_after = Pt(8)
+
+def _fmt_v(v, kind="money", currency="INR", units="Crores"):
+    if v is None: return "\u2014"
+    try:
+        sym = "\u20b9" if currency == "INR" else ("$" if currency == "USD" else "")
+        if kind == "money":
+            # Data is already scaled (Crores for INR, Millions for USD)
+            av = abs(v)
+            if currency == "INR":
+                if av >= 100000:  return f"{sym}{v/100000:,.2f} L.Cr"
+                return f"{sym}{v:,.2f} Cr"
+            else:
+                if av >= 1000:    return f"{sym}{v/1000:,.2f}B"
+                return f"{sym}{v:,.2f}M"
+        if kind == "money_dec": return f"{v:,.2f}"
+        if kind == "pct":   return f"{v*100:.1f}%"
+        if kind in ("ratio", "days"): return f"{v:.2f}"
+        return str(v)
+    except: return str(v)
+
+def _page_break(doc):
+    p = doc.add_paragraph(); p.add_run().add_break()
+
+# ── Table builder ─────────────────────────────────────────────────────────────
+
+def _table(doc, headers, rows, formats=None, currency="INR", units="Crores"):
+    t = doc.add_table(rows=1+len(rows), cols=len(headers))
+    t.alignment = WD_TABLE_ALIGNMENT.LEFT
+    hc = t.rows[0].cells
+    for i, h in enumerate(headers):
+        hc[i].text = ""
+        p = hc[i].paragraphs[0]
+        r = p.add_run(str(h)); r.font.bold = True; r.font.color.rgb = RGBColor(0xFF,0xFF,0xFF)
+        r.font.size = Pt(10); r.font.name = "Calibri"
+        p.alignment = WD_ALIGN_PARAGRAPH.CENTER if i > 0 else WD_ALIGN_PARAGRAPH.LEFT
+        _shd(hc[i], "1F4E78"); _borders(hc[i])
+    _hdr_repeat(t.rows[0])
+    for ri, row in enumerate(rows):
+        bg = "F2F2F2" if ri % 2 else "FFFFFF"
+        cells = t.rows[ri+1].cells
+        for ci, val in enumerate(row):
+            cells[ci].text = ""
+            p = cells[ci].paragraphs[0]
+            kind = formats[ci] if formats and ci < len(formats) else "money"
+            if ci == 0:
+                text = str(val) if val is not None else "—"
+            else:
+                text = _fmt_v(val, kind, currency, units)
+            r = p.add_run(text); r.font.size = Pt(10); r.font.name = "Calibri"
+            p.alignment = WD_ALIGN_PARAGRAPH.LEFT if ci == 0 else WD_ALIGN_PARAGRAPH.RIGHT
+            _shd(cells[ci], bg); _borders(cells[ci])
+    doc.add_paragraph().paragraph_format.space_after = Pt(6)
+    return t
+
+def _gather(items, src, years):
+    return [[label] + [(src.get(key) or [None]*len(years))[:len(years)][i]
+                       for i in range(len(years))] for label, key in items]
+
+# ── Section builders ──────────────────────────────────────────────────────────
+
+def _cover(doc, data):
+    co = data.get("company", {})
+    units_label = data.get("units_label", data.get("units", "Crores"))
+    currency = data.get("currency", co.get("currency", "INR"))
+    for _ in range(3): doc.add_paragraph()
+    p = doc.add_paragraph()
+    r = p.add_run("Financial Statement Analysis")
+    r.font.size = Pt(32); r.font.bold = True; r.font.color.rgb = NAVY; r.font.name = "Calibri"
+    p = doc.add_paragraph()
+    r = p.add_run(co.get("name",""))
+    r.font.size = Pt(24); r.font.color.rgb = GRAY; r.font.name = "Calibri"
+    p = doc.add_paragraph()
+    r = p.add_run(f"{co.get('ticker','')}  \u00b7  {co.get('exchange','')}  \u00b7  {co.get('industry','')}")
+    r.font.size = Pt(13); r.font.color.rgb = GRAY; r.font.italic = True; r.font.name = "Calibri"
+    for _ in range(6): doc.add_paragraph()
+    for text in [
+        f"Report date: {co.get('report_date', datetime.date.today().isoformat())}",
+        f"Analysis window: {', '.join(data.get('years',[]))}",
+        f"Reporting currency: {currency}  |  Units: {units_label}",
+        f"Market cap: {co.get('market_cap', 'N/A')}  |  Share price: {co.get('share_price', 'N/A')}",
+        f"AI models used: {', '.join(data.get('models_used',[]) or ['Data-only (no AI narrative)'])}",
+        f"Data source: {data.get('source', 'Yahoo Finance (yfinance)')}",
+    ]:
+        p = doc.add_paragraph(); r = p.add_run(text)
+        r.font.size = Pt(11); r.font.color.rgb = GRAY; r.font.name = "Calibri"
+    _page_break(doc)
+
+
+def _swot_section(doc, data):
+    _add_heading(doc, "SWOT Analysis", 1)
+    swot = data.get("swot", {})
+    configs = [
+        ("Strengths",     "strengths",     "C6EFCE", GREEN_DARK),
+        ("Weaknesses",    "weaknesses",    "FFC7CE", RGBColor(0xC0,0x00,0x00)),
+        ("Opportunities", "opportunities", "DDEBF7", NAVY),
+        ("Threats",       "threats",       "FFEB9C", RGBColor(0x7F,0x60,0x00)),
+    ]
+    t = doc.add_table(rows=2, cols=2)
+    t.alignment = WD_TABLE_ALIGNMENT.LEFT
+    idx = 0
+    for row_i in range(2):
+        for col_i in range(2):
+            if idx >= len(configs): break
+            label, key, bg, color = configs[idx]; idx += 1
+            cell = t.cell(row_i, col_i)
+            cell.text = ""
+            p = cell.paragraphs[0]
+            r = p.add_run(label); r.font.bold = True; r.font.size = Pt(12)
+            r.font.color.rgb = color; r.font.name = "Calibri"
+            _shd(cell, bg)
+            for item in swot.get(key, []):
+                p2 = cell.add_paragraph(f"• {item}")
+                for run in p2.runs: run.font.size = Pt(10); run.font.name = "Calibri"
+    doc.add_paragraph()
+
+
+def _trends_section(doc, data):
+    _add_heading(doc, "Multi-Year Financial Trends", 1)
+    years = data.get("years", [])
+    currency = data.get("currency", "INR")
+    units_label = data.get("units_label", data.get("units", "Crores"))
+    trend = data.get("trend_analysis", {})
+
+    for section_title, prose_key, items, src_key, fmts in [
+        ("Revenue & Profitability", "revenue_and_profitability",
+         [("Revenue","revenue"),("Gross Profit","gross_profit"),("Operating Income","operating_income"),
+          ("Net Income","net_income")],
+         "income_statement", ["text"]+["money"]*len(years)),
+        ("Balance Sheet Strength", "balance_sheet_strength",
+         [("Total Assets","total_assets"),("Total Equity","total_equity"),
+          ("Long-term Debt","long_term_debt"),("Current Ratio","current_ratio")],
+         "balance_sheet", ["text"]+["money"]*len(years)),
+        ("Cash Flow Generation", "cash_flow_generation",
+         [("Cash from Operations","cash_from_operations"),("Capex","capex"),("Free Cash Flow","free_cash_flow")],
+         "cash_flow", ["text"]+["money"]*len(years)),
+    ]:
+        _add_heading(doc, section_title, 2)
+        _add_text(doc, trend.get(prose_key,""))
+        src_data = data.get(src_key, {})
+        if src_key == "balance_sheet":
+            merged = dict(data.get("balance_sheet",{})); merged.update(data.get("ratios",{}))
+            src_data = merged
+        rows = _gather(items, src_data, years)
+        _table(doc, [f"({units_label})"]+years, rows, fmts, currency, units_label)
+
+
+def _ratio_section(doc, data):
+    _add_heading(doc, "Financial Ratio Analysis", 1)
+    _add_text(doc, data.get("ratio_analysis_commentary",""))
+    years = data.get("years", [])
+    ratios = data.get("ratios", {})
+    currency = data.get("currency", "INR")
+    units_label = data.get("units_label", data.get("units", "Crores"))
+    for sec_name, items in [
+        ("Profitability", [("Gross Margin","gross_margin","pct"),("Operating Margin","operating_margin","pct"),
+                           ("Net Margin","net_margin","pct"),("ROE","roe","pct"),("ROIC","roic","pct")]),
+        ("Liquidity & Solvency", [("Current Ratio","current_ratio","ratio"),("Quick Ratio","quick_ratio","ratio"),
+                                   ("Debt-to-Equity","debt_to_equity","ratio"),("Net Debt/EBITDA","net_debt_to_ebitda","ratio")]),
+        ("Efficiency", [("Asset Turnover","asset_turnover","ratio"),("DSO (days)","days_sales_outstanding","days"),
+                        ("DPO (days)","days_payables","days"),("CCC (days)","cash_conversion_cycle","days")]),
+        ("Cash Flow Quality", [("OCF/Net Income","ocf_to_net_income","ratio"),("FCF Margin","fcf_margin","pct"),
+                                ("FCF Conversion","fcf_conversion","ratio")]),
+    ]:
+        _add_heading(doc, sec_name, 3)
+        rows = []
+        for label, key, kind in items:
+            vals = (ratios.get(key,[]) + [None]*len(years))[:len(years)]
+            rows.append([label] + list(vals))
+        kinds = ["text"] + [items[0][2]]*len(years)
+        _table(doc, ["Metric"]+years, rows, kinds, currency, units_label)
+
+
+def _dupont_section(doc, data):
+    _add_heading(doc, "DuPont Analysis", 1)
+    p = doc.add_paragraph()
+    r = p.add_run("ROE  =  Net Margin  \u00d7  Asset Turnover  \u00d7  Equity Multiplier")
+    r.font.size = Pt(11); r.font.bold = True; r.font.name = "Calibri"
+    years = data.get("years", [])
+    dp = data.get("dupont", {})
+    currency = data.get("currency", "INR")
+    rows = []
+    for label, key, kind in [
+        ("Net Margin","net_margin","pct"),("\u00d7 Asset Turnover","asset_turnover","ratio"),
+        ("\u00d7 Equity Multiplier","equity_multiplier","ratio"),("= ROE (DuPont)","roe_computed","pct"),
+        ("ROE (Reported)","roe_reported","pct"),
+    ]:
+        vals = (dp.get(key,[]) + [None]*len(years))[:len(years)]
+        rows.append([label]+list(vals))
+    _table(doc, ["Component"]+years, rows, ["text"]+["pct"]*len(years), currency)
+
+
+def _peer_section(doc, data):
+    _add_heading(doc, "Peer Benchmarking", 1)
+    _add_text(doc, data.get("peer_comparison_commentary",""))
+    peers = data.get("peers", [])
+    currency = data.get("currency", "INR")
+    units_label = data.get("units_label", "Crores")
+    co = data.get("company",{}); ratios = data.get("ratios",{})
+    inc = data.get("income_statement",{}); val = data.get("valuation_snapshot",{})
+    def last(arr):
+        for v in reversed(arr or []):
+            if v is not None: return v
+        return None
+    headers = ["Company","Revenue","Op Margin","Net Margin","ROIC","D/E","FCF Margin","P/E"]
+    fmts = ["text","money","pct","pct","pct","ratio","pct","ratio"]
+    rows = [[
+        co.get("name",co.get("ticker",""))+" (Target)",
+        last(inc.get("revenue",[])), last(ratios.get("operating_margin",[])),
+        last(ratios.get("net_margin",[])), last(ratios.get("roic",[])),
+        last(ratios.get("debt_to_equity",[])), last(ratios.get("fcf_margin",[])),
+        val.get("pe_ttm"),
+    ]]
+    if not peers:
+        doc.add_paragraph("Peer comparison data not available for this run.")
+    for p in peers:
+        rows.append([p.get("name",p.get("ticker","")), p.get("revenue"), p.get("operating_margin"),
+                     p.get("net_margin"), p.get("roic"), p.get("debt_to_equity"),
+                     p.get("fcf_margin"), p.get("pe_ttm")])
+    if rows:
+        _table(doc, headers, rows, fmts, currency, units_label)
+
+
+def _bullets(doc, items, heading=None, level=1):
+    if heading: _add_heading(doc, heading, level)
+    for item in items:
+        if isinstance(item, dict):
+            p = doc.add_paragraph(style="List Bullet")
+            r1 = p.add_run(f"{item.get('category','')}: "); r1.font.bold=True; r1.font.size=Pt(11); r1.font.name="Calibri"
+            r2 = p.add_run(item.get("description","")); r2.font.size=Pt(11); r2.font.name="Calibri"
+        else:
+            p = doc.add_paragraph(str(item), style="List Bullet")
+            for r in p.runs: r.font.size=Pt(11); r.font.name="Calibri"
+        p.paragraph_format.space_after = Pt(2)
+
+
+def _sources_section(doc, data):
+    _add_heading(doc, "Sources", 1)
+    for i, src in enumerate(data.get("sources",[]), 1):
+        p = doc.add_paragraph()
+        p.add_run(f"{i}. ").font.size = Pt(10)
+        url_r = p.add_run(src.get("url",""))
+        url_r.font.size=Pt(10); url_r.font.color.rgb=RGBColor(0x05,0x63,0xC1); url_r.font.name="Calibri"
+        suffix = ""
+        if src.get("description"): suffix += f" — {src['description']}"
+        if src.get("retrieved"):   suffix += f" (retrieved {src['retrieved']})"
+        if suffix:
+            sr = p.add_run(suffix); sr.font.size=Pt(10); sr.font.color.rgb=GRAY; sr.font.name="Calibri"
+
+
+def _disclaimer(doc):
+    p = doc.add_paragraph()
+    r = p.add_run(
+        "Disclaimer: This report is generated from public financial data and AI analysis for informational "
+        "purposes only. It is not investment advice. Verify all figures against primary sources before "
+        "making any financial decisions."
+    )
+    r.font.size=Pt(9); r.font.italic=True; r.font.color.rgb=GRAY; r.font.name="Calibri"
+    p.paragraph_format.space_before=Pt(12)
+
+
+# ── Orchestrator ──────────────────────────────────────────────────────────────
+
+def build_document(data: dict, output_path: str) -> None:
+    doc = Document()
+    for section in doc.sections:
+        section.left_margin = section.right_margin = Cm(2.0)
+        section.top_margin  = section.bottom_margin = Cm(2.0)
+
+    _cover(doc, data)
+
+    # Executive Summary
+    _add_heading(doc, "Executive Summary", 1)
+    _add_text(doc, data.get("executive_summary",""))
+
+    # Company & Industry Profile
+    _add_heading(doc, "Company Profile", 1)
+    _add_text(doc, data.get("company_overview",""))
+
+    _add_heading(doc, "Industry Profile", 1)
+    _add_text(doc, data.get("industry_profile",""))
+
+    _add_heading(doc, "Industry Trends", 1)
+    _add_text(doc, data.get("industry_trends",""))
+
+    _swot_section(doc, data)
+    _trends_section(doc, data)
+    _ratio_section(doc, data)
+    _dupont_section(doc, data)
+    _peer_section(doc, data)
+
+    if data.get("key_insights"):
+        _bullets(doc, data["key_insights"], "Key Insights", 1)
+    if data.get("risks"):
+        _bullets(doc, data["risks"], "Risks", 1)
+    if data.get("things_to_watch"):
+        _bullets(doc, data["things_to_watch"], "Things to Watch", 1)
+    if data.get("limitations_and_caveats"):
+        _bullets(doc, data["limitations_and_caveats"], "Limitations & Caveats", 1)
+
+    _sources_section(doc, data)
+    _disclaimer(doc)
+
+    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+    doc.save(output_path)
+
+
+if __name__ == "__main__":
+    import argparse
+    p = argparse.ArgumentParser()
+    p.add_argument("--input","-i",required=True)
+    p.add_argument("--output","-o",required=True)
+    args = p.parse_args()
+    with open(args.input, encoding="utf-8") as f:
+        data = json.load(f)
+    build_document(data, args.output)
+    print(f"Wrote: {args.output}")

builders/build_excel.py

@@ -0,0 +1,446 @@
+#!/usr/bin/env python3
+"""
+builders/build_excel.py — Enhanced Excel workbook builder.
+Reads the skill's original builder and adds DuPont, SWOT, and Indian unit support.
+"""
+import json, sys, datetime
+from pathlib import Path
+
+try:
+    from openpyxl import Workbook
+    from openpyxl.styles import Font, PatternFill, Alignment, Border, Side
+    from openpyxl.utils import get_column_letter
+    from openpyxl.chart import BarChart, LineChart, Reference
+except ImportError:
+    print("ERROR: pip install openpyxl", file=sys.stderr); sys.exit(1)
+
+# ── Style constants ───────────────────────────────────────────────────────────
+HDR_FILL  = PatternFill("solid", fgColor="1F4E78")
+HDR_FONT  = Font(name="Calibri", size=11, bold=True, color="FFFFFF")
+SEC_FILL  = PatternFill("solid", fgColor="D9E1F2")
+SEC_FONT  = Font(name="Calibri", size=11, bold=True, color="1F4E78")
+LBL_FONT  = Font(name="Calibri", size=11)
+TTL_FONT  = Font(name="Calibri", size=16, bold=True, color="1F4E78")
+DAT_FONT  = Font(name="Calibri", size=11)
+GRN_FILL  = PatternFill("solid", fgColor="C6EFCE")
+RED_FILL  = PatternFill("solid", fgColor="FFC7CE")
+YLW_FILL  = PatternFill("solid", fgColor="FFEB9C")
+
+THIN = Border(
+    left=Side(style="thin", color="BFBFBF"), right=Side(style="thin", color="BFBFBF"),
+    top=Side(style="thin",  color="BFBFBF"), bottom=Side(style="thin", color="BFBFBF"),
+)
+CENTER = Alignment(horizontal="center", vertical="center", wrap_text=True)
+LEFT   = Alignment(horizontal="left",   vertical="center", wrap_text=True)
+RIGHT  = Alignment(horizontal="right",  vertical="center")
+
+FMT_MONEY = '#,##0;(#,##0);"—"'
+FMT_DEC   = '#,##0.00;(#,##0.00);"—"'
+FMT_PCT   = '0.0%;(0.0%);"—"'
+FMT_RATIO = '0.00;(0.00);"—"'
+FMT_DAYS  = '0.0;"—"'
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _safe(arr, i, default=None):
+    try: return arr[i] if arr and arr[i] is not None else default
+    except: return default
+
+def _hdr(ws, row, cols, start=1):
+    for i, h in enumerate(cols):
+        c = ws.cell(row=row, column=start+i, value=h)
+        c.font, c.fill, c.alignment, c.border = HDR_FONT, HDR_FILL, CENTER, THIN
+
+def _sec(ws, row, label, ncols, start=1):
+    ws.cell(row=row, column=start, value=label).font = SEC_FONT
+    ws.cell(row=row, column=start).fill = SEC_FILL
+    ws.cell(row=row, column=start).alignment = LEFT
+    for col in range(start+1, start+ncols):
+        ws.cell(row=row, column=col).fill = SEC_FILL
+
+def _data_row(ws, row, label, values, fmt=FMT_MONEY, start=1):
+    c = ws.cell(row=row, column=start, value=label)
+    c.font, c.alignment, c.border = LBL_FONT, LEFT, THIN
+    for i, v in enumerate(values):
+        cell = ws.cell(row=row, column=start+1+i, value=v if v is not None else "—")
+        cell.font, cell.alignment, cell.border = DAT_FONT, RIGHT, THIN
+        if v is not None and isinstance(v, (int, float)):
+            cell.number_format = fmt
+
+def _title(ws, title, subtitle=None):
+    ws.cell(row=1, column=1, value=title).font = TTL_FONT
+    if subtitle:
+        ws.cell(row=2, column=1, value=subtitle).font = Font(name="Calibri", size=11, italic=True, color="595959")
+
+def _widths(ws, widths):
+    for i, w in enumerate(widths):
+        ws.column_dimensions[get_column_letter(i+1)].width = w
+
+def _freeze(ws, hdr_row):
+    ws.freeze_panes = ws.cell(row=hdr_row+1, column=2)
+
+def _last(arr):
+    if not arr: return None
+    for v in reversed(arr):
+        if v is not None: return v
+    return None
+
+# ── Statement section helper ──────────────────────────────────────────────────
+
+def _stmt_section(ws, row, title, items, data_dict, years, fmt=FMT_MONEY):
+    _sec(ws, row, title, 1+len(years))
+    row += 1
+    for label, key in items:
+        vals = data_dict.get(key, [None]*len(years))
+        vals = (vals + [None]*len(years))[:len(years)]
+        _data_row(ws, row, label, vals, fmt)
+        row += 1
+    return row
+
+# ── Sheet builders ────────────────────────────────────────────────────────────
+
+def _summary_sheet(wb, data):
+    ws = wb.create_sheet("Summary")
+    co = data.get("company", {})
+    units_label = data.get("units_label", data.get("units", "Crores"))
+    currency    = data.get("currency", co.get("currency", "INR"))
+    _title(ws, f"{co.get('name','')} ({co.get('ticker','')}) — Financial Analysis",
+           f"Report date: {co.get('report_date', datetime.date.today().isoformat())}")
+    r = 4
+    for label, val in [
+        ("Company",         co.get("name","")),
+        ("Ticker",          co.get("ticker","")),
+        ("Exchange",        co.get("exchange","")),
+        ("Industry",        co.get("industry","")),
+        ("Sector",          co.get("sector","")),
+        ("Currency",        currency),
+        ("Reporting Units", units_label),
+        ("Fiscal Year End", co.get("fiscal_year_end","")),
+        ("Analysis Period", f"{len(data.get('years',[]))} years ({', '.join(data.get('years',[]))})"),
+        ("Share Price",     co.get("share_price")),
+        ("Market Cap",      co.get("market_cap")),
+        ("Data Source",     data.get("source", "Yahoo Finance (yfinance)")),
+        ("Models Used",     ", ".join(data.get("models_used", []) or ["None"])),
+        ("Warnings",        " | ".join(data.get("warnings", []))),
+    ]:
+        ws.cell(row=r, column=1, value=label).font = LBL_FONT
+        ws.cell(row=r, column=2, value=val).font   = DAT_FONT
+        r += 1
+    _widths(ws, [28, 50])
+
+
+def _income_sheet(wb, data):
+    ws = wb.create_sheet("Income Statement")
+    co, years = data.get("company",{}), data.get("years",[])
+    units_label = data.get("units_label", data.get("units", "Crores"))
+    currency    = data.get("currency", co.get("currency", "INR"))
+    _title(ws, f"Income Statement — {co.get('ticker','')}",
+           f"All figures in {units_label}")
+    _hdr(ws, 4, [f"({units_label})"] + years)
+    inc = data.get("income_statement", {})
+    r = _stmt_section(ws, 5, "Revenue & Profitability", [
+        ("Revenue",              "revenue"),
+        ("Cost of Revenue",      "cost_of_revenue"),
+        ("Gross Profit",         "gross_profit"),
+        ("Operating Expenses",   "operating_expenses"),
+        ("Operating Income (EBIT)","operating_income"),
+        ("D&A",                  "depreciation_amort"),
+        ("EBITDA",               "ebitda"),
+        ("Interest Expense",     "interest_expense"),
+        ("Pretax Income",        "pretax_income"),
+        ("Tax Expense",          "tax_expense"),
+        ("Net Income",           "net_income"),
+    ], inc, years)
+    r += 1
+    _sec(ws, r, "Per-Share Data", 1+len(years)); r += 1
+    _data_row(ws, r, "Diluted EPS",    inc.get("diluted_eps",[None]*len(years))[:len(years)], FMT_DEC); r += 1
+    _data_row(ws, r, "Diluted Shares (M)", inc.get("diluted_shares",[None]*len(years))[:len(years)], FMT_MONEY)
+
+    # Add revenue bar chart
+    if len(years) >= 2:
+        chart = BarChart()
+        chart.title = f"Revenue Trend ({units_label})"
+        chart.style = 10
+        chart.y_axis.title = units_label
+        rev_row = 6
+        data_ref = Reference(ws, min_col=2, max_col=1+len(years), min_row=rev_row, max_row=rev_row)
+        cats_ref = Reference(ws, min_col=2, max_col=1+len(years), min_row=4, max_row=4)
+        chart.add_data(data_ref)
+        chart.set_categories(cats_ref)
+        chart.shape = 4
+        ws.add_chart(chart, f"A{r+3}")
+
+    _widths(ws, [34]+[16]*len(years)); _freeze(ws, 4)
+
+
+def _balance_sheet(wb, data):
+    ws = wb.create_sheet("Balance Sheet")
+    co, years = data.get("company",{}), data.get("years",[])
+    units_label = data.get("units_label", data.get("units", "Crores"))
+    _title(ws, f"Balance Sheet — {co.get('ticker','')}",
+           f"As of fiscal year-end. {units_label}")
+    _hdr(ws, 4, [f"({units_label})"] + years)
+    bs = data.get("balance_sheet", {})
+    r = 5
+    for sec_title, items in [
+        ("Current Assets", [
+            ("Cash & Equivalents","cash_and_equivalents"),("Short-term Investments","short_term_investments"),
+            ("Receivables","receivables"),("Inventory","inventory"),("Other Current Assets","other_current_assets"),
+            ("Total Current Assets","total_current_assets"),
+        ]),
+        ("Non-Current Assets", [
+            ("PP&E (Net)","ppe_net"),("Goodwill","goodwill"),("Intangibles","intangibles"),
+            ("Other LT Assets","other_long_term_assets"),("Total Assets","total_assets"),
+        ]),
+        ("Current Liabilities", [
+            ("Accounts Payable","accounts_payable"),("Short-term Debt","short_term_debt"),
+            ("Other Current Liabilities","other_current_liabilities"),
+            ("Total Current Liabilities","total_current_liabilities"),
+        ]),
+        ("Non-Current Liabilities & Equity", [
+            ("Long-term Debt","long_term_debt"),("Other LT Liabilities","other_long_term_liabilities"),
+            ("Total Liabilities","total_liabilities"),("Total Equity","total_equity"),
+            ("Total Liabilities + Equity","total_liab_and_equity"),
+        ]),
+    ]:
+        r = _stmt_section(ws, r, sec_title, items, bs, years)
+    _widths(ws, [36]+[16]*len(years)); _freeze(ws, 4)
+
+
+def _cashflow_sheet(wb, data):
+    ws = wb.create_sheet("Cash Flow")
+    co, years = data.get("company",{}), data.get("years",[])
+    units_label = data.get("units_label", data.get("units", "Crores"))
+    _title(ws, f"Cash Flow Statement — {co.get('ticker','')}",
+           f"All figures in {units_label}")
+    _hdr(ws, 4, [f"({units_label})"] + years)
+    cf = data.get("cash_flow", {})
+    r = 5
+    for sec_title, items in [
+        ("Operating Activities", [
+            ("Net Income","net_income"),("D&A","depreciation_amort"),("Stock-Based Comp","stock_based_comp"),
+            ("Working Capital Changes","working_capital_changes"),("Cash from Operations","cash_from_operations"),
+        ]),
+        ("Investing Activities", [
+            ("Capital Expenditures","capex"),("Acquisitions","acquisitions"),("Cash from Investing","cash_from_investing"),
+        ]),
+        ("Financing Activities", [
+            ("Debt Issuance/(Repayment)","debt_issuance_repayment"),("Buybacks","stock_buybacks"),
+            ("Dividends Paid","dividends_paid"),("Cash from Financing","cash_from_financing"),
+        ]),
+        ("Summary", [
+            ("Net Change in Cash","net_change_in_cash"),("Free Cash Flow","free_cash_flow"),
+        ]),
+    ]:
+        r = _stmt_section(ws, r, sec_title, items, cf, years)
+    _widths(ws, [36]+[16]*len(years)); _freeze(ws, 4)
+
+
+RATIO_SECTIONS = [
+    ("Profitability", [
+        ("gross_margin","Gross Margin",FMT_PCT),("operating_margin","Operating Margin",FMT_PCT),
+        ("ebitda_margin","EBITDA Margin",FMT_PCT),("net_margin","Net Margin",FMT_PCT),
+        ("roe","ROE",FMT_PCT),("roa","ROA",FMT_PCT),("roic","ROIC",FMT_PCT),
+    ]),
+    ("Liquidity", [
+        ("current_ratio","Current Ratio",FMT_RATIO),("quick_ratio","Quick Ratio",FMT_RATIO),
+        ("cash_ratio","Cash Ratio",FMT_RATIO),
+    ]),
+    ("Solvency / Leverage", [
+        ("debt_to_equity","Debt-to-Equity",FMT_RATIO),("debt_to_assets","Debt-to-Assets",FMT_RATIO),
+        ("net_debt_to_ebitda","Net Debt/EBITDA",FMT_RATIO),("interest_coverage","Interest Coverage",FMT_RATIO),
+    ]),
+    ("Efficiency", [
+        ("asset_turnover","Asset Turnover",FMT_RATIO),("inventory_turnover","Inventory Turnover",FMT_RATIO),
+        ("days_inventory","Days Inventory (DIO)",FMT_DAYS),("days_sales_outstanding","DSO",FMT_DAYS),
+        ("days_payables","DPO",FMT_DAYS),("cash_conversion_cycle","Cash Conversion Cycle",FMT_DAYS),
+    ]),
+    ("Cash Flow Quality", [
+        ("ocf_to_net_income","OCF/Net Income",FMT_RATIO),("fcf_margin","FCF Margin",FMT_PCT),
+        ("fcf_conversion","FCF Conversion",FMT_RATIO),("capex_intensity","Capex/Revenue",FMT_PCT),
+    ]),
+]
+
+
+def _ratios_sheet(wb, data):
+    ws = wb.create_sheet("Ratios")
+    years = data.get("years", [])
+    _title(ws, f"Financial Ratios — {data.get('company',{}).get('ticker','')}", "5-year trend")
+    _hdr(ws, 4, ["Ratio"] + years)
+    ratios = data.get("ratios", {})
+    r = 5
+    for sec_name, items in RATIO_SECTIONS:
+        _sec(ws, r, sec_name, 1+len(years)); r += 1
+        for key, label, fmt in items:
+            vals = ratios.get(key, [None]*len(years))
+            vals = (vals + [None]*len(years))[:len(years)]
+            _data_row(ws, r, label, vals, fmt); r += 1
+    _widths(ws, [40]+[14]*len(years)); _freeze(ws, 4)
+
+
+def _dupont_sheet(wb, data):
+    ws = wb.create_sheet("DuPont Analysis")
+    years = data.get("years", [])
+    _title(ws, "DuPont Decomposition", "ROE = Net Margin × Asset Turnover × Equity Multiplier")
+    _hdr(ws, 4, ["Component"] + years)
+    dp = data.get("dupont", {})
+    r = 5
+    for label, key, fmt in [
+        ("Net Margin",       "net_margin",        FMT_PCT),
+        ("× Asset Turnover", "asset_turnover",     FMT_RATIO),
+        ("× Equity Multiplier","equity_multiplier",FMT_RATIO),
+        ("= ROE (DuPont)",   "roe_computed",       FMT_PCT),
+        ("ROE (Reported)",   "roe_reported",       FMT_PCT),
+    ]:
+        vals = dp.get(key, [None]*len(years))
+        vals = (vals + [None]*len(years))[:len(years)]
+        _data_row(ws, r, label, vals, fmt)
+        r += 1
+    _widths(ws, [28]+[14]*len(years))
+
+
+def _growth_sheet(wb, data):
+    ws = wb.create_sheet("Growth Metrics")
+    years = data.get("years", [])
+    yoy_hdrs = [f"{years[i]} vs {years[i-1]}" for i in range(1, len(years))] if len(years) > 1 else []
+    _title(ws, "Growth Metrics", "YoY growth and CAGRs")
+    _hdr(ws, 4, ["Metric"] + yoy_hdrs + ["CAGR"])
+    g = data.get("growth_metrics", {})
+    r = 5
+    for label, yoy_key, cagr_key in [
+        ("Revenue",        "revenue_yoy",        "revenue_cagr_5y"),
+        ("Operating Income","operating_income_yoy","operating_income_cagr_5y"),
+        ("Net Income",     "net_income_yoy",      "net_income_cagr_5y"),
+        ("Diluted EPS",    "eps_yoy",             "eps_cagr_5y"),
+        ("Free Cash Flow", "fcf_yoy",             "fcf_cagr_5y"),
+    ]:
+        yoy = g.get(yoy_key, [])[1:]  # skip first None
+        cagr = g.get(cagr_key)
+        vals = (yoy + [None]*len(yoy_hdrs))[:len(yoy_hdrs)] + [cagr]
+        _data_row(ws, r, label, vals, FMT_PCT); r += 1
+    _widths(ws, [28]+[16]*(len(yoy_hdrs)+1))
+
+
+def _peers_sheet(wb, data):
+    ws = wb.create_sheet("Peer Comparison")
+    co = data.get("company", {})
+    _title(ws, f"Peer Comparison — {co.get('ticker','')}", "Latest fiscal year")
+    cols = ["Company","Ticker","Revenue","Gross Margin","Op Margin","Net Margin",
+            "ROE","ROIC","D/E","Current Ratio","FCF Margin","P/E","EV/EBITDA","Rationale"]
+    _hdr(ws, 4, cols)
+    r = 5
+    years = data.get("years", [])
+    rat = data.get("ratios", {}); inc = data.get("income_statement", {})
+    val = data.get("valuation_snapshot", {})
+    # Target row
+    target = [
+        co.get("name",""), co.get("ticker",""),
+        _last(inc.get("revenue",[])), _last(rat.get("gross_margin",[])),
+        _last(rat.get("operating_margin",[])), _last(rat.get("net_margin",[])),
+        _last(rat.get("roe",[])), _last(rat.get("roic",[])),
+        _last(rat.get("debt_to_equity",[])), _last(rat.get("current_ratio",[])),
+        _last(rat.get("fcf_margin",[])), val.get("pe_ttm"), val.get("ev_ebitda"),
+        "Target company",
+    ]
+    fmts = ["","","money","pct","pct","pct","pct","pct","ratio","ratio","pct","ratio","ratio",""]
+    _write_peer_row(ws, r, target, fmts, is_target=True); r += 1
+    for p in data.get("peers", []):
+        peer_row = [
+            p.get("name",""), p.get("ticker",""), p.get("revenue"),
+            p.get("gross_margin"), p.get("operating_margin"), p.get("net_margin"),
+            p.get("roe"), p.get("roic"), p.get("debt_to_equity"), p.get("current_ratio"),
+            p.get("fcf_margin"), p.get("pe_ttm"), p.get("ev_ebitda"), p.get("rationale",""),
+        ]
+        _write_peer_row(ws, r, peer_row, fmts); r += 1
+    _widths(ws, [24,10,16,12,12,12,10,10,10,12,12,10,12,50])
+
+
+def _write_peer_row(ws, row, values, fmts, is_target=False):
+    fmt_map = {"money":FMT_MONEY,"pct":FMT_PCT,"ratio":FMT_RATIO}
+    fill = PatternFill("solid", fgColor="FFF2CC") if is_target else None
+    for i, v in enumerate(values):
+        c = ws.cell(row=row, column=i+1, value=v if v is not None else "—")
+        c.border = THIN
+        c.font = Font(name="Calibri", size=11, bold=is_target)
+        if fill: c.fill = fill
+        fmt = fmts[i] if i < len(fmts) else ""
+        if fmt in fmt_map and isinstance(v, (int, float)):
+            c.number_format = fmt_map[fmt]
+            c.alignment = RIGHT
+        else:
+            c.alignment = LEFT
+
+
+def _swot_sheet(wb, data):
+    ws = wb.create_sheet("SWOT Analysis")
+    _title(ws, "SWOT Analysis", "Strengths, Weaknesses, Opportunities, Threats")
+    swot = data.get("swot", {})
+    r = 4
+    colors = {"Strengths":"C6EFCE","Weaknesses":"FFC7CE","Opportunities":"DDEBF7","Threats":"FFEB9C"}
+    for category, key in [("Strengths","strengths"),("Weaknesses","weaknesses"),
+                           ("Opportunities","opportunities"),("Threats","threats")]:
+        fill = PatternFill("solid", fgColor=colors[category])
+        hdr_cell = ws.cell(row=r, column=1, value=category)
+        hdr_cell.font = Font(name="Calibri", size=12, bold=True)
+        hdr_cell.fill = fill
+        r += 1
+        for item in swot.get(key, []):
+            c = ws.cell(row=r, column=1, value=f"• {item}")
+            c.font = Font(name="Calibri", size=11)
+            c.alignment = Alignment(horizontal="left", vertical="top", wrap_text=True)
+            ws.row_dimensions[r].height = 32
+            r += 1
+        r += 1
+    _widths(ws, [90])
+
+
+def _sources_sheet(wb, data):
+    ws = wb.create_sheet("Sources")
+    _title(ws, "Sources", "All data sources and retrieval dates")
+    _hdr(ws, 4, ["#","URL","Description","Retrieved"])
+    r = 5
+    for i, src in enumerate(data.get("sources",[]), start=1):
+        ws.cell(row=r, column=1, value=i).alignment = CENTER
+        url = src.get("url","")
+        uc = ws.cell(row=r, column=2, value=url)
+        uc.font = Font(name="Calibri", size=10, color="0563C1", underline="single")
+        uc.alignment = LEFT
+        if url:
+            try: uc.hyperlink = url
+            except: pass
+        ws.cell(row=r, column=3, value=src.get("description","")).alignment = LEFT
+        ws.cell(row=r, column=4, value=src.get("retrieved","")).alignment = CENTER
+        for col in range(1,5): ws.cell(row=r,column=col).border = THIN
+        ws.row_dimensions[r].height = 28; r += 1
+    _widths(ws, [6,70,50,16])
+
+
+# ── Orchestrator ──────────────────────────────────────────────────────────────
+
+def build_workbook(data: dict, output_path: str) -> None:
+    wb = Workbook()
+    wb.remove(wb.active)
+    _summary_sheet(wb, data)
+    _income_sheet(wb, data)
+    _balance_sheet(wb, data)
+    _cashflow_sheet(wb, data)
+    _ratios_sheet(wb, data)
+    _dupont_sheet(wb, data)
+    _growth_sheet(wb, data)
+    _peers_sheet(wb, data)
+    _swot_sheet(wb, data)
+    _sources_sheet(wb, data)
+    wb.save(output_path)
+
+
+if __name__ == "__main__":
+    import argparse
+    p = argparse.ArgumentParser()
+    p.add_argument("--input", "-i", required=True)
+    p.add_argument("--output", "-o", required=True)
+    args = p.parse_args()
+    with open(args.input, encoding="utf-8") as f:
+        data = json.load(f)
+    Path(args.output).parent.mkdir(parents=True, exist_ok=True)
+    build_workbook(data, args.output)
+    print(f"Wrote: {args.output}")

builders/build_pptx.py

@@ -0,0 +1,423 @@
+"""
+builders/build_pptx.py — PowerPoint presentation builder.
+
+Generates a widescreen (16:9) PPTX presentation summarizing the financial analysis
+and AI narrative, strictly matching user-defined theme, colors, and layout structure.
+"""
+import os
+import sys
+import datetime
+from pathlib import Path
+from typing import Dict, List
+
+# import python-pptx classes
+from pptx import Presentation
+from pptx.util import Inches, Pt
+from pptx.dml.color import RGBColor
+from pptx.enum.text import PP_ALIGN
+from pptx.enum.shapes import MSO_SHAPE
+from pptx.enum.shapes import MSO_CONNECTOR
+
+# Color Palette defined in User Rules
+COLOR_DARK_TEXT = RGBColor(0, 0, 0)         # 000000 (Black)
+COLOR_LIGHT_BG = RGBColor(255, 255, 255)     # FFFFFF (White)
+COLOR_DARK_GREEN = RGBColor(0, 132, 0)      # 008400 (Green Bar 1)
+COLOR_LIGHT_GREEN = RGBColor(149, 203, 137)  # 95CB89 (Green Bar 2)
+COLOR_GRAY_LINE = RGBColor(0, 0, 0)         # 000000 (Black bottom line)
+COLOR_DARK_SLATE = RGBColor(69, 95, 81)     # 455F51 (Dark slate green)
+COLOR_LIGHT_GRAY = RGBColor(227, 222, 209)  # E3DED1 (Light warm gray/beige)
+COLOR_ACCENT = RGBColor(84, 158, 57)        # 549E39 (Accent green)
+
+FONT_MAJOR = "Helvetica Neue Bold"
+FONT_MINOR = "Helvetica Neue Light"
+FONT_MAJOR_FALLBACK = "Arial"
+FONT_MINOR_FALLBACK = "Arial"
+
+def _apply_theme_decorations(slide, prs):
+    """
+    Applies the layout rectangles and bottom line strictly defined in the
+    Slide Master Layout.
+    """
+    # 1. Decorative top-left dark green bar
+    # rect: x: 0.15, y: 0.0, w: 0.36, h: 1.16
+    rect1 = slide.shapes.add_shape(
+        MSO_SHAPE.RECTANGLE, 
+        Inches(0.15), Inches(0.0), Inches(0.36), Inches(1.16)
+    )
+    rect1.fill.solid()
+    rect1.fill.fore_color.rgb = COLOR_DARK_GREEN
+    rect1.line.fill.background()  # No border line
+
+    # 2. Decorative top-left light green bar
+    # rect: x: 0.55, y: 0.0, w: 0.11, h: 1.39
+    rect2 = slide.shapes.add_shape(
+        MSO_SHAPE.RECTANGLE, 
+        Inches(0.55), Inches(0.0), Inches(0.11), Inches(1.39)
+    )
+    rect2.fill.solid()
+    rect2.fill.fore_color.rgb = COLOR_LIGHT_GREEN
+    rect2.line.fill.background()  # No border line
+
+    # 3. Decorative bottom line
+    # line: x: 0.67, y: 6.83, w: 12.0, h: 0.0
+    connector = slide.shapes.add_connector(
+        MSO_CONNECTOR.STRAIGHT,
+        Inches(0.67), Inches(6.83), Inches(12.67), Inches(6.83)
+    )
+    connector.line.color.rgb = COLOR_GRAY_LINE
+    connector.line.width = Pt(1)
+
+def _add_slide_title(slide, text: str):
+    """
+    Adds the Slide Title using Layout 7 Title configurations:
+    placeholder: x: 0.81, y: 0.29, w: 11.74, h: 0.38, align: left, valign: top
+    """
+    tx_box = slide.shapes.add_textbox(
+        Inches(0.81), Inches(0.29), Inches(11.74), Inches(0.38)
+    )
+    tf = tx_box.text_frame
+    tf.word_wrap = True
+    tf.margin_top = 0
+    tf.margin_bottom = 0
+    tf.margin_left = 0
+    tf.margin_right = 0
+    
+    p = tf.paragraphs[0]
+    p.text = text
+    p.font.name = FONT_MAJOR
+    p.font.size = Pt(20)
+    p.font.bold = True
+    p.font.color.rgb = COLOR_DARK_TEXT
+    p.alignment = PP_ALIGN.LEFT
+
+def _add_bullet_points(slide, bullets: List[str], top_inch=1.56, height_inch=5.14):
+    """
+    Adds bullet points body text block using Master 2 Body:
+    placeholder: x: 0.67, y: top, w: 12.0, h: height
+    """
+    tx_box = slide.shapes.add_textbox(
+        Inches(0.67), Inches(top_inch), Inches(12.0), Inches(height_inch)
+    )
+    tf = tx_box.text_frame
+    tf.word_wrap = True
+    tf.margin_top = 0
+    tf.margin_bottom = 0
+    tf.margin_left = 0
+    tf.margin_right = 0
+    
+    for i, b in enumerate(bullets):
+        p = tf.add_paragraph() if i > 0 else tf.paragraphs[0]
+        p.text = "•  " + b
+        p.font.name = FONT_MINOR
+        p.font.size = Pt(15)
+        p.font.color.rgb = COLOR_DARK_TEXT
+        p.space_after = Pt(8)
+        p.line_spacing = 1.2
+
+def _style_table_cell(cell, text: str, font_name=FONT_MINOR, font_size=11, bold=False, text_color=COLOR_DARK_TEXT, bg_color=None, align=PP_ALIGN.CENTER):
+    """Styles cell texts and background fills."""
+    cell.text = text
+    p = cell.text_frame.paragraphs[0]
+    p.alignment = align
+    p.font.name = font_name
+    p.font.size = Pt(font_size)
+    p.font.bold = bold
+    p.font.color.rgb = text_color
+    
+    if bg_color:
+        cell.fill.solid()
+        cell.fill.fore_color.rgb = bg_color
+
+def build_presentation(data: Dict, output_path: str):
+    """
+    Assembles a widescreen PowerPoint report from scraped financial data and AI models output.
+    """
+    prs = Presentation()
+    
+    # Strictly configure widescreen 16:9 aspect ratio
+    prs.slide_width = Inches(13.333)
+    prs.slide_height = Inches(7.5)
+    
+    blank_layout = prs.slide_layouts[6] # Blank slide template
+    
+    company_name = data.get("company", {}).get("name", "Unknown Company")
+    ticker = data.get("company", {}).get("ticker", "N/A")
+    industry = data.get("company", {}).get("industry", "N/A")
+    sector = data.get("company", {}).get("sector", "N/A")
+    date_str = data.get("company", {}).get("report_date", datetime.date.today().isoformat())
+    years = data.get("years", [])
+    
+    # ==========================================
+    # SLIDE 1: Title Slide
+    # ==========================================
+    slide_title = prs.slides.add_slide(blank_layout)
+    _apply_theme_decorations(slide_title, prs)
+    
+    # Title Text Frame
+    title_box = slide_title.shapes.add_textbox(
+        Inches(1.0), Inches(2.2), Inches(11.3), Inches(2.0)
+    )
+    tf = title_box.text_frame
+    tf.word_wrap = True
+    p1 = tf.paragraphs[0]
+    p1.text = company_name
+    p1.font.name = FONT_MAJOR
+    p1.font.size = Pt(40)
+    p1.font.bold = True
+    p1.font.color.rgb = COLOR_DARK_TEXT
+    
+    p2 = tf.add_paragraph()
+    p2.text = f"Financial Analysis & Investment Insights ({ticker})"
+    p2.font.name = FONT_MINOR
+    p2.font.size = Pt(22)
+    p2.font.color.rgb = COLOR_DARK_SLATE
+    p2.space_before = Pt(8)
+
+    # Subtitle Info (Date / Authors)
+    sub_box = slide_title.shapes.add_textbox(
+        Inches(1.0), Inches(5.0), Inches(11.3), Inches(1.2)
+    )
+    tf_sub = sub_box.text_frame
+    p_sub = tf_sub.paragraphs[0]
+    p_sub.text = f"Report Date: {date_str}  |  Sector: {sector}  |  Industry: {industry}"
+    p_sub.font.name = FONT_MINOR
+    p_sub.font.size = Pt(13)
+    p_sub.font.color.rgb = COLOR_DARK_SLATE
+    
+    p_sub2 = tf_sub.add_paragraph()
+    p_sub2.text = "Disclaimer: This report is for informational purposes only and does not constitute investment advice."
+    p_sub2.font.name = FONT_MINOR
+    p_sub2.font.size = Pt(11)
+    p_sub2.font.color.rgb = COLOR_DARK_SLATE
+    p_sub2.space_before = Pt(6)
+
+    # ==========================================
+    # SLIDE 2: Executive Summary
+    # ==========================================
+    exec_summary_text = data.get("executive_summary", "")
+    if exec_summary_text and len(exec_summary_text) > 50:
+        slide_exec = prs.slides.add_slide(blank_layout)
+        _apply_theme_decorations(slide_exec, prs)
+        _add_slide_title(slide_exec, "Executive Summary")
+        
+        # Clean up text and divide into bullet blocks
+        paragraphs = [p.strip() for p in exec_summary_text.split('\n') if p.strip()]
+        _add_bullet_points(slide_exec, paragraphs[:5])
+
+    # ==========================================
+    # SLIDE 3: Key Financial Highlights Table
+    # ==========================================
+    if years:
+        slide_metrics = prs.slides.add_slide(blank_layout)
+        _apply_theme_decorations(slide_metrics, prs)
+        _add_slide_title(slide_metrics, "Key Financial Performance")
+        
+        # Build Grid Table
+        cols = len(years) + 1
+        rows = 6
+        table_shape = slide_metrics.shapes.add_table(
+            rows, cols, Inches(0.8), Inches(1.6), Inches(11.7), Inches(3.8)
+        )
+        table = table_shape.table
+        
+        # Column Headers
+        _style_table_cell(table.cell(0, 0), "Financial Metric", FONT_MAJOR, 12, True, COLOR_LIGHT_BG, COLOR_DARK_SLATE, PP_ALIGN.LEFT)
+        for idx, y in enumerate(years):
+            _style_table_cell(table.cell(0, idx+1), str(y), FONT_MAJOR, 12, True, COLOR_LIGHT_BG, COLOR_DARK_SLATE)
+            
+        metrics = [
+            ("Revenue", "income_statement", 1.0),
+            ("Gross Profit", "income_statement", 1.0),
+            ("Operating Income (EBIT)", "income_statement", 1.0),
+            ("Net Income", "income_statement", 1.0),
+            ("Operating Cash Flow (OCF)", "cash_flow", 1.0)
+        ]
+        
+        currency = data.get("company", {}).get("currency", "USD")
+        units = data.get("company", {}).get("units", "millions")
+        
+        for r_idx, (m_label, sheet_name, scale) in enumerate(metrics):
+            curr_row = r_idx + 1
+            bg_color = COLOR_LIGHT_GRAY if curr_row % 2 == 1 else COLOR_LIGHT_BG
+            
+            # Label cell
+            _style_table_cell(table.cell(curr_row, 0), f"{m_label} ({currency} {units.capitalize()})", FONT_MAJOR, 11, False, COLOR_DARK_TEXT, bg_color, PP_ALIGN.LEFT)
+            
+            # Values cells
+            sheet_data = data.get(sheet_name, {})
+            val_list = sheet_data.get(m_label, [])
+            for c_idx, y in enumerate(years):
+                val_str = "N/A"
+                if c_idx < len(val_list) and val_list[c_idx] is not None:
+                    val_str = f"{val_list[c_idx]:,.1f}"
+                _style_table_cell(table.cell(curr_row, c_idx+1), val_str, FONT_MINOR, 11, False, COLOR_DARK_TEXT, bg_color)
+                
+        # Brief Narrative summary underneath table
+        rev_commentary = data.get("trend_analysis", {}).get("revenue_and_profitability", "")
+        if rev_commentary:
+            comment_box = slide_metrics.shapes.add_textbox(Inches(0.8), Inches(5.6), Inches(11.7), Inches(1.1))
+            tf_c = comment_box.text_frame
+            tf_c.word_wrap = True
+            p_c = tf_c.paragraphs[0]
+            p_c.text = "Key Takeaway: " + (rev_commentary[:260] + "..." if len(rev_commentary) > 260 else rev_commentary)
+            p_c.font.name = FONT_MINOR
+            p_c.font.size = Pt(12)
+            p_c.font.italic = True
+            p_c.font.color.rgb = COLOR_DARK_SLATE
+
+    # ==========================================
+    # SLIDE 4: Dupont ROE Decomposition
+    # ==========================================
+    dp_data = data.get("dupont", {})
+    if dp_data and "years" in dp_data:
+        slide_dp = prs.slides.add_slide(blank_layout)
+        _apply_theme_decorations(slide_dp, prs)
+        _add_slide_title(slide_dp, "DuPont ROE Analysis (Latest 3 Years)")
+        
+        dp_years = dp_data.get("years", [])
+        cols = len(dp_years) + 1
+        rows = 5
+        table_shape = slide_dp.shapes.add_table(
+            rows, cols, Inches(0.8), Inches(1.6), Inches(11.7), Inches(3.2)
+        )
+        table = table_shape.table
+        
+        # Headers
+        _style_table_cell(table.cell(0, 0), "DuPont Component", FONT_MAJOR, 12, True, COLOR_LIGHT_BG, COLOR_DARK_SLATE, PP_ALIGN.LEFT)
+        for idx, y in enumerate(dp_years):
+            _style_table_cell(table.cell(0, idx+1), str(y), FONT_MAJOR, 12, True, COLOR_LIGHT_BG, COLOR_DARK_SLATE)
+            
+        components = [
+            ("Net Profit Margin (%)", "Net Margin"),
+            ("Asset Turnover (x)", "Asset Turnover"),
+            ("Equity Multiplier (x)", "Equity Multiplier"),
+            ("Return on Equity (ROE %)", "ROE")
+        ]
+        
+        for r_idx, (c_label, key) in enumerate(components):
+            curr_row = r_idx + 1
+            bg_color = COLOR_LIGHT_GRAY if curr_row % 2 == 1 else COLOR_LIGHT_BG
+            is_bold = (curr_row == 4)  # Bold ROE row
+            
+            _style_table_cell(table.cell(curr_row, 0), c_label, FONT_MAJOR if is_bold else FONT_MINOR, 11, is_bold, COLOR_DARK_TEXT, bg_color, PP_ALIGN.LEFT)
+            
+            vals_list = dp_data.get(key, [])
+            for c_idx, y in enumerate(dp_years):
+                val_str = "N/A"
+                if c_idx < len(vals_list) and vals_list[c_idx] is not None:
+                    val_val = vals_list[c_idx]
+                    if "%" in c_label or "ROE" in key:
+                        val_str = f"{val_val * 100:.1f}%" if val_val < 1.0 else f"{val_val:.1f}%"
+                    else:
+                        val_str = f"{val_val:.2f}x"
+                _style_table_cell(table.cell(curr_row, c_idx+1), val_str, FONT_MAJOR if is_bold else FONT_MINOR, 11, is_bold, COLOR_DARK_TEXT, bg_color)
+                
+        # DuPont Commentary Text Box
+        commentary = data.get("trend_analysis", {}).get("balance_sheet_strength", "")
+        if commentary:
+            comment_box = slide_dp.shapes.add_textbox(Inches(0.8), Inches(5.0), Inches(11.7), Inches(1.6))
+            tf_c = comment_box.text_frame
+            tf_c.word_wrap = True
+            p_c = tf_c.paragraphs[0]
+            p_c.text = "DuPont Drivers & Balance Sheet Strength: " + (commentary[:380] + "..." if len(commentary) > 380 else commentary)
+            p_c.font.name = FONT_MINOR
+            p_c.font.size = Pt(12)
+            p_c.font.color.rgb = COLOR_DARK_TEXT
+            p_c.line_spacing = 1.2
+
+    # ==========================================
+    # SLIDE 5: Competitor Benchmarking
+    # ==========================================
+    peers_list = data.get("peers", [])
+    if peers_list:
+        slide_peers = prs.slides.add_slide(blank_layout)
+        _apply_theme_decorations(slide_peers, prs)
+        _add_slide_title(slide_peers, "Competitor Benchmarking")
+        
+        # Build Grid Table
+        cols = 5
+        rows = min(len(peers_list) + 1, 6)
+        table_shape = slide_peers.shapes.add_table(
+            rows, cols, Inches(0.8), Inches(1.6), Inches(11.7), Inches(3.2)
+        )
+        table = table_shape.table
+        
+        # Headers
+        headers = ["Company", "Revenue Growth", "Operating Margin", "P/E Ratio", "ROE"]
+        for c_idx, h in enumerate(headers):
+            _style_table_cell(table.cell(0, c_idx), h, FONT_MAJOR, 12, True, COLOR_LIGHT_BG, COLOR_DARK_SLATE, PP_ALIGN.LEFT if c_idx == 0 else PP_ALIGN.CENTER)
+            
+        for r_idx in range(rows - 1):
+            peer = peers_list[r_idx]
+            curr_row = r_idx + 1
+            bg_color = COLOR_LIGHT_GRAY if curr_row % 2 == 1 else COLOR_LIGHT_BG
+            
+            # Format peer outputs
+            rev_gr = peer.get("revenue_growth", "N/A")
+            if isinstance(rev_gr, float): rev_gr = f"{rev_gr*100:.1f}%"
+            op_marg = peer.get("operating_margin", "N/A")
+            if isinstance(op_marg, float): op_marg = f"{op_marg*100:.1f}%"
+            pe_r = peer.get("pe_ratio", "N/A")
+            if isinstance(pe_r, float): pe_r = f"{pe_r:.1f}x"
+            roe_val = peer.get("roe", "N/A")
+            if isinstance(roe_val, float): roe_val = f"{roe_val*100:.1f}%"
+            
+            _style_table_cell(table.cell(curr_row, 0), peer.get("name", "N/A"), FONT_MAJOR, 11, False, COLOR_DARK_TEXT, bg_color, PP_ALIGN.LEFT)
+            _style_table_cell(table.cell(curr_row, 1), str(rev_gr), FONT_MINOR, 11, False, COLOR_DARK_TEXT, bg_color)
+            _style_table_cell(table.cell(curr_row, 2), str(op_marg), FONT_MINOR, 11, False, COLOR_DARK_TEXT, bg_color)
+            _style_table_cell(table.cell(curr_row, 3), str(pe_r), FONT_MINOR, 11, False, COLOR_DARK_TEXT, bg_color)
+            _style_table_cell(table.cell(curr_row, 4), str(roe_val), FONT_MINOR, 11, False, COLOR_DARK_TEXT, bg_color)
+            
+        # Peer comparison commentary
+        peer_comm = data.get("peer_comparison_commentary", "")
+        if peer_comm:
+            comment_box = slide_peers.shapes.add_textbox(Inches(0.8), Inches(5.0), Inches(11.7), Inches(1.6))
+            tf_c = comment_box.text_frame
+            tf_c.word_wrap = True
+            p_c = tf_c.paragraphs[0]
+            p_c.text = "Benchmarking Insights: " + (peer_comm[:380] + "..." if len(peer_comm) > 380 else peer_comm)
+            p_c.font.name = FONT_MINOR
+            p_c.font.size = Pt(12)
+            p_c.font.color.rgb = COLOR_DARK_TEXT
+            p_c.line_spacing = 1.2
+
+    # ==========================================
+    # SLIDE 6: Key Synthesis Insights
+    # ==========================================
+    insights_list = data.get("key_insights", [])
+    if insights_list:
+        slide_insights = prs.slides.add_slide(blank_layout)
+        _apply_theme_decorations(slide_insights, prs)
+        _add_slide_title(slide_insights, "Synthesized Key Insights")
+        
+        # Clean insights
+        clean_insights = []
+        for ins in insights_list:
+            if isinstance(ins, dict):
+                clean_insights.append(f"{ins.get('title', '')}: {ins.get('text', '')}")
+            else:
+                clean_insights.append(str(ins))
+                
+        _add_bullet_points(slide_insights, clean_insights[:4])
+
+    # ==========================================
+    # SLIDE 7: Risks & Red Flags
+    # ==========================================
+    risks_list = data.get("risks", [])
+    if risks_list:
+        slide_risks = prs.slides.add_slide(blank_layout)
+        _apply_theme_decorations(slide_risks, prs)
+        _add_slide_title(slide_risks, "Investment Risks & Key Red Flags")
+        
+        clean_risks = []
+        for r in risks_list:
+            if isinstance(r, dict):
+                clean_risks.append(f"{r.get('title', '')} ({r.get('impact', 'Medium Impact')}): {r.get('text', '')}")
+            else:
+                clean_risks.append(str(r))
+                
+        _add_bullet_points(slide_risks, clean_risks[:4])
+
+    # Save Presentation
+    os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_ok=True)
+    prs.save(output_path)

config.py

@@ -0,0 +1,41 @@
+"""
+config.py — App-wide constants and environment loading.
+"""
+import os
+from pathlib import Path
+from dotenv import load_dotenv
+
+# Load .env from the app root
+_ENV_PATH = Path(__file__).parent / ".env"
+load_dotenv(_ENV_PATH)
+
+# ── API Keys ──────────────────────────────────────────────────────────────────
+FMP_API_KEY: str    = os.environ.get("FMP_API_KEY", "")
+GEMINI_API_KEY: str = os.environ.get("GEMINI_API_KEY", "")
+CLAUDE_API_KEY: str = os.environ.get("CLAUDE_API_KEY", "")
+OPENAI_API_KEY: str = os.environ.get("OPENAI_API_KEY", "")
+GROQ_API_KEY: str   = os.environ.get("GROQ_API_KEY", "")
+
+# ── Data settings ─────────────────────────────────────────────────────────────
+DEFAULT_YEARS: int = 5
+CACHE_TTL_DAYS: int = 7           # days before cached data expires
+FMP_BASE: str = "https://financialmodelingprep.com/api"
+SCREENER_BASE: str = "https://screener.in/company"
+REQUEST_TIMEOUT: int = 20
+
+# ── Output ────────────────────────────────────────────────────────────────────
+OUTPUT_DIR: Path = Path(__file__).parent / "outputs"
+OUTPUT_DIR.mkdir(exist_ok=True)
+
+DB_PATH: Path = Path(__file__).parent / "storage" / "history.db"
+DB_PATH.parent.mkdir(exist_ok=True)
+
+# ── AI Models ─────────────────────────────────────────────────────────────────
+GEMINI_MODEL: str  = "gemini-2.0-flash"
+CLAUDE_MODEL: str  = "claude-3-5-haiku-20241022"
+OPENAI_MODEL: str  = "gpt-4o-mini"
+GROQ_MODEL: str    = "llama-3.3-70b-versatile"    # free, high-quality
+
+# ── App metadata ──────────────────────────────────────────────────────────────
+APP_NAME: str = "Financial Analyzer"
+APP_VERSION: str = "1.0.0"

main.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""
+main.py — Financial Analyzer entry point.
+
+Run: python main.py
+"""
+import sys, io, os
+from pathlib import Path
+
+# Force UTF-8 on Windows so log messages with unicode chars (→ ✓ ✗) don't crash
+if sys.platform == "win32":
+    os.environ["PYTHONIOENCODING"] = "utf-8"
+    try:
+        sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8", errors="replace")
+        sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8", errors="replace")
+    except AttributeError:
+        pass
+
+# Make sure local packages resolve correctly
+sys.path.insert(0, str(Path(__file__).parent))
+
+from storage.cache import init_db
+
+def main():
+    # Ensure DB exists
+    init_db()
+
+    try:
+        from gui.app_window import AppWindow
+    except ImportError as e:
+        print(f"ERROR: Could not import GUI: {e}")
+        print("Make sure you have installed dependencies:")
+        print("  pip install customtkinter Pillow requests beautifulsoup4 lxml")
+        print("  pip install python-dotenv google-generativeai anthropic openpyxl python-docx pandas")
+        sys.exit(1)
+
+    app = AppWindow()
+    app.mainloop()
+
+
+if __name__ == "__main__":
+    main()

pipeline/__init__.py

@@ -0,0 +1 @@
+# pipeline package

pipeline/analyst.py

@@ -0,0 +1,579 @@
+"""
+pipeline/analyst.py — Multi-model AI narrative generation.
+
+Supports Google Gemini and Anthropic Claude.
+Each model generates the full narrative; if both selected,
+outputs are combined with a comparison section.
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from config import GEMINI_API_KEY, CLAUDE_API_KEY, GEMINI_MODEL, CLAUDE_MODEL, OPENAI_API_KEY, OPENAI_MODEL, GROQ_API_KEY, GROQ_MODEL
+
+
+# ── Formatting helpers ────────────────────────────────────────────────────────
+
+def _pct(v):
+    return f"{v*100:.1f}%" if v is not None else "N/A"
+
+def _num(v, dec=2):
+    return f"{v:.{dec}f}" if v is not None else "N/A"
+
+def _money(v, currency="INR", units="Crores"):
+    """Format a pre-scaled monetary value. Data is already in Crores (INR) or Millions (USD)."""
+    if v is None:
+        return "N/A"
+    sym = "\u20b9" if currency == "INR" else "$"
+    av = abs(v)
+    if currency == "INR":
+        # Data already in Crores
+        if av >= 100000:
+            return f"{sym}{v/100000:,.2f} L.Cr"
+        return f"{sym}{v:,.2f} Cr"
+    else:
+        # Data already in Millions
+        if av >= 1000:
+            return f"{sym}{v/1000:,.2f}B"
+        return f"{sym}{v:,.2f}M"
+
+
+# ── Context builder ───────────────────────────────────────────────────────────
+
+def _build_context(data: Dict, meta: Dict) -> str:
+    """Build a rich textual context string from all financial data."""
+    years = data.get("years", [])
+    inc   = data.get("income_statement", {})
+    bal   = data.get("balance_sheet", {})
+    cf    = data.get("cash_flow", {})
+    rat   = data.get("ratios", {})
+    gr    = data.get("growth_metrics", {})
+    dp    = data.get("dupont", {})
+    cur   = data.get("currency", "INR")
+
+    def row(label, arr, fmt="money"):
+        units = data.get("units", "Crores")
+        vals = " | ".join([
+            (_money(v, cur, units) if fmt == "money" else _pct(v) if fmt == "pct" else _num(v))
+            for v in (arr or [])
+        ])
+        return f"  {label}: {vals}"
+
+    lines = [
+        f"COMPANY: {meta.get('name', '')} ({meta.get('ticker', '')})",
+        f"EXCHANGE: {meta.get('exchange', '')} | SECTOR: {meta.get('sector', '')} | INDUSTRY: {meta.get('industry', '')}",
+        f"COUNTRY: {meta.get('country', '')} | CURRENCY: {cur}",
+        f"YEARS (oldest→newest): {' | '.join(str(y) for y in years)}",
+        "",
+        "=== INCOME STATEMENT ===",
+        row("Revenue",            inc.get("revenue")),
+        row("Gross Profit",       inc.get("gross_profit")),
+        row("Operating Income",   inc.get("operating_income")),
+        row("EBITDA",             inc.get("ebitda")),
+        row("Net Income",         inc.get("net_income")),
+        row("Diluted EPS",        inc.get("diluted_eps"), "num"),
+        "",
+        "=== BALANCE SHEET ===",
+        row("Total Assets",       bal.get("total_assets")),
+        row("Total Equity",       bal.get("total_equity")),
+        row("Total Liabilities",  bal.get("total_liabilities")),
+        row("Long-term Debt",     bal.get("long_term_debt")),
+        row("Cash",               bal.get("cash_and_equivalents")),
+        row("Current Assets",     bal.get("total_current_assets")),
+        row("Current Liabilities",bal.get("total_current_liabilities")),
+        "",
+        "=== CASH FLOW ===",
+        row("Cash from Operations", cf.get("cash_from_operations")),
+        row("Capex",                cf.get("capex")),
+        row("Free Cash Flow",       cf.get("free_cash_flow")),
+        "",
+        "=== PROFITABILITY RATIOS ===",
+        row("Gross Margin",         rat.get("gross_margin"), "pct"),
+        row("Operating Margin",     rat.get("operating_margin"), "pct"),
+        row("Net Margin",           rat.get("net_margin"), "pct"),
+        row("ROE",                  rat.get("roe"), "pct"),
+        row("ROA",                  rat.get("roa"), "pct"),
+        row("ROIC",                 rat.get("roic"), "pct"),
+        "",
+        "=== LIQUIDITY & SOLVENCY ===",
+        row("Current Ratio",        rat.get("current_ratio"), "num"),
+        row("Quick Ratio",          rat.get("quick_ratio"), "num"),
+        row("Debt-to-Equity",       rat.get("debt_to_equity"), "num"),
+        row("Net Debt/EBITDA",      rat.get("net_debt_to_ebitda"), "num"),
+        row("Interest Coverage",    rat.get("interest_coverage"), "num"),
+        "",
+        "=== EFFICIENCY ===",
+        row("Asset Turnover",       rat.get("asset_turnover"), "num"),
+        row("DSO (days)",           rat.get("days_sales_outstanding"), "num"),
+        row("DPO (days)",           rat.get("days_payables"), "num"),
+        row("Cash Conversion Cycle",rat.get("cash_conversion_cycle"), "num"),
+        "",
+        "=== DUPONT DECOMPOSITION ===",
+        row("Net Margin",           dp.get("net_margin"), "pct"),
+        row("Asset Turnover",       dp.get("asset_turnover"), "num"),
+        row("Equity Multiplier",    dp.get("equity_multiplier"), "num"),
+        row("ROE (DuPont)",         dp.get("roe_computed"), "pct"),
+        "",
+        "=== GROWTH METRICS ===",
+        row("Revenue YoY",          gr.get("revenue_yoy"), "pct"),
+        f"  Revenue 5yr CAGR: {_pct(gr.get('revenue_cagr_5y'))}",
+        row("Net Income YoY",       gr.get("net_income_yoy"), "pct"),
+        f"  Net Income 5yr CAGR: {_pct(gr.get('net_income_cagr_5y'))}",
+        row("FCF YoY",              gr.get("fcf_yoy"), "pct"),
+    ]
+
+    # Valuation
+    val = data.get("valuation_snapshot", {})
+    if val:
+        lines += [
+            "",
+            "=== VALUATION SNAPSHOT ===",
+            f"  P/E (TTM): {_num(val.get('pe_ttm'))}",
+            f"  P/B: {_num(val.get('pb'))}",
+            f"  EV/EBITDA: {_num(val.get('ev_ebitda'))}",
+            f"  FCF Yield: {_pct(val.get('fcf_yield'))}",
+            f"  Dividend Yield: {_pct(val.get('dividend_yield'))}",
+        ]
+
+    # Peers
+    peers = data.get("peers", [])
+    if peers:
+        lines += ["", "=== PEER BENCHMARKING ==="]
+        for p in peers:
+            lines.append(
+                f"  {p.get('name')} ({p.get('ticker')}): "
+                f"Rev={_money(p.get('revenue'), p.get('currency','USD'))} | "
+                f"OpM={_pct(p.get('operating_margin'))} | "
+                f"ROE={_pct(p.get('roe'))} | "
+                f"D/E={_num(p.get('debt_to_equity'))}"
+            )
+
+    return "\n".join(lines)
+
+
+# ── System prompt ─────────────────────────────────────────────────────────────
+
+SYSTEM_PROMPT = """You are a senior financial analyst with expertise in Indian and global equity markets. 
+You write rigorous, opinionated, data-driven financial analysis reports.
+
+Guidelines:
+- Be specific: cite exact numbers from the data provided, not generic statements
+- Be opinionated: state what the numbers actually mean, not just what they are
+- Use Indian financial terminology where appropriate (Crores, Lakhs, SEBI, NSE/BSE)
+- Flag data gaps honestly rather than speculating
+- Keep commentary professional but readable
+- Do NOT use markdown formatting in your response — plain prose only
+- Paragraph breaks only (use double newline to separate paragraphs)
+- Numbers should be expressed in appropriate units (Cr for large INR amounts, B/M for USD)
+"""
+
+# ── Section prompts ───────────────────────────────────────────────────────────
+
+SECTION_PROMPTS = {
+    "executive_summary": """
+Write a 250-300 word executive summary of this company's financial health.
+Answer these questions directly:
+1. Is the business financially healthy or deteriorating?
+2. What is the most important trend in the numbers?
+3. How does it stack up against peers?
+4. What is the key risk visible in the data?
+5. What is the key opportunity?
+Be direct and opinionated. No hedging.
+""",
+    "company_profile": """
+Write a 2-paragraph company profile covering:
+- What the company does, its key business segments, and geographic presence
+- Its position in the market, key products/services, major customers or clients if known
+Use public knowledge about this company; supplement with the financial data provided.
+""",
+    "industry_profile": """
+Write a 2-paragraph industry profile for this company's sector/industry covering:
+- Market size and structure (fragmented/consolidated, key players)
+- Key growth drivers and headwinds for this industry in the Indian/global context
+- Regulatory environment relevant to this industry
+""",
+    "swot": """
+Perform a rigorous SWOT analysis grounded in the financial data and industry knowledge.
+Format your response as four sections:
+
+STRENGTHS:
+[3-4 specific, data-grounded strengths]
+
+WEAKNESSES:
+[3-4 specific, data-grounded weaknesses]
+
+OPPORTUNITIES:
+[3-4 specific opportunities for this company/industry]
+
+THREATS:
+[3-4 specific threats, including competitive and regulatory]
+
+Be specific — avoid generic SWOT points that could apply to any company.
+""",
+    "industry_trends": """
+Write 2-3 paragraphs on current and emerging trends in this company's industry, covering:
+- Macro trends (digitization, ESG, AI, PLI schemes for Indian companies, etc.)
+- Competitive dynamics and consolidation
+- Technology disruption if applicable
+- Regulatory changes (SEBI, RBI, sector-specific regulators for Indian companies)
+Ground trends in the financial data where possible (e.g., if margins are compressing, is it industry-wide?).
+""",
+    "trend_analysis_revenue": """
+Write 2-3 paragraphs analyzing the revenue and profitability trends over the analysis period.
+Specifically address:
+- Revenue trajectory (acceleration/deceleration/volatility)
+- Gross margin trend and what it reveals about pricing power
+- Operating leverage (are operating margins improving as revenue grows?)
+- Quality of earnings (is net income growing in line with revenue?)
+Reference specific numbers from the data.
+""",
+    "trend_analysis_balance_sheet": """
+Write 2 paragraphs analyzing balance sheet strength and capital structure trends.
+Address:
+- Liquidity position (current ratio, cash levels)
+- Leverage trajectory (is debt rising or falling relative to equity/earnings?)
+- Asset quality (goodwill, receivables trends)
+- Working capital efficiency
+""",
+    "trend_analysis_cashflow": """
+Write 2 paragraphs analyzing cash flow quality and capital allocation.
+Address:
+- OCF quality (does it consistently exceed net income, or lag it — and why?)
+- Capex intensity and investment cycle
+- Free cash flow generation and its trajectory
+- How is FCF being allocated (buybacks, dividends, debt repayment, acquisitions)?
+""",
+    "ratio_commentary": """
+Write 2-3 paragraphs interpreting the ratio analysis.
+Focus on:
+- Which ratios show the most significant trends (positive or negative)?
+- Any ratios that are outliers vs. industry norms?
+- What do the efficiency ratios (DSO, DPO, CCC) tell us about operational quality?
+- DuPont decomposition: which driver is most responsible for ROE trends?
+""",
+    "peer_commentary": """
+Write 2 paragraphs benchmarking this company against its peers.
+Address:
+- Where does the company rank on the most important metrics for this industry?
+- What explains the gaps vs. peers (structural, cyclical, or management decisions)?
+- Is the company gaining or losing competitive position?
+""",
+    "key_insights": """
+List 4-6 key insights, one per line. Each insight must:
+- Be substantive and specific (not generic)
+- Reference a specific number or trend from the data
+- Convey an analytical judgment, not just a fact
+
+Format: One insight per line, starting with a dash (-).
+""",
+    "risks": """
+List the top 5-7 risks facing this company. For each risk, use this format:
+CATEGORY | Risk description (specific, grounded in data or industry knowledge)
+
+Categories to use: Financial, Business, Industry, Regulatory, ESG
+""",
+    "things_to_watch": """
+List 4-5 specific, monitorable metrics or events that would change the investment picture.
+Format: One per line starting with a dash (-).
+Be concrete: e.g., 'Watch for gross margin recovery above 30% in FY26' not 'watch margins'.
+""",
+    "limitations": """
+List any material analytical limitations in 3-5 bullet points. Include:
+- Data gaps (which line items are missing or estimated)
+- Comparability issues (fiscal year changes, acquisitions)
+- Data source caveats (scraped vs. filed data)
+- Any ratios that could not be computed meaningfully (negative equity, etc.)
+Format: One per line starting with a dash (-).
+""",
+}
+
+
+# ── Gemini ────────────────────────────────────────────────────────────────────
+
+def _gemini_generate(context: str, section: str, log_fn=None) -> str:
+    """Generate using Gemini — tries API key first, then Google OAuth login."""
+    prompt = f"{SYSTEM_PROMPT}\n\nFINANCIAL DATA:\n{context}\n\nTASK:\n{SECTION_PROMPTS[section]}"
+
+    # ── Path 1: API Key (new google-genai SDK) ──────────────────────────────
+    if GEMINI_API_KEY:
+        try:
+            from google import genai
+            from google.genai import types as gtypes
+            client = genai.Client(api_key=GEMINI_API_KEY)
+            response = client.models.generate_content(
+                model=GEMINI_MODEL,
+                contents=prompt,
+                config=gtypes.GenerateContentConfig(temperature=0.2, max_output_tokens=1024),
+            )
+            return response.text.strip()
+        except Exception:
+            pass
+        # Fallback to old SDK
+        try:
+            import google.generativeai as genai_old
+            genai_old.configure(api_key=GEMINI_API_KEY)
+            model = genai_old.GenerativeModel(model_name=GEMINI_MODEL, system_instruction=SYSTEM_PROMPT)
+            response = model.generate_content(f"FINANCIAL DATA:\n{context}\n\nTASK:\n{SECTION_PROMPTS[section]}")
+            return response.text.strip()
+        except Exception as e2:
+            return f"[Gemini error for {section}: {e2}]"
+
+    return f"[Gemini unavailable for {section}: API key missing]"
+
+
+
+# ── OpenAI / ChatGPT ─────────────────────────────────────────────────────────
+
+def _openai_generate(context: str, section: str, log_fn=None) -> str:
+    try:
+        from openai import OpenAI
+        client = OpenAI(api_key=OPENAI_API_KEY)
+        prompt = f"FINANCIAL DATA:\n{context}\n\nTASK:\n{SECTION_PROMPTS[section]}"
+        resp = client.chat.completions.create(
+            model=OPENAI_MODEL,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user",   "content": prompt},
+            ],
+            temperature=0.2,
+            max_tokens=1024,
+        )
+        return resp.choices[0].message.content.strip()
+    except Exception as e:
+        return f"[ChatGPT error for {section}: {e}]"
+
+
+# ── Groq (free — Llama 3.3 70B) ──────────────────────────────────────────────
+
+def _groq_generate(context: str, section: str, log_fn=None) -> str:
+    """Generate using Groq's OpenAI-compatible API (free tier, Llama 3.3 70B)."""
+    try:
+        from openai import OpenAI
+        client = OpenAI(
+            api_key=GROQ_API_KEY,
+            base_url="https://api.groq.com/openai/v1",
+        )
+        prompt = f"FINANCIAL DATA:\n{context}\n\nTASK:\n{SECTION_PROMPTS[section]}"
+        resp = client.chat.completions.create(
+            model=GROQ_MODEL,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {"role": "user",   "content": prompt},
+            ],
+            temperature=0.2,
+            max_tokens=1024,
+        )
+        return resp.choices[0].message.content.strip()
+    except Exception as e:
+        return f"[Groq error for {section}: {e}]"
+
+
+# ── Claude ────────────────────────────────────────────────────────────────────
+
+def _claude_generate(context: str, section: str, log_fn=None) -> str:
+    try:
+        import anthropic
+        client = anthropic.Anthropic(api_key=CLAUDE_API_KEY)
+        prompt = f"FINANCIAL DATA:\n{context}\n\nTASK:\n{SECTION_PROMPTS[section]}"
+        message = client.messages.create(
+            model=CLAUDE_MODEL,
+            max_tokens=1024,
+            system=SYSTEM_PROMPT,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        return message.content[0].text.strip()
+    except Exception as e:
+        return f"[Claude error for {section}: {e}]"
+
+
+# ── Parse structured sections ─────────────────────────────────────────────────
+
+def _parse_swot(text: str) -> Dict[str, List[str]]:
+    """Parse SWOT text into a structured dict."""
+    result = {"strengths": [], "weaknesses": [], "opportunities": [], "threats": []}
+    current = None
+    for line in text.split("\n"):
+        l = line.strip()
+        if l.upper().startswith("STRENGTH"):
+            current = "strengths"
+        elif l.upper().startswith("WEAKNESS"):
+            current = "weaknesses"
+        elif l.upper().startswith("OPPORTUNIT"):
+            current = "opportunities"
+        elif l.upper().startswith("THREAT"):
+            current = "threats"
+        elif current and l and not l.upper() in ("STRENGTHS:", "WEAKNESSES:", "OPPORTUNITIES:", "THREATS:"):
+            result[current].append(l.lstrip("-• "))
+    return result
+
+
+def _parse_bullets(text: str) -> List[str]:
+    """Parse a bulleted list response into a list of strings."""
+    items = []
+    for line in text.split("\n"):
+        l = line.strip().lstrip("-•* ")
+        if l:
+            items.append(l)
+    return items
+
+
+def _parse_risks(text: str) -> List[Dict]:
+    """Parse risk list into categorized dicts."""
+    risks = []
+    for line in text.split("\n"):
+        l = line.strip().lstrip("-•* ")
+        if "|" in l:
+            parts = l.split("|", 1)
+            risks.append({"category": parts[0].strip(), "description": parts[1].strip()})
+        elif l:
+            risks.append({"category": "General", "description": l})
+    return risks
+
+
+# ── Main entry point ──────────────────────────────────────────────────────────
+
+def generate_narrative(
+    data: Dict,
+    meta: Dict,
+    models: List[str],
+    log_fn=None,
+) -> Dict:
+    """
+    Generate full narrative analysis using selected AI models.
+
+    Args:
+        data: Calculated financial data dict.
+        meta: CompanyMeta.to_dict()
+        models: List of model names, e.g. ['gemini', 'claude'] or ['gemini']
+        log_fn: Optional progress callback.
+
+    Returns:
+        Dict with all narrative fields populated.
+    """
+    def log(msg):
+        if log_fn:
+            log_fn(msg)
+
+    use_gemini = "gemini" in models and bool(GEMINI_API_KEY)
+    use_claude = "claude" in models and bool(CLAUDE_API_KEY)
+    use_openai = "openai" in models and bool(OPENAI_API_KEY)
+    use_groq   = "groq"   in models and bool(GROQ_API_KEY)
+
+    if not use_gemini and not use_claude and not use_openai and not use_groq:
+        log("No AI models configured. Running data-only analysis (no narrative).")
+        return _empty_narrative()
+
+    context = _build_context(data, meta)
+    active = [m for m, ok in [("Gemini",use_gemini),("Claude",use_claude),("ChatGPT",use_openai),("Groq (Llama)",use_groq)] if ok]
+    log(f"Generating AI narrative ({', '.join(active)}) ...")
+
+    def gen(section: str) -> str:
+        results = []
+        if use_gemini:
+            log(f"  Gemini: {section} ...")
+            results.append(("Gemini", _gemini_generate(context, section, log_fn)))
+        if use_claude:
+            log(f"  Claude: {section} ...")
+            results.append(("Claude", _claude_generate(context, section, log_fn)))
+        if use_openai:
+            log(f"  ChatGPT: {section} ...")
+            results.append(("ChatGPT", _openai_generate(context, section, log_fn)))
+        if use_groq:
+            log(f"  Groq (Llama 3.3): {section} ...")
+            results.append(("Groq/Llama", _groq_generate(context, section, log_fn)))
+
+        if len(results) == 1:
+            return results[0][1]
+        # Multiple models — combine with attribution
+        combined = ""
+        for name, text in results:
+            combined += f"[{name}]\n{text}\n\n"
+        return combined.strip()
+
+    # Generate all sections
+    log("  Generating executive summary …")
+    exec_summary = gen("executive_summary")
+
+    log("  Generating company profile …")
+    company_overview = gen("company_profile")
+
+    log("  Generating industry profile …")
+    industry_profile = gen("industry_profile")
+
+    log("  Generating SWOT …")
+    swot_raw = gen("swot")
+    swot = _parse_swot(swot_raw)
+
+    log("  Generating industry trends …")
+    industry_trends = gen("industry_trends")
+
+    log("  Generating trend analysis …")
+    trend_revenue  = gen("trend_analysis_revenue")
+    trend_bs       = gen("trend_analysis_balance_sheet")
+    trend_cf       = gen("trend_analysis_cashflow")
+
+    log("  Generating ratio commentary …")
+    ratio_commentary = gen("ratio_commentary")
+
+    log("  Generating peer commentary …")
+    peer_commentary = gen("peer_commentary")
+
+    log("  Generating insights …")
+    insights_raw = gen("key_insights")
+    insights = _parse_bullets(insights_raw)
+
+    log("  Generating risks …")
+    risks_raw = gen("risks")
+    risks = _parse_risks(risks_raw)
+
+    log("  Generating things to watch …")
+    watch_raw = gen("things_to_watch")
+    things_to_watch = _parse_bullets(watch_raw)
+
+    log("  Generating limitations …")
+    lim_raw = gen("limitations")
+    limitations = _parse_bullets(lim_raw)
+
+    log("  ✓ AI narrative generation complete")
+
+    return {
+        "executive_summary":        exec_summary,
+        "company_overview":         company_overview,
+        "industry_profile":         industry_profile,
+        "swot":                     swot,
+        "industry_trends":          industry_trends,
+        "trend_analysis": {
+            "revenue_and_profitability": trend_revenue,
+            "balance_sheet_strength":    trend_bs,
+            "cash_flow_generation":      trend_cf,
+        },
+        "ratio_analysis_commentary":   ratio_commentary,
+        "peer_comparison_commentary":  peer_commentary,
+        "key_insights":                insights,
+        "risks":                       risks,
+        "things_to_watch":             things_to_watch,
+        "limitations_and_caveats":     limitations,
+        "models_used":                 models,
+    }
+
+
+def _empty_narrative() -> Dict:
+    return {
+        "executive_summary":         "AI narrative not generated (no API keys configured).",
+        "company_overview":          "",
+        "industry_profile":          "",
+        "swot":                      {"strengths": [], "weaknesses": [], "opportunities": [], "threats": []},
+        "industry_trends":           "",
+        "trend_analysis":            {"revenue_and_profitability": "", "balance_sheet_strength": "", "cash_flow_generation": ""},
+        "ratio_analysis_commentary": "",
+        "peer_comparison_commentary":"",
+        "key_insights":              [],
+        "risks":                     [],
+        "things_to_watch":           [],
+        "limitations_and_caveats":   [],
+        "models_used":               [],
+    }

pipeline/calculator.py

@@ -0,0 +1,361 @@
+"""
+pipeline/calculator.py — Compute all financial ratios, DuPont decomposition,
+growth metrics, and scale numbers for display.
+"""
+from __future__ import annotations
+
+import math
+from typing import Any, Dict, List, Optional, Tuple
+
+
+def _safe_div(num, den, default=None):
+    """Safe division returning default if denominator is None/zero."""
+    try:
+        if num is None or den is None:
+            return default
+        if den == 0:
+            return default
+        return num / den
+    except (TypeError, ZeroDivisionError):
+        return default
+
+
+def _avg(a, b):
+    """Average of two values, None if either is None."""
+    if a is None or b is None:
+        return None
+    return (a + b) / 2
+
+
+def _pct_change(current, previous):
+    """Year-over-year % change."""
+    if current is None or previous is None or previous == 0:
+        return None
+    return (current - previous) / abs(previous)
+
+
+def _cagr(start, end, n):
+    """Compound annual growth rate over n periods."""
+    if start is None or end is None or n <= 0:
+        return None
+    if start <= 0 or end < 0:
+        return None
+    try:
+        return (end / start) ** (1 / n) - 1
+    except (ZeroDivisionError, ValueError):
+        return None
+
+
+def _series(data_dict: Dict, key: str, n: int) -> List[Optional[float]]:
+    """Extract a time-series list, padded/trimmed to length n."""
+    vals = data_dict.get(key, [])
+    if len(vals) < n:
+        vals = vals + [None] * (n - len(vals))
+    return vals[:n]
+
+
+# ── Auto unit scaling ─────────────────────────────────────────────────────────
+
+def auto_scale(values: List[Optional[float]], currency: str) -> Tuple[List[Optional[float]], str]:
+    """
+    Scale a list of monetary values to a human-readable unit.
+    Returns (scaled_values, unit_label).
+    """
+    non_null = [abs(v) for v in values if v is not None and v != 0]
+    if not non_null:
+        return values, ""
+    mag = max(non_null)
+
+    if currency == "INR":
+        if mag >= 1e7:          # >= 1 Crore (in thousands → multiply)
+            # FMP stores in thousands for Indian, screener in Crores
+            # We'll just label appropriately
+            if mag >= 1e9:
+                factor, label = 1e7, "₹ Crores"
+            elif mag >= 1e5:
+                factor, label = 1e5, "₹ Lakhs"
+            else:
+                factor, label = 1e3, "₹ Thousands"
+        else:
+            factor, label = 1, "₹"
+        # Most FMP returns in actual currency value (not thousands)
+        # screener returns in Crores already
+        return values, label
+    else:
+        # USD / other
+        if mag >= 1e9:
+            factor, label = 1e9, "Billions"
+        elif mag >= 1e6:
+            factor, label = 1e6, "Millions"
+        elif mag >= 1e3:
+            factor, label = 1e3, "Thousands"
+        else:
+            factor, label = 1, ""
+        scaled = [v / factor if v is not None else None for v in values]
+        return scaled, label
+
+
+def smart_format(value: Optional[float], currency: str = "USD") -> str:
+    """Format a single monetary value with smart units."""
+    if value is None:
+        return "N/A"
+    av = abs(value)
+    if currency == "INR":
+        if av >= 1e7:
+            return f"₹{value/1e7:,.2f} Cr"
+        elif av >= 1e5:
+            return f"₹{value/1e5:,.2f} L"
+        else:
+            return f"₹{value:,.0f}"
+    else:
+        sym = "$" if currency == "USD" else ""
+        if av >= 1e9:
+            return f"{sym}{value/1e9:,.2f}B"
+        elif av >= 1e6:
+            return f"{sym}{value/1e6:,.2f}M"
+        elif av >= 1e3:
+            return f"{sym}{value/1e3:,.2f}K"
+        else:
+            return f"{sym}{value:,.2f}"
+
+
+# ── Main calculation entry ────────────────────────────────────────────────────
+
+def calculate(financial_data: Dict, meta_dict: Dict) -> Dict:
+    """
+    Compute all ratios, DuPont, growth metrics from raw financial data.
+
+    Args:
+        financial_data: Output of fetcher.fetch_all()
+        meta_dict: CompanyMeta.to_dict()
+
+    Returns:
+        Complete analysis dict ready for analyst.py and builders.
+    """
+    years = financial_data.get("years", [])
+    n = len(years)
+    if n == 0:
+        return financial_data  # Nothing to compute
+
+    inc = financial_data.get("income_statement", {})
+    bal = financial_data.get("balance_sheet", {})
+    cf  = financial_data.get("cash_flow", {})
+    currency = financial_data.get("currency", meta_dict.get("currency", "USD"))
+
+    def S(key, src=None):
+        src = src or inc
+        return _series(src, key, n)
+
+    # ── Extract series ──────────────────────────────────────────────────��─────
+    revenue            = S("revenue")
+    cogs               = S("cost_of_revenue")
+    gross_profit       = S("gross_profit")
+    op_income          = S("operating_income")
+    ebitda             = S("ebitda")
+    da                 = S("depreciation_amort")
+    interest_exp       = S("interest_expense")
+    pretax_income      = S("pretax_income")
+    tax_expense        = S("tax_expense")
+    net_income         = S("net_income")
+    diluted_eps        = S("diluted_eps")
+    diluted_shares     = S("diluted_shares")
+
+    total_assets       = S("total_assets", bal)
+    total_equity       = S("total_equity", bal)
+    total_liabilities  = S("total_liabilities", bal)
+    total_curr_assets  = S("total_current_assets", bal)
+    total_curr_liab    = S("total_current_liabilities", bal)
+    inventory          = S("inventory", bal)
+    receivables        = S("receivables", bal)
+    payables           = S("accounts_payable", bal)
+    short_debt         = S("short_term_debt", bal)
+    long_debt          = S("long_term_debt", bal)
+    cash               = S("cash_and_equivalents", bal)
+    st_inv             = S("short_term_investments", bal)
+
+    cfo                = S("cash_from_operations", cf)
+    capex              = S("capex", cf)
+    fcf                = S("free_cash_flow", cf)
+    dividends          = S("dividends_paid", cf)
+    buybacks           = S("stock_buybacks", cf)
+
+    # Compute EBITDA if missing
+    for i in range(n):
+        if ebitda[i] is None and op_income[i] is not None and da[i] is not None:
+            ebitda[i] = op_income[i] + da[i]
+
+    # Compute FCF if missing
+    for i in range(n):
+        if fcf[i] is None and cfo[i] is not None and capex[i] is not None:
+            fcf[i] = cfo[i] + capex[i]  # capex is usually negative in FMP
+
+    # Total debt
+    total_debt = [
+        (s or 0) + (l or 0) if (s is not None or l is not None) else None
+        for s, l in zip(short_debt, long_debt)
+    ]
+
+    # Effective tax rate
+    eff_tax_rate = [
+        _safe_div(t, p) if p and p > 0 else None
+        for t, p in zip(tax_expense, pretax_income)
+    ]
+
+    # NOPAT
+    nopat = [
+        o * (1 - (t or 0)) if o is not None else None
+        for o, t in zip(op_income, eff_tax_rate)
+    ]
+
+    # Invested capital = Total equity + Total debt - Cash
+    inv_capital = [
+        (e or 0) + (d or 0) - (c or 0)
+        if e is not None or d is not None else None
+        for e, d, c in zip(total_equity, total_debt, cash)
+    ]
+
+    # ── Profitability ratios ──────────────────────────────────────────────────
+    gross_margin    = [_safe_div(g, r) for g, r in zip(gross_profit, revenue)]
+    op_margin       = [_safe_div(o, r) for o, r in zip(op_income, revenue)]
+    ebitda_margin   = [_safe_div(e, r) for e, r in zip(ebitda, revenue)]
+    net_margin      = [_safe_div(n_, r) for n_, r in zip(net_income, revenue)]
+
+    # ROE, ROA, ROIC use averages
+    roe  = [_safe_div(n_, _avg(e0, e1)) for n_, e0, e1 in zip(
+        net_income, [None] + total_equity[:-1], total_equity)]
+    roa  = [_safe_div(n_, _avg(a0, a1)) for n_, a0, a1 in zip(
+        net_income, [None] + total_assets[:-1], total_assets)]
+    roic = [_safe_div(no, _avg(ic0, ic1)) for no, ic0, ic1 in zip(
+        nopat, [None] + inv_capital[:-1], inv_capital)]
+
+    # ── Liquidity ─────────────────────────────────────────────────────────────
+    current_ratio = [_safe_div(ca, cl) for ca, cl in zip(total_curr_assets, total_curr_liab)]
+    quick_ratio   = [
+        _safe_div((ca or 0) - (inv or 0), cl)
+        if ca is not None and cl else None
+        for ca, inv, cl in zip(total_curr_assets, inventory, total_curr_liab)
+    ]
+    cash_ratio = [
+        _safe_div((c or 0) + (si or 0), cl)
+        if cl else None
+        for c, si, cl in zip(cash, st_inv, total_curr_liab)
+    ]
+
+    # ── Solvency / Leverage ───────────────────────────────────────────────────
+    debt_to_equity   = [_safe_div(d, e) for d, e in zip(total_debt, total_equity)]
+    debt_to_assets   = [_safe_div(d, a) for d, a in zip(total_debt, total_assets)]
+    net_debt         = [(d or 0) - (c or 0) - (si or 0) if d is not None else None
+                        for d, c, si in zip(total_debt, cash, st_inv)]
+    net_debt_ebitda  = [_safe_div(nd, e) for nd, e in zip(net_debt, ebitda)]
+    interest_cov     = [_safe_div(o, ie) for o, ie in zip(op_income, interest_exp)]
+
+    # ── Efficiency ────────────────────────────────────────────────────────────
+    asset_turnover    = [_safe_div(r, _avg(a0, a1)) for r, a0, a1 in zip(
+        revenue, [None] + total_assets[:-1], total_assets)]
+    inv_turnover      = [_safe_div(c, _avg(i0, i1)) for c, i0, i1 in zip(
+        cogs, [None] + inventory[:-1], inventory)]
+    days_inv          = [_safe_div(365, it) for it in inv_turnover]
+    rec_turnover      = [_safe_div(r, _avg(rc0, rc1)) for r, rc0, rc1 in zip(
+        revenue, [None] + receivables[:-1], receivables)]
+    days_sales        = [_safe_div(365, rt) for rt in rec_turnover]
+    pay_turnover      = [_safe_div(c, _avg(p0, p1)) for c, p0, p1 in zip(
+        cogs, [None] + payables[:-1], payables)]
+    days_payable      = [_safe_div(365, pt) for pt in pay_turnover]
+    ccc               = [
+        (di or 0) + (ds or 0) - (dp or 0)
+        if di is not None and ds is not None and dp is not None else None
+        for di, ds, dp in zip(days_inv, days_sales, days_payable)
+    ]
+
+    # ── Cash flow quality ─────────────────────────────────────────────────────
+    ocf_to_ni      = [_safe_div(c, n_) for c, n_ in zip(cfo, net_income)]
+    fcf_margin_    = [_safe_div(f, r) for f, r in zip(fcf, revenue)]
+    fcf_conversion = [_safe_div(f, n_) for f, n_ in zip(fcf, net_income)]
+    capex_intensity = [_safe_div(abs(c) if c else None, r) for c, r in zip(capex, revenue)]
+
+    # ── Growth metrics ────────────────────────────────────────────────────────
+    def yoy(arr):
+        result = [None]
+        for i in range(1, len(arr)):
+            result.append(_pct_change(arr[i], arr[i-1]))
+        return result
+
+    rev_yoy   = yoy(revenue)
+    op_yoy    = yoy(op_income)
+    ni_yoy    = yoy(net_income)
+    eps_yoy   = yoy(diluted_eps)
+    fcf_yoy   = yoy(fcf)
+
+    def cagr_5y(arr):
+        valid = [v for v in arr if v is not None]
+        if len(valid) < 2:
+            return None
+        return _cagr(valid[0], valid[-1], len(valid) - 1)
+
+    growth_metrics = {
+        "revenue_yoy":               rev_yoy,
+        "revenue_cagr_5y":           cagr_5y(revenue),
+        "operating_income_yoy":      op_yoy,
+        "operating_income_cagr_5y":  cagr_5y(op_income),
+        "net_income_yoy":            ni_yoy,
+        "net_income_cagr_5y":        cagr_5y(net_income),
+        "eps_yoy":                   eps_yoy,
+        "eps_cagr_5y":               cagr_5y(diluted_eps),
+        "fcf_yoy":                   fcf_yoy,
+        "fcf_cagr_5y":               cagr_5y(fcf),
+    }
+
+    # ── DuPont decomposition ──────────────────────────────────────────────────
+    # ROE = Net Margin × Asset Turnover × Equity Multiplier
+    equity_multiplier = [_safe_div(a, e) for a, e in zip(total_assets, total_equity)]
+    dupont = {
+        "net_margin":         net_margin,
+        "asset_turnover":     asset_turnover,
+        "equity_multiplier":  equity_multiplier,
+        "roe_computed":       [
+            (nm or 0) * (at or 0) * (em or 0)
+            if nm is not None and at is not None and em is not None else None
+            for nm, at, em in zip(net_margin, asset_turnover, equity_multiplier)
+        ],
+        "roe_reported":       roe,
+    }
+
+    # ── Ratios dict ───────────────────────────────────────────────────────────
+    ratios = {
+        "gross_margin":           gross_margin,
+        "operating_margin":       op_margin,
+        "ebitda_margin":          ebitda_margin,
+        "net_margin":             net_margin,
+        "roe":                    roe,
+        "roa":                    roa,
+        "roic":                   roic,
+        "current_ratio":          current_ratio,
+        "quick_ratio":            quick_ratio,
+        "cash_ratio":             cash_ratio,
+        "debt_to_equity":         debt_to_equity,
+        "debt_to_assets":         debt_to_assets,
+        "net_debt_to_ebitda":     net_debt_ebitda,
+        "interest_coverage":      interest_cov,
+        "asset_turnover":         asset_turnover,
+        "inventory_turnover":     inv_turnover,
+        "days_inventory":         days_inv,
+        "days_sales_outstanding": days_sales,
+        "days_payables":          days_payable,
+        "cash_conversion_cycle":  ccc,
+        "ocf_to_net_income":      ocf_to_ni,
+        "fcf_margin":             fcf_margin_,
+        "fcf_conversion":         fcf_conversion,
+        "capex_intensity":        capex_intensity,
+    }
+
+    # Build final output
+    result = dict(financial_data)
+    result["ratios"] = ratios
+    result["growth_metrics"] = growth_metrics
+    result["dupont"] = dupont
+    result["nopat"] = nopat
+    result["total_debt"] = total_debt
+    result["net_debt"] = net_debt
+    result["currency"] = currency
+
+    return result

pipeline/fetcher.py

@@ -0,0 +1,542 @@
+"""
+pipeline/fetcher.py — Fetch 5-year financials.
+Priority: yfinance (free, Indian stocks) → FMP → screener.in
+"""
+from __future__ import annotations
+import sys, re, json, datetime
+from pathlib import Path
+from typing import Optional, List, Dict, Any
+
+import requests
+from bs4 import BeautifulSoup
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from config import FMP_API_KEY, FMP_BASE, REQUEST_TIMEOUT, DEFAULT_YEARS
+from storage.cache import get_cached, set_cache
+from pipeline.resolver import CompanyMeta
+
+HEADERS = {"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"}
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _s(v, default=None):
+    if v is None or (isinstance(v, float) and v != v): return default
+    return v
+
+
+def _row(df, *keys):
+    """Get a row from a yfinance DataFrame by trying multiple key names."""
+    for k in keys:
+        if k in df.index:
+            return df.loc[k].tolist()
+    return [None] * len(df.columns)
+
+
+# ── yfinance fetcher (primary for Indian + global) ───────────────────────────
+
+def _fetch_yfinance(ticker: str, years: int, log_fn=None) -> Optional[Dict]:
+    def log(m):
+        if log_fn: log_fn(m)
+    try:
+        import yfinance as yf
+        log(f"  → yfinance: fetching {ticker} …")
+        t = yf.Ticker(ticker)
+
+        fin = t.financials      # newest col first
+        bs  = t.balance_sheet
+        cf  = t.cashflow
+        info = t.info
+
+        if fin is None or fin.empty:
+            log("  ✗ yfinance returned empty financials")
+            return None
+
+        # Year labels — columns are Timestamps, newest first; we want oldest→newest
+        all_cols = list(fin.columns)          # newest first
+        use_cols = all_cols[:years]           # take up to `years` newest
+        use_cols_asc = list(reversed(use_cols))  # now oldest→newest
+        year_labels = []
+        for c in use_cols_asc:
+            try:
+                year_labels.append(f"{c.year}/{c.month:02d}")
+            except Exception:
+                year_labels.append(str(c)[:7])
+
+        n = len(year_labels)
+
+        def col(df, *keys):
+            """Extract a row from df, return list oldest→newest, length n."""
+            for k in keys:
+                if df is not None and not df.empty and k in df.index:
+                    # df columns are newest first; slice to use_cols then reverse
+                    vals = []
+                    for c in use_cols_asc:   # iterate oldest→newest
+                        if c in df.columns:
+                            v = df.at[k, c]
+                            vals.append(None if (v != v or v is None) else float(v))
+                        else:
+                            vals.append(None)
+                    return vals
+            return [None] * n
+
+        currency = info.get("currency", "INR")
+
+        # Determine display scale
+        # INR: raw values are in rupees → divide by 1e7 to get Crores
+        # USD/others: raw values in dollars → divide by 1e6 for Millions
+        if currency == "INR":
+            scale = 1e7          # rupees → crores
+            units = "Crores"
+            units_label = "INR Crores (₹ Cr)"
+        else:
+            scale = 1e6          # dollars → millions
+            units = "Millions"
+            units_label = f"{currency} Millions"
+
+        def sc(lst):
+            """Scale a list of raw values."""
+            return [round(v / scale, 2) if v is not None else None for v in lst]
+
+        income = {
+            "revenue":            sc(col(fin, "Total Revenue", "Operating Revenue")),
+            "cost_of_revenue":    sc(col(fin, "Cost Of Revenue", "Reconciled Cost Of Revenue")),
+            "gross_profit":       sc(col(fin, "Gross Profit")),
+            "operating_expenses": sc(col(fin, "Operating Expense")),
+            "operating_income":   sc(col(fin, "Operating Income", "EBIT")),
+            "ebitda":             sc(col(fin, "EBITDA", "Normalized EBITDA")),
+            "depreciation_amort": sc(col(fin, "Reconciled Depreciation", "Depreciation And Amortization")),
+            "interest_expense":   sc(col(fin, "Interest Expense Non Operating", "Interest Expense")),
+            "pretax_income":      sc(col(fin, "Pretax Income")),
+            "tax_expense":        sc(col(fin, "Tax Provision")),
+            "net_income":         sc(col(fin, "Net Income", "Net Income Common Stockholders")),
+            "diluted_eps":        col(fin, "Diluted EPS"),      # EPS not scaled
+            "diluted_shares":     col(fin, "Diluted Average Shares"),  # not scaled
+        }
+
+        balance = {
+            "cash_and_equivalents":       sc(col(bs, "Cash And Cash Equivalents", "Cash Financial")),
+            "short_term_investments":     sc(col(bs, "Other Short Term Investments")),
+            "receivables":                sc(col(bs, "Accounts Receivable", "Other Receivables")),
+            "inventory":                  sc(col(bs, "Inventory")),
+            "other_current_assets":       sc(col(bs, "Other Current Assets")),
+            "total_current_assets":       sc(col(bs, "Current Assets")),
+            "ppe_net":                    sc(col(bs, "Net PPE")),
+            "goodwill":                   sc(col(bs, "Goodwill")),
+            "intangibles":                sc(col(bs, "Other Intangible Assets")),
+            "other_long_term_assets":     sc(col(bs, "Other Non Current Assets")),
+            "total_assets":               sc(col(bs, "Total Assets")),
+            "accounts_payable":           sc(col(bs, "Accounts Payable", "Payables")),
+            "short_term_debt":            sc(col(bs, "Current Debt", "Current Debt And Capital Lease Obligation")),
+            "other_current_liabilities":  sc(col(bs, "Other Current Liabilities")),
+            "total_current_liabilities":  sc(col(bs, "Current Liabilities")),
+            "long_term_debt":             sc(col(bs, "Long Term Debt", "Long Term Debt And Capital Lease Obligation")),
+            "other_long_term_liabilities":sc(col(bs, "Other Non Current Liabilities")),
+            "total_liabilities":          sc(col(bs, "Total Liabilities Net Minority Interest")),
+            "total_equity":               sc(col(bs, "Stockholders Equity", "Common Stock Equity")),
+            "total_liab_and_equity":      sc(col(bs, "Total Assets")),
+        }
+
+        cashflow = {
+            "net_income":              sc(col(cf, "Net Income From Continuing Operations")),
+            "depreciation_amort":      sc(col(cf, "Depreciation And Amortization", "Depreciation")),
+            "stock_based_comp":        [None] * n,
+            "working_capital_changes": sc(col(cf, "Change In Working Capital")),
+            "other_operating":         sc(col(cf, "Other Non Cash Items")),
+            "cash_from_operations":    sc(col(cf, "Operating Cash Flow")),
+            "capex":                   sc(col(cf, "Capital Expenditure", "Purchase Of PPE")),
+            "acquisitions":            [None] * n,
+            "cash_from_investing":     sc(col(cf, "Investing Cash Flow")),
+            "debt_issuance_repayment": sc(col(cf, "Net Long Term Debt Issuance")),
+            "stock_buybacks":          sc(col(cf, "Net Common Stock Issuance")),
+            "dividends_paid":          sc(col(cf, "Cash Dividends Paid")),
+            "cash_from_financing":     sc(col(cf, "Financing Cash Flow")),
+            "net_change_in_cash":      sc(col(cf, "Changes In Cash")),
+            "free_cash_flow":          sc(col(cf, "Free Cash Flow")),
+        }
+
+        # Compute FCF if missing
+        for i in range(n):
+            if cashflow["free_cash_flow"][i] is None:
+                cfo = cashflow["cash_from_operations"][i]
+                cap = cashflow["capex"][i]
+                if cfo is not None and cap is not None:
+                    cashflow["free_cash_flow"][i] = round(cfo + cap, 2)
+
+        log(f"  ✓ yfinance data ready ({n} years, {currency}, in {units})")
+
+        return {
+            "years": year_labels,
+            "income_statement": income,
+            "balance_sheet":    balance,
+            "cash_flow":        cashflow,
+            "currency":         currency,
+            "units":            units,
+            "units_label":      units_label,
+            "scale":            scale,
+            "source":           "Yahoo Finance (yfinance)",
+            "valuation_snapshot": {
+                "pe_ttm":         _s(info.get("trailingPE")),
+                "pb":             _s(info.get("priceToBook")),
+                "ps":             _s(info.get("priceToSalesTrailing12Months")),
+                "ev_ebitda":      _s(info.get("enterpriseToEbitda")),
+                "ev_revenue":     _s(info.get("enterpriseToRevenue")),
+                "fcf_yield":      None,
+                "dividend_yield": _s(info.get("dividendYield")),
+            },
+        }
+    except Exception as e:
+        import traceback
+        if log_fn: log_fn(f"  ✗ yfinance error: {e}\n{traceback.format_exc()}")
+        return None
+
+
+# ── FMP fetcher (secondary for global) ───────────────────────────────────────
+
+def _fmp_get(path, params=None):
+    if not FMP_API_KEY: return None
+    p = {"apikey": FMP_API_KEY}
+    if params: p.update(params)
+    try:
+        r = requests.get(f"{FMP_BASE}{path}", params=p, timeout=REQUEST_TIMEOUT, headers=HEADERS)
+        r.raise_for_status()
+        return r.json()
+    except Exception:
+        return None
+
+
+def _normalise_fmp(raw, years):
+    inc = list(reversed(raw.get("income", [])))[:years]
+    bal = list(reversed(raw.get("balance", [])))[:years]
+    cf  = list(reversed(raw.get("cashflow", [])))[:years]
+
+    def col(lst, key):
+        return [_s(d.get(key)) for d in lst]
+
+    year_labels = [d.get("calendarYear", str(d.get("date",""))[:4]) for d in inc]
+    income = {
+        "revenue":            col(inc, "revenue"),
+        "cost_of_revenue":    col(inc, "costOfRevenue"),
+        "gross_profit":       col(inc, "grossProfit"),
+        "operating_expenses": col(inc, "operatingExpenses"),
+        "operating_income":   col(inc, "operatingIncome"),
+        "ebitda":             col(inc, "ebitda"),
+        "depreciation_amort": col(inc, "depreciationAndAmortization"),
+        "interest_expense":   col(inc, "interestExpense"),
+        "pretax_income":      col(inc, "incomeBeforeTax"),
+        "tax_expense":        col(inc, "incomeTaxExpense"),
+        "net_income":         col(inc, "netIncome"),
+        "diluted_eps":        col(inc, "epsdiluted"),
+        "diluted_shares":     col(inc, "weightedAverageShsOutDil"),
+    }
+    balance = {
+        "cash_and_equivalents":       col(bal, "cashAndCashEquivalents"),
+        "short_term_investments":     col(bal, "shortTermInvestments"),
+        "receivables":                col(bal, "netReceivables"),
+        "inventory":                  col(bal, "inventory"),
+        "other_current_assets":       col(bal, "otherCurrentAssets"),
+        "total_current_assets":       col(bal, "totalCurrentAssets"),
+        "ppe_net":                    col(bal, "propertyPlantEquipmentNet"),
+        "goodwill":                   col(bal, "goodwill"),
+        "intangibles":                col(bal, "intangibleAssets"),
+        "other_long_term_assets":     col(bal, "otherNonCurrentAssets"),
+        "total_assets":               col(bal, "totalAssets"),
+        "accounts_payable":           col(bal, "accountPayables"),
+        "short_term_debt":            col(bal, "shortTermDebt"),
+        "other_current_liabilities":  col(bal, "otherCurrentLiabilities"),
+        "total_current_liabilities":  col(bal, "totalCurrentLiabilities"),
+        "long_term_debt":             col(bal, "longTermDebt"),
+        "other_long_term_liabilities":col(bal, "otherNonCurrentLiabilities"),
+        "total_liabilities":          col(bal, "totalLiabilities"),
+        "total_equity":               col(bal, "totalStockholdersEquity"),
+        "total_liab_and_equity":      col(bal, "totalLiabilitiesAndStockholdersEquity"),
+    }
+    cashflow = {
+        "net_income":              col(cf, "netIncome"),
+        "depreciation_amort":      col(cf, "depreciationAndAmortization"),
+        "stock_based_comp":        col(cf, "stockBasedCompensation"),
+        "working_capital_changes": col(cf, "changeInWorkingCapital"),
+        "other_operating":         col(cf, "otherWorkingCapital"),
+        "cash_from_operations":    col(cf, "netCashProvidedByOperatingActivities"),
+        "capex":                   col(cf, "capitalExpenditure"),
+        "acquisitions":            col(cf, "acquisitionsNet"),
+        "cash_from_investing":     col(cf, "netCashUsedForInvestingActivites"),
+        "debt_issuance_repayment": col(cf, "debtRepayment"),
+        "stock_buybacks":          col(cf, "commonStockRepurchased"),
+        "dividends_paid":          col(cf, "dividendsPaid"),
+        "cash_from_financing":     col(cf, "netCashUsedProvidedByFinancingActivities"),
+        "net_change_in_cash":      col(cf, "netChangeInCash"),
+        "free_cash_flow":          col(cf, "freeCashFlow"),
+    }
+    return {
+        "years": year_labels, "income_statement": income,
+        "balance_sheet": balance, "cash_flow": cashflow,
+        "currency": "USD", "units": "millions",
+        "source": "FMP API",
+        "valuation_snapshot": {},
+    }
+
+
+def _fetch_fmp(ticker, years, log_fn=None):
+    def log(m):
+        if log_fn: log_fn(m)
+    if not FMP_API_KEY:
+        return None
+    log("  → FMP: fetching statements …")
+    lim = years + 1
+    raw = {
+        "income":   _fmp_get(f"/v3/income-statement/{ticker}", {"limit": lim, "period": "annual"}) or [],
+        "balance":  _fmp_get(f"/v3/balance-sheet-statement/{ticker}", {"limit": lim, "period": "annual"}) or [],
+        "cashflow": _fmp_get(f"/v3/cash-flow-statement/{ticker}", {"limit": lim, "period": "annual"}) or [],
+    }
+    if not raw["income"]:
+        log("  ✗ FMP returned no data")
+        return None
+    log("  ✓ FMP data ready")
+    data = _normalise_fmp(raw, years)
+    # Add valuation
+    rtm = (_fmp_get(f"/v3/ratios-ttm/{ticker}") or [{}])[0]
+    km  = (_fmp_get(f"/v3/key-metrics-ttm/{ticker}") or [{}])[0]
+    data["valuation_snapshot"] = {
+        "pe_ttm":         _s(rtm.get("peRatioTTM")),
+        "pb":             _s(rtm.get("priceToBookRatioTTM")),
+        "ps":             _s(rtm.get("priceToSalesRatioTTM")),
+        "ev_ebitda":      _s(km.get("enterpriseValueOverEBITDATTM")),
+        "ev_revenue":     _s(km.get("evToSalesTTM")),
+        "fcf_yield":      _s(km.get("freeCashFlowYieldTTM")),
+        "dividend_yield": _s(rtm.get("dividendYieldTTM")),
+    }
+    return data
+
+
+# ── screener.in (Indian fallback) ────────────────────────────────────────────
+
+def _scrape_screener(name: str, log_fn=None) -> Optional[Dict]:
+    def log(m):
+        if log_fn: log_fn(m)
+    slug = re.sub(r"[^a-z0-9]+", "-", name.lower().strip()).strip("-")
+    for url in [f"https://www.screener.in/company/{slug}/",
+                f"https://www.screener.in/company/{slug.upper()}/"]:
+        try:
+            log(f"  → screener.in: {url}")
+            r = requests.get(url, timeout=REQUEST_TIMEOUT, headers=HEADERS)
+            if r.status_code == 200:
+                soup = BeautifulSoup(r.text, "lxml")
+                sections = {}
+                for sec_id, key in [("profit-loss","income"),("balance-sheet","balance"),
+                                     ("cash-flow","cashflow")]:
+                    sec = soup.find("section", {"id": sec_id})
+                    if sec:
+                        table = sec.find("table")
+                        if table:
+                            result = {}
+                            for row in table.find_all("tr"):
+                                cells = row.find_all(["td","th"])
+                                if len(cells) < 2: continue
+                                label = cells[0].get_text(strip=True)
+                                vals = []
+                                for c in cells[1:]:
+                                    t2 = c.get_text(strip=True).replace(",","").replace("+","")
+                                    try: vals.append(float(t2))
+                                    except: vals.append(None)
+                                if label: result[label] = vals
+                            sections[key] = result
+                            if "years" not in sections:
+                                hdr = table.find("tr")
+                                if hdr:
+                                    sections["years"] = [c.get_text(strip=True)
+                                                         for c in hdr.find_all(["th","td"])[1:]]
+                if sections:
+                    sections["source_url"] = url
+                    log("  ✓ screener.in scraped")
+                    return sections
+        except Exception as e:
+            log(f"  ✗ screener.in error: {e}")
+    return None
+
+
+def _normalise_screener(raw, years):
+    yr = raw.get("years", [])[:years]
+    n = len(yr)
+    inc = raw.get("income", {})
+    bal = raw.get("balance", {})
+    cf  = raw.get("cashflow", {})
+
+    def row(*keys):
+        for k in keys:
+            if k in inc: return inc[k][:n]
+            if k in bal: return bal[k][:n]
+            if k in cf:  return cf[k][:n]
+        return [None]*n
+
+    income = {
+        "revenue":            row("Revenue","Net Sales","Sales"),
+        "cost_of_revenue":    row("Expenses","Cost of Goods Sold"),
+        "gross_profit":       row("Gross Profit"),
+        "operating_expenses": [None]*n,
+        "operating_income":   row("Operating Profit","EBIT","PBDIT"),
+        "ebitda":             row("PBDIT","EBITDA"),
+        "depreciation_amort": row("Depreciation"),
+        "interest_expense":   row("Interest"),
+        "pretax_income":      row("Profit before tax","PBT"),
+        "tax_expense":        row("Tax"),
+        "net_income":         row("Net Profit","PAT"),
+        "diluted_eps":        row("EPS in Rs"),
+        "diluted_shares":     [None]*n,
+    }
+    balance = {
+        "cash_and_equivalents":       row("Cash Equivalents"),
+        "short_term_investments":     [None]*n,
+        "receivables":                [None]*n,
+        "inventory":                  [None]*n,
+        "other_current_assets":       [None]*n,
+        "total_current_assets":       row("Current Assets"),
+        "ppe_net":                    row("Fixed Assets"),
+        "goodwill":                   [None]*n,
+        "intangibles":                [None]*n,
+        "other_long_term_assets":     [None]*n,
+        "total_assets":               row("Total Assets","Balance Sheet Size"),
+        "accounts_payable":           [None]*n,
+        "short_term_debt":            row("Short Term Borrowing"),
+        "other_current_liabilities":  [None]*n,
+        "total_current_liabilities":  row("Current Liabilities"),
+        "long_term_debt":             row("Borrowings","Long Term Borrowing"),
+        "other_long_term_liabilities":[None]*n,
+        "total_liabilities":          row("Total Liabilities"),
+        "total_equity":               row("Equity Capital","Total Equity"),
+        "total_liab_and_equity":      row("Total Assets","Balance Sheet Size"),
+    }
+    cfo_vals = row("Cash from Operating Activity","Cash from Operations")
+    cap_vals = row("Fixed Assets Purchased","Capital Expenditure")
+    fcf_vals = [(c - abs(x)) if c is not None and x is not None else None
+                for c, x in zip(cfo_vals, cap_vals)]
+    cashflow = {
+        "net_income":              income["net_income"],
+        "depreciation_amort":      income["depreciation_amort"],
+        "stock_based_comp":        [None]*n,
+        "working_capital_changes": [None]*n,
+        "other_operating":         [None]*n,
+        "cash_from_operations":    cfo_vals,
+        "capex":                   cap_vals,
+        "acquisitions":            [None]*n,
+        "cash_from_investing":     row("Cash from Investing Activity"),
+        "debt_issuance_repayment": [None]*n,
+        "stock_buybacks":          [None]*n,
+        "dividends_paid":          row("Dividend Amount"),
+        "cash_from_financing":     row("Cash from Financing Activity"),
+        "net_change_in_cash":      row("Net Cash Flow"),
+        "free_cash_flow":          fcf_vals,
+    }
+    return {
+        "years": yr, "income_statement": income, "balance_sheet": balance, "cash_flow": cashflow,
+        "currency": "INR", "units": "crores",
+        "source": f"screener.in ({raw.get('source_url','')})",
+        "valuation_snapshot": {},
+    }
+
+
+# ── Peer snapshot ─────────────────────────────────────────────────────────────
+
+def fetch_peer_snapshot(ticker: str) -> Optional[Dict]:
+    try:
+        import yfinance as yf
+        t = yf.Ticker(ticker)
+        info = t.info
+        if not info.get("longName"): return None
+        fin = t.financials
+        rev = fin.loc["Total Revenue"].iloc[0] if fin is not None and "Total Revenue" in fin.index else None
+        ratios_ttm = (_fmp_get(f"/v3/ratios-ttm/{ticker}") or [{}])[0]
+        return {
+            "name": info.get("longName", ticker),
+            "ticker": ticker,
+            "rationale": f"Industry peer ({info.get('industry','')})",
+            "latest_year": "",
+            "currency": info.get("currency","INR"),
+            "units": "actuals",
+            "revenue": _s(rev),
+            "gross_margin": _s(info.get("grossMargins")),
+            "operating_margin": _s(info.get("operatingMargins")),
+            "net_margin": _s(info.get("profitMargins")),
+            "roe": _s(info.get("returnOnEquity")),
+            "roic": _s(ratios_ttm.get("returnOnCapitalEmployedTTM")),
+            "debt_to_equity": _s(info.get("debtToEquity")),
+            "current_ratio": _s(info.get("currentRatio")),
+            "fcf_margin": None,
+            "revenue_growth_3y_cagr": _s(info.get("revenueGrowth")),
+            "pe_ttm": _s(info.get("trailingPE")),
+            "ev_ebitda": _s(info.get("enterpriseToEbitda")),
+        }
+    except Exception:
+        return None
+
+
+def fetch_valuation(ticker: str) -> Dict:
+    try:
+        import yfinance as yf
+        info = yf.Ticker(ticker).info
+        return {
+            "pe_ttm":         _s(info.get("trailingPE")),
+            "pb":             _s(info.get("priceToBook")),
+            "ps":             _s(info.get("priceToSalesTrailing12Months")),
+            "ev_ebitda":      _s(info.get("enterpriseToEbitda")),
+            "ev_revenue":     _s(info.get("enterpriseToRevenue")),
+            "fcf_yield":      None,
+            "dividend_yield": _s(info.get("dividendYield")),
+        }
+    except Exception:
+        return {}
+
+
+# ── Main entry ────────────────────────────────────────────────────────────────
+
+def fetch_all(meta: CompanyMeta, years: int = DEFAULT_YEARS,
+              force_refresh: bool = False, log_fn=None) -> Dict:
+    def log(m):
+        if log_fn: log_fn(m)
+
+    if not meta.is_listed:
+        msg = (f"'{meta.name}' is unlisted/private. Public data not available. "
+               "Try the exact BSE/NSE ticker.")
+        log(f"  ⚠ {msg}")
+        return {"warnings": [msg], "years": [], "income_statement": {},
+                "balance_sheet": {}, "cash_flow": {}}
+
+    ticker = meta.ticker
+    cache_key = f"full_{years}yr"
+    if not force_refresh:
+        cached = get_cached(ticker, cache_key)
+        if cached:
+            log(f"  ✓ Loaded cached data for {ticker}")
+            return cached
+
+    warnings = []
+    result = None
+
+    # 1. yfinance (primary — free, excellent Indian coverage)
+    log(f"Fetching data for {meta.name} ({ticker}) …")
+    result = _fetch_yfinance(ticker, years, log_fn)
+
+    # 2. FMP (secondary — global companies)
+    if result is None and FMP_API_KEY:
+        result = _fetch_fmp(ticker, years, log_fn)
+
+    # 3. screener.in (Indian fallback)
+    if result is None and meta.currency == "INR":
+        log("  → Trying screener.in …")
+        scraped = _scrape_screener(meta.name, log_fn)
+        if scraped:
+            result = _normalise_screener(scraped, years)
+            warnings.append("Data from screener.in (web scrape). Verify against company filings.")
+
+    if result is None:
+        msg = (f"Could not fetch data for '{meta.name}' ({ticker}). "
+               "Check ticker, or the company may have limited public data coverage.")
+        log(f"  ⚠ {msg}")
+        return {"warnings": [msg], "years": [], "income_statement": {},
+                "balance_sheet": {}, "cash_flow": {}}
+
+    result["warnings"] = warnings
+    result.setdefault("currency", meta.currency)
+    set_cache(ticker, cache_key, result)
+    log("  ✓ Data cached for 7 days")
+    return result

pipeline/google_login.py

@@ -0,0 +1,182 @@
+"""
+pipeline/google_login.py — Google OAuth login for Gemini API access.
+
+Uses google-auth-oauthlib InstalledAppFlow to authenticate via browser.
+After login, the access token is used directly with the Generative Language REST API
+so the user NEVER needs to touch an API key manually.
+
+Credentials are stored in  storage/google_token.json  and auto-refreshed.
+"""
+from __future__ import annotations
+import json, time, threading
+from pathlib import Path
+from typing import Optional, Tuple
+
+# Where we persist the user's OAuth token
+_TOKEN_FILE = Path(__file__).parent.parent / "storage" / "google_token.json"
+
+# Gemini generative language scope
+_SCOPES = ["https://www.googleapis.com/auth/generative-language"]
+
+# ── Bundled OAuth client credentials ─────────────────────────────────────────
+# These are "Desktop app" / "Installed app" OAuth 2.0 credentials.
+# They are intentionally public-facing (like VS Code's GitHub OAuth client).
+# They allow users to log in with Google; they cannot access anything beyond
+# what the user explicitly authorises. No secrets are exposed.
+_CLIENT_CONFIG = {
+    "installed": {
+        "client_id":     "764086051850-6qr4p6gpi6hn506pt8ejuq83di341hur.apps.googleusercontent.com",
+        "client_secret": "d-FL95Q19q7MQmFpd7hHD0Ty",
+        "auth_uri":      "https://accounts.google.com/o/oauth2/auth",
+        "token_uri":     "https://oauth2.googleapis.com/token",
+        "redirect_uris": ["urn:ietf:wg:oauth:2.0:oob", "http://localhost"],
+    }
+}
+
+
+# ── Core OAuth helpers ────────────────────────────────────────────────────────
+
+def _load_token() -> Optional[dict]:
+    if _TOKEN_FILE.exists():
+        try:
+            return json.loads(_TOKEN_FILE.read_text(encoding="utf-8"))
+        except Exception:
+            pass
+    return None
+
+
+def _save_token(token_data: dict):
+    _TOKEN_FILE.parent.mkdir(parents=True, exist_ok=True)
+    _TOKEN_FILE.write_text(json.dumps(token_data, indent=2), encoding="utf-8")
+
+
+def _refresh_token(token_data: dict) -> Tuple[bool, dict]:
+    """Use the refresh_token to get a new access_token."""
+    try:
+        import requests
+        r = requests.post(
+            _CLIENT_CONFIG["installed"]["token_uri"],
+            data={
+                "client_id":     _CLIENT_CONFIG["installed"]["client_id"],
+                "client_secret": _CLIENT_CONFIG["installed"]["client_secret"],
+                "refresh_token": token_data.get("refresh_token", ""),
+                "grant_type":    "refresh_token",
+            },
+            timeout=15,
+        )
+        resp = r.json()
+        if "access_token" in resp:
+            token_data["access_token"] = resp["access_token"]
+            token_data["expires_at"]   = time.time() + resp.get("expires_in", 3600)
+            _save_token(token_data)
+            return True, token_data
+        return False, token_data
+    except Exception as e:
+        return False, token_data
+
+
+def get_valid_token() -> Optional[str]:
+    """Return a valid access_token, refreshing if needed. None if not logged in."""
+    token_data = _load_token()
+    if not token_data:
+        return None
+    if time.time() > token_data.get("expires_at", 0) - 60:
+        ok, token_data = _refresh_token(token_data)
+        if not ok:
+            return None
+    return token_data.get("access_token")
+
+
+def is_logged_in() -> bool:
+    return get_valid_token() is not None
+
+
+def logout():
+    if _TOKEN_FILE.exists():
+        _TOKEN_FILE.unlink()
+
+
+# ── Browser login flow ────────────────────────────────────────────────────────
+
+def login_with_browser(log_fn=None) -> Tuple[bool, str]:
+    """
+    Launch Google OAuth in the default browser.
+    Blocks until auth completes or fails.
+    Returns (success, message).
+    """
+    def log(m):
+        if log_fn: log_fn(m)
+    try:
+        from google_auth_oauthlib.flow import InstalledAppFlow
+    except ImportError:
+        return False, (
+            "google-auth-oauthlib not installed.\n"
+            "Run:  pip install google-auth-oauthlib"
+        )
+
+    try:
+        log("Opening browser for Google login…")
+        flow = InstalledAppFlow.from_client_config(_CLIENT_CONFIG, scopes=_SCOPES)
+        # Try local server first (most reliable), fallback to console input
+        try:
+            creds = flow.run_local_server(port=0, open_browser=True)
+        except Exception:
+            creds = flow.run_console()
+
+        token_data = {
+            "access_token":  creds.token,
+            "refresh_token": creds.refresh_token,
+            "expires_at":    creds.expiry.timestamp() if creds.expiry else time.time() + 3600,
+        }
+        _save_token(token_data)
+        log("✓ Google login successful — token saved")
+        return True, "Logged in successfully ✓"
+    except Exception as e:
+        return False, f"Login failed: {e}"
+
+
+# ── Gemini call via REST (no API key needed when using OAuth token) ───────────
+
+def gemini_generate_oauth(prompt: str, model: str = "gemini-2.0-flash") -> str:
+    """Call Gemini API using the stored OAuth token (no API key)."""
+    token = get_valid_token()
+    if not token:
+        raise RuntimeError("Not logged in to Google. Please sign in via Settings.")
+    try:
+        import requests
+        url = (f"https://generativelanguage.googleapis.com/v1beta/models/"
+               f"{model}:generateContent")
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Content-Type":  "application/json",
+        }
+        body = {
+            "contents": [{"parts": [{"text": prompt}]}],
+            "generationConfig": {"temperature": 0.2, "maxOutputTokens": 1024},
+        }
+        r = requests.post(url, headers=headers, json=body, timeout=60)
+        r.raise_for_status()
+        candidates = r.json().get("candidates", [])
+        if candidates:
+            parts = candidates[0].get("content", {}).get("parts", [])
+            if parts:
+                return parts[0].get("text", "").strip()
+        return "[No response from Gemini]"
+    except Exception as e:
+        raise RuntimeError(f"Gemini OAuth call failed: {e}")
+
+
+# ── Quick validity check ──────────────────────────────────────────────────────
+
+def validate_google_login() -> Tuple[bool, str]:
+    """Test if the stored Google token works with Gemini."""
+    token = get_valid_token()
+    if not token:
+        return False, "Not signed in. Click 'Sign in with Google'."
+    try:
+        result = gemini_generate_oauth("Reply with the single word: OK", model="gemini-2.0-flash")
+        if "OK" in result or len(result) > 0:
+            return True, "Google login active — Gemini working ✓"
+        return True, "Google login active ✓"
+    except Exception as e:
+        return False, f"Token expired or invalid: {e}"

pipeline/key_validator.py

@@ -0,0 +1,160 @@
+"""
+pipeline/key_validator.py — Validate API keys before running analysis.
+"""
+from __future__ import annotations
+import sys
+from pathlib import Path
+from typing import Tuple
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+
+def validate_fmp(key: str) -> Tuple[bool, str]:
+    """Test FMP key with a lightweight profile call."""
+    if not key or key.strip() in ("", "your_fmp_key_here"):
+        return False, "No key entered."
+    try:
+        import requests
+        r = requests.get(
+            "https://financialmodelingprep.com/api/v3/profile/AAPL",
+            params={"apikey": key.strip()},
+            timeout=10,
+        )
+        data = r.json()
+        if isinstance(data, list) and data and data[0].get("symbol"):
+            return True, f"Valid ✓  (plan: {data[0].get('exchange','FMP')})"
+        if isinstance(data, dict) and "Error Message" in data:
+            return False, f"Invalid key: {data['Error Message']}"
+        return False, "Unexpected response — key may be invalid."
+    except Exception as e:
+        return False, f"Connection error: {e}"
+
+
+def validate_gemini(key: str) -> Tuple[bool, str]:
+    """Test Gemini key with a minimal generate call."""
+    if not key or key.strip() in ("", "your_gemini_key_here"):
+        return False, "No key entered."
+    try:
+        # Try new google.genai SDK first
+        from google import genai
+        client = genai.Client(api_key=key.strip())
+        resp = client.models.generate_content(
+            model="gemini-2.0-flash",
+            contents="Reply with the single word: OK",
+        )
+        text = resp.text.strip() if resp.text else ""
+        return True, f"Valid ✓  (response: '{text[:20]}')"
+    except Exception as e1:
+        # Fallback to old SDK
+        try:
+            import google.generativeai as genai_old
+            genai_old.configure(api_key=key.strip())
+            model = genai_old.GenerativeModel("gemini-1.5-flash")
+            resp = model.generate_content("Reply with the single word: OK")
+            return True, f"Valid ✓  (response: '{resp.text.strip()[:20]}')"
+        except Exception as e2:
+            msg = str(e1)
+            if "API_KEY_INVALID" in msg or "invalid" in msg.lower():
+                return False, "Invalid API key. Check and re-enter."
+            if "quota" in msg.lower():
+                return True, "Key valid but quota exceeded — will still work."
+            return False, f"Error: {msg[:80]}"
+
+
+def validate_claude(key: str) -> Tuple[bool, str]:
+    """Test Claude key with a minimal message."""
+    if not key or key.strip() in ("", "your_claude_key_here"):
+        return False, "No key entered."
+    try:
+        import anthropic
+        client = anthropic.Anthropic(api_key=key.strip())
+        msg = client.messages.create(
+            model="claude-3-5-haiku-20241022",
+            max_tokens=10,
+            messages=[{"role": "user", "content": "Reply with the single word: OK"}],
+        )
+        text = msg.content[0].text.strip() if msg.content else ""
+        return True, f"Valid ✓  (response: '{text[:20]}')"
+    except Exception as e:
+        msg = str(e)
+        if "authentication" in msg.lower() or "401" in msg or "invalid" in msg.lower():
+            return False, "Invalid API key. Check and re-enter."
+        if "quota" in msg.lower() or "credit" in msg.lower():
+            return True, "Key valid but credit exhausted."
+        return False, f"Error: {msg[:80]}"
+
+
+def validate_openai(key: str) -> Tuple[bool, str]:
+    """Test OpenAI key with a minimal chat completion."""
+    if not key or key.strip() in ("", "your_openai_key_here"):
+        return False, "No key entered."
+    try:
+        from openai import OpenAI
+        client = OpenAI(api_key=key.strip())
+        resp = client.chat.completions.create(
+            model="gpt-4o-mini",
+            messages=[{"role": "user", "content": "Reply with the single word: OK"}],
+            max_tokens=5,
+        )
+        text = resp.choices[0].message.content.strip() if resp.choices else ""
+        return True, f"Valid ✓  (response: '{text[:20]}')"
+    except Exception as e:
+        msg = str(e)
+        if "401" in msg or "Incorrect API key" in msg or "invalid_api_key" in msg:
+            return False, "Invalid API key. Check and re-enter."
+        if "quota" in msg.lower() or "insufficient" in msg.lower():
+            return True, "Key valid but quota/credit exhausted."
+        return False, f"Error: {msg[:80]}"
+
+
+def validate_groq(key: str) -> tuple:
+    """Test Groq key with a minimal chat completion (free API)."""
+    if not key or key.strip() in ("", "your_groq_key_here"):
+        return False, "No key entered."
+    try:
+        from openai import OpenAI
+        client = OpenAI(
+            api_key=key.strip(),
+            base_url="https://api.groq.com/openai/v1",
+        )
+        resp = client.chat.completions.create(
+            model="llama-3.3-70b-versatile",
+            messages=[{"role": "user", "content": "Reply with the single word: OK"}],
+            max_tokens=5,
+        )
+        text = resp.choices[0].message.content.strip() if resp.choices else ""
+        return True, f"Valid ✓  (Llama 3.3 70B, response: '{text[:20]}')"
+    except Exception as e:
+        msg = str(e)
+        if "401" in msg or "invalid_api_key" in msg.lower() or "unauthorized" in msg.lower():
+            return False, "Invalid Groq API key. Check and re-enter."
+        if "quota" in msg.lower() or "rate" in msg.lower():
+            return True, "Key valid but rate-limited — try again shortly."
+        return False, f"Error: {msg[:80]}"
+
+
+def check_any_ai_model(gemini_key: str = "", claude_key: str = "", openai_key: str = "", groq_key: str = "") -> tuple:
+    """Quickly check if at least one AI model is usable."""
+    checks = [
+        ("groq",   groq_key,   validate_groq),
+        ("gemini", gemini_key, validate_gemini),
+        ("claude", claude_key, validate_claude),
+        ("openai", openai_key, validate_openai),
+    ]
+    for name, key, fn in checks:
+        if key and key.strip():
+            ok, msg = fn(key)
+            if ok:
+                return True, f"{name.capitalize()}: {msg}"
+
+    return False, (
+        "No working AI model key found.\n\n"
+        "Free options (no credit card needed):\n"
+        "  • Groq (Llama 3.3 70B) → console.groq.com\n"
+        "  • Gemini → aistudio.google.com\n\n"
+        "Paid options:\n"
+        "  • Claude → console.anthropic.com\n"
+        "  • ChatGPT → platform.openai.com/api-keys\n\n"
+        "OR uncheck all AI models to run data-only analysis."
+    )
+

pipeline/peer_selector.py

@@ -0,0 +1,128 @@
+"""
+pipeline/peer_selector.py — Automatically select 3-5 peer companies.
+
+Uses FMP's peers endpoint first, then falls back to industry-based hardcoded peers.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import List, Dict, Optional
+
+import requests
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from config import FMP_API_KEY, FMP_BASE, REQUEST_TIMEOUT
+from pipeline.resolver import CompanyMeta
+from pipeline.fetcher import fetch_peer_snapshot, _fmp_get
+
+# yfinance-based peer fetch (no API key needed)
+def _yf_peers_from_industry(meta: CompanyMeta) -> list:
+    """Return peer tickers based on industry using hardcoded maps."""
+    return []  # handled by INDIAN_PEERS / GLOBAL_PEERS maps below
+
+# ── Hardcoded industry → peer tickers (Indian + Global) ──────────────────────
+
+INDIAN_PEERS: Dict[str, List[str]] = {
+    "IT Services": ["TCS.NS", "INFY.NS", "WIPRO.NS", "HCLTECH.NS", "TECHM.NS"],
+    "Information Technology": ["TCS.NS", "INFY.NS", "WIPRO.NS", "HCLTECH.NS", "LTIM.NS"],
+    "Banking": ["HDFCBANK.NS", "ICICIBANK.NS", "AXISBANK.NS", "SBIN.NS", "KOTAKBANK.NS"],
+    "Finance": ["BAJFINANCE.NS", "BAJAJFINSV.NS", "HDFCAMC.NS", "MUTHOOTFIN.NS"],
+    "Pharmaceuticals": ["SUNPHARMA.NS", "CIPLA.NS", "DRREDDY.NS", "DIVISLAB.NS", "AUROPHARMA.NS"],
+    "Automobile": ["MARUTI.NS", "TATAMOTORS.NS", "M&M.NS", "HEROMOTOCO.NS", "BAJAJ-AUTO.NS"],
+    "FMCG": ["HINDUNILVR.NS", "ITC.NS", "NESTLEIND.NS", "DABUR.NS", "MARICO.NS"],
+    "Cement": ["ULTRACEMCO.NS", "SHREECEM.NS", "AMBUJACEM.NS", "ACC.NS", "GRASIM.NS"],
+    "Steel": ["TATASTEEL.NS", "JSWSTEEL.NS", "SAIL.NS", "HINDALCO.NS", "VEDL.NS"],
+    "Telecom": ["BHARTIARTL.NS", "RELIANCE.NS", "IDEA.NS"],
+    "Oil & Gas": ["RELIANCE.NS", "ONGC.NS", "IOC.NS", "BPCL.NS", "HINDPETRO.NS"],
+    "Power": ["NTPC.NS", "POWERGRID.NS", "ADANIGREEN.NS", "TATAPOWER.NS", "CESC.NS"],
+    "Real Estate": ["DLF.NS", "GODREJPROP.NS", "OBEROIRLTY.NS", "PHOENIXLTD.NS"],
+    "Consumer Electronics": ["DIXON.NS", "VOLTAS.NS", "BLUESTARCO.NS", "HAVELLS.NS"],
+    "Insurance": ["SBILIFE.NS", "HDFCLIFE.NS", "ICICIPRULI.NS", "LICI.NS"],
+    "Retail": ["DMART.NS", "TRENT.NS", "SHOPPERSSTOP.NS", "VMART.NS"],
+    "Paints": ["ASIANPAINT.NS", "BERGEPAINT.NS", "KANSAINER.NS", "INDIGO.NS"],
+}
+
+GLOBAL_PEERS: Dict[str, List[str]] = {
+    "Technology": ["AAPL", "MSFT", "GOOGL", "META", "AMZN"],
+    "Semiconductors": ["NVDA", "AMD", "INTC", "QCOM", "AVGO"],
+    "Cloud": ["MSFT", "AMZN", "GOOGL", "ORCL", "CRM"],
+    "EV/Auto": ["TSLA", "GM", "F", "TM", "STLA"],
+    "Banking": ["JPM", "BAC", "WFC", "C", "GS"],
+    "Pharma": ["JNJ", "PFE", "MRK", "ABBV", "LLY"],
+    "FMCG": ["PG", "KO", "PEP", "UL", "NESN"],
+    "Oil & Gas": ["XOM", "CVX", "SHEL", "BP", "TTE"],
+    "Retail": ["WMT", "AMZN", "COST", "TGT", "HD"],
+    "Telecom": ["VZ", "T", "TMUS", "VOD", "ORAN"],
+}
+
+
+def _fmp_peers(ticker: str) -> List[str]:
+    """Use FMP's stock-peers endpoint."""
+    data = _fmp_get(f"/v4/stock_peers", {"symbol": ticker})
+    if data and isinstance(data, list) and data[0].get("peersList"):
+        return data[0]["peersList"][:5]
+    return []
+
+
+def select_peers(
+    meta: CompanyMeta,
+    max_peers: int = 4,
+    log_fn=None,
+) -> List[Dict]:
+    """
+    Select peer companies for benchmarking.
+    Returns list of peer snapshot dicts (same format as peers in the JSON schema).
+    """
+    def log(msg):
+        if log_fn:
+            log_fn(msg)
+
+    ticker = meta.ticker
+    peers_out: List[Dict] = []
+
+    log(f"Selecting peers for {meta.name} ({meta.industry}) …")
+
+    # 1. Try FMP peers endpoint
+    peer_tickers = []
+    if FMP_API_KEY and meta.is_listed and ticker != "UNLISTED":
+        peer_tickers = _fmp_peers(ticker)
+        if peer_tickers:
+            log(f"  → FMP suggested {len(peer_tickers)} peers")
+
+    # 2. Fallback to hardcoded industry map
+    if not peer_tickers:
+        industry = meta.industry or meta.sector or ""
+        # Check Indian peers first
+        for key, tickers in INDIAN_PEERS.items():
+            if key.lower() in industry.lower() or industry.lower() in key.lower():
+                peer_tickers = [t for t in tickers if t.upper() != ticker.upper()][:max_peers]
+                log(f"  → Using hardcoded Indian peers for '{key}'")
+                break
+        # Check global peers
+        if not peer_tickers:
+            for key, tickers in GLOBAL_PEERS.items():
+                if key.lower() in industry.lower() or industry.lower() in key.lower():
+                    peer_tickers = [t for t in tickers if t.upper() != ticker.upper()][:max_peers]
+                    log(f"  → Using hardcoded global peers for '{key}'")
+                    break
+
+    # Remove self
+    peer_tickers = [t for t in peer_tickers if t.upper() != ticker.upper()][:max_peers]
+
+    if not peer_tickers:
+        log("  ⚠ No peers found. Peer comparison section will be skipped.")
+        return []
+
+    # 3. Fetch snapshots for each peer
+    for pt in peer_tickers:
+        log(f"  → Fetching peer data: {pt} …")
+        snap = fetch_peer_snapshot(pt)
+        if snap:
+            peers_out.append(snap)
+            log(f"    ✓ {snap['name']} ({pt})")
+        else:
+            log(f"    ✗ Could not fetch {pt}")
+
+    log(f"  ✓ {len(peers_out)} peers ready")
+    return peers_out

pipeline/resolver.py

@@ -0,0 +1,346 @@
+"""
+pipeline/resolver.py — Resolve a company name or ticker to structured metadata.
+
+Source priority:
+  1. yfinance (free, no key, excellent Indian stock support)
+  2. FMP API (if key available)
+  3. Mark as unlisted with clear message
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from config import FMP_API_KEY, FMP_BASE, REQUEST_TIMEOUT
+
+import requests
+
+
+# ── CompanyMeta ───────────────────────────────────────────────────────────────
+
+class CompanyMeta:
+    def __init__(self, name, ticker, exchange, currency, sector, industry,
+                 country, description, website, mkt_cap, share_price, is_listed,
+                 source_note="", fiscal_year_end="March"):
+        self.name = name
+        self.ticker = ticker
+        self.exchange = exchange
+        self.currency = currency
+        self.sector = sector
+        self.industry = industry
+        self.country = country
+        self.description = description
+        self.website = website
+        self.mkt_cap = mkt_cap
+        self.share_price = share_price
+        self.is_listed = is_listed
+        self.source_note = source_note
+        self.fiscal_year_end = fiscal_year_end
+
+    def to_dict(self):
+        return self.__dict__.copy()
+
+
+# ── Indian company name → NSE ticker map ─────────────────────────────────────
+
+INDIAN_TICKERS = {
+    # IT
+    "tcs": "TCS.NS", "tata consultancy": "TCS.NS", "tata consultancy services": "TCS.NS",
+    "infosys": "INFY.NS", "infy": "INFY.NS",
+    "wipro": "WIPRO.NS",
+    "hcl": "HCLTECH.NS", "hcl tech": "HCLTECH.NS", "hcl technologies": "HCLTECH.NS",
+    "tech mahindra": "TECHM.NS", "techm": "TECHM.NS",
+    "ltimindtree": "LTIM.NS", "lti mindtree": "LTIM.NS",
+    "mphasis": "MPHASIS.NS",
+    "persistent": "PERSISTENT.NS",
+    "coforge": "COFORGE.NS",
+    # Banking
+    "hdfc bank": "HDFCBANK.NS", "hdfcbank": "HDFCBANK.NS",
+    "icici bank": "ICICIBANK.NS", "icicibank": "ICICIBANK.NS",
+    "axis bank": "AXISBANK.NS", "axisbank": "AXISBANK.NS",
+    "sbi": "SBIN.NS", "state bank": "SBIN.NS", "state bank of india": "SBIN.NS",
+    "kotak": "KOTAKBANK.NS", "kotak bank": "KOTAKBANK.NS", "kotak mahindra bank": "KOTAKBANK.NS",
+    "yes bank": "YESBANK.NS",
+    "indusind bank": "INDUSINDBK.NS",
+    "bank of baroda": "BANKBARODA.NS",
+    "pnb": "PNB.NS", "punjab national bank": "PNB.NS",
+    "canara bank": "CANARABANK.NS",
+    # Conglomerates / Energy
+    "reliance": "RELIANCE.NS", "reliance industries": "RELIANCE.NS", "ril": "RELIANCE.NS",
+    "tata": "TATAMOTORS.NS",
+    "adani enterprises": "ADANIENT.NS", "adani ports": "ADANIPORTS.NS",
+    "adani green": "ADANIGREEN.NS", "adani total gas": "ATGL.NS",
+    "ongc": "ONGC.NS",
+    "oil and natural gas": "ONGC.NS",
+    "ioc": "IOC.NS", "indian oil": "IOC.NS",
+    "bpcl": "BPCL.NS", "bharat petroleum": "BPCL.NS",
+    "coal india": "COALINDIA.NS",
+    # FMCG
+    "hindustan unilever": "HINDUNILVR.NS", "hul": "HINDUNILVR.NS",
+    "itc": "ITC.NS",
+    "nestle india": "NESTLEIND.NS", "nestle": "NESTLEIND.NS",
+    "britannia": "BRITANNIA.NS",
+    "dabur": "DABUR.NS",
+    "marico": "MARICO.NS",
+    "godrej consumer": "GODREJCP.NS", "godrej": "GODREJCP.NS",
+    "emami": "EMAMILTD.NS",
+    # Pharma
+    "sun pharma": "SUNPHARMA.NS", "sun pharmaceutical": "SUNPHARMA.NS",
+    "cipla": "CIPLA.NS",
+    "dr reddy": "DRREDDY.NS", "dr reddys": "DRREDDY.NS",
+    "divi's labs": "DIVISLAB.NS", "divis": "DIVISLAB.NS",
+    "aurobindo": "AUROPHARMA.NS",
+    "lupin": "LUPIN.NS",
+    "torrent pharma": "TORNTPHARM.NS",
+    # Auto
+    "maruti": "MARUTI.NS", "maruti suzuki": "MARUTI.NS",
+    "tata motors": "TATAMOTORS.NS",
+    "m&m": "M&M.NS", "mahindra": "M&M.NS", "mahindra and mahindra": "M&M.NS",
+    "hero motocorp": "HEROMOTOCO.NS", "hero": "HEROMOTOCO.NS",
+    "bajaj auto": "BAJAJ-AUTO.NS",
+    "eicher": "EICHERMOT.NS", "royal enfield": "EICHERMOT.NS",
+    "tvs motor": "TVSMOTOR.NS",
+    # Finance (non-bank)
+    "bajaj finance": "BAJFINANCE.NS",
+    "bajaj finserv": "BAJAJFINSV.NS",
+    "hdfc life": "HDFCLIFE.NS",
+    "sbi life": "SBILIFE.NS",
+    "lic": "LICI.NS",
+    "icici prudential": "ICICIPRULI.NS",
+    "muthoot": "MUTHOOTFIN.NS",
+    # Infra / Utilities
+    "larsen": "LT.NS", "l&t": "LT.NS", "larsen and toubro": "LT.NS",
+    "ntpc": "NTPC.NS",
+    "power grid": "POWERGRID.NS",
+    "tata power": "TATAPOWER.NS",
+    "adani power": "ADANIPOWER.NS",
+    # Cement / Materials
+    "ultratech": "ULTRACEMCO.NS", "ultratech cement": "ULTRACEMCO.NS",
+    "shree cement": "SHREECEM.NS",
+    "ambuja": "AMBUJACEM.NS",
+    "acc": "ACC.NS",
+    "grasim": "GRASIM.NS",
+    "tata steel": "TATASTEEL.NS",
+    "jsw steel": "JSWSTEEL.NS",
+    "hindalco": "HINDALCO.NS",
+    "vedanta": "VEDL.NS",
+    "jspl": "JINDALSTEL.NS",
+    # Paints / Consumer
+    "asian paints": "ASIANPAINT.NS",
+    "berger paints": "BERGEPAINT.NS",
+    "pidilite": "PIDILITIND.NS",
+    "havells": "HAVELLS.NS",
+    "voltas": "VOLTAS.NS",
+    "titan": "TITAN.NS",
+    "tanishq": "TITAN.NS",
+    # Retail / Consumer
+    "dmart": "DMART.NS", "avenue supermarts": "DMART.NS",
+    "trent": "TRENT.NS",
+    "zomato": "ZOMATO.NS",
+    "nykaa": "NYKAA.NS",
+    "policybazaar": "POLICYBZR.NS",
+    # Telecom
+    "airtel": "BHARTIARTL.NS", "bharti airtel": "BHARTIARTL.NS",
+    "jio": "RELIANCE.NS",  # Jio is part of Reliance
+    # IT Infrastructure
+    "hcl infosystems": "HCLISEC.NS",
+    "dixon": "DIXON.NS",
+}
+
+
+def _guess_ticker(query: str) -> Optional[str]:
+    """Try to find an Indian NSE ticker for a given name/query."""
+    q = query.lower().strip()
+    # Exact match
+    if q in INDIAN_TICKERS:
+        return INDIAN_TICKERS[q]
+    # Partial match
+    for key, ticker in INDIAN_TICKERS.items():
+        if key in q or q in key:
+            return ticker
+    return None
+
+
+# ── yfinance resolution ───────────────────────────────────────────────────────
+
+def _yf_resolve(ticker: str, log_fn=None) -> Optional[CompanyMeta]:
+    """Try to resolve a ticker via yfinance. Returns CompanyMeta or None."""
+    def log(msg):
+        if log_fn: log_fn(msg)
+    try:
+        import yfinance as yf
+        t = yf.Ticker(ticker)
+        info = t.info
+        name = info.get("longName") or info.get("shortName", "")
+        if not name:
+            return None
+        exchange_code = info.get("exchange", "")
+        currency = info.get("currency", "INR")
+        exchange_map = {
+            "NSI": "NSE (India)", "BSE": "BSE (India)",
+            "NMS": "NASDAQ (USA)", "NYQ": "NYSE (USA)",
+            "LSE": "LSE (UK)",
+        }
+        exchange_display = exchange_map.get(exchange_code, exchange_code or "Unknown")
+        country = info.get("country", "India")
+        # Fiscal year end
+        fy_end = "March" if currency == "INR" else "December"
+
+        log(f"  ✓ yfinance: {name} | {ticker} | {exchange_display}")
+        return CompanyMeta(
+            name=name,
+            ticker=ticker,
+            exchange=exchange_display,
+            currency=currency,
+            sector=info.get("sector", ""),
+            industry=info.get("industry", ""),
+            country=country,
+            description=info.get("longBusinessSummary", ""),
+            website=info.get("website", ""),
+            mkt_cap=info.get("marketCap"),
+            share_price=info.get("currentPrice") or info.get("regularMarketPrice"),
+            is_listed=True,
+            source_note="Data sourced from Yahoo Finance (yfinance).",
+            fiscal_year_end=fy_end,
+        )
+    except Exception as e:
+        log(f"  ✗ yfinance failed for {ticker}: {e}")
+        return None
+
+
+# ── FMP resolution ────────────────────────────────────────────────────────────
+
+def _fmp_get(path: str, params: dict | None = None):
+    if not FMP_API_KEY:
+        return None
+    url = f"{FMP_BASE}{path}"
+    p = {"apikey": FMP_API_KEY}
+    if params: p.update(params)
+    try:
+        r = requests.get(url, params=p, timeout=REQUEST_TIMEOUT)
+        r.raise_for_status()
+        return r.json()
+    except Exception:
+        return None
+
+
+def _fmp_resolve(query: str, log_fn=None) -> Optional[CompanyMeta]:
+    """Try FMP search for global companies."""
+    def log(msg):
+        if log_fn: log_fn(msg)
+    if not FMP_API_KEY:
+        return None
+    log("  → Searching FMP …")
+    # Direct profile
+    profile = _fmp_get(f"/v3/profile/{query.upper()}")
+    if not (profile and isinstance(profile, list) and profile[0].get("symbol")):
+        # Search
+        results = _fmp_get("/v3/search", {"query": query, "limit": 5})
+        if results:
+            best = results[0]
+            profile = _fmp_get(f"/v3/profile/{best['symbol']}")
+    if not (profile and isinstance(profile, list)):
+        return None
+    p = profile[0]
+    if not p.get("companyName"):
+        return None
+    exchange = p.get("exchange", "") or p.get("exchangeShortName", "")
+    exchange_map = {"NSE":"NSE (India)","BSE":"BSE (India)","NASDAQ":"NASDAQ (USA)","NYSE":"NYSE (USA)"}
+    log(f"  ✓ FMP: {p.get('companyName')} ({p.get('symbol')})")
+    return CompanyMeta(
+        name=p.get("companyName",""),
+        ticker=p.get("symbol",""),
+        exchange=exchange_map.get(exchange, exchange),
+        currency=p.get("currency","USD"),
+        sector=p.get("sector",""),
+        industry=p.get("industry",""),
+        country=p.get("country",""),
+        description=p.get("description",""),
+        website=p.get("website",""),
+        mkt_cap=p.get("mktCap"),
+        share_price=p.get("price"),
+        is_listed=True,
+        source_note="Data sourced from FMP.",
+        fiscal_year_end="December",
+    )
+
+
+# ── yfinance search by company name ──────────────────────────────────────────
+
+def _yf_search(query: str, log_fn=None) -> Optional[CompanyMeta]:
+    """Use yfinance's search to find a ticker from a company name."""
+    def log(msg):
+        if log_fn: log_fn(msg)
+    try:
+        import yfinance as yf
+        log(f"  → yfinance search for '{query}' …")
+        results = yf.Search(query, max_results=5)
+        quotes = results.quotes
+        if not quotes:
+            return None
+        # Take the first relevant result
+        for q in quotes:
+            symbol = q.get("symbol", "")
+            qtype = q.get("quoteType", "")
+            if qtype in ("EQUITY", "MUTUALFUND") and symbol:
+                log(f"  → Found: {q.get('longname', symbol)} ({symbol})")
+                return _yf_resolve(symbol, log_fn)
+        return None
+    except Exception as e:
+        log(f"  ✗ yfinance search failed: {e}")
+        return None
+
+
+# ── Public resolve() ──────────────────────────────────────────────────────────
+
+def resolve(query: str, log_fn=None) -> CompanyMeta:
+    """
+    Resolve a company name or ticker to CompanyMeta.
+    Source priority: Indian map → yfinance direct → yfinance search → FMP → unlisted
+    """
+    def log(msg):
+        if log_fn: log_fn(msg)
+
+    query = query.strip()
+    log(f"Resolving: '{query}' …")
+
+    # 1. Check Indian name map → resolve via yfinance
+    indian_ticker = _guess_ticker(query)
+    if indian_ticker:
+        log(f"  → Mapped to Indian ticker: {indian_ticker}")
+        meta = _yf_resolve(indian_ticker, log_fn)
+        if meta:
+            return meta
+
+    # 2. Try direct yfinance (query as-is, and with .NS suffix)
+    for candidate in [query, query.upper(), f"{query.upper()}.NS", f"{query.upper()}.BO"]:
+        meta = _yf_resolve(candidate, log_fn)
+        if meta:
+            return meta
+
+    # 3. yfinance search
+    meta = _yf_search(query, log_fn)
+    if meta:
+        return meta
+
+    # 4. FMP search (for global companies)
+    meta = _fmp_resolve(query, log_fn)
+    if meta:
+        return meta
+
+    # 5. Unlisted fallback
+    log(f"  ⚠ '{query}' not found in any public market database.")
+    log("  → Treating as unlisted / private company.")
+    return CompanyMeta(
+        name=query, ticker="UNLISTED", exchange="Unlisted / Private",
+        currency="INR", sector="Unknown", industry="Unknown",
+        country="India", description="", website="",
+        mkt_cap=None, share_price=None, is_listed=False,
+        source_note=(
+            f"'{query}' could not be found. It may be unlisted, private, or use a different name. "
+            "Try using the exact BSE/NSE ticker (e.g. RELIANCE, TCS, HDFCBANK)."
+        ),
+        fiscal_year_end="March",
+    )

requirements.txt

@@ -0,0 +1,12 @@
+customtkinter>=5.2.0
+requests>=2.31.0
+beautifulsoup4>=4.12.0
+lxml>=4.9.0
+python-dotenv>=1.0.0
+google-generativeai>=0.7.0
+anthropic>=0.25.0
+openpyxl>=3.1.0
+python-docx>=1.1.0
+pandas>=2.0.0
+Pillow>=10.0.0
+yfinance>=0.2.40

storage/__init__.py

@@ -0,0 +1 @@
+# storage package

storage/cache.py

@@ -0,0 +1,146 @@
+"""
+storage/cache.py — SQLite-backed search history and financial data cache.
+"""
+import sqlite3
+import json
+import datetime
+from pathlib import Path
+from typing import Optional, List, Dict, Any
+
+import sys
+sys.path.insert(0, str(Path(__file__).parent.parent))
+from config import DB_PATH, CACHE_TTL_DAYS
+
+
+# ── Database setup ────────────────────────────────────────────────────────────
+
+def _connect() -> sqlite3.Connection:
+    conn = sqlite3.connect(DB_PATH)
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def init_db() -> None:
+    """Create tables if they don't exist."""
+    with _connect() as conn:
+        conn.executescript("""
+            CREATE TABLE IF NOT EXISTS searches (
+                id            INTEGER PRIMARY KEY AUTOINCREMENT,
+                company_name  TEXT    NOT NULL,
+                ticker        TEXT,
+                exchange      TEXT,
+                searched_at   TEXT    NOT NULL,
+                models_used   TEXT,
+                output_docx   TEXT,
+                output_xlsx   TEXT,
+                status        TEXT    DEFAULT 'completed'
+            );
+
+            CREATE TABLE IF NOT EXISTS financial_cache (
+                ticker        TEXT    NOT NULL,
+                data_type     TEXT    NOT NULL,
+                fetched_at    TEXT    NOT NULL,
+                expires_at    TEXT    NOT NULL,
+                raw_json      TEXT    NOT NULL,
+                PRIMARY KEY (ticker, data_type)
+            );
+
+            CREATE INDEX IF NOT EXISTS idx_searches_ticker ON searches(ticker);
+            CREATE INDEX IF NOT EXISTS idx_cache_ticker    ON financial_cache(ticker);
+        """)
+
+
+# ── Search history ────────────────────────────────────────────────────────────
+
+def add_search(
+    company_name: str,
+    ticker: str,
+    exchange: str,
+    models_used: List[str],
+    output_docx: str = "",
+    output_xlsx: str = "",
+    status: str = "completed",
+) -> int:
+    """Record a completed analysis in search history. Returns row id."""
+    now = datetime.datetime.now().isoformat(timespec="seconds")
+    with _connect() as conn:
+        cur = conn.execute(
+            """INSERT INTO searches
+               (company_name, ticker, exchange, searched_at, models_used, output_docx, output_xlsx, status)
+               VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
+            (company_name, ticker, exchange, now, json.dumps(models_used), output_docx, output_xlsx, status),
+        )
+        return cur.lastrowid
+
+
+def update_search_outputs(row_id: int, output_docx: str, output_xlsx: str, status: str = "completed") -> None:
+    with _connect() as conn:
+        conn.execute(
+            "UPDATE searches SET output_docx=?, output_xlsx=?, status=? WHERE id=?",
+            (output_docx, output_xlsx, status, row_id),
+        )
+
+
+def get_history(limit: int = 50) -> List[Dict]:
+    """Return recent searches, newest first."""
+    with _connect() as conn:
+        rows = conn.execute(
+            "SELECT * FROM searches ORDER BY searched_at DESC LIMIT ?", (limit,)
+        ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def delete_history_entry(row_id: int) -> None:
+    with _connect() as conn:
+        conn.execute("DELETE FROM searches WHERE id=?", (row_id,))
+
+
+# ── Financial data cache ──────────────────────────────────────────────────────
+
+def get_cached(ticker: str, data_type: str) -> Optional[Any]:
+    """Return cached JSON data if still valid, else None."""
+    now = datetime.datetime.now().isoformat()
+    with _connect() as conn:
+        row = conn.execute(
+            "SELECT raw_json, expires_at FROM financial_cache WHERE ticker=? AND data_type=?",
+            (ticker.upper(), data_type),
+        ).fetchone()
+    if row is None:
+        return None
+    if row["expires_at"] < now:
+        # Expired
+        return None
+    return json.loads(row["raw_json"])
+
+
+def set_cache(ticker: str, data_type: str, data: Any) -> None:
+    """Store data in cache with TTL."""
+    now = datetime.datetime.now()
+    expires = (now + datetime.timedelta(days=CACHE_TTL_DAYS)).isoformat()
+    with _connect() as conn:
+        conn.execute(
+            """INSERT OR REPLACE INTO financial_cache
+               (ticker, data_type, fetched_at, expires_at, raw_json)
+               VALUES (?, ?, ?, ?, ?)""",
+            (ticker.upper(), data_type, now.isoformat(), expires, json.dumps(data)),
+        )
+
+
+def clear_cache(ticker: str) -> None:
+    """Remove all cached data for a ticker (force refresh)."""
+    with _connect() as conn:
+        conn.execute("DELETE FROM financial_cache WHERE ticker=?", (ticker.upper(),))
+
+
+def cache_stats() -> Dict:
+    """Return some stats for diagnostics."""
+    with _connect() as conn:
+        total_searches = conn.execute("SELECT COUNT(*) FROM searches").fetchone()[0]
+        cached_tickers = conn.execute(
+            "SELECT COUNT(DISTINCT ticker) FROM financial_cache"
+        ).fetchone()[0]
+    return {"total_searches": total_searches, "cached_tickers": cached_tickers}
+
+
+# Initialise on import
+init_db()

verify_data.py

@@ -0,0 +1,33 @@
+import sys, io
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+sys.path.insert(0, '.')
+from pipeline.resolver import resolve
+from pipeline.fetcher import fetch_all
+from pipeline.calculator import calculate
+
+meta = resolve('TCS', log_fn=lambda m: print(m))
+data = fetch_all(meta, years=5, force_refresh=True, log_fn=lambda m: print(m))
+data = calculate(data, meta.to_dict())
+
+print()
+print("=== SCALED DATA ===")
+inc = data['income_statement']
+yr  = data['years']
+units_label = data.get('units_label', data.get('units', '?'))
+print("Units label:", units_label)
+print()
+for y, r, n, e in zip(yr, inc['revenue'], inc['net_income'], inc['ebitda']):
+    r_s = f"{r:,.0f} Cr" if r else "N/A"
+    n_s = f"{n:,.0f} Cr" if n else "N/A"
+    e_s = f"{e:,.0f} Cr" if e else "N/A"
+    print(f"  {y} | Rev: {r_s:>15} | NetInc: {n_s:>12} | EBITDA: {e_s:>12}")
+
+print()
+rat = data['ratios']
+print("Ratios (latest year):")
+print(f"  Operating Margin: {(rat['operating_margin'][-1] or 0)*100:.1f}%")
+print(f"  Net Margin:       {(rat['net_margin'][-1] or 0)*100:.1f}%")
+print(f"  ROE:              {(rat['roe'][-1] or 0)*100:.1f}%")
+print(f"  Current Ratio:    {rat['current_ratio'][-1]}")
+print()
+print("Data looks correct - ready for reports!")

verify_reports.py

@@ -0,0 +1,43 @@
+import sys, io, os
+sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
+sys.path.insert(0, '.')
+
+from pipeline.resolver import resolve
+from pipeline.fetcher import fetch_all
+from pipeline.calculator import calculate
+from pipeline.analyst import generate_narrative
+from builders.build_excel import build_workbook
+from builders.build_docx import build_document
+
+def run_test():
+    print("1. Resolving TCS...")
+    meta = resolve('TCS', log_fn=lambda m: print("  " + m))
+    
+    print("\n2. Fetching data...")
+    data = fetch_all(meta, years=5, force_refresh=False, log_fn=lambda m: print("  " + m))
+    
+    print("\n3. Calculating ratios...")
+    data = calculate(data, meta.to_dict())
+    
+    print("\n4. Generating Narrative (Data-only)...")
+    # Use empty models list to skip actual API calls for a quick formatting test
+    narrative = generate_narrative(data, meta.to_dict(), models=[], log_fn=lambda m: print("  " + m))
+    data.update(narrative)
+    
+    # Save test files
+    os.makedirs("test_outputs", exist_ok=True)
+    excel_path = "test_outputs/TCS_Analysis.xlsx"
+    docx_path = "test_outputs/TCS_Analysis.docx"
+    
+    print("\n5. Building Excel...")
+    build_workbook(data, excel_path)
+    print(f"  ✓ Saved to {excel_path}")
+    
+    print("\n6. Building Word Document...")
+    build_document(data, docx_path)
+    print(f"  ✓ Saved to {docx_path}")
+    
+    print("\nAll tests passed successfully!")
+
+if __name__ == "__main__":
+    run_test()

web_app/app.py

@@ -0,0 +1,473 @@
+"""
+web_app/app.py — Cloud-hosted Streamlit Portal for Financial Analysis.
+
+Provides a rich dark UI dashboard to scrape, compute, analyze and download reports
+for Excel, Word, and PowerPoint formats using user-supplied LLM credentials.
+"""
+import os
+import sys
+import time
+import datetime
+from pathlib import Path
+import streamlit as st
+
+# Setup sys.path so local packages can be resolved from parent directory
+PARENT_DIR = Path(__file__).parent.parent
+sys.path.insert(0, str(PARENT_DIR))
+
+# Import builders and pipeline
+from pipeline.resolver import resolve
+from pipeline.fetcher import fetch_all
+from pipeline.peer_selector import select_peers
+from pipeline.calculator import calculate
+from pipeline.analyst import generate_narrative
+from builders.build_excel import build_workbook
+from builders.build_docx import build_document
+from builders.build_pptx import build_presentation
+from web_app.database import save_audit_log, get_audit_logs
+
+# Streamlit Page Config
+st.set_page_config(
+    page_title="Financial Statement Analyzer Cloud Portal",
+    page_icon="📈",
+    layout="wide",
+    initial_sidebar_state="expanded"
+)
+
+# Dark Theme Glassmorphism Custom CSS Injection
+st.markdown("""
+<style>
+    @import url('https://fonts.googleapis.com/css2?family=Inter:wght@300;400;600;700&display=swap');
+    
+    html, body, [class*="css"] {
+        font-family: 'Inter', sans-serif;
+    }
+    
+    .main {
+        background-color: #0A0F1D;
+        color: #F3F4F6;
+    }
+    
+    /* Sidebar styling */
+    [data-testid="stSidebar"] {
+        background-color: #0F162A;
+        border-right: 1px solid #1E293B;
+    }
+    
+    /* Title and Subtitle */
+    .dashboard-title {
+        font-size: 2.5rem;
+        font-weight: 700;
+        background: linear-gradient(135deg, #60A5FA, #34D399);
+        -webkit-background-clip: text;
+        -webkit-text-fill-color: transparent;
+        margin-bottom: 0.2rem;
+    }
+    
+    .dashboard-subtitle {
+        font-size: 1.1rem;
+        font-weight: 300;
+        color: #9CA3AF;
+        margin-bottom: 2rem;
+    }
+    
+    /* Glowing card containers */
+    .glass-card {
+        background: rgba(30, 41, 59, 0.45);
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        border-radius: 16px;
+        padding: 1.5rem;
+        backdrop-filter: blur(12px);
+        margin-bottom: 1.5rem;
+        box-shadow: 0 8px 32px 0 rgba(0, 0, 0, 0.37);
+    }
+    
+    .status-log {
+        background-color: #0D1117 !important;
+        border: 1px solid #1F242C !important;
+        border-radius: 8px !important;
+        color: #C9D1D9 !important;
+        font-family: 'Consolas', monospace !important;
+        padding: 12px;
+        max-height: 380px;
+        overflow-y: auto;
+    }
+    
+    /* Primary buttons styling */
+    div.stButton > button:first-child {
+        background: linear-gradient(135deg, #3B82F6, #10B981);
+        border: none;
+        color: white;
+        font-weight: 600;
+        padding: 0.6rem 2rem;
+        border-radius: 8px;
+        transition: transform 0.2s, box-shadow 0.2s;
+        box-shadow: 0 0 15px rgba(59, 130, 246, 0.4);
+    }
+    
+    div.stButton > button:first-child:hover {
+        transform: translateY(-2px);
+        box-shadow: 0 0 25px rgba(16, 185, 129, 0.6);
+        color: white;
+    }
+    
+    /* Checkbox layouts styling */
+    .stCheckbox > label {
+        color: #D1D5DB !important;
+    }
+</style>
+""", unsafe_allow_html=True)
+
+# ── Sidebar — Connect Your AI ──────────────────────────────────────────
+st.sidebar.markdown("""
+<h2 style='color:#60A5FA;margin-top:0;'>🤖 Connect Your AI</h2>
+<p style='font-size:0.8rem;color:#9CA3AF;'>
+  Bring your own key. Keys live only in your browser session — never stored on the server.
+</p>
+""", unsafe_allow_html=True)
+
+# ── FREE OPTIONS ───────────────────────────────────────────────────────
+st.sidebar.markdown("""
+<div style='background:rgba(16,185,129,0.08);border:1px solid rgba(16,185,129,0.25);
+            border-radius:8px;padding:0.6rem 0.85rem;margin-bottom:0.5rem;'>
+  <span style='font-size:0.75rem;font-weight:700;color:#34D399;letter-spacing:0.06em;'>🆓 FREE — NO CREDIT CARD</span>
+</div>
+""", unsafe_allow_html=True)
+
+st.sidebar.markdown("""
+**Groq** *(Llama 3.3 70B — fast & free)*  
+<a href='https://console.groq.com/keys' target='_blank' style='font-size:0.75rem;color:#34D399;'>Get free key → console.groq.com</a>
+""", unsafe_allow_html=True)
+groq_key = st.sidebar.text_input(
+    "Groq API Key", type="password",
+    placeholder="gsk_…",
+    value=os.environ.get("GROQ_API_KEY", ""),
+    help="100% free. Sign up at console.groq.com → API Keys. No credit card.",
+    key="inp_groq"
+)
+
+st.sidebar.markdown("""
+**Google Gemini** *(Gemini 2.0 Flash — free tier)*  
+<a href='https://aistudio.google.com/app/apikey' target='_blank' style='font-size:0.75rem;color:#34D399;'>Get free key → aistudio.google.com</a>
+""", unsafe_allow_html=True)
+gemini_key = st.sidebar.text_input(
+    "Gemini API Key", type="password",
+    placeholder="AIza…",
+    value=os.environ.get("GEMINI_API_KEY", ""),
+    help="Free tier: 15 requests/min, 1M tokens/day. No billing needed.",
+    key="inp_gemini"
+)
+
+# ── PAID OPTIONS ───────────────────────────────────────────────────────
+st.sidebar.markdown("""
+<div style='background:rgba(99,102,241,0.08);border:1px solid rgba(99,102,241,0.25);
+            border-radius:8px;padding:0.6rem 0.85rem;margin:0.5rem 0;'>
+  <span style='font-size:0.75rem;font-weight:700;color:#818CF8;letter-spacing:0.06em;'>💳 OPTIONAL — PAID APIS</span>
+</div>
+""", unsafe_allow_html=True)
+
+with st.sidebar.expander("Claude (Anthropic) — paid", expanded=False):
+    st.markdown("<a href='https://console.anthropic.com/' target='_blank' style='font-size:0.75rem;color:#818CF8;'>Get key → console.anthropic.com</a>", unsafe_allow_html=True)
+    claude_key = st.text_input(
+        "Claude API Key", type="password",
+        placeholder="sk-ant-…",
+        value=os.environ.get("CLAUDE_API_KEY", ""),
+        key="inp_claude"
+    )
+
+with st.sidebar.expander("ChatGPT (OpenAI) — paid", expanded=False):
+    st.markdown("<a href='https://platform.openai.com/api-keys' target='_blank' style='font-size:0.75rem;color:#818CF8;'>Get key → platform.openai.com</a>", unsafe_allow_html=True)
+    openai_key = st.text_input(
+        "OpenAI API Key", type="password",
+        placeholder="sk-proj-…",
+        value=os.environ.get("OPENAI_API_KEY", ""),
+        key="inp_openai"
+    )
+
+st.sidebar.markdown("---")
+st.sidebar.markdown("<h3 style='color:#34D399;'>👤 User Profile</h3>", unsafe_allow_html=True)
+username = st.sidebar.text_input("Username / Email", value="guest@local", help="Logged in the audit trail")
+
+# ── Main Dashboard Layout ──────────────────────────────────────────────
+st.markdown("<h1 class='dashboard-title'>📈 Financial Statement Analyzer</h1>", unsafe_allow_html=True)
+st.markdown("<p class='dashboard-subtitle'>Multi-model AI insights scraper and report compilation portal</p>", unsafe_allow_html=True)
+
+# Left Column: Inputs
+# Right Column: Exporters & Progress
+col1, col2 = st.columns([1, 1.2])
+
+with col1:
+    st.markdown("<div class='glass-card'>", unsafe_allow_html=True)
+    st.subheader("Analysis Parameters")
+    
+    ticker_input = st.text_input("Company Name or Stock Ticker", placeholder="e.g. TCS, Reliance, AAPL, MSFT, INFY", help="Resolves directly via yfinance and FMP")
+    
+    col_years, col_refresh = st.columns([1, 1])
+    with col_years:
+        analysis_years = st.selectbox("Analysis Horizon", options=[5, 7, 10], index=0)
+    with col_refresh:
+        force_refresh = st.checkbox("Bypass Cache (Force Scrape)", value=False)
+    
+    st.markdown("<b>Download Formats:</b>", unsafe_allow_html=True)
+    chk_excel = st.checkbox("Excel Analysis Workbook (.xlsx)", value=True)
+    chk_word  = st.checkbox("Word Summary Report (.docx)",     value=True)
+    chk_pptx  = st.checkbox("PowerPoint Pitch Deck (.pptx)",   value=True)
+    
+    # ── AI Engine selection — auto-disable if key not supplied
+    st.markdown("<b>AI Engines:</b>", unsafe_allow_html=True)
+
+    _hint = "<span style='font-size:0.72rem;color:#9CA3AF;'>(add key in sidebar →)</span>"
+
+    engines = []
+    if st.checkbox(
+        "🆓 Groq — Llama 3.3 70B (recommended)",
+        value=bool(groq_key),
+        disabled=not groq_key,
+        help="Free. Get key at console.groq.com"
+    ):
+        engines.append("groq")
+
+    if st.checkbox(
+        "🆓 Gemini 2.0 Flash (Google)",
+        value=bool(gemini_key),
+        disabled=not gemini_key,
+        help="Free tier. Get key at aistudio.google.com"
+    ):
+        engines.append("gemini")
+
+    if st.checkbox(
+        "💳 Claude Haiku (Anthropic)",
+        value=False,
+        disabled=not claude_key,
+        help="Paid. Add key in sidebar to enable."
+    ):
+        engines.append("claude")
+
+    if st.checkbox(
+        "💳 ChatGPT — GPT-4o mini (OpenAI)",
+        value=False,
+        disabled=not openai_key,
+        help="Paid. Add key in sidebar to enable."
+    ):
+        engines.append("openai")
+
+    if not groq_key and not gemini_key:
+        st.info("💡 Add a **free Groq key** in the sidebar to enable AI narratives.", icon="🔑")
+
+    st.markdown("<br>", unsafe_allow_html=True)
+    start_btn = st.button("Begin Financial Scrape & Analysis")
+    st.markdown("</div>", unsafe_allow_html=True)
+
+with col2:
+    st.markdown("<div class='glass-card'>", unsafe_allow_html=True)
+    st.subheader("Execution Status & Logs")
+    
+    log_container = st.empty()
+    download_container = st.empty()
+    
+    log_container.code("Ready to analyze. Input a company and click the button above.", language="text")
+    st.markdown("</div>", unsafe_allow_html=True)
+
+# ── Analysis Runner ───────────────────────────────────────────────────
+if start_btn:
+    if not ticker_input:
+        st.error("Please enter a stock ticker or company name.")
+    elif not (chk_excel or chk_word or chk_pptx):
+        st.error("Please select at least one download format checkbox.")
+    else:
+        # Inject credentials into all modules that cache them at import time
+        import config
+        import pipeline.analyst
+        import pipeline.key_validator
+        
+        config.GEMINI_API_KEY = gemini_key
+        config.CLAUDE_API_KEY = claude_key
+        config.OPENAI_API_KEY = openai_key
+        config.GROQ_API_KEY   = groq_key
+        
+        pipeline.analyst.GEMINI_API_KEY = gemini_key
+        pipeline.analyst.CLAUDE_API_KEY = claude_key
+        pipeline.analyst.OPENAI_API_KEY = openai_key
+        pipeline.analyst.GROQ_API_KEY   = groq_key
+        
+        pipeline.key_validator.GEMINI_API_KEY = gemini_key
+        pipeline.key_validator.CLAUDE_API_KEY = claude_key
+        pipeline.key_validator.OPENAI_API_KEY = openai_key
+
+        # Push into environment for any sub-process
+        for k, v in [("GEMINI_API_KEY", gemini_key), ("CLAUDE_API_KEY", claude_key),
+                     ("OPENAI_API_KEY", openai_key), ("GROQ_API_KEY", groq_key)]:
+            if v: os.environ[k] = v
+        
+        # Validate that selected engines have keys
+        failed_validation = False
+        engine_key_map = {
+            "groq":   (groq_key,   "Groq"),
+            "gemini": (gemini_key, "Gemini"),
+            "claude": (claude_key, "Claude"),
+            "openai": (openai_key, "ChatGPT"),
+        }
+        for engine in engines:
+            key, label = engine_key_map[engine]
+            if not key:
+                st.error(f"Please supply a {label} API Key or uncheck the {label} model.")
+                failed_validation = True
+            
+        if not failed_validation:
+            logs = []
+            
+            def log_fn(msg):
+                logs.append(msg)
+                log_container.code("\n".join(logs), language="text")
+                
+            try:
+                log_fn("="*60)
+                log_fn(f"Starting analysis for: '{ticker_input}'")
+                log_fn(f"Time: {datetime.datetime.now().strftime('%Y-%m-%d %H:%M:%S')}")
+                log_fn(f"Formats: " + ", ".join([f for f, ok in [("Excel", chk_excel), ("Word", chk_word), ("PowerPoint", chk_pptx)] if ok]))
+                log_fn(f"AI Models: {engines or ['None (Data Only)']}")
+                log_fn("="*60)
+                
+                # 1. Resolve Company Info
+                log_fn("\n[1/7] Resolving company metadata …")
+                meta = resolve(ticker_input, log_fn=log_fn)
+                log_fn(f"  ✓ {meta.name} | {meta.ticker} | {meta.exchange}")
+                
+                # 2. Fetch Statements
+                log_fn("\n[2/7] Scrape financial statements …")
+                fin_data = fetch_all(meta, force_refresh=force_refresh, log_fn=log_fn)
+                
+                # 3. Peers Comparison Selection
+                log_fn("\n[3/7] Benchmarking peer selection …")
+                fin_data["peers"] = select_peers(meta, log_fn=log_fn)
+                
+                # 4. Math ratios calculations
+                log_fn("\n[4/7] Computing financial ratios & DuPont decomposition …")
+                fin_data = calculate(fin_data, meta.to_dict())
+                log_fn("  ✓ Completed ratio math computations")
+                
+                # 5. AI Synthesis Narrative
+                log_fn("\n[5/7] Requesting AI Model narrative generation …")
+                narrative = generate_narrative(fin_data, meta.to_dict(), engines, log_fn=log_fn)
+                fin_data.update(narrative)
+                
+                # 6. Generate outputs
+                log_fn("\n[6/7] Building output report files …")
+                fin_data["company"] = {
+                    "name": meta.name, "ticker": meta.ticker, "exchange": meta.exchange,
+                    "currency": fin_data.get("currency", meta.currency),
+                    "units": fin_data.get("units", "millions"),
+                    "fiscal_year_end": "",
+                    "industry": meta.industry, "sector": meta.sector,
+                    "business_description": meta.description,
+                    "report_date": datetime.date.today().isoformat(),
+                    "analysis_period_years": len(fin_data.get("years", [])),
+                    "share_price": meta.share_price, "market_cap": meta.mkt_cap,
+                }
+                fin_data["models_used"] = engines
+                fin_data.setdefault("sources", [])
+                
+                ticker_safe = meta.ticker.replace(".", "_").replace("/", "_")
+                timestamp_suffix = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+                
+                # Exporters path settings
+                excel_bytes = None
+                word_bytes = None
+                pptx_bytes = None
+                
+                out_dir = PARENT_DIR / "outputs"
+                os.makedirs(str(out_dir), exist_ok=True)
+                
+                # Build files in memory / disk
+                if chk_excel:
+                    xlsx_path = out_dir / f"{ticker_safe}_financial_analysis_{timestamp_suffix}.xlsx"
+                    build_workbook(fin_data, str(xlsx_path))
+                    with open(xlsx_path, "rb") as f:
+                        excel_bytes = f.read()
+                    log_fn(f"  ✓ Created Excel analysis: {xlsx_path.name}")
+                    
+                if chk_word:
+                    docx_path = out_dir / f"{ticker_safe}_financial_analysis_{timestamp_suffix}.docx"
+                    build_document(fin_data, str(docx_path))
+                    with open(docx_path, "rb") as f:
+                        word_bytes = f.read()
+                    log_fn(f"  ✓ Created Word summary: {docx_path.name}")
+                    
+                if chk_pptx:
+                    pptx_path = out_dir / f"{ticker_safe}_financial_analysis_{timestamp_suffix}.pptx"
+                    build_presentation(fin_data, str(pptx_path))
+                    with open(pptx_path, "rb") as f:
+                        pptx_bytes = f.read()
+                    log_fn(f"  ✓ Created PowerPoint Presentation: {pptx_path.name}")
+                
+                log_fn(f"\n[7/7] ✅ Financial analysis process complete!")
+                log_fn("="*60)
+                
+                # ── Generate download buttons in UI
+                with download_container.container():
+                    st.success("Download ready!")
+                    col_btn1, col_btn2, col_btn3 = st.columns(3)
+                    
+                    if excel_bytes:
+                        col_btn1.download_button(
+                            label="📥 Download Excel Workbook",
+                            data=excel_bytes,
+                            file_name=f"{ticker_safe}_Analysis_{timestamp_suffix}.xlsx",
+                            mime="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+                        )
+                    if word_bytes:
+                        col_btn2.download_button(
+                            label="📥 Download Word Report",
+                            data=word_bytes,
+                            file_name=f"{ticker_safe}_Report_{timestamp_suffix}.docx",
+                            mime="application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+                        )
+                    if pptx_bytes:
+                        col_btn3.download_button(
+                            label="📥 Download PowerPoint Deck",
+                            data=pptx_bytes,
+                            file_name=f"{ticker_safe}_Presentation_{timestamp_suffix}.pptx",
+                            mime="application/vnd.openxmlformats-officedocument.presentationml.presentation"
+                        )
+                
+                # Write search activity log to audit table
+                selected_formats = [f for f, ok in [("xlsx", chk_excel), ("docx", chk_word), ("pptx", chk_pptx)] if ok]
+                save_audit_log(
+                    user_email=username,
+                    company_ticker=meta.ticker,
+                    company_name=meta.name,
+                    selected_formats=selected_formats,
+                    ai_models=engines,
+                    status="completed"
+                )
+                
+            except Exception as e:
+                log_fn(f"\n❌ Pipeline failed: {e}")
+                import traceback
+                log_fn(traceback.format_exc())
+                st.error(f"Analysis failed: {e}")
+                
+                # Save audit log failure
+                try:
+                    selected_formats = [f for f, ok in [("xlsx", chk_excel), ("docx", chk_word), ("pptx", chk_pptx)] if ok]
+                    save_audit_log(
+                        user_email=username,
+                        company_ticker=ticker_input,
+                        company_name="N/A",
+                        selected_formats=selected_formats,
+                        ai_models=engines,
+                        status="failed"
+                    )
+                except:
+                    pass
+
+# ── Audit History Panel Table ───────────────────────────────────────────
+st.markdown("---")
+st.markdown("<h3 style='color:#60A5FA;margin-top:0;'>📜 Query Audit Trail & History</h3>", unsafe_allow_html=True)
+st.markdown("<p style='font-size:0.85rem;color:#9CA3AF;'>Past analysis runs requested by team members.</p>", unsafe_allow_html=True)
+
+history_logs = get_audit_logs()
+if history_logs:
+    st.table(history_logs)
+else:
+    st.info("No queries have been run yet.")

web_app/database.py

@@ -0,0 +1,149 @@
+"""
+web_app/database.py — Database audit logging system.
+
+Supports dual-driver data persistence:
+- Direct Cloud Supabase PostgreSQL storage (if environment variables exist).
+- Automatic Local SQLite database fallback.
+"""
+import os
+import sqlite3
+import datetime
+from pathlib import Path
+from typing import List, Dict
+
+DB_PATH = Path(__file__).parent / "financial_audit.db"
+
+def init_db():
+    """Initializes the local SQLite database if not present."""
+    conn = sqlite3.connect(str(DB_PATH))
+    cursor = conn.cursor()
+    cursor.execute("""
+        CREATE TABLE IF NOT EXISTS financial_analysis_audit (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            timestamp TEXT NOT NULL,
+            user_email TEXT NOT NULL,
+            company_ticker TEXT NOT NULL,
+            company_name TEXT NOT NULL,
+            selected_formats TEXT NOT NULL,
+            ai_model_used TEXT NOT NULL,
+            status TEXT NOT NULL
+        )
+    """)
+    conn.commit()
+    conn.close()
+
+def save_audit_log(user_email: str, company_ticker: str, company_name: str, selected_formats: List[str], ai_models: List[str], status: str):
+    """
+    Saves an audit log entry.
+    Tries Supabase first, falls back to local SQLite on failure or if not configured.
+    """
+    timestamp = datetime.datetime.utcnow().isoformat()
+    selected_formats_str = ", ".join(selected_formats)
+    ai_models_str = ", ".join(ai_models) if ai_models else "none"
+
+    supabase_url = os.environ.get("SUPABASE_URL")
+    supabase_key = os.environ.get("SUPABASE_KEY")
+
+    if supabase_url and supabase_key:
+        try:
+            from supabase import create_client, Client
+            supabase: Client = create_client(supabase_url, supabase_key)
+            data = {
+                "user_email": user_email,
+                "company_ticker": company_ticker,
+                "company_name": company_name,
+                "selected_formats": selected_formats,  # stored as text array in Postgres
+                "ai_model_used": ai_models_str,
+                "status": status
+            }
+            supabase.table("financial_analysis_audit").insert(data).execute()
+            print("Audit log successfully written to Cloud Supabase DB.")
+            return
+        except Exception as e:
+            print(f"Supabase logging failed: {e}. Falling back to SQLite.")
+
+    # Local SQLite Fallback
+    try:
+        init_db()
+        conn = sqlite3.connect(str(DB_PATH))
+        cursor = conn.cursor()
+        cursor.execute("""
+            INSERT INTO financial_analysis_audit (timestamp, user_email, company_ticker, company_name, selected_formats, ai_model_used, status)
+            VALUES (?, ?, ?, ?, ?, ?, ?)
+        """, (timestamp, user_email, company_ticker, company_name, selected_formats_str, ai_models_str, status))
+        conn.commit()
+        conn.close()
+        print("Audit log written to local SQLite database.")
+    except Exception as sqle:
+        print(f"Local SQLite database audit write error: {sqle}")
+
+def get_audit_logs() -> List[Dict]:
+    """
+    Fetches the history of audit logs.
+    Tries Supabase first, falls back to local SQLite.
+    """
+    supabase_url = os.environ.get("SUPABASE_URL")
+    supabase_key = os.environ.get("SUPABASE_KEY")
+
+    if supabase_url and supabase_key:
+        try:
+            from supabase import create_client, Client
+            supabase: Client = create_client(supabase_url, supabase_key)
+            response = supabase.table("financial_analysis_audit").select("*").order("timestamp", desc=True).limit(50).execute()
+            logs = []
+            for row in response.data:
+                # Convert list array from supabase to comma-separated string for display alignment
+                formats = row.get("selected_formats", [])
+                formats_str = ", ".join(formats) if isinstance(formats, list) else str(formats)
+                
+                # Format timestamp
+                ts = row.get("timestamp", "")
+                if ts:
+                    try:
+                        ts = datetime.datetime.fromisoformat(ts.replace("Z", "+00:00")).strftime("%Y-%m-%d %H:%M:%S")
+                    except:
+                        pass
+                
+                logs.append({
+                    "timestamp": ts,
+                    "user_email": row.get("user_email", "N/A"),
+                    "company_ticker": row.get("company_ticker", "N/A"),
+                    "company_name": row.get("company_name", "N/A"),
+                    "selected_formats": formats_str,
+                    "ai_model_used": row.get("ai_model_used", "N/A"),
+                    "status": row.get("status", "N/A")
+                })
+            return logs
+        except Exception as e:
+            print(f"Supabase fetch logs failed: {e}. Falling back to SQLite.")
+
+    # SQLite Fallback
+    try:
+        init_db()
+        conn = sqlite3.connect(str(DB_PATH))
+        conn.row_factory = sqlite3.Row
+        cursor = conn.cursor()
+        cursor.execute("SELECT * FROM financial_analysis_audit ORDER BY timestamp DESC LIMIT 50")
+        rows = cursor.fetchall()
+        logs = []
+        for r in rows:
+            ts = r["timestamp"]
+            if ts and "T" in ts:
+                try:
+                    ts = datetime.datetime.fromisoformat(ts).strftime("%Y-%m-%d %H:%M:%S")
+                except:
+                    pass
+            logs.append({
+                "timestamp": ts,
+                "user_email": r["user_email"],
+                "company_ticker": r["company_ticker"],
+                "company_name": r["company_name"],
+                "selected_formats": r["selected_formats"],
+                "ai_model_used": r["ai_model_used"],
+                "status": r["status"]
+            })
+        conn.close()
+        return logs
+    except Exception as sqle:
+        print(f"Local SQLite logs retrieve error: {sqle}")
+        return []

web_app/requirements.txt

@@ -0,0 +1,16 @@
+streamlit>=1.30.0
+python-pptx>=0.6.21
+supabase==2.4.0
+requests>=2.31.0
+beautifulsoup4>=4.12.0
+lxml>=4.9.0
+python-dotenv>=1.0.0
+google-generativeai>=0.7.0
+google-genai>=0.8.0
+anthropic>=0.25.0
+openai>=1.0.0
+openpyxl>=3.1.0
+python-docx>=1.1.0
+pandas>=2.0.0
+Pillow>=10.0.0
+yfinance>=0.2.40

web_app/run_web.bat

@@ -0,0 +1,45 @@
+@echo off
+title Financial Analyzer Web Portal Launcher
+cd /d "%~dp0"
+
+echo ====================================================
+echo Starting Financial Statement Analysis Web Portal...
+echo ====================================================
+
+:: Path check for virtual environments
+set ROOT_VENV=..\..\.venv
+set LOCAL_VENV=.venv
+
+if exist "%ROOT_VENV%\Scripts\python.exe" (
+    echo [INFO] Found shared virtual environment at %ROOT_VENV%
+    set VENV_PATH=%ROOT_VENV%
+) else if exist "%LOCAL_VENV%\Scripts\python.exe" (
+    echo [INFO] Found local virtual environment at %LOCAL_VENV%
+    set VENV_PATH=%LOCAL_VENV%
+) else (
+    echo [INFO] Creating new virtual environment...
+    python -m venv .venv
+    set VENV_PATH=.venv
+)
+
+set PYTHON_EXE=%VENV_PATH%\Scripts\python.exe
+set PIP_EXE=%VENV_PATH%\Scripts\pip.exe
+set STREAMLIT_EXE=%VENV_PATH%\Scripts\streamlit.exe
+
+echo [INFO] Updating Python dependencies inside virtual environment...
+%PIP_EXE% install -r requirements.txt
+if %ERRORLEVEL% neq 0 (
+    echo [ERROR] Dependencies installation failed.
+    pause
+    exit /b 1
+)
+
+echo [INFO] Booting Streamlit server...
+%STREAMLIT_EXE% run app.py
+if %ERRORLEVEL% neq 0 (
+    echo [ERROR] Streamlit failed to start.
+    pause
+    exit /b 1
+)
+
+pause

web_app/streamlit_config.toml

@@ -0,0 +1,21 @@
+[general]
+email = ""
+
+[server]
+port = 7860
+address = "0.0.0.0"
+headless = true
+enableXsrfProtection = false
+maxUploadSize = 50
+
+[browser]
+gatherUsageStats = false
+serverAddress = "0.0.0.0"
+serverPort = 7860
+
+[theme]
+base = "dark"
+backgroundColor = "#0A0F1D"
+secondaryBackgroundColor = "#0F162A"
+textColor = "#F3F4F6"
+primaryColor = "#3B82F6"