v1alpha1

type AcceleratorSpec struct {
	// Type of accelerator hardware.
	// The operator uses this to determine the appropriate resource name
	// (e.g. nvidia.com/gpu, amd.com/gpu) and any accelerator-specific
	// environment variables.
	// +kubebuilder:validation:Enum=nvidia;amd;intel-gaudi;google;cpu
	// +required
	Type AcceleratorType `json:"type"`
}

type AcceleratorType string

type EPPFailureMode string

type EndpointPickerSpec struct {
	// Image is the EPP container image.
	// +kubebuilder:default="ghcr.io/llm-d/llm-d-inference-scheduler:v0.6.0"
	// +optional
	Image string `json:"image,omitempty"`

	// Replicas is the number of EPP pod replicas.
	// +kubebuilder:default=1
	// +kubebuilder:validation:Minimum=0
	// +optional
	Replicas *int32 `json:"replicas,omitempty"`

	// Resources for the EPP container (CPU, memory).
	// CPU limits are intentionally left unset by default to allow bursting
	// during scheduling spikes.
	// +optional
	Resources corev1.ResourceRequirements `json:"resources,omitempty"`

	// Port of the EPP service (extProc gRPC port).
	// +kubebuilder:default=9002
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	// +optional
	Port int32 `json:"port,omitempty"`

	// FailureMode determines behavior when the EPP is unavailable.
	// +kubebuilder:validation:Enum=FailOpen;FailClose
	// +kubebuilder:default="FailOpen"
	// +optional
	FailureMode EPPFailureMode `json:"failureMode,omitempty"`
}

type EngineSpec struct {
	// Image is the vLLM container image.
	// +kubebuilder:default="ghcr.io/llm-d/llm-d-cuda:v0.5.1"
	// +optional
	Image string `json:"image,omitempty"`

	// ImagePullPolicy for the engine container.
	// +optional
	ImagePullPolicy corev1.PullPolicy `json:"imagePullPolicy,omitempty"`

	// Args are additional vLLM command-line arguments.
	// The operator automatically sets --model, --port, --served-model-name,
	// --tensor-parallel-size, and --data-parallel-size based on the spec.
	// User-provided args are appended after the auto-generated ones.
	// +optional
	Args []string `json:"args,omitempty"`

	// Env are additional environment variables for the engine container.
	// +optional
	Env []corev1.EnvVar `json:"env,omitempty"`

	// Port is the port the inference engine listens on.
	// When a routing proxy is enabled, this is the external port exposed by the proxy,
	// and vLLM listens on routingProxy.targetPort instead.
	// +kubebuilder:default=8000
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	// +optional
	Port int32 `json:"port,omitempty"`
}

type GatewayRef struct {
	// Name of the Gateway.
	// +kubebuilder:validation:MinLength=1
	// +required
	Name string `json:"name"`

	// Namespace of the Gateway. If empty, defaults to the ModelService namespace.
	// +optional
	Namespace string `json:"namespace,omitempty"`
}

type HTTPRouteSpec struct {
	// GatewayRef references the Gateway to attach the HTTPRoute to.
	// +required
	GatewayRef GatewayRef `json:"gatewayRef"`

	// Hostnames for the HTTPRoute. If empty, the route matches all hostnames.
	// +optional
	Hostnames []string `json:"hostnames,omitempty"`
}

type HuggingFaceSource struct {
	// Model is the HuggingFace model identifier (e.g. "microsoft/phi-4", "facebook/opt-125m").
	// Must contain only alphanumerics, dots, underscores, hyphens, and slashes.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern="^[a-zA-Z0-9][a-zA-Z0-9._/-]*$"
	// +required
	Model string `json:"model"`

	// Revision pins a specific branch, tag, or commit hash.
	// If not specified, the default branch is used.
	// Must contain only alphanumerics, dots, underscores, hyphens, and slashes.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern="^[a-zA-Z0-9._/-]*$"
	// +optional
	Revision string `json:"revision,omitempty"`

	// TokenSecretRef references a Secret containing the HuggingFace access token.
	// Required for private or gated repositories.
	// +optional
	TokenSecretRef *SecretKeySelector `json:"tokenSecretRef,omitempty"`
}

type InferencePoolSpec struct {
	// EndpointPicker configures the Endpoint Picker extension deployment.
	// The operator creates and manages the EPP Deployment, Service, and
	// supporting resources alongside the InferencePool.
	// +required
	EndpointPicker EndpointPickerSpec `json:"endpointPicker"`
}

type ModelArtifact struct {
	metav1.TypeMeta `json:",inline"`

	// Standard object's metadata.
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// Spec defines the desired artifact.
	// +required
	Spec ModelArtifactSpec `json:"spec"`

	// Status represents the current state of the artifact pipeline.
	// +optional
	Status ModelArtifactStatus `json:"status,omitzero"`
}

type ModelArtifactList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []ModelArtifact `json:"items"`
}

type ModelArtifactPhase string

type ModelArtifactSpec struct {
	// Source defines where to fetch the model from.
	// +required
	Source ModelSource `json:"source"`

	// Target defines the OCI registry destination for the packaged artifact.
	// +required
	Target OCITarget `json:"target"`

	// Format specifies the OCI artifact packaging format.
	// +kubebuilder:validation:Enum=ModelPack;ModelKit
	// +kubebuilder:default=ModelPack
	// +optional
	Format PackFormat `json:"format,omitempty"`

	// Storage configures the temporary PVC used during the import/pack/push pipeline.
	// The PVC is automatically cleaned up after the job completes.
	// +required
	Storage StorageSpec `json:"storage"`
}

type ModelArtifactStatus struct {
	// ObservedGeneration is the most recent generation observed by the controller.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Phase is the high-level summary of the artifact lifecycle.
	// +optional
	Phase ModelArtifactPhase `json:"phase,omitempty"`

	// Digest is the OCI manifest digest of the pushed artifact (e.g. "sha256:abc123...").
	// Only populated when Phase is Succeeded.
	// +optional
	Digest string `json:"digest,omitempty"`

	// Reference is the full OCI reference of the pushed artifact including tag.
	// +optional
	Reference string `json:"reference,omitempty"`

	// JobRef references the most recently created Job for this artifact.
	// +optional
	JobRef *ResourceReference `json:"jobRef,omitempty"`

	// StartTime is the timestamp when the most recent job was created.
	// +optional
	StartTime *metav1.Time `json:"startTime,omitempty"`

	// CompletionTime is the timestamp when the most recent job completed (succeeded or failed).
	// +optional
	CompletionTime *metav1.Time `json:"completionTime,omitempty"`

	// Conditions store the status conditions of the ModelArtifact.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type ModelService struct {
	metav1.TypeMeta `json:",inline"`

	// Standard object's metadata.
	// +optional
	metav1.ObjectMeta `json:"metadata,omitzero"`

	// Spec defines the desired model serving configuration.
	// +required
	Spec ModelServiceSpec `json:"spec"`

	// Status represents the current state of the model serving deployment.
	// +optional
	Status ModelServiceStatus `json:"status,omitzero"`
}

type ModelServiceList struct {
	metav1.TypeMeta `json:",inline"`
	metav1.ListMeta `json:"metadata,omitzero"`
	Items           []ModelService `json:"items"`
}

type ModelServicePhase string

type ModelServiceSpec struct {
	// Model defines the OCI model artifact and serving identity.
	// +required
	Model ModelSpec `json:"model"`

	// Engine configures the inference engine (vLLM).
	// +required
	Engine EngineSpec `json:"engine"`

	// Accelerator configures the GPU/accelerator type for serving pods.
	// +required
	Accelerator AcceleratorSpec `json:"accelerator"`

	// Decode configures the decode (or unified) serving pods.
	// In non-disaggregated mode, these are the only serving pods.
	// +required
	Decode RoleSpec `json:"decode"`

	// Prefill optionally configures separate prefill pods for disaggregated serving.
	// When set, the serving architecture splits into Prefill (prompt processing)
	// and Decode (token generation) phases on separate pod groups.
	// +optional
	Prefill *RoleSpec `json:"prefill,omitempty"`

	// RoutingProxy configures the llm-d routing sidecar for disaggregated serving.
	// Required when Prefill is set; the proxy routes prefill requests between pods.
	// +optional
	RoutingProxy *RoutingProxySpec `json:"routingProxy,omitempty"`

	// InferencePool configures the Gateway API Inference Extension InferencePool.
	// When set, the operator creates and manages an InferencePool resource
	// with selector labels matching the serving pods.
	// +optional
	InferencePool *InferencePoolSpec `json:"inferencePool,omitempty"`

	// HTTPRoute optionally creates a Gateway API HTTPRoute pointing to the InferencePool.
	// Requires InferencePool to be set.
	// +optional
	HTTPRoute *HTTPRouteSpec `json:"httpRoute,omitempty"`

	// Monitoring configures observability features.
	// +optional
	Monitoring *MonitoringSpec `json:"monitoring,omitempty"`
}

type ModelServiceStatus struct {
	// ObservedGeneration is the most recent generation observed by the controller.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Phase is the high-level summary of the ModelService lifecycle.
	// +optional
	Phase ModelServicePhase `json:"phase,omitempty"`

	// DecodeReady is the number of ready decode replicas.
	// +optional
	DecodeReady int32 `json:"decodeReady,omitempty"`

	// DecodeReplicas is the desired number of decode replicas.
	// +optional
	DecodeReplicas int32 `json:"decodeReplicas,omitempty"`

	// PrefillReady is the number of ready prefill replicas.
	// +optional
	PrefillReady int32 `json:"prefillReady,omitempty"`

	// PrefillReplicas is the desired number of prefill replicas.
	// +optional
	PrefillReplicas int32 `json:"prefillReplicas,omitempty"`

	// Conditions store the status conditions of the ModelService.
	// +listType=map
	// +listMapKey=type
	// +optional
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type ModelSource struct {
	// HuggingFace specifies a HuggingFace Hub repository as the model source.
	// +optional
	HuggingFace *HuggingFaceSource `json:"huggingFace,omitempty"`
}

type ModelSpec struct {
	// Name is the model identifier used in OpenAI-compatible API requests
	// (e.g. "qwen/Qwen3-32B", "meta-llama/Llama-3-70B-Instruct").
	// This is passed to vLLM as --served-model-name.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +required
	Name string `json:"name"`

	// Image is the OCI reference for the model artifact.
	// It is used as a Kubernetes image volume source, leveraging node-level
	// container image caching for efficient model distribution.
	// Example: "registry.example.com/models/qwen3-32b:v1"
	// +kubebuilder:validation:MinLength=1
	// +required
	Image string `json:"image"`

	// MountPath is where the model artifact is mounted in serving containers.
	// The vLLM --model argument is automatically set to this path.
	// +kubebuilder:default="/models"
	// +optional
	MountPath string `json:"mountPath,omitempty"`

	// ImagePullSecrets for pulling the model OCI artifact from a private registry.
	// +optional
	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`
}

type MonitoringSpec struct {
	// PodMonitor configures Prometheus PodMonitor creation for serving pods.
	// +optional
	PodMonitor *PodMonitorSpec `json:"podMonitor,omitempty"`
}

type OCITarget struct {
	// Registry is the OCI registry host, optionally with port (e.g. "ghcr.io", "registry.local:5001").
	// Must not contain slashes — the path component belongs in Repository.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern="^[a-zA-Z0-9][a-zA-Z0-9._:-]*$"
	// +required
	Registry string `json:"registry"`

	// Repository is the OCI repository path within the registry (e.g. "myorg/models/phi-4", "facebook/opt-125m").
	// Must not include the registry host. Must contain only alphanumerics, dots, underscores, hyphens, and slashes.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=253
	// +kubebuilder:validation:Pattern="^[a-zA-Z0-9][a-zA-Z0-9._/-]*$"
	// +required
	Repository string `json:"repository"`

	// Tag is the image tag to push. Defaults to "latest" if not specified.
	// Must contain only alphanumerics, dots, underscores, and hyphens.
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:MaxLength=128
	// +kubebuilder:validation:Pattern="^[a-zA-Z0-9][a-zA-Z0-9._-]*$"
	// +optional
	Tag string `json:"tag,omitempty"`

	// CredentialsSecretRef references a Secret containing OCI registry credentials.
	// The Secret must contain "username" and "password" keys.
	// +optional
	CredentialsSecretRef *SecretReference `json:"credentialsSecretRef,omitempty"`

	// Insecure uses an unencrypted connection to the registry instead of TLS.
	// Only use for development or air-gapped environments.
	// +optional
	Insecure bool `json:"insecure,omitempty"`
}

type PackFormat string

type ParallelismSpec struct {
	// Tensor is the tensor-parallel-size: number of GPUs used to shard a single model.
	// +kubebuilder:default=1
	// +kubebuilder:validation:Minimum=1
	// +optional
	Tensor int32 `json:"tensor,omitempty"`

	// Data is the data-parallel-size: number of data-parallel replicas within a single pod.
	// +kubebuilder:default=1
	// +kubebuilder:validation:Minimum=1
	// +optional
	Data int32 `json:"data,omitempty"`

	// DataLocal is the data-parallel-size-local for disaggregated serving.
	// +kubebuilder:default=1
	// +kubebuilder:validation:Minimum=1
	// +optional
	DataLocal int32 `json:"dataLocal,omitempty"`
}

type PodMonitorSpec struct {
	// Enabled controls PodMonitor creation.
	// +kubebuilder:default=false
	// +optional
	Enabled bool `json:"enabled,omitempty"`

	// PortName to scrape metrics from. Must match a named port on the vLLM container.
	// +kubebuilder:default="http"
	// +optional
	PortName string `json:"portName,omitempty"`

	// Path is the HTTP endpoint to scrape metrics from.
	// +kubebuilder:default="/metrics"
	// +optional
	Path string `json:"path,omitempty"`

	// Interval between scrapes.
	// +kubebuilder:default="30s"
	// +optional
	Interval string `json:"interval,omitempty"`
}

type ResourceReference struct {
	// Name is the name of the referenced resource.
	// +required
	Name string `json:"name"`

	// Namespace is the namespace of the referenced resource.
	// +optional
	Namespace string `json:"namespace,omitempty"`
}

type RoleSpec struct {
	// Replicas is the desired number of pod replicas.
	// +kubebuilder:default=1
	// +kubebuilder:validation:Minimum=0
	// +optional
	Replicas *int32 `json:"replicas,omitempty"`

	// Parallelism configures vLLM tensor/data parallelism for this role.
	// +optional
	Parallelism ParallelismSpec `json:"parallelism,omitempty"`

	// Resources for the vLLM container (CPU, memory).
	// GPU resources are automatically calculated from accelerator type
	// and parallelism (tensor * dataLocal) and should not be set manually.
	// +optional
	Resources corev1.ResourceRequirements `json:"resources,omitempty"`

	// NodeSelector constrains pods to nodes with matching labels.
	// +optional
	NodeSelector map[string]string `json:"nodeSelector,omitempty"`

	// Tolerations for the serving pods.
	// +optional
	Tolerations []corev1.Toleration `json:"tolerations,omitempty"`
}

type RoutingProxySpec struct {
	// Image is the routing proxy container image.
	// +kubebuilder:default="ghcr.io/llm-d/llm-d-routing-sidecar:v0.6.0"
	// +optional
	Image string `json:"image,omitempty"`

	// Connector specifies the KV-cache transfer protocol.
	// +kubebuilder:default="nixlv2"
	// +optional
	Connector string `json:"connector,omitempty"`

	// TargetPort is the port where vLLM actually listens when the proxy is enabled.
	// The proxy intercepts on engine.port and forwards to this port.
	// +kubebuilder:default=8200
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=65535
	// +optional
	TargetPort int32 `json:"targetPort,omitempty"`

	// ZapEncoder sets the Zap log encoding format (e.g. "json", "console").
	// +optional
	ZapEncoder string `json:"zapEncoder,omitempty"`

	// ZapLogLevel sets the Zap log level (e.g. "debug", "info", "error").
	// +optional
	ZapLogLevel string `json:"zapLogLevel,omitempty"`

	// SecureProxy enables TLS on the routing proxy.
	// +optional
	SecureProxy *bool `json:"secureProxy,omitempty"`

	// PrefillerUseTLS enables TLS for prefiller communication.
	// +optional
	PrefillerUseTLS *bool `json:"prefillerUseTLS,omitempty"`

	// CertPath is the path to TLS certificates for the routing proxy.
	// +optional
	CertPath string `json:"certPath,omitempty"`
}

type SecretKeySelector struct {
	// Name is the name of the Secret in the same namespace as the ModelArtifact.
	// +kubebuilder:validation:MinLength=1
	// +required
	Name string `json:"name"`

	// Key is the key within the Secret data. If omitted, defaults to "token".
	// +optional
	Key string `json:"key,omitempty"`
}

type SecretReference struct {
	// Name is the name of the Secret in the same namespace as the ModelArtifact.
	// +kubebuilder:validation:MinLength=1
	// +required
	Name string `json:"name"`
}

type StorageSpec struct {
	// Size is the requested PVC storage capacity (e.g. "100Gi").
	// Should be at least 2x the expected model size to accommodate both
	// the downloaded files and the packed artifact.
	// +required
	Size resource.Quantity `json:"size"`

	// StorageClassName overrides the cluster default StorageClass.
	// If not specified, the cluster default StorageClass is used.
	// +optional
	StorageClassName *string `json:"storageClassName,omitempty"`
}