[Enhancement] Sync `reference.json` and Platform function docstring (#6211)

* obbject params stored as a list of dict

platform markdown generator processes obbject returns into a string

* process field types further

* process field type correctly

* fixed models

* mypy suggestion was sus

* updated assets and packages

---------

Co-authored-by: Henrique Joaquim <h.joaquim@campus.fct.unl.pt>
Co-authored-by: montezdesousa <79287829+montezdesousa@users.noreply.github.com>

9 files changed, 5556 insertions, 2427 deletions

diff --git a/openbb_platform/core/openbb_core/app/static/package_builder.py b/openbb_platform/core/openbb_core/app/static/package_builder.py
index a784e5e8164..917f9ff03df 100644
--- a/openbb_platform/core/openbb_core/app/static/package_builder.py
+++ b/openbb_platform/core/openbb_core/app/static/package_builder.py
@@ -892,12 +892,17 @@ class DocstringGenerator:
 
         Parameters
         ----------
-            field (FieldInfo): Pydantic field object containing field information.
-            target (Literal["docstring", "website"], optional): Target to return type for. Defaults to "docstring".
+            field_type (Any):
+                Typing object containing the field type.
+            is_required (bool):
+                Flag to indicate if the field is required.
+            target (Literal["docstring", "website"], optional):
+                Target to return type for. Defaults to "docstring".
 
         Returns
         -------
-            str: String representation of the field type.
+            str:
+                String representation of the field type.
         """
         is_optional = not is_required
 
@@ -907,7 +912,7 @@ class DocstringGenerator:
             if "BeforeValidator" in str(_type):
                 _type = "Optional[int]" if is_optional else "int"  # type: ignore
 
-            field_type = (
+            _type = (
                 str(_type)
                 .replace("<class '", "")
                 .replace("'>", "")
@@ -919,17 +924,22 @@ class DocstringGenerator:
                 .replace(", None", "")
             )
 
-            field_type = (
-                f"Optional[{field_type}]"
+            if "openbb_" in str(_type):
+                _type = (
+                    str(_type).split(".", maxsplit=1)[0].split("openbb_")[0]
+                    + str(_type).rsplit(".", maxsplit=1)[-1]
+                )
+
+            _type = (
+                f"Optional[{_type}]"
                 if is_optional and "Optional" not in str(_type)
-                else field_type
+                else _type
             )
 
             if target == "website":
-                field_type = re.sub(r"Optional\[(.*)\]", r"\1", field_type)
-                field_type = re.sub(r"Annotated\[(.*)\]", r"\1", field_type)
+                _type = re.sub(r"Optional\[(.*)\]", r"\1", _type)
 
-            return field_type
+            return _type
 
         except TypeError:
             # Fallback to the annotation if the repr fails
@@ -939,11 +949,10 @@ class DocstringGenerator:
     def get_OBBject_description(
         results_type: str,
         providers: Optional[str],
-        target: Literal["docstring", "website"] = "docstring",
     ) -> str:
         """Get the command output description."""
         available_providers = providers or "Optional[str]"
-        indent = 2 if target == "docstring" else 0
+        indent = 2
 
         obbject_description = (
             f"{create_indent(indent)}OBBject\n"
@@ -1358,7 +1367,7 @@ class ReferenceGenerator:
                     # Should be removed if TYPE_EXPANSION is updated to include this
                     field_type = f"Union[{field_type}, List[{field_type}]]"
 
-            default_value = "" if field_info.default is PydanticUndefined else str(field_info.default)  # fmt: skip
+            default_value = "" if field_info.default is PydanticUndefined else field_info.default  # fmt: skip
 
             provider_field_params.append(
                 {
@@ -1373,6 +1382,56 @@ class ReferenceGenerator:
         return provider_field_params
 
     @staticmethod
+    def get_obbject_returns_fields(
+        model: str,
+        providers: str,
+    ) -> List[Dict[str, str]]:
+        """Get the fields of the OBBject returns object for the given standard_model.
+
+        Args
+        ----
+            model (str):
+                Standard model of the returned object.
+            providers (str):
+                Available providers for the model.
+
+        Returns
+        -------
+            List[Dict[str, str]]:
+                List of dictionaries containing the field name, type, description, default
+                and optionality of each field.
+        """
+        obbject_list = [
+            {
+                "name": "results",
+                "type": f"List[{model}]",
+                "description": "Serializable results.",
+            },
+            {
+                "name": "provider",
+                "type": f"Optional[{providers}]",
+                "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.",
+            },
+        ]
+
+        return obbject_list
+
+    @staticmethod
     def get_post_method_parameters_info(
         docstring: str,
     ) -> List[Dict[str, Union[bool, str]]]:
@@ -1429,7 +1488,7 @@ class ReferenceGenerator:
         return parameters_list
 
     @staticmethod
-    def get_post_method_returns_info(docstring: str) -> str:
+    def get_post_method_returns_info(docstring: str) -> List[Dict[str, str]]:
         """Get the returns information for the POST method endpoints.
 
         Parameters
@@ -1439,10 +1498,11 @@ class ReferenceGenerator:
 
         Returns
         -------
-            Dict[str, str]:
-                Dictionary containing the name, type, description of the return value
+            List[Dict[str, str]]:
+                Single element list having a dictionary containing the name, type,
+                description of the return value
         """
-        return_info = ""
+        returns_list = []
 
         # Define a regex pattern to match the Returns section
         # This pattern captures the model name inside "OBBject[]" and its description
@@ -1456,15 +1516,17 @@ class ReferenceGenerator:
             content_inside_brackets = re.search(
                 r"OBBject\[\s*((?:[^\[\]]|\[[^\[\]]*\])*)\s*\]", return_type
             )
-            return_type_content = content_inside_brackets.group(1)  # type: ignore
+            return_type = content_inside_brackets.group(1)  # type: ignore
 
-            return_info = (
-                f"OBBject\n"
-                f"{create_indent(1)}results : {return_type_content}\n"
-                f"{create_indent(2)}{description}"
-            )
+            returns_list = [
+                {
+                    "name": "results",
+                    "type": return_type,
+                    "description": description,
+                }
+            ]
 
-        return return_info
+        return returns_list
 
     @classmethod
     def get_reference_data(cls) -> Dict[str, Dict[str, Any]]:
@@ -1489,7 +1551,7 @@ class ReferenceGenerator:
             # Route method is used to distinguish between GET and POST methods
             route_method = getattr(route, "methods", None)
             # Route endpoint is the callable function
-            route_func = getattr(route, "endpoint", None)
+            route_func = getattr(route, "endpoint", lambda: None)
             # Attribute contains the model and examples info for the endpoint
             openapi_extra = getattr(route, "openapi_extra", {})
             # Standard model is used as the key for the ProviderInterface Map dictionary
@@ -1504,7 +1566,9 @@ class ReferenceGenerator:
             # Add endpoint examples
             examples = openapi_extra.get("examples", [])
             reference[path]["examples"] = cls.get_endpoint_examples(
-                path, route_func, examples  # type: ignore
+                path,
+                route_func,
+                examples,  # type: ignore
             )
             # Add data for the endpoints having a standard model
             if route_method == {"GET"}:
@@ -1548,10 +1612,8 @@ class ReferenceGenerator:
                 # Add endpoint returns data
                 # Currently only OBBject object is returned
                 providers = provider_parameter_fields["type"]
-                reference[path]["returns"]["OBBject"] = (
-                    DocstringGenerator.get_OBBject_description(
-                        standard_model, providers, "website"
-                    )
+                reference[path]["returns"]["OBBject"] = cls.get_obbject_returns_fields(
+                    standard_model, providers
                 )
             # Add data for the endpoints without a standard model (data processing endpoints)
             elif route_method == {"POST"}:
diff --git a/openbb_platform/openbb/assets/reference.json b/openbb_platform/openbb/assets/reference.json
index 6b304444527..bdbae0cf973 100644
--- a/openbb_platform/openbb/assets/reference.json
+++ b/openbb_platform/openbb/assets/reference.json
@@ -19,14 +19,14 @@
                     "name": "start_date",
                     "type": "Union[date, str]",
                     "description": "Start date of the data, in YYYY-MM-DD format.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
                     "name": "end_date",
                     "type": "Union[date, str]",
                     "description": "End date of the data, in YYYY-MM-DD format.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
@@ -65,7 +65,7 @@
                     "name": "limit",
                     "type": "int",
                     "description": "The number of data entries to return.",
-                    "default": "49999",
+                    "default": 49999,
                     "optional": true
                 }
             ],
@@ -81,7 +81,7 @@
                     "name": "exchanges",
                     "type": "List[str]",
                     "description": "To limit the query to a subset of exchanges e.g. ['POLONIEX', 'GDAX']",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 }
             ],
@@ -96,7 +96,33 @@
             ]
         },
         "returns": {
-            "OBBject": "OBBject\n    results : CryptoHistorical\n        Serializable results.\n    provider : Literal['fmp', 'polygon', 'tiingo', 'yfinance']\n        Provider name.\n    warnings : Optional[List[Warning_]]\n        List of warnings.\n    chart : Optional[Chart]\n        Chart object.\n    extra : Dict[str, Any]\n        Extra info.\n"
+            "OBBject": [
+                {
+                    "name": "results",
+                    "type": "List[CryptoHistorical]",
+                    "description": "Serializable results."
+                },
+                {
+                    "name": "provider",
+                    "type": "Optional[Literal['fmp', 'polygon', 'tiingo', 'yfinance']]",
+                    "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": [
@@ -144,9 +170,9 @@
                 },
                 {
                     "name": "vwap",
-                    "type": "float, Gt(gt=0)",
+                    "type": "Annotated[float, Gt(gt=0)]",
                     "description": "Volume Weighted Average Price over the period.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 }
             ],
@@ -155,30 +181,30 @@
                     "name": "adj_close",
                     "type": "float",
                     "description": "The adjusted close price.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
                     "name": "change",
                     "type": "float",
                     "description": "Change in the price from the previous close.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
                     "name": "change_percent",
                     "type": "float",
                     "description": "Change in the price from the previous close, as a normalized percent.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 }
             ],
             "polygon": [
                 {
                     "name": "transactions",
-                    "type": "int, Gt(gt=0)",
+                    "type": "Annotated[int, Gt(gt=0)]",
                     "description": "Number of transactions for the symbol in the time period.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 }
             ],
@@ -187,14 +213,14 @@
                     "name": "transactions",
                     "type": "int",
                     "description": "Number of transactions for the symbol in the time period.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
                     "name": "volume_notional",
                     "type": "float",
                     "description": "The last size done for the asset on the specific date in the quote currency. The volume of the asset on the specific date in the quote currency.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 }
             ],
@@ -215,7 +241,7 @@
                     "name": "query",
                     "type": "str",
                     "description": "Search query.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
@@ -229,7 +255,33 @@
             "fmp": []
         },
         "returns": {
-            "OBBject": "OBBject\n    results : CryptoSearch\n        Serializable results.\n    provider : Literal['fmp']\n        Provider name.\n    warnings : Optional[List[Warning_]]\n        List of warnings.\n    chart : Optional[Chart]\n        Chart object.\n    extra : Dict[str, Any]\n        Extra info.\n"
+            "OBBject": [
+                {
+                    "name": "results",
+                    "type": "List[CryptoSearch]",
+                    "description": "Serializable results."
+                },
+                {
+                    "name": "provider",
+                    "type": "Optional[Literal['fmp']]",
+                    "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": [
@@ -244,7 +296,7 @@
                     "name": "name",
                     "type": "str",
                     "description": "Name of the crypto.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 }
             ],
@@ -253,21 +305,21 @@
                     "name": "currency",
                     "type": "str",
                     "description": "The currency the crypto trades for.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
                     "name": "exchange",
                     "type": "str",
                     "description": "The exchange code the crypto trades on.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
                     "name": "exchange_name",
                     "type": "str",
                     "description": "The short name of the exchange the crypto trades on.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 }
             ]
@@ -294,14 +346,14 @@
                     "name": "start_date",
                     "type": "Union[date, str]",
                     "description": "Start date of the data, in YYYY-MM-DD format.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
                     "name": "end_date",
                     "type": "Union[date, str]",
                     "description": "End date of the data, in YYYY-MM-DD format.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
@@ -340,7 +392,7 @@
                     "name": "limit",
                     "type": "int",
                     "description": "The number of data entries to return.",
-                    "default": "49999",
+                    "default": 49999,
                     "optional": true
                 }
             ],
@@ -364,7 +416,33 @@
             ]
         },
         "returns": {
-            "OBBject": "OBBject\n    results : CurrencyHistorical\n        Serializable results.\n    provider : Literal['fmp', 'polygon', 'tiingo', 'yfinance']\n        Provider name.\n    warnings : Optional[List[Warning_]]\n        List of warnings.\n    chart : Optional[Chart]\n        Chart object.\n    extra : Dict[str, Any]\n        Extra info.\n"
+            "OBBject": [
+                {
+                    "name": "results",
+                    "type": "List[CurrencyHistorical]",
+                    "description": "Serializable results."
+                },
+                {
+                    "name": "provider",
+                    "type": "Optional[Literal['fmp', 'polygon', 'tiingo', 'yfinance']]",
+                    "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": [
@@ -407,14 +485,14 @@
                     "name": "volume",
                     "type": "float",
                     "description": "The trading volume.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
                     "name": "vwap",
-                    "type": "float, Gt(gt=0)",
+                    "type": "Annotated[float, Gt(gt=0)]",
                     "description": "Volume Weighted Average Price over the period.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 }
             ],
@@ -423,30 +501,30 @@
                     "name": "adj_close",
                     "type": "float",
                     "description": "The adjusted close price.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
                     "name": "change",
                     "type": "float",
                     "description": "Change in the price from the previous close.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
                     "name": "change_percent",
                     "type": "float",
                     "description": "Change in the price from the previous close, as a normalized percent.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 }
             ],
             "polygon": [
                 {
                     "name": "transactions",
-                    "type": "int, Gt(gt=0)",
+                    "type": "Annotated[int, Gt(gt=0)]",
                     "description": "Number of transactions for the symbol in the time period.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 }
             ],
@@ -479,14 +557,14 @@
                     "name": "symbol",
                     "type": "str",
                     "description": "Symbol of the pair to search.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
                     "name": "date",
                     "type": "Union[date, str]",
                     "description": "A specific date to get data for.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
@@ -500,7 +578,7 @@
                     "name": "active",
                     "type": "bool",
                     "description": "Specify if the tickers returned should be actively traded on the queried date.",
-                    "default": "True",
+                    "default": true,
                     "optional": true
                 },
                 {
@@ -519,15 +597,41 @@
                 },
                 {
                     "name": "limit",
-                    "type": "int, Gt(gt=0)",
+                    "type": "Annotated[int, Gt(gt=0)]",
                     "description": "The number of data entries to return.",
-                    "default": "1000",
+                    "default": 1000,
                     "optional": true
                 }
             ]
         },
         "returns": {
-            "OBBject": "OBBject\n    results : CurrencyPairs\n        Serializable results.\n    provider : Literal['fmp', 'intrinio', 'polygon']\n        Provider name.\n    warnings : Optional[List[Warning_]]\n        List of warnings.\n    chart : Optional[Chart]\n        Chart object.\n    extra : Dict[str, Any]\n        Extra info.\n"
+            "OBBject": [
+                {
+                    "name": "results",
+                    "type": "List[CurrencyPairs]",
+                    "description": "Serializable results."
+                },
+                {
+                    "name": "provider",
+                    "type": "Optional[Literal['fmp', 'intrinio', 'polygon']]",
+                    "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": [
@@ -558,14 +662,14 @@
                     "name": "stock_exchange",
                     "type": "str",
                     "description": "Stock exchange of the currency pair.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
                     "name": "exchange_short_name",
                     "type": "str",
                     "description": "Short name of the stock exchange of the currency pair.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 }
             ],
@@ -611,28 +715,28 @@
                     "name": "currency_symbol",
                     "type": "str",
                     "description": "The symbol of the quote currency.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
                     "name": "currency_name",
                     "type": "str",
                     "description": "Name of the quote currency.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
                     "name": "base_currency_symbol",
                     "type": "str",
                     "description": "The symbol of the base currency.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
                     "name": "base_currency_name",
                     "type": "str",
                     "description": "Name of the base currency.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
@@ -646,7 +750,7 @@
                     "name": "delisted_utc",
                     "type": "datetime",
                     "description": "The delisted timestamp in UTC.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 }
             ]
@@ -680,7 +784,7 @@
                     "name": "counter_currencies",
                     "type": "Union[str, List[str]]",
                     "description": "An optional list of counter currency symbols to filter for. None returns all.",
-                    "default": "None",
+                    "default": null,
                     "optional": true
                 },
                 {
@@ -694,7 +798,33 @@
             "fmp": []
         },