OpenBB/openbb_platform/core

openbb-core

openbb-core is the runtime that turns a collection of installed Python packages into the OpenBB Platform. By itself it ships no data, no providers, and no commands. Its job is to:

1. Discover provider, command, and result-type extensions installed in the current Python environment via setuptools entry points.
2. Stitch them together into a single typed Python client (from openbb import obb) and an equivalent FastAPI REST API.
3. Execute calls against those extensions, normalise the output through shared Pydantic models, and return a uniform OBBject result wrapper.

If you are an end user, you install openbb (which depends on this package) and one or more provider extensions. If you are an extension author, you depend on openbb-core and register one of the entry points below.

Entry points

Extensions plug into the runtime through three setuptools entry-point groups defined in openbb_core/app/extension_loader.py. At import time, ExtensionLoader enumerates each group and the rest of the platform consumes the results.

openbb_core_extension

A Router to mount under the platform. Each entry point is loaded as an openbb_core.app.router.Router instance and merged into the root router. This is how command surfaces such as obb.equity, obb.economy, obb.derivatives get added.

# pyproject.toml of an extension
[project.entry-points."openbb_core_extension"]
equity = "openbb_equity.equity_router:router"

openbb_provider_extension

A Provider describing a data source — its credentials, the standard models it implements, and the Fetcher classes that satisfy them. Routers do not hard-code providers; they declare a standard model, and at call time the runtime picks a Fetcher from any installed provider that implements it.

[project.entry-points."openbb_provider_extension"]
yfinance = "openbb_yfinance:yfinance_provider"

openbb_obbject_extension

An Extension (see openbb_core/app/model/extension.py) attached to the OBBject result wrapper. There are two flavours, configured on the same Extension instance:

1. Accessor extensions (default — on_command_output=False)

Add a namespace attribute on every OBBject, pandas-style. The entry-point name becomes the attribute name. Used for opt-in transformations the caller explicitly invokes:

result = obb.equity.price.historical("AAPL")
result.charting.to_chart()  # accessor registered by openbb_charting

[project.entry-points."openbb_obbject_extension"]
charting = "openbb_charting:ext"   # ext = Extension(name="charting")

2. on_command_output callbacks (post-execution hooks)

Set on_command_output=True to make the extension run automatically on the OBBject returned by every command, or only by specific routes via command_output_paths. ExtensionLoader._register_command_output_callbacks indexes them by path (with "*" meaning "all commands") and the API layer (openbb_core/api/router/commands.py) applies them after the command runs.

Three flags govern their behaviour:

• on_command_output: bool — enable the post-execution hook.
• command_output_paths: list[str] | None — restrict to specific endpoint paths; None means every command.
• immutable: bool = True — if False, the hook may modify OBBject.results in place. Mutable hooks additionally require system_settings.allow_mutable_extensions=True.
• results_only: bool = False — return just OBBject.results over the REST API instead of the full envelope.

[project.entry-points."openbb_obbject_extension"]
my_hook = "openbb_my_hook:ext"
# ext = Extension(
#     name="my_hook",
#     on_command_output=True,
#     command_output_paths=["/equity/price/historical"],
#     immutable=False,
# )

Because these hooks run on every matching response, they are gated by an explicit opt-in: system_settings.allow_on_command_output (env: OPENBB_ALLOW_ON_COMMAND_OUTPUT) must be True, or instantiating the Extension will raise. Mutating hooks need allow_mutable_extensions (env: OPENBB_ALLOW_MUTABLE_EXTENSIONS) on top of that. Treat on_command_output extensions as code that runs against every result — only install them from sources you trust.

Console script: openbb-build

openbb-core installs one console script:

openbb-build

It is defined in openbb_core/build.py (openbb-build = openbb_core.build:main). It imports the openbb package in a subprocess, which triggers static-client generation when the generated package is missing or stale, and falls back to calling openbb.build() explicitly if the import did not rebuild. Run it after installing or upgrading any extension to regenerate openbb/package/ and reference.json.

What lives inside the package

• openbb_core.provider — base classes (Data, QueryParams, Provider, Fetcher) and the registry that turns openbb_provider_extension entries into a queryable map of (standard_model, provider) -> Fetcher.
• openbb_core.provider.standard_models — the shared Pydantic schemas (equity prices, options chains, CPI, treasury rates, etc.) that every provider maps onto. This is what makes "swap providers without changing caller code" possible.
• openbb_core.app.router.Router — a thin wrapper around FastAPI's APIRouter used by openbb_core_extension packages to declare commands.
• openbb_core.app.command_runner — the execution path used by the generated Python client: resolves provider choice, runs the matching Fetcher, applies post-processing hooks, and returns an OBBject.
• openbb_core.app.static.package_builder — walks the merged router and emits the typed openbb/package/ modules plus reference.json. This is what openbb-build ultimately drives.
• openbb_core.api.rest_api — the FastAPI app (app) built from the same routers, with auth hooks and OpenAPI generation. Serve it with any ASGI server.
• openbb_core.app.extension_loader — the entry-point discovery layer described above.
• openbb_core.app.service — system settings, user settings, credentials, and auth services shared by the runtime and the REST API.
• openbb_core.app.logs — structured logging with rotating file handlers.

Prerequisites

• Python >=3.10,<4
• For extension authors: working knowledge of FastAPI and Pydantic v2.

Installation

pip install openbb-core

You normally do not install openbb-core directly — openbb and provider extensions pull it in. Install it explicitly only when authoring an extension.

Running the REST API

uvicorn openbb_core.api.rest_api:app --reload

The same router graph that backs from openbb import obb is exposed over HTTP, with OpenAPI available at /docs.

Bugs

Report bugs on GitHub.

License

Apache-2.0. See LICENSE.