v1alpha1

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

	Spec   AIMArtifactSpec   `json:"spec,omitempty"`
	Status AIMArtifactStatus `json:"status,omitempty"`
}

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

type AIMArtifactMode string

type AIMArtifactSpec struct {
	// SourceURI specifies the source location of the model to download.
	// Supported protocols: hf:// (HuggingFace) and s3:// (S3-compatible storage).
	// This field uniquely identifies the artifact and is immutable after creation.
	// Example: hf://meta-llama/Llama-3-8B
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="sourceUri is immutable"
	// +kubebuilder:validation:Pattern=`^(hf|s3)://[^ \t\r\n]+$`
	SourceURI string `json:"sourceUri"`

	// ModelID is the canonical identifier in {org}/{name} format.
	// Determines the cache download path: /workspace/cache/{modelId}
	// For HuggingFace sources, this is typically derived from the URI (e.g., "meta-llama/Llama-3-8B").
	// For S3 sources, this must be explicitly provided (e.g., "my-team/fine-tuned-llama").
	// When not specified, derived from SourceURI for HuggingFace sources.
	// +optional
	// +kubebuilder:validation:Pattern=`^[a-zA-Z0-9_-]+/[a-zA-Z0-9._-]+$`
	ModelID string `json:"modelId,omitempty"`

	// StorageClassName specifies the storage class for the cache volume.
	// When not specified, uses the cluster default storage class.
	// +optional
	StorageClassName string `json:"storageClassName,omitempty"`

	// Size specifies the size of the cache volume
	// +optional
	Size resource.Quantity `json:"size"`

	// Env lists the environment variables to use for authentication when downloading models.
	// These variables are used for authentication with model registries (e.g., HuggingFace tokens).
	// +optional
	// +listType=map
	// +listMapKey=name
	Env []corev1.EnvVar `json:"env,omitempty"`

	// ModelDownloadImage specifies the container image used to download and initialize the artifact.
	// This image runs as a job to download model artifacts from the source URI to the cache volume.
	// When not specified, defaults to "ghcr.io/silogen/aim-artifact-downloader:0.2.0".
	// +optional
	// +kubebuilder:default="ghcr.io/silogen/aim-artifact-downloader:0.2.0"
	ModelDownloadImage string `json:"modelDownloadImage,omitempty"`

	// ImagePullSecrets references secrets for pulling AIM container images.
	// +optional
	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`

	// RuntimeConfigRef contains the runtime config reference for this artifact.
	RuntimeConfigRef `json:",inline"`
}

type AIMArtifactStatus struct {
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions represent the latest available observations of the artifact's state
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// Status represents the current status of the artifact
	// +kubebuilder:default=Pending
	// +kubebuilder:validation:Enum=Pending;Progressing;Ready;Degraded;Failed;NotAvailable
	Status constants.AIMStatus `json:"status,omitempty"`

	// Progress represents the download progress when Status is Progressing
	// +optional
	Progress *DownloadProgress `json:"progress,omitempty"`

	// Download represents the current download attempt state, patched by the downloader pod.
	// Shows which protocol is active, what attempt we're on, etc.
	// +optional
	Download *DownloadState `json:"download,omitempty"`

	// DisplaySize is the human-readable effective size (spec or discovered)
	// +optional
	DisplaySize string `json:"displaySize,omitempty"`

	// LastUsed represents the last time a model was deployed that used this cache
	LastUsed *metav1.Time `json:"lastUsed,omitempty"`

	// PersistentVolumeClaim represents the name of the created PVC
	PersistentVolumeClaim string `json:"persistentVolumeClaim,omitempty"`

	// Mode indicates the ownership mode of this artifact, derived from owner references.
	// - Dedicated: Has owner references, will be garbage collected when owners are deleted.
	// - Shared: No owner references, persists independently and can be shared.
	// +optional
	Mode AIMArtifactMode `json:"mode,omitempty"`
	// DiscoveredSizeBytes is the model size discovered via check-size job.
	// Populated when spec.size is not provided.
	// +optional
	DiscoveredSizeBytes *int64 `json:"discoveredSizeBytes,omitempty"`

	// AllocatedSize is the actual PVC size requested (including headroom).
	// +optional
	AllocatedSize resource.Quantity `json:"allocatedSize,omitempty"`

	// HeadroomPercent is the headroom percentage that was applied to the PVC size.
	// +optional
	HeadroomPercent *int32 `json:"headroomPercent,omitempty"`
}

type AIMCachingMode string

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

	Spec   AIMModelSpec   `json:"spec,omitempty"`
	Status AIMModelStatus `json:"status,omitempty"`
}

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

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

	Spec   AIMClusterModelSourceSpec   `json:"spec,omitempty"`
	Status AIMClusterModelSourceStatus `json:"status,omitempty"`
}

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

type AIMClusterModelSourceSpec struct {
	// Registry to sync from (e.g., docker.io, ghcr.io, gcr.io).
	// Defaults to docker.io if not specified.
	// +kubebuilder:default=docker.io
	// +optional
	Registry string `json:"registry,omitempty"`

	// ImagePullSecrets contains references to secrets for authenticating to private registries.
	// Secrets must exist in the operator namespace (typically aim-system).
	// Used for both registry catalog listing and image metadata extraction.
	// +optional
	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`

	// Filters define which images to discover and sync.
	// Each filter specifies an image pattern with optional version constraints and exclusions.
	// Multiple filters are combined with OR logic (any match includes the image).
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=100
	Filters []ModelSourceFilter `json:"filters"`

	// SyncInterval defines how often to sync with the registry.
	// Defaults to 1h. Minimum recommended interval is 15m to avoid rate limiting.
	// Format: duration string (e.g., "30m", "1h", "2h30m").
	// +kubebuilder:default="1h"
	// +optional
	SyncInterval metav1.Duration `json:"syncInterval,omitempty"`

	// Versions specifies global semantic version constraints applied to all filters.
	// Individual filters can override this with their own version constraints.
	// Constraints use semver syntax: >=1.0.0, <2.0.0, ~1.2.0, ^1.0.0, etc.
	// Non-semver tags (e.g., "latest", "dev") are silently skipped.
	//
	// Version ranges work on all registries (including ghcr.io, gcr.io) when combined with
	// exact repository names (no wildcards). The controller uses the Tags List API to fetch
	// all tags for the repository and filters them by the semver constraint.
	//
	// Example: registry=ghcr.io, filters=[{image: "silogen/aim-llama"}], versions=[">=1.0.0"]
	// will fetch all tags from ghcr.io/silogen/aim-llama and include only those >=1.0.0.
	// +optional
	Versions []string `json:"versions,omitempty"`

	// MaxModels is the maximum number of AIMClusterModel resources to create from this source.
	// Once this limit is reached, no new models will be created, even if more matching images are discovered.
	// Existing models are never deleted.
	// This prevents runaway model creation from overly broad filters.
	// +kubebuilder:default=100
	// +kubebuilder:validation:Minimum=1
	// +kubebuilder:validation:Maximum=10000
	// +optional
	MaxModels *int `json:"maxModels,omitempty"`
}

type AIMClusterModelSourceStatus struct {
	// Status represents the overall state of the model source.
	// +kubebuilder:validation:Enum=Pending;Starting;Progressing;Ready;Running;Degraded;NotAvailable;Failed
	// +optional
	Status string `json:"status,omitempty"`

	// LastSyncTime is the timestamp of the last successful registry sync.
	// Updated after each successful sync operation.
	// +optional
	LastSyncTime *metav1.Time `json:"lastSyncTime,omitempty"`

	// DiscoveredModels is the count of AIMClusterModel resources managed by this source.
	// Includes both existing and newly created models.
	// +optional
	DiscoveredModels int `json:"discoveredModels,omitempty"`

	// AvailableModels is the total count of images discovered in the registry that match the filters.
	// This may be higher than DiscoveredModels if maxModels limit was reached.
	// +optional
	AvailableModels int `json:"availableModels,omitempty"`

	// ModelsLimitReached indicates whether the maxModels limit has been reached.
	// When true, no new models will be created even if more matching images are discovered.
	// +optional
	ModelsLimitReached bool `json:"modelsLimitReached,omitempty"`

	// Conditions represent the latest available observations of the source's state.
	// Standard conditions: Ready, Syncing, RegistryReachable.
	// +optional
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// ObservedGeneration reflects the generation of the most recently observed spec.
	// +optional
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`
}

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

	Spec   AIMClusterRuntimeConfigSpec `json:"spec,omitempty"`
	Status AIMRuntimeConfigStatus      `json:"status,omitempty"`
}

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

type AIMClusterRuntimeConfigSpec struct {
	AIMRuntimeConfigCommon `json:",inline"`
}

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

	Spec   AIMClusterServiceTemplateSpec `json:"spec,omitempty"`
	Status AIMServiceTemplateStatus      `json:"status,omitempty"`
}

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

type AIMClusterServiceTemplateSpec struct {
	AIMServiceTemplateSpecCommon `json:",inline"`
}

type AIMCpuRequirements struct {
	// Requests is the number of CPU cores to request. Required and must be > 0.
	// +required
	Requests resource.Quantity `json:"requests"`

	// Limits is the maximum number of CPU cores to allow.
	// +optional
	Limits *resource.Quantity `json:"limits,omitempty"`
}

type AIMCustomModelSpec struct {
	// Hardware specifies default hardware requirements for all templates.
	// Individual templates can override these defaults.
	// Required when modelSources is set and customTemplates is empty.
	// +optional
	Hardware *AIMHardwareRequirements `json:"hardware,omitempty"`

	// Type specifies default type for all templates.
	// Individual templates can override this default.
	// When nil, templates default to "unoptimized".
	// +optional
	// +kubebuilder:validation:Enum=optimized;preview;unoptimized
	Type *AIMProfileType `json:"type,omitempty"`
}

type AIMCustomTemplate struct {
	// Name is the template name. If not provided, auto-generated from model name + profile.
	// +optional
	// +kubebuilder:validation:MaxLength=63
	Name string `json:"name,omitempty"`

	// Type indicates the optimization status of this template.
	// - optimized: Template has been tuned for performance
	// - preview: Template is experimental/pre-release
	// - unoptimized: Default, no specific optimizations applied
	// +optional
	// +kubebuilder:validation:Enum=optimized;preview;unoptimized
	// +kubebuilder:default=unoptimized
	Type AIMProfileType `json:"type,omitempty"`

	// Env specifies environment variable overrides when this template is selected.
	// +optional
	// +listType=map
	// +listMapKey=name
	// +kubebuilder:validation:MaxItems=64
	Env []corev1.EnvVar `json:"env,omitempty"`

	// Hardware specifies GPU and CPU requirements for this template.
	// Optional when spec.hardware is set (inherits from spec).
	// When both are set, values are merged field-by-field with template taking precedence.
	// +optional
	Hardware *AIMHardwareRequirements `json:"hardware,omitempty"`

	// Profile declares runtime profile variables for template selection.
	// Used when multiple templates exist to select based on metric/precision.
	// +optional
	Profile *AIMTemplateProfile `json:"profile,omitempty"`
}

type AIMDiscoveryProfile struct {
	// EngineArgs contains runtime-specific engine configuration as a free-form JSON object.
	// The structure depends on the inference engine being used (e.g., vLLM, TGI).
	// These arguments are passed to the runtime container to configure model loading and inference.
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Schemaless
	EngineArgs *apiextensionsv1.JSON `json:"engine_args,omitempty"`

	// EnvVars contains environment variables required by the runtime for this profile.
	// These may include engine-specific settings, optimization flags, or hardware configuration.
	// +optional
	EnvVars map[string]string `json:"env_vars,omitempty"`

	// Metadata provides structured information about this deployment profile's characteristics.
	Metadata AIMDiscoveryProfileMetadata `json:"metadata,omitempty"`
}

type AIMDiscoveryProfileMetadata struct {
	// Engine identifies the inference engine used for this profile (e.g., "vllm", "tgi").
	// +optional
	Engine string `json:"engine,omitempty"`

	// GPU specifies the GPU model this profile is optimized for (e.g., "MI300X", "MI325X").
	// +optional
	GPU string `json:"gpu,omitempty"`

	// GPUCount indicates how many GPUs are required per replica for this profile.
	// +optional
	GPUCount int32 `json:"gpu_count,omitempty"`

	// Metric indicates the optimization goal for this profile ("latency" or "throughput").
	// +optional
	Metric AIMMetric `json:"metric,omitempty"`

	// Precision specifies the numeric precision used in this profile (e.g., "fp16", "fp8").
	// +optional
	Precision AIMPrecision `json:"precision,omitempty"`

	// Type specifies the optimization level of this profile (optimized, unoptimized, preview).
	// +optional
	Type AIMProfileType `json:"type,omitempty"`
}

type AIMGpuRequirements struct {
	// Requests is the number of GPUs to set as requests/limits.
	// Set to 0 to target GPU nodes without consuming GPU resources (useful for testing).
	// +optional
	// +kubebuilder:validation:Minimum=0
	Requests int32 `json:"requests,omitempty"`

	// Model limits deployment to a specific GPU model.
	// Example: "MI300X"
	// Cannot be combined with minVram.
	// +optional
	// +kubebuilder:validation:MaxLength=64
	Model string `json:"model,omitempty"`

	// MinVRAM limits deployment to GPUs having at least this much VRAM.
	// Used for capacity planning when the model size is known but any GPU with
	// sufficient VRAM is acceptable.
	// Cannot be combined with model.
	// +optional
	MinVRAM *resource.Quantity `json:"minVram,omitempty"`

	// ResourceName is the Kubernetes resource name for GPU resources.
	// Defaults to "amd.com/gpu" if not specified.
	// +optional
	// +kubebuilder:default="amd.com/gpu"
	ResourceName string `json:"resourceName,omitempty"`
}

type AIMHardwareRequirements struct {
	// GPU specifies GPU requirements. If not set, no GPUs are requested (CPU-only model).
	// +optional
	GPU *AIMGpuRequirements `json:"gpu,omitempty"`

	// CPU specifies CPU requirements.
	// +optional
	CPU *AIMCpuRequirements `json:"cpu,omitempty"`
}

type AIMMetric string

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

	Spec   AIMModelSpec   `json:"spec,omitempty"`
	Status AIMModelStatus `json:"status,omitempty"`
}

type AIMModelConfig struct {
	// AutoDiscovery controls whether models run discovery by default.
	// When true, models run discovery jobs to extract metadata and auto-create templates.
	// When false, discovery is skipped. Discovery failures are non-fatal and reported via conditions.
	// +optional
	AutoDiscovery *bool `json:"autoDiscovery,omitempty"`
}

type AIMModelDiscoveryConfig struct {
	// ExtractMetadata controls whether metadata extraction runs for this model.
	// During metadata extraction, the controller connects to the image registry and
	// extracts the image's labels.
	// +optional
	// +kubebuilder:default=true
	ExtractMetadata bool `json:"extractMetadata,omitempty"`

	// CreateServiceTemplates controls whether (cluster) service templates are auto-created from the image metadata.
	// +optional
	// +kubebuilder:default=true
	CreateServiceTemplates bool `json:"createServiceTemplates,omitempty"`
}

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

type AIMModelSource struct {
	// ModelID is the canonical identifier in {org}/{name} format.
	// Determines the cache mount path: /workspace/cache/{modelId}
	// For HuggingFace sources, this typically mirrors the URI path (e.g., meta-llama/Llama-3-8B).
	// For S3 sources, users define their own organizational structure.
	// +required
	// +kubebuilder:validation:Pattern=`^[a-zA-Z0-9_-]+/[a-zA-Z0-9._-]+$`
	ModelID string `json:"modelId"`

	// SourceURI is the location from which the model should be downloaded.
	// Supported schemes:
	// - hf://org/model - Hugging Face Hub model
	// - s3://bucket/key - S3-compatible storage
	// +kubebuilder:validation:Pattern=`^(hf|s3)://[^ \t\r\n]+$`
	SourceURI string `json:"sourceUri"`

	// Size is the expected storage space required for this model artifact.
	// Used for PVC sizing and capacity planning during cache creation.
	// Optional - if not specified, the download job will discover the size automatically.
	// Can be set explicitly to pre-allocate storage or override auto-discovery.
	// +optional
	Size *resource.Quantity `json:"size,omitempty"`

	// Env specifies per-source credential overrides.
	// These variables are used for authentication when downloading this specific source.
	// Takes precedence over base-level env for the same variable name.
	// +optional
	// +listType=map
	// +listMapKey=name
	Env []corev1.EnvVar `json:"env,omitempty"`
}

type AIMModelSourceType string

type AIMModelSpec struct {
	// Image is the container image URI for this AIM model.
	// This image is inspected by the operator to select runtime profiles used by templates.
	// Discovery behavior is controlled by the discovery field and runtime config's AutoDiscovery setting.
	// +kubebuilder:validation:MinLength=1
	Image string `json:"image"`

	// Discovery controls discovery behavior for this model.
	// When unset, uses runtime config defaults.
	// +optional
	Discovery *AIMModelDiscoveryConfig `json:"discovery,omitempty"`

	// DefaultServiceTemplate specifies the default AIMServiceTemplate to use when creating services for this model.
	// When set, services that reference this model will use this template if no template is explicitly specified.
	// If this is not set, a template will be automatically selected.
	// +optional
	DefaultServiceTemplate string `json:"defaultServiceTemplate,omitempty"`

	// Custom contains configuration for custom models (models with inline modelSources).
	// Only used when modelSources are specified; ignored for image-based models.
	// +optional
	Custom *AIMCustomModelSpec `json:"custom,omitempty"`

	// CustomTemplates defines explicit template configurations for this model.
	// These templates are created directly without running a discovery job.
	// Can be used with or without modelSources to define custom deployment configurations.
	// If omitted when modelSources is set, a single template is auto-generated
	// using the custom.hardware requirements.
	// +optional
	// +kubebuilder:validation:MaxItems=16
	CustomTemplates []AIMCustomTemplate `json:"customTemplates,omitempty"`

	// ModelSources specifies the model sources to use for this model.
	// When specified, these sources are used instead of auto-discovery from the container image.
	// This enables pre-creating custom models with explicit model sources.
	// The size field is optional - if not specified, it will be discovered by the download job.
	// AIM runtime currently supports only one model source.
	// +optional
	// +kubebuilder:validation:MaxItems=1
	ModelSources []AIMModelSource `json:"modelSources,omitempty"`

	// RuntimeConfigRef contains the runtime config reference for this model, and is used to control discovery behavior.
	RuntimeConfigRef `json:",inline"`

	// ImagePullSecrets lists secrets containing credentials for pulling the model container image.
	// These secrets are used for:
	// - OCI registry metadata extraction during discovery
	// - Pulling the image for inference services
	// The secrets are merged with any runtime config defaults.
	// For namespace-scoped models, secrets must exist in the same namespace.
	// For cluster-scoped models, secrets must exist in the operator namespace.
	// +optional
	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`

	// Env specifies environment variables for authentication during model discovery and metadata extraction.
	// These variables are used for authentication with model registries (e.g., HuggingFace tokens).
	// +optional
	// +listType=map
	// +listMapKey=name
	Env []corev1.EnvVar `json:"env,omitempty"`

	// ServiceAccountName specifies the Kubernetes service account to use for workloads related to this model.
	// This includes metadata extraction jobs and any other model-related operations.
	// If empty, the default service account for the namespace is used.
	// +optional
	ServiceAccountName string `json:"serviceAccountName,omitempty"`

	// Resources defines the default resource requirements for services using this model.
	// Template- or service-level values override these defaults.
	// +optional
	Resources corev1.ResourceRequirements `json:"resources,omitempty"`

	// ImageMetadata is the metadata that is used to determine which recommended service templates to create,
	// and to drive clients with richer metadata regarding this particular model. For most cases the user does
	// not need to set this field manually, for images that have the supported labels embedded in them
	// the `AIM(Cluster)Model.status.imageMetadata` field is automatically filled from the container image labels.
	// This field is intended to be used when there are network restrictions, or in other similar situations.
	// If this field is set, the remote extraction will not be performed at all.
	ImageMetadata *ImageMetadata `json:"imageMetadata,omitempty"`
}

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

	// Status represents the overall status of the image based on its templates
	// +kubebuilder:default=Pending
	// +kubebuilder:validation:Enum=Pending;Progressing;Ready;Degraded;Failed;NotAvailable
	Status constants.AIMStatus `json:"status,omitempty"`

	// Conditions represent the latest available observations of the model's state
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// ResolvedRuntimeConfig captures metadata about the runtime config that was resolved.
	// +optional
	ResolvedRuntimeConfig *AIMResolvedReference `json:"resolvedRuntimeConfig,omitempty"`

	// ImageMetadata is the metadata extracted from an AIM image
	// +optional
	ImageMetadata *ImageMetadata `json:"imageMetadata,omitempty"`

	// SourceType indicates how this model's artifacts are sourced.
	// - "Image": Model discovered from container image labels
	// - "Custom": Model uses explicit spec.modelSources
	// Set by the controller based on whether spec.modelSources is populated.
	// +optional
	SourceType AIMModelSourceType `json:"sourceType,omitempty"`
}

type AIMPrecision string

type AIMProfile struct {
	// EngineArgs contains runtime-specific engine configuration as a free-form JSON object.
	// The structure depends on the inference engine being used (e.g., vLLM, TGI).
	// These arguments are passed to the runtime container to configure model loading and inference.
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Schemaless
	EngineArgs *apiextensionsv1.JSON `json:"engine_args,omitempty"`

	// EnvVars contains environment variables required by the runtime for this profile.
	// These may include engine-specific settings, optimization flags, or hardware configuration.
	// +optional
	EnvVars map[string]string `json:"env_vars,omitempty"`

	// Metadata provides structured information about this deployment profile's characteristics.
	Metadata AIMProfileMetadata `json:"metadata,omitempty"`

	// OriginalDiscoveryOutput contains the raw discovery job JSON output.
	// This preserves the complete discovery result from the dry-run container,
	// including all fields that may not be mapped to structured fields above.
	// +kubebuilder:pruning:PreserveUnknownFields
	// +kubebuilder:validation:Schemaless
	// +optional
	OriginalDiscoveryOutput *apiextensionsv1.JSON `json:"originalDiscoveryOutput,omitempty"`
}

type AIMProfileMetadata struct {
	// Engine identifies the inference engine used for this profile (e.g., "vllm", "tgi").
	// +optional
	Engine string `json:"engine,omitempty"`

	// GPU specifies the GPU model this profile is optimized for (e.g., "MI300X", "MI325X").
	// +optional
	GPU string `json:"gpu,omitempty"`

	// GPUCount indicates how many GPUs are required per replica for this profile.
	// +optional
	GPUCount int32 `json:"gpuCount,omitempty"`

	// Metric indicates the optimization goal for this profile ("latency" or "throughput").
	// +optional
	Metric AIMMetric `json:"metric,omitempty"`

	// Precision specifies the numeric precision used in this profile (e.g., "fp16", "fp8").
	// +optional
	Precision AIMPrecision `json:"precision,omitempty"`

	// Type indicates the optimization level of this profile (optimized, preview, unoptimized).
	// +optional
	Type AIMProfileType `json:"type,omitempty"`
}

type AIMProfileType string

type AIMResolutionScope string

type AIMResolvedArtifact struct {
	// UID of the AIMArtifact resource
	UID string `json:"uid"`
	// Name of the AIMArtifact resource
	Name string `json:"name"`
	// Model is the name of the model that is cached
	Model string `json:"model"`
	// Status of the artifact
	Status constants.AIMStatus `json:"status"`
	// PersistentVolumeClaim name if available
	PersistentVolumeClaim string `json:"persistentVolumeClaim,omitempty"`
	// MountPoint is the mount point for the artifact
	MountPoint string `json:"mountPoint,omitempty"`
}

type AIMResolvedReference struct {
	// Name is the resource name that satisfied the reference.
	Name string `json:"name,omitempty"`

	// Namespace identifies where the resource was found when namespace-scoped.
	// Empty indicates a cluster-scoped resource.
	Namespace string `json:"namespace,omitempty"`

	// Scope indicates whether the resolved resource was namespace or cluster scoped.
	Scope AIMResolutionScope `json:"scope,omitempty"`

	// Kind is the fully-qualified kind of the resolved reference, when known.
	// +optional
	Kind string `json:"kind,omitempty"`

	// UID captures the unique identifier of the resolved reference, when known.
	// +optional
	UID types.UID `json:"uid,omitempty"`
}

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

	Spec   AIMRuntimeConfigSpec   `json:"spec,omitempty"`
	Status AIMRuntimeConfigStatus `json:"status,omitempty"`
}

type AIMRuntimeConfigCommon struct {
	AIMServiceRuntimeConfig `json:",inline"`

	// Model controls model creation and discovery defaults.
	// This field only applies to RuntimeConfig/ClusterRuntimeConfig and is not available for services.
	// +optional
	Model *AIMModelConfig `json:"model,omitempty"`

	// LabelPropagation controls how labels from parent AIM resources are propagated to child resources.
	// When enabled, labels matching the specified patterns are automatically copied from parent resources
	// (e.g., AIMService, AIMTemplateCache) to their child resources (e.g., Deployments, Services, PVCs).
	// This is useful for propagating organizational metadata like cost centers, team identifiers,
	// or compliance labels through the resource hierarchy.
	// +optional
	LabelPropagation *AIMRuntimeConfigLabelPropagationSpec `json:"labelPropagation,omitempty"`

	// DEPRECATED: Use Storage.DefaultStorageClassName instead. This field will be removed in a future version.
	// For backward compatibility, if this field is set and Storage.DefaultStorageClassName is not set,
	// the value will be automatically migrated.
	// +optional
	// +kubebuilder:validation:Deprecated
	// +kubebuilder:validation:DeprecatedMessage="Use Storage.DefaultStorageClassName instead. This field will be removed in a future version."
	DefaultStorageClassName string `json:"defaultStorageClassName,omitempty"`

	// DEPRECATED: Use Storage.PVCHeadroomPercent instead. This field will be removed in a future version.
	// For backward compatibility, if this field is set and Storage.PVCHeadroomPercent is not set,
	// the value will be automatically migrated.
	// +optional
	// +kubebuilder:validation:Deprecated
	// +kubebuilder:validation:DeprecatedMessage="Use Storage.PVCHeadroomPercent instead. This field will be removed in a future version."
	PVCHeadroomPercent *int32 `json:"pvcHeadroomPercent,omitempty"`
}

type AIMRuntimeConfigLabelPropagationSpec struct {
	// Enabled, if true, allows propagating parent labels to all child resources it creates directly
	// Only label keys that match the ones in Match are propagated.
	// +kubebuilder:default=false
	// +optional
	Enabled bool `json:"enabled,omitempty"`

	// Match is a list of label keys that will be propagated to any child resources created.
	// Wildcards are supported, so for example `org.my/my-key-*` would match any label with that prefix.
	// +optional
	Match []string `json:"match,omitempty"`
}

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

type AIMRuntimeConfigSpec struct {
	AIMRuntimeConfigCommon `json:",inline"`
}

type AIMRuntimeConfigStatus struct {
	// ObservedGeneration is the last reconciled generation.
	ObservedGeneration int64 `json:"observedGeneration,omitempty"`

	// Conditions communicate reconciliation progress.
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`
}

type AIMRuntimeParameters struct {
	// Metric selects the optimization goal.
	//
	// - `latency`: prioritize low end‑to‑end latency
	// - `throughput`: prioritize sustained requests/second
	//
	// +optional
	// +kubebuilder:validation:Enum=latency;throughput
	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="metric is immutable"
	Metric *AIMMetric `json:"metric,omitempty"`

	// Precision selects the numeric precision used by the runtime.
	// +optional
	// +kubebuilder:validation:Enum=auto;fp4;fp8;fp16;fp32;bf16;int4;int8
	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="precision is immutable"
	Precision *AIMPrecision `json:"precision,omitempty"`

	// Hardware specifies GPU and CPU requirements for each replica.
	// For GPU models, defines the GPU count and model types required for deployment.
	// For CPU-only models, defines CPU resource requirements.
	// This field is immutable after creation.
	// +optional
	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="hardware is immutable"
	Hardware *AIMHardwareRequirements `json:"hardware,omitempty"`
}

type AIMRuntimeRoutingConfig struct {
	// Enabled controls whether HTTP routing is managed for inference services using this config.
	// When true, the operator creates HTTPRoute resources for services that reference this config.
	// When false or unset, routing must be explicitly enabled on each service.
	// This provides a namespace or cluster-wide default that individual services can override.
	// +optional
	Enabled *bool `json:"enabled,omitempty"`

	// GatewayRef specifies the Gateway API Gateway resource that should receive HTTPRoutes.
	// This identifies the parent gateway for routing traffic to inference services.
	// The gateway can be in any namespace (cross-namespace references are supported).
	// If routing is enabled but GatewayRef is not specified, service reconciliation will fail
	// with a validation error.
	// +optional
	GatewayRef *gatewayapiv1.ParentReference `json:"gatewayRef,omitempty"`

	// PathTemplate defines the HTTP path template for routes, evaluated using JSONPath expressions.
	// The template is rendered against the AIMService object to generate unique paths.
	//
	// Example templates:
	// - `/{.metadata.namespace}/{.metadata.name}` - namespace and service name
	// - `/{.metadata.namespace}/{.metadata.labels['team']}/inference` - with label
	// - `/models/{.metadata.name}` - based on service name
	//
	// The template must:
	// - Use valid JSONPath expressions wrapped in {...}
	// - Reference fields that exist on the service
	// - Produce a path ≤ 200 characters after rendering
	// - Result in valid URL path segments (lowercase, RFC 1123 compliant)
	//
	// If evaluation fails, the service enters Degraded state with PathTemplateInvalid reason.
	// Individual services can override this template via spec.routing.pathTemplate.
	// +optional
	PathTemplate *string `json:"pathTemplate,omitempty"`

	// RequestTimeout defines the HTTP request timeout for routes.
	// This sets the maximum duration for a request to complete before timing out.
	// The timeout applies to the entire request/response cycle.
	// If not specified, no timeout is set on the route.
	// Individual services can override this value via spec.routing.requestTimeout.
	// +optional
	RequestTimeout *metav1.Duration `json:"requestTimeout,omitempty"`

	// Annotations defines default annotations to add to all HTTPRoute resources.
	// Services can add additional annotations or override these via spec.routingAnnotations.
	// When both are specified, service annotations take precedence for conflicting keys.
	// Common use cases include ingress controller settings, rate limiting, monitoring labels,
	// and security policies that should apply to all services using this config.
	// +optional
	Annotations map[string]string `json:"annotations,omitempty"`
}

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

	Spec   AIMServiceSpec   `json:"spec,omitempty"`
	Status AIMServiceStatus `json:"status,omitempty"`
}

type AIMServiceAutoScaling struct {
	// Metrics is a list of metrics to be used for autoscaling.
	// Each metric defines a source (PodMetric) and target values.
	// +optional
	Metrics []AIMServiceMetricsSpec `json:"metrics,omitempty"`
}

type AIMServiceCacheStatus struct {
	// TemplateCacheRef references the TemplateCache being used, if any.
	// +optional
	TemplateCacheRef *AIMResolvedReference `json:"templateCacheRef,omitempty"`

	// RetryAttempts tracks how many times this service has attempted to retry a failed cache.
	// Each service gets exactly one retry attempt. When a TemplateCache enters Failed state,
	// this counter is incremented from 0 to 1 after deleting failed Artifacts.
	// If the retry fails (cache enters Failed again with attempts == 1), the service degrades.
	// +optional
	RetryAttempts int `json:"retryAttempts,omitempty"`
}

type AIMServiceCachingConfig struct {
	// Mode controls when to use caching.
	// Canonical values:
	// - Shared (default): reuse/create shared cache assets
	// - Dedicated: create service-owned dedicated cache assets
	//
	// Legacy values are accepted and normalized:
	// - Always -> Shared
	// - Auto -> Shared
	// - Never -> Dedicated
	// +kubebuilder:default=Shared
	// +optional
	Mode AIMCachingMode `json:"mode,omitempty"`
}

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

type AIMServiceMetricTarget struct {
	// Type specifies how to interpret the metric value.
	// "Value": absolute value target (use Value field)
	// "AverageValue": average value across all pods (use AverageValue field)
	// "Utilization": percentage utilization for resource metrics (use AverageUtilization field)
	// +kubebuilder:validation:Enum=Value;AverageValue;Utilization
	Type string `json:"type"`

	// Value is the target value of the metric (as a quantity).
	// Used when Type is "Value".
	// Example: "1" for 1 request, "100m" for 100 millicores
	// +optional
	Value string `json:"value,omitempty"`

	// AverageValue is the target value of the average of the metric across all relevant pods (as a quantity).
	// Used when Type is "AverageValue".
	// Example: "100m" for 100 millicores per pod
	// +optional
	AverageValue string `json:"averageValue,omitempty"`

	// AverageUtilization is the target value of the average of the resource metric across all relevant pods,
	// represented as a percentage of the requested value of the resource for the pods.
	// Used when Type is "Utilization". Only valid for Resource metric source type.
	// Example: 80 for 80% utilization
	// +optional
	AverageUtilization *int32 `json:"averageUtilization,omitempty"`
}

type AIMServiceMetricsSpec struct {
	// Type is the type of metric source.
	// Valid values: "PodMetric" (per-pod custom metrics).
	// +kubebuilder:validation:Enum=PodMetric
	Type string `json:"type"`

	// PodMetric refers to a metric describing each pod in the current scale target.
	// Used when Type is "PodMetric". Supports backends like OpenTelemetry for custom metrics.
	// +optional
	PodMetric *AIMServicePodMetricSource `json:"podmetric,omitempty"`
}

type AIMServiceModel struct {
	// Name references an existing AIMModel or AIMClusterModel by metadata.name.
	// The controller looks for a namespace-scoped AIMModel first, then falls back to cluster-scoped AIMClusterModel.
	// Example: `meta-llama-3-8b`
	// +optional
	Name *string `json:"name,omitempty"`

	// Image specifies a container image URI directly.
	// The controller searches for an existing model with this image, or creates one if none exists.
	// Auto-created models are namespace-scoped and can be reused by other services.
	// Example: `ghcr.io/silogen/llama-3-8b:v1.2.0`
	// +optional
	Image *string `json:"image,omitempty"`

	// Custom specifies a custom model configuration with explicit base image,
	// model sources, and hardware requirements. The controller will search for
	// an existing matching AIMModel or auto-create one if not found.
	// +optional
	Custom *AIMServiceModelCustom `json:"custom,omitempty"`
}

type AIMServiceModelCustom struct {
	// BaseImage is the container image URI for the AIM base image.
	// This will be used as the image for the auto-created AIMModel.
	// Example: `ghcr.io/silogen/aim-base:0.7.0`
	// +required
	BaseImage string `json:"baseImage"`

	// ModelSources specifies the model sources to use.
	// The controller will search for or create an AIMModel with these sources.
	// The size field is optional - if not specified, it will be discovered by the download job.
	// AIM runtime currently supports only one model source.
	// +required
	// +kubebuilder:validation:MinItems=1
	// +kubebuilder:validation:MaxItems=1
	ModelSources []AIMModelSource `json:"modelSources"`

	// Hardware specifies the GPU and CPU requirements for this custom model.
	// GPU is optional - if not set, no GPUs are requested (CPU-only model).
	// +required
	Hardware AIMHardwareRequirements `json:"hardware"`
}

type AIMServiceOverrides struct {
	AIMRuntimeParameters `json:",inline"`
}

type AIMServicePodMetric struct {
	// Backend defines the metrics backend to use.
	// If not specified, defaults to "opentelemetry".
	// +kubebuilder:validation:Enum=opentelemetry
	// +kubebuilder:default=opentelemetry
	// +optional
	Backend string `json:"backend,omitempty"`

	// ServerAddress specifies the address of the metrics backend server.
	// If not specified, defaults to "keda-otel-scaler.keda.svc:4317" for OpenTelemetry backend.
	// +optional
	ServerAddress string `json:"serverAddress,omitempty"`

	// MetricNames specifies which metrics to collect from pods and send to ServerAddress.
	// Example: ["vllm:num_requests_running"]
	// +optional
	MetricNames []string `json:"metricNames,omitempty"`

	// Query specifies the query to run to retrieve metrics from the backend.
	// The query syntax depends on the backend being used.
	// Example: "vllm:num_requests_running" for OpenTelemetry.
	// +optional
	Query string `json:"query,omitempty"`

	// OperationOverTime specifies the operation to aggregate metrics over time.
	// Valid values: "last_one", "avg", "max", "min", "rate", "count"
	// Default: "last_one"
	// +optional
	OperationOverTime string `json:"operationOverTime,omitempty"`
}

type AIMServicePodMetricSource struct {
	// Metric contains the metric identification and backend configuration.
	// Defines which metrics to collect and how to query them.
	Metric *AIMServicePodMetric `json:"metric"`

	// Target specifies the target value for the metric.
	// The autoscaler will scale to maintain this target value.
	Target *AIMServiceMetricTarget `json:"target"`
}

type AIMServiceRoutingStatus struct {
	// Path is the HTTP path prefix used when routing is enabled.
	// Example: `/tenant/svc-uuid`
	// +optional
	Path string `json:"path,omitempty"`
}

type AIMServiceRuntimeConfig struct {
	// Storage configures storage defaults for this service's PVCs and caches.
	// When set, these values override namespace/cluster runtime config defaults.
	// +optional
	Storage *AIMStorageConfig `json:"storage,omitempty"`

	// Routing controls HTTP routing configuration for this service.
	// When set, these values override namespace/cluster runtime config defaults.
	// +optional
	Routing *AIMRuntimeRoutingConfig `json:"routing,omitempty"`

	// Env specifies environment variables for inference containers.
	// When set on AIMService, these take highest precedence in the merge hierarchy.
	// When set on RuntimeConfig, these provide namespace/cluster-level defaults.
	// Merge order (highest to lowest): Service.Env > Template.Env > RuntimeConfig.Env > Profile.Env
	// +optional
	// +listType=map
	// +listMapKey=name
	Env []corev1.EnvVar `json:"env,omitempty"`
}

type AIMServiceRuntimeStatus struct {
	// CurrentReplicas is the current number of replicas as reported by the HPA.
	// +optional
	CurrentReplicas int32 `json:"currentReplicas,omitempty"`

	// DesiredReplicas is the desired number of replicas as determined by the HPA.
	// +optional
	DesiredReplicas int32 `json:"desiredReplicas,omitempty"`

	// MinReplicas is the minimum number of replicas configured for autoscaling.
	// +optional
	MinReplicas int32 `json:"minReplicas,omitempty"`

	// MaxReplicas is the maximum number of replicas configured for autoscaling.
	// +optional
	MaxReplicas int32 `json:"maxReplicas,omitempty"`

	// Replicas is a formatted display string for kubectl output.
	// Shows "current" for fixed replicas or "current/desired (min-max)" for autoscaling.
	// +optional
	Replicas string `json:"replicas,omitempty"`
}

type AIMServiceSpec struct {
	// Model specifies which model to deploy using one of the available reference methods.
	// Use `name` to reference an existing AIMModel/AIMClusterModel by name, or use `image`
	// to specify a container image URI directly (which will auto-create a model if needed).
	Model AIMServiceModel `json:"model"`

	// Template contains template selection and configuration.
	// Use Template.Name to specify an explicit template, or omit to auto-select.
	// +optional
	Template AIMServiceTemplateConfig `json:"template,omitempty"`

	// Caching controls caching behavior for this service.
	// When nil, defaults to Shared mode.
	// +optional
	Caching *AIMServiceCachingConfig `json:"caching,omitempty"`

	// DEPRECATED: Use Caching.Mode instead. This field will be removed in a future version.
	// This field is no longer honored by the controller.
	// +optional
	// +kubebuilder:validation:Deprecated
	// +kubebuilder:validation:DeprecatedMessage="Use Caching.Mode instead. This field will be removed in a future version."
	CacheModel *bool `json:"cacheModel,omitempty"`

	// Replicas specifies the number of replicas for this service.
	// When not specified, defaults to 1 replica.
	// This value overrides any replica settings from the template.
	// For autoscaling, use MinReplicas and MaxReplicas instead.
	// +optional
	// +kubebuilder:default=1
	Replicas *int32 `json:"replicas,omitempty"`

	// MinReplicas specifies the minimum number of replicas for autoscaling.
	// Defaults to 1. Scale to zero is not supported.
	// When specified with MaxReplicas, enables autoscaling for the service.
	// +optional
	// +kubebuilder:validation:Minimum=1
	MinReplicas *int32 `json:"minReplicas,omitempty"`

	// MaxReplicas specifies the maximum number of replicas for autoscaling.
	// Required when MinReplicas is set or when AutoScaling configuration is provided.
	// +optional
	// +kubebuilder:validation:Minimum=1
	MaxReplicas *int32 `json:"maxReplicas,omitempty"`

	// AutoScaling configures advanced autoscaling behavior using KEDA.
	// Supports custom metrics from OpenTelemetry backend.
	// When specified, MinReplicas and MaxReplicas should also be set.
	// +optional
	AutoScaling *AIMServiceAutoScaling `json:"autoScaling,omitempty"`

	// RuntimeConfigRef contains the runtime config reference for this service.
	// The result of the merged runtime configs is merged with the inline AIMServiceRuntimeConfig configuration.
	RuntimeConfigRef `json:",inline"`

	// Inline AIMServiceRuntimeConfig fields for cleaner access
	AIMServiceRuntimeConfig `json:",inline"`

	// Resources overrides the container resource requirements for this service.
	// When specified, these values take precedence over the template and image defaults.
	// +optional
	Resources *corev1.ResourceRequirements `json:"resources,omitempty"`

	// Overrides allows overriding specific template parameters for this service.
	// When specified, these values take precedence over the template values.
	// +optional
	Overrides *AIMServiceOverrides `json:"overrides,omitempty"`

	// ImagePullSecrets references secrets for pulling AIM container images.
	// +optional
	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`

	// ServiceAccountName specifies the Kubernetes service account to use for the inference workload.
	// This service account is used by the deployed inference pods.
	// If empty, the default service account for the namespace is used.
	// +optional
	ServiceAccountName string `json:"serviceAccountName,omitempty"`
}

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

	// Conditions represent the latest observations of template state.
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// ResolvedRuntimeConfig captures metadata about the runtime config that was resolved.
	// +optional
	ResolvedRuntimeConfig *AIMResolvedReference `json:"resolvedRuntimeConfig,omitempty"`

	// ResolvedModel captures metadata about the image that was resolved.
	// +optional
	ResolvedModel *AIMResolvedReference `json:"resolvedModel,omitempty"`

	// Status represents the current high‑level status of the service lifecycle.
	// Values: `Pending`, `Starting`, `Running`, `Degraded`, `Failed`.
	// +kubebuilder:default=Pending
	// +kubebuilder:validation:Enum=Pending;Starting;Running;Degraded;Failed
	Status constants.AIMStatus `json:"status,omitempty"`

	// Routing surfaces information about the configured HTTP routing, when enabled.
	// +optional
	Routing *AIMServiceRoutingStatus `json:"routing,omitempty"`

	// ResolvedTemplate captures metadata about the template that satisfied the reference.
	ResolvedTemplate *AIMResolvedReference `json:"resolvedTemplate,omitempty"`

	// Cache captures cache-related status for this service.
	// +optional
	Cache *AIMServiceCacheStatus `json:"cache,omitempty"`

	// Runtime captures runtime status including replica counts.
	// +optional
	Runtime *AIMServiceRuntimeStatus `json:"runtime,omitempty"`
}

type AIMServiceStatusEnum string

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

	Spec   AIMServiceTemplateSpec   `json:"spec,omitempty"`
	Status AIMServiceTemplateStatus `json:"status,omitempty"`
}

type AIMServiceTemplateConfig struct {
	// Name is the name of the AIMServiceTemplate or AIMClusterServiceTemplate to use.
	// The template selects the runtime profile and GPU parameters.
	// When not specified, a template will be automatically selected based on the model.
	// +optional
	Name string `json:"name,omitempty"`

	// AllowUnoptimized, if true, will allow automatic selection of templates
	// that resolve to an unoptimized profile.
	// +optional
	AllowUnoptimized bool `json:"allowUnoptimized,omitempty"`
}

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

type AIMServiceTemplateScope string

type AIMServiceTemplateSpec struct {
	AIMServiceTemplateSpecCommon `json:",inline"`

	// Caching configures model caching behavior for this namespace-scoped template.
	// When enabled, models will be cached using the specified environment variables
	// during download.
	// +optional
	Caching *AIMTemplateCachingConfig `json:"caching,omitempty"`
}

type AIMServiceTemplateSpecCommon struct {
	// ModelName is the model name. Matches `metadata.name` of an AIMModel or AIMClusterModel. Immutable.
	//
	// Example: `meta/llama-3-8b:1.1+20240915`
	//
	// +kubebuilder:validation:MinLength=1
	// +kubebuilder:validation:XValidation:rule="self == oldSelf",message="model name is immutable"
	ModelName string `json:"modelName"`

	AIMRuntimeParameters `json:",inline"`

	// RuntimeConfigRef contains the runtime config reference for this service template
	RuntimeConfigRef `json:",inline"`

	// ImagePullSecrets lists secrets containing credentials for pulling container images.
	// These secrets are used for:
	// - Discovery dry-run jobs that inspect the model container
	// - Pulling the image for inference services
	// The secrets are merged with any model or runtime config defaults.
	// For namespace-scoped templates, secrets must exist in the same namespace.
	// For cluster-scoped templates, secrets must exist in the operator namespace.
	// +optional
	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`

	// ServiceAccountName specifies the Kubernetes service account to use for workloads related to this template.
	// This includes discovery dry-run jobs and inference services created from this template.
	// If empty, the default service account for the namespace is used.
	// +optional
	ServiceAccountName string `json:"serviceAccountName,omitempty"`

	// Resources defines the default container resource requirements applied to services derived from this template.
	// Service-specific values override the template defaults.
	// +optional
	Resources *corev1.ResourceRequirements `json:"resources,omitempty"`

	// ModelSources specifies the model sources required to run this template.
	// When provided, the discovery dry-run will be skipped and these sources will be used directly.
	// This allows users to explicitly declare model dependencies without requiring a discovery job.
	// If omitted, a discovery job will be run to automatically determine the required model sources.
	// +optional
	ModelSources []AIMModelSource `json:"modelSources,omitempty"`

	// ProfileId is the specific AIM profile ID that this template should use.
	// When set, the discovery job will be instructed to use this specific profile.
	// +optional
	ProfileId string `json:"profileId,omitempty"`

	// Type indicates the optimization level of this template.
	// - optimized: Template has been tuned for performance
	// - preview: Template is experimental/pre-release
	// - unoptimized: Default, no specific optimizations applied
	// When nil, the type is determined by discovery. When set, overrides discovery.
	// +optional
	// +kubebuilder:validation:Enum=optimized;preview;unoptimized
	Type *AIMProfileType `json:"type,omitempty"`

	// Env specifies environment variables for inference containers.
	// These variables are passed to the inference runtime and can be used
	// to configure runtime behavior, authentication, or other settings.
	// +optional
	// +listType=map
	// +listMapKey=name
	Env []corev1.EnvVar `json:"env,omitempty"`
}

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

	// Conditions represent the latest observations of template state.
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// ResolvedRuntimeConfig captures metadata about the runtime config that was resolved.
	// +optional
	ResolvedRuntimeConfig *AIMResolvedReference `json:"resolvedRuntimeConfig,omitempty"`

	// ResolvedModel captures metadata about the image that was resolved.
	// +optional
	ResolvedModel *AIMResolvedReference `json:"resolvedModel,omitempty"`

	// ResolvedCache captures metadata about which cache is used for this template
	// +optional
	ResolvedCache *AIMResolvedReference `json:"resolvedCache,omitempty"`

	// ResolvedHardware contains the resolved hardware requirements for this template.
	// These values are computed from discovery results and spec defaults, and represent
	// what will actually be used when creating InferenceServices.
	// Resolution order: discovery output > spec values > defaults.
	// +optional
	ResolvedHardware *AIMHardwareRequirements `json:"resolvedHardware,omitempty"`

	// ResolvedNodeAffinity contains the computed node affinity rules for GPU scheduling.
	// This is derived from GPU model and minVRAM requirements, merged with any user-specified
	// affinity from the spec. The service controller uses this directly when creating InferenceServices.
	// +optional
	ResolvedNodeAffinity *corev1.NodeAffinity `json:"resolvedNodeAffinity,omitempty"`

	// HardwareSummary is a human-readable display string for the hardware requirements.
	// Format: "{count} x {model}" for GPU (e.g., "2 x MI300X") or "CPU" for CPU-only.
	// This is a computed field for display purposes only.
	// +optional
	HardwareSummary string `json:"hardwareSummary,omitempty"`

	// Status represents the current high‑level status of the template lifecycle.
	// Values: `Pending`, `Progressing`, `Ready`, `Degraded`, `Failed`.
	// +kubebuilder:default=Pending
	// +kubebuilder:validation:Enum=Pending;Progressing;Ready;Degraded;Failed;NotAvailable
	Status constants.AIMStatus `json:"status,omitempty"`

	// ModelSources list the models that this template requires to run. These are the models that will be
	// cached, if this template is cached.
	ModelSources []AIMModelSource `json:"modelSources,omitempty"`

	// Profile contains the full discovery result profile as a free-form JSON object.
	// This includes metadata, engine args, environment variables, and model details.
	Profile *AIMProfile `json:"profile,omitempty"`

	// DiscoveryJob is a reference to the job that was run for discovery
	DiscoveryJob *AIMResolvedReference `json:"discoveryJob,omitempty"`

	// Discovery contains state tracking for the discovery process, including
	// retry attempts and backoff timing for the circuit breaker pattern.
	// +optional
	Discovery *DiscoveryState `json:"discovery,omitempty"`
}

type AIMStorageConfig struct {
	// DefaultStorageClassName specifies the storage class to use for artifacts and PVCs
	// when the consuming resource (AIMArtifact, AIMTemplateCache, AIMServiceTemplate) does not
	// specify a storage class. If this field is empty, the cluster's default storage class is used.
	// +optional
	DefaultStorageClassName *string `json:"defaultStorageClassName,omitempty"`

	// PVCHeadroomPercent specifies the percentage of extra space to add to PVCs
	// for model storage. This accounts for filesystem overhead and temporary files
	// during model loading. The value represents a percentage (e.g., 10 means 10% extra space).
	// If not specified, defaults to 10%.
	// +kubebuilder:default=10
	// +kubebuilder:validation:Minimum=0
	// +optional
	PVCHeadroomPercent *int32 `json:"pvcHeadroomPercent,omitempty"`
}

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

	Spec   AIMTemplateCacheSpec   `json:"spec,omitempty"`
	Status AIMTemplateCacheStatus `json:"status,omitempty"`
}

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

type AIMTemplateCacheMode string

type AIMTemplateCacheSpec struct {
	// TemplateName is the name of the AIMServiceTemplate or AIMClusterServiceTemplate to cache.
	// The controller will first look for a namespace-scoped AIMServiceTemplate in the same namespace.
	// If not found, it will look for a cluster-scoped AIMClusterServiceTemplate with the same name.
	// Namespace-scoped templates take priority over cluster-scoped templates.
	// +kubebuilder:validation:MinLength=1
	TemplateName string `json:"templateName"`

	// TemplateScope indicates whether the template is namespace-scoped or cluster-scoped.
	// This field is set by the controller during template resolution.
	// +required
	TemplateScope AIMServiceTemplateScope `json:"templateScope"`

	// Env specifies environment variables to use for authentication when downloading models.
	// These variables are used for authentication with model registries (e.g., HuggingFace tokens).
	// +optional
	// +listType=map
	// +listMapKey=name
	Env []corev1.EnvVar `json:"env,omitempty"`

	// ImagePullSecrets references secrets for pulling AIM container images.
	// +optional
	ImagePullSecrets []corev1.LocalObjectReference `json:"imagePullSecrets,omitempty"`

	// StorageClassName specifies the storage class for cache volumes.
	// When not specified, uses the cluster default storage class.
	// +optional
	StorageClassName string `json:"storageClassName,omitempty"`

	// DownloadImage specifies the container image used to download and initialize artifacts.
	// When not specified, the controller uses the default model download image.
	// +optional
	DownloadImage string `json:"downloadImage,omitempty"`

	// ModelSources specifies the model sources to cache for this template.
	// These sources are typically copied from the resolved template's model sources.
	// +optional
	ModelSources []AIMModelSource `json:"modelSources,omitempty"`

	// RuntimeConfigRef contains the runtime config reference for this template cache.
	RuntimeConfigRef `json:",inline"`

	// Mode controls the ownership behavior of artifacts created by this template cache.
	// - Dedicated: artifacts are owned by this template cache and garbage collected when it's deleted.
	// - Shared (default): artifacts have no owner references and persist independently.
	// When a Shared template cache encounters artifacts with owner references, it promotes them
	// to shared by removing the owner references, ensuring they persist for long-term use.
	// +kubebuilder:default=Shared
	// +optional
	Mode AIMTemplateCacheMode `json:"mode,omitempty"`
}

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

	// Conditions represent the latest observations of the template cache state.
	// +listType=map
	// +listMapKey=type
	Conditions []metav1.Condition `json:"conditions,omitempty"`

	// ResolvedRuntimeConfig captures metadata about the runtime config that was resolved.
	// +optional
	ResolvedRuntimeConfig *AIMResolvedReference `json:"resolvedRuntimeConfig,omitempty"`

	// Status represents the current high-level status of the template cache.
	// +kubebuilder:default=Pending
	// +kubebuilder:validation:Enum=Pending;Progressing;Ready;Failed;Degraded;NotAvailable
	Status constants.AIMStatus `json:"status,omitempty"`

	// ResolvedTemplateKind indicates whether the template resolved to a namespace-scoped
	// AIMServiceTemplate or cluster-scoped AIMClusterServiceTemplate.
	// Values: "AIMServiceTemplate", "AIMClusterServiceTemplate"
	ResolvedTemplateKind string `json:"resolvedTemplateKind,omitempty"`

	// Artifacts maps model names to their resolved AIMArtifact resources.
	// +optional
	Artifacts map[string]AIMResolvedArtifact `json:"artifacts,omitempty"`
}

type AIMTemplateCachingConfig struct {
	// Enabled controls whether caching is enabled for this template.
	// Defaults to `false`.
	// +kubebuilder:default=false
	Enabled bool `json:"enabled,omitempty"`

	// Env specifies environment variables to use when downloading the model for caching.
	// These variables are available to the model download process and can be used
	// to configure download behavior, authentication, proxies, etc.
	// If not set, falls back to the template's top-level Env field.
	// +optional
	// +listType=map
	// +listMapKey=name
	Env []corev1.EnvVar `json:"env,omitempty"`
}

type AIMTemplateCandidateResult struct {
	// Name is the name of the template candidate.
	Name string `json:"name"`
	// Status indicates whether the candidate was "chosen" or "rejected".
	Status string `json:"status"`
	// Reason provides a CamelCase reason for the evaluation result.
	Reason string `json:"reason,omitempty"`
}

type AIMTemplateProfile struct {
	// Metric specifies the optimization target (e.g., latency, throughput).
	// +optional
	// +kubebuilder:validation:Enum=latency;throughput
	Metric AIMMetric `json:"metric,omitempty"`

	// Precision specifies the numerical precision (e.g., fp8, fp16, bf16).
	// +optional
	// +kubebuilder:validation:Enum=auto;fp4;fp8;fp16;fp32;bf16;int4;int8
	Precision AIMPrecision `json:"precision,omitempty"`
}

type DiscoveryState struct {
	// Attempts is the number of discovery job attempts that have been made.
	// This counter increments each time a new discovery job is created after a failure.
	// +optional
	Attempts int32 `json:"attempts,omitempty"`

	// LastAttemptTime is the timestamp of the most recent discovery job creation.
	// Used to calculate exponential backoff before the next retry.
	// +optional
	LastAttemptTime *metav1.Time `json:"lastAttemptTime,omitempty"`

	// LastFailureReason captures the reason for the most recent discovery failure.
	// Used to classify failures as terminal vs transient.
	// +optional
	LastFailureReason string `json:"lastFailureReason,omitempty"`

	// SpecHash is a hash of the template spec fields that affect discovery.
	// When the spec changes, the circuit breaker resets to allow fresh attempts.
	// +optional
	SpecHash string `json:"specHash,omitempty"`
}

type DownloadProgress struct {
	// TotalBytes is the expected total size of the download in bytes
	// +optional
	TotalBytes int64 `json:"totalBytes,omitempty"`

	// DownloadedBytes is the number of bytes downloaded so far
	// +optional
	DownloadedBytes int64 `json:"downloadedBytes,omitempty"`

	// Percentage is the download progress as a percentage (0-100)
	// +optional
	// +kubebuilder:validation:Minimum=0
	// +kubebuilder:validation:Maximum=100
	Percentage int32 `json:"percentage,omitempty"`

	// DisplayPercentage is a human-readable progress string (e.g., "45 %")
	// This field is automatically populated from Progress.Percentage
	// +optional
	DisplayPercentage string `json:"displayPercentage,omitempty"`
}

type DownloadState struct {
	// Protocol is the download protocol currently in use (e.g., "XET", "HF_TRANSFER", "HTTP")
	// +optional
	Protocol string `json:"protocol,omitempty"`

	// Attempt is the current attempt number (1-based)
	// +optional
	Attempt int32 `json:"attempt,omitempty"`

	// TotalAttempts is the total number of attempts configured via AIM_DOWNLOADER_PROTOCOL
	// +optional
	TotalAttempts int32 `json:"totalAttempts,omitempty"`

	// ProtocolSequence is the configured protocol sequence (e.g., "HF_TRANSFER,XET")
	// +optional
	ProtocolSequence string `json:"protocolSequence,omitempty"`

	// Message is a human-readable status message from the downloader
	// +optional
	Message string `json:"message,omitempty"`
}

type ImageMetadata struct {
	// Model contains AMD Silogen model-specific metadata.
	// +optional
	Model *ModelMetadata `json:"model,omitempty"`

	// OCI contains standard OCI image metadata.
	// +optional
	OCI *OCIMetadata `json:"oci,omitempty"`

	// OriginalLabels contains the raw OCI image labels as a JSON object.
	// This preserves all labels from the image, including those not mapped to structured fields.
	// +optional
	OriginalLabels map[string]string `json:"originalLabels,omitempty"`
}

type ModelMetadata struct {
	// CanonicalName is the canonical model identifier (e.g., mistralai/Mixtral-8x22B-Instruct-v0.1).
	// Extracted from: org.amd.silogen.model.canonicalName
	// +optional
	CanonicalName string `json:"canonicalName,omitempty"`

	// Source is the URL where the model can be found.
	// Extracted from: org.amd.silogen.model.source
	// +optional
	Source string `json:"source,omitempty"`

	// Tags are descriptive tags (e.g., ["text-generation", "chat", "instruction"]).
	// Extracted from: org.amd.silogen.model.tags (comma-separated)
	// +optional
	Tags []string `json:"tags,omitempty"`

	// Versions lists available versions.
	// Extracted from: org.amd.silogen.model.versions (comma-separated)
	// +optional
	Versions []string `json:"versions,omitempty"`

	// Variants lists model variants.
	// Extracted from: org.amd.silogen.model.variants (comma-separated)
	// +optional
	Variants []string `json:"variants,omitempty"`

	// HFTokenRequired indicates if a HuggingFace token is required.
	// Extracted from: org.amd.silogen.hfToken.required
	// +optional
	HFTokenRequired bool `json:"hfTokenRequired,omitempty"`

	// Title is the Silogen-specific title for the model.
	// Extracted from: org.amd.silogen.title
	// +optional
	Title string `json:"title,omitempty"`

	// DescriptionFull is the full description.
	// Extracted from: org.amd.silogen.description.full
	// +optional
	DescriptionFull string `json:"descriptionFull,omitempty"`

	// ReleaseNotes contains release notes for this version.
	// Extracted from: org.amd.silogen.release.notes
	// +optional
	ReleaseNotes string `json:"releaseNotes,omitempty"`

	// RecommendedDeployments contains recommended deployment configurations.
	// Extracted from: org.amd.silogen.model.recommendedDeployments (parsed from JSON array)
	// +optional
	RecommendedDeployments []RecommendedDeployment `json:"recommendedDeployments,omitempty"`
}

type ModelSourceFilter struct {
	// Image pattern with wildcard and full URI support.
	//
	// Supported formats:
	// - Repository pattern: "amdenterpriseai/aim-*"
	// - Repository with tag: "silogen/aim-llama:1.0.0" (overrides versions field)
	// - Full URI: "ghcr.io/silogen/aim-google-gemma-3-1b-it:0.8.1-rc1" (overrides spec.registry and versions)
	// - Full URI with wildcard: "ghcr.io/silogen/aim-*" (overrides spec.registry)
	//
	// When a full URI is specified (including registry like ghcr.io), only images from that
	// registry will match. When a tag is included, it takes precedence over the versions field.
	//
	// Wildcard: * matches any sequence of characters.
	// +kubebuilder:validation:MaxLength=512
	Image string `json:"image"`

	// Exclude lists specific repository names to skip (exact match on repository name only, not registry).
	// Useful for excluding base images or experimental versions.
	//
	// Examples:
	// - ["amdenterpriseai/aim-base", "amdenterpriseai/aim-experimental"]
	// - ["silogen/aim-base"] - works with "ghcr.io/silogen/aim-*" (registry is not checked in exclusion)
	//
	// Note: Exclusions match against repository names (e.g., "silogen/aim-base"), not full URIs.
	// +optional
	Exclude []string `json:"exclude,omitempty"`

	// Versions specifies semantic version constraints for this filter.
	// If specified, overrides the global Versions field.
	// Only tags that parse as valid semver are considered (including prereleases like 0.8.1-rc1).
	// Ignored if the Image field includes an explicit tag (e.g., "repo:1.0.0").
	//
	// Examples: ">=1.0.0", "<2.0.0", "~1.2.0" (patch updates), "^1.0.0" (minor updates)
	//
	// Prerelease versions (e.g., 0.8.1-rc1) are supported and follow semver rules:
	// - 0.8.1-rc1 matches ">=0.8.0" (prerelease is part of version 0.8.1)
	// - Use ">=0.8.1-rc1" to match only that prerelease or higher
	// - Leave empty to match all tags (including prereleases and non-semver tags)
	// +optional
	Versions []string `json:"versions,omitempty"`
}

type OCIMetadata struct {
	// Title is the human-readable title.
	// Extracted from: org.opencontainers.image.title
	// +optional
	Title string `json:"title,omitempty"`

	// Description is a brief description.
	// Extracted from: org.opencontainers.image.description
	// +optional
	Description string `json:"description,omitempty"`

	// Licenses is the SPDX license identifier(s).
	// Extracted from: org.opencontainers.image.licenses
	// +optional
	Licenses string `json:"licenses,omitempty"`

	// Vendor is the organization that produced the image.
	// Extracted from: org.opencontainers.image.vendor
	// +optional
	Vendor string `json:"vendor,omitempty"`

	// Authors is contact details of the authors.
	// Extracted from: org.opencontainers.image.authors
	// +optional
	Authors string `json:"authors,omitempty"`

	// Source is the URL to the source code repository.
	// Extracted from: org.opencontainers.image.source
	// +optional
	Source string `json:"source,omitempty"`

	// Documentation is the URL to documentation.
	// Extracted from: org.opencontainers.image.documentation
	// +optional
	Documentation string `json:"documentation,omitempty"`

	// Created is the creation timestamp.
	// Extracted from: org.opencontainers.image.created
	// +optional
	Created string `json:"created,omitempty"`

	// Revision is the source control revision.
	// Extracted from: org.opencontainers.image.revision
	// +optional
	Revision string `json:"revision,omitempty"`

	// Version is the image version.
	// Extracted from: org.opencontainers.image.version
	// +optional
	Version string `json:"version,omitempty"`
}

type ProfileDiscoveryStatusEnum string

type RecommendedDeployment struct {
	// GPUModel is the GPU model name (e.g., MI300X, MI325X)
	// +optional
	GPUModel string `json:"gpuModel,omitempty"`

	// GPUCount is the number of GPUs required
	// +optional
	GPUCount int32 `json:"gpuCount,omitempty"`

	// Precision is the recommended precision (e.g., fp8, fp16, bf16)
	// +optional
	Precision string `json:"precision,omitempty"`

	// Metric is the optimization target (e.g., latency, throughput)
	// +optional
	Metric string `json:"metric,omitempty"`

	// ProfileId is the unique identifier of the AIM profile for this deployment.
	// When set, templates created from this deployment will use this profile ID
	// to deterministically select the correct runtime profile in the AIM container.
	// +optional
	ProfileId string `json:"profileId,omitempty"`

	// Description provides additional context about this deployment configuration
	// +optional
	Description string `json:"description,omitempty"`
}

type RuntimeConfigRef struct {
	// Name is the name of the runtime config to use for this resource. If a runtime config with this name exists both
	// as a namespace and a cluster runtime config, the values are merged together, the namespace config taking priority
	// over the cluster config when there are conflicts. If this field is empty or set to `default`, the namespace / cluster
	// runtime config with the name `default` is used, if it exists.
	// +optional
	Name string `json:"runtimeConfigName,omitempty"`
}