quant-agent 0.3.0__py3-none-any.whl

quant_agent/fundamental.py

@@ -0,0 +1,580 @@
+"""
+Company fundamentals: stock listings, company profiles, financial statements
+and ratios, corporate events, dividend history.
+
+Data sources:
+  - Stock listing: Wifeed / Local CSV / SSI.
+  - Company overview, profile, shareholders, officers, subsidiaries, events, news: VCI (VietCap Securities).
+  - Financial statements and ratios: VCI (VietCap Securities).
+"""
+
+from bs4 import BeautifulSoup
+
+from .config import *
+
+# =============================================================================
+# STOCK LISTING
+# =============================================================================
+
+def live_stock_list ():
+    """
+    Return a DataFrame of all available stock symbols. Live data is retrieved from the API.
+    """
+    data = fetch_json('GET', "https://wifeed.vn/api/thong-tin-co-phieu/danh-sach-ma-chung-khoan", source='Wifeed')
+    if data is None:
+        return None
+    df = pd.DataFrame(data['data'])
+    df = df.rename(columns={'fullname_vi': 'organName', 'code': 'ticker', 'loaidn': 'organTypeCode', 'san': 'comGroupCode'})
+    return df
+
+def organ_listing (lang='vi', headers=ssi_headers):
+    """
+    Return a DataFrame of all available stock symbols. Live data is retrieved from the SSI API.
+    Parameters:
+        lang (str): language of the data. Default is 'vi', other options are 'en'
+        headers (dict): headers of the request
+    """
+    url = f"https://fiin-core.ssi.com.vn/Master/GetListOrganization?language={lang}"
+    data = fetch_json('GET', url, headers=headers, source='SSI')
+    if data is None:
+        return None
+    print('Total number of companies: ', data['totalCount'])
+    return pd.DataFrame(data['items'])
+
+def indices_listing (lang='vi', headers=ssi_headers):
+    """
+    Return a DataFrame of all available indices. Live data is retrieved from the SSI API.
+    Parameters:
+        lang (str): language of the data. Default is 'vi', other options are 'en'
+        headers (dict): headers of the request
+    """
+    url = f"https://fiin-core.ssi.com.vn/Master/GetAllCompanyGroup?language={lang}"
+    data = fetch_json('GET', url, headers=headers, source='SSI')
+    if data is None:
+        return None
+    df = pd.DataFrame(data['items'])
+    df = df.sort_values(by='comGroupOrder').reset_index(drop=True)
+    return df[['comGroupCode', 'parentComGroupCode', 'comGroupOrder']]
+
+def offline_stock_list (path):
+    """
+    This function returns the list of all available stock symbols from a csv file.
+    Parameters:
+        path (str): Path or URL of a CSV file containing stock symbols, in the same
+            column layout as listing_companies()'s output. No bundled default is
+            provided - point this at your own maintained copy.
+    Returns: df (DataFrame): A pandas dataframe containing the stock symbols and other information.
+    """
+    return pd.read_csv(path)
+
+def listing_companies (live=False, source='Wifeed', path=None):
+    """
+    This function returns the list of all available stock symbols from a csv file or a live api request.
+    Parameters:
+        live (bool): If True, return the list of all available stock symbols from a live api request. If False, read from the CSV given in `path`. Default is False.
+        path (str): Required when live=False - path or URL to your own offline CSV of stock symbols. No default is bundled.
+    Returns: df (DataFrame): A pandas dataframe containing the stock symbols and other information.
+    """
+    if not live:
+        if path is None:
+            print("listing_companies(live=False) requires a 'path' to your own CSV of stock "
+                  "symbols - no bundled default is provided. Pass path=... or use live=True "
+                  "to fetch the list from a live API instead.")
+            return None
+        return offline_stock_list(path)
+    if source == 'Wifeed':
+        return live_stock_list()
+    elif source == 'SSI':
+        return organ_listing()
+    print(f"Unknown source '{source}'. Use 'Wifeed' or 'SSI'.")
+    return None
+
+
+# =============================================================================
+# COMPANY OVERVIEW (VCI)
+# =============================================================================
+
+def company_overview (symbol):
+    """
+    This function returns the company overview of a target stock symbol.
+    Data source: VCI (VietCap Securities).
+    stockRating, deltaInWeek/Month/Year, or website).
+    Args:
+        symbol (:obj:`str`, required): 3 digits name of the desired stock.
+    """
+    url = f'https://iq.vietcap.com.vn/api/iq-insight-service/v1/company/details?ticker={symbol}'
+    payload = fetch_json('GET', url, headers=vci_headers, source='VCI')
+    if payload is None:
+        return None
+    data = payload.get('data')
+    if not data:
+        print(f'No company overview data returned by VCI for {symbol}.')
+        return None
+    df = json_normalize(data)
+    df = df.rename(columns={
+        'viOrganName': 'organName', 'enOrganName': 'organNameEn',
+        'viOrganShortName': 'shortName', 'enOrganShortName': 'shortNameEn',
+        'sectorVn': 'industry', 'sector': 'industryEn',
+        'enProfile': 'profileEn', 'numberOfSharesMktCap': 'outstandingShare',
+    })
+    keep_cols = ['ticker', 'organName', 'shortName', 'industry', 'industryEn',
+                 'listingDate', 'outstandingShare', 'profile']
+    return df[[c for c in keep_cols if c in df.columns]]
+
+
+# =============================================================================
+# COMPANY PROFILE / OFFICERS / SHAREHOLDERS (VCI)
+# =============================================================================
+
+def company_profile (symbol='TCB', headers=None):
+    """
+    Return a DataFrame of the company's descriptive business profile.
+    Data source: VCI (VietCap Securities).
+    retired its API; reuses the same `company/details` endpoint as
+    `company_overview()`, extracting the long-form profile text instead of the
+    structured summary fields.
+    Parameters:
+    symbol (str): ticker of the company, default is 'TCB', other tickers available can be obtained from the function `listing_companies()`.
+    """
+    url = f'https://iq.vietcap.com.vn/api/iq-insight-service/v1/company/details?ticker={symbol}'
+    payload = fetch_json('GET', url, headers=vci_headers, source='VCI')
+    if payload is None:
+        return None
+    data = payload.get('data')
+    if not data:
+        print(f'No company profile data returned by VCI for {symbol}.')
+        return None
+    df = json_normalize(data)
+    df['ticker'] = symbol
+    # convert HTML-formatted text columns (profile, enProfile) to plain text
+    for col in df.columns:
+        try:
+            df[col] = df[col].apply(lambda x: BeautifulSoup(x, 'html.parser').get_text())
+            df[col] = df[col].str.replace('\n', ' ')
+        except (TypeError, AttributeError):
+            pass
+    keep_cols = ['ticker', 'profile', 'enProfile', 'listingDate', 'sectorVn', 'sector']
+    return df[[c for c in keep_cols if c in df.columns]]
+
+def _fetch_vci_shareholders(symbol):
+    """Shared fetcher for VCI's per-owner shareholder list, used by both
+    `company_large_shareholders()` and `company_officers()`."""
+    url = f'https://iq.vietcap.com.vn/api/iq-insight-service/v1/company/{symbol}/shareholder'
+    payload = fetch_json('GET', url, headers=vci_headers, source='VCI')
+    if payload is None:
+        return None
+    records = payload.get('data', [])
+    if not records:
+        print(f'No shareholder data returned by VCI for {symbol}.')
+        return None
+    df = json_normalize(records)
+    df['ticker'] = symbol
+    return df
+
+def company_large_shareholders (symbol='TCB', headers=None):
+    """
+    Return a DataFrame of company large shareholders data.
+    Data source: VCI (VietCap Securities).
+    Parameters:
+    symbol (str): ticker of the company, default is 'TCB'.
+    """
+    df = _fetch_vci_shareholders(symbol)
+    if df is None:
+        return None
+    df = df.rename(columns={'ownerName': 'shareHolder', 'percentage': 'shareOwnPercent', 'quantity': 'shareQuantity'})
+    keep_cols = ['ticker', 'shareHolder', 'ownerType', 'shareOwnPercent', 'shareQuantity', 'publicDate', 'updateDate']
+    df = df[[c for c in keep_cols if c in df.columns]]
+    return df.sort_values('shareOwnPercent', ascending=False).reset_index(drop=True)
+
+def company_fundamental_ratio (symbol='TCB', mode='simplify', missing_pct=0.8, headers=None):
+    """
+    Return a single-row DataFrame snapshot of the company's most recent
+    financial ratios (P/E, P/B, ROE, ROA, market cap, EPS, etc.).
+    Data source: VCI (VietCap Securities).
+    the same statistics-financial endpoint as `financial_ratio()`, but
+    returns only the most recent period as a single row (the closest
+    a full history.
+    Parameters:
+    symbol (str): ticker of the company, default is 'TCB'.
+    mode (str): 'simplify' drops any text/name-style columns; kept for backward compatibility.
+    missing_pct (float): drop columns with more than this fraction of missing values. Default 0.8.
+    """
+    request_headers = dict(vci_headers)
+    request_headers.update(vci_session_cookies())
+    url = f'https://iq.vietcap.com.vn/api/iq-insight-service/v1/company/{symbol}/statistics-financial'
+    payload = fetch_json('GET', url, headers=request_headers, source='VCI')
+    if payload is None:
+        return None
+    records = payload.get('data', [])
+    if not records:
+        print(f'No financial ratio data returned by VCI for {symbol}.')
+        return None
+    df = json_normalize(records)
+    df = df.dropna(axis=1, how='all')
+    df = df.sort_values(['yearReport', 'quarter'])
+    latest = df.tail(1).copy()
+    latest.insert(0, 'ticker', symbol)
+    if mode == 'simplify':
+        latest = latest.loc[:, ~latest.columns.str.contains('Name')]
+    return latest.loc[:, latest.isnull().mean() < missing_pct].reset_index(drop=True)
+
+def ticker_price_volatility (symbol='TCB', headers=None):
+    """
+    Return a DataFrame of ticker price/trading-range data.
+    Data source: VCI (VietCap Securities).
+    the same company/details endpoint as `company_overview()`. Note the
+    1-year high/low window plus a few point-in-time trading fields, not a
+    full week/month/quarter/year breakdown of price changes.
+    Parameters:
+    symbol (str): ticker of the company, default is 'TCB'.
+    """
+    url = f'https://iq.vietcap.com.vn/api/iq-insight-service/v1/company/details?ticker={symbol}'
+    payload = fetch_json('GET', url, headers=vci_headers, source='VCI')
+    if payload is None:
+        return None
+    data = payload.get('data')
+    if not data:
+        print(f'No price volatility data returned by VCI for {symbol}.')
+        return None
+    df = json_normalize(data)
+    keep_cols = ['ticker', 'currentPrice', 'marketCap', 'highestPrice1Year', 'lowestPrice1Year',
+                 'averageMatchVolume1Month', 'averageMatchValue1Month',
+                 'foreignerPercentage', 'maximumForeignPercentage', 'statePercentage']
+    df = df[[c for c in keep_cols if c in df.columns]]
+    df.columns = [c if c == 'ticker' else 'ticker_' + c for c in df.columns]
+    return df
+
+def company_insider_deals (symbol='TCB', page_size=20, page=0, headers=None):
+    """
+    Return a DataFrame of large-shareholder & insider trading transactions.
+    Data source: VCI (VietCap Securities) corporate events feed, filtered to
+    insider/large-shareholder dealing event codes (DDIND, DDINS, DDRP).
+    transaction as a free-text title combining name, action, and quantity
+    (e.g. "Nguyen Thu Lan - Subscribe to Buy 800,000 TCB shares") rather than
+    Parameters:
+    symbol (str): ticker of the company, default is 'TCB'.
+    page_size (int): number of items per page, default is 20.
+    page (int): page number, default is 0.
+    """
+    from_date = (datetime.now() - timedelta(days=365 * 10)).strftime('%Y%m%d')
+    to_date = datetime.now().strftime('%Y%m%d')
+    url = (f'https://iq.vietcap.com.vn/api/iq-insight-service/v1/events'
+           f'?ticker={symbol}&fromDate={from_date}&toDate={to_date}&eventCode=DDIND,DDINS,DDRP&page={page}&size={page_size}')
+    payload = fetch_json('GET', url, headers=vci_headers, source='VCI')
+    if payload is None:
+        return None
+    content = payload.get('data', {}).get('content', [])
+    if not content:
+        print(f'No insider dealing data returned by VCI for {symbol}.')
+        return None
+    df = json_normalize(content)
+    df = df.drop(columns=[c for c in ['organCode', 'organNameEn', 'organNameVi', '__typename'] if c in df.columns])
+    df = df.rename(columns={'eventTitleVi': 'dealTitle', 'actionTypeVi': 'dealAction', 'publicDate': 'dealAnnounceDate'})
+    if 'dealAnnounceDate' in df.columns:
+        df['dealAnnounceDate'] = pd.to_datetime(df['dealAnnounceDate'])
+        df = df.sort_values('dealAnnounceDate', ascending=False)
+    return df.reset_index(drop=True)
+
+def company_subsidiaries_listing (symbol='TCB', page_size=100, page=0, headers=None):
+    """
+    Return a DataFrame of company subsidiaries data.
+    Data source: VCI (VietCap Securities). Note
+    VCI returns the full subsidiaries list in one call (no pagination); the
+    `page_size`/`page` parameters are accepted for backward compatibility
+    but have no effect.
+    Parameters:
+    symbol (str): ticker of the company, default is 'TCB'.
+    """
+    url = f'https://iq.vietcap.com.vn/api/iq-insight-service/v1/company/{symbol}/relationship'
+    payload = fetch_json('GET', url, headers=vci_headers, source='VCI')
+    if payload is None:
+        return None
+    subsidiaries = (payload.get('data') or {}).get('subsidiaries', [])
+    if not subsidiaries:
+        print(f'No subsidiaries data returned by VCI for {symbol}.')
+        return None
+    df = json_normalize(subsidiaries)
+    df['ticker'] = symbol
+    df = df.rename(columns={'rightOrganNameVi': 'subCompanyName', 'rightOrganCode': 'subOrganCode', 'ownedPercentage': 'subOwnPercent'})
+    keep_cols = ['ticker', 'subCompanyName', 'subOrganCode', 'subOwnPercent']
+    return df[[c for c in keep_cols if c in df.columns]]
+
+def company_officers (symbol='TCB', page_size=20, page=0, headers=None):
+    """
+    Return a DataFrame of company officers data.
+    Data source: VCI (VietCap Securities) shareholder list, filtered to
+    individuals holding a named position - VCI has no dedicated
+    `page` are accepted for backward compatibility but have no effect (VCI
+    returns the full list in one call).
+    Parameters:
+    symbol (str): ticker of the company, default is 'TCB'.
+    """
+    df = _fetch_vci_shareholders(symbol)
+    if df is None:
+        return None
+    df = df[(df.get('ownerType') == 'INDIVIDUAL') & df.get('positionName').notna()]
+    if df.empty:
+        print(f'No officer data (individuals with a named position) returned by VCI for {symbol}.')
+        return None
+    df = df.rename(columns={'ownerName': 'officerName', 'positionName': 'officerPosition', 'percentage': 'officerOwnPercent', 'quantity': 'officerOwnQuantity'})
+    keep_cols = ['ticker', 'officerName', 'officerPosition', 'officerOwnPercent', 'officerOwnQuantity']
+    df = df[[c for c in keep_cols if c in df.columns]]
+    return df.sort_values(['officerOwnPercent', 'officerPosition'], ascending=False).reset_index(drop=True)
+
+def company_events (symbol='TPB', page_size=15, page=0, headers=None):
+    """
+    Return a DataFrame of ticker events data (dividends, share issuance,
+    insider dealing, AGM/EGM, M&A, etc.).
+    Data source: VCI (VietCap Securities) corporate events feed. Migrated
+    Parameters:
+    symbol (str): ticker of the company, default is 'TPB'.
+    page_size (int): number of records per page, default is 15.
+    page (int): page number, default is 0. You can increase the page number to get more events.
+    """
+    from_date = (datetime.now() - timedelta(days=365 * 10)).strftime('%Y%m%d')
+    to_date = datetime.now().strftime('%Y%m%d')
+    event_codes = 'DIV,ISS,DDIND,DDINS,DDRP,AGME,AGMR,EGME,AIS,MA,MOVE,NLIS,OTHE,RETU,SUSP'
+    url = (f'https://iq.vietcap.com.vn/api/iq-insight-service/v1/events'
+           f'?ticker={symbol}&fromDate={from_date}&toDate={to_date}&eventCode={event_codes}&page={page}&size={page_size}')
+    payload = fetch_json('GET', url, headers=vci_headers, source='VCI')
+    if payload is None:
+        return None
+    content = payload.get('data', {}).get('content', [])
+    if not content:
+        print(f'No events returned by VCI for {symbol}.')
+        return None
+    df = json_normalize(content)
+    return df.drop(columns=[c for c in ['organCode', 'organNameEn', 'organNameVi', '__typename'] if c in df.columns])
+
+def company_news (symbol='TCB', page_size=15, page=0, headers=None):
+    """
+    Return a DataFrame of ticker news data.
+    Data source: VCI (VietCap Securities).
+    Parameters:
+    symbol (str): ticker of the company, default is 'TCB'.
+    page_size (int): number of records per page, default is 15.
+    page (int): page number, default is 0. You can increase the page number to get more news.
+    """
+    from_date = (datetime.now() - timedelta(days=365 * 10)).strftime('%Y%m%d')
+    to_date = datetime.now().strftime('%Y%m%d')
+    url = (f'https://iq.vietcap.com.vn/api/iq-insight-service/v1/news'
+           f'?ticker={symbol}&fromDate={from_date}&toDate={to_date}&languageId=1&page={page}&size={page_size}')
+    payload = fetch_json('GET', url, headers=vci_headers, source='VCI')
+    if payload is None:
+        return None
+    content = payload.get('data', {}).get('content', [])
+    if not content:
+        print(f'No news returned by VCI for {symbol}.')
+        return None
+    df = json_normalize(content)
+    df['ticker'] = symbol
+    keep_cols = ['ticker', 'newsId', 'newsTitle', 'newsShortContent', 'newsSource', 'newsImageUrl', 'publicDate']
+    return df[[c for c in keep_cols if c in df.columns]]
+
+
+# =============================================================================
+# FINANCIAL STATEMENTS & RATIOS (VCI)
+# =============================================================================
+
+_VCI_SECTION_MAP = {'balancesheet': 'BALANCE_SHEET', 'incomestatement': 'INCOME_STATEMENT', 'cashflow': 'CASH_FLOW'}
+
+def _vci_financial_statement(symbol, report_type, frequency):
+    """
+    Shared VCI financial-statement fetcher used by both financial_report() and
+    financial_flow(). Returns a DataFrame with periods as rows and financial-statement
+    line items as columns (labelled in Vietnamese via VCI's metrics endpoint where
+    available), or None on error.
+    """
+    section = _VCI_SECTION_MAP.get(report_type.lower().replace('_', ''), report_type.upper())
+    headers = dict(vci_headers)
+    headers.update(vci_session_cookies())
+    url = f'https://iq.vietcap.com.vn/api/iq-insight-service/v1/company/{symbol}/financial-statement'
+    payload = fetch_json('GET', url, headers=headers, params={'section': section}, source='VCI')
+    if payload is None:
+        return None
+    data = payload.get('data', {})
+    key = 'years' if frequency.lower().startswith('year') else 'quarters'
+    records = data.get(key, [])
+    if not records:
+        print(f'No {report_type} data returned by VCI for {symbol} ({frequency}).')
+        return None
+    df = json_normalize(records)
+    # Best-effort: resolve cryptic field codes to Vietnamese labels via the metrics endpoint.
+    metrics_url = f'https://iq.vietcap.com.vn/api/iq-insight-service/v1/company/{symbol}/financial-statement/metrics'
+    metrics_payload = fetch_json('GET', metrics_url, headers=headers, source='VCI')
+    if metrics_payload is not None:
+        label_map = {
+            item['field']: item['titleVi']
+            for items in (metrics_payload.get('data') or {}).values()
+            for item in items
+            if 'field' in item and 'titleVi' in item
+        }
+        df = df.rename(columns=label_map)
+    return df
+
+def financial_report (symbol='SSI', report_type='BalanceSheet', frequency='Quarterly', headers=None): # Quarterly, Yearly
+    """
+    Return financial reports of a stock symbol by type and period.
+    Data source: VCI (VietCap Securities). Migrated from SSI in 2026 after SSI's
+    download endpoint started blocking automated requests via Cloudflare (403).
+    Note the output shape changed: rows are now reporting periods and columns are
+    line items (the old SSI Excel export had the opposite orientation).
+    Args:
+        symbol (:obj:`str`, required): 3 digits name of the desired stock.
+        report_type (:obj:`str`, required): BalanceSheet, IncomeStatement, CashFlow
+        frequency (:obj:`str`, required): Yearly or Quarterly.
+    """
+    return _vci_financial_statement(symbol, report_type, frequency)
+
+def financial_flow(symbol='TCB', report_type='incomestatement', report_range='quarterly', get_all=True): # incomestatement, balancesheet, cashflow
+    """
+    This function returns the financial statement line items of a stock symbol over time.
+    Data source: VCI (VietCap Securities).
+    its API. `financial_flow` and `financial_report` now source from the same VCI
+    endpoint; kept as a separate function for backward compatibility with existing code.
+    Args:
+        symbol (:obj:`str`, required): 3 digits name of the desired stock.
+        report_type (:obj:`str`, required): select one of 3 reports: incomestatement, balancesheet, cashflow.
+        report_range (:obj:`str`, required): yearly or quarterly.
+    """
+    df = _vci_financial_statement(symbol, report_type, report_range)
+    if df is None:
+        return None
+    year_col = 'year' if 'year' in df.columns else 'yearReport'
+    quarter_col = 'quarter' if 'quarter' in df.columns else 'lengthReport'
+    if report_range == 'yearly' and year_col in df.columns:
+        df = df.sort_values(year_col).set_index(year_col)
+    elif year_col in df.columns and quarter_col in df.columns:
+        df = df.sort_values([year_col, quarter_col])
+        df['index'] = df[year_col].astype(str).str.cat('-Q' + df[quarter_col].astype(str))
+        df = df.set_index('index').drop(columns=[year_col, quarter_col])
+    if not get_all:
+        df = df.tail(10)
+    return df
+
+def financial_ratio (symbol, report_range, is_all=False):
+    """
+    This function retrieves the essential financial ratios of a stock symbol on a quarterly or yearly basis. Some of the expected ratios include: P/E, P/B, ROE, ROA, BVPS, etc
+    Data source: VCI (VietCap Securities) statistics-financial endpoint. Migrated from
+    (e.g. BVPS) are not present in VCI's response.
+    Args:
+        symbol (:obj:`str`, required): 3 digits name of the desired stock.
+        report_range (:obj:`str`, required): 'yearly' or 'quarterly'.
+        is_all (:obj:`bool`, optional): Set to True to keep all available periods, False to keep only the 5 most recent. Default is False.
+    """
+    headers = dict(vci_headers)
+    headers.update(vci_session_cookies())
+    url = f'https://iq.vietcap.com.vn/api/iq-insight-service/v1/company/{symbol}/statistics-financial'
+    payload = fetch_json('GET', url, headers=headers, source='VCI')
+    if payload is None:
+        return None
+    records = payload.get('data', [])
+    if not records:
+        print(f'No financial ratio data returned by VCI for {symbol}.')
+        return None
+    df = json_normalize(records)
+    df = df.dropna(axis=1, how='all')
+    # VCI marks full-year figures with ratioType='RATIO_YEAR' (quarter=5, a sentinel) and
+    # trailing-twelve-month quarterly figures with ratioType='RATIO_TTM' (quarter=1..4).
+    if report_range == 'yearly':
+        df = df[df['ratioType'] == 'RATIO_YEAR']
+        df = df.sort_values('yearReport')
+        if not is_all:
+            df = df.tail(5)
+        df = df.set_index('yearReport')
+    elif report_range == 'quarterly':
+        df = df[df['ratioType'] == 'RATIO_TTM']
+        df = df.sort_values(['yearReport', 'quarter'])
+        if not is_all:
+            df = df.tail(10)
+        df['range'] = 'Q' + df['quarter'].astype(int).astype(str) + '-' + df['yearReport'].astype(int).astype(str)
+        df = df.set_index('range')
+    df = df.drop(columns=[c for c in ['quarter', 'ratioTTMId', 'ratioType', 'organCode', 'year'] if c in df.columns])
+    return df.T
+
+def financial_ratio_compare (symbol_ls=["CTG", "TCB", "ACB"], industry_comparison=True, frequency='Yearly', start_year=2010, headers=None):
+    """
+    This function compares financial ratios (P/E, P/B, ROE, ROA, etc.) of multiple
+    stock symbols side by side, for the most recent reporting period.
+    Data source: VCI (VietCap Securities), built on top of `financial_ratio()`.
+    Migrated from SSI in 2026 after SSI's Excel download endpoint started blocking
+    automated requests via Cloudflare (403).
+    Note: `industry_comparison` is no longer supported — VCI's statistics-financial
+    endpoint does not expose an industry-average aggregate, only per-company figures
+    (unlike the old SSI-based version). It is accepted for backward compatibility but
+    has no effect. `start_year` is also unused since VCI always returns its own
+    available history; use `financial_ratio()` directly if you need a specific range.
+    Args:
+        symbol_ls (:obj:`list`, required): list of stock symbols to compare, e.g. ["CTG", "TCB", "ACB"].
+        industry_comparison (:obj:`bool`, optional): unused, kept for backward compatibility.
+        frequency (:obj:`str`, required): 'Yearly' or 'Quarterly'.
+        start_year (:obj:`int`, optional): unused, kept for backward compatibility.
+    """
+    report_range = 'yearly' if frequency.lower().startswith('year') else 'quarterly'
+    columns = {}
+    for symbol in symbol_ls:
+        ratio_df = financial_ratio(symbol, report_range, is_all=False)
+        if ratio_df is None or ratio_df.empty:
+            print(f'Skipping {symbol}: no financial ratio data available from VCI.')
+            continue
+        columns[symbol] = ratio_df.iloc[:, -1]  # most recent period
+    if not columns:
+        print('No financial ratio data available for any of the requested symbols.')
+        return None
+    df = pd.DataFrame(columns)
+    df.index.name = 'Chỉ số'
+    return df
+
+def dividend_history (symbol):
+    """
+    This function returns the dividend historical data of the seed stock symbol.
+    Data source: VCI (VietCap Securities) corporate events feed, filtered to dividend
+    Args:
+        symbol (:obj:`str`, required): 3 digits name of the desired stock.
+    """
+    from_date = (datetime.now() - timedelta(days=365 * 15)).strftime('%Y%m%d')
+    to_date = datetime.now().strftime('%Y%m%d')
+    url = (f'https://iq.vietcap.com.vn/api/iq-insight-service/v1/events'
+           f'?ticker={symbol}&fromDate={from_date}&toDate={to_date}&eventCode=DIV&page=0&size=50')
+    payload = fetch_json('GET', url, headers=vci_headers, source='VCI')
+    if payload is None:
+        return None
+    content = payload.get('data', {}).get('content', [])
+    if not content:
+        print(f'No dividend history returned by VCI for {symbol}.')
+        return None
+    df = json_normalize(content)
+    return df.drop(columns=[c for c in ['organCode', '__typename', 'organNameEn', 'organNameVi', 'isEvent'] if c in df.columns])
+
+
+# =============================================================================
+# STOCK EVALUATION (VCI)
+# =============================================================================
+
+def stock_evaluation (symbol='ACB', period=1, time_window='D', headers=None):
+    """
+    Return a DataFrame of the stock's own historical P/E and P/B ratios by quarter.
+    Data source: VCI (VietCap Securities), reusing `financial_ratio()`.
+    endpoint also returned industry-average and VNIndex-average P/E and P/B
+    for comparison; confirmed VCI has no equivalent industry/index benchmark
+    data anywhere, so only the stock's own P/E and P/B series is available
+    here. `period`/`time_window` are accepted for backward compatibility but
+    no longer change the result - VCI always returns its own available
+    quarterly history.
+    Parameters:
+    symbol (str): ticker of the company, default is 'ACB'.
+    period (int): unused, kept for backward compatibility.
+    time_window (str): unused, kept for backward compatibility.
+    """
+    ratio_df = financial_ratio(symbol, 'quarterly', is_all=True)
+    if ratio_df is None:
+        return None
+    keep_rows = [r for r in ['pe', 'pb'] if r in ratio_df.index]
+    if not keep_rows:
+        print(f'No PE/PB data available from VCI for {symbol}.')
+        return None
+    df = ratio_df.loc[keep_rows].T
+    df = df.rename(columns={'pe': 'PE', 'pb': 'PB'})
+    df['ticker'] = symbol
+    df.index.name = 'period'
+    return df.reset_index()