bfinance 0.1.0__py3-none-any.whl

bfinance/__init__.py

@@ -0,0 +1,64 @@
+"""
+bfinance — High-performance Python SDK for Indian Equities (NSE & BSE).
+A 1:1 drop-in replacement for yfinance (1.7.0+ compatible) supercharged with 10-year financials, concalls, and live market microstructure.
+"""
+
+from .ticker import Ticker
+from .tickers import Tickers
+from .screens import Screen, screens
+from .download import download
+from .sector import Sector, Industry
+from .screener.client import ScreenerClient
+from .market.fast_info import FastInfo
+from .market.ratios import ScreenerRatioSearch, CustomRatiosCalculator
+from .models.company import CompanyProfile, Concall, PeerStock, TopRatios
+from .models.options import OptionChain, OptionContract
+from .models.statements import FinancialStatement
+from .utils.excel import FinancialModelExcelExporter
+from .utils.downloader import DocumentDownloader
+from .ai.context import AIContextBuilder
+from .ai.prompts import AIPromptFactory
+from .ai.tools import BFinanceAITools
+from .utils.exceptions import (
+    BFinanceError,
+    TickerNotFoundError,
+    UpstreamServiceError,
+    RateLimitExceededError,
+)
+
+ratios = ScreenerRatioSearch()
+
+__version__ = "0.1.0"
+__author__ = "bfinance contributors"
+
+__all__ = [
+    "Ticker",
+    "Tickers",
+    "Sector",
+    "Industry",
+    "Screen",
+    "screens",
+    "ratios",
+    "download",
+    "FastInfo",
+    "ScreenerClient",
+    "CompanyProfile",
+    "Concall",
+    "PeerStock",
+    "TopRatios",
+    "OptionChain",
+    "OptionContract",
+    "FinancialStatement",
+    "FinancialModelExcelExporter",
+    "DocumentDownloader",
+    "AIContextBuilder",
+    "AIPromptFactory",
+    "BFinanceAITools",
+    "ScreenerRatioSearch",
+    "CustomRatiosCalculator",
+    "BFinanceError",
+    "TickerNotFoundError",
+    "UpstreamServiceError",
+    "RateLimitExceededError",
+    "__version__",
+]

bfinance/ai/__init__.py

@@ -0,0 +1,13 @@
+"""
+AI Integration Engine for bfinance: Context generation, Institutional Prompt Templates, and Agent Tool Schemas.
+"""
+
+from .context import AIContextBuilder
+from .prompts import AIPromptFactory
+from .tools import BFinanceAITools
+
+__all__ = [
+    "AIContextBuilder",
+    "AIPromptFactory",
+    "BFinanceAITools",
+]

bfinance/ai/context.py

@@ -0,0 +1,194 @@
+"""
+AI Context Engine: Formats and serializes 100% of bfinance corporate data into
+token-optimized, highly structured Markdown, JSON, and text representations for LLMs.
+"""
+
+from typing import Any, Dict, List, Literal, Optional, Set
+import json
+import pandas as pd
+
+from bfinance.models.company import CompanyProfile
+
+
+class AIContextBuilder:
+    """
+    Constructs comprehensive AI-ready context dossiers from CompanyProfile.
+    Supports token-efficient Markdown, JSON Schema, and plain dense text.
+    """
+
+    @classmethod
+    def build_markdown_context(
+        cls,
+        profile: CompanyProfile,
+        include_sections: Optional[Set[str]] = None,
+        max_quarters: int = 8,
+        max_years: int = 7,
+        max_concalls: int = 5,
+    ) -> str:
+        """
+        Generate dense, professional Markdown formatted financial context for LLMs.
+        """
+        all_sections = {
+            "metadata", "valuation", "income_stmt", "quarters",
+            "balance_sheet", "cash_flow", "shareholding", "ratios",
+            "cagrs", "analysis", "concalls", "peers", "documents"
+        }
+        active = include_sections or all_sections
+
+        lines: List[str] = []
+        r = profile.ratios
+
+        # 1. Metadata
+        if "metadata" in active:
+            lines.append(f"# FINANCIAL DOSSIER: {profile.name} (NSE: {profile.nse_symbol or profile.symbol} | BSE: {profile.bse_code or 'N/A'})")
+            lines.append(f"**Sector**: {profile.sector or 'N/A'} | **Industry**: {profile.industry or 'N/A'} | **Sub-Industry**: {profile.sub_industry or 'N/A'}")
+            if profile.indices:
+                lines.append(f"**Index Memberships**: {', '.join(profile.indices[:6])}")
+            if profile.about:
+                lines.append(f"\n### Business Description\n{profile.about}")
+
+        # 2. Key Valuation & Financial Ratios
+        if "valuation" in active:
+            lines.append("\n## Current Valuation & Quality Metrics")
+            lines.append(f"- **Current Market Price (CMP)**: ₹{r.current_price:,.2f}" if r.current_price else "- **CMP**: N/A")
+            lines.append(f"- **Market Capitalization**: ₹{r.market_cap:,.2f} Cr" if r.market_cap else "- **Market Cap**: N/A")
+            lines.append(f"- **52-Week Range**: ₹{r.low_52w:,.2f} - ₹{r.high_52w:,.2f}" if r.low_52w and r.high_52w else "")
+            lines.append(f"- **Stock P/E**: {r.stock_pe:.2f}x | **Book Value**: ₹{r.book_value:,.2f}" if r.stock_pe and r.book_value else "")
+            lines.append(f"- **ROCE**: {r.roce:.2f}% | **ROE**: {r.roe:.2f}%" if r.roce and r.roe else "")
+            lines.append(f"- **Dividend Yield**: {r.dividend_yield:.2f}% | **Face Value**: ₹{r.face_value}" if r.dividend_yield is not None else "")
+            if r.debt_to_equity is not None:
+                lines.append(f"- **Debt to Equity**: {r.debt_to_equity:.2f}")
+
+        # 3. Annual Income Statement
+        if "income_stmt" in active and not profile.profit_loss.empty:
+            lines.append(f"\n## Annual Income Statement (Last {max_years} Years in ₹ Cr)")
+            df_pnl = profile.profit_loss.to_dataframe(orient="columns")
+            if not df_pnl.empty:
+                cols = list(df_pnl.columns)[-max_years:]
+                lines.append(df_pnl[cols].to_markdown())
+
+        # 4. Quarterly Results
+        if "quarters" in active and not profile.quarters.empty:
+            lines.append(f"\n## Quarterly Financial Results (Last {max_quarters} Quarters in ₹ Cr)")
+            df_q = profile.quarters.to_dataframe(orient="columns")
+            if not df_q.empty:
+                cols = list(df_q.columns)[-max_quarters:]
+                lines.append(df_q[cols].to_markdown())
+
+        # 5. Balance Sheet
+        if "balance_sheet" in active and not profile.balance_sheet.empty:
+            lines.append(f"\n## Annual Balance Sheet (Last {max_years} Years in ₹ Cr)")
+            df_bs = profile.balance_sheet.to_dataframe(orient="columns")
+            if not df_bs.empty:
+                cols = list(df_bs.columns)[-max_years:]
+                lines.append(df_bs[cols].to_markdown())
+
+        # 6. Cash Flow Statement
+        if "cash_flow" in active and not profile.cash_flow.empty:
+            lines.append(f"\n## Cash Flow Statement (Last {max_years} Years in ₹ Cr)")
+            df_cf = profile.cash_flow.to_dataframe(orient="columns")
+            if not df_cf.empty:
+                cols = list(df_cf.columns)[-max_years:]
+                lines.append(df_cf[cols].to_markdown())
+
+        # 7. Shareholding Pattern Trends
+        if "shareholding" in active:
+            lines.append("\n## Institutional Shareholding Distribution (%)")
+            df_sh = profile.shareholding.to_dataframe(orient="columns")
+            if not df_sh.empty:
+                lines.append("### Quarterly Trend (Recent Quarters)")
+                lines.append(df_sh.iloc[:, -6:].to_markdown())
+
+            df_shy = profile.shareholding_yearly.to_dataframe(orient="columns")
+            if not df_shy.empty:
+                lines.append("\n### 10-Year Annual Trend")
+                lines.append(df_shy.iloc[:, -6:].to_markdown())
+
+        # 8. Operating Ratios History
+        if "ratios" in active and not profile.ratios_history.empty:
+            lines.append("\n## Historical Operating Ratios & Efficiency Metrics")
+            df_rh = profile.ratios_history.to_dataframe(orient="columns")
+            if not df_rh.empty:
+                lines.append(df_rh.iloc[:, -max_years:].to_markdown())
+
+        # 9. Compounded CAGRs
+        if "cagrs" in active and profile.cagrs:
+            lines.append("\n## Compounded Annual Growth Rates (CAGR %)")
+            for k, v in profile.cagrs.items():
+                vals = " | ".join([f"{time_k}: {val}" for time_k, val in v.items()])
+                lines.append(f"- **{k}**: {vals}")
+
+        # 10. Qualitative Insights (Pros & Cons)
+        if "analysis" in active and (profile.analysis.pros or profile.analysis.cons):
+            lines.append("\n## Qualitative Analysis (Pros & Cons)")
+            if profile.analysis.pros:
+                lines.append("### Key Strengths (Pros)")
+                for p in profile.analysis.pros:
+                    lines.append(f"- [PRO] {p}")
+            if profile.analysis.cons:
+                lines.append("### Key Risks & Concerns (Cons)")
+                for c in profile.analysis.cons:
+                    lines.append(f"- [CON] {c}")
+
+        # 11. Earnings Conference Calls
+        if "concalls" in active and profile.concalls:
+            lines.append(f"\n## Recent Conference Calls & Transcripts (Latest {max_concalls})")
+            for call in profile.concalls[:max_concalls]:
+                audio_tag = f" | [Audio MP3]({call.audio_url})" if call.audio_url else ""
+                transcript_tag = f" | [PDF Transcript]({call.transcript_url})" if call.transcript_url else ""
+                lines.append(f"- **{call.date}**: {call.title}{transcript_tag}{audio_tag}")
+
+        # 12. Peer Benchmarking
+        if "peers" in active and profile.peers:
+            lines.append("\n## Industry Peer Comparison Matrix")
+            df_peers = profile.peers_dataframe()
+            if not df_peers.empty:
+                peer_cols = [c for c in ["rank", "name", "cmp", "pe", "market_cap_cr", "roce", "dividend_yield"] if c in df_peers.columns]
+                lines.append(df_peers[peer_cols].head(8).to_markdown(index=False))
+
+        return "\n".join([line for line in lines if line.strip() != ""])
+
+    @classmethod
+    def build_json_context(cls, profile: CompanyProfile) -> Dict[str, Any]:
+        """
+        Generate structured nested JSON dictionary format for tool outputs and function calls.
+        """
+        r = profile.ratios
+        return {
+            "symbol": profile.symbol,
+            "company_name": profile.name,
+            "bse_code": profile.bse_code,
+            "nse_symbol": profile.nse_symbol,
+            "sector": profile.sector,
+            "industry": profile.industry,
+            "sub_industry": profile.sub_industry,
+            "indices": profile.indices,
+            "about": profile.about,
+            "valuation": {
+                "current_price": r.current_price,
+                "market_cap_cr": r.market_cap,
+                "high_52w": r.high_52w,
+                "low_52w": r.low_52w,
+                "pe_ratio": r.stock_pe,
+                "book_value": r.book_value,
+                "dividend_yield_pct": r.dividend_yield,
+                "roce_pct": r.roce,
+                "roe_pct": r.roe,
+                "face_value": r.face_value,
+                "debt_to_equity": r.debt_to_equity,
+                "peg_ratio": r.peg_ratio,
+            },
+            "cagrs": profile.cagrs,
+            "pros_and_cons": {
+                "pros": profile.analysis.pros,
+                "cons": profile.analysis.cons,
+            },
+            "annual_pnl": profile.profit_loss.rows,
+            "quarterly_pnl": profile.quarters.rows,
+            "balance_sheet": profile.balance_sheet.rows,
+            "cash_flow": profile.cash_flow.rows,
+            "shareholding_quarterly": profile.shareholding.rows,
+            "shareholding_yearly": profile.shareholding_yearly.rows,
+            "concalls": [c.model_dump() for c in profile.concalls[:10]],
+            "peers": [p.model_dump() for p in profile.peers[:8]],
+        }

bfinance/ai/prompts.py

@@ -0,0 +1,81 @@
+"""
+Institutional LLM Prompt Templates for Financial Analysis and Decision-Making.
+"""
+
+from typing import Optional
+from bfinance.models.company import CompanyProfile
+from bfinance.ai.context import AIContextBuilder
+
+
+class AIPromptFactory:
+    """
+    Constructs institutional-grade system and user prompts for AI equity analysis.
+    """
+
+    @classmethod
+    def investment_memo(cls, profile: CompanyProfile, custom_instructions: str = "") -> str:
+        """
+        Generate an institutional initiation coverage / investment memo prompt.
+        """
+        context = AIContextBuilder.build_markdown_context(profile)
+        instructions = custom_instructions or (
+            "You are a Senior Principal at a top-tier Indian Long-Only Equity Fund.\n"
+            "Analyze the provided financial dossier and draft a rigorous Investment Initiation Note.\n"
+            "Include:\n"
+            "1. Executive Summary & Investment Thesis (Key Moats, Catalysts, Risks)\n"
+            "2. Business Model & Industry Dynamics (Competitive Positioning, Pricing Power)\n"
+            "3. Financial Quality Breakdown (Revenue Quality, Margin Durability, Capital Allocation, ROCE trends)\n"
+            "4. Capital Structure & Balance Sheet Health (Working capital, debt trajectory, Cash Conversion Cycle)\n"
+            "5. Ownership & Institutional Flow Analysis (Promoter pledge, FII vs DII trajectory)\n"
+            "6. Valuation Multiples & Fair Value Range (Historical PE vs Growth, DCF expectations)\n"
+            "7. Key Downside Risks & Invalidation Triggers"
+        )
+
+        return (
+            f"<INSTRUCTIONS>\n{instructions}\n</INSTRUCTIONS>\n\n"
+            f"<COMPANY_FINANCIAL_DOSSIER>\n{context}\n</COMPANY_FINANCIAL_DOSSIER>\n\n"
+            "Please write the comprehensive investment memo now."
+        )
+
+    @classmethod
+    def forensic_audit(cls, profile: CompanyProfile) -> str:
+        """
+        Generate a forensic accounting audit prompt to identify red flags and earnings manipulation.
+        """
+        context = AIContextBuilder.build_markdown_context(profile)
+        return (
+            "<INSTRUCTIONS>\n"
+            "You are an expert Forensic Accounting Auditor specializing in Indian listed equities.\n"
+            "Perform a forensic quality check on the provided financial statements.\n"
+            "Specifically examine and score (1 to 10):\n"
+            "1. Cash Flow vs Reported PAT Divergence (Is Operating Cash Flow lagging Net Profit?)\n"
+            "2. Working Capital Stress (Are Debtor Days or Inventory Days surging?)\n"
+            "3. Other Income Dependency (Is Other Income inflating Operating PBT?)\n"
+            "4. Depreciation & CWIP Capitalization Shenanigans (Is Capex stuck in CWIP?)\n"
+            "5. Promoter Pledge & Stake Dilution\n"
+            "6. Auditor Observations or Material Related Party Transactions (if indicated in notes)\n"
+            "Provide a final 'Forensic Risk Rating' (Low, Medium, High, Extreme Red Flag) with detailed justification.\n"
+            "</INSTRUCTIONS>\n\n"
+            f"<COMPANY_FINANCIAL_DOSSIER>\n{context}\n</COMPANY_FINANCIAL_DOSSIER>\n\n"
+            "Please conduct the forensic audit now."
+        )
+
+    @classmethod
+    def concall_summary(cls, profile: CompanyProfile) -> str:
+        """
+        Generate prompt focusing on management commentary, concalls, and forward guidance.
+        """
+        context = AIContextBuilder.build_markdown_context(profile)
+        return (
+            "<INSTRUCTIONS>\n"
+            "You are an Equity Research Analyst covering Indian Markets.\n"
+            "Analyze the latest earnings conference calls, quarterly performance, and management commentary.\n"
+            "Extract:\n"
+            "1. Core Operational Highlights for the Latest Quarter\n"
+            "2. Forward Revenue, Margin, and Capex Guidance given by Management\n"
+            "3. Raw Q&A Analysis: Tough questions asked by institutional analysts and management's answers\n"
+            "4. Headwinds vs Tailwinds summary\n"
+            "</INSTRUCTIONS>\n\n"
+            f"<COMPANY_FINANCIAL_DOSSIER>\n{context}\n</COMPANY_FINANCIAL_DOSSIER>\n\n"
+            "Please summarize the management commentary and forward guidance now."
+        )

bfinance/ai/tools.py

@@ -0,0 +1,93 @@
+"""
+Agent Function Calling & Tool Specifications for OpenAI, Gemini, Anthropic, LangChain, and LiteLLM.
+"""
+
+from typing import Any, Callable, Dict, List, Optional
+import json
+from bfinance.ticker import Ticker
+from bfinance.screens import screens
+from bfinance.ai.context import AIContextBuilder
+
+
+class BFinanceAITools:
+    """
+    Standard Function Calling / Tool specifications for AI Agents.
+    """
+
+    @classmethod
+    def get_openai_tools(cls) -> List[Dict[str, Any]]:
+        """
+        Return OpenAI / Gemini / LiteLLM function calling schemas.
+        """
+        return [
+            {
+                "type": "function",
+                "function": {
+                    "name": "get_stock_dossier",
+                    "description": "Fetch 100% of financial statements, valuation ratios, 10Y CAGRs, shareholding, and concall media for an Indian stock (NSE/BSE).",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "symbol": {
+                                "type": "string",
+                                "description": "NSE or BSE stock symbol, e.g. 'RELIANCE', 'TCS', 'HDFCBANK', 'BAJAJ-AUTO'."
+                            },
+                            "format": {
+                                "type": "string",
+                                "enum": ["markdown", "json"],
+                                "description": "Output format ('markdown' for direct LLM reasoning, 'json' for structured processing).",
+                                "default": "markdown"
+                            }
+                        },
+                        "required": ["symbol"]
+                    }
+                }
+            },
+            {
+                "type": "function",
+                "function": {
+                    "name": "run_institutional_screen",
+                    "description": "Run institutional quantitative stock screener across Indian equities (Coffee Can, Magic Formula, Debt Free Compounders, High Dividend, Undervalued Growth).",
+                    "parameters": {
+                        "type": "object",
+                        "properties": {
+                            "screen_name": {
+                                "type": "string",
+                                "enum": ["coffee_can", "magic_formula", "debt_free_compounders", "high_dividend_yield", "undervalued_growth"],
+                                "description": "The institutional strategy to execute."
+                            },
+                            "max_stocks": {
+                                "type": "integer",
+                                "description": "Maximum matching stocks to return.",
+                                "default": 10
+                            }
+                        },
+                        "required": ["screen_name"]
+                    }
+                }
+            }
+        ]
+
+    @classmethod
+    def execute_tool(cls, name: str, arguments: Dict[str, Any]) -> str:
+        """
+        Execute an AI tool call and return serialized string output.
+        """
+        if name == "get_stock_dossier":
+            symbol = arguments.get("symbol", "")
+            out_fmt = arguments.get("format", "markdown")
+            t = Ticker(symbol)
+            if out_fmt == "json":
+                return json.dumps(t.to_ai_context(format="json"), indent=2)
+            return t.to_ai_context(format="markdown")
+
+        elif name == "run_institutional_screen":
+            screen_name = arguments.get("screen_name", "coffee_can")
+            max_stocks = arguments.get("max_stocks", 10)
+            screen_obj = getattr(screens, screen_name, None)
+            if not screen_obj:
+                return f"Error: Screen '{screen_name}' not found."
+            df = screen_obj.run(max_stocks=max_stocks)
+            return df.to_markdown(index=False)
+
+        return f"Error: Unknown tool function '{name}'."

bfinance/cache/__init__.py

@@ -0,0 +1,7 @@
+"""
+Cache layer for bfinance.
+"""
+
+from .sqlite_cache import SQLiteCache
+
+__all__ = ["SQLiteCache"]

bfinance/cache/sqlite_cache.py

@@ -0,0 +1,121 @@
+"""
+Persistent SQLite caching layer with TTL support for bfinance.
+"""
+
+import json
+import os
+import sqlite3
+import time
+from typing import Any, Optional
+from pathlib import Path
+
+
+class SQLiteCache:
+    """
+    Lightweight, embedded SQLite cache for bfinance upstream queries.
+    Stores serialized JSON payloads with expiration timestamps.
+    """
+
+    def __init__(self, db_path: Optional[str] = None, default_ttl_hours: float = 24.0):
+        if db_path is None:
+            # Store in user home directory under ~/.bfinance/cache.db
+            home_dir = Path.home() / ".bfinance"
+            home_dir.mkdir(parents=True, exist_ok=True)
+            self.db_path = str(home_dir / "cache.db")
+        else:
+            self.db_path = db_path
+
+        self.default_ttl_hours = default_ttl_hours
+        self._init_db()
+
+    def _init_db(self):
+        """Create cache table and indexes if not exists."""
+        with sqlite3.connect(self.db_path) as conn:
+            cursor = conn.cursor()
+            cursor.execute(
+                """
+                CREATE TABLE IF NOT EXISTS bfinance_cache (
+                    cache_key TEXT PRIMARY KEY,
+                    category TEXT NOT NULL,
+                    payload TEXT NOT NULL,
+                    created_at REAL NOT NULL,
+                    expires_at REAL NOT NULL
+                )
+                """
+            )
+            cursor.execute(
+                "CREATE INDEX IF NOT EXISTS idx_cache_category ON bfinance_cache(category)"
+            )
+            cursor.execute(
+                "CREATE INDEX IF NOT EXISTS idx_cache_expires ON bfinance_cache(expires_at)"
+            )
+            conn.commit()
+
+    def get(self, cache_key: str) -> Optional[Any]:
+        """Retrieve unexpired cached payload."""
+        now = time.time()
+        try:
+            with sqlite3.connect(self.db_path) as conn:
+                cursor = conn.cursor()
+                cursor.execute(
+                    "SELECT payload, expires_at FROM bfinance_cache WHERE cache_key = ?",
+                    (cache_key,),
+                )
+                row = cursor.fetchone()
+                if row:
+                    payload_str, expires_at = row
+                    if expires_at > now:
+                        return json.loads(payload_str)
+                    else:
+                        # Expired, clean it up
+                        cursor.execute("DELETE FROM bfinance_cache WHERE cache_key = ?", (cache_key,))
+                        conn.commit()
+        except Exception:
+            return None
+        return None
+
+    def set(
+        self,
+        cache_key: str,
+        payload: Any,
+        category: str = "general",
+        ttl_hours: Optional[float] = None,
+    ):
+        """Store serialized payload with TTL."""
+        if ttl_hours is None:
+            ttl_hours = self.default_ttl_hours
+
+        now = time.time()
+        expires_at = now + (ttl_hours * 3600.0)
+        payload_str = json.dumps(payload)
+
+        try:
+            with sqlite3.connect(self.db_path) as conn:
+                cursor = conn.cursor()
+                cursor.execute(
+                    """
+                    INSERT INTO bfinance_cache (cache_key, category, payload, created_at, expires_at)
+                    VALUES (?, ?, ?, ?, ?)
+                    ON CONFLICT(cache_key) DO UPDATE SET
+                        payload = excluded.payload,
+                        created_at = excluded.created_at,
+                        expires_at = excluded.expires_at
+                    """,
+                    (cache_key, category, payload_str, now, expires_at),
+                )
+                conn.commit()
+        except Exception:
+            pass
+
+    def clear(self, category: Optional[str] = None):
+        """Clear all or category-specific cache entries."""
+        try:
+            with sqlite3.connect(self.db_path) as conn:
+                cursor = conn.cursor()
+                if category:
+                    cursor.execute("DELETE FROM bfinance_cache WHERE category = ?", (category,))
+                else:
+                    cursor.execute("DELETE FROM bfinance_cache")
+                conn.commit()
+        except Exception:
+            pass