[Feature] SEC - Management Discussion & Analysis Sections

openbb_platform/core/openbb_core/provider/standard_models/management_discussion_analysis.py

@@ -0,0 +1,48 @@
+"""Management Discussion & Analysis Standard Model."""
+
+from datetime import date as dateType
+from typing import Literal, Optional
+
+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 pydantic import Field, field_validator
+
+
+class ManagementDiscussionAnalysisQueryParams(QueryParams):
+    """Management Discussion & Analysis Query Parameters."""
+
+    symbol: str = Field(description=QUERY_DESCRIPTIONS.get("symbol", ""))
+    calendar_year: Optional[int] = Field(
+        default=None,
+        description="Calendar year of the report. By default, is the current year."
+        + " If the calendar period is not provided, but the calendar year is, it will return the annual report.",
+    )
+    calendar_period: Optional[Literal["Q1", "Q2", "Q3", "Q4"]] = Field(
+        default=None,
+        description="Calendar period of the report. By default, is the most recent report available for the symbol."
+        + " If no calendar year and no calendar period are provided, it will return the most recent report.",
+    )
+
+    @field_validator("symbol", mode="before", check_fields=False)
+    @classmethod
+    def to_upper(cls, v: str):
+        """Convert field to uppercase."""
+        return v.upper()
+
+
+class ManagementDiscussionAnalysisData(Data):
+    """Management Discussion & Analysis Data."""
+
+    symbol: str = Field(description=DATA_DESCRIPTIONS.get("symbol", ""))
+    calendar_year: int = Field(description="The calendar year of the report.")
+    calendar_period: int = Field(description="The calendar period of the report.")
+    period_ending: Optional[dateType] = Field(
+        description="The end date of the reporting period.", default=None
+    )
+    content: str = Field(
+        description="The content of the management discussion and analysis."
+    )

openbb_platform/extensions/equity/integration/test_equity_api.py

@@ -2189,3 +2189,33 @@ def test_equity_ownership_government_trades(params, headers):
     result = requests.get(url, headers=headers, timeout=10)
     assert isinstance(result, requests.Response)
     assert result.status_code == 200
+
+
+@parametrize(
+    "params",
+    [
+        (
+            {
+                "symbol": "AAPL",
+                "calendar_year": 2024,
+                "calendar_period": "Q2",
+                "wrap_length": 120,
+                "include_tables": False,
+                "use_cache": True,
+                "raw_html": False,
+                "strategy": "trafilatura",
+                "provider": "sec",
+            }
+        ),
+    ],
+)
+@pytest.mark.integration
+def test_equity_fundamental_management_discussion_analysis(params, headers):
+    """Test the equity fundamental management discussion analysis endpoint."""
+    params = {p: v for p, v in params.items() if v}
+
+    query_str = get_querystring(params, [])
+    url = f"http://0.0.0.0:8000/api/v1/equity/fundamental/management_discussion_analysis?{query_str}"
+    result = requests.get(url, headers=headers, timeout=10)
+    assert isinstance(result, requests.Response)
+    assert result.status_code == 200

openbb_platform/extensions/equity/integration/test_equity_python.py

@@ -2049,3 +2049,30 @@ def test_equity_ownership_government_trades(params, obb):
     assert result
     assert isinstance(result, OBBject)
     assert len(result.results) > 0
+
+
+@parametrize(
+    "params",
+    [
+        (
+            {
+                "symbol": "AAPL",
+                "calendar_year": 2024,
+                "calendar_period": "Q2",
+                "wrap_length": 120,
+                "include_tables": False,
+                "use_cache": True,
+                "raw_html": False,
+                "strategy": "trafilatura",
+                "provider": "sec",
+            }
+        ),
+    ],
+)
+@pytest.mark.integration
+def test_equity_fundamental_management_discussion_analysis(params, obb):
+    """Test the equity fundamental management discussion analysis endpoint."""
+    result = obb.equity.fundamental.management_discussion_analysis(**params)
+    assert result
+    assert isinstance(result, OBBject)
+    assert len(result.results.content) > 0

openbb_platform/extensions/equity/openbb_equity/fundamental/fundamental_router.py

@@ -477,3 +477,58 @@ async def trailing_dividend_yield(
 ) -> OBBject:
     """Get the 1 year trailing dividend yield for a given company over time."""
     return await OBBject.from_query(Query(**locals()))
+
+
+@router.command(
+    model="ManagementDiscussionAnalysis",
+    examples=[
+        APIEx(parameters={"symbol": "AAPL", "provider": "sec"}),
+        APIEx(
+            description="Get the Management Discussion & Analysis section by calendar year and period.",
+            parameters={
+                "symbol": "AAPL",
+                "calendar_year": 2020,
+                "calendar_period": "Q4",
+                "provider": "sec",
+            },
+        ),
+        APIEx(
+            description="Setting 'include_tables' to True will attempt to extract all tables in valid Markdown.",
+            parameters={
+                "symbol": "AAPL",
+                "calendar_year": 2020,
+                "calendar_period": "Q4",
+                "provider": "sec",
+                "include_tables": True,
+            },
+        ),
+        APIEx(
+            description="Setting 'raw_html' to True will bypass extraction and return the raw HTML file, as is."
+            + " Use this for custom parsing or to access the entire HTML filing.",
+            parameters={
+                "symbol": "AAPL",
+                "calendar_year": 2020,
+                "calendar_period": "Q4",
+                "provider": "sec",
+                "raw_html": True,
+            },
+        ),
+    ],
+    openapi_extra={
+        "widget_config": {
+            "type": "markdown",
+            "data": {"dataKey": "results.content", "columnsDefs": []},
+            "staleTime": 86400000,
+            "refetchInterval": 86400000,
+            "source": "SEC",
+        }
+    },
+)
+async def management_discussion_analysis(
+    cc: CommandContext,
+    provider_choices: ProviderChoices,
+    standard_params: StandardParams,
+    extra_params: ExtraParams,
+) -> OBBject:
+    """Get the Management Discussion & Analysis section from the financial statements for a given company."""
+    return await OBBject.from_query(Query(**locals()))

openbb_platform/openbb/assets/reference.json

@@ -26646,6 +26646,160 @@
             },
             "model": "TrailingDividendYield"
         },
+        "/equity/fundamental/management_discussion_analysis": {
+            "deprecated": {
+                "flag": null,
+                "message": null
+            },
+            "description": "Get the Management Discussion & Analysis section from the financial statements for a given company.",
+            "examples": "\nExamples\n--------\n\n```python\nfrom openbb import obb\nobb.equity.fundamental.management_discussion_analysis(symbol='AAPL', provider='sec')\n# Get the Management Discussion & Analysis section by calendar year and period.\nobb.equity.fundamental.management_discussion_analysis(symbol='AAPL', calendar_year=2020, calendar_period=4, provider='sec')\n# Setting 'include_tables' to True will attempt to extract all tables in valid Markdown.\nobb.equity.fundamental.management_discussion_analysis(symbol='AAPL', calendar_year=2020, calendar_period=4, provider='sec', include_tables=True)\n# Setting 'raw_html' to True will bypass extraction and return the raw HTML file, as is. Use this for custom parsing or to access the entire HTML filing.\nobb.equity.fundamental.management_discussion_analysis(symbol='AAPL', calendar_year=2020, calendar_period=4, provider='sec', raw_html=True)\n```\n\n",
+            "parameters": {
+                "standard": [
+                    {
+                        "name": "symbol",
+                        "type": "str",
+                        "description": "Symbol to get data for.",
+                        "default": "",
+                        "optional": false,
+                        "choices": null
+                    },
+                    {
+                        "name": "calendar_year",
+                        "type": "int",
+                        "description": "Calendar year of the report. By default, is the current year. If the calendar period is not provided, but the calendar year is, it will return the annual report.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "calendar_period",
+                        "type": "int",
+                        "description": "Calendar period of the report. By default, is the most recent report available for the symbol. If no calendar year and no calendar period are provided, it will return the most recent report.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    }
+                ],
+                "sec": [
+                    {
+                        "name": "wrap_length",
+                        "type": "int",
+                        "description": "The length to wrap the extracted text, excluding tables. Default is 120.",
+                        "default": 120,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "include_tables",
+                        "type": "bool",
+                        "description": "Return tables formatted as markdown in the text. Default is False. Tables may reveal 'missing' content, but will likely need some level of manual cleaning, post-request, to display properly. In some cases, tables may not be recoverable due to the nature of the document.",
+                        "default": false,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "use_cache",
+                        "type": "bool",
+                        "description": "When True, the file will be cached for use later. Default is True.",
+                        "default": true,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "raw_html",
+                        "type": "bool",
+                        "description": "When True, the raw HTML content of the entire filing will be returned. Default is False. Use this option to parse the document manually.",
+                        "default": false,
+                        "optional": true,
+                        "choices": null
+                    }
+                ]
+            },
+            "returns": {
+                "OBBject": [
+                    {
+                        "name": "results",
+                        "type": "List[ManagementDiscussionAnalysis]",
+                        "description": "Serializable results."
+                    },
+                    {
+                        "name": "provider",
+                        "type": "Optional[Literal['sec']]",
+                        "description": "Provider name."
+                    },
+                    {
+                        "name": "warnings",
+                        "type": "Optional[List[Warning_]]",
+                        "description": "List of warnings."
+                    },
+                    {
+                        "name": "chart",
+                        "type": "Optional[Chart]",
+                        "description": "Chart object."
+                    },
+                    {
+                        "name": "extra",
+                        "type": "Dict[str, Any]",
+                        "description": "Extra info."
+                    }
+                ]
+            },
+            "data": {
+                "standard": [
+                    {
+                        "name": "symbol",
+                        "type": "str",
+                        "description": "Symbol representing the entity requested in the data.",
+                        "default": "",
+                        "optional": false,
+                        "choices": null
+                    },
+                    {
+                        "name": "calendar_year",
+                        "type": "int",
+                        "description": "The calendar year of the report.",
+                        "default": "",
+                        "optional": false,
+                        "choices": null
+                    },
+                    {
+                        "name": "calendar_period",
+                        "type": "int",
+                        "description": "The calendar period of the report.",
+                        "default": "",
+                        "optional": false,
+                        "choices": null
+                    },
+                    {
+                        "name": "period_ending",
+                        "type": "date",
+                        "description": "The end date of the reporting period.",
+                        "default": null,
+                        "optional": true,
+                        "choices": null
+                    },
+                    {
+                        "name": "content",
+                        "type": "str",
+                        "description": "The content of the management discussion and analysis.",
+                        "default": "",
+                        "optional": false,
+                        "choices": null
+                    }
+                ],
+                "sec": [
+                    {
+                        "name": "url",
+                        "type": "str",
+                        "description": "The URL of the filing from which the data was extracted.",
+                        "default": "",
+                        "optional": false,
+                        "choices": null
+                    }
+                ]
+            },
+            "model": "ManagementDiscussionAnalysis"
+        },
         "/equity/ownership/major_holders": {
             "deprecated": {
                 "flag": null,