builder_set_allocation MCP Tool

Back to MCP catalog

builder_set_allocation

Set the basket allocation policy: cross-instrument weighting, rebalance schedule, and capital model.

Area

Strategy Builder

Group

Config & allocation

Access

Write

Risk

May change server state

Details

Full description

Set the basket allocation policy (cross-instrument weighting + rebalance + capital model). Sets Strategy.allocation.

Meaningful only for a basket (len(instruments) >= 2); a single-instrument leaf has no siblings to allocate across and is rejected.

This is the rotation surface: "rotate into the top N by <signal>, rebalance weekly" becomes mode='rank_based', score=<signal>, top_n=N, rebalance='weekly'. It sets intent-level construction and never touches per-symbol weights.

Naming — weight here is the cross-instrument construction weighting. Within-leaf position sizing (allocation) is set separately via builder_set_strategy_config(patch={'sizing': ...}).

Valid combinations (the only supported shapes):

equal_weight + none                                   → static equal-weight basket
rank_based + score + top_n + (daily|weekly|monthly)   → top-N rotation
signal_proportional + score + (daily|weekly|monthly)  → signal-weighted

Rejected: equal_weight with a calendar rebalance; rank_based/signal_proportional with rebalance='none' (a rotation must re-rank); and a rotating basket that also carries standing entry/exit cards (the allocation layer owns position lifecycle). These are enforced by the same totality rule the backtest engine applies, so the tool never saves a config the engine later rejects.

Returns the resulting allocation policy and a plain-language description. Read the full config back with builder_get_strategy.

Capabilities

Bounded options and operating modes surfaced above the full JSON schema.

Capital Model options

capital_model

partitionedshared_pool

Mode options

mode

equal_weightrank_basedsignal_proportional

Rebalance options

rebalance

nonedailyweeklymonthly

Required Inputs

FieldTypeDescription

modeenum: equal_weight, rank_based, signal_proportionalHow capital is WEIGHTED across the instruments of a BASKET strategy (len(instruments) >= 2) — distinct from within-leaf 'allocation' (sizing). 'equal_weight': every active instrument gets the same weight. This is STATIC and MUST use rebalance='none' — equal_weight + a calendar rebalance is REJECTED (periodic rebalancing of static weights is deferred P3.x). 'rank_based': hold the top_n instruments by 'score', equal-weighted — this is a rotation (e.g. 'rotate into the top 3 by momentum'). Optionally pair with 'exit_top_n' for entry/exit hysteresis (reduces rank-boundary whipsaw). 'signal_proportional': weight EVERY instrument in proportion to its 'score'. rank_based and signal_proportional rank/weight on a live signal and therefore REQUIRE a calendar rebalance (daily/weekly/monthly). Sets intent-level construction, NOT per-symbol weights.

strategy_idstringStrategy ID

Optional Inputs

FieldTypeDescription

capital_modelenum: partitioned, shared_poolHow the basket shares capital. 'partitioned': each instrument gets its own capital slice (the default — sleeves cannot borrow from one another). 'shared_pool': all instruments draw from one cash-bounded pool.

collection_riskanyOf (2 variants)Book-level reactive risk controls applied to the WHOLE basket (cash + total exposure), as a dict. All fields optional: 'max_daily_loss_pct' (0.1-50) halts ALL new entries across the book if the book's daily P&L drops below -X% (soft = resume next UTC day, hard = manual reset; 'halt_behavior', 'cooldown_bars' tune it); 'max_entries_per_day' / 'max_total_entries' cap NEW entries across the book per day / per run; 'min_cash_pct' (0<=x<1) holds a cash reserve so an entry can't push pool cash below that fraction of book equity. Example: {'max_daily_loss_pct': 5.0, 'max_entries_per_day': 3, 'min_cash_pct': 0.1}. Omit for no book-level risk controls. Distinct from the per-instrument 'risk_policy' breaker — this governs the whole book.

constraintsanyOf (2 variants)Construction concentration bounds applied when cross-instrument weights are computed, as a dict. Enforced fields: 'max_position_pct' (0<x<=1) caps any single instrument's weight; 'min_position_pct' (0<=x<1) is a per-instrument MINIMUM received weight — an instrument that would receive less is dropped (not held) and its weight redistributes to the rest ('no dust positions'); 'asset_class_caps' ({asset_class: max_weight}) caps aggregate weight per asset class — ALL THREE apply ONLY to a construction-managed rotation (rank_based / signal_proportional + a calendar rebalance); they are rejected on a static / equal_weight basket because they would silently no-op. 'max_active_sleeves' (>=1) caps how many instruments may hold a position at once (book-level max positions) and applies to ANY basket. Example for a top-N rotation: {'max_position_pct': 0.4, 'min_position_pct': 0.1}. Other fields (sector_caps, gross/net leverage) are not yet enforced and are rejected. Omit for no construction constraints.

exit_top_nanyOf (2 variants)Optional looser exit rank for entry/exit hysteresis on mode='rank_based' only. When set, an already-held instrument stays held until it drops out of the top exit_top_n (not just top_n); a NOT-yet-held instrument still only enters at top_n. Must be strictly greater than top_n. Omit for no hysteresis (today's behavior — a single top_n cutoff for both entry and exit). Example: top_n=2, exit_top_n=3 approximates 'enter top 40%, exit top 60%' on a 5-name basket.

rebalanceenum: none, daily, weekly, monthlyWhen construction weights are recomputed. 'none' (set once and hold; the ONLY valid value for equal_weight) vs 'daily'/'weekly'/'monthly' (REQUIRED for rank_based/signal_proportional to re-rank). See mode.

scoreanyOf (2 variants)The raw per-instrument signal to rank/weight on, as an inline IndicatorRef. Required for rank_based / signal_proportional; omit for equal_weight. Example (20-bar momentum): {'indicator_type': 'ROC', 'params': {'period': 20}}. Higher values rank/weight higher. This must be a RAW per-instrument metric (an indicator like ROC / SMA / RSI) — the constructor performs the cross-sectional ranking itself, so cross-sectional refs (RankRef / ZScoreRef / cross_sectional_percentile / sibling) are rejected.

top_nanyOf (2 variants)Number of top-ranked instruments to hold (equal-weighted). REQUIRED for mode='rank_based'; must be omitted for the other modes. Example: top_n=3 to rotate into the 3 strongest instruments.