Skip to main content

hyprstream_k8s/
training.rs

1//! `training.hyprstream.io/v1alpha1` — [`TrainingRun`].
2//!
3//! A [`TrainingRun`] is the intent to run Test-Time-Training / adapter training
4//! against a model, producing a file-based adapter. It is *intent only*: the
5//! STEP-loop reconciliation that dispatches it to workers and promotes results
6//! via git merge is K5c. `spec` is desired intent; `status` is observed truth.
7
8use kube::CustomResource;
9use schemars::JsonSchema;
10use serde::{Deserialize, Serialize};
11
12/// Coarse resource request for a training run. Lowered to a concrete PodSpec by
13/// the placement→PodSpec vocabulary map (K4c); kept minimal and portable here.
14#[derive(Serialize, Deserialize, Clone, Debug, Default, JsonSchema)]
15#[serde(rename_all = "camelCase")]
16pub struct ResourceSpec {
17    /// Number of GPUs requested (0 = CPU-only).
18    #[serde(default, skip_serializing_if = "Option::is_none")]
19    pub gpus: Option<u32>,
20
21    /// CPU request in Kubernetes quantity form, e.g. `"2"` or `"500m"`.
22    #[serde(default, skip_serializing_if = "Option::is_none")]
23    pub cpu: Option<String>,
24
25    /// Memory request in Kubernetes quantity form, e.g. `"8Gi"`.
26    #[serde(default, skip_serializing_if = "Option::is_none")]
27    pub memory: Option<String>,
28}
29
30/// Desired state of a [`TrainingRun`].
31///
32/// # Validation
33/// - `modelRef` must be non-empty.
34/// - `datasetMount` must be an absolute path.
35#[derive(CustomResource, Serialize, Deserialize, Clone, Debug, JsonSchema)]
36#[kube(
37    group = "training.hyprstream.io",
38    version = "v1alpha1",
39    kind = "TrainingRun",
40    plural = "trainingruns",
41    singular = "trainingrun",
42    shortname = "hstrain",
43    namespaced,
44    status = "TrainingRunStatus",
45    category = "hyprstream",
46    doc = "A TTT / adapter training job intent. spec is desired intent; status is observed truth. Promotion of results happens via git merge in RegistryService (K5c), never by this operator writing weights.",
47    printcolumn = r#"{"name":"Model","type":"string","jsonPath":".spec.modelRef"}"#,
48    printcolumn = r#"{"name":"Phase","type":"string","jsonPath":".status.phase"}"#,
49    validation = "self.spec.modelRef != ''",
50    validation = "self.spec.datasetMount.startsWith('/')",
51    cel
52)]
53#[serde(rename_all = "camelCase")]
54pub struct TrainingRunSpec {
55    /// Name of the [`crate::models::Model`] (same namespace) to train against.
56    pub model_ref: String,
57
58    /// Absolute mount path where the training dataset is delivered to the job
59    /// (a hyprstream VFS mount, K4b/CSI).
60    pub dataset_mount: String,
61
62    /// Name of the output file-based adapter to produce, e.g.
63    /// `00_finetune.safetensors`. Defaults are chosen by the reconciler when
64    /// omitted.
65    #[serde(default, skip_serializing_if = "Option::is_none")]
66    pub adapter_name: Option<String>,
67
68    /// Placement class / scheduling hint (`runs_on`) resolved by the scheduling
69    /// substrate. Free-form label consumed by K4c.
70    #[serde(default, skip_serializing_if = "Option::is_none")]
71    pub runs_on: Option<String>,
72
73    /// Coarse resource request for the training pod.
74    #[serde(default, skip_serializing_if = "Option::is_none")]
75    pub resources: Option<ResourceSpec>,
76}
77
78/// Observed truth for a [`TrainingRun`]. Written only by the operator.
79#[derive(Serialize, Deserialize, Clone, Debug, Default, JsonSchema)]
80#[serde(rename_all = "camelCase")]
81pub struct TrainingRunStatus {
82    /// Coarse lifecycle phase (`Pending`, `Running`, `Succeeded`, `Failed`).
83    #[serde(default, skip_serializing_if = "Option::is_none")]
84    pub phase: Option<String>,
85
86    /// Adapter file observed as produced by the run, once complete.
87    #[serde(default, skip_serializing_if = "Option::is_none")]
88    pub produced_adapter: Option<String>,
89
90    /// Human-readable detail for the current phase.
91    #[serde(default, skip_serializing_if = "Option::is_none")]
92    pub message: Option<String>,
93
94    /// `metadata.generation` last reconciled.
95    #[serde(default, skip_serializing_if = "Option::is_none")]
96    pub observed_generation: Option<i64>,
97}