defmodule TradeMachine.GMGradeV2.PTV do
  @moduledoc """
  Entry point and calibration gate for Player Transaction Value.

  The checked-in nonlinear curve is intentionally provisional. Candidate
  parameters may be fitted against labeled transaction cases, but only a
  reviewed human decision may set `"calibrated": true`.
  """

  alias TradeMachine.GMGradeV2.PTV.NonlinearV1

  @doc "Values a player with the current PTV implementation."
  @spec value(map(), map()) :: %{ptv: float(), confidence: atom(), diagnostics: map()}
  def value(player_snapshot, context \\ %{}), do: NonlinearV1.value(player_snapshot, context)

  @doc "Returns whether the checked-in coefficient set passed human calibration."
  @spec calibrated?() :: boolean()
  def calibrated? do
    coefficients_document() |> Map.fetch!("calibrated")
  end

  @doc "Loads the versioned coefficient document."
  @spec coefficients_document() :: map()
  def coefficients_document do
    expected = Map.fetch!(TradeMachine.GMGradeV2.ModelVersion.versions(), :ptv)

    document =
      :ptv |> TradeMachine.Valuation.ModelArtifact.load_legacy!(expected) |> legacy_projection()

    actual = Map.fetch!(document, "version")

    if actual != expected do
      raise ArgumentError,
            "PTV coefficient version #{inspect(actual)} does not match model registry #{inspect(expected)}"
    end

    document
  end

  defp legacy_projection(artifact) do
    artifact
    |> Map.fetch!("parameters")
    |> Map.put("version", Map.fetch!(artifact, "version"))
    |> Map.put("calibrated", get_in(artifact, ["approval", "calibrated"]))
  end
end