get_international_portfolio filtered the frames and their metadata with different conditions when all_data_items_required is False. The frames kept the tables without "Not Reqd" in the description, which are the "Required" tables, and the metadata kept descriptions ending with "Not Reqd", which the ex-dividend files never do because their descriptions end with " - Ex-Dividends". So with dividends=True the call returned the "All 4 Data Items Required" returns under the "Not Reqd" description, and with dividends=False the metadata list was empty and transform_data raised IndexError. The documented example obb.famafrench.country_portfolio_returns(frequency="annual", measure="local", country="japan", dividends=False, all_data_items_required=False) fails with "[Unexpected Error] -> IndexError -> list index out of range". Filter both lists on "Not Reqd" in the description. Co-authored-by: dlee-bq <dlee@brightquery.com> Co-authored-by: Danglewood <85772166+deeleeramone@users.noreply.github.com>
OpenBB Platform
The OpenBB Platform is a set of Python packages that turn financial and economic data sources into one typed Python client (from openbb import obb), a FastAPI REST API, and an MCP server.
openbb-core is the runtime. It ships no data and no commands; it discovers the extensions installed in the environment through entry points and assembles them. Everything else in this folder is an extension:
- Routers add command namespaces such as
obb.equityorobb.economy. - Providers implement those commands against a data source, and may add their own namespace such as
obb.fred. - OBBject extensions add accessors to every result, such as
result.charting.
Documentation lives at docs.openbb.co.
Repository layout
| Path | Contents |
|---|---|
core/ |
openbb-core: the runtime, the generated openbb package, and the REST API app. |
extensions/ |
Routers, plus the API launcher, the MCP server, and developer tooling. |
providers/ |
Data provider extensions. |
obbject_extensions/ |
Result accessors (openbb-charting). |
dev_install.py |
Editable install of every package for local development. |
../cli/ |
openbb-cli, the command-line interface. |
Packages
Core and tooling
| Package | Path | Description |
|---|---|---|
openbb-core |
core |
Runtime, extension loader, static package builder (openbb-build), and REST API app. |
openbb-platform-api |
extensions/platform_api |
openbb-api launcher for the REST API and the OpenBB Workspace custom-backend connector. |
openbb-mcp-server |
extensions/mcp_server |
openbb-mcp: serves the installed commands as Model Context Protocol tools. |
openbb-devtools |
extensions/devtools |
Linters, type checker, and test dependencies for development. |
openbb-cli |
../cli |
openbb: interactive command-line interface. |
Routers
| Package | Namespace |
|---|---|
openbb-commodity |
obb.commodity |
openbb-crypto |
obb.crypto |
openbb-currency |
obb.currency |
openbb-derivatives |
obb.derivatives |
openbb-econometrics |
obb.econometrics |
openbb-economy |
obb.economy |
openbb-equity |
obb.equity |
openbb-etf |
obb.etf |
openbb-fixedincome |
obb.fixedincome |
openbb-index |
obb.index |
openbb-news |
obb.news |
openbb-quantitative |
obb.quantitative |
openbb-technical |
obb.technical |
Providers
| Package | Path | Source | Credential |
|---|---|---|---|
openbb-bls |
providers/bls |
U.S. Bureau of Labor Statistics | bls_api_key |
openbb-cboe |
providers/cboe |
Cboe | None |
openbb-cftc |
providers/cftc |
CFTC and DTCC Public Price Dissemination | cftc_app_token |
openbb-deribit |
providers/deribit |
Deribit | None |
openbb-ecb |
providers/ecb |
European Central Bank | None |
openbb-famafrench |
providers/famafrench |
Ken French Data Library | None |
openbb-federal-reserve |
providers/federal_reserve |
Federal Reserve System, FOMC, and the twelve regional districts | None |
openbb-finra |
providers/finra |
FINRA | None |
openbb-fred |
providers/fred |
FRED | fred_api_key |
openbb-government-us |
providers/government_us |
U.S. Congress, U.S. Treasury, and USDA | congress_gov_api_key |
openbb-imf |
providers/imf |
International Monetary Fund | None |
openbb-jodi |
providers/jodi |
Joint Organisations Data Initiative | None |
openbb-nasdaq |
providers/nasdaq |
Nasdaq | None |
openbb-oecd |
providers/oecd |
OECD | None |
openbb-sec |
providers/sec |
SEC EDGAR | None |
openbb-tmx |
providers/tmx |
TMX (Canadian markets) | None |
openbb-us-eia |
providers/eia |
U.S. Energy Information Administration | eia_api_key |
OBBject extensions
| Package | Accessor |
|---|---|
openbb-charting |
result.charting: Plotly charts, with native window rendering through the pywry extra. |
Installation
Install openbb-core together with the routers and providers you need; openbb-core is pulled in by each of them.
pip install openbb-equity openbb-cboe
The openbb Python package is generated from whatever is installed. It rebuilds on import when the installed extensions change, and openbb-build rebuilds it explicitly after installing or removing an extension.
openbb-build
Python
from openbb import obb
output = obb.equity.price.historical("AAPL", provider="cboe")
df = output.to_dataframe()
Credentials
Providers that need a key read it as <provider>_<credential>, as listed in the provider table.
Set keys in ~/.openbb_platform/user_settings.json:
{
"credentials": {
"fred_api_key": "REPLACE_ME",
"bls_api_key": "REPLACE_ME"
}
}
Or as environment variables, which take precedence over the file. ~/.openbb_platform/.env is loaded automatically.
export FRED_API_KEY=REPLACE_ME
Or for the current session only:
from openbb import obb
obb.user.credentials.fred_api_key = "REPLACE_ME"
REST API
openbb-platform-api serves every installed command over FastAPI, with OpenAPI docs at /docs and a widgets.json for OpenBB Workspace.
pip install openbb-platform-api
openbb-api
The bare FastAPI app is openbb_core.api.rest_api:app and runs under any ASGI server.
uvicorn openbb_core.api.rest_api:app --host 127.0.0.1 --port 8000
MCP server
pip install openbb-mcp-server
openbb-mcp
See extensions/mcp_server/README.md for transports, tool discovery, and configuration.
Local development
Requirements:
- Git
- Python 3.11 or newer
- uv
From an activated virtual environment at the repository root:
python openbb_platform/dev_install.py --routers
This installs every tracked package under core, extensions, obbject_extensions, providers, and ../cli in editable mode, with all optional extras and each package's dev dependency group, then runs openbb-build. A new extension is picked up once its pyproject.toml is committed in one of those folders.
Router extensions (openbb-equity, openbb-economy, openbb-fixedincome, and the rest of the router table except openbb-news) are installed only with --routers. Without it, you get core, the tooling, openbb-news, the providers, openbb-charting, and the CLI.
Install the git hooks, which run the same ruff, ty, codespell, and markdownlint checks as CI:
pre-commit install
Each package is linted and tested from its own directory, matching its CI workflow:
cd openbb_platform/providers/fred
ruff format --check .
ruff check .
ty check openbb_fred
pytest tests
See CONTRIBUTING.md for extension guidelines.
License
Apache-2.0. See LICENSE.