Command Execution Engine

Relevant source files

• frontend-components/plotly/src/data/mockup.ts
• openbb_platform/core/openbb_core/api/router/commands.py
• openbb_platform/core/openbb_core/app/command_runner.py
• openbb_platform/core/openbb_core/app/extension_loader.py
• openbb_platform/core/openbb_core/app/logs/handlers_manager.py
• openbb_platform/core/openbb_core/app/logs/logging_service.py
• openbb_platform/core/openbb_core/app/logs/models/logging_settings.py
• openbb_platform/core/openbb_core/app/model/abstract/tagged.py
• openbb_platform/core/openbb_core/app/model/defaults.py
• openbb_platform/core/openbb_core/app/model/extension.py
• openbb_platform/core/openbb_core/app/model/obbject.py
• openbb_platform/core/openbb_core/app/model/system_settings.py
• openbb_platform/core/openbb_core/app/service/system_service.py
• openbb_platform/core/openbb_core/app/static/container.py
• openbb_platform/core/openbb_core/env.py
• openbb_platform/core/tests/app/logs/test_handlers_manager.py
• openbb_platform/core/tests/app/logs/test_logging_service.py
• openbb_platform/core/tests/app/model/test_extension.py
• openbb_platform/core/tests/app/model/test_obbject.py
• openbb_platform/core/tests/app/model/test_system_settings.py
• openbb_platform/core/tests/app/test_command_runner.py
• openbb_platform/obbject_extensions/charting/openbb_charting/charts/helpers.py

The Command Execution Engine is responsible for executing commands in the OpenBB Platform. It handles parameter validation, command invocation, result wrapping in OBBject containers, extension callback triggering, and execution logging. This engine provides a unified execution flow for all user interfaces (Python SDK, CLI, API, Workspace).

For information about how commands are routed to this execution engine, see Architecture. For details on the provider abstraction that the engine delegates to for data fetching, see Provider Architecture.

Core Components

The execution engine consists of four primary classes that work together to process commands:

Class	Location	Responsibility
CommandRunner	openbb_core/app/command_runner.py642-723	Main entry point; manages system/user settings and delegates to StaticCommandRunner
ExecutionContext	openbb_core/app/command_runner.py34-57	Container for execution metadata (route, settings, command map)
ParametersBuilder	openbb_core/app/command_runner.py59-237	Validates and builds function parameters from args/kwargs
StaticCommandRunner	openbb_core/app/command_runner.py240-641	Executes commands, wraps results, triggers callbacks, logs execution

Sources: openbb_core/app/command_runner.py1-723

CommandRunner

The CommandRunner class is instantiated once per session and maintains system and user settings. It provides both async (run) and sync (sync_run) interfaces for command execution.

Sources: openbb_core/app/command_runner.py642-723

ExecutionContext

ExecutionContext bundles all metadata required for command execution. It includes:

• command_map: Maps routes to command functions
• route: The command path (e.g., /equity/price/historical)
• system_settings: Platform-wide configuration
• user_settings: User-specific preferences and credentials
• api_route: FastAPI route metadata (accessed via _route_map)

Sources: openbb_core/app/command_runner.py34-57

Command Execution Lifecycle

The execution lifecycle flows through multiple stages, from parameter validation to result wrapping and logging:

The execution process performs these steps:

1. Context Creation: Bundle route, settings, and command map into ExecutionContext
2. Parameter Building: Merge positional/keyword args, inject dependencies, validate types
3. Function Execution: Call the command function with validated parameters
4. Result Wrapping: Create OBBject container with results, provider info, warnings
5. Extension Callbacks: Trigger registered OBBject extensions (e.g., charting)
6. Metadata Addition: Add execution metadata (duration, timestamp, arguments)
7. Logging: Log command execution to configured handlers

Sources: openbb_core/app/command_runner.py431-535 openbb_core/app/command_runner.py244-427

ParametersBuilder

The ParametersBuilder class transforms raw function arguments into validated, type-coerced parameters:

Parameter Processing Steps

1. Merge Args and Kwargs (openbb_core/app/command_runner.py89-124): Converts positional arguments to keyword arguments based on function signature

2. Update Command Context (openbb_core/app/command_runner.py127-144): Injects CommandContext if function signature includes cc parameter

3. Validate and Coerce (openbb_core/app/command_runner.py181-206): Creates a Pydantic model from function signature to validate and type-coerce all parameters

4. Warn on Unknown Parameters (openbb_core/app/command_runner.py147-168): Emits OpenBBWarning if extra parameters are passed that don't match the function signature

Sources: openbb_core/app/command_runner.py59-237

Parameter Validation Example

The validator creates a dynamic Pydantic model to ensure type safety:

This approach automatically converts string "2" to integer 2, validates enums, and ensures required parameters are present.

Sources: openbb_core/app/command_runner.py181-206

OBBject Output Container

All command results are wrapped in an OBBject instance, which provides a standardized output format across all interfaces:

OBBject Fields

Field	Type	Description
results	T | None	The actual data returned by the command (list, dict, DataFrame, etc.)
provider	str | None	Name of the provider that fetched the data (e.g., "fmp", "yfinance")
warnings	list[Warning_]	Any warnings raised during execution
chart	Chart | None	Plotly chart object if charting is enabled
extra	dict	Additional metadata including execution details

Sources: openbb_core/app/model/obbject.py36-72

Data Conversion Methods

OBBject provides multiple methods to convert results into common data formats:

Method	Return Type	Description
to_dataframe()	DataFrame	Convert results to Pandas DataFrame with optional index/sorting
to_dict()	dict | list[dict]	Convert to dictionary using Pandas orient options
to_numpy()	ndarray	Convert to NumPy array
to_polars()	PolarsDataFrame	Convert to Polars DataFrame
to_llm()	dict | list[dict]	Convert to LLM-compatible JSON format

The to_dataframe() method supports multiple input formats including lists of BaseModels, dicts, and nested data structures. It handles complex cases like multiple date columns with timezone awareness.

Sources: openbb_core/app/model/obbject.py81-353

Extension Callbacks

After command execution, the engine triggers registered OBBject extension callbacks. These extensions can add functionality like charting, analytics, or custom transformations:

Extension Callback Flow

Extensions are registered in the ExtensionLoader and categorized by route. The callback system:

1. Loads Callbacks (openbb_core/app/command_runner.py538-543): Retrieves all registered extensions from ExtensionLoader.on_command_output_callbacks

2. Filters by Route (openbb_core/app/command_runner.py581-591): Executes extensions registered for "*" (all routes) or the specific route

3. Clones for Immutable Extensions (openbb_core/app/command_runner.py565-576): Creates a copy of OBBject if extension is marked as immutable

4. Executes Accessor (openbb_core/app/command_runner.py594-621): Calls the extension's accessor function (may be async)

5. Sets Modification Flags (openbb_core/app/command_runner.py623-628): Updates _extension_modified and _results_only attributes

Sources: openbb_core/app/command_runner.py537-641

Extension Types

Extension Property	Effect
immutable=True	Extension runs on a copy; original OBBject unchanged
immutable=False	Extension modifies the original OBBject; requires allow_mutable_extensions=True
results_only=True	API returns only the results field instead of full OBBject
command_output_paths=["route1", "route2"]	Extension only triggers for specified routes

Sources: openbb_core/app/model/extension.py7-141

Logging and Metadata

The execution engine integrates with the LoggingService to record all command executions:

Logging Process

The logging flow (openbb_core/app/command_runner.py412-425):

1. Instantiate LoggingService: Creates service with current system/user settings
2. Extract Execution Info: Gathers route, kwargs, exception info, custom headers
3. Format Log Message: Constructs JSON message with CMD: or ERROR: prefix
4. Send to Handlers: Dispatches to configured handlers (file, stdout, stderr)

Log Message Structure

Sources: openbb_core/app/logs/logging_service.py199-283

Metadata Attachment

After execution, the engine adds metadata to OBBject.extra["metadata"] (openbb_core/app/command_runner.py458-505):

Metadata Field	Description
arguments	All parameters passed to command (standard_params, extra_params, provider_choices)
duration	Execution time in nanoseconds
route	Command route path
timestamp	Execution start time

The metadata includes cleaned parameters with dependency injections removed to ensure serialization compatibility.

Sources: openbb_core/app/command_runner.py458-534

Chart Generation

When chart=True is passed to a command, the engine triggers chart generation via the charting extension:

The chart generation process (openbb_core/app/command_runner.py261-296):

1. Extract Chart Parameters: Pulls chart_params from extra_params in kwargs
2. Verify Charting Installed: Checks if "charting" accessor exists on OBBject
3. Call Charting Extension: Invokes obbject.charting.show(render=False, **params)
4. Attach to OBBject: Chart object is stored in obbject.chart field

Sources: openbb_core/app/command_runner.py261-296

API Integration

The command runner integrates with FastAPI through a wrapper function that handles authentication and response formatting:

The API wrapper (openbb_core/api/router/commands.py212-342):

1. Extracts User Settings: Gets authenticated user settings from dependency injection
2. Applies Defaults: Merges user default preferences for the command
3. Executes Command: Calls command_runner.run() with processed parameters
4. Handles Extensions: If extensions modified output, returns as JSONResponse
5. Validates Output: For unmodified output, validates against OBBject schema

Sources: openbb_core/api/router/commands.py212-342

Error Handling

The execution engine catches and logs errors while preserving the stack trace:

Error handling occurs at multiple levels:

1. Function Execution (openbb_core/app/command_runner.py322-427): Wraps command execution in try/finally to ensure logging happens
2. Warning Capture (openbb_core/app/command_runner.py323): Uses catch_warnings() context manager to capture warnings
3. Logging (openbb_core/app/command_runner.py412-425): Logs error with full exception info
4. Warning Attachment (openbb_core/app/command_runner.py396-410): Attaches captured warnings to OBBject.warnings

The finally block ensures logging always occurs, even if the command raises an exception.

Sources: openbb_core/app/command_runner.py322-427

Execution Flow Summary

The complete execution flow through the command runner:

Sources: openbb_core/app/command_runner.py431-535 openbb_core/app/command_runner.py690-710