This guide covers the full lifecycle of building, running, and serving a custom OpenBB Workspace application from an extension project scaffolded by `openbb-cookiecutter`. It assumes the project shell already exists (see the `develop_extension` skill for scaffolding instructions).
Scanned 5/31/2026
Install via CLI
Skills Directoryopenskills install gabrielmoreira/agent-skills-mirror---
name: build_workspace_app
description: This guide covers the full lifecycle of building, running, and serving a custom OpenBB Workspace application from an extension project scaffolded by `openbb-cookiecutter`. It assumes the project shell already exists (see the `develop_extension` skill for scaffolding instructions).
---
# Build and Run OpenBB Workspace Applications
This guide covers the full lifecycle of building, running, and serving a custom
OpenBB Workspace application from an extension project scaffolded by
`openbb-cookiecutter`. It assumes the project shell already exists
(see the `develop_extension` skill for scaffolding instructions).
---
## Prerequisites
Ensure the following packages are installed in the active Python environment:
```
pip install openbb-core openbb-platform-api openbb-devtools
```
- `openbb-core` provides the Router, Provider, OBBject, and Fetcher base classes.
- `openbb-platform-api` provides the `openbb-api` CLI for serving backends
and auto-generating `widgets.json` for OpenBB Workspace.
- `openbb-devtools` provides `pytest`, cassette recording, and QA utilities.
If you also need the Python Interface wrapper (the `obb` object), install the
main package:
```
pip install openbb --no-deps
```
---
## Architecture Overview
OpenBB is built on FastAPI and Pydantic. The application has two independent
interfaces that share core logic and models:
- **Python Interface** — wraps installed routers into an `obb` Python package
with auto-generated docstrings and function signatures. Requires a build step
(`openbb-build`) to generate static assets.
- **REST API** — a FastAPI instance with all installed routers available via
HTTP. Import it with `from openbb_core.api.rest_api import app` or launch
with `uvicorn openbb_core.api.rest_api:app`.
The application is the product of all installed extensions. With just `openbb-core`
there are no routers or endpoints — users compose their own combinations.
### Key Classes
| Class | Import | Purpose |
|---|---|---|
| `Router` | `openbb_core.app.router` | Subclass of `fastapi.APIRouter`; defines commands |
| `OBBject` | `openbb_core.app.model.obbject` | Standard response object with results, provider, warnings, extra |
| `Provider` | `openbb_core.provider.abstract.provider` | Registers fetchers for the provider interface |
| `Fetcher` | `openbb_core.provider.abstract.fetcher` | TET pipeline: Transform query → Extract data → Transform data |
| `QueryParams` | `openbb_core.provider.abstract.query_params` | Base class for input parameters |
| `Data` | `openbb_core.provider.abstract.data` | Base class for output data schemas |
---
## Router Extensions (API Endpoints)
Router extensions are the user-facing endpoints that power the REST API, MCP,
and Python Interface.
### Creating a Router
```python
from openbb_core.app.model.obbject import OBBject
from openbb_core.app.router import Router
router = Router(prefix="", description="My custom extension.")
```
The top-level API path prefix is determined by the entry point name in
`pyproject.toml`, not the `prefix` argument. Only use `prefix` for sub-routers.
```toml
[tool.poetry.plugins."openbb_core_extension"]
my_app = "my_package.routers.my_router:router"
```
Commands appear at `/my_app/...` in the API and `obb.my_app.` in Python.
### Provider Interface Endpoints
Connect a router command to one or more provider fetchers via the model name:
```python
from openbb_core.app.model.command_context import CommandContext
from openbb_core.app.model.obbject import OBBject
from openbb_core.app.provider_interface import ExtraParams, ProviderChoices, StandardParams
from openbb_core.app.query import Query
from pydantic import BaseModel
@router.command(model="MyModel")
async def my_command(
cc: CommandContext,
provider_choices: ProviderChoices,
standard_params: StandardParams,
extra_params: ExtraParams,
) -> OBBject[BaseModel]:
"""Description of this command."""
return await OBBject.from_query(Query(**locals()))
```
The four parameters and the `OBBject.from_query(Query(**locals()))` return are
mandatory and must be used exactly as shown.
### Basic GET Endpoint
```python
@router.command(methods=["GET"])
async def hello() -> OBBject[str]:
"""OpenBB Hello World."""
return OBBject(results="Hello from the extension!")
```
### Basic POST Endpoint
```python
from openbb_core.provider.abstract.data import Data
@router.command(methods=["POST"])
async def process(data: Data, some_param: str) -> OBBject:
"""Process submitted data."""
return OBBject(results=data.model_dump())
```
### Decorator Parameters
`@router.command` accepts:
- `model` — metamodel name linking to Provider fetchers
- `methods` — list of HTTP methods, typically `["GET"]` or `["POST"]`
- `examples` — list of `APIEx` or `PythonEx` for docs
- `deprecated` — deprecation notice
- `exclude_from_api` — Python Interface only
- `no_validate` — skip response validation, treat output as `Any`
- `openapi_extra` — dictionary for inline `widget_config` or `mcp_config`
### Using FastAPI APIRouter Directly
Access the underlying FastAPI router via `router._api_router`:
```python
@router._api_router.get("/also_empty")
async def also_empty(param: str) -> str:
"""Also empty."""
return "Hello world!"
```
---
## From FastAPI — Converting Existing Apps
Any existing FastAPI application can become an OpenBB extension without changing
code. Define the entry point in `pyproject.toml` pointed at the FastAPI or
APIRouter instance:
```toml
[tool.poetry.plugins."openbb_core_extension"]
my_app = "my_package.app:app"
```
Install the package and build static assets:
```
pip install -e .
openbb-build
```
Known limitations:
- Authorization hooks are not injected into the Python Interface
- Request-bound dependencies or those returning None are not injected
- WebSockets are not supported in the Python Interface
- Multi-method routes (GET + POST on same path) may not generate correctly
---
## Serving with openbb-api (Workspace Backends)
The `openbb-api` CLI converts a FastAPI instance into an OpenBB Workspace
backend with auto-generated widget definitions.
### Basic Usage
```
# Start with default OpenBB extensions
openbb-api
# Start with a custom FastAPI file
openbb-api --app ./my_app.py --host 0.0.0.0 --port 8005
# Factory function pattern
openbb-api --app my_app.py:create_app --factory
# Custom FastAPI instance name
openbb-api --app my_app.py --name my_app
```
Defaults are `--host 127.0.0.1 --port 6900`, falling back to the next
available port if already in use.
### Key Arguments
| Argument | Description |
|---|---|
| `--app` | Path to Python file with a FastAPI instance |
| `--name` | Name of the FastAPI instance (default: `app`) |
| `--factory` | Flag if the app name is a factory function |
| `--editable` | Make `widgets.json` editable at runtime |
| `--no-build` | Load existing `widgets.json` without checking for updates |
| `--exclude` | JSON list of API paths to exclude from widgets |
| `--widgets-json` | Custom path for `widgets.json` |
| `--apps-json` | Custom path for `workspace_apps.json` |
All remaining arguments are passed to `uvicorn.run`.
---
## Inline Widget Definitions
Widget properties can be defined inline in your code via `openapi_extra`:
```python
@app.get(
"/some_endpoint",
openapi_extra={
"widget_config": {
"name": "Custom Widget Name",
"description": "Override docstring description",
}
},
)
async def some_endpoint():
"""Description from docstring."""
pass
```
### Exclude an Endpoint from Widgets
```python
@app.get(
"/internal_endpoint",
openapi_extra={"widget_config": {"exclude": True}},
)
async def internal_endpoint():
return [{"label": "Choice 1", "value": "choice1"}]
```
### Dropdown Parameters
Dropdowns are auto-generated from `Literal` types:
```python
from typing import Literal
@app.get("/with_dropdown")
async def with_dropdown(
choices: Literal["Choice 1", "Choice 2", "Choice 3"] = "Choice 3"
):
pass
```
### Column Definitions for Tables
Use Pydantic response models to auto-generate table column definitions:
```python
import datetime
from pydantic import BaseModel, Field
class MyData(BaseModel):
date: datetime.date = Field(description="The date.")
value: float = Field(description="The value.")
@app.get("/my_data")
async def my_data() -> list[MyData]:
"""Widget with typed columns."""
return [MyData(date=datetime.date.today(), value=42.0)]
```
### Widget Types by Return Type
| Return Type | Widget Type |
|---|---|
| `list[dict]` or `list[BaseModel]` | Table (AgGrid) |
| `str` | Markdown |
| `dict` (with `widget_config.type="chart"`) | Plotly Chart |
| `MetricResponseModel` | Metric |
| `PdfResponseModel` | PDF |
### Response Models for Special Widgets
```python
from openbb_platform_api.response_models import MetricResponseModel, PdfResponseModel
@app.get("/metric", response_model=MetricResponseModel)
async def metric():
"""A metric widget."""
return dict(label="Revenue", value=12345, delta=5.67)
@app.get("/pdf", response_model=PdfResponseModel)
async def open_pdf(file_path: str):
"""Open a PDF document."""
with open(file_path, "rb") as f:
return dict(content=f.read())
```
### Plotly Chart Widget
```python
@app.get(
"/chart",
openapi_extra={"widget_config": {"type": "chart"}},
)
async def chart() -> dict:
"""A chart widget."""
from plotly.graph_objs import Bar, Layout, Figure
fig = Figure(
data=[Bar(x=["A", "B", "C"], y=[1, 2, 3])],
layout=Layout(title="My Chart", template="plotly_dark"),
)
return fig.to_plotly_json()
```
### JSON Schema Extra for Parameters
Annotate parameters with additional widget configuration:
```python
from typing import Annotated
from fastapi import Query
my_param: Annotated[
str,
Query(
title="My Title",
description="Detailed hover text",
json_schema_extra={
"x-widget_config": {
"optionsEndpoint": "/my_choices_endpoint"
}
},
),
]
```
### Form Input Widget
Create an input form tied to a table:
- GET endpoint defines `widget_config.form_endpoint` pointing to the POST route
- POST route accepts a single Pydantic model argument
---
## OBBject Extensions (Result Post-Processing)
Extend the `OBBject` response with custom methods, accessible in the Python Interface.
### Class Accessor (Namespaced Methods)
```python
from openbb_core.app.model.extension import Extension
ext = Extension(name="my_tools", description="Custom result tools.")
@ext.obbject_accessor
class MyTools:
def __init__(self, obbject):
self._obbject = obbject
def summary(self):
"""Return a summary."""
return self._obbject.to_dataframe().describe()
```
Register in `pyproject.toml`:
```toml
[tool.poetry.plugins."openbb_obbject_extension"]
my_tools = "my_package.obbject.my_ext:ext"
```
### Callable Accessor (Property-Like)
```python
ext = Extension(name="to_csv", description="Convert results to CSV.")
@ext.obbject_accessor
def to_csv(obbject):
"""Convert to CSV string."""
return obbject.to_dataframe().to_csv()
```
### OBBject Output Conversion Methods
Every `OBBject` has built-in conversion methods:
- `to_df()` / `to_dataframe()` — Pandas DataFrame
- `to_dict(orientation=...)` — Python dict
- `to_numpy()` — NumPy array
- `to_polars()` — Polars DataFrame (requires `polars` installed)
- `model_dump()` — Complete object as dict
- `model_dump_json()` — Serialized JSON string
---
## OBBject Plugins (Pre-Return Interceptors)
Plugins execute before the response is returned, compatible with both REST API
and Python Interface. They can conditionally alter the output of any command.
**WARNING**: Plugins are considered potentially dangerous. The environment must
be explicitly configured to allow them.
In `system_settings.json`:
```json
{
"allow_on_command_output": true,
"allow_mutable_extensions": true
}
```
### Plugin Configuration
```python
from openbb_core.app.model.extension import Extension
plugin = Extension(
name="my_plugin",
description="Intercept output before return.",
on_command_output=True,
command_output_paths=["/my_router/my_command"],
immutable=False,
results_only=False,
)
```
Key parameters:
- `on_command_output=True` — required for plugins
- `command_output_paths` — list of endpoint paths to intercept (None = all)
- `immutable=False` — set to allow modifying the response object
- `results_only=True` — receive only the `results` portion instead of full OBBject
### Plugin Code
```python
@plugin.obbject_accessor
def my_plugin_func(obbject):
"""Modify or inspect the response before it returns."""
# Modify obbject directly; do NOT return anything
pass
```
---
## Charting Extensions (Views)
Add custom chart views to any router endpoint, activated when the user sets
`chart=True`.
### Structure
```python
from typing import TYPE_CHECKING, Any
if TYPE_CHECKING:
from openbb_charting.core.openbb_figure import OpenBBFigure
class MyViews:
"""Chart views for the router."""
@staticmethod
def my_router_my_command(**kwargs) -> tuple["OpenBBFigure", dict[str, Any]]:
"""Chart for my_command."""
from openbb_charting.core.openbb_figure import OpenBBFigure
data = kwargs["obbject_item"]
fig = OpenBBFigure()
# Build chart with fig.add_*() methods
content = fig.show(external=True).to_plotly_json()
return fig, content
```
Method naming convention: `<router_name>_<command_name>` matching the route path
in lower_snake_case.
Register in `pyproject.toml`:
```toml
[tool.poetry.plugins."openbb_charting_extension"]
my_router = "my_package.routers.my_views:MyViews"
```
### Kwargs Available in Views
| Key | Content |
|---|---|
| `obbject_item` | Validated results object |
| `charting_settings` | User charting preferences |
| `standard_params` | Standard model parameters |
| `extra_params` | Provider-specific parameters |
| `provider` | Provider name used |
| `extra` | Execution metadata |
---
## HTTP Requests in Fetchers
Use the built-in utilities instead of creating new clients from scratch.
### Query String Helper
```python
from openbb_core.provider.utils.helpers import get_querystring
query_string = get_querystring(query.model_dump(), ["exclude_this_param"])
```
### Synchronous Requests
```python
from openbb_core.provider.utils import make_request
response = make_request(url, headers=headers, params=params)
```
### Requests Session
```python
from openbb_core.provider.utils.helpers import get_requests_session
session = get_requests_session()
```
### Asynchronous Requests (AIOHTTP)
```python
from openbb_core.provider.utils.helpers import amake_request
response_json = await amake_request(url)
```
### Multi-URL Async Requests
```python
from openbb_core.provider.utils.helpers import amake_requests
results = await amake_requests([url1, url2, url3])
```
### Custom Response Callback
```python
from io import StringIO
from pandas import DataFrame
results = []
async def response_callback(response, _):
text = await response.text()
data = DataFrame(StringIO(text), skiprows=2)
results.append(data.to_dict("records"))
await amake_requests(url, response_callback=response_callback)
```
### Async Session
```python
from openbb_core.provider.utils.helpers import get_async_requests_session
async with await get_async_requests_session() as session:
async with await session.get(url) as response:
data = await response.json()
```
### Async Fetchers
Use `aextract_data` instead of `extract_data` for async fetchers:
```python
@staticmethod
async def aextract_data(
query: MyQueryParams,
credentials: dict[str, str] | None,
**kwargs: Any,
) -> list[dict]:
"""Async data extraction."""
...
```
---
## Testing
### Built-In Fetcher Test
Every Fetcher has a `.test()` method for quick validation:
```python
from my_package.providers.my_provider.models.my_model import MyFetcher
fetcher = MyFetcher()
fetcher.test({"symbol": "AAPL"}, {}) # Returns None on success
```
### Unit Tests with Cassettes
Install dev tools and use `pytest_recorder` for HTTP cassette recording:
```
pip install openbb-devtools
pytest test_my_fetcher.py --record http
```
Subsequent test runs replay the recorded HTTP interactions.
### Running Tests
```
# Unit tests only
pytest tests/ -m "not integration"
# Integration tests only
pytest tests/ -m integration
# All tests
pytest tests/
```
### Integration Testing
For API integration tests, start a local server first:
```
uvicorn openbb_core.api.rest_api:app --host 0.0.0.0 --port 8000 --reload
```
---
## Install and Build
### Development Install
From the project root:
```
pip install -e ".[dev]"
```
### Build Python Interface
After installing or removing extensions, regenerate static assets:
```
openbb-build
```
### Verify in Python
```python
from openbb import obb
# Your commands appear under obb.<router_name>.<command_name>()
```
### Serve as Workspace Backend
```
openbb-api --app ./my_app.py --editable --host 0.0.0.0 --port 6900
```
---
## Workflow Summary
When a user asks "Build me a Workspace application that does X":
1. **Scaffold** the project with `openbb-cookiecutter` (see `develop_extension` skill).
2. **Remove** example files and clean up boilerplate.
3. **Implement fetchers** for each data source in `providers/<name>/models/`.
4. **Register fetchers** in `providers/<name>/__init__.py` via `fetcher_dict`.
5. **Implement router commands** in `routers/<name>.py`.
6. **Add widget config** via `openapi_extra` for Workspace-specific behavior.
7. **Update `pyproject.toml`** entry points and dependencies.
8. **Install** with `pip install -e ".[dev]"`.
9. **Build** static assets with `openbb-build`.
10. **Serve** with `openbb-api` and verify widgets in OpenBB Workspace.
11. **Test** with `pytest` and fetcher `.test()` methods.
No comments yet. Be the first to comment!
