Skip to main content

codex_codes/
models.rs

1//! Convenience enum for the models the Codex CLI exposes.
2//!
3//! Variants are keyed by human-friendly model names; [`CodexModel::cli_arg`]
4//! returns the model slug to pass to `codex -m` / `--model`, to
5//! `ThreadStartParams.model`, or to an `AppServerBuilder::config_override`
6//! of `model`.
7//!
8//! The catalog was taken from `openai/codex@main`'s bundled
9//! `models-manager/models.json` (2026-07-11). The server catalog evolves
10//! faster than this crate; GPT-6.1 Sol was verified against the live Codex
11//! catalog and official model documentation (2026-10-04). Unknown slugs round-trip through
12//! [`CodexModel::Custom`].
13
14use serde::{Deserialize, Deserializer, Serialize, Serializer};
15use std::fmt;
16
17/// A model slug accepted by the Codex CLI and app-server.
18#[derive(Debug, Clone, PartialEq, Eq, Hash)]
19pub enum CodexModel {
20    /// GPT-6.1 Sol (`gpt-6.1-sol`). Availability depends on the server/account.
21    Gpt61Sol,
22    /// GPT-6-Astra (`gpt-6-astra`) — first GPT-6-family model in the
23    /// catalog (272k context). Live-probed 2026-09-04: the backend
24    /// recognizes the slug but rejects it for ChatGPT-plan auth
25    /// ("not supported when using Codex with a ChatGPT account").
26    Gpt6Astra,
27    /// Daybreak Blue (`gpt-daybreak-blue-latest`) — the cyber-access
28    /// program models (see `CyberAccessProgram`); server-side gated.
29    DaybreakBlue,
30    /// Daybreak Red (`gpt-daybreak-red-latest`) — cyber-access program,
31    /// 372k context; server-side gated.
32    DaybreakRed,
33    /// GPT-5.6-Sol (`gpt-5.6-sol`).
34    Gpt56Sol,
35    /// GPT-5.6-Terra (`gpt-5.6-terra`).
36    Gpt56Terra,
37    /// GPT-5.6-Luna (`gpt-5.6-luna`).
38    Gpt56Luna,
39    /// GPT-5.5 (`gpt-5.5`).
40    Gpt55,
41    /// GPT-5.4 (`gpt-5.4`).
42    Gpt54,
43    /// GPT-5.4-Mini (`gpt-5.4-mini`).
44    Gpt54Mini,
45    /// GPT-5.2 (`gpt-5.2`).
46    Gpt52,
47    /// Codex Auto Review (`codex-auto-review`) — hidden from the picker but
48    /// accepted by the API.
49    CodexAutoReview,
50    /// A model slug not yet known to this version of the crate. Passed
51    /// through verbatim.
52    Custom(String),
53}
54
55impl CodexModel {
56    /// The slug to pass to `codex -m` / `ThreadStartParams.model`.
57    pub fn cli_arg(&self) -> &str {
58        match self {
59            Self::Gpt61Sol => "gpt-6.1-sol",
60            Self::Gpt6Astra => "gpt-6-astra",
61            Self::DaybreakBlue => "gpt-daybreak-blue-latest",
62            Self::DaybreakRed => "gpt-daybreak-red-latest",
63            Self::Gpt56Sol => "gpt-5.6-sol",
64            Self::Gpt56Terra => "gpt-5.6-terra",
65            Self::Gpt56Luna => "gpt-5.6-luna",
66            Self::Gpt55 => "gpt-5.5",
67            Self::Gpt54 => "gpt-5.4",
68            Self::Gpt54Mini => "gpt-5.4-mini",
69            Self::Gpt52 => "gpt-5.2",
70            Self::CodexAutoReview => "codex-auto-review",
71            Self::Custom(s) => s.as_str(),
72        }
73    }
74
75    /// Alias for [`cli_arg`](Self::cli_arg), matching the crate's string-enum
76    /// convention.
77    pub fn as_str(&self) -> &str {
78        self.cli_arg()
79    }
80
81    /// Human-friendly display name, matching the catalog's `display_name`.
82    pub fn display_name(&self) -> &str {
83        match self {
84            Self::Gpt61Sol => "GPT-6.1-Sol",
85            Self::Gpt6Astra => "GPT-6-Astra",
86            Self::DaybreakBlue => "Daybreak Blue",
87            Self::DaybreakRed => "Daybreak Red",
88            Self::Gpt56Sol => "GPT-5.6-Sol",
89            Self::Gpt56Terra => "GPT-5.6-Terra",
90            Self::Gpt56Luna => "GPT-5.6-Luna",
91            Self::Gpt55 => "GPT-5.5",
92            Self::Gpt54 => "GPT-5.4",
93            Self::Gpt54Mini => "GPT-5.4-Mini",
94            Self::Gpt52 => "GPT-5.2",
95            Self::CodexAutoReview => "Codex Auto Review",
96            Self::Custom(s) => s.as_str(),
97        }
98    }
99
100    /// Every model known to this version of the crate.
101    pub fn known() -> &'static [CodexModel] {
102        &[
103            Self::Gpt61Sol,
104            Self::Gpt6Astra,
105            Self::DaybreakBlue,
106            Self::DaybreakRed,
107            Self::Gpt56Sol,
108            Self::Gpt56Terra,
109            Self::Gpt56Luna,
110            Self::Gpt55,
111            Self::Gpt54,
112            Self::Gpt54Mini,
113            Self::Gpt52,
114            Self::CodexAutoReview,
115        ]
116    }
117}
118
119impl fmt::Display for CodexModel {
120    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
121        f.write_str(self.cli_arg())
122    }
123}
124
125impl From<&str> for CodexModel {
126    fn from(s: &str) -> Self {
127        match s {
128            "gpt-6.1-sol" => Self::Gpt61Sol,
129            "gpt-6-astra" => Self::Gpt6Astra,
130            "gpt-daybreak-blue-latest" => Self::DaybreakBlue,
131            "gpt-daybreak-red-latest" => Self::DaybreakRed,
132            "gpt-5.6-sol" => Self::Gpt56Sol,
133            "gpt-5.6-terra" => Self::Gpt56Terra,
134            "gpt-5.6-luna" => Self::Gpt56Luna,
135            "gpt-5.5" => Self::Gpt55,
136            "gpt-5.4" => Self::Gpt54,
137            "gpt-5.4-mini" => Self::Gpt54Mini,
138            "gpt-5.2" => Self::Gpt52,
139            "codex-auto-review" => Self::CodexAutoReview,
140            other => Self::Custom(other.to_string()),
141        }
142    }
143}
144
145impl From<CodexModel> for String {
146    fn from(model: CodexModel) -> Self {
147        model.cli_arg().to_string()
148    }
149}
150
151impl Serialize for CodexModel {
152    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
153        serializer.serialize_str(self.cli_arg())
154    }
155}
156
157impl<'de> Deserialize<'de> for CodexModel {
158    fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
159        let s = String::deserialize(deserializer)?;
160        Ok(Self::from(s.as_str()))
161    }
162}
163
164#[cfg(test)]
165mod tests {
166    use super::CodexModel;
167
168    #[test]
169    fn test_gpt61_sol_catalog_and_wire_round_trip() {
170        let model = CodexModel::from("gpt-6.1-sol");
171        assert_eq!(model, CodexModel::Gpt61Sol);
172        assert!(CodexModel::known().contains(&model));
173        assert_eq!(model.display_name(), "GPT-6.1-Sol");
174        assert_eq!(model.to_string(), "gpt-6.1-sol");
175        let json = serde_json::to_string(&model).unwrap();
176        assert_eq!(json, "\"gpt-6.1-sol\"");
177        assert_eq!(serde_json::from_str::<CodexModel>(&json).unwrap(), model);
178        let slug: String = model.into();
179        assert_eq!(slug, "gpt-6.1-sol");
180    }
181
182    #[test]
183    fn test_cli_arg_round_trip() {
184        for model in CodexModel::known() {
185            assert_eq!(&CodexModel::from(model.cli_arg()), model);
186        }
187        assert_eq!(
188            CodexModel::from("gpt-9-experimental"),
189            CodexModel::Custom("gpt-9-experimental".to_string())
190        );
191    }
192
193    #[test]
194    fn test_into_string_matches_cli_arg() {
195        let s: String = CodexModel::Gpt56Sol.into();
196        assert_eq!(s, "gpt-5.6-sol");
197    }
198
199    #[test]
200    fn test_converts_into_thread_start_model_field() {
201        // ThreadStartParams.model is Option<String>; the enum feeds it via Into.
202        let model: Option<String> = Some(CodexModel::Gpt55.into());
203        assert_eq!(model.as_deref(), Some("gpt-5.5"));
204    }
205
206    #[test]
207    fn test_serde_round_trip() {
208        let json = serde_json::to_string(&CodexModel::Gpt54Mini).unwrap();
209        assert_eq!(json, "\"gpt-5.4-mini\"");
210        let back: CodexModel = serde_json::from_str(&json).unwrap();
211        assert_eq!(back, CodexModel::Gpt54Mini);
212    }
213}