v1alpha1

type API interface {
	Options(context.Context) (Server, error)

	GetAllExperiments(context.Context, ExperimentListQuery) (ExperimentList, error)
	GetAllExperimentsByPage(context.Context, string) (ExperimentList, error)
	GetExperimentByName(context.Context, ExperimentName) (Experiment, error)
	GetExperiment(context.Context, string) (Experiment, error)
	CreateExperimentByName(context.Context, ExperimentName, Experiment) (Experiment, error)
	CreateExperiment(context.Context, string, Experiment) (Experiment, error)
	DeleteExperiment(context.Context, string) error
	LabelExperiment(context.Context, string, ExperimentLabels) error

	GetAllTrials(context.Context, string, TrialListQuery) (TrialList, error)
	CreateTrial(context.Context, string, TrialAssignments) (TrialAssignments, error)
	NextTrial(context.Context, string) (TrialAssignments, error)
	ReportTrial(context.Context, string, TrialValues) error
	AbandonRunningTrial(context.Context, string) error
	LabelTrial(context.Context, string, TrialLabels) error
}

type Assignment struct {
	// The name of the parameter in the experiment the assignment corresponds to.
	ParameterName string `json:"parameterName"`
	// The assigned value of the parameter.
	Value numstr.NumberOrString `json:"value"`
}

type Bounds struct {
	// The minimum value for a numeric parameter.
	Min json.Number `json:"min"`
	// The maximum value for a numeric parameter.
	Max json.Number `json:"max"`
}

type Constraint struct {
	// Optional name for constraint.
	Name string `json:"name,omitempty"`

	ConstraintType   ConstraintType `json:"constraintType"`
	*SumConstraint   `json:",omitempty"`
	*OrderConstraint `json:",omitempty"`
}

type ConstraintType string

type Experiment struct {
	// The experiment metadata.
	api.Metadata `json:"-"`
	// The display name of the experiment. Do not use for generating URLs!
	DisplayName string `json:"displayName,omitempty"`
	// The number of observations made for this experiment.
	Observations int64 `json:"observations,omitempty"`
	// The target number of observations for this experiment.
	Budget int64 `json:"budget,omitempty"`
	// Controls how the optimizer will generate trials.
	Optimization []Optimization `json:"optimization,omitempty"`
	// The metrics been optimized in the experiment.
	Metrics []Metric `json:"metrics"`
	// Constraints for the experiment.
	Constraints []Constraint `json:"constraints,omitempty"`
	// The search space of the experiment.
	Parameters []Parameter `json:"parameters"`
	// Labels for this experiment.
	Labels map[string]string `json:"labels,omitempty"`
}

type ExperimentItem struct{ Experiment }

type ExperimentLabels struct {
	// New labels for this experiment.
	Labels map[string]string `json:"labels"`
}

type ExperimentList struct {
	// The experiment list metadata.
	api.Metadata `json:"-"`
	// The list of experiments.
	Experiments []ExperimentItem `json:"experiments,omitempty"`
}

type ExperimentListQuery struct{ api.IndexQuery }

type ExperimentName interface {
	Name() string
}

type Metric struct {
	// The name of the metric.
	Name string `json:"name"`
	// The flag indicating this metric should be minimized.
	Minimize bool `json:"minimize,omitempty"`
	// The flag indicating this metric is optimized (nil defaults to true).
	Optimize *bool `json:"optimize,omitempty"`
}

type Optimization struct {
	// The name of the optimization parameter.
	Name string `json:"name"`
	// The value of the optimization parameter.
	Value string `json:"value"`
}

type OrderConstraint struct {
	// Name of lower parameter.
	LowerParameter string `json:"lowerParameter"`
	// Name of upper parameter.
	UpperParameter string `json:"upperParameter"`
}

type Parameter struct {
	// The name of the parameter.
	Name string `json:"name"`
	// The type of the parameter.
	Type ParameterType `json:"type"`
	// The domain of the parameter.
	Bounds *Bounds `json:"bounds,omitempty"`
	// The discrete values for a categorical parameter.
	Values []string `json:"values,omitempty"`
}

type ParameterType string

type Server struct {
	api.Metadata `json:"-"`
}

type SumConstraint struct {
	// Flag indicating if bound is upper or lower bound.
	IsUpperBound bool `json:"isUpperBound,omitempty"`
	// Bound for inequality constraint.
	Bound float64 `json:"bound"`
	// Parameters and weights for constraint.
	Parameters []SumConstraintParameter `json:"parameters"`
}

type SumConstraintParameter struct {
	// Name of parameter to be used in constraint.
	ParameterName string `json:"parameterName"`
	// Weight for parameter in constraint.
	Weight float64 `json:"weight"`
}

type TrialAssignments struct {
	// The trial metadata.
	api.Metadata `json:"-"`
	// The list of parameter names and their assigned values.
	Assignments []Assignment `json:"assignments"`
	// Labels for this trial.
	Labels map[string]string `json:"labels,omitempty"`
}

type TrialItem struct {
	TrialAssignments
	TrialValues

	// The current trial status.
	Status TrialStatus `json:"status"`
	// Ordinal number indicating when during an experiment the trail was generated.
	Number int64 `json:"number"`

	// Experiment is a reference back to the experiment this trial item is associated with. This field is never
	// populated by the API, but may be useful for consumers to maintain a connection between resources.
	Experiment *Experiment `json:"-"`
}

type TrialLabels struct {
	// New labels for this trial.
	Labels map[string]string `json:"labels"`
}

type TrialList struct {
	// The trial list metadata.
	api.Metadata `json:"-"`
	// The list of trials.
	Trials []TrialItem `json:"trials"`

	// Experiment is a reference back to the experiment this trial item is associated with. This field is never
	// populated by the API, but may be useful for consumers to maintain a connection between resources.
	Experiment *Experiment `json:"-"`
}

type TrialListQuery struct{ api.IndexQuery }

type TrialStatus string

type TrialValues struct {
	// The observed values.
	Values []Value `json:"values,omitempty"`
	// Indicator that the trial failed, Values is ignored when true.
	Failed bool `json:"failed,omitempty"`
	// FailureReason is a the machine-readable reason code for the failure, if Failed is true.
	FailureReason string `json:"failureReason,omitempty"`
	// FailureMessage is a human-readable explanation of the failure, if Failed is true.
	FailureMessage string `json:"failureMessage,omitempty"`
	// StartTime is the time at which the trial was started.
	StartTime *time.Time `json:"startTime,omitempty"`
	// CompletionTime is the time at which the trial was completed.
	CompletionTime *time.Time `json:"completionTime,omitempty"`
}

type Value struct {
	// The name of the metric in the experiment the value corresponds to.
	MetricName string `json:"metricName"`
	// The observed value of the metric.
	Value float64 `json:"value"`
	// The observed error of the metric.
	Error float64 `json:"error,omitempty"`
}