v1alpha1

type BackendName string

type BackendRuntime struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   BackendRuntimeSpec   `json:"spec,omitempty"`
	Status BackendRuntimeStatus `json:"status,omitempty"`
}

type BackendRuntimeArg struct {
	// Name represents the identifier of the backendRuntime argument.
	// +kubebuilder:default=default
	// +optional
	Name *string `json:"name,omitempty"`
	// Flags represents all the preset configurations.
	// Flag around with {{ .CONFIG }} is a configuration waiting for render.
	Flags []string `json:"flags,omitempty"`
}

type BackendRuntimeConfig struct {
	// Name represents the inference backend under the hood, e.g. vLLM.
	// +kubebuilder:default=vllm
	// +optional
	Name *BackendName `json:"name,omitempty"`
	// Version represents the backend version if you want a different one
	// from the default version.
	// +optional
	Version *string `json:"version,omitempty"`
	// Args represents the specified arguments of the backendRuntime,
	// will be append to the backendRuntime.spec.Args.
	Args *BackendRuntimeArg `json:"args,omitempty"`
	// Envs represents the environments set to the container.
	// +optional
	Envs []corev1.EnvVar `json:"envs,omitempty"`
	// Resources represents the resource requirements for backend, like cpu/mem,
	// accelerators like GPU should not be defined here, but at the model flavors,
	// or the values here will be overwritten.
	Resources *ResourceRequirements `json:"resources,omitempty"`
}

type BackendRuntimeList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []BackendRuntime `json:"items"`
}

type BackendRuntimeSpec struct {
	// Commands represents the default commands for the backendRuntime.
	// +optional
	Commands []string `json:"commands,omitempty"`
	// MultiHostCommands represents leader and worker commands for nodes with
	// different roles.
	// +optional
	MultiHostCommands *MultiHostCommands `json:"multiHostCommands,omitempty"`
	// Image represents the default image registry of the backendRuntime.
	// It will work together with version to make up a real image.
	Image string `json:"image"`
	// Version represents the default version of the backendRuntime.
	// It will be appended to the image as a tag.
	Version string `json:"version"`
	// Args represents the preset arguments of the backendRuntime.
	// They can be appended or overwritten by the Playground backendRuntimeConfig.
	Args []BackendRuntimeArg `json:"args,omitempty"`
	// Envs represents the environments set to the container.
	// +optional
	Envs []corev1.EnvVar `json:"envs,omitempty"`
	// Resources represents the resource requirements for backendRuntime, like cpu/mem,
	// accelerators like GPU should not be defined here, but at the model flavors,
	// or the values here will be overwritten.
	Resources ResourceRequirements `json:"resources"`
	// Periodic probe of backend liveness.
	// Backend will be restarted if the probe fails.
	// Cannot be updated.
	// +optional
	LivenessProbe *corev1.Probe `json:"livenessProbe,omitempty"`
	// Periodic probe of backend readiness.
	// Backend will be removed from service endpoints if the probe fails.
	// +optional
	ReadinessProbe *corev1.Probe `json:"readinessProbe,omitempty"`
	// StartupProbe indicates that the Backend has successfully initialized.
	// If specified, no other probes are executed until this completes successfully.
	// If this probe fails, the backend will be restarted, just as if the livenessProbe failed.
	// This can be used to provide different probe parameters at the beginning of a backend's lifecycle,
	// when it might take a long time to load data or warm a cache, than during steady-state operation.
	// +optional
	StartupProbe *corev1.Probe `json:"startupProbe,omitempty"`
	// ScaleTriggers represents a set of triggers preset to be used by Playground.
	// If Playground not specify the scale trigger, the 0-index trigger will be used.
	// +optional
	ScaleTriggers []NamedScaleTrigger `json:"scaleTriggers,omitempty"`
}

type BackendRuntimeStatus struct {
	// Conditions represents the Inference condition.
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type ElasticConfig struct {
	// MinReplicas indicates the minimum number of inference workloads based on the traffic.
	// Default to 1.
	// MinReplicas couldn't be 0 now, will support serverless in the future.
	// +kubebuilder:default=1
	// +optional
	MinReplicas *int32 `json:"minReplicas,omitempty"`
	// MaxReplicas indicates the maximum number of inference workloads based on the traffic.
	// Default to nil means there's no limit for the instance number.
	// +optional
	MaxReplicas *int32 `json:"maxReplicas,omitempty"`
	// ScaleTriggerRef refers to the configured scaleTrigger in the backendRuntime
	// with tuned target value.
	// ScaleTriggerRef and ScaleTrigger can't be set at the same time.
	// +optional
	ScaleTriggerRef *ScaleTriggerRef `json:"scaleTriggerRef,omitempty"`
	// ScaleTrigger defines a set of triggers to scale the workloads.
	// If not defined, trigger configured in backendRuntime will be used,
	// otherwise, trigger defined here will overwrite the defaulted ones.
	// ScaleTriggerRef and ScaleTrigger can't be set at the same time.
	// +optional
	ScaleTrigger *ScaleTrigger `json:"scaleTrigger,omitempty"`
}

type HPATrigger struct {
	// metrics contains the specifications for which to use to calculate the
	// desired replica count (the maximum replica count across all metrics will
	// be used).  The desired replica count is calculated multiplying the
	// ratio between the target value and the current value by the current
	// number of pods.  Ergo, metrics used must decrease as the pod count is
	// increased, and vice-versa.  See the individual metric source types for
	// more information about how each type of metric must respond.
	// +optional
	Metrics []autoscalingv2.MetricSpec `json:"metrics,omitempty"`
	// behavior configures the scaling behavior of the target
	// in both Up and Down directions (scaleUp and scaleDown fields respectively).
	// If not set, the default HPAScalingRules for scale up and scale down are used.
	// +optional
	Behavior *autoscalingv2.HorizontalPodAutoscalerBehavior `json:"behavior,omitempty"`
}

type MultiHostCommands struct {
	Leader []string `json:"leader,omitempty"`
	Worker []string `json:"worker,omitempty"`
}

type NamedScaleTrigger struct {
	// Name represents the identifier of the scale trigger, e.g. some triggers defined for
	// latency sensitive workloads, some are defined for throughput sensitive workloads.
	Name string `json:"name,omitempty"`
	// HPA represents the trigger configuration of the HorizontalPodAutoscaler.
	HPA *HPATrigger `json:"hpa,omitempty"`
}

type Playground struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   PlaygroundSpec   `json:"spec,omitempty"`
	Status PlaygroundStatus `json:"status,omitempty"`
}

type PlaygroundList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []Playground `json:"items"`
}

type PlaygroundSpec struct {
	// Replicas represents the replica number of inference workloads.
	// +kubebuilder:default=1
	// +optional
	Replicas *int32 `json:"replicas,omitempty"`
	// ModelClaim represents claiming for one model, it's a simplified use case
	// of modelClaims. Most of the time, modelClaim is enough.
	// ModelClaim and modelClaims are exclusive configured.
	// +optional
	ModelClaim *coreapi.ModelClaim `json:"modelClaim,omitempty"`
	// ModelClaims represents claiming for multiple models for more complicated
	// use cases like speculative-decoding.
	// ModelClaims and modelClaim are exclusive configured.
	// +optional
	ModelClaims *coreapi.ModelClaims `json:"modelClaims,omitempty"`
	// BackendRuntimeConfig represents the inference backendRuntime configuration
	// under the hood, e.g. vLLM, which is the default backendRuntime.
	// +optional
	BackendRuntimeConfig *BackendRuntimeConfig `json:"backendRuntimeConfig,omitempty"`
	// ElasticConfig defines the configuration for elastic usage,
	// e.g. the max/min replicas.
	// Note: this requires to install the HPA first or will report error.
	// +optional
	ElasticConfig *ElasticConfig `json:"elasticConfig,omitempty"`
}

type PlaygroundStatus struct {
	// Conditions represents the Inference condition.
	Conditions []metav1.Condition `json:"conditions,omitempty"`
	// Replicas track the replicas that have been created, whether ready or not.
	Replicas int32 `json:"replicas"`
	// Selector points to the string form of a label selector which will be used by HPA.
	Selector string `json:"selector,omitempty"`
}

type ResourceRequirements struct {
	// Limits describes the maximum amount of compute resources allowed.
	// More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
	// +optional
	Limits corev1.ResourceList `json:"limits,omitempty"`
	// Requests describes the minimum amount of compute resources required.
	// If Requests is omitted for a container, it defaults to Limits if that is explicitly specified,
	// otherwise to an implementation-defined value. Requests cannot exceed Limits.
	// More info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
	// +optional
	Requests corev1.ResourceList `json:"requests,omitempty"`
}

type ScaleTrigger struct {
	// HPA represents the trigger configuration of the HorizontalPodAutoscaler.
	HPA *HPATrigger `json:"hpa,omitempty"`
}

type ScaleTriggerRef struct {
	// Name represents the scale trigger name defined in the backendRuntime.scaleTriggers.
	Name string `json:"name"`
}

type Service struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   ServiceSpec   `json:"spec,omitempty"`
	Status ServiceStatus `json:"status,omitempty"`
}

type ServiceList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitempty"`
	Items           []Service `json:"items"`
}

type ServiceSpec struct {
	// ModelClaims represents multiple claims for different models.
	ModelClaims coreapi.ModelClaims `json:"modelClaims,omitempty"`
	// WorkloadTemplate defines the underlying workload layout and configuration.
	// Note: the LWS spec might be twisted with various LWS instances to support
	// accelerator fungibility or other cutting-edge researches.
	// LWS supports both single-host and multi-host scenarios, for single host
	// cases, only need to care about replicas, rolloutStrategy and workerTemplate.
	WorkloadTemplate lws.LeaderWorkerSetSpec `json:"workloadTemplate"`
}

type ServiceStatus struct {
	// Conditions represents the Inference condition.
	Conditions []metav1.Condition `json:"conditions,omitempty"`
	// Replicas track the replicas that have been created, whether ready or not.
	Replicas int32 `json:"replicas"`
	// Selector points to the string form of a label selector, the HPA will be
	// able to autoscale your resource.
	Selector string `json:"selector,omitempty"`
}