Build Workspace App

---
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.