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 codex_acp_binary: PathBuf = toml
90            .rubric
91            .backend
92            .unwrap_or_else(|| default_backend.to_string())
93            .into();
94        let acp_args = toml
95            .rubric
96            .args
97            .unwrap_or_else(|| default_acp_args(&codex_acp_binary));
98        RubricRunConfig {
99            codex_acp_binary,
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
130/// Launch arguments for an ACP backend when none are configured: opencode
131/// serves ACP only under its `acp` subcommand, while `codex-acp` takes none.
132pub(crate) fn default_acp_args(binary: &Path) -> Vec<String> {
133    if binary.file_name().is_some_and(|name| name == "opencode") {
134        vec!["acp".to_string()]
135    } else {
136        Vec::new()
137    }
138}
139
140/// Returns the default rubric options.
141#[cfg(feature = "codex-acp")]
142#[must_use]
143pub fn default_options() -> RubricOptions {
144    RubricOptions {
145        model: Some(DEFAULT_CODEX_ACP_MODEL.to_string()),
146        effort: Some(DEFAULT_CODEX_ACP_REASONING_EFFORT.into()),
147        system_prompt: Some(DEFAULT_SYSTEM_PROMPT.to_string()),
148    }
149}
150
151/// Returns the default Codex ACP executable name.
152#[cfg(feature = "codex-acp")]
153#[must_use]
154pub fn default_codex_acp_binary() -> PathBuf {
155    PathBuf::from("codex-acp")
156}
157
158/// Backend mode read from `config.toml`.
159#[derive(Clone, Copy, Debug, Default, Deserialize, Serialize, PartialEq, Eq, clap::ValueEnum)]
160#[serde(rename_all = "kebab-case")]
161pub enum ConfigMode {
162    /// Direct screenshot evaluation through codex-acp.
163    #[default]
164    Direct,
165    /// Vision extraction followed by rubric scoring.
166    Pipeline,
167}
168
169/// Full shape of `~/.config/visual-rubric/config.toml`.
170#[derive(Debug, Deserialize, Serialize, Default)]
171#[serde(default)]
172pub struct TomlConfig {
173    /// Top-level mode: `"direct"` or `"pipeline"`.
174    pub mode: Option<ConfigMode>,
175    /// `[vision]` section (used by pipeline mode only).
176    pub vision: TomlVision,
177    /// `[rubric]` section — binary, args, model, effort, system prompt.
178    pub rubric: TomlRubric,
179    /// `[sequence]` ordered-checkpoint policy.
180    pub sequence: TomlSequence,
181}
182
183/// `[sequence]` ordered-checkpoint policy.
184#[derive(Debug, Deserialize, Serialize, Default)]
185#[serde(default)]
186pub struct TomlSequence {
187    /// Maximum number of frames accepted by one sequence request.
188    pub max_frames: Option<usize>,
189    /// Require the rubric to assess before/after transition semantics.
190    pub require_transition: Option<bool>,
191}
192
193/// `[vision]` section of the TOML config.
194#[derive(Debug, Deserialize, Serialize, Default)]
195#[serde(default)]
196pub struct TomlVision {
197    /// Vision API base URL.
198    pub url: Option<String>,
199    /// Vision model name.
200    pub model: Option<String>,
201    /// Vision API key (Bearer token).
202    pub api_key: Option<String>,
203    /// Custom prompt for the vision extraction stage.
204    pub prompt: Option<String>,
205}
206
207/// `[rubric]` section of the TOML config.
208#[derive(Debug, Deserialize, Serialize, Default)]
209#[serde(default)]
210pub struct TomlRubric {
211    /// ACP binary name or path (e.g. `"opencode"` or `"codex-acp"`).
212    pub backend: Option<String>,
213    /// Extra CLI arguments for the ACP binary (e.g. `["acp"]` for opencode).
214    pub args: Option<Vec<String>>,
215    /// HTTP rubric API base URL (e.g. `"http://127.0.0.1:8013"`).
216    /// When set, the pipeline uses a direct HTTP call to a text model
217    /// instead of spawning an ACP child process.
218    pub url: Option<String>,
219    /// Rubric model name (passed to codex-acp or used as the HTTP model).
220    pub model: Option<String>,
221    /// Rubric reasoning effort.
222    pub effort: Option<String>,
223    /// Rubric system prompt override.
224    pub system_prompt: Option<String>,
225}
226
227/// Build the canonical direct Codex GPT TOML configuration.
228///
229/// This is the optimized subscription-backed path: `codex-acp` receives one
230/// multimodal prompt containing both the rubric text and the screenshot.
231#[cfg(feature = "codex-acp")]
232#[must_use]
233pub fn direct_codex_gpt_config(model: Option<&str>, effort: Option<&str>) -> TomlConfig {
234    TomlConfig {
235        mode: Some(ConfigMode::Direct),
236        vision: TomlVision::default(),
237        sequence: TomlSequence::default(),
238        rubric: TomlRubric {
239            backend: Some("codex-acp".to_string()),
240            args: None,
241            url: None,
242            model: Some(model.unwrap_or(DEFAULT_CODEX_ACP_MODEL).to_string()),
243            effort: Some(
244                effort
245                    .unwrap_or(DEFAULT_CODEX_ACP_REASONING_EFFORT)
246                    .to_string(),
247            ),
248            system_prompt: None,
249        },
250    }
251}
252
253/// Load the TOML config from `path`, falling back to the user config path and
254/// then the Infernix-managed `/etc/visual-rubric/config.toml`.
255///
256/// Returns the default `TomlConfig` (empty optional fields) when the file
257/// is missing.
258pub fn load_config_toml(path: Option<&Path>) -> Result<TomlConfig, std::io::Error> {
259    let path = match path {
260        Some(p) => p.to_path_buf(),
261        None => config_candidates()
262            .into_iter()
263            .find(|candidate| candidate.is_file())
264            .unwrap_or_else(|| PathBuf::from("/etc/visual-rubric/config.toml")),
265    };
266    let content = match std::fs::read_to_string(&path) {
267        Ok(c) => c,
268        Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
269            return Ok(TomlConfig::default());
270        }
271        Err(e) => return Err(e),
272    };
273    toml::from_str(&content).map_err(|e| std::io::Error::new(std::io::ErrorKind::InvalidData, e))
274}
275
276fn config_candidates() -> Vec<PathBuf> {
277    let mut candidates = Vec::new();
278    if let Some(base) = config_dir() {
279        candidates.push(base.join("visual-rubric/config.toml"));
280    }
281    candidates.push(PathBuf::from("/etc/visual-rubric/config.toml"));
282    candidates
283}
284
285fn config_dir() -> Option<PathBuf> {
286    #[cfg(windows)]
287    {
288        std::env::var_os("APPDATA").map(PathBuf::from)
289    }
290    #[cfg(target_os = "macos")]
291    {
292        std::env::var_os("HOME").map(|h| PathBuf::from(h).join("Library/Application Support"))
293    }
294    #[cfg(not(any(windows, target_os = "macos")))]
295    {
296        std::env::var("XDG_CONFIG_HOME")
297            .ok()
298            .map(PathBuf::from)
299            .or_else(|| {
300                std::env::var("HOME")
301                    .ok()
302                    .map(|h| PathBuf::from(h).join(".config"))
303            })
304    }
305}