Tool reference

Search the Arc Research knowledge graph for concepts and their relationships. Use for questions about market drivers, company exposure, and published research themes.

Parameters

• query string required Plain-language search query
• hops integer optional Neighborhood expansion depth (1-2)

Look up one concept in the Arc Research knowledge graph by slug or name and return its neighborhood of relationships and supporting sources.

Parameters

• concept string required Concept slug or name
• hops integer optional Neighborhood expansion depth (1-2)

Trace how two concepts in the Arc Research knowledge graph are connected, including relationship rationales from source research.

Parameters

• from string required Starting concept slug or name
• to string required Destination concept slug or name

Resolve a commodity by slug, name, or futures product code and return hub and stream paths on Arc Research.

Parameters

• query string required Commodity slug, name, or product code

Resolve a ticker or futures root symbol to its Arc Research page and any related commodity hub.

Parameters

• symbol string required Ticker or futures root symbol

Latest outright futures quote. A product root or slug (NG, natural-gas) returns the front month. A contract symbol (NGZ5) returns that outright. While a session is trading, source is massive_snapshot (10-minute delayed; close is the latest session price, as_of its exchange time); otherwise source is futures_quotes, the last daily bar. is_stale is true when the contract is expired or the bar is older than three trading days.

Parameters

• symbol string required Futures contract symbol

Latest equity quote (OHLC) for a ticker such as EQT. A futures root may collide with an equity (NG is NovaGold, not Henry Hub); the payload includes symbol_warning and company_name. is_stale is set when the bar is older than three trading days.

Parameters

• symbol string required Equity ticker symbol

Recent daily OHLC bars for an equity ticker. Server-computed — do not invent bars.

Parameters

• symbol string required Equity ticker symbol
• limit integer optional Number of bars (default 30, max 120)

Server-computed SMA, EMA, or RSI for an equity ticker. kind is required: sma, ema, or rsi. Never invent indicator values.

Parameters

• symbol string required Equity ticker symbol
• kind string required sma, ema, or rsi
• period integer optional Lookback period

List commodities the authenticated user has pinned on Arc Research.

No parameters.

List commodity-adjacent equities (producers, miners, fertilizer, utilities) for a commodity, with latest screen scores when available.

Parameters

• commodity string required Commodity slug, name, or product code
• limit integer optional Max members (default 25, max 100)
• role string optional Optional role: producer, midstream, utility, sic_match
• include_non_common boolean optional Include preferreds, notes, and units. Default false.

Screen commodity-adjacent equities. preset: value | breakout | flow | hybrid. Returns a short ranked table with scores and one-line reasons.

Parameters

• commodity string required Commodity slug, name, or product code
• preset string optional value | breakout | flow | hybrid
• min_dollar_volume number optional Minimum dollar volume
• max_results integer optional Max hits (default 15, max 50)
• include_non_common boolean optional Include preferreds, notes, and units. Default false.

Equity institutional-flow proxy from daily price/volume (not 13F/dark pool). Optionally attaches linked commodity COT positioning.

Parameters

• symbol string required Equity ticker symbol
• lookback_days integer optional Lookback days (default 60)
• commodity string optional Optional commodity slug for COT context

Single-name equity dossier: quote, screen features, flow proxy, fundamentals, graph neighborhood, and explicit data gaps.

Parameters

• symbol string required Equity ticker symbol
• commodity string optional Optional commodity slug for feature context

Latest Finnhub basic financials snapshot (P/E, P/B, margins, debt) plus optional peer-relative comparison within a commodity universe.

Parameters

• symbol string required Equity ticker symbol
• commodity string optional Optional commodity for peer medians

Get the latest CFTC Commitments of Traders (COT) positioning snapshot for a commodity: open interest, trader-category levels, week-over-week changes, and a managed-money sentiment score. Use for marketing/spec positioning questions.

Parameters

• commodity string required Commodity slug, name, or product code (e.g. natural-gas, NG)

Return recent week-over-week CFTC/COT position changes for a commodity (managed money, producers, swap dealers, open interest). Useful for tracking marketing and speculative flow.

Parameters

• commodity string required Commodity slug, name, or product code
• weeks integer optional Number of weeks (1-26, default 8)

Compute the managed-money COT oscillator (0-100) for a commodity over a lookback window. High values mean managed money is near lookback net-long extremes; low values mean near net-short extremes.

Parameters

• commodity string required Commodity slug, name, or product code
• lookback integer optional Lookback weeks (4-104, default 52)

Return latest plus prior weeks of CFTC/COT rows for a commodity (levels and changes). Use when you need a longer positioning history beyond a single week.

Parameters

• commodity string required Commodity slug, name, or product code
• weeks integer optional Prior weeks to include (1-52, default 12)

Fetch the published Arc Research COT / marketing-positioning narrative for a commodity stream. Optionally pass a YYYY-MM-DD reporting date; otherwise returns the latest published brief.

Parameters

• commodity string required Commodity slug, name, or product code
• date string optional Optional reporting date YYYY-MM-DD

Get the NYMEX WTI (CL) or Brent (BZ) settlement forward curve: each listed month's price, calendar spreads M1-M2, M1-M12 and M1-M36 in $/bbl (positive = backwardation), the contango/backwardation label, and where M1-M12 sits in its 5-year history. Optional as_of (YYYY-MM-DD) returns the curve known then. Daily settlements only, not live prices.

Parameters

• benchmark string optional wti (default) or brent
• as_of string optional YYYY-MM-DD (default: latest)
• months integer optional How many contract months to return (default 24, max 120)

Get refining crack spreads in $/bbl: RBOB-WTI, HO-WTI, RBOB-Brent, HO-Brent, the 3-2-1 crack, Gulf jet-Brent and Gulf jet-ULSD. Uses NYMEX front-month settlements when every leg has one, else EIA spot. Pass crack to also get that crack's weekly 5-year seasonal range (min/avg/max by ISO week, EIA spot) and this year's daily values.

Parameters

• crack string optional Optional crack key for the seasonal band

Get the latest EIA Weekly Petroleum Status Report: US commercial crude (ex-SPR), Cushing, SPR, gasoline, distillate and jet stocks; refinery utilization and crude inputs; product supplied; crude imports, exports and field production. Each series has its week-over-week change, the 5-year average change for the same week (there is no free consensus), the 5-year same-week range, and days of supply. Optional as_of (YYYY-MM-DD) returns only what had been released by the end of that day. Stocks are in thousand barrels.

Parameters

• as_of string optional YYYY-MM-DD (default: now)
• history_weeks integer optional Also return this many weeks of one series' history (max 520)
• series string optional Series key for history_weeks (default crude_ex_spr)

Get proven oil reserves (barrels), production (barrels/day), reserves-to-production years and share of world reserves by country, from one publisher's latest edition (energy_institute, opec_asb or eia_international). Sources are never blended. Pass country (ISO3, e.g. VEN) for that country's history.

Parameters

• source string optional Publisher (default: first imported)
• country string optional ISO 3166 alpha-3 code for one country's history
• limit integer optional Countries to return, largest reserves first (default 20)

Get the latest EIA Weekly Natural Gas Storage Report snapshot for Lower 48 working gas: storage level (Bcf), net change, and 5-year average context. Defaults to the natural-gas commodity hub.

Parameters

• commodity string optional Commodity slug (default natural-gas). Must have EIA storage linkage.

Fetch the published Arc Research EIA Weekly Natural Gas Storage narrative. Optionally pass a YYYY-MM-DD reporting date; otherwise returns the latest brief.

Parameters

• commodity string optional Commodity slug (default natural-gas)
• date string optional Optional reporting date YYYY-MM-DD

Get the latest NOAA Climate Prediction Center population-weighted HDD/CDD degree-day snapshot (national + regions vs normal). Key input for U.S. natural gas weather demand research.

Parameters

• weeks integer optional Number of recent weeks (1-12, default 1)

Get the latest GFS/ECMWF multi-hub U.S. demand-weighted HDD/CDD forecast: weighted cumulative degree days, model convergence, and run-over-run deltas. GFS and ECMWF are often different model runs: gfs_init_utc and ecmwf_init_utc give each one's init. Use for forward-looking natural gas weather/demand research.

Parameters

• include_locations boolean optional Include per-hub location detail (default false; can be large)

Return point-in-time natural gas weather ML features (Helios): demand-weighted HDD/CDD from GFS and ECMWF, model spreads, convergence, and run deltas as of a decision date. Defaults to today. Also returns signal_features: teleconnection index values (Niño 3.4 anomaly, observed and forecast GBI z and PNA, 10 hPa zonal-wind minimum) and basin freeze hours per model, each with its released_at, as of the same decision time. Not a forecast.

Parameters

• as_of string optional Decision date YYYY-MM-DD (default today)

Fetch the latest published Arc Research weather & demand narrative for natural gas (NOAA degree days and/or GFS/ECMWF hub forecast briefs). Optionally pass a YYYY-MM-DD reporting date.

Parameters

• commodity string optional Commodity slug (default natural-gas)
• date string optional Optional reporting date YYYY-MM-DD

Return the NG weather signal engine's newest snapshot at or before as_of: six scores (ENSO, polar vortex, Greenland block, PNA, Permian and Appalachia freeze-off) with their inputs, models and runs; the raw weather bias; the widowmaker (H/J spread) state; the conviction-matrix quadrant with backtest scorecards; and action_copy_allowed (false unless the state's backtest cleared the bar). Point in time: only rows knowable at as_of. Not a forecast and not a trade call.

Parameters

• as_of string optional YYYY-MM-DD (end of that day, UTC) or ISO 8601 time. Default now.

Return one teleconnection index used by the NG weather signals: gbi (Greenland Blocking Index), pna (Pacific–North American pattern), nino34 (Niño 3.4 anomaly) or pv (10 hPa 60°N zonal wind). Gives the observed series between from and to (default the last 60 days, 26 weeks for nino34), the 1991–2020 climatology band, each model's newest forecast run (GFS, ECMWF, ECMWF ensemble mean and spread; the marine trajectory for nino34), the score thresholds and lead-5 skill. Point in time: values released by as_of only. Not a forecast.

Parameters

• index_key string required
• from string optional YYYY-MM-DD start of the observed series
• to string optional YYYY-MM-DD end of the observed series (never past as_of)
• as_of string optional YYYY-MM-DD or ISO 8601 time. Default now.

Return freeze-off risk for the Permian and Appalachian basins (or one, with basin_key): each model's newest run (GFS and ECMWF longest forecast freeze run and hours at or below 32 °F in days 1–7 and 8–14, the freeze start and end, minimum temperature, the 14-day hourly strip), whether both models are past the basin's PRD threshold (consensus_met; 24 h Permian, 72 h Appalachia), the engine's score, and the station's realized minima for the last 7 days. Point in time: runs available by as_of only. Not a forecast.

Parameters

• basin_key string optional
• as_of string optional YYYY-MM-DD or ISO 8601 time. Default now.

Return one backtest by id from list_ng_signal_backtests ("signal-<id>" or "experiment-<id>"): status, the summary per horizon (events, hit rate, average move, p-value, date range, clears_bar), folds, CPCV paths and PBO, the engine's quadrant scorecards, coverage and per-event results. Observed-upper-bound runs are labelled and never count toward the bar. Not a forecast.

Parameters

• id string required signal-<id> or experiment-<id>

Get the latest reported vault stocks of gold, silver, platinum or palladium per venue (COMEX/NYMEX depositories, LBMA London vaults, SHFE, SGE, bullion ETFs), in troy ounces and tonnes, with registered/eligible splits, each vault inside a venue, and the change since that location's previous report. Venues report on different schedules, so compare observed_on dates.

Parameters

• metal string required Metal to report.
• venue string optional Optional venue code: COMEX, NYMEX, LBMA_LONDON, SHFE, SGE, ETF_GLD, ...
• as_of string optional Optional ISO date; latest stocks on or before it (default today).

List physical movements of gold, silver, platinum or palladium between locations, newest first. basis "reported" rows come straight from a source: vault_receipt / vault_withdrawal (exchange depository in/out) and cross_border (customs trade between countries). basis "inferred" rows are derived from stock changes: category_transfer (registered <-> eligible inside a vault) and venue_transfer (one venue's stocks fell while another's rose), with a 0-1 confidence raised by matching customs trade. Treat inferred rows as estimates and cite their evidence.

Parameters

• metal string required Metal to report.
• since string optional ISO date; flows ending on or after it (default 90 days ago).
• basis string optional Optional: reported or inferred.
• flow_type string optional Optional flow type filter.
• location string optional Optional location code (venue, vault, or ISO country). A venue includes its vaults.
• limit integer optional Max rows (default 100, max 500).

Palladium or platinum market fundamentals by year, in koz: mine supply by country, recycling by source, demand by end use, surplus/deficit (mine + recycling - demand), cumulative balance and above-ground stocks. Only admin-approved figures extracted from cited source documents (WPIC, Johnson Matthey, USGS, producers); each year lists its citations.

Parameters

• commodity string optional palladium (default) or platinum.

Palladium or platinum cost of production per mining operation from admin-approved producer results: AISC per basket oz in USD, basket margin at spot, break-even price of the metal after by-product credits at spot, revenue-share cost, the cost curve, share of supply underwater and 50th/90th-percentile break-even. Costs convert at each report's own FX rate.

Parameters

• commodity string optional palladium (default) or platinum.

List the caller's Arc Research stories (investment theses) with id, title, description snippet, sentiment, tickers, and path. Use before get_story or journal tools when the story id/title is unknown.

No parameters.

Fetch one of the caller's stories by id or title, including description, sentiment, tickers, and recent journal entries.

Parameters

• story string required Story id or title
• journal_limit integer optional Recent journal entries to include (1-50, default 10)

List journal entries for one of the caller's stories (newest first). Pass story id or title.

Parameters

• story string required Story id or title
• limit integer optional Max entries (1-100, default 20)

Semantically search the caller's stories and journal entries (StoryChunk embeddings). Use for "what did I write about X?" style questions. Falls back to title/description match when embeddings are not ready yet.

Parameters

• query string required Natural language search query
• limit integer optional Max chunks (1-20, default 5)

Add a journal entry to one of the caller's stories (by id or title). Use when the user wants to record an insight or update on an investment thesis. This mutates the caller's data and re-embeds the story for search.

Parameters

• story string required Story id or title
• content string required Journal entry body

Alpha — requires Commodity ML alpha access. List forecast models the caller can access, including visibility and whether each is platform core.

No parameters.

Alpha — requires Commodity ML alpha access. Fetch metrics, hyperparameters, and artifact metadata for one model version.

Parameters

• model_version_id integer required CommodityMlModelVersion id

Alpha — requires Commodity ML alpha access. List recent training exports (CSV snapshots used to train forecast models). Use the id as training_export_id for get_commodity_ml_training_export, analyze_commodity_ml_training_export, or create_commodity_ml_experiment.

Parameters

• commodity string optional Commodity slug or name (optional)
• feature_profile string optional Filter profile, e.g. natural_gas_storage

Alpha — requires Commodity ML alpha access. Inspect one training export: metadata, stored data_quality audit, CSV columns, date range, present targets, and head/tail sample rows. Use analyze_commodity_ml_training_export for stats and improvement ideas.

Parameters

• training_export_id integer required CommodityMlTrainingExport id
• sample_rows integer optional Head/tail sample size (default 5, max 15)

Alpha — requires Commodity ML alpha access. Analyze a training-export CSV: column stats, target summary, feature–target correlations, collinear pairs, and ranked suggestions (missing targets, stale schema, nulls, constant features, scale). Use the suggestion actions to pick the next experiment grid or re-export.

Parameters

• training_export_id integer required CommodityMlTrainingExport id
• sample_rows integer optional Head/tail sample size (default 5, max 15)

Alpha — requires Commodity ML alpha access. List parameter experiments for a model.

Parameters

• model_id integer required CommodityMlModel id

Alpha — requires Commodity ML alpha access. Get trial ranking and walk-forward metrics for one experiment.

Parameters

• experiment_id integer required CommodityMlExperiment id

Alpha — requires Commodity ML alpha access. Start a parameter sweep experiment on a training export. Default grid: reg_param [0.1,1.0,10.0] x standardize_features [false,true].

Parameters

• model_id integer required CommodityMlModel id
• training_export_id integer required CommodityMlTrainingExport id
• parameter_grid_json string optional Optional JSON object grid
• eval_window_days integer optional Walk-forward window days (default 180; 365 for storage exports, whose newest 26 weeks are a frozen holdout)
• evaluation_method string optional How trials are ranked: walk_forward (default), purged_kfold or cpcv (purged, embargoed cross-validation over the rows before the frozen holdout; walk-forward is still reported, and cpcv adds PBO)

Alpha — requires Commodity ML alpha access. Publish your own model (subscribers or published visibility). Does not promote to platform core.

Parameters

• model_id integer required CommodityMlModel id
• visibility string optional subscribers or published (default published)

Alpha — requires Commodity ML alpha access. Queue a backtest. Pass subject (ng_signal:<enso|pv|gbi|pna|frz_permian| frz_appalachia>, ng_action_engine, or model_version:<id> for an experiment sweep) with method (walk_forward, purged_kfold, cpcv) and, for signal subjects, horizon_days (5/10/20), n_folds (5–10), embargo_days (0–60), window_start / window_end and inputs (snapshots or observed_upper_bound). Or pass only model_version_id to queue that version's walk-forward evaluation. Not a forecast.

Parameters

• model_version_id integer optional CommodityMlModelVersion id (walk-forward evaluation of that version)
• subject string optional ng_signal:<key>, ng_action_engine, or model_version:<id>
• method string optional
• horizon_days integer optional
• n_folds integer optional
• embargo_days integer optional
• window_start string optional YYYY-MM-DD
• window_end string optional YYYY-MM-DD
• inputs string optional

Alpha — requires Commodity ML alpha access. Queue a Lower-48 storage training export and (by default) train the change + direction models. Same job as the Wednesday cron. After it completes, list_commodity_ml_models / get_commodity_ml_model_version for the new storage_regression version, then run_commodity_ml_backtest.

Parameters

• commodity string optional Commodity slug or name (default natural-gas)
• start_ruby_training boolean optional Train after export (default true)

Alpha — requires Commodity ML alpha access. Queue a Squeeze Pressure (squeeze_weekly) training export: one row per NYMEX natural gas COT report with positioning, GEFS/CPC weather turns and front-month futures features, labeled covered when managed-money shorts fall 15%+ within 2 reports. By default it then trains the logistic classifier and runs the winter-by-winter walk-forward evaluation against the Squeeze Pressure rank baseline and the base rate. Afterwards: get_commodity_ml_training_export for the export, get_commodity_ml_model_version for evaluation_metrics.squeeze_walk_forward and the gate. Research, not a trading signal.

Parameters

• commodity string optional Commodity slug or name (default natural-gas)
• start_ruby_training boolean optional Train and evaluate after export (default true)
• reg_param number optional L2 regularization strength for the classifier (default 1.0; larger is stronger)
• bias_scale number optional Scale of the classifier's intercept column (default 10; larger shrinks the intercept less)
• calibrate boolean optional Platt-scale probabilities on out-of-fold training scores (default true)
• feature_set string optional core (default): the four features in SqueezeCsvExporter::CORE_FEATURE_COLUMNS; full: every exported feature

Alpha — requires Commodity ML alpha access. Latest published platform forecasts and the model version that produced them.

Parameters

• commodity string optional Commodity slug or name (default natural-gas)

Score the natural gas weekly storage call against the street consensus median and the seasonal naive. Returns 8-week and 26-week RMSE, MAE, and direction hit rate. Both windows start at the first call from the live model (live_from, the 3 Sep 2026 retrain); consensus rows captured after Thursday 10:30 ET are excluded. This does not replace the storage retrain promote card.

Parameters

• commodity string optional Commodity slug (default natural-gas).

Return the El Niño–Southern Oscillation (ENSO) state from NOAA CPC's weekly Niño 3.4 sea surface temperature anomaly (1991–2020 base): phase (el_nino above +0.5 °C, la_nina below −0.5 °C, else neutral), the 13-week ONI, how many weeks the phase has held, recent weekly anomalies, the Open-Meteo marine trajectory for the Niño 3.4 box, and the NG weather engine's ENSO score (El Niño −3, La Niña +3, bearish/bullish for gas). Point in time: only values released by as_of. Not a forecast.

Parameters

• as_of string optional Decision date YYYY-MM-DD (end of that day, UTC) or ISO 8601 time. Default now.
• weeks integer optional Weekly anomalies to return, newest last (default 13, max 104)

List NG weather signal and action-engine backtests: the nightly system runs (walk-forward, purged k-fold and CPCV for every signal and the action engine, plus the observed-index upper bound) and the caller's own runs, newest first, each with its headline (events, hit rate, average move, PBO), plus the subjects and methods run_commodity_ml_backtest accepts and the bar a record must clear. Read a run with get_ng_signal_backtest. Backtests describe the past; nothing here is a forecast.

No parameters.