feature/financials - PR for working on structure of financial statements. (#5794)

* balance sheet draft

* balance_sheet draft

* cash_flow draft

* income_statement draft

* intrinio financials

* description

* period field

* ruff

* income statement

* field

* label - gross profit ratio

* cash flow statement

* investing order

* add option for caching to cashflow

* add caching to balance and income

* typos and update order for financial institutions

* replace 0 values with None

* add financial ratios from intrinio

* black

* missing test params

* balance cassette

* query param description

* symbol list warning

* black

* handle BRK-A and symbols with a dash for Intrinio

* fix typo error

* add free cash flow to bottom of cash flow statement

* amortization_expense

* dev_install.py

* undo dev_install.. wrong branch

* cash flow order things

* standardized cash flow

* fields

* integration tests

* cash flow model validator

* more polygon cash

* black

* black

* Delete openbb_sdk/providers/polygon/openbb_polygon/utils/definitions.py

wrong file

* balance sheet

* some cleanup

* ruff

* income statement

* black

* test params

* financial ratios async update

* recapture fmp and polygon tests

* yFinance financials

* yfinance tests

* delete financial_statements standard model

* intrinio balance sheet order

* fiscal year standard param

* remove file accidentally committed

* add reported_financials end point

* fiscal_year param for reported_financials

* fix url

* fmp test cassette

* add safe-guard with warning for fiscal year before 2008

* periods can only be annual and quarter

* url in docstring correction

* add fiscal_year param to intrinio standardized financials and ratios

* fix fmp ratios

* black

* rename fields as per Minh

* rogue field

* black

* Fix typo in a docstring

* Resolve linting errors

* type ignore

* disable=unused-argument

* changing the arg name cc @minhhoang1023

---------

Co-authored-by: Igor Radovanovic <74266147+IgorWounds@users.noreply.github.com>
Co-authored-by: Theodore Aptekarev <aptekarev@gmail.com>
Co-authored-by: hjoaquim <h.joaquim@campus.fct.unl.pt>

38 files changed, 3702 insertions, 1649 deletions

diff --git a/openbb_platform/core/openbb_core/provider/standard_models/balance_sheet.py b/openbb_platform/core/openbb_core/provider/standard_models/balance_sheet.py
index 0b8832bcca9..80ef5c30d3a 100644
--- a/openbb_platform/core/openbb_core/provider/standard_models/balance_sheet.py
+++ b/openbb_platform/core/openbb_core/provider/standard_models/balance_sheet.py
@@ -1,27 +1,25 @@
 """Balance Sheet Standard Model."""
 
+import warnings
+from datetime import date as dateType
+from typing import Optional
 
-from datetime import (
-    date as dateType,
-    datetime,
-)
-from typing import List, Literal, Optional, Set, Union
-
-from pydantic import Field, NonNegativeInt, StrictFloat, field_validator
+from pydantic import Field, NonNegativeInt, field_validator
 
 from openbb_core.provider.abstract.data import Data
 from openbb_core.provider.abstract.query_params import QueryParams
 from openbb_core.provider.utils.descriptions import (
-    DATA_DESCRIPTIONS,
     QUERY_DESCRIPTIONS,
 )
 
+_warn = warnings.warn
+
 
 class BalanceSheetQueryParams(QueryParams):
     """Balance Sheet Query."""
 
     symbol: str = Field(description=QUERY_DESCRIPTIONS.get("symbol", ""))
-    period: Optional[Literal["annual", "quarter"]] = Field(
+    period: str = Field(
         default="annual",
         description=QUERY_DESCRIPTIONS.get("period", ""),
     )
@@ -31,159 +29,22 @@ class BalanceSheetQueryParams(QueryParams):
 
     @field_validator("symbol", mode="before", check_fields=False)
     @classmethod
-    def upper_symbol(cls, v: Union[str, List[str], Set[str]]):
+    def upper_symbol(cls, v: str):
         """Convert symbol to uppercase."""
+        if "," in v:
+            _warn(
+                f"{QUERY_DESCRIPTIONS.get('symbol_list_warning', '')} {v.split(',')[0].upper()}"
+            )
         return v.split(",")[0].upper() if "," in v else v.upper()
 
 
 class BalanceSheetData(Data):
     """Balance Sheet Data."""
 
-    symbol: Optional[str] = Field(
-        default=None, description=DATA_DESCRIPTIONS.get("symbol", "")
-    )
-    date: dateType = Field(description=DATA_DESCRIPTIONS.get("date", ""))
-    cik: Optional[str] = Field(
-        default=None,
-        description=DATA_DESCRIPTIONS.get("cik", ""),
-    )
-    currency: Optional[str] = Field(default=None, description="Reporting currency.")
-    filling_date: Optional[dateType] = Field(default=None, description="Filling date.")
-    accepted_date: Optional[datetime] = Field(
-        default=None, description="Accepted date."
-    )
-    period: Optional[str] = Field(
-        default=None, description="Reporting period of the statement."
-    )
-
-    cash_and_cash_equivalents: Optional[StrictFloat] = Field(
-        default=None, description="Cash and cash equivalents"
-    )
-    short_term_investments: Optional[StrictFloat] = Field(
-        default=None, description="Short-term investments"
-    )
-    long_term_investments: Optional[StrictFloat] = Field(
-        default=None, description="Long-term investments"
-    )
-
-    inventory: Optional[StrictFloat] = Field(default=None, description="Inventory")
-    net_receivables: Optional[StrictFloat] = Field(
-        default=None, description="Receivables, net"
-    )
-
-    marketable_securities: Optional[StrictFloat] = Field(
-        default=None, description="Marketable securities"
-    )
-    property_plant_equipment_net: Optional[StrictFloat] = Field(
-        default=None, description="Property, plant and equipment, net"
-    )
-    goodwill: Optional[StrictFloat] = Field(default=None, description="Goodwill")
-
-    assets: Optional[StrictFloat] = Field(default=None, description="Total assets")
-    current_assets: Optional[StrictFloat] = Field(
-        default=None, description="Total current assets"
-    )
-    other_current_assets: Optional[StrictFloat] = Field(
-        default=None, description="Other current assets"
-    )
-    intangible_assets: Optional[StrictFloat] = Field(
-        default=None, description="Intangible assets"
-    )
-    tax_assets: Optional[StrictFloat] = Field(
-        default=None, description="Accrued income taxes"
-    )
-    non_current_assets: Optional[StrictFloat] = Field(
-        default=None, description="Total non-current assets"
-    )
-    other_non_current_assets: Optional[StrictFloat] = Field(
-        default=None, description="Other non-current assets"
-    )
-
-    account_payables: Optional[StrictFloat] = Field(
-        default=None, description="Accounts payable"
-    )
-    tax_payables: Optional[StrictFloat] = Field(
-        default=None, description="Accrued income taxes"
-    )
-    deferred_revenue: Optional[StrictFloat] = Field(
-        default=None, description="Accrued income taxes, other deferred revenue"
-    )
-    other_assets: Optional[StrictFloat] = Field(
-        default=None, description="Other assets"
-    )
-    total_assets: Optional[StrictFloat] = Field(
-        default=None, description="Total assets"
-    )
-
-    long_term_debt: Optional[StrictFloat] = Field(
-        default=None,
-        description="Long-term debt, Operating lease obligations, Long-term finance lease obligations",
-    )
-    short_term_debt: Optional[StrictFloat] = Field(
-        default=None,
-        description="Short-term borrowings, Long-term debt due within one year, "
-        "Operating lease obligations due within one year, "
-        "Finance lease obligations due within one year",
-    )
-
-    liabilities: Optional[StrictFloat] = Field(
-        default=None, description="Total liabilities"
-    )
-    other_current_liabilities: Optional[StrictFloat] = Field(
-        default=None, description="Other current liabilities"
-    )
-    current_liabilities: Optional[StrictFloat] = Field(
-        default=None, description="Total current liabilities"
-    )
-    total_liabilities_and_total_equity: Optional[StrictFloat] = Field(
-        default=None, description="Total liabilities and total equity"
-    )
-    other_non_current_liabilities: Optional[StrictFloat] = Field(
-        default=None, description="Other non-current liabilities"
-    )
-    non_current_liabilities: Optional[StrictFloat] = Field(
-        default=None, description="Total non-current liabilities"
-    )
-    total_liabilities_and_stockholders_equity: Optional[StrictFloat] = Field(
-        default=None, description="Total liabilities and stockholders' equity"
-    )
-    other_stockholder_equity: Optional[StrictFloat] = Field(
-        default=None, description="Other stockholders equity"
-    )
-    total_stockholders_equity: Optional[StrictFloat] = Field(
-        default=None, description="Total stockholders' equity"
+    period_ending: dateType = Field(description="The end date of the reporting period.")
+    fiscal_period: Optional[str] = Field(
+        description="The fiscal period of the report.", default=None
     )
-    other_liabilities: Optional[StrictFloat] = Field(
-        default=None, description="Other liabilities"
+    fiscal_year: Optional[int] = Field(
+        description="The fiscal year of the fiscal period.", default=None
     )
-    total_liabilities: Optional[StrictFloat] = Field(
-        default=None, description="Total liabilities"
-    )
-
-    common_stock: Optional[StrictFloat] = Field(
-        default=None, description="Common stock"
-    )
-    preferred_stock: Optional[StrictFloat] = Field(
-        default=None, description="Preferred stock"
-    )
-
-    accumulated_other_comprehensive_income_loss: Optional[StrictFloat] = Field(
-        default=None, description="Accumulated other comprehensive income (loss)"
-    )
-    retained_earnings: Optional[StrictFloat] = Field(
-        default=None, description="Retained earnings"
-    )
-    minority_interest: Optional[StrictFloat] = Field(
-        default=None, description="Minority interest"
-    )
-    total_equity: Optional[StrictFloat] = Field(
-        default=None, description="Total equity"
-    )
-
-    @field_validator("symbol", mode="before", check_fields=False)
-    @classmethod
-    def upper_symbol(cls, v: Union[str, List[str], Set[str]]):
-        """Convert symbol to uppercase."""
-        if isinstance(v, str):
-            return v.upper()
-        return ",".join([symbol.upper() for symbol in list(v)]) if v else None
diff --git a/openbb_platform/core/openbb_core/provider/standard_models/cash_flow.py b/openbb_platform/core/openbb_core/provider/standard_models/cash_flow.py
index 3a2f4bc1ae4..8e7cc2b40a4 100644
--- a/openbb_platform/core/openbb_core/provider/standard_models/cash_flow.py
+++ b/openbb_platform/core/openbb_core/provider/standard_models/cash_flow.py
@@ -1,24 +1,23 @@
 """Cash Flow Statement Standard Model."""
 
-
+import warnings
 from datetime import date as dateType
-from typing import List, Literal, Optional, Set, Union
+from typing import Optional
 
-from pydantic import Field, NonNegativeInt, StrictFloat, field_validator
+from pydantic import Field, NonNegativeInt, field_validator
 
 from openbb_core.provider.abstract.data import Data
 from openbb_core.provider.abstract.query_params import QueryParams
-from openbb_core.provider.utils.descriptions import (
-    DATA_DESCRIPTIONS,
-    QUERY_DESCRIPTIONS,
-)
+from openbb_core.provider.utils.descriptions import QUERY_DESCRIPTIONS
+
+_warn = warnings.warn
 
 
 class CashFlowStatementQueryParams(QueryParams):
     """Cash Flow Statement Query."""
 
     symbol: str = Field(description=QUERY_DESCRIPTIONS.get("symbol", ""))
-    period: Optional[Literal["annual", "quarter"]] = Field(
+    period: str = Field(
         default="annual",
         description=QUERY_DESCRIPTIONS.get("period", ""),
     )
@@ -28,116 +27,22 @@ class CashFlowStatementQueryParams(QueryParams):
 
     @field_validator("symbol", mode="before", check_fields=False)
     @classmethod
-    def upper_symbol(cls, v: Union[str, List[str], Set[str]]):
+    def upper_symbol(cls, v: str):
         """Convert symbol to uppercase."""
+        if "," in v:
+            _warn(
+                f"{QUERY_DESCRIPTIONS.get('symbol_list_warning', '')} {v.split(',')[0].upper()}"
+            )
         return v.split(",")[0].upper() if "," in v else v.upper()
 
 
 class CashFlowStatementData(Data):
     """Cash Flow Statement Data."""
 
-    symbol: Optional[str] = Field(
-        default=None, description=DATA_DESCRIPTIONS.get("symbol", "")
-    )
-    date: dateType = Field(description=DATA_DESCRIPTIONS.get("date" ""))
-    period: Optional[str] = Field(
-        default=None, description="Reporting period of the statement."
-    )
-    cik: Optional[str] = Field(
-        default=None,
-        description=DATA_DESCRIPTIONS.get("cik", ""),
-    )
-
-    net_income: Optional[StrictFloat] = Field(default=None, description="Net income.")
-
-    depreciation_and_amortization: Optional[StrictFloat] = Field(
-        default=None, description="Depreciation and amortization."
-    )
-    stock_based_compensation: Optional[StrictFloat] = Field(
-        default=None, description="Stock based compensation."
-    )
-    deferred_income_tax: Optional[StrictFloat] = Field(
-        default=None, description="Deferred income tax."
-    )
-    other_non_cash_items: Optional[StrictFloat] = Field(
-        default=None, description="Other non-cash items."
-    )
-    changes_in_operating_assets_and_liabilities: Optional[StrictFloat] = Field(
-        default=None, description="Changes in operating assets and liabilities."
-    )
-
-    accounts_receivables: Optional[StrictFloat] = Field(
-        default=None, description="Accounts receivables."
-    )
-    inventory: Optional[StrictFloat] = Field(default=None, description="Inventory.")
-    vendor_non_trade_receivables: Optional[StrictFloat] = Field(
-        default=None, description="Vendor non-trade receivables."
-    )
-    other_current_and_non_current_assets: Optional[StrictFloat] = Field(
-        default=None, description="Other current and non-current assets."
-    )
-    accounts_payables: Optional[StrictFloat] = Field(
-        default=None, description="Accounts payables."
-    )
-    deferred_revenue: Optional[StrictFloat] = Field(
-        default=None, description="Deferred revenue."
-    )
-    other_current_and_non_current_liabilities: Optional[StrictFloat] = Field(
-        default=None, description="Other current and non-current liabilities."
-    )
-    net_cash_flow_from_operating_activities: Optional[StrictFloat] = Field(
-        default=None, description="Net cash flow from operating activities."
-    )
-
-    purchases_of_marketable_securities: Optional[StrictFloat] = Field(
-        default=None, description="Purchases of investments."
-    )
-    sales_from_maturities_of_investments: Optional[StrictFloat] = Field(
-        default=None, description="Sales and maturities of investments."
-    )
-    investments_in_property_plant_and_equipment: Optional[StrictFloat] = Field(
-        default=None, description="Investments in property, plant, and equipment."
-    )
-    payments_from_acquisitions: Optional[StrictFloat] = Field(
-        default=None, description="Acquisitions, net of cash acquired, and other"
-    )
-    other_investing_activities: Optional[StrictFloat] = Field(
-        default=None, description="Other investing activities"
-    )
-    net_cash_flow_from_investing_activities: Optional[StrictFloat] = Field(
-        default=None, description="Net cash used for investing activities."
-    )
-
-    taxes_paid_on_net_share_settlement: Optional[StrictFloat] = Field(
-        default=None, description="Taxes paid on net share settlement of equity awards."
-    )
-    dividends_paid: Optional[StrictFloat] = Field(
-        default=None, description="Payments for dividends and dividend equivalents"
+    period_ending: dateType = Field(description="The end date of the reporting period.")
+    fiscal_period: Optional[str] = Field(
+        description="The fiscal period of the report.", default=None
     )
-    common_stock_repurchased: Optional[StrictFloat] = Field(
-        default=None, description="Payments related to repurchase of common stock"
+    fiscal_year: Optional[int] = Field(
+        description="The fiscal year of the fiscal period.", default=None
     )
-    debt_proceeds: Optional[StrictFloat] = Field(
-        default=None, description="Proceeds from issuance of term debt"
-    )
-    debt_repayment: Optional[StrictFloat] = Field(
-        default=None, description="Payments of long-term debt"
-    )
-    other_financing_activities: Optional[StrictFloat] = Field(
-        default=None, description="Other financing activities, net"
-    )
-    net_cash_flow_from_financing_activities: Optional[StrictFloat] = Field(
-        default=None, description="Net cash flow from financing activities."
-    )
-    net_change_in_cash: Optional[StrictFloat] = Field(
-        default=None,
-        description="Net increase (decrease) in cash, cash equivalents, and restricted cash",
-    )
-
-    @field_validator("symbol", mode="before", check_fields=False)
-    @classmethod
-    def upper_symbol(cls, v: Union[str, List[str], Set[str]]):
-        """Convert symbol to uppercase."""
-        if isinstance(v, str):
-            return v.upper()
-        return ",".join([symbol.upper() for symbol in list(v)]) if v else None
diff --git a/openbb_platform/core/openbb_core/provider/standard_models/financial_ratios.py b/openbb_platform/core/openbb_core/provider/standard_models/financial_ratios.py
index f8ee01ab31d..e34210ba489 100644
--- a/openbb_platform/core/openbb_core/provider/standard_models/financial_ratios.py
+++ b/openbb_platform/core/openbb_core/provider/standard_models/financial_ratios.py
@@ -1,7 +1,7 @@
 """Financial Ratios Standard Model."""
 
-
-from typing import List, Literal, Optional, Set, Union
+import warnings
+from typing impor