nempulse

Deep-dive metrics for one battery by DUID (e.g. HPR1 = Hornsdale): revenue, dispatch, SOC, FCAS. WARNING: rev_today, energy_rev_today, fcas_rev_today and contingency_fcas_rev_today are MONTH-TO-DATE by default, not daily (matching the rev_mtd keys in fcas_breakdown) — do not report them as 'today's revenue'. throughput_cycles, throughput_mwh, avg_dispatch_price, avg_charge_price and efficiency_pct cover the same window. Pass date_from and date_to (both required together) to scope this window explicitly, e.g. to a single day, instead of relying on the month-to-date default. For a true daily time series use get_battery_revenue. rte_pct is NOT window-scoped: it is the unit's latest measured round-trip efficiency (fitted from AEMO's reported energy storage against its dispatch over a trailing 30 days, refreshed weekly), and is null for units whose fit has not cleared its acceptance checks — null means 'not measured', never 'inefficient'. Also returns commercial_context (e.g. TOLLED, CONTRACTED) and commercial_note — ALWAYS check commercial_context before comparing this unit's revenue against another unit's: tolled/contracted units do not trade merchant and their spot figures are not comparable.

{'type': 'object', 'required': ['duid'], 'properties': {'duid': {'type': 'string', 'description': 'Battery DUID, e.g. HPR1'}, 'date_to': {'type': 'string', 'description': 'Optional end date YYYY-MM-DD (requires date_from too).'}, 'date_from': {'type': 'string', 'description': 'Optional start date YYYY-MM-DD (scopes revenue/throughput stats; requires date_to too). Omit both for the month-to-date default.'}}, 'additionalProperties': False}

Actual vs LP-optimal dispatch revenue, per-DUID summary, over a date range (energy-only, perfect-foresight benchmark). NOT a revenue-total source — use get_battery_revenue for that. Both the 'actual' AND the 'optimal' figures here are MLF-adjusted (get_battery_revenue's is gross) — the LP's objective is solved on MLF-adjusted prices, not just settled at them afterward — and both cover solved LP days only (days where the solver failed are dropped from both), so the two tools' totals will not match even for the same DUID and date range. The requested date_to may also be silently truncated to the latest date with sufficient fleet-wide LP coverage. Pass duid to restrict to one battery — omitting it scans every DUID and can time out even on a ~3-week range; even a single-DUID, single-month scan has been observed to time out, so keep date ranges short and retry narrower on a timeout.

{'type': 'object', 'required': ['date_from', 'date_to'], 'properties': {'duid': {'type': 'string', 'description': 'Battery DUID, e.g. HPR1 (optional — omit for all DUIDs)'}, 'date_to': {'type': 'string', 'description': 'End date YYYY-MM-DD'}, 'date_from': {'type': 'string', 'description': 'Start date YYYY-MM-DD'}}, 'additionalProperties': False}

Daily gross-spot revenue by market (energy + FCAS) for one battery (DUID) over a date range. Daily grain only. This is the tool for total revenue questions — use get_battery_optimal only for the actual-vs-perfect-foresight benchmark, not as a revenue source (its 'actual' figure is MLF-adjusted and solved-days-only, so it will not match this tool's totals). Each day also carries energy_rev_mlf_adjusted (null if the LP backcast hasn't run for that day yet, not zero) alongside the gross energy_rev, so MLF-adjusted figures are available here too without switching tools.

{'type': 'object', 'required': ['duid', 'date_from', 'date_to'], 'properties': {'duid': {'type': 'string', 'description': 'Battery DUID, e.g. HPR1'}, 'date_to': {'type': 'string', 'description': 'End date YYYY-MM-DD'}, 'date_from': {'type': 'string', 'description': 'Start date YYYY-MM-DD'}}, 'additionalProperties': False}

Summary stats for one market price event by id (per-interval dispatch during the event is not exposed).

{'type': 'object', 'required': ['id'], 'properties': {'id': {'type': 'string', 'description': 'Event id'}}, 'additionalProperties': False}

Fleet-wide snapshot: unit count, total capacity, revenue month-to-date, average spot price.

{'type': 'object', 'properties': {}, 'additionalProperties': False}

List every NEM-registered grid-scale battery (DUID, station, region, MW/MWh, MLF, coordinates, is_commissioning, commercial_context, unit_class, peer_comparable). rev_per_mw_yr is trailing 365-day energy + FCAS revenue (NOT FPP), gross (no MLF), divided by Max Cap MW, then annualised over the days the unit actually had dispatch data — not over a fixed 365-day denominator. This is a rough simulator guide, NOT a performance ranking. It is distorted for any unit with is_commissioning=true or commissioned within the last 365 days, because that span-annualisation extrapolates a few months of ramp-up behaviour out to a full year (scale-up factors of 1.5x-2.4x are live in the current data), which magnifies both weak and negative figures rather than diluting them — do NOT try to 'correct' it by rescaling to the unit's operating span, as that double-counts the annualisation. It is also inflated for small FCAS-primary units, and structurally biased against longer-duration units (shorter-duration units can concentrate power into the highest-price intervals). Do not use it to compare units, rank performance, or answer 'which battery earns most' — use get_battery_revenue over a matched window, or get_battery_optimal for capture. Before comparing any two units' revenue, check BOTH labels on each. commercial_context (TOLLED/CONTRACTED) means the unit does not trade merchant, so its spot revenue is not comparable; a null here means no publicly documented arrangement was found, NOT that the unit is confirmed merchant — only an explicit MERCHANT value means that, and most units are null. unit_class is the structural label (STANDALONE/HYBRID/NETWORK-SUPPORT/MICRO): peer_comparable is false for the latter three, whose dispatch answers to a co-located generator, a non-market obligation, or sub-10MW FCAS granularity rather than to price. Never pool a peer_comparable=false unit into a cross-unit statistic or ranking. Null until the first background refresh completes.

{'type': 'object', 'properties': {}, 'additionalProperties': False}

List NEM spot-price events (negative, elevated, spike, extreme), optionally filtered by region.

{'type': 'object', 'properties': {'limit': {'type': 'integer', 'description': 'Max events to return (default 50, max 500)'}, 'region': {'type': 'string', 'description': 'NEM region, e.g. SA1 (optional)'}}, 'additionalProperties': False}

Ask a natural-language question about NEM BESS data; returns generated SQL, result rows and a plain-English explanation. Scope each question to roughly one region-month or less — aggregates spanning more (e.g. a full year by region, or per-day top-N across all regions) risk the generated SQL exceeding its own 8s execution cap, which this tool's longer timeout does not extend. For per-day top-N / bottom-N questions, phrase them so the generated SQL uses a window function (ROW_NUMBER/RANK) rather than a per-day correlated subquery — the latter has been observed to silently return all-null rows with no error. Only dispatch_prices, daily_revenue, optimal_dispatch, bess_price_profile and market_events are reachable here; the market_* cache tables (market_monthly, market_regression, market_corr_tracker, market_daily_price, market_daily_fleet) behind the market-analysis page live in a separate database and are NOT queryable through this tool — a question about them will be recomputed from dispatch_prices instead, which is slower and easy to phrase incorrectly.

{'type': 'object', 'required': ['question'], 'properties': {'question': {'type': 'string', 'description': 'Plain-English question (max 500 chars).'}}, 'additionalProperties': False}