v1alpha1

type API interface {
	GetAllExperiments(context.Context, *ExperimentListQuery) (ExperimentList, error)
	GetAllExperimentsByPage(context.Context, string) (ExperimentList, error)
	GetExperimentByName(context.Context, ExperimentName) (Experiment, error)
	GetExperiment(context.Context, string) (Experiment, error)
	CreateExperiment(context.Context, ExperimentName, Experiment) (Experiment, error)
	DeleteExperiment(context.Context, string) error
	GetAllTrials(context.Context, string, *TrialListQuery) (TrialList, error)
	CreateTrial(context.Context, string, TrialAssignments) (string, error) // TODO Should this return TrialAssignments?
	NextTrial(context.Context, string) (TrialAssignments, error)
	ReportTrial(context.Context, string, TrialValues) error
	AbandonRunningTrial(context.Context, string) 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 json.Number `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 Error struct {
	Type       ErrorType     `json:"-"`
	Message    string        `json:"error"`
	RetryAfter time.Duration `json:"-"`
}

type ErrorType string

type Experiment struct {
	ExperimentMeta

	// The display name of the experiment. Do not use for generating URLs!
	DisplayName string `json:"displayName,omitempty"`
	// Controls how the optimizer will generate trials.
	Optimization Optimization `json:"optimization,omitempty"`
	// The metrics been optimized in the experiment.
	Metrics []Metric `json:"metrics"`
	// The search space of the experiment.
	Parameters []Parameter `json:"parameters"`
}

type ExperimentItem struct {
	Experiment

	// The metadata for an individual experiment.
	Metadata Metadata `json:"_metadata,omitempty"`
}

type ExperimentList struct {
	ExperimentListMeta

	// The list of experiments.
	Experiments []ExperimentItem `json:"experiments,omitempty"`
}

type ExperimentListMeta struct {
	Next string `json:"-"`
	Prev string `json:"-"`
}

type ExperimentListQuery struct {
	Offset int
	Limit  int
}

type ExperimentMeta struct {
	LastModified time.Time `json:"-"`
	Self         string    `json:"-"`
	Trials       string    `json:"-"`
	NextTrial    string    `json:"-"`
}

type ExperimentName interface {
	Name() string
}

type Meta interface {
	SetLocation(string)
	SetLastModified(time.Time)
	SetLink(rel, link string)
}

type Metadata map[string][]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"`
}

type Optimization struct {
	// The estimated number of trial runs to perform for an experiment.
	ExperimentBudget int32 `json:"experimentBudget,omitempty"`
	// The total number of concurrent trial runs supported for an experiment.
	ParallelTrials int32 `json:"parallelTrials,omitempty"`
	// The total number of random trials used to start an experiment.
	BurnIn int32 `json:"burnIn,omitempty"`
}

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

type ParameterType string

type TrialAssignments struct {
	TrialMeta

	// The list of parameter names and their assigned values.
	Assignments []Assignment `json:"assignments"`
}

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"`
	// Labels for this trial.
	Labels map[string]string `json:"labels,omitempty"`
}

type TrialList struct {
	// The list of trials.
	Trials []TrialItem `json:"trials"`
}

type TrialListQuery struct {
	Status []TrialStatus
}

type TrialMeta struct {
	ReportTrial string `json:"-"`
}

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

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