Docs — Lieva dispatch decision recorder

01 · Quickstart

Import one dispatch interval.

Save the timestamp, market interval, price and forecast inputs, state of charge, chosen bid or dispatch, expected and actual outcome, and the counterfactual you considered. The minimal JSON below works with the current importer and needs no instrumentation SDK.

npx lieva import dispatch-2026-07-10.json

dispatch-2026-07-10.jsonone interval

{
  "spans": [
    {
      "traceId": "dispatch-2026-07-10-1425",
      "spanId": "bess-07-market-dispatch",
      "name": "bess.market-dispatch",
      "startTimeUnixNano": "1783712700000000000",
      "endTimeUnixNano": "1783712700180000000",
      "attributes": [
        { "key": "decision.timestamp", "value": { "stringValue": "2026-07-10T14:25:00Z" } },
        { "key": "market.interval", "value": { "stringValue": "2026-07-10T14:25:00Z/2026-07-10T14:30:00Z" } },
        { "key": "input.prices_usd_mwh", "value": { "arrayValue": { "values": [
          { "doubleValue": 84.2 }, { "doubleValue": 91.7 }, { "doubleValue": 76.4 }
        ] } } },
        { "key": "input.forecast_mw", "value": { "doubleValue": 18.6 } },
        { "key": "input.soc_pct", "value": { "doubleValue": 63.4 } },
        { "key": "decision.bid_mw", "value": { "doubleValue": 12.0 } },
        { "key": "decision.dispatch_mw", "value": { "doubleValue": 11.8 } },
        { "key": "outcome.expected_revenue_usd", "value": { "doubleValue": 91.70 } },
        { "key": "outcome.actual_revenue_usd", "value": { "doubleValue": 90.17 } },
        { "key": "counterfactual.note", "value": { "stringValue": "Holding 4 MW for the next interval would reduce cycling but miss the current spread." } }
      ],
      "status": { "code": 1 }
    }
  ]
}

If your historian writes CSV, keep the same decision fields, convert the selected rows to this JSON shape, then import the resulting file. The current CLI reads JSON files.

Import is local and offline. Add --push only when you want to send the raw record to your hosted Lieva inbox.

npx lieva import dispatch-2026-07-10.json --push

02 · Why record decisions

Configuration changes. Behavior drifts. The log should show both.

A firmware or configuration change can alter dispatch behavior for months without an obvious alarm. A decision record puts the inputs, action, result, and counterfactual beside the version that produced them, so the postmortem starts with evidence instead of recollection.

Postmortems: Replay the market interval against the prices, forecast, SoC, bid, dispatch, and software version that were present at decision time.
Owner and lender reports: Keep the evidence behind reliability reviews and shadow-trading audits without exposing the full strategy log by default.
AEMO rebid records: Rebids need a brief, verifiable, and specific contemporaneous reason. AER examines flagged bids weekly, so keep the reason tied to the exact interval and inputs.

EU AI Act Article 12: get ready for the Dec 2027 and Aug 2028 enforcement dates, but first check whether your system is in scope. Most trading optimizers likely are not.

03 · Local-first & data sovereignty

Dispatch data is trading alpha. It stays on your machine.

The MIT CLI reads and categorizes your trace locally. The timeline works offline. Nothing leaves the machine unless you add --push; that explicit action sends the raw trace to your configured Lieva inbox.

04 · CLI reference

Commands and flags in 0.1.0.

The reference below mirrors the current source. Import accepts JSON trace exports; CSV decision logs must be converted to JSON before import.

lieva import <file> [options]

Normalize a supported JSON trace export, print its detected source and span count, surface the first broken step, and emit a RepairSpec skeleton.

--source <source>: Set auto, otel, langfuse, langsmith, or openai. Default: auto.
--out <file>: Write the generated RepairSpec to a file instead of stdout.
--push: POST the raw trace to the hosted inbox. Requires LIEVA_API_KEY. --upload remains an alias.

lieva validate <file>

Validate a RepairSpec JSON file. The command exits 0 when valid and 1 when invalid, printing validation errors to stderr.

lieva --help · lieva --version

Print usage or CLI version. Short aliases: -h and -v.

Environment

LIEVA_API_KEY — required for --push.
LIEVA_INGEST_URL — overrides the ingest endpoint; the source default is http://localhost:4318.

Record the decision before someone asks why.