Skip to main content

hyprstream_k8s/
models.rs

1//! `models.hyprstream.io/v1alpha1` — [`Model`] and [`Adapter`].
2//!
3//! A [`Model`] is **git-ref intent**: which repository, which ref, and which
4//! STEP stage the operator should observe. An [`Adapter`] is **file-based
5//! adapter intent**: a `.safetensors` file under `adapters/` attached to a
6//! model (adapters are files, never branches — see the project's adapter model).
7//!
8//! Single-writer rule: `spec` is desired intent, `status` is observed git
9//! truth. The operator never writes weights; promotion/rollback happen in git
10//! via `RegistryService`.
11
12use kube::CustomResource;
13use schemars::JsonSchema;
14use serde::{Deserialize, Serialize};
15
16/// STEP-loop stage a model ref should be observed at.
17#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, Default, JsonSchema)]
18pub enum ModelStage {
19    /// Candidate weights on a staging branch, not yet promoted.
20    #[default]
21    Staged,
22    /// Weights merged/promoted onto the mainline (the served ref).
23    Promoted,
24}
25
26/// Desired state of a [`Model`]: a git-ref intent.
27///
28/// # Validation
29/// - `repo` must be non-empty.
30/// - `gitRef` (when set) must be non-empty.
31#[derive(CustomResource, Serialize, Deserialize, Clone, Debug, JsonSchema)]
32#[kube(
33    group = "models.hyprstream.io",
34    version = "v1alpha1",
35    kind = "Model",
36    plural = "models",
37    singular = "model",
38    shortname = "hsmodel",
39    namespaced,
40    status = "ModelStatus",
41    category = "hyprstream",
42    doc = "A hyprstream model as a git-ref intent (Stage → Train → Evaluate → Promote). spec is desired intent; status is observed git truth. The operator never writes weights.",
43    printcolumn = r#"{"name":"Repo","type":"string","jsonPath":".spec.repo"}"#,
44    printcolumn = r#"{"name":"Ref","type":"string","jsonPath":".status.observedRef"}"#,
45    printcolumn = r#"{"name":"Stage","type":"string","jsonPath":".spec.stage"}"#,
46    validation = "self.spec.repo != ''",
47    validation = "!has(self.spec.gitRef) || self.spec.gitRef != ''",
48    cel
49)]
50#[serde(rename_all = "camelCase")]
51pub struct ModelSpec {
52    /// Git repository the model lives in (URL or registry id). Required.
53    pub repo: String,
54
55    /// Git ref (branch, tag, or commit) to observe. Defaults to the repository
56    /// default branch when omitted.
57    #[serde(default, skip_serializing_if = "Option::is_none")]
58    pub git_ref: Option<String>,
59
60    /// STEP stage the operator should observe this model at.
61    #[serde(default)]
62    pub stage: ModelStage,
63}
64
65/// Observed git/runtime truth for a [`Model`]. Written only by the operator.
66#[derive(Serialize, Deserialize, Clone, Debug, Default, JsonSchema)]
67#[serde(rename_all = "camelCase")]
68pub struct ModelStatus {
69    /// Resolved commit (or ref) currently observed in git.
70    #[serde(default, skip_serializing_if = "Option::is_none")]
71    pub observed_ref: Option<String>,
72
73    /// Coarse lifecycle phase (`Pending`, `Ready`, `Failed`, ...).
74    #[serde(default, skip_serializing_if = "Option::is_none")]
75    pub phase: Option<String>,
76
77    /// Human-readable detail for the current phase.
78    #[serde(default, skip_serializing_if = "Option::is_none")]
79    pub message: Option<String>,
80
81    /// `metadata.generation` last reconciled, for staleness detection.
82    #[serde(default, skip_serializing_if = "Option::is_none")]
83    pub observed_generation: Option<i64>,
84}
85
86/// Desired state of an [`Adapter`]: a file-based adapter intent.
87///
88/// # Validation
89/// - `modelRef` must be non-empty.
90/// - `file` must match the file-based adapter naming convention
91///   `NN_name.safetensors` (two leading digits, then `_`, then a name,
92///   ending in `.safetensors`).
93#[derive(CustomResource, Serialize, Deserialize, Clone, Debug, JsonSchema)]
94#[kube(
95    group = "models.hyprstream.io",
96    version = "v1alpha1",
97    kind = "Adapter",
98    plural = "adapters",
99    singular = "adapter",
100    shortname = "hsadapter",
101    namespaced,
102    status = "AdapterStatus",
103    category = "hyprstream",
104    doc = "A file-based LoRA adapter intent stored as adapters/NN_name.safetensors on a model. Adapters are files, not branches.",
105    printcolumn = r#"{"name":"Model","type":"string","jsonPath":".spec.modelRef"}"#,
106    printcolumn = r#"{"name":"File","type":"string","jsonPath":".spec.file"}"#,
107    validation = "self.spec.modelRef != ''",
108    validation = "self.spec.file.matches('^[0-9]{2}_[A-Za-z0-9._-]+\\\\.safetensors$')",
109    cel
110)]
111#[serde(rename_all = "camelCase")]
112pub struct AdapterSpec {
113    /// Name of the [`Model`] (same namespace) this adapter attaches to.
114    pub model_ref: String,
115
116    /// Adapter filename under `adapters/`, e.g. `00_style.safetensors`.
117    pub file: String,
118
119    /// Optional base git ref the adapter was trained against, for provenance.
120    #[serde(default, skip_serializing_if = "Option::is_none")]
121    pub base_ref: Option<String>,
122}
123
124/// Observed truth for an [`Adapter`]. Written only by the operator.
125#[derive(Serialize, Deserialize, Clone, Debug, Default, JsonSchema)]
126#[serde(rename_all = "camelCase")]
127pub struct AdapterStatus {
128    /// The adapter file the operator observed on the model.
129    #[serde(default, skip_serializing_if = "Option::is_none")]
130    pub observed_file: Option<String>,
131
132    /// Coarse lifecycle phase (`Pending`, `Ready`, `Failed`, ...).
133    #[serde(default, skip_serializing_if = "Option::is_none")]
134    pub phase: Option<String>,
135
136    /// `metadata.generation` last reconciled.
137    #[serde(default, skip_serializing_if = "Option::is_none")]
138    pub observed_generation: Option<i64>,
139}