Skip to main content

visual_rubric/
config.rs

1//! Runtime and TOML configuration for visual rubric evaluation.
2
3use std::ffi::OsString;
4use std::path::{Path, PathBuf};
5
6use serde::{Deserialize, Serialize};
7
8#[cfg(feature = "codex-acp")]
9use crate::{DEFAULT_CODEX_ACP_MODEL, DEFAULT_CODEX_ACP_REASONING_EFFORT, DEFAULT_SYSTEM_PROMPT};
10use crate::{RubricEffort, SequenceOptions};
11
12/// Optional model settings for one rubric request.
13#[derive(Clone, Debug, Default, Deserialize, Serialize, PartialEq, Eq)]
14pub struct RubricOptions {
15    /// ACP model override.
16    pub model: Option<String>,
17    /// Reasoning effort override.
18    pub effort: Option<RubricEffort>,
19    /// System prompt override.
20    pub system_prompt: Option<String>,
21}
22
23/// Runtime configuration for rubric evaluation.
24///
25/// Supports two backends:
26/// - **HTTP** (via `url`): calls an OpenAI-compatible text model endpoint.
27/// - **ACP** (via `codex_acp_binary`): spawns an ACP child process.
28///
29/// When `url` is `Some`, the pipeline uses the HTTP backend and ignores ACP
30/// fields.  When `url` is `None`, the pipeline falls back to ACP.
31#[derive(Clone, Debug, PartialEq, Eq)]
32pub struct RubricRunConfig {
33    /// Path to the ACP binary (e.g. `codex-acp` or `opencode`).
34    pub codex_acp_binary: PathBuf,
35    /// Extra CLI arguments for the ACP binary.
36    /// Defaults to an empty list. ACP v1 session configuration carries model
37    /// and reasoning settings after `session/new`; legacy adapters may still
38    /// be given explicit arguments here.
39    pub acp_args: Vec<String>,
40    /// HTTP rubric API base URL (e.g. `"http://127.0.0.1:8013"`).
41    /// When set, the pipeline calls an OpenAI-compatible text model
42    /// directly instead of spawning an ACP child process.
43    pub url: Option<String>,
44    /// Model name for the HTTP rubric backend (ignored when `url` is `None`).
45    pub api_model: Option<String>,
46    /// Extra environment variables for the child process.
47    pub extra_env: Vec<(OsString, OsString)>,
48    /// Working directory passed to ACP.
49    pub cwd: Option<PathBuf>,
50}
51
52impl Default for RubricRunConfig {
53    fn default() -> Self {
54        Self {
55            #[cfg(feature = "codex-acp")]
56            codex_acp_binary: PathBuf::from("codex-acp"),
57            #[cfg(not(feature = "codex-acp"))]
58            codex_acp_binary: PathBuf::from("opencode"),
59            acp_args: Vec::new(),
60            url: None,
61            api_model: None,
62            extra_env: Vec::new(),
63            cwd: None,
64        }
65    }
66}
67
68impl RubricRunConfig {
69    /// Build a `RubricRunConfig` from the Home-Manager-managed TOML file.
70    ///
71    /// Reads `~/.config/visual-rubric/config.toml` (or an explicit
72    /// `path`) and extracts the `[rubric]` section: `backend` becomes
73    /// `codex_acp_binary`, `args` becomes `acp_args`.
74    ///
75    /// In `pipeline` mode the vision config is ignored — this method only
76    /// populates the rubric/ACP fields.  When the file is missing or
77    /// unreadable, returns the library [`Default`].
78    #[must_use]
79    pub fn from_config_toml(path: Option<&Path>) -> Self {
80        let toml = match load_config_toml(path) {
81            Ok(c) => c,
82            Err(_) => return RubricRunConfig::default(),
83        };
84        let mode = toml.mode.unwrap_or_default();
85        let default_backend = match mode {
86            ConfigMode::Direct => "codex-acp",
87            ConfigMode::Pipeline => "opencode",
88        };
89        let acp_args = match toml.rubric.args {
90            Some(args) => args,
91            None if mode == ConfigMode::Direct => direct_codex_acp_args(&toml.rubric),
92            None => vec!["acp".to_string()],
93        };
94        RubricRunConfig {
95            codex_acp_binary: toml
96                .rubric
97                .backend
98                .unwrap_or_else(|| default_backend.to_string())
99                .into(),
100            acp_args,
101            url: toml.rubric.url,
102            api_model: toml.rubric.model.clone(),
103            ..Default::default()
104        }
105    }
106}
107
108impl SequenceOptions {
109    /// Load the ordered-checkpoint policy from the Home-Manager TOML file.
110    ///
111    /// Invalid or missing configuration falls back to the library defaults;
112    /// deployment preflight is responsible for rejecting invalid production
113    /// configuration before a visual run starts.
114    #[must_use]
115    pub fn from_config_toml(path: Option<&Path>) -> Self {
116        let config = load_config_toml(path).ok();
117        let defaults = Self::default();
118        let sequence = config.as_ref().map(|value| &value.sequence);
119        Self {
120            max_frames: sequence
121                .and_then(|value| value.max_frames)
122                .unwrap_or(defaults.max_frames),
123            require_transition: sequence
124                .and_then(|value| value.require_transition)
125                .unwrap_or(defaults.require_transition),
126        }
127    }
128}
129
130fn direct_codex_acp_args(rubric: &TomlRubric) -> Vec<String> {
131    let _ = rubric;
132    Vec::new()
133}
134
135/// Returns the default rubric options.
136#[cfg(feature = "codex-acp")]
137#[must_use]
138pub fn default_options() -> RubricOptions {
139    RubricOptions {
140        model: Some(DEFAULT_CODEX_ACP_MODEL.to_string()),
141        effort: Some(DEFAULT_CODEX_ACP_REASONING_EFFORT.into()),
142        system_prompt: Some(DEFAULT_SYSTEM_PROMPT.to_string()),
143    }
144}
145
146/// Returns the default Codex ACP executable name.
147#[cfg(feature = "codex-acp")]
148#[must_use]
149pub fn default_codex_acp_binary() -> PathBuf {
150    PathBuf::from("codex-acp")
151}
152
153/// Backend mode read from `config.toml`.
154#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize, PartialEq, Eq, clap::ValueEnum)]
155#[serde(rename_all = "kebab-case")]
156pub enum ConfigMode {
157    /// Direct screenshot evaluation through codex-acp.
158    #[default]
159    Direct,
160    /// Vision extraction followed by rubric scoring.
161    Pipeline,
162}
163
164/// Full shape of `~/.config/visual-rubric/config.toml`.
165#[derive(Debug, Deserialize, Serialize, Default)]
166#[serde(default)]
167pub struct TomlConfig {
168    /// Top-level mode: `"direct"` or `"pipeline"`.
169    pub mode: Option<ConfigMode>,
170    /// `[vision]` section (used by pipeline mode only).
171    pub vision: TomlVision,
172    /// `[rubric]` section — binary, args, model, effort, system prompt.
173    pub rubric: TomlRubric,
174    /// `[sequence]` ordered-checkpoint policy.
175    pub sequence: TomlSequence,
176}
177
178/// `[sequence]` ordered-checkpoint policy.
179#[derive(Debug, Deserialize, Serialize, Default)]
180#[serde(default)]
181pub struct TomlSequence {
182    /// Maximum number of frames accepted by one sequence request.
183    pub max_frames: Option<usize>,
184    /// Require the rubric to assess before/after transition semantics.
185    pub require_transition: Option<bool>,
186}
187
188/// `[vision]` section of the TOML config.
189#[derive(Debug, Deserialize, Serialize, Default)]
190#[serde(default)]
191pub struct TomlVision {
192    /// Vision API base URL.
193    pub url: Option<String>,
194    /// Vision model name.
195    pub model: Option<String>,
196    /// Vision API key (Bearer token).
197    pub api_key: Option<String>,
198    /// Custom prompt for the vision extraction stage.
199    pub prompt: Option<String>,
200}
201
202/// `[rubric]` section of the TOML config.
203#[derive(Debug, Deserialize, Serialize, Default)]
204#[serde(default)]
205pub struct TomlRubric {
206    /// ACP binary name or path (e.g. `"opencode"` or `"codex-acp"`).
207    pub backend: Option<String>,
208    /// Extra CLI arguments for the ACP binary (e.g. `["acp"]` for opencode).
209    pub args: Option<Vec<String>>,
210    /// HTTP rubric API base URL (e.g. `"http://127.0.0.1:8013"`).
211    /// When set, the pipeline uses a direct HTTP call to a text model
212    /// instead of spawning an ACP child process.
213    pub url: Option<String>,
214    /// Rubric model name (passed to codex-acp or used as the HTTP model).
215    pub model: Option<String>,
216    /// Rubric reasoning effort.
217    pub effort: Option<String>,
218    /// Rubric system prompt override.
219    pub system_prompt: Option<String>,
220}
221
222/// Build the canonical direct Codex GPT TOML configuration.
223///
224/// This is the optimized subscription-backed path: `codex-acp` receives one
225/// multimodal prompt containing both the rubric text and the screenshot.
226#[cfg(feature = "codex-acp")]
227#[must_use]
228pub fn direct_codex_gpt_config(model: Option<&str>, effort: Option<&str>) -> TomlConfig {
229    TomlConfig {
230        mode: Some(ConfigMode::Direct),
231        vision: TomlVision::default(),
232        sequence: TomlSequence::default(),
233        rubric: TomlRubric {
234            backend: Some("codex-acp".to_string()),
235            args: None,
236            url: None,
237            model: Some(model.unwrap_or(DEFAULT_CODEX_ACP_MODEL).to_string()),
238            effort: Some(
239                effort
240                    .unwrap_or(DEFAULT_CODEX_ACP_REASONING_EFFORT)
241                    .to_string(),
242            ),
243            system_prompt: None,
244        },
245    }
246}
247
248/// Load the TOML config from `path`, falling back to the user config path and
249/// then the Infernix-managed `/etc/visual-rubric/config.toml`.
250///
251/// Returns the default `TomlConfig` (empty optional fields) when the file
252/// is missing.
253pub fn load_config_toml(path: Option<&Path>) -> Result<TomlConfig, std::io::Error> {
254    let path = match path {
255        Some(p) => p.to_path_buf(),
256        None => config_candidates()
257            .into_iter()
258            .find(|candidate| candidate.is_file())
259            .unwrap_or_else(|| PathBuf::from("/etc/visual-rubric/config.toml")),
260    };
261    let content = match std::fs::read_to_string(&path) {
262        Ok(c) => c,
263        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
264            return Ok(TomlConfig::default());
265        }
266        Err(e) => return Err(e),
267    };
268    toml::from_str(&content).map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))
269}
270
271fn config_candidates() -> Vec<PathBuf> {
272    let mut candidates = Vec::new();
273    if let Some(base) = config_dir() {
274        candidates.push(base.join("visual-rubric/config.toml"));
275    }
276    candidates.push(PathBuf::from("/etc/visual-rubric/config.toml"));
277    candidates
278}
279
280fn config_dir() -> Option<PathBuf> {
281    #[cfg(windows)]
282    {
283        std::env::var_os("APPDATA").map(PathBuf::from)
284    }
285    #[cfg(target_os = "macos")]
286    {
287        std::env::var_os("HOME").map(|h| PathBuf::from(h).join("Library/Application Support"))
288    }
289    #[cfg(not(any(windows, target_os = "macos")))]
290    {
291        std::env::var("XDG_CONFIG_HOME")
292            .ok()
293            .map(PathBuf::from)
294            .or_else(|| {
295                std::env::var("HOME")
296                    .ok()
297                    .map(|h| PathBuf::from(h).join(".config"))
298            })
299    }
300}