Find tickers and market indicators in the catalog. Three usable shapes:

1. query='gold' — keyword search across ticker / name / description

2. category='fx' (no query) — list every FX feature in the catalog. Same for 'commodity', 'rates', 'volatility', 'economic', 'crypto', 'equity'

3. query='ETF', category='commodity', is_asset=True — narrow by both

PREFER browsing by category to keyword-spam: one category='fx' call beats ten query='euro currency' / query='FXY yen' / etc. searches when you want every instrument in a class. Browsing is also more reliable — catalog rows are tagged with category at ingest, so you don't depend on the keyword matching the description.

Catalog size: ~1300+ holdable assets (US large/mid-cap, international listings on LSE / XETR / TYO / HKEX / KOSPI / TWSE, ETFs, futures, FX, crypto). For 'build me a 500-asset / 1000-asset portfolio' requests, call search_features(is_asset=True, limit=1500) ONCE — limit ceiling is 2000, no pagination needed. Do NOT reach for screen_universe to enumerate the catalog: that endpoint is for ranking by price metrics and returns at most limit matches (default 50), not a full enumeration.

Add a ticker to the feature catalog AND populate its historical data in one call — the feature is ready to use in portfolios / conditioning sets / models as soon as this tool returns. IMPORTANT: First use search_features to check if the ticker already exists — calling add_feature for an existing ticker returns a 409 error. Specify source ('yahoo' for stocks/ETFs/futures, 'fred' for rates/economic indicators). Validates the ticker exists on the source API and auto-populates metadata (display_name, category, units, etc.) from the API response.

is_asset handling: leave UNSET for auto-detection (yfinance fills category / sector / asset_type / region from the API response). Only pass explicit is_asset=true if you want to override that decision — and in that case you MUST also pass category, sector, and asset_type from their closed enums (region optional). Listing the valid values:

• category: 'equity', 'fixed_income', 'credit', 'rates', 'fx', 'commodity', 'volatility', 'economic', 'crypto', 'inflation', 'employment', 'growth', 'corporate', 'thematic', 'sector', 'region'

• sector: 'Technology', 'Healthcare', 'Financials', 'Consumer Discretionary', 'Consumer Staples', 'Industrials', 'Energy', 'Materials', 'Communication Services', 'Utilities', 'Real Estate', 'Fixed Income', 'FX', 'Commodities', 'Cryptocurrency', 'Alternatives', 'Broad Market', 'International Equity', 'Factor'

• asset_type: 'Stock', 'ETF', 'Bond ETF', 'Crypto', 'Commodity', 'Currency ETF', 'Futures'

• region: 'US', 'Europe', 'Global', 'Asia', 'EM', 'Japan', 'China', 'Brazil', 'India', 'Korea', 'Taiwan', 'Vietnam', 'Latin America', 'Australia' Takes a few seconds while historical data is fetched.

Currency handling: non-USD tickers (e.g. .KS Korea, .L London, .DE Frankfurt, .T Tokyo, .HK Hong Kong, .SS Shanghai) are auto-translated to USD. The corresponding FX pair (e.g. KRWUSD=X for .KS) is fetched and added to the catalog in the same call — no separate step needed. Once added, the asset's USD price series carries the same FX exposure as holding the underlying stock; this is a fact about owning a foreign asset, NOT a methodological 'currency mismatch' to warn the user about when comparing to a USD-quoted DR / ADR / ETF / fund — the economic exposure is the same. Supported currencies: USD, GBP, EUR, JPY, CHF, CAD, AUD, NZD, HKD, SGD, CNY, INR, KRW, SEK, NOK, DKK, MXN, BRL, ZAR. Unsupported currencies return a clear 400 error.

Batch-add multiple tickers to the catalog in one call. Parallel ingest with a 10-wide semaphore — much faster than looping add_feature from the model side, and avoids the per-call tool-use overhead.

Returns a three-bucket breakdown: • added: tickers newly inserted (catalog + training_data populated) • already_existed: tickers that were already in the catalog (409s from the single-add path; not a failure) • failed: [{ticker, reason}] for symbols yfinance/FRED rejected

Use this when you want to register a research universe in the catalog without committing to a portfolio — e.g. 'add the S&P 500 constituents' or 'add these 200 tickers from my CSV'. For portfolio-bound bulk imports prefer create_portfolio with auto_add=true — same parallel ingest, but the result also creates the portfolio in one round-trip.

Per-ticker taxonomy fields (category, sector, asset_type, region) apply uniformly to every ticker in the batch. For heterogeneous batches leave them unset so each ticker gets its own auto-detected taxonomy from yfinance.

Typical wall-time: 100 tickers ≈ 10-30s, 1000 tickers ≈ 2-5 min.

Fetch/update historical training data for specific tickers from Yahoo Finance or FRED. For new features: full fetch from 2000. For existing: incremental update to today. Use this after add_feature, or to force-update stale data.

List the user's existing portfolios with names, IDs, asset compositions, and status.

Get detailed information about a specific portfolio including assets, weights, and associated feature sets. Use the portfolio ID from list_portfolios.

Create a new portfolio from tickers. Two payload shapes: • Explicit weights: pass tickers AND weights (parallel arrays, weights must sum to 1.0). • Equal weight: pass tickers only with equal_weight=True — server applies 1/N each.

Use equal_weight=True for ANY portfolio over ~50 assets. The parallel-array shape blows past LLM tool-call output budgets around 60-100 entries: one array gets truncated mid-generation and you'll see 'tickers and weights must have the same length' even though you generated them at the same size. A 500-ticker single-list call is ~10× smaller and reliable.

For CSV-paste / large-portfolio flows: combine equal_weight=True with auto_add=True to have the server auto-ingest unknown tickers via Yahoo Finance, and skip_missing=True to drop the ones yfinance rejects. The result includes import_summary with added_from_catalog / newly_ingested / dropped (with reasons) — report all three counts back to the user.

Size: up to ~1000 assets per portfolio (tier limit is 999,999 — effectively unbounded). If a user asks for a 500-asset or 1000-asset portfolio, build it. Do not refuse, do not lecture about 'focused portfolios', do not suggest ETF buckets unless the user explicitly asks for construction advice. Large portfolios are a supported, intentional product surface (F=1000 FLOW models train in minutes on GPU; analytics stay fast via precomputed bands + virtualized UIs).

Non-USD tickers are accepted — their prices are auto-translated to USD and the FX pair is fetched on-demand by add_feature. Resulting returns are USD-denominated and reflect the same FX exposure the underlying stock carries; do NOT warn the user about a 'currency mismatch' against a USD-quoted equivalent (DR/ADR/ETF/fund) — the exposure is economically the same.

Update an existing portfolio. Can change name, description, weights, capital, and/or options_positions. Only pass the fields you want to update — omitted fields stay unchanged. Weights must sum to 1.0 if provided.

ASSET MUTATION: passing a weights dict that includes a ticker not currently in the portfolio's target set is supported — update_portfolio AUTO-EXPANDS the target set as long as the new ticker is in the global feature catalog. If the ticker isn't in the catalog yet, call add_feature first, then retry this update. (You don't need to create a new portfolio to add an asset.) Removing assets is not supported via this path — drop a weight to 0.0 to zero a position; only create_portfolio_from_assets can produce a portfolio with a strictly smaller asset universe.

options_positions sets the options overlay for derivatives analysis (persisted on the portfolio).

Get the current live value of a portfolio: total value, P&L, and per-position breakdown.

One-call printable portfolio summary. Returns: • allocation — per-position ticker, name, current price, current value, current weight, target weight • returns — MTD, QTD, YTD, 1Y period returns • growth_of_10k — $10K invested 1Y ago, portfolio vs benchmark ending value • risk_stats — Sharpe, Sortino, vol, max drawdown, beta, alpha, risk-free rate (1Y window) • benchmark_return_1y, as_of, n_data_points

Use this when the user asks for 'a one-pager', 'portfolio summary', 'how is my portfolio doing'. Single call, ~1-2s, free. Default benchmark SPY; pass any ticker to override.

Get historical portfolio analytics: Sharpe ratio, volatility, expected return, max drawdown, and market beta (benchmarked vs SPY). Supports timeframes: 1W, 1M, 1Y, 2Y, 5Y. This is backward-looking — for forward-looking risk, use compute_returns or test_flow_risk. NEW: Pass model_group_id to also get factor return attribution — shows which factors (VIX, rates, oil, etc.) drove your portfolio returns over the period. Requires compute_betas to have been run first via analyze_quantitative.

Get asset classification for a portfolio: sector, industry, country, exchange, and asset type per holding.

Delete a portfolio by ID. Permanent, cannot be undone.

Find optimal portfolio weights using per-asset factor exposures from compute_betas or analyze_quantitative. Requires simulation_batch_id (from their output). Objectives: 'max_sharpe' (maximize risk-adjusted return), 'min_variance' (minimize portfolio volatility), 'max_return' (maximize expected return for given risk). Advanced objectives (pass the string directly): 'analytical_risk_parity' (equalize risk contributions), 'mean_cvar' (minimize CVaR, requires simulation_ids not beta_simulation_ids), 'expected_utility' (maximize CRRA utility), 'risk_parity' (CVaR-based equal risk), 'exposure_target' (match target factor exposures — set target_exposures on the API). Default: 'max_sharpe'. Long-only constraint applied by default.

Calculate the mean-variance efficient frontier for portfolio assets using historical returns. Returns a curve of optimal risk-return tradeoffs with long-only constraints (no shorting). Each point includes optimal weights, expected return, and volatility. This is a historical analysis — for forward-looking optimization, use optimize_portfolio with simulation data.

Retrieve past portfolio optimization results. Each entry includes the objective, optimal weights, expected return, volatility, VaR, and Sharpe ratio. Optionally filter by simulation_batch_id to see results for a specific beta computation.

Run qualitative (GRAIN) analysis: scans SEC filings and earnings calls to score company exposure to themes (0-100). Supports predefined themes ('AI exposure') or custom themes. Pass either portfolio_id or tickers directly.

Browse the GRAIN theme library. Returns predefined themes with names, descriptions, keywords, and categories.

List past qualitative (GRAIN) analyses. Optionally filter by portfolio_id.

Retrieve full results of a completed GRAIN analysis: theme scores, per-ticker breakdown, and evidence passages. Use list_grain_analyses first to find the analysis_id.

Delete a saved GRAIN qualitative analysis by ID. Permanent, cannot be undone.

List all model groups (each created by analyze_quantitative). A model group ties a portfolio to a conditioning set and contains per-asset models. Check model_type: null/absent = Moment (linear), 'flow_generative' = Flow. Use this to find model_group_ids for compute_betas, compute_returns, (resume).

Browse pre-built sets of market drivers (e.g. interest rates, volatility, commodities). Returns template names, factors, and conditioning_set_id needed by analyze_quantitative.

Create a custom conditioning set (or target set) from features in the catalog. Use this to build arbitrary factor sets for analyze_quantitative instead of using pre-built templates. Each feature needs at minimum a 'ticker' and 'source' ('YAHOO' or 'FRED'). The display_name is auto-resolved from available_features if omitted. Returns the conditioning_set_id that can be passed to analyze_quantitative.

List all accessible feature sets: your custom sets plus shared templates. Filter by set_type ('conditioning' or 'target'). Use this to find conditioning_set_id values for analyze_quantitative.

Get detailed information about a specific feature set including all features and their configuration.

Delete a custom feature set. Permanent, cannot be undone. Cannot delete shared templates.

Delete a model group and all its models, simulations, and associated data. Permanent, cannot be undone.

Get the cross-asset residual correlation matrix for a model group. Shows how much unexplained co-movement exists between assets after accounting for factor exposures. High residual correlations suggest missing common factors.

List past beta computation runs for a Moment model group. Each entry is a compute_betas invocation with its simulation_batch_id, date, and status. Use this to find older simulation_batch_ids for compute_returns. NOT for Flow models — use list_flow_scenarios for those.

Compute factor exposures (betas) for an already-trained model group. Use this when you already have a trained model_group_id (from analyze_quantitative or list_model_groups) and want to refresh betas with a different lookback window, or get a new simulation_batch_id. You do NOT need this if you just ran analyze_quantitative — it already includes this step. Returns per-asset factor exposures with R² (goodness-of-fit), rolling_window used, factor_last_date (effective beta date), data_truncated_by (stale factors), and simulation_batch_id (for compute_returns). Key use: call with different lookback_days (e.g. 63, 126, 252) to compare betas across time horizons — divergence signals regime changes. Check R² to gauge how well factors explain each asset.

Run a what-if stress test on a Moment (linear) factor model — the PRIMARY tool for scenario analysis. Requires simulation_batch_id from analyze_quantitative or compute_betas. Express stresses as FRACTIONAL CHANGES of each factor's current value (shocks dict). The server translates to absolute levels using each factor's latest observed value — you don't need to look it up or do the arithmetic. Examples: • 'TLT down 8.5%' → {'TLT': -0.085}. • '50bps rate cut on DGS10 (currently 5%)' → {'DGS10': -0.10} (−50bps / 500bps of the current rate = −10%). • 'VIX doubles (to ~40 from 20)' → {'VIX': 1.00}. • 'SPY drops 20%' → {'SPY': -0.20}. Omitted factors default to no shock. Include factor_last_values_raw from the betas output in your narration so the user sees the current level next to the stressed level. Also check data_freshness_warning in betas output — if present, betas may be stale. For Flow (generative) models, use simulate_flow_scenario instead.

Save a named Moment scenario template for later reuse. This does NOT run a simulation — use compute_returns with the factor values instead, or for ad-hoc tests. IMPORTANT: requires model_id — this is an individual per-asset model UUID from list_model_groups → models[].model_id, NOT the model_group_id. Each scenario is tied to one asset's model. Factor spec format: {'VIX': {'type': 'fixed', 'value': 35}}. Supported types: 'fixed' (exact value), 'percentile' (historical percentile), 'shock' (std dev shift).

List saved Moment scenario templates (created via create_scenario). These are stored factor specs tied to individual model_ids — to execute one, use compute_returns with the factor values. For ad-hoc tests, use compute_returns directly. NOT for Flow scenarios — use list_flow_scenarios for those.

Get detailed information about a saved scenario including its factor specs.

Update a saved scenario. Can change name, description, or factor specs. Only pass the fields you want to update.

Delete a saved scenario. Permanent, cannot be undone.

Build and train linear factor models for a portfolio in one step (creates models → trains → computes betas). This is the starting point for Moment (linear) analysis. Requires conditioning_set_id (the market drivers — get one from list_feature_set_templates or create_feature_set). Uses a two-layer architecture: thematic factors (conditioning_set_id) + optional baseline factors (baseline_mode='us' absorbs market/value/growth variance via real-time ETF proxies before thematic factors). Pass either portfolio_id or tickers directly (auto-creates portfolio with equal weights). Returns: factor exposures (betas), per-asset R² (in-sample goodness-of-fit — tells you how linear the relationship actually is for the given window), rolling_window used, factor_last_date (effective beta date — may be truncated if a factor has stale data), and data_truncated_by (which factors caused truncation).

Important: there is NO regime-conditional or 'calm vs stress' beta API. If a user asks for regime decomposition, do NOT invent it — the right substitute is to RE-RUN this tool with a shorter rolling_window (e.g. 90 days vs the 252-day default) and compare the betas to the long-window fit. Where (a) a beta shifted meaningfully AND (b) R² stayed reasonable in the short window, that's a real shift to talk about. Where R² collapsed in the short window, the apparent shift is noise from thin degrees of freedom — say so explicitly to the user. Do NOT pick rolling_window < 90 unless you have very few factors: each per-asset regression has (n_factors + n_baseline_etfs) RHS variables, and you need at least ~10 obs per parameter for stable betas (so rolling_window=90 supports up to ~9 RHS variables, rolling_window=60 supports ~6).

Low R² (e.g. < 0.2) suggests nonlinear dynamics or missing factors — flag the asset, don't claim a precise beta decomposition. R² in this Moment model is per-asset (each asset gets its own regression on the conditioning set), so a low R² for one name doesn't impeach the others. Next step: call compute_returns with the simulation_batch_id to run what-if stress tests.

Train a generative Flow model on a portfolio and conditioning set. Returns immediately — training runs on a GPU and takes 5-15 minutes. After calling this, STOP and tell the user training has started. Let them keep chatting. The user will ask you to check progress — use check_flow_job(job_id=...) when they do. Do NOT automatically poll or call check_flow_job yourself. Requires conditioning_set_id (from list_feature_set_templates or create_feature_set) and tickers or portfolio_id.

Check the status of an async Flow job (training, generation, or validation). Returns status ('running', 'completed', 'failed') and progress details. Does NOT return results — when completed, call get_flow_results(job_id) to fetch data. Call this ONCE, report status to the user, then STOP — do not poll in a loop. Typical times: training 5-15 min, generation 1-3 min, validation 3-5 min.

Generate simulated multi-step price trajectories from a trained Flow model. Returns per-asset percentile bands (p5/p25/p50/p75/p95 per timestep), sample paths per target asset, and scalar terminal statistics. Requires model_group_id from train_flow_model or list_model_groups. If paths already exist, returns cached results instantly. Path generation takes ~1-3 min on GPU. Defaults: horizon=60 (~1 quarter), n_paths=1000.

Pre-flight feasibility check for a constrained FLOW scenario. ALWAYS call this BEFORE simulate_flow_scenario when you have ≥2 constraints, or whenever you're unsure if a scenario is in the model's natural distribution.

Probes the trained model with up to n_baseline unconstrained paths and reports what fraction satisfy your constraints, plus a recommended generation method: • probability ≥5% → 'rejection' (fast, exact samples) • probability 1-5% → 'hybrid' (rejection + latent fallback) • probability <1% → 'latent' (paths satisfy by construction; mild dynamics distortion) • probability <0.1% → infeasibility floor — refuse or relax constraints

Cheap (~1-15s) compared to a full scenario (minutes + GPU credits). Reuses today's baseline if generate_flow_paths has already been called; if not, auto_generate_baseline=True (default) creates one in the same call.

Workflow when probability is low: report it back to the user, then iterate — try each constraint individually to identify the binding one, relax magnitudes, widen t_start/t_end windows, or drop the least-essential constraint. Only commit to simulate_flow_scenario once probability is in a usable band, OR the user has explicitly accepted latent-mode distortion.

feature_name in constraints must be the DISPLAY NAME from the trained model's feature_names (e.g. 'Apple Inc.', 'SPDR S&P 500 ETF Trust'), NOT ticker symbols.

Start constrained what-if scenario generation from a trained Flow model. Returns immediately with a job_id — use check_flow_job(job_id, job_type='generate') to poll for results. PREREQ: Always run generate_flow_paths FIRST on the same day to establish a baseline.

REQUIRED for any scenario with ≥2 constraints: call check_scenario_probability FIRST and verify probability ≥0.1% before invoking this tool. Two constraints multiply joint probability (e.g. oil ≥155 alone ~2%, VIX ≥40 alone ~3% → joint ~0.06%, below the resolution floor). Skipping the pre-check wastes GPU credits on infeasible scenarios and surfaces 0% results that are confusing to the user. The pre-check is ~1-15s; the full scenario is minutes.

After this tool runs, scenario_probability comes back in get_flow_results — interpret it as: ≥5% within normal range | 1-5% rare | <1% outside training distribution | 0% below measurable (not necessarily impossible — could be rare-event paths from latent mode). When latent mode produced the paths, surface that to the user verbatim — those paths satisfy constraints by construction but represent rare-event distortions, not unconditional samples.

THREE WAYS TO GET 0% PROBABILITY — avoid all: (1) DURATION: mean-reverting features (VIX, spreads, rates) spike for days to weeks, not months. Always use t_start/t_end to window constraints (e.g. t_start=10, t_end=20), not the full horizon. (2) JUMP TOO ABRUPT: if today's value is far from the threshold, t_start must give enough time to get there. (3) MULTIPLE CONSTRAINTS: joint probability multiplies. With 2+ constraints, ALWAYS check_scenario_probability first.

Check last_price from generate_flow_paths first — if VIX is at 15 and you constrain it above 30 from day 5, that's a 2x move in 5 days (essentially never happens). Set t_start large enough for a realistic transition: the bigger the gap between current value and threshold, the later t_start should be. VIX all-time high ~89, never sustained above 30 for more than a few weeks.

feature_name in constraints must be the DISPLAY NAME from feature_names (e.g. 'Apple Inc.', 'SPDR S&P 500 ETF Trust'), NOT ticker symbols. Constraint types: 'level' (absolute price bounds), 'return' (per-step return bounds). Pass portfolio_id through so test_flow_risk can be called directly on results. Run scenarios SEQUENTIALLY (one at a time), not in parallel, to avoid GPU queue contention.

Run portfolio risk analytics on Flow-generated paths (FUTURES/EQUITIES ONLY — no options). Computes expected return, volatility, Sharpe ratio, Sortino ratio, Calmar ratio, VaR 95%, CVaR 95%, max drawdown, profitability rate, and return distribution percentiles. Requires portfolio_id and flow_job_id from generate_flow_paths, or simulate_flow_scenario. If the user has OPTIONS positions, use analyze_derivatives instead — it reprices options on every path using Black-76 and shows combined futures+options risk. TIP: Call this on multiple flow_job_ids (baseline + different scenarios) to build a side-by-side comparison of risk metrics across scenarios.

List completed constrained scenarios for a Flow model group. Returns job IDs, constraints used, satisfaction rates, and timestamps. Use this to find previous scenario results without re-running them — pass any flow_job_id to test_flow_risk for risk metrics.

List completed baseline (unconstrained) generation jobs for a Flow model group. Returns job IDs, path counts, horizons, and creation dates. Baselines are standalone unconstrained simulations used for comparison with scenarios. Use generate_flow_paths to create new baselines.

Download all generated paths from a Flow generation job as CSV. Returns raw path data with columns: path_idx, day, then one column per feature. Works for both baseline and scenario generation jobs. Use the flow_job_id from generate_flow_paths, simulate_flow_scenario, or list_flow_baselines/list_flow_scenarios.

Delete a flow simulation job (baseline or constrained scenario). Permanent, cannot be undone.

Add a systematic trading rule to a portfolio. Rules are evaluated day-by-day on FLOW forward paths during forward_test_rules — not backtested on history.

TWO RULE TYPES: • Signal rules (action.type='signal_weight') — continuous indicator → proportional position. For CTAs and trend-followers. • Binary rules (all other action types) — trigger fires → discrete weight change. For risk overlays, hard stops, regime gates.

Use signal rules (priority 0) for the core strategy; binary rules (priority 1+) for risk overrides.

── SIGNAL RULE ── trigger: {indicator, asset, params} ← no operator/threshold action: {type:'signal_weight', asset, normalizer, max_weight, min_weight} normalizer = typical signal magnitude; clip(signal/normalizer, -1, 1) → position weight = scaledmax_weight if scaled≥0 else scaled|min_weight|

trigger={indicator:'macd_line', asset:'CL=F', params:{fast:12, slow:60}} action={type:'signal_weight', asset:'CL=F', normalizer:2.0, max_weight:0.6, min_weight:-0.3}

trigger={indicator:'z_score', asset:'ZN=F', params:{window:60}} action={type:'signal_weight', asset:'ZN=F', normalizer:2.0, max_weight:0.5, min_weight:-0.5}

── BINARY RULE ── trigger: {indicator, asset, params, operator, threshold} OR {combinator:'all'|'any', conditions:[...]} indicators: raw | moving_average | ema | rsi | bollinger_upper | bollinger_lower | bollinger_width | macd_line | macd_signal | rolling_std | rolling_volatility | rate_of_change | z_score asset: portfolio assets OR conditioning factors ('^VIX', 'DX-Y.NYB', 'T10Y2Y', 'ZN=F', ...) operator: '>' | '<' | '>=' | '<=' | '==' | 'crosses_above' | 'crosses_below' action: exit | set_weight (exact value, negative=short) | scale_weight (multiplier) | reverse

trigger={indicator:'rsi', asset:'CL=F', params:{period:14}, operator:'>', threshold:70} action={type:'exit', asset:'CL=F'}

trigger={combinator:'all', conditions:[ {indicator:'raw', asset:'^VIX', params:{}, operator:'>', threshold:30}, {indicator:'rsi', asset:'CL=F', params:{period:14}, operator:'>', threshold:65}]} action={type:'scale_weight', asset:'CL=F', value:0.5}

IMPORTANT: Trigger assets can be portfolio assets OR conditioning factors (VIX, DXY, etc.). For forward_test_rules, the FLOW model must include ALL referenced features — missing features cause rules to silently fail. For evaluate_rules (live data), any feature in training_data works with no model dependency.

List all systematic trading rules attached to a portfolio, including their trigger/action definitions, active status, and priority order.

Activate or deactivate a systematic trading rule. Only active rules are included in forward_test_rules by default.

Permanently delete a systematic trading rule from a portfolio.

Edit an existing systematic trading rule. Only fields you pass are updated; omit a field to leave it untouched. Use to retune a trigger threshold, change the action, rename, reprioritize, or flip activation. For just toggling active/inactive, prefer toggle_rule (clearer intent). live_mode controls broker deployment: null = paper-only, 'observe' = log live signals without trading, 'auto' = execute via connected broker. Live deployment requires a connected broker (see platform UI).

Preflight validation of stored rules: schema-checks each rule's trigger and action grammar, verifies referenced assets exist in the portfolio, and (if flow_job_id given) confirms every feature the rules reference is covered by the FLOW model's feature set. Run this before backtest_rules / forward_test_rules to surface bad rules cheaply (~200ms, free) instead of letting them silently fail mid-backtest. Returns ok=true with empty error lists if all clean; otherwise lists missing_portfolio_assets, missing_rule_features, and per-rule grammar errors so the agent can patch and retry.

Forward-test systematic trading rules against FLOW-generated price paths. Returns TWO levels of output: • combined_strategy — ALL rules applied together in priority order on every path. This is your actual strategy performance vs the base static portfolio. • rule_attribution — each rule tested individually to show which rules help vs hurt.

How it works:

1. Loads the FLOW price paths (same N paths for every evaluation — fair comparison)

2. Steps through each path day-by-day, applies rules in priority order, tracks P&L

3. Returns Sharpe, CVaR, max drawdown, return for combined strategy and each rule alone

IMPORTANT: The FLOW model must include paths for ALL features referenced in rule triggers (both portfolio assets AND conditioning factors like VIX, DXY, etc.). Rules referencing features not in the FLOW model will silently fail — check warnings in the response. For checking rules against today's real market data (no FLOW dependency), use evaluate_rules instead.

Prerequisites: (1) create rules with create_rule; (2) activate them with toggle_rule(is_active=True); (3) generate FLOW paths with generate_flow_paths. If rule_ids is omitted, tests all active rules.

Check which portfolio trading rules trigger on TODAY's real market data. Unlike forward_test_rules (which tests against simulated FLOW paths), this evaluates rules against actual historical prices from training_data — no FLOW model needed.

Returns per-rule: triggered (bool), action prescribed, current indicator values. Also returns recommended_weights (combined effect of all triggered rules) and weight_changes.

Data source: training_data (refreshed daily at 21:00 UTC after US market close). On weekends/holidays, evaluates against the most recent trading day.

Use this for daily 'any rules fired?' monitoring. For simulated forward-testing across 1000+ scenarios, use forward_test_rules instead.

Get results of a completed Flow job (generation or validation). For generation jobs (default): returns per-asset terminal statistics, percentile bands (P5–P95 timeseries), sample paths, and price_history for indicator warmup. Set summary_only=true to keep stats + bands but drop sample paths (~60%% smaller). Use download_flow_paths to get full raw path data as CSV. For scenario jobs: also returns satisfaction_rate and constraint details. For validation jobs (job_type='validate'): returns quality badge, pass_rate, and per-feature metrics (Wasserstein distance, KS tests, coverage, marginal checks). Use check_flow_job first to verify the job is completed.

Validate a trained Flow model against real data. Generates paths and compares them to historical distributions using Wasserstein distance, KS tests, coverage tests, and marginal distribution checks. Returns immediately with a job_id — validation runs asynchronously (~3-5 min). Use check_flow_job(job_id=..., job_type='validate') to monitor progress. Requires a trained Flow model (run train_flow_model first).

Run options risk analysis on FLOW-generated paths for a mixed futures + options portfolio. Reprices each option at every timestep of every path using Black-76, then computes portfolio-level risk metrics (VaR, CVaR, Sharpe, Sortino, max drawdown) and per-position Greeks (delta, gamma, vega, theta, rho). Returns separate risk breakdowns for: combined portfolio, futures-only, and options-only components, plus P&L timeseries percentile bands. Requires a flow_job_id from generate_flow_paths or simulate_flow_scenario. For scenario analysis: run simulate_flow_scenario first (e.g., 'VIX > 30 and crude drops 20%'), then call this tool to see how your options hedge performs under that scenario.

Price a single option on a futures contract using the Black-76 model. Returns the option price, per-contract value (price × contract multiplier), and analytical Greeks (delta, gamma, vega, theta, rho). Supports all major futures: ES=F, NQ=F, CL=F, GC=F, SI=F, ZB=F, ZN=F, ZC=F, ZW=F, ZS=F, etc. If a flow_job_id is provided, also computes an Esscher fair-value estimate from FLOW paths (captures fat tails and vol clustering that Black-76 misses). Use this for quick pricing checks; use analyze_derivatives for full portfolio risk.

Run a historical backtest of trading rules on REAL market data — not simulated FLOW paths. Tests how rules would have performed over a historical period. Returns same structure as forward_test_rules (base vs combined vs per-rule attribution) PLUS monthly returns table, drawdown series, turnover stats, and transaction cost analysis. Prerequisites: create rules with create_rule (and activate them). Transaction costs: configurable (default 10bps per trade). Warmup period (default 252 days) pre-fills indicator state before the test period starts. For forward-looking testing on synthetic FLOW paths, use forward_test_rules instead.

Screen the asset universe by metadata (sector, region, asset type) and price-based metrics (momentum, volatility, percentile rank, z-score, RSI, MA distance). Only screens assets already in the Sablier catalog with training data. Use search_features + add_feature first to expand the catalog if needed. Metadata fields: sector, region, asset_type, category, source. Price fields: momentum_20d/60d/252d, volatility_20d/60d, percentile_1y, z_score_60d, ma_distance_50d/200d, rsi_14, current_price, change_1d_pct/1w_pct/1m_pct. Operators: eq, neq, in (metadata); gt, gte, lt, lte, between (price). Results include computed metrics per asset. Use top results to create a portfolio.

Get a Bloomberg-terminal-grade market briefing with 50+ indicators and computed regime signals. Returns current levels, 1-day/1-week/1-month changes, z-scores, and percentiles for equities, rates, credit, FX, commodities, volatility, international markets, and crypto. Also computes cross-asset signals: Risk-On/Risk-Off score, yield curve regime, credit stress, volatility regime, sector rotation, copper/gold ratio, stock-bond correlation, and inflation momentum. Flags significant moves (|z-score| > 2) as content opportunities. Use this to understand the current market environment and decide what Sablier analyses to run.

Live price snapshot for one or more tickers (Alpha Vantage). Pass up to 100 tickers in one call. Returns current price, change, change_pct per symbol; unresolved tickers (typos, delistings) come back as error stubs without failing the batch. Use for 'what's X trading at right now?' or to seed a quick position-level P&L calc.

OHLC bars for a single ticker. range='1W'/'1M'/'3M'/'6M'/'1Y'/'2Y'/'5Y'/'ALL' for canned windows, OR pass start_date/end_date (YYYY-MM-DD) for a custom slice.

frequency='daily' (default) | 'weekly' | 'monthly' | 'quarterly' | 'annual' (alias: 'year_end'). For multi-year analysis, USE A COARSER FREQUENCY rather than 50 point queries. A 20-year range='ALL', frequency='annual' request returns ~20 rows; the equivalent in daily granularity is ~5,000 rows that exceed the agent-side response clamp and force you into the dozens-of-calls year-end-extraction pattern that costs credits and time. The downsampler keeps the LAST trading day of each period (week-end / month-end / etc.), which is what return / drawdown / vol calcs actually want.

Use for ad-hoc time-series analysis the trained models don't already cover (return distributions, drawdown curves, custom regression windows, event studies around specific dates).

News feed with per-ticker sentiment scores (Alpha Vantage NEWS_SENTIMENT). Filter by tickers (per-name news + sentiment) or topics (e.g. 'earnings', 'mergers_and_acquisitions', 'financial_markets', 'economy_macro'). Returns headlines, source, summary, sentiment label/score, and per-ticker sentiment within multi-ticker articles. Strong for 'any news on X?', 'what's driving X today?', or a portfolio-wide news roll-up (pass the portfolio's tickers). Pair with market_radar for the full 'what's happening' briefing.

Company fundamentals for a single US equity: P/E, PEG, P/B, P/S, EV/EBITDA, EV/Revenue, EPS, revenue TTM, EBITDA, profit margin, operating margin, ROE, ROA, dividend yield, beta, 52-week high/low, 50/200-day moving averages, market cap, shares outstanding, analyst target price, analyst ratings, quarterly earnings/revenue growth YoY. Source: Alpha Vantage OVERVIEW (verified data provider, 24h cache — fundamentals change at most quarterly so caching is safe). Only US equities with SEC filings; ETFs / futures / crypto return 404.

Current US Treasury yield curve (2y / 5y / 10y / 30y) plus 2s10s spread. Use for rates context, curve-shape regime, or to feed a duration scenario.

VIX level + term structure (VIX vs VIX3M vs VIX6M) + implied vol regime. Backwardation = stress (front > back), contango = calm. Use for vol-regime context before running stress scenarios or sizing options overlays.

Upcoming earnings reports sorted chronologically. Filter by single symbol, by date window (start_date/end_date YYYY-MM-DD), or by horizon ('3month'/'6month'/'12month'). Returns symbol, company name, report date, report time (BMO/AMC), estimate EPS, actual EPS where reported. Use to flag earnings-event risk in a portfolio over the next N days.

Top gainers, top losers, and most-active stocks for the day. Use for 'what moved today' context — pair with get_news to explain why.

Major US equity indices snapshot (S&P 500, Nasdaq 100, Dow, Russell 2000) sourced from ETF proxies. Returns symbol, name, price, change, change_pct. Quick orient before deeper analysis.

S&P 500 sector ETF performance over a window: 1D / 1W / 1M / YTD. Returns one row per sector with performance_pct + change_pct. Use for sector-rotation reads ('which sectors are leading this week?').

Pairwise correlation matrix + annualized volatility from daily returns over a window. Pass 2-20 tickers and a timeframe ('1W'/'1M'/'3M'/'6M'/'1Y'/'2Y'/'5Y'/'ALL', default '1Y'). Returns the matrix, per-asset annualized vol, and the top-correlated pairs. Lighter than analyze_quantitative when you just want raw pairwise structure without a factor model.

Quick account summary: name, email, tier, credit balance, and billing period. Use this first to orient yourself — single call covers identity and credit status.

Credit balance details: used, remaining, purchased packs, and overage status. Use whoami for a quick summary; use this when you need the full credit object.

Subscription plan details: tier limits, overage rates, and per-operation costs. Use this to understand pricing before running expensive operations (not for credit balance — use whoami or get_credits).

Get detailed usage breakdown for the current or a specific billing month. Shows per-operation counts, included limits, overage counts, and costs. Month format: YYYY-MM (e.g. '2026-03').

Subscribe to a Sablier plan (new subscription). Returns a Stripe Checkout URL to complete payment. Tiers: 'pro' (Pro Monthly €499/mo or Pro Annual €349/mo — 1,000 credits/month, overage at €0.50/credit monthly or €0.35/credit annual). Enterprise pricing is custom — contact team@sablier.it. To manage an existing subscription (upgrade, downgrade, cancel, update payment), use manage_subscription instead.

Open the Stripe Customer Portal to manage an EXISTING subscription: upgrade, downgrade, cancel, or update payment method. Returns a portal URL. For new subscriptions, use subscribe instead.

List available credit packs for one-time purchase. Returns pack options with credits, price, and per-credit cost. Credit packs are available to all tiers and never expire. To purchase, use buy_credit_pack with the pack_id.

Purchase a one-time credit pack. Returns a Stripe Checkout URL to complete payment. Available packs: 'pack_100' (100 credits, €69), 'pack_500' (500 credits, €299), 'pack_1000' (1000 credits, €549). Credits are added instantly after payment and never expire. Use list_credit_packs to see current pricing. Use get_credits to check your balance first.

Enable or disable on-demand overage credits for Pro subscribers. When enabled, operations continue beyond the monthly credit allocation and are billed at the overage rate (€0.50/credit monthly, €0.35/credit annual). When disabled, operations are blocked once monthly credits run out. Only available for Pro tier — free users should buy credit packs or subscribe.