Dashboards¶

Strategy dashboards are Streamlit pages loaded by the hosted platform's dashboard image and by almanak dashboard locally. Both call your render_custom_dashboard() with the same arguments.

Anatomy of a dashboard¶

If a built-in template renderer fits your strategy, call it. The renderer owns the title, the strategy header (Deployment ID / pool / chain markdown), and the three audit sections (PnL, cost stack, trade tape). Do not wrap it with your own st.title(...) or audit-section helpers — that double-renders the title and the audit panels.

from almanak.framework.dashboard.templates import get_bollinger_config, render_ta_dashboard

def render_custom_dashboard(deployment_id, strategy_config, api_client, session_state):
    config = get_bollinger_config(period=20, std_dev=1.0)
    render_ta_dashboard(deployment_id, strategy_config, session_state, config)

Need to add summary cards or extra metrics? Call the renderer first and append your own widgets after — see strategies/accounting/lp/dashboard/ui.py and strategies/accounting/looping/dashboard/ui.py for committed reference implementations of that pattern (renderer + st.divider() + bespoke st.metric(...) cards below).

Need a custom title or to replace the audit sections entirely? Hand-roll the dashboard instead — see the next snippet. What you must NOT do is wrap render_*_dashboard() with extra st.title(...) / render_pnl_section(...) calls; the template already emits those, so you'll double-render.

If no template fits, hand-roll Streamlit and wire the audit primitives yourself (this is what almanak strat new scaffolds for blank / multi-step templates; LP / lending / TA / perp templates scaffold the template-renderer path above):

import streamlit as st
from almanak.framework.dashboard import (
    render_pnl_section, render_cost_stack_section, render_trade_tape_section,
)

def render_custom_dashboard(deployment_id, strategy_config, api_client, session_state):
    st.title("My Custom Strategy")
    render_pnl_section(deployment_id)
    # your indicator / position / performance UI
    render_cost_stack_section(deployment_id)
    render_trade_tape_section(deployment_id)

Audit primitives¶

almanak.framework.dashboard ¶

Almanak Strategy Framework v2.0 - Dashboard

Public exports for dashboard data access, rendering, and PM integration. External consumers (PM dashboard, custom UIs) should import from here.

The streamlit-using render_*_section helpers are resolved lazily via :pep:562 __getattr__ so that gateway-side consumers — which import almanak.framework.dashboard.quant_aggregations to build PnL / cost-stack RPC responses — do not transitively pay the cost of loading streamlit at package init. The gateway image strips streamlit (see deploy/docker/strip-list-gateway.txt); an eager re-export here would ModuleNotFoundError on every dashboard RPC in production (VIB-4048). Regression guard: tests/gateway/test_imports_lean.py.

For strategy authors writing a dashboard/ui.py for their strategy, the recommended convention is to frame render_custom_dashboard() with three section helpers (VIB-3969) so accounting is visually QA'able locally and on the hosted platform from the same single-source code path:

render_pnl_section(deployment_id) — top, the 5-second eyeball
render_cost_stack_section(deployment_id) — bottom, life-to-date costs
render_trade_tape_section(deployment_id) — bottom, TX-level audit

Usage::

from almanak.framework.dashboard import (
    DashboardDataClient,
    Strategy,
    render_cost_stack_section,
    render_pnl_section,
    render_strategy_detail,
    render_strategy_timeline,
    render_trade_tape_section,
    strategy_from_pm_dict,
)

render_pnl_section ¶

render_pnl_section(deployment_id: str) -> None

Render the 5-second-eyeball PnL section (VIB-3969).

Money Trail row: Deployed / NAV / Lifetime PnL / Net APR. The standard top-of-dashboard card so an operator answers "am I making or losing money?" before scrolling. Backed by the gateway's GetPnLSummary RPC; on RPC failure the section degrades to an info banner rather than crashing the page.

Conventionally placed immediately below the strategy title.

参数：

名称	类型	描述	默认
`deployment_id`	`str`	The deployment id (passed straight through from `render_custom_dashboard`'s first positional argument).	必需

render_cost_stack_section ¶

render_cost_stack_section(
    deployment_id: str, *, heading: str = "### Cost Stack"
) -> None

Render the life-to-date Cost Stack section (VIB-3969).

Gas / Fees / Slippage / Earn — generic across primitives (every primitive emits these into transaction_ledger + accounting_events). Backed by the gateway's GetCostStack RPC; on RPC failure the section degrades to an info banner.

Conventionally placed at the start of an "Audit" section, just above the trade tape.

参数：

名称	类型	描述	默认
`deployment_id`	`str`	The deployment id.	必需
`heading`	`str`	Override the section heading. Pass an empty string to suppress the heading entirely (useful when composing inside a larger Audit panel that already has its own heading).	`'### Cost Stack'`

render_trade_tape_section ¶

render_trade_tape_section(
    deployment_id: str, *, limit: int = 50
) -> None

Render the standard trade-tape section.

Conventionally placed at the bottom of every render_custom_dashboard() so accounting can be visually QA'd locally and on the hosted platform from the same code path. The underlying render_trade_tape reads through the gateway's DashboardService.GetTradeTape, which abstracts SQLite (local) and Postgres (hosted) — the section travels everywhere the gateway does.

参数：

名称	类型	描述	默认
`deployment_id`	`str`	The deployment id (passed straight through from `render_custom_dashboard`'s first positional argument).	必需
`limit`	`int`	Most recent intents to fetch. Defaults to 50.	`50`

Template renderers¶

Pre-built sections for common strategy types. Each renderer is paired with factory configs that adapt the rendering to a specific protocol or indicator. Use these to fill the middle of the dashboard instead of hand-rolling indicator/position/performance UI.

Technical analysis (RSI, MACD, Bollinger, …)¶

almanak.framework.dashboard.templates.ta_dashboard ¶

Technical Analysis (TA) Dashboard Template.

Reusable template for creating dashboards for indicator-based strategies. Supports any TA indicator with configurable signal logic and visualization.

Scope (single-position): the template drives one position on one base_token/quote_token pair. The 3 accounting sections (PnL, Cost Stack, Trade Tape) are baked in so every TA dashboard ships with full accounting by default.

Single indicator — pass one TADashboardConfig.
Multiple indicators (multi-signal, VIB-4897) — compose with :func:multi_ta_config. The template stacks one panel per indicator under a shared price chart (all on one time axis). Useful for confluence strategies (e.g. RSI + MACD + Bollinger).

For genuinely multi-position layouts the template is still the wrong tool — hand-roll from the section helpers (render_pnl_section, render_cost_stack_section, render_trade_tape_section) plus the primitive plot helpers in almanak.framework.dashboard.plots. See the dashboard blueprints.

Usage (single indicator): from almanak.framework.dashboard.templates import TADashboardConfig, render_ta_dashboard

config = TADashboardConfig(
    indicator_name="RSI", indicator_period=14,
    upper_threshold=70, lower_threshold=30, signal_type="reversion",
)

def render_custom_dashboard(deployment_id, strategy_config, api_client, session_state):
    # Pass deployment_id so the price chart follows the operator-selected
    # NAV range (24h/7d/30d) when one is picked (VIB-5114); omitting it
    # keeps the legacy recent-window fetch.
    session_state = prepare_ta_session_state(
        api_client, session_state, config, deployment_id=deployment_id
    )
    render_ta_dashboard(deployment_id, strategy_config, session_state, config)

Usage (multi-signal): from almanak.framework.dashboard.templates import ( get_rsi_config, get_macd_config, get_bollinger_config, multi_ta_config, prepare_ta_session_state, render_ta_dashboard, )

config = multi_ta_config(get_rsi_config(), get_macd_config(), get_bollinger_config())

def render_custom_dashboard(deployment_id, strategy_config, api_client, session_state):
    session_state = prepare_ta_session_state(
        api_client, session_state, config, deployment_id=deployment_id
    )
    render_ta_dashboard(deployment_id, strategy_config, session_state, config)

TADashboardConfig `dataclass` ¶

TADashboardConfig(
    indicator_name: str,
    indicator_period: int = 14,
    secondary_periods: list[int] = list(),
    upper_threshold: float | None = None,
    lower_threshold: float | None = None,
    signal_type: Literal[
        "reversion", "momentum"
    ] = "reversion",
    value_format: str = "{:.1f}",
    value_suffix: str = "",
    custom_signal_fn: Callable[[dict[str, Any]], str]
    | None = None,
    chain: str = "Arbitrum",
    protocol: str = "Uniswap V3",
    base_token: str = "WETH",
    quote_token: str = "USDC",
    timeframe: str = "1h",
    extra_indicators: list[TADashboardConfig] = list(),
    display_window_seconds: int = DEFAULT_DISPLAY_WINDOW_SECONDS,
)

Configuration for a TA dashboard.

属性：

名称	类型	描述
`indicator_name`	`str`	Name of the indicator (e.g., "RSI", "MACD", "CCI")
`indicator_period`	`int`	Primary period for the indicator
`secondary_periods`	`list[int]`	Additional periods (e.g., signal line for MACD)
`upper_threshold`	`float \| None`	Upper threshold for signals (overbought/bullish)
`lower_threshold`	`float \| None`	Lower threshold for signals (oversold/bearish)
`signal_type`	`Literal['reversion', 'momentum']`	Type of signal logic - "reversion" or "momentum"
`value_format`	`str`	Format string for displaying indicator value (e.g., "{:.1f}", "{:+.2f}")
`value_suffix`	`str`	Suffix for indicator value (e.g., "%", " bps")
`custom_signal_fn`	`Callable[[dict[str, Any]], str] \| None`	Optional custom function for signal determination
`chain`	`str`	Default chain name
`protocol`	`str`	Default protocol name
`base_token`	`str`	Default base token
`quote_token`	`str`	Default quote token
`timeframe`	`str`	OHLCV candle interval the dashboard fetches and computes the indicator series from — one of `1m`/`5m`/`15m`/`1h`/`4h`/`1d`. Defaults to `"1h"` for back-compat. Must match the strategy's own `data_granularity`: otherwise the dashboard RSI/MACD/etc. line is a different series from the one the strategy decides on, so buy/sell markers won't align with the indicator band (VIB-4969). For the multi-signal layout the primary config's `timeframe` is authoritative (one shared OHLCV fetch); extras' timeframes are ignored, mirroring how their pair/chain are ignored.
`extra_indicators`	`list[TADashboardConfig]`	Additional indicator configs to render as stacked panels (multi-signal layout, VIB-4897). Empty by default — the single-indicator path is unchanged. Compose via :func:`multi_ta_config`. Each extra contributes one more panel beneath the price chart; the extras' pair/chain/timeframe are ignored (the primary config drives the shared OHLCV fetch).
`display_window_seconds`	`int`	Default visible span of the price/indicator x-axis, in seconds (VIB-5345). Decoupled from the FETCH span: the dashboard still fetches the wide candle window (`timeframe` cap + signal backfill) and computes the indicator over that full series — this only bounds how much is plotted by default so a freshly deployed strategy's recent action is not crowded into a multi-day axis. Anchored to the strategy's own timeline (see :func:`~almanak.framework.dashboard.templates._ohlcv_window.display_window_bounds`): the window never extends before the strategy start, and a hard floor of `now - display_window_seconds` guards against an unreliable reported start (VIB-5343). Defaults to one day (:data:`~almanak.framework.dashboard.templates._ohlcv_window.DEFAULT_DISPLAY_WINDOW_SECONDS`); set `<= 0` to disable the cap and plot the full fetched span.

multi_ta_config ¶

multi_ta_config(
    primary: TADashboardConfig, *extras: TADashboardConfig
) -> TADashboardConfig

Compose a multi-indicator (multi-signal) TA dashboard config.

The first config is the primary — it drives the dashboard title, the configured pair/chain, the shared OHLCV fetch, and the signal-status section. Each additional config renders as one more stacked indicator panel beneath the price chart. Indicator params (periods / thresholds) on the extras are honoured; their base_token / quote_token / chain are not — the primary's pair is authoritative so every panel shares one time axis.

Example::

config = multi_ta_config(
    get_rsi_config(period=14),
    get_macd_config(),
    get_bollinger_config(period=20, std_dev=2.0),
)
session_state = prepare_ta_session_state(api_client, session_state, config)
render_ta_dashboard(deployment_id, strategy_config, session_state, config)

Returns a new config (does not mutate primary).

prepare_ta_session_state ¶

prepare_ta_session_state(
    api_client: Any,
    session_state: dict[str, Any] | None = None,
    config: TADashboardConfig | None = None,
    *,
    deployment_id: str | None = None,
) -> dict[str, Any]

Enrich session state for render_ta_dashboard (chart subplot).

Mirrors :func:prepare_lp_session_state: fetches OHLCV via the api_client, computes the indicator series client-side, reads the trade tape for buy/sell markers, and loads wallet balances for the Current Position section — strategy authors don't write any of that plumbing. Without this helper the chart section silently degrades to Price history data not available (nothing populates price_history / rsi_history / buy_signals / sell_signals) and the Current Position section reads 0.0000 / $0.00 / $0.00 (nothing populates base_balance / quote_balance / base_price).

参数：

名称	类型	描述	默认
`api_client`	`Any`	`DashboardAPIClient` (or a duck-typed mock).	必需
`session_state`	`dict[str, Any] \| None`	Optional pre-existing state. Caller-supplied keys are preserved — never overwritten — so custom dashboards that already populate `price_history` keep working.	`None`
`config`	`TADashboardConfig \| None`	`TADashboardConfig` describing the indicator, pair, and chain. Required to know which token to fetch OHLCV for.	`None`
`deployment_id`	`str \| None`	Optional deployment id used to read the operator's selected NAV range from `session_state` (VIB-5114). When supplied AND the operator has picked a bounded range (24h/7d/30d) on the shared NAV chart, the candle granularity + the marker window follow that range. When `None` (the default, every legacy call site) or no range is selected, the fetch is byte-for-byte the configured recent window — full backward compatibility.	`None`

返回：

类型	描述
`dict[str, Any]`	The enriched session_state dict. Always returns; degrades to the
`dict[str, Any]`	unenriched state on any API failure rather than raising.

render_ta_dashboard ¶

render_ta_dashboard(
    deployment_id: str,
    strategy_config: dict[str, Any],
    session_state: dict[str, Any],
    config: TADashboardConfig,
) -> None

Render a technical analysis dashboard using the provided configuration.

Single-position template. Renders one indicator panel by default; pass a :func:multi_ta_config (config.extra_indicators set) to stack one panel per indicator under a shared price chart (multi-signal, VIB-4897). Bakes in the 3 accounting sections (PnL → chart content → Cost Stack → Trade Tape). For multi-position layouts, compose a custom dashboard from the section helpers directly rather than parameterizing this template.

参数：

名称	类型	描述	默认
`deployment_id`	`str`	The deployment identifier	必需
`strategy_config`	`dict[str, Any]`	Strategy configuration dictionary	必需
`session_state`	`dict[str, Any]`	Current session state with indicator values	必需
`config`	`TADashboardConfig`	TADashboardConfig for this dashboard	必需

get_rsi_config ¶

get_rsi_config(
    period: int = 14,
    overbought: float = 70,
    oversold: float = 30,
    timeframe: str = "1h",
) -> TADashboardConfig

Get pre-configured RSI dashboard config.

timeframe must match the strategy's data_granularity so the dashboard RSI is computed from the same candles the strategy decides on (VIB-4969). Defaults to "1h" for back-compat.