indiequity 0.1.0__tar.gz

indiequity-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayush (AnonyyMouse)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

indiequity-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: indiequity
+Version: 0.1.0
+Summary: Indian equity research toolkit for NSE/BSE fundamental analysis, ratios, screening, and DCF valuation.
+Author-email: Ayush <anon.yy.mouse.712@gmail.com>
+License: MIT
+Keywords: finance,equity-research,nse,bse,nifty,dcf-valuation,fundamental-analysis,dupont-analysis,india-stock-market,stock-screener
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: yfinance>=0.2.40
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: rich>=13.5.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: jupyter>=1.0.0; extra == "dev"
+Dynamic: license-file
+
+# indiequity: Indian Equity Research Toolkit
+
+A Python library designed for small-cap and mid-cap equity research on Indian markets (NSE & BSE).
+
+## Key Features
+- **Public Data Ingestion**: Seamless financial statement retrieval for NSE and BSE tickers with local SQLite caching.
+- **Fundamental Ratios**: Return on Capital Employed (ROCE), Return on Equity (ROE), Debt-to-Equity, Interest Coverage, and FCF Yield.
+- **DuPont Analysis**: 3-Stage and 5-Stage Return on Equity decomposition.
+- **Stock Screener**: Configurable screening filters and built-in strategy presets (`Quality Smallcap`, `Deep Value`, `High Compounder`).
+- **5-Year FCFF DCF Valuation**: Enterprise value and intrinsic equity value per share with a 2D sensitivity grid (WACC vs. Terminal Growth Rate).
+- **Export & Visualization**: Publication-grade charts and multi-tab formatted Excel workbooks (`.xlsx`).
+- **Command Line & Notebook Interfaces**: Clean CLI powered by Rich and Typer, plus interactive Jupyter tutorial notebooks.
+
+## Installation
+
+```bash
+pip install indiequity
+```
+
+Or install in development mode from source:
+```bash
+git clone https://github.com/AnonyyMouse/indiequity.git
+cd indiequity
+pip install -e .
+```
+
+## Quickstart
+
+### Python API
+```python
+import indiequity as ie
+
+# 1. Fetch public financial profile
+profile = ie.fetch_company_data("ITC")
+
+# 2. Compute key financial ratios
+ratios = ie.calculate_ratios(profile)
+print(f"Company:   {profile.company_name}")
+print(f"Mcap:      {ie.format_crores(ratios.market_cap)}")
+print(f"ROCE:      {ie.format_percentage(ratios.roce)}")
+print(f"ROE:       {ie.format_percentage(ratios.roe)}")
+
+# 3. 5-Stage DuPont Decomposition
+dupont = ie.decompose_dupont_5stage(profile)
+print(f"Operating Margin: {ie.format_percentage(dupont.operating_margin)}")
+print(f"Tax Burden:       {dupont.tax_burden:.2f}x")
+print(f"Interest Burden:  {dupont.interest_burden:.2f}x")
+
+# 4. DCF Valuation & Sensitivity Analysis
+dcf = ie.calculate_dcf(profile, forecast_years=5, terminal_growth_rate=0.05)
+print(f"Intrinsic Value: ₹{dcf.intrinsic_value_per_share:,.2f} per share")
+print(dcf.sensitivity_table)
+```
+
+### Command Line Interface (CLI)
+```bash
+# View company ratios
+indiequity ratios ITC
+
+# View 5-stage DuPont decomposition
+indiequity dupont ITC --stages 5
+
+# Run 5-Year DCF with sensitivity table
+indiequity dcf ITC
+
+# Run stock screener
+indiequity screen --universe smallcap --preset quality-smallcap
+
+# Export complete research report to Excel
+indiequity export ITC --output itc_report.xlsx
+```
+
+## Known Limitations & Disclaimer
+- **Data Source**: Fundamental statements are sourced from public market feeds via `yfinance`. Corporate restructurings or unaudited quarterly results may occasionally require cross-checking with official BSE/NSE filings.
+- **Educational / Research Use Only**: This toolkit is created by equity research students for educational, academic, and screening purposes. It does not constitute investment advice or SEBI-registered advisory recommendations.
+
+## License
+Distributed under the MIT License. See `LICENSE` for details.

indiequity-0.1.0/README.md

@@ -0,0 +1,78 @@
+# indiequity: Indian Equity Research Toolkit
+
+A Python library designed for small-cap and mid-cap equity research on Indian markets (NSE & BSE).
+
+## Key Features
+- **Public Data Ingestion**: Seamless financial statement retrieval for NSE and BSE tickers with local SQLite caching.
+- **Fundamental Ratios**: Return on Capital Employed (ROCE), Return on Equity (ROE), Debt-to-Equity, Interest Coverage, and FCF Yield.
+- **DuPont Analysis**: 3-Stage and 5-Stage Return on Equity decomposition.
+- **Stock Screener**: Configurable screening filters and built-in strategy presets (`Quality Smallcap`, `Deep Value`, `High Compounder`).
+- **5-Year FCFF DCF Valuation**: Enterprise value and intrinsic equity value per share with a 2D sensitivity grid (WACC vs. Terminal Growth Rate).
+- **Export & Visualization**: Publication-grade charts and multi-tab formatted Excel workbooks (`.xlsx`).
+- **Command Line & Notebook Interfaces**: Clean CLI powered by Rich and Typer, plus interactive Jupyter tutorial notebooks.
+
+## Installation
+
+```bash
+pip install indiequity
+```
+
+Or install in development mode from source:
+```bash
+git clone https://github.com/AnonyyMouse/indiequity.git
+cd indiequity
+pip install -e .
+```
+
+## Quickstart
+
+### Python API
+```python
+import indiequity as ie
+
+# 1. Fetch public financial profile
+profile = ie.fetch_company_data("ITC")
+
+# 2. Compute key financial ratios
+ratios = ie.calculate_ratios(profile)
+print(f"Company:   {profile.company_name}")
+print(f"Mcap:      {ie.format_crores(ratios.market_cap)}")
+print(f"ROCE:      {ie.format_percentage(ratios.roce)}")
+print(f"ROE:       {ie.format_percentage(ratios.roe)}")
+
+# 3. 5-Stage DuPont Decomposition
+dupont = ie.decompose_dupont_5stage(profile)
+print(f"Operating Margin: {ie.format_percentage(dupont.operating_margin)}")
+print(f"Tax Burden:       {dupont.tax_burden:.2f}x")
+print(f"Interest Burden:  {dupont.interest_burden:.2f}x")
+
+# 4. DCF Valuation & Sensitivity Analysis
+dcf = ie.calculate_dcf(profile, forecast_years=5, terminal_growth_rate=0.05)
+print(f"Intrinsic Value: ₹{dcf.intrinsic_value_per_share:,.2f} per share")
+print(dcf.sensitivity_table)
+```
+
+### Command Line Interface (CLI)
+```bash
+# View company ratios
+indiequity ratios ITC
+
+# View 5-stage DuPont decomposition
+indiequity dupont ITC --stages 5
+
+# Run 5-Year DCF with sensitivity table
+indiequity dcf ITC
+
+# Run stock screener
+indiequity screen --universe smallcap --preset quality-smallcap
+
+# Export complete research report to Excel
+indiequity export ITC --output itc_report.xlsx
+```
+
+## Known Limitations & Disclaimer
+- **Data Source**: Fundamental statements are sourced from public market feeds via `yfinance`. Corporate restructurings or unaudited quarterly results may occasionally require cross-checking with official BSE/NSE filings.
+- **Educational / Research Use Only**: This toolkit is created by equity research students for educational, academic, and screening purposes. It does not constitute investment advice or SEBI-registered advisory recommendations.
+
+## License
+Distributed under the MIT License. See `LICENSE` for details.

indiequity-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "indiequity"
+version = "0.1.0"
+description = "Indian equity research toolkit for NSE/BSE fundamental analysis, ratios, screening, and DCF valuation."
+readme = "README.md"
+authors = [
+    { name = "Ayush", email = "anon.yy.mouse.712@gmail.com" }
+]
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+keywords = [
+    "finance",
+    "equity-research",
+    "nse",
+    "bse",
+    "nifty",
+    "dcf-valuation",
+    "fundamental-analysis",
+    "dupont-analysis",
+    "india-stock-market",
+    "stock-screener"
+]
+requires-python = ">=3.10"
+dependencies = [
+    "yfinance>=0.2.40",
+    "pandas>=2.0.0",
+    "numpy>=1.24.0",
+    "openpyxl>=3.1.0",
+    "matplotlib>=3.7.0",
+    "rich>=13.5.0",
+    "typer>=0.12.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+    "ruff>=0.4.0",
+    "build>=1.2.0",
+    "twine>=5.0.0",
+    "jupyter>=1.0.0",
+]
+
+[project.scripts]
+indiequity = "indiequity.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"

indiequity-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

indiequity-0.1.0/src/indiequity/__init__.py

@@ -0,0 +1,89 @@
+"""
+indiequity: Indian Equity Research Toolkit
+=========================================
+A Python toolkit for small-cap & mid-cap equity research on Indian markets (NSE & BSE).
+Provides:
+- Public fundamental financial statement ingestion
+- Core ratios: ROE, ROCE, Debt/Equity, Interest Coverage, EV/EBITDA, FCF Yield
+- 3-Stage and 5-Stage DuPont decomposition
+- Configurable stock screening with preset Indian investment strategies
+- 5-Year FCFF DCF valuation engine with 2D sensitivity analysis
+- Visual charting and Excel/CSV export
+"""
+
+from indiequity.cache import FinancialCache
+from indiequity.charts import plot_dcf_waterfall, plot_dupont_5stage
+from indiequity.config import (
+    CRORE_DIVISOR,
+    DEFAULT_EQUITY_RISK_PREMIUM,
+    DEFAULT_RISK_FREE_RATE,
+    DEFAULT_TAX_RATE,
+    DEFAULT_TERMINAL_GROWTH_RATE,
+    format_crores,
+    format_percentage,
+    resolve_ticker,
+)
+from indiequity.data import FinancialProfile, fetch_company_data
+from indiequity.dcf import (
+    DCFResult,
+    calculate_dcf,
+    estimate_wacc,
+    generate_sensitivity_matrix,
+)
+from indiequity.dupont import (
+    DuPont3Stage,
+    DuPont5Stage,
+    decompose_dupont_3stage,
+    decompose_dupont_5stage,
+)
+from indiequity.export import export_screener_to_excel, export_to_csv, export_to_excel
+from indiequity.ratios import RatioMetrics, calculate_ratios
+from indiequity.screener import (
+    NIFTY_50_TICKERS,
+    NIFTY_SMALLCAP_PRESET,
+    PRESET_DEEP_VALUE,
+    PRESET_HIGH_COMPOUNDER,
+    PRESET_QUALITY_SMALLCAP,
+    ScreenerCriteria,
+    StockScreener,
+)
+
+__version__ = "0.1.0"
+__author__ = "Ayush"
+
+__all__ = [
+    "__version__",
+    "DEFAULT_RISK_FREE_RATE",
+    "DEFAULT_EQUITY_RISK_PREMIUM",
+    "DEFAULT_TERMINAL_GROWTH_RATE",
+    "DEFAULT_TAX_RATE",
+    "CRORE_DIVISOR",
+    "format_crores",
+    "format_percentage",
+    "resolve_ticker",
+    "FinancialCache",
+    "FinancialProfile",
+    "fetch_company_data",
+    "RatioMetrics",
+    "calculate_ratios",
+    "DuPont3Stage",
+    "DuPont5Stage",
+    "decompose_dupont_3stage",
+    "decompose_dupont_5stage",
+    "NIFTY_50_TICKERS",
+    "NIFTY_SMALLCAP_PRESET",
+    "ScreenerCriteria",
+    "StockScreener",
+    "PRESET_QUALITY_SMALLCAP",
+    "PRESET_DEEP_VALUE",
+    "PRESET_HIGH_COMPOUNDER",
+    "DCFResult",
+    "calculate_dcf",
+    "estimate_wacc",
+    "generate_sensitivity_matrix",
+    "plot_dupont_5stage",
+    "plot_dcf_waterfall",
+    "export_to_excel",
+    "export_screener_to_excel",
+    "export_to_csv",
+]

indiequity-0.1.0/src/indiequity/cache.py

@@ -0,0 +1,123 @@
+"""
+Local caching layer for financial statement data using SQLite.
+
+Prevents rate-limiting and IP bans by public data sources (Yahoo Finance)
+when screening across large universes of Indian stocks.
+"""
+
+import io
+import json
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+import pandas as pd
+
+
+class FinancialCache:
+    """
+    Lightweight SQLite cache for financial profiles and statement DataFrames.
+    Default cache location: ~/.cache/indiequity/market_cache.db
+    """
+
+    def __init__(self, db_path: Optional[str] = None, ttl_seconds: int = 86400):
+        """
+        Args:
+            db_path: Path to SQLite database file. Defaults to user cache folder.
+            ttl_seconds: Cache validity duration in seconds (defaults to 24 hours).
+        """
+        if db_path is None:
+            cache_dir = Path.home() / ".cache" / "indiequity"
+            cache_dir.mkdir(parents=True, exist_ok=True)
+            self.db_path = str(cache_dir / "market_cache.db")
+        else:
+            self.db_path = db_path
+            Path(self.db_path).parent.mkdir(parents=True, exist_ok=True)
+
+        self.ttl_seconds = ttl_seconds
+        self._init_db()
+
+    def _init_db(self) -> None:
+        """Create tables if they do not exist."""
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.cursor()
+            cursor.execute("""
+                CREATE TABLE IF NOT EXISTS company_cache (
+                    symbol TEXT PRIMARY KEY,
+                    updated_at REAL,
+                    info_json TEXT,
+                    income_json TEXT,
+                    balance_json TEXT,
+                    cashflow_json TEXT
+                )
+            """)
+            conn.commit()
+
+    def get(self, symbol: str) -> Optional[Dict[str, Any]]:
+        """
+        Retrieve cached company financial statements if not expired.
+
+        Returns:
+            Dictionary with parsed DataFrames and info dictionary, or None if expired/missing.
+        """
+        symbol_clean = symbol.strip().upper()
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.cursor()
+            cursor.execute(
+                "SELECT updated_at, info_json, income_json, balance_json, cashflow_json FROM company_cache WHERE symbol = ?",
+                (symbol_clean,),
+            )
+            row = cursor.fetchone()
+
+        if not row:
+            return None
+
+        updated_at, info_json, inc_json, bal_json, cf_json = row
+        # Check TTL
+        if (time.time() - updated_at) > self.ttl_seconds:
+            return None
+
+        try:
+            info = json.loads(info_json) if info_json else {}
+            income_stmt = pd.read_json(io.StringIO(inc_json)) if inc_json else pd.DataFrame()
+            balance_sheet = pd.read_json(io.StringIO(bal_json)) if bal_json else pd.DataFrame()
+            cash_flow = pd.read_json(io.StringIO(cf_json)) if cf_json else pd.DataFrame()
+            return {
+                "info": info,
+                "income_stmt": income_stmt,
+                "balance_sheet": balance_sheet,
+                "cash_flow": cash_flow,
+            }
+        except Exception:
+            return None
+
+    def set(
+        self,
+        symbol: str,
+        info: Dict[str, Any],
+        income_stmt: pd.DataFrame,
+        balance_sheet: pd.DataFrame,
+        cash_flow: pd.DataFrame,
+    ) -> None:
+        """Store financial statements in local SQLite cache."""
+        symbol_clean = symbol.strip().upper()
+        info_json = json.dumps(info, default=str)
+        inc_json = income_stmt.to_json() if income_stmt is not None else ""
+        bal_json = balance_sheet.to_json() if balance_sheet is not None else ""
+        cf_json = cash_flow.to_json() if cash_flow is not None else ""
+
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.cursor()
+            cursor.execute("""
+                INSERT OR REPLACE INTO company_cache (
+                    symbol, updated_at, info_json, income_json, balance_json, cashflow_json
+                ) VALUES (?, ?, ?, ?, ?, ?)
+            """, (symbol_clean, time.time(), info_json, inc_json, bal_json, cf_json))
+            conn.commit()
+
+    def clear(self) -> None:
+        """Clear all entries in the cache."""
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.cursor()
+            cursor.execute("DELETE FROM company_cache")
+            conn.commit()

indiequity-0.1.0/src/indiequity/charts.py

@@ -0,0 +1,142 @@
+"""
+Financial charting module for Indian equity research using Matplotlib.
+
+Generates publication-grade charts:
+1. DuPont 5-Stage decomposition bar chart
+2. DCF Enterprise Value to Equity Value waterfall bridge
+3. Valuation & profitability ratios summary
+"""
+
+from pathlib import Path
+from typing import Optional
+import matplotlib
+matplotlib.use("Agg")  # Non-interactive backend safe for headless environments and servers
+import matplotlib.pyplot as plt
+import numpy as np
+
+from indiequity.config import CRORE_DIVISOR
+from indiequity.dcf import DCFResult
+from indiequity.dupont import DuPont5Stage
+from indiequity.ratios import RatioMetrics
+
+
+def plot_dupont_5stage(d5: DuPont5Stage, save_path: Optional[str] = None) -> plt.Figure:
+    """
+    Generate a 5-Stage DuPont ROE Decomposition Bar Chart.
+
+    Args:
+        d5: DuPont5Stage object.
+        save_path: Optional file path to save the chart as PNG.
+
+    Returns:
+        matplotlib Figure object.
+    """
+    labels = [
+        "Tax Burden\n(NI / EBT)",
+        "Interest Burden\n(EBT / EBIT)",
+        "Operating Margin\n(EBIT / Rev)",
+        "Asset Turnover\n(Rev / Assets)",
+        "Equity Multiplier\n(Assets / Equity)",
+    ]
+    values = [
+        d5.tax_burden,
+        d5.interest_burden,
+        d5.operating_margin,
+        d5.asset_turnover,
+        d5.equity_multiplier,
+    ]
+
+    fig, ax = plt.subplots(figsize=(10, 5), dpi=150)
+    colors = ["#2b5c8f", "#3b75af", "#4f92d1", "#289672", "#e28743"]
+
+    bars = ax.bar(labels, values, color=colors, width=0.55, edgecolor="#1c2d42", linewidth=1.2)
+
+    # Add data labels
+    for bar in bars:
+        height = bar.get_height()
+        ax.annotate(
+            f"{height:.2f}x" if height > 1 else f"{height * 100:.1f}%",
+            xy=(bar.get_x() + bar.get_width() / 2, height),
+            xytext=(0, 4),
+            textcoords="offset points",
+            ha="center",
+            va="bottom",
+            fontsize=10,
+            fontweight="bold",
+        )
+
+    ax.set_title(
+        f"DuPont 5-Stage ROE Breakdown: {d5.symbol}\nCalculated ROE = {d5.calculated_roe * 100:.2f}%",
+        fontsize=13,
+        fontweight="bold",
+        pad=15,
+    )
+    ax.set_ylabel("Factor Multiplier / Margin", fontsize=11)
+    ax.grid(axis="y", linestyle="--", alpha=0.4)
+    plt.tight_layout()
+
+    if save_path:
+        Path(save_path).parent.mkdir(parents=True, exist_ok=True)
+        plt.savefig(save_path, bbox_inches="tight")
+
+    return fig
+
+
+def plot_dcf_waterfall(dcf: DCFResult, save_path: Optional[str] = None) -> plt.Figure:
+    """
+    Generate a DCF Enterprise Value to Equity Value Bridge Chart (in ₹ Crores).
+
+    Args:
+        dcf: DCFResult object.
+        save_path: Optional file path to save the chart as PNG.
+
+    Returns:
+        matplotlib Figure object.
+    """
+    labels = ["PV of 5Y FCF", "PV of Terminal Val", "Enterprise Value", "+ Cash", "- Debt", "Implied Equity Val"]
+    
+    pv_5y_cr = dcf.sum_pv_fcff / CRORE_DIVISOR
+    pv_tv_cr = dcf.pv_terminal_value / CRORE_DIVISOR
+    ev_cr = dcf.enterprise_value / CRORE_DIVISOR
+    cash_cr = dcf.cash_and_equivalents / CRORE_DIVISOR
+    debt_cr = dcf.total_debt / CRORE_DIVISOR
+    eq_val_cr = dcf.implied_equity_value / CRORE_DIVISOR
+
+    values = [pv_5y_cr, pv_tv_cr, ev_cr, cash_cr, -debt_cr, eq_val_cr]
+    colors = ["#2b5c8f", "#3b75af", "#1f4e78", "#289672", "#c0392b", "#16a085"]
+
+    fig, ax = plt.subplots(figsize=(11, 5.5), dpi=150)
+    bars = ax.bar(labels, values, color=colors, width=0.55, edgecolor="#1c2d42", linewidth=1.2)
+
+    for bar, val in zip(bars, values):
+        height = bar.get_height()
+        va = "bottom" if height >= 0 else "top"
+        ax.annotate(
+            f"₹{abs(val):,.1f} Cr",
+            xy=(bar.get_x() + bar.get_width() / 2, height),
+            xytext=(0, 4 if height >= 0 else -12),
+            textcoords="offset points",
+            ha="center",
+            va=va,
+            fontsize=9.5,
+            fontweight="bold",
+        )
+
+    ax.axhline(0, color="black", linewidth=0.8, linestyle="--")
+    ax.set_title(
+        f"DCF Valuation Bridge: {dcf.symbol} ({dcf.company_name})\n"
+        f"Intrinsic Value: ₹{dcf.intrinsic_value_per_share:,.2f} | Current Price: ₹{dcf.current_price:,.2f} "
+        f"({dcf.upside_downside_pct * 100:+.1f}% Upside)",
+        fontsize=12.5,
+        fontweight="bold",
+        pad=15,
+    )
+    ax.set_ylabel("Value in ₹ Crores", fontsize=11)
+    ax.grid(axis="y", linestyle="--", alpha=0.4)
+    plt.tight_layout()
+
+    if save_path:
+        Path(save_path).parent.mkdir(parents=True, exist_ok=True)
+        plt.savefig(save_path, bbox_inches="tight")
+
+    return fig