crucible_ir

defmodule CrucibleIR do
  @moduledoc """
  Intermediate Representation for the Crucible ML reliability ecosystem.

  `CrucibleIR` provides shared data structures for defining ML reliability
  experiments across the Crucible ecosystem. It includes definitions for
  experiments, backends, datasets, reliability configurations, and more.

  ## Main Components

  - `CrucibleIR.Experiment` - Top-level experiment definition
  - `CrucibleIR.BackendRef` - Reference to an LLM backend
  - `CrucibleIR.DatasetRef` - Reference to a dataset
  - `CrucibleIR.StageDef` - Processing stage definition
  - `CrucibleIR.OutputSpec` - Output specification
  - `CrucibleIR.Reliability.Config` - Container for reliability configurations

  ## Reliability Mechanisms

  - `CrucibleIR.Reliability.Ensemble` - Ensemble voting configuration
  - `CrucibleIR.Reliability.Hedging` - Request hedging configuration
  - `CrucibleIR.Reliability.Stats` - Statistical testing configuration
  - `CrucibleIR.Reliability.Fairness` - Fairness checking configuration
  - `CrucibleIR.Reliability.Guardrail` - Security guardrails configuration

  ## Example

      iex> alias CrucibleIR.{Experiment, BackendRef, StageDef}
      iex> exp = CrucibleIR.new_experiment(
      ...>   id: :my_exp,
      ...>   backend: %BackendRef{id: :gpt4},
      ...>   pipeline: [%StageDef{name: :inference}]
      ...> )
      iex> exp.backend.id
      :gpt4
  """

  alias CrucibleIR.Experiment

  @doc """
  Creates a new experiment with the given attributes.

  This is a convenience function for creating `CrucibleIR.Experiment` structs.

  ## Parameters

  - `attrs` - Keyword list of experiment attributes

  ## Required Attributes

  - `:id` - Unique experiment identifier
  - `:backend` - BackendRef struct
  - `:pipeline` - List of StageDef structs

  ## Optional Attributes

  - `:description` - Experiment description
  - `:owner` - Experiment owner
  - `:tags` - List of tags
  - `:metadata` - Additional metadata map
  - `:dataset` - DatasetRef struct
  - `:reliability` - Reliability.Config struct
  - `:outputs` - List of OutputSpec structs
  - `:created_at` - Creation timestamp
  - `:updated_at` - Update timestamp

  ## Examples

      iex> alias CrucibleIR.{BackendRef, StageDef}
      iex> exp = CrucibleIR.new_experiment(
      ...>   id: :test,
      ...>   backend: %BackendRef{id: :gpt4},
      ...>   pipeline: [%StageDef{name: :run}]
      ...> )
      iex> exp.id
      :test

      iex> alias CrucibleIR.{BackendRef, StageDef, DatasetRef}
      iex> alias CrucibleIR.Reliability.{Config, Stats}
      iex> exp = CrucibleIR.new_experiment(
      ...>   id: :exp1,
      ...>   backend: %BackendRef{id: :gpt4},
      ...>   pipeline: [%StageDef{name: :run}],
      ...>   dataset: %DatasetRef{name: :mmlu},
      ...>   reliability: %Config{stats: %Stats{alpha: 0.01}}
      ...> )
      iex> exp.reliability.stats.alpha
      0.01
  """
  @spec new_experiment(keyword()) :: Experiment.t()
  def new_experiment(attrs) when is_list(attrs) do
    struct!(Experiment, attrs)
  end
end