Merge pull request 'Formalize deep research tool as a clap CLI with gated logging and a spinner' (#3) from worktree-deep-research-cli into master

Reviewed-on: #3

Cargo.lock

@@ -80,6 +80,56 @@ dependencies = [
  "libc",
 ]
 
+[[package]]
+name = "anstream"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"
+
+[[package]]
+name = "anstyle-parse"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "anyhow"
 version = "1.0.104"
@@ -810,6 +860,46 @@ dependencies = [
  "phf 0.12.1",
 ]
 
+[[package]]
+name = "clap"
+version = "4.6.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "473c7e07f409a8d772161724aa8db6a765a2532a70f9667eeb7b49d3d02fbdca"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.6.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b48fea5a88e9ae728a2dcbedbfc0e730f7d60da42e1cb049a83c9fb8b789889"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d012d2b9d65aca7f18f4d9878a045bc17899bba951561ba5ec3c2ba1eed9a061"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn 3.0.3",
+]
+
+[[package]]
+name = "clap_lex"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c8d4a3bb8b1e0c1050499d1815f5ab16d04f0959b233085fb31653fbfc9d98f9"
+
 [[package]]
 name = "cmake"
 version = "0.1.58"
@@ -825,6 +915,12 @@ version = "1.1.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3d7b894f5411737b7867f4827955924d7c254fc9f4d91a6aad6b097804b1018b"
 
+[[package]]
+name = "colorchoice"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
+
 [[package]]
 name = "combine"
 version = "4.6.7"
@@ -1980,6 +2076,8 @@ version = "0.1.0"
 dependencies = [
  "anyhow",
  "chrono",
+ "clap",
+ "indicatif",
  "reqwest 0.13.4",
  "rig",
  "schemars 1.2.2",
@@ -2964,6 +3062,12 @@ version = "2.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d98f6fed1fde3f8c21bc40a1abb88dd75e67924f9cffc3ef95607bad8017f8e2"
 
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
 [[package]]
 name = "itertools"
 version = "0.13.0"
@@ -4359,6 +4463,12 @@ version = "1.21.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
 [[package]]
 name = "onig"
 version = "6.5.3"
@@ -6857,6 +6967,12 @@ version = "1.0.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
 
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
 [[package]]
 name = "uuid"
 version = "1.24.0"

Cargo.toml

@@ -5,6 +5,8 @@ edition = "2024"
 
 [dependencies]
 anyhow = "1.0.104"
+clap = { version = "4", features = ["derive"] }
+indicatif = "0.17"
 reqwest = { version = "0.13.4", features = ["query"] }
 rig = { version = "0.41.0", features = ["test-utils"] }
 schemars = "1"

src/deep_research/mod.rs

@@ -1,3 +1,4 @@
 pub mod starter;
+mod progress;
 mod review;
 mod tools;

src/deep_research/progress.rs

@@ -0,0 +1,33 @@
+use std::time::Duration;
+
+/// A terminal spinner for a research phase, shown only when logging is off —
+/// with logging on, the trace output already tells the user something is
+/// happening, and interleaving both would just be noisy. Clearing on drop
+/// means call sites don't need an explicit "stop" at every early return.
+pub(crate) struct Spinner(Option<indicatif::ProgressBar>);
+
+impl Spinner {
+    pub(crate) fn start(enabled: bool, message: &'static str) -> Self {
+        if !enabled {
+            return Self(None);
+        }
+
+        let bar = indicatif::ProgressBar::new_spinner();
+        bar.enable_steady_tick(Duration::from_millis(100));
+        bar.set_style(
+            indicatif::ProgressStyle::with_template("{spinner:.cyan} {msg}")
+                .expect("static template is valid"),
+        );
+        bar.set_message(message);
+
+        Self(Some(bar))
+    }
+}
+
+impl Drop for Spinner {
+    fn drop(&mut self) {
+        if let Some(bar) = &self.0 {
+            bar.finish_and_clear();
+        }
+    }
+}

src/deep_research/review.rs

@@ -3,6 +3,8 @@ use rig::providers::ollama;
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
+use crate::deep_research::progress::Spinner;
+
 /// Judging whether a conclusion actually follows from its cited sources is a
 /// bounded, single-shot classification task, not multi-step reasoning — so
 /// it doesn't need the researcher's larger model, just a fresh context free
@@ -32,6 +34,7 @@ pub(crate) async fn review_findings(
     client: &ollama::Client,
     topic: &str,
     findings: &str,
+    show_progress: bool,
 ) -> anyhow::Result<Review> {
     let reviewer = client
         .extractor::<Review>(REVIEWER_MODEL)
@@ -47,9 +50,11 @@ pub(crate) async fn review_findings(
         .retries(2)
         .build();
 
+    let spinner = Spinner::start(show_progress, "Reviewing findings...");
     let review = reviewer
         .extract(format!("Topic: {topic}\n\nResearch findings to review:\n{findings}"))
         .await?;
+    drop(spinner);
 
     tracing::info!(approved = review.approved, gaps = %review.gaps, "review complete");
 

src/deep_research/starter.rs

@@ -1,5 +1,7 @@
+use crate::deep_research::progress::Spinner;
 use crate::deep_research::review::{self, Review};
 use crate::deep_research::tools::{FetchPage, SearchWeb};
+use clap::Parser;
 use rig::client::{AgentClientExt, Nothing};
 use rig::completion::Prompt;
 use rig::providers::ollama;
@@ -20,28 +22,49 @@ const MAX_RESEARCH_ROUNDS: usize = 3;
 const DEFAULT_TOPIC: &str =
     "What are the latest advances in running large language models locally, on consumer hardware?";
 
-fn initialize_observability() {
+/// Deep research agentic loop over local Gemma models: a tool-calling agent
+/// gathers and cross-checks web evidence, a reviewer agent gates it, and a
+/// writer agent turns approved findings into a structured report.
+#[derive(Parser)]
+#[command(name = "doubleo7-research", version, about)]
+struct Cli {
+    /// Research topic to investigate
+    topic: Option<String>,
+
+    /// Emit logs at this level (off by default; passing this also enables a
+    /// progress spinner to switch off, since the logs already show progress)
+    #[arg(short = 'l', long, value_name = "LEVEL")]
+    log_level: Option<tracing::Level>,
+}
+
+/// Only initializes a subscriber (and thus produces any log output at all)
+/// when the caller opted in via `--log-level` — otherwise tracing's macros
+/// are no-ops, leaving the terminal clean for the spinner.
+fn initialize_observability(log_level: tracing::Level) {
     tracing_subscriber::fmt()
         .with_env_filter(
             tracing_subscriber::EnvFilter::try_from_default_env()
-                .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")),
+                .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new(log_level.to_string())),
         )
         .with_span_events(tracing_subscriber::fmt::format::FmtSpan::CLOSE)
         .with_writer(std::io::stderr)
         .init();
 }
 
-/// Performs deep research via a two-stage agentic flow: a tool-calling agent
-/// gathers and cross-checks evidence from the web, then a second agent turns
-/// those raw notes into a structured report.
 pub(crate) async fn start() -> anyhow::Result<()> {
-    initialize_observability();
+    let cli = Cli::parse();
 
-    let topic = std::env::args()
-        .nth(1)
-        .unwrap_or_else(|| DEFAULT_TOPIC.to_string());
+    let show_progress = match cli.log_level {
+        Some(level) => {
+            initialize_observability(level);
+            false
+        }
+        None => true,
+    };
 
-    let report = research(&topic).await?;
+    let topic = cli.topic.unwrap_or_else(|| DEFAULT_TOPIC.to_string());
+
+    let report = research(&topic, show_progress).await?;
 
     println!("{report}");
 
@@ -52,16 +75,16 @@ pub(crate) async fn start() -> anyhow::Result<()> {
 /// not a model, in charge of when to stop — re-running research with the
 /// reviewer's feedback folded in until it approves or the round budget runs
 /// out, then writing the report from whatever the last pass produced.
-async fn research(topic: &str) -> anyhow::Result<String> {
+async fn research(topic: &str, show_progress: bool) -> anyhow::Result<String> {
     let client = ollama::Client::new(Nothing)?;
 
     let mut findings = String::new();
     let mut feedback: Option<Review> = None;
 
     for round in 1..=MAX_RESEARCH_ROUNDS {
-        findings = gather_findings(&client, topic, feedback.as_ref(), round).await?;
+        findings = gather_findings(&client, topic, feedback.as_ref(), round, show_progress).await?;
 
-        let review = review::review_findings(&client, topic, &findings).await?;
+        let review = review::review_findings(&client, topic, &findings, show_progress).await?;
         let approved = review.approved;
 
         tracing::info!(round, approved, "review verdict");
@@ -73,7 +96,7 @@ async fn research(topic: &str) -> anyhow::Result<String> {
         feedback = Some(review);
     }
 
-    write_report(&client, topic, &findings).await
+    write_report(&client, topic, &findings, show_progress).await
 }
 
 /// Wraps the tool-calling research loop in its own span so it's visible as a
@@ -85,6 +108,7 @@ async fn gather_findings(
     topic: &str,
     feedback: Option<&Review>,
     round: usize,
+    show_progress: bool,
 ) -> anyhow::Result<String> {
     let current_date = chrono::offset::Local::now().to_string();
 
@@ -127,12 +151,14 @@ async fn gather_findings(
         ),
     };
 
+    let spinner = Spinner::start(show_progress, "Researching...");
     let findings = researcher
         .runner(task)
         .max_turns(MAX_RESEARCH_TURNS)
         .run()
         .await?
         .output;
+    drop(spinner);
 
     tracing::info!(round, findings = %findings, "research phase complete");
 
@@ -144,6 +170,7 @@ async fn write_report(
     client: &ollama::Client,
     topic: &str,
     findings: &str,
+    show_progress: bool,
 ) -> anyhow::Result<String> {
     let writer = client
         .agent(WRITER_MODEL)
@@ -160,9 +187,11 @@ async fn write_report(
         )
         .build();
 
+    let spinner = Spinner::start(show_progress, "Writing report...");
     let report = writer
         .prompt(format!("Topic: {topic}\n\nResearch notes:\n{findings}"))
         .await?;
+    drop(spinner);
 
     Ok(report)
 }