Skip to main content

reflex/pulse/write/
mod.rs

1//! The Pulse LLM writing pass.
2//!
3//! Pulse builds a complete site without an LLM. This pass only fills narrative slots,
4//! and every task goes through one executor ([`run_tasks`]) and one content-addressed
5//! cache ([`cache::WriteCache`]). Evidence packs, output contracts and the grounding
6//! gate build on top of this layer.
7
8pub mod cache;
9pub mod contract;
10pub mod gate;
11pub mod provider;
12pub mod run;
13
14pub use cache::WriteCache;
15pub use provider::{LlmHandle, ModelIdent};
16pub use run::{OutputSpec, RunStats, TaskOutcome, WriteConfig, WriteOutcome, WriteTask, run_tasks};
17
18use std::path::{Path, PathBuf};
19use std::str::FromStr;
20
21/// Writing-pass options from the command line. `None` fields fall back to `[pulse.write]`.
22#[derive(Debug, Clone, Default)]
23pub struct WriteOptions {
24    pub mode: LlmMode,
25    pub force: ForceScope,
26    pub dry_run: bool,
27    pub concurrency: Option<usize>,
28    pub max_llm_tokens: Option<u64>,
29    pub cache_dir: Option<PathBuf>,
30    pub no_prune: bool,
31    pub model: Option<String>,
32    /// Print every sentence the grounding gate dropped, and why.
33    pub explain: bool,
34}
35
36impl WriteOptions {
37    /// The LLM is off.
38    pub fn off() -> Self {
39        Self {
40            mode: LlmMode::Off,
41            ..Self::default()
42        }
43    }
44}
45
46/// A ready-to-run writing pass: provider handle, cache and executor settings.
47pub struct WriteSession {
48    pub llm: LlmHandle,
49    pub cache: WriteCache,
50    pub cfg: WriteConfig,
51}
52
53impl WriteSession {
54    /// Merge CLI options over `[pulse.write]` and resolve the provider.
55    pub fn open(reflex_cache: &Path, opts: &WriteOptions) -> Self {
56        let mut settings = crate::pulse::config::load_pulse_config(reflex_cache)
57            .map(|c| c.write)
58            .unwrap_or_else(|e| {
59                log::warn!("ignoring invalid [pulse] config: {e:#}");
60                Default::default()
61            });
62        if opts.model.is_some() {
63            settings.model = opts.model.clone();
64        }
65        let cache_dir = opts
66            .cache_dir
67            .clone()
68            .or_else(|| settings.cache_dir.as_ref().map(PathBuf::from))
69            .unwrap_or_else(|| WriteCache::default_dir(reflex_cache));
70        let cfg = WriteConfig {
71            mode: opts.mode,
72            concurrency: opts.concurrency.unwrap_or(settings.concurrency),
73            max_llm_tokens: opts.max_llm_tokens.or(settings.max_llm_tokens),
74            force: opts.force.clone(),
75            dry_run: opts.dry_run,
76            keep_runs: settings.keep_runs,
77            prune: !opts.no_prune,
78            cache_model_agnostic: settings.cache_model_agnostic,
79            ..WriteConfig::default()
80        };
81        Self {
82            llm: provider::resolve(opts.mode, &settings),
83            cache: WriteCache::new(cache_dir),
84            cfg,
85        }
86    }
87
88    pub fn run(&self, tasks: Vec<WriteTask>) -> WriteOutcome {
89        run_tasks(tasks, &self.llm, &self.cache, &self.cfg)
90    }
91
92    /// Run one task and return its text, printing the summary on failure.
93    pub fn run_one(&self, task: WriteTask) -> Option<String> {
94        let id = task.id.clone();
95        let out = self.run(vec![task]);
96        if out.degraded.is_some() {
97            eprintln!("{}", out.summary());
98        }
99        out.text(&id).map(str::to_string)
100    }
101}
102
103/// Whether the writing pass may call a provider.
104#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
105pub enum LlmMode {
106    /// Call the provider on cache misses.
107    #[default]
108    On,
109    /// Structural output only.
110    Off,
111    /// Use cached answers; never call. For CI jobs without secrets (fork PRs).
112    CacheOnly,
113}
114
115impl FromStr for LlmMode {
116    type Err = String;
117
118    fn from_str(s: &str) -> Result<Self, Self::Err> {
119        match s.to_ascii_lowercase().as_str() {
120            "on" => Ok(Self::On),
121            "off" => Ok(Self::Off),
122            "cache-only" | "cache_only" | "cached" => Ok(Self::CacheOnly),
123            other => Err(format!(
124                "invalid --llm value '{other}' (expected on, off or cache-only)"
125            )),
126        }
127    }
128}
129
130/// Which tasks `--force-renarrate` re-runs, ignoring the cache.
131#[derive(Debug, Clone, Default, PartialEq)]
132pub enum ForceScope {
133    #[default]
134    None,
135    All,
136    /// Task kinds (`modules`, `overview`, …) or globs over task ids (`module:src/pulse*`).
137    Only(Vec<String>),
138}
139
140impl ForceScope {
141    /// Parse `all` or a comma-separated list. An empty string means none.
142    pub fn parse(spec: &str) -> Self {
143        let parts: Vec<String> = spec
144            .split(',')
145            .map(|p| p.trim().to_string())
146            .filter(|p| !p.is_empty())
147            .collect();
148        if parts.is_empty() {
149            Self::None
150        } else if parts.iter().any(|p| p == "all") {
151            Self::All
152        } else {
153            Self::Only(parts)
154        }
155    }
156
157    pub fn matches(&self, task: &WriteTask) -> bool {
158        match self {
159            Self::None => false,
160            Self::All => true,
161            Self::Only(parts) => parts.iter().any(|p| {
162                p == task.kind
163                    || globset::Glob::new(p)
164                        .map(|g| g.compile_matcher().is_match(&task.id))
165                        .unwrap_or(false)
166            }),
167        }
168    }
169}
170
171#[cfg(test)]
172mod tests {
173    use super::*;
174    use crate::semantic::providers::ProviderErrorKind;
175    use crate::semantic::providers::mock::MockLlmProvider;
176    use std::sync::Arc;
177    use std::time::Duration;
178    use tempfile::TempDir;
179
180    const WORDS: &str = "one two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen sixteen";
181
182    fn task(id: &str, kind: &'static str) -> WriteTask {
183        WriteTask::text(id, kind, "SYSTEM", format!("{WORDS} {id}"))
184    }
185
186    fn fast_cfg() -> WriteConfig {
187        WriteConfig {
188            base_backoff: Duration::from_millis(1),
189            ..WriteConfig::default()
190        }
191    }
192
193    fn echo() -> Arc<MockLlmProvider> {
194        Arc::new(MockLlmProvider::routed(|req| {
195            Ok(format!("text for {}", req.tag))
196        }))
197    }
198
199    fn handle(p: &Arc<MockLlmProvider>) -> LlmHandle {
200        LlmHandle::from_provider(p.clone())
201    }
202
203    #[test]
204    fn llm_mode_parse() {
205        assert_eq!("on".parse::<LlmMode>().unwrap(), LlmMode::On);
206        assert_eq!("OFF".parse::<LlmMode>().unwrap(), LlmMode::Off);
207        assert_eq!("cache-only".parse::<LlmMode>().unwrap(), LlmMode::CacheOnly);
208        assert!("maybe".parse::<LlmMode>().is_err());
209    }
210
211    #[test]
212    fn force_scope_parse_and_match() {
213        assert_eq!(ForceScope::parse(""), ForceScope::None);
214        assert_eq!(ForceScope::parse("all"), ForceScope::All);
215        let s = ForceScope::parse("overview, module:src/pulse*");
216        assert!(s.matches(&task("project-overview", "overview")));
217        assert!(s.matches(&task("module:src/pulse/write", "modules")));
218        assert!(!s.matches(&task("module:src/query", "modules")));
219    }
220
221    #[test]
222    fn calls_then_hits_the_cache_on_rerun() {
223        let dir = TempDir::new().unwrap();
224        let cache = WriteCache::new(dir.path());
225        let p = echo();
226        let tasks = vec![task("a", "modules"), task("b", "modules")];
227
228        let first = run_tasks(tasks.clone(), &handle(&p), &cache, &fast_cfg());
229        assert!(first.degraded.is_none(), "{:?}", first.degraded);
230        assert_eq!(first.stats.called, 2);
231        assert_eq!(first.text("a"), Some("text for a"));
232        assert_eq!(p.call_count(), 2);
233
234        let second = run_tasks(tasks, &handle(&p), &cache, &fast_cfg());
235        assert_eq!(second.stats.cached, 2);
236        assert_eq!(second.stats.called, 0);
237        assert_eq!(second.text("b"), Some("text for b"));
238        assert_eq!(p.call_count(), 2, "no new calls on a warm cache");
239    }
240
241    #[test]
242    fn system_and_user_are_sent_separately() {
243        let dir = TempDir::new().unwrap();
244        let p = echo();
245        run_tasks(
246            vec![task("a", "modules")],
247            &handle(&p),
248            &WriteCache::new(dir.path()),
249            &fast_cfg(),
250        );
251        let req = &p.requests()[0];
252        assert_eq!(req.system, "SYSTEM");
253        assert!(req.user.ends_with(" a"));
254        assert_eq!(req.output, "text");
255    }
256
257    #[test]
258    fn identical_requests_share_one_call() {
259        let dir = TempDir::new().unwrap();
260        let p = echo();
261        let a = WriteTask::text("a", "modules", "S", WORDS);
262        let b = WriteTask::text("b", "modules", "S", WORDS);
263        let out = run_tasks(
264            vec![a, b],
265            &handle(&p),
266            &WriteCache::new(dir.path()),
267            &fast_cfg(),
268        );
269        assert_eq!(p.call_count(), 1);
270        assert_eq!(out.text("a"), out.text("b"));
271        assert!(out.text("a").is_some());
272    }
273
274    #[test]
275    fn thin_input_is_suppressed_without_a_call() {
276        let dir = TempDir::new().unwrap();
277        let p = echo();
278        let thin = WriteTask::text("thin", "modules", "S", "too short");
279        let out = run_tasks(
280            vec![thin],
281            &handle(&p),
282            &WriteCache::new(dir.path()),
283            &fast_cfg(),
284        );
285        assert!(matches!(
286            out.results["thin"].outcome,
287            TaskOutcome::Suppressed(_)
288        ));
289        assert_eq!(p.call_count(), 0);
290        assert!(out.degraded.is_none());
291    }
292
293    #[test]
294    fn model_change_misses_unless_model_agnostic() {
295        let dir = TempDir::new().unwrap();
296        let cache = WriteCache::new(dir.path());
297        let t = vec![task("a", "modules")];
298        run_tasks(t.clone(), &handle(&echo()), &cache, &fast_cfg());
299
300        let other = Arc::new(MockLlmProvider::routed(|_| Ok("new".into())).with_model("other"));
301        let out = run_tasks(t.clone(), &handle(&other), &cache, &fast_cfg());
302        assert_eq!(out.stats.called, 1, "different model → different key");
303
304        let agnostic = WriteConfig {
305            cache_model_agnostic: true,
306            ..fast_cfg()
307        };
308        run_tasks(t.clone(), &handle(&echo()), &cache, &agnostic);
309        let again = Arc::new(MockLlmProvider::routed(|_| Ok("x".into())).with_model("third"));
310        let out = run_tasks(t, &handle(&again), &cache, &agnostic);
311        assert_eq!(out.stats.cached, 1);
312        assert_eq!(again.call_count(), 0);
313    }
314
315    #[test]
316    fn fatal_probe_degrades_the_whole_run_and_ignores_hits() {
317        let dir = TempDir::new().unwrap();
318        let cache = WriteCache::new(dir.path());
319        // Warm one entry.
320        run_tasks(
321            vec![task("a", "modules")],
322            &handle(&echo()),
323            &cache,
324            &fast_cfg(),
325        );
326
327        let p = Arc::new(
328            MockLlmProvider::routed(|_| Ok("x".into())).fail_first(1, ProviderErrorKind::Auth),
329        );
330        let tasks = vec![
331            task("a", "modules"),
332            task("b", "modules"),
333            task("c", "modules"),
334        ];
335        let out = run_tasks(tasks, &handle(&p), &cache, &fast_cfg());
336        assert!(out.degraded.is_some());
337        assert_eq!(p.call_count(), 1, "nothing is sent after a fatal probe");
338        assert_eq!(
339            out.text("a"),
340            None,
341            "cache hits are not used in a degraded run"
342        );
343        assert!(!out.has_text());
344    }
345
346    #[test]
347    fn transient_errors_are_retried() {
348        let dir = TempDir::new().unwrap();
349        let p = Arc::new(
350            MockLlmProvider::routed(|_| Ok("ok".into()))
351                .fail_first(2, ProviderErrorKind::RateLimited),
352        );
353        let out = run_tasks(
354            vec![task("a", "modules")],
355            &handle(&p),
356            &WriteCache::new(dir.path()),
357            &fast_cfg(),
358        );
359        assert_eq!(out.text("a"), Some("ok"));
360        assert_eq!(out.stats.retries, 2);
361        assert_eq!(p.call_count(), 3);
362    }
363
364    #[test]
365    fn consecutive_failures_trip_the_breaker() {
366        let dir = TempDir::new().unwrap();
367        let p = Arc::new(MockLlmProvider::routed(|_| {
368            Err(MockLlmProvider::error(ProviderErrorKind::Server))
369        }));
370        let cfg = WriteConfig {
371            concurrency: 1,
372            max_attempts: 1,
373            breaker_threshold: 3,
374            ..fast_cfg()
375        };
376        let tasks: Vec<_> = (0..10)
377            .map(|i| task(&format!("t{i:02}"), "modules"))
378            .collect();
379        let out = run_tasks(tasks, &handle(&p), &WriteCache::new(dir.path()), &cfg);
380        assert!(out.degraded.as_deref().unwrap().contains("consecutive"));
381        assert!(
382            p.call_count() <= 4,
383            "stops soon after the breaker trips: {}",
384            p.call_count()
385        );
386    }
387
388    #[test]
389    fn low_success_rate_degrades_but_keeps_successes_cached() {
390        let dir = TempDir::new().unwrap();
391        let cache = WriteCache::new(dir.path());
392        let p = Arc::new(MockLlmProvider::routed(|req| {
393            if req.tag == "a" {
394                Ok("fine".into())
395            } else {
396                Err(MockLlmProvider::error(ProviderErrorKind::Server))
397            }
398        }));
399        let cfg = WriteConfig {
400            max_attempts: 1,
401            ..fast_cfg()
402        };
403        let tasks = vec![
404            task("a", "modules"),
405            task("b", "modules"),
406            task("c", "modules"),
407        ];
408        let out = run_tasks(tasks.clone(), &handle(&p), &cache, &cfg);
409        assert!(out.degraded.is_some());
410        assert_eq!(out.text("a"), None);
411
412        let rerun = run_tasks(vec![task("a", "modules")], &handle(&echo()), &cache, &cfg);
413        assert_eq!(rerun.results["a"].outcome, TaskOutcome::Cached);
414    }
415
416    #[test]
417    fn budget_defers_low_priority_tasks_deterministically() {
418        let dir = TempDir::new().unwrap();
419        let p = echo();
420        let one = task("x", "modules");
421        let cost = ((one.system.len() + one.user.len()) as f64 / 3.5).ceil() as u64
422            + (one.max_tokens as f64 * 0.6).ceil() as u64;
423        let tasks = vec![
424            task("low", "modules").with_priority(200),
425            task("high", "overview").with_priority(10),
426            task("mid", "modules").with_priority(50),
427        ];
428        let cfg = WriteConfig {
429            max_llm_tokens: Some(cost * 2 + 5),
430            ..fast_cfg()
431        };
432        let out = run_tasks(tasks, &handle(&p), &WriteCache::new(dir.path()), &cfg);
433        assert!(out.truncated);
434        assert_eq!(out.results["low"].outcome, TaskOutcome::Deferred);
435        assert_eq!(out.results["high"].outcome, TaskOutcome::Called);
436        assert_eq!(out.results["mid"].outcome, TaskOutcome::Called);
437        assert_eq!(out.stats.pruned, 0, "a truncated run never prunes");
438    }
439
440    #[test]
441    fn dry_run_makes_no_calls_and_reports_a_plan() {
442        let dir = TempDir::new().unwrap();
443        let p = echo();
444        let cfg = WriteConfig {
445            dry_run: true,
446            ..fast_cfg()
447        };
448        let out = run_tasks(
449            vec![task("a", "modules"), task("o", "overview")],
450            &handle(&p),
451            &WriteCache::new(dir.path()),
452            &cfg,
453        );
454        assert_eq!(p.call_count(), 0);
455        let table = out.plan_table();
456        assert!(table.contains("modules"), "{table}");
457        assert!(table.contains("total"), "{table}");
458        assert!(table.contains("mock/mock-model"), "{table}");
459        assert_eq!(out.text("a"), None);
460    }
461
462    #[test]
463    fn cache_only_uses_hits_and_never_calls() {
464        let dir = TempDir::new().unwrap();
465        let cache = WriteCache::new(dir.path());
466        run_tasks(
467            vec![task("a", "modules")],
468            &handle(&echo()),
469            &cache,
470            &fast_cfg(),
471        );
472
473        let ident_only = LlmHandle {
474            ident: handle(&echo()).ident,
475            provider: None,
476            unavailable: Some("cache-only mode".into()),
477        };
478        let cfg = WriteConfig {
479            mode: LlmMode::CacheOnly,
480            ..fast_cfg()
481        };
482        let out = run_tasks(
483            vec![task("a", "modules"), task("b", "modules")],
484            &ident_only,
485            &cache,
486            &cfg,
487        );
488        assert!(out.degraded.is_none());
489        assert_eq!(out.text("a"), Some("text for a"));
490        assert_eq!(out.results["b"].outcome, TaskOutcome::NotCached);
491    }
492
493    #[test]
494    fn forced_scope_recalls_only_that_scope() {
495        let dir = TempDir::new().unwrap();
496        let cache = WriteCache::new(dir.path());
497        let tasks = vec![task("m", "modules"), task("o", "overview")];
498        run_tasks(tasks.clone(), &handle(&echo()), &cache, &fast_cfg());
499
500        let p = echo();
501        let cfg = WriteConfig {
502            force: ForceScope::parse("overview"),
503            ..fast_cfg()
504        };
505        let out = run_tasks(tasks, &handle(&p), &cache, &cfg);
506        let tags: Vec<String> = p.requests().into_iter().map(|r| r.tag).collect();
507        assert_eq!(tags, vec!["o".to_string()]);
508        assert_eq!(out.results["m"].outcome, TaskOutcome::Cached);
509    }
510
511    #[test]
512    fn successful_run_prunes_stale_entries() {
513        let dir = TempDir::new().unwrap();
514        let cache = WriteCache::new(dir.path());
515        let cfg = WriteConfig {
516            keep_runs: 1,
517            ..fast_cfg()
518        };
519        run_tasks(vec![task("old", "modules")], &handle(&echo()), &cache, &cfg);
520        assert_eq!(cache.count(), 1);
521        let out = run_tasks(vec![task("new", "modules")], &handle(&echo()), &cache, &cfg);
522        assert_eq!(out.stats.pruned, 1);
523        assert_eq!(cache.count(), 1);
524    }
525
526    #[test]
527    fn off_mode_skips_everything() {
528        let dir = TempDir::new().unwrap();
529        let p = echo();
530        let cfg = WriteConfig {
531            mode: LlmMode::Off,
532            ..fast_cfg()
533        };
534        let out = run_tasks(
535            vec![task("a", "modules")],
536            &handle(&p),
537            &WriteCache::new(dir.path()),
538            &cfg,
539        );
540        assert_eq!(out.results["a"].outcome, TaskOutcome::Skipped);
541        assert_eq!(p.call_count(), 0);
542        assert!(out.degraded.is_none());
543    }
544}