v1alpha1

type API interface {
	// CheckEndpoint verifies we can talk to the backend.
	CheckEndpoint(ctx context.Context) (api.Metadata, 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 api.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 name of the experiment.
	Name ExperimentName `json:"-"`
	// The display name of the experiment.
	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 string

type Lister struct {
	// API is the Experiment API used to fetch objects.
	API API
	// BatchSize overrides the default batch size for fetching lists.
	BatchSize int
}

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"`
}