CLI Reference

The voiage command-line interface exposes calculation, plotting, and configuration helpers for the core VOI workflows.

Representative commands

voiage calculate-evpi
voiage calculate-evppi
voiage calculate-evsi
voiage calculate-enbs
voiage calculate-coss examples/cli_samples/coss_study_design.json
voiage calculate-structural-evpi
voiage calculate-structural-evppi
voiage calculate-perspective
voiage calculate-distributional-equity
voiage calculate-implementation
voiage calculate-dynamic-real-options
voiage calculate-heterogeneity-value INPUT.json --format json
voiage calculate-value-of-flexibility
voiage calculate-value-of-distributional-information
voiage calculate-mcda-information
voiage calculate-forecast-signal-information
voiage calculate-outcome-conditional-sample-information
voiage calculate-belief-state-information
voiage calculate-information-source-portfolio
voiage assess-qualitative-information
voiage calculate-expected-utility-information
voiage plot-ceac
voiage plot-ceaf
voiage plot-voi-curves
voiage plot-coss coss-result.json --output coss.png
voiage plot-dominance

Experimental Value of Perspective boundary

calculate-perspective is an experimental, fixture-backed Python surface for directional current-information Value of Perspective over an explicit sample × strategy × perspective net-benefit array. See the versioned perspective contract and capability dispositions for the supported estimand and language boundaries. Perfect, partial, and sample perspective-information estimands remain unsupported; Rust, R, and Julia execution is not advertised, and Mojo remains an external boundary.

Sample inputs

examples/cli_example.py
examples/evpi_validation.ipynb
examples/evppi_validation.ipynb
examples/evsi_validation.ipynb
examples/cli_samples/evpi_net_benefit.csv
examples/cli_samples/evppi_parameters.csv
examples/cli_samples/evsi_trial_design.json
examples/cli_samples/coss_study_design.json
examples/expected_utility_information.py
specs/frontier/value-of-flexibility/v1/fixtures/normative/input.json
specs/frontier/value-of-distributional-information/v1/fixtures/normative/input.json
specs/frontier/mcda-information/v1/fixtures/normative/input.json
specs/frontier/forecast-signal-information/v1/fixtures/normative/input.json
specs/frontier/outcome-conditional-sample-information/v1/fixtures/normative/input.json
specs/frontier/belief-state-information/v1/fixtures/normative/input.json
specs/frontier/information-source-portfolio/v1/fixtures/normative/input.json
specs/frontier/qualitative-information/v1/fixtures/normative/input.json

Experimental finite additive MCDA information value

calculate-mcda-information consumes a strict finite-state additive MCDA request. It evaluates the baseline policy and exactly one criterion, preference, and joint perfect-information partition while preserving the declared correlation between outcomes and preferences:

voiage --format json calculate-mcda-information \
  specs/frontier/mcda-information/v1/fixtures/normative/input.json \
  --output mcda-information-result.json

voiage --format text calculate-mcda-information \
  specs/frontier/mcda-information/v1/fixtures/normative/input.json

JSON output retains the versioned baseline and conditional policies, complete ties and rankings, gross and signed net information values, joint interaction, regret, fractional complete-tie rank acceptability, Pareto diagnostics, provenance, and exact-enumeration assurance. The text form reports criterion, preference, joint, and interaction values with the declared aggregate unit.

Python also exposes plot_mcda_information_value and plot_mcda_rank_acceptability. The former uses hatching, outlines, labels, and numeric annotations; the latter uses distinct markers and a labelled legend, so neither plot relies on colour alone. This experimental surface excludes AHP, outranking, non-compensatory aggregation, post-information normalization, and imperfect/sample information. Scientific review, stable promotion, release, and Rust/R/Julia parity remain separate gates.

Experimental forecast and signal information value

calculate-forecast-signal-information consumes a finite forecast artifact, outcome prior, signal likelihoods, reported conditional probabilities, frozen payoffs, feasible actions, timing and acquisition cost:

voiage --format json calculate-forecast-signal-information \
  specs/frontier/forecast-signal-information/v1/fixtures/normative/input.json \
  --output forecast-signal-result.json

The result distinguishes timely-oracle signal value from signed deployed forecast value. It reports policy changes by signal, horizon, freshness, latency, lead time, regret avoided, maximum price, calibration error, Brier diagnostics and signal-probability coverage. A late or stale signal has zero operational value. Accuracy alone is never reported as value.

The experimental Python evaluator performs exact finite enumeration and does not train forecasting models. Continuous signals, multistage recourse, endogenous temporal-dependence estimation, stable status and Rust/R/Julia execution remain gated.

Experimental information-source portfolio value

calculate-information-source-portfolio consumes a finite joint-world law, candidate information sources, feasible procurement sequences, frozen action payoffs and acquisition costs:

voiage --format json calculate-information-source-portfolio \
  specs/frontier/information-source-portfolio/v1/fixtures/normative/input.json \
  --output information-source-portfolio-result.json

The result reports every evaluated design, complete action and sequence ties, gross and signed net value, willingness to pay, prefix-conditional marginal values and exact decision-value Shapley attribution. Dependence is evaluated from the declared joint-world law; source values are not added independently. The method remains experimental pending scientific review, stable promotion and Rust/R/Julia parity.

Experimental qualitative information assessment

assess-qualitative-information consumes a governed JSON assessment and returns its complete versioned result. JSON output is deterministic and keeps the ordinal groups, complete dissent or ties, unresolved questions, approval state, audit digest, source summary, provenance and diagnostics:

voiage --format json assess-qualitative-information \
  specs/frontier/qualitative-information/v1/fixtures/normative/input.json \
  --output qualitative-information-result.json

voiage --format text assess-qualitative-information \
  specs/frontier/qualitative-information/v1/fixtures/normative/input.json

The text form is a deterministic accessibility alternative with explicit headings, status labels, unresolved questions and preserved redaction markers; it does not rely on colour. Missing evidence, dissent or unverified AI assistance remains visible rather than being converted to a score. This experimental command produces no probability, utility, currency, aggregate score or quantitative VOI estimand. Python is the only executable surface; Rust, R and Julia remain unsupported.

Experimental COSS workflow

calculate-coss reads a governed JSON specification containing a shared decision/value context and the complete set of evaluated study designs. JSON output retains the versioned CossResultV1 contract, signed ENBS curve, feasibility, deterministic optimum, uncertainty fields, diagnostics, and estimator provenance inside a CHEERS-VOI-aligned reporting envelope:

voiage --format json calculate-coss \
  examples/cli_samples/coss_study_design.json \
  --output coss-result.json
voiage plot-coss coss-result.json --output coss.png

The plotting command consumes either the CLI envelope or a bare CossResultV1 JSON document. Its high-contrast colours are reinforced by different markers and line styles for selected, feasible, and infeasible designs. COSS remains experimental and is not part of the stable v1 API.

Expected-utility information pricing

The experimental command consumes a JSON object conforming to expected-utility-information-input-v1:

voiage calculate-expected-utility-information request.json --measure bpi
voiage --format json calculate-expected-utility-information request.json \
  --presentation voc --measure eui --output result.json

The supported measures are eui, cei, bpi, spi, and ppi. The evpi display alias additionally requires --presentation voc, clairvoyant information, and positive-affine utility. VoC is only a presentation of the canonical result, so there is no separate calculate-voc command. JSON output retains the full result and diagnostics rather than returning only the selected number.

Common errors

Missing input files usually mean CLI path arguments need to point at the repo-local examples or generated CSV/JSON artifact.
Invalid JSON input is rejected early by CLI invariants tests.
If a command reports a backend or approximation warning, the payload includes the method metadata and diagnostics fields described in specs/core-api/.