deepstrike 0.2.6__tar.gz → 0.2.7__tar.gz

{deepstrike-0.2.6 → deepstrike-0.2.7}/Cargo.lock

@@ -194,7 +194,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-core"
-version = "0.2.6"
+version = "0.2.7"
 dependencies = [
  "compact_str",
  "pretty_assertions",
@@ -206,7 +206,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-node"
-version = "0.2.6"
+version = "0.2.7"
 dependencies = [
  "compact_str",
  "deepstrike-core",
@@ -218,7 +218,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-py"
-version = "0.2.6"
+version = "0.2.7"
 dependencies = [
  "compact_str",
  "deepstrike-core",
@@ -229,7 +229,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-sdk"
-version = "0.2.6"
+version = "0.2.7"
 dependencies = [
  "async-stream",
  "async-trait",
@@ -263,7 +263,7 @@ dependencies = [
 
 [[package]]
 name = "deepstrike-wasm"
-version = "0.2.6"
+version = "0.2.7"
 dependencies = [
  "compact_str",
  "deepstrike-core",

{deepstrike-0.2.6 → deepstrike-0.2.7}/Cargo.toml

@@ -3,13 +3,13 @@ resolver = "2"
 members = ["crates/deepstrike-core", "crates/deepstrike-py"]
 
 [workspace.package]
-version = "0.2.6"
+version = "0.2.7"
 edition = "2024"
 license = "MIT"
 repository = "https://github.com/kongusen/deepstrike"
 
 [workspace.dependencies]
-deepstrike-core = { path = "crates/deepstrike-core", version = "0.2.6" }
+deepstrike-core = { path = "crates/deepstrike-core", version = "0.2.7" }
 notify = "6"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"

{deepstrike-0.2.6 → deepstrike-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepstrike
-Version: 0.2.6
+Version: 0.2.7
 Requires-Dist: httpx>=0.27
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: anyio>=4.0

deepstrike-0.2.7/crates/deepstrike-core/src/orchestration/loop_until_done.rs

@@ -0,0 +1,281 @@
+//! Loop-until-done — drive an agent round after round until a stop predicate fires.
+//!
+//! For tasks with an unknown amount of work (keep investigating until no new findings;
+//! keep fixing until no more errors). Mirrors [`super::gen_eval::GenEvalLoop`]: a pure
+//! control state machine emitting **abstract actions**; the SDK spawns a worker per round
+//! and feeds back what that round produced. No I/O, no clock.
+//!
+//! Termination is guaranteed *in-kernel*: a [`StopCondition::MaxRounds`] backstop is always
+//! present (injected with [`DEFAULT_MAX_ROUNDS`] if the caller configured none), so the loop
+//! cannot run forever regardless of SDK behavior. Wall-clock / token backstops are an
+//! orthogonal concern owned by the SDK's [`crate::scheduler::policy::SchedulerBudget`]
+//! wrapped around the loop — this state machine stays zero-clock.
+
+/// Default hard round cap injected when the caller configures no [`StopCondition::MaxRounds`].
+pub const DEFAULT_MAX_ROUNDS: u32 = 50;
+
+/// A stop predicate. The loop stops as soon as **any** configured condition fires.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum StopCondition {
+    /// The round produced no new findings (`new_findings == 0`).
+    NoNewFindings,
+    /// The round reported no errors (`errors == 0`).
+    NoErrors,
+    /// Hard cap: stop once this many rounds have completed.
+    MaxRounds(u32),
+}
+
+/// Loop configuration. Always carries a `MaxRounds` backstop after construction.
+#[derive(Debug, Clone)]
+pub struct LoopConfig {
+    conditions: Vec<StopCondition>,
+}
+
+impl LoopConfig {
+    /// Build a config. If no [`StopCondition::MaxRounds`] is present, a
+    /// [`DEFAULT_MAX_ROUNDS`] backstop is appended so termination is guaranteed.
+    pub fn new(conditions: Vec<StopCondition>) -> Self {
+        let has_max = conditions
+            .iter()
+            .any(|c| matches!(c, StopCondition::MaxRounds(_)));
+        let mut conditions = conditions;
+        if !has_max {
+            conditions.push(StopCondition::MaxRounds(DEFAULT_MAX_ROUNDS));
+        }
+        Self { conditions }
+    }
+
+    pub fn conditions(&self) -> &[StopCondition] {
+        &self.conditions
+    }
+}
+
+impl Default for LoopConfig {
+    fn default() -> Self {
+        Self::new(Vec::new())
+    }
+}
+
+/// What the SDK reports after running a round's worker.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct RoundReport {
+    pub new_findings: u32,
+    pub errors: u32,
+}
+
+/// Why the loop stopped.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum StopReason {
+    NoNewFindings,
+    NoErrors,
+    MaxRounds,
+}
+
+/// What the SDK should do next.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum LoopAction {
+    /// Spawn the worker for round `round`, then call [`LoopUntilDone::feed`] with its report.
+    Spawn { round: u32 },
+    /// The loop converged.
+    Done {
+        rounds_used: u32,
+        reason: StopReason,
+    },
+}
+
+/// Loop-until-done control state machine.
+#[derive(Debug)]
+pub struct LoopUntilDone {
+    config: LoopConfig,
+    /// Round currently in flight (the last one emitted by `start`/`feed`).
+    round: u32,
+    done: bool,
+}
+
+impl LoopUntilDone {
+    pub fn new(config: LoopConfig) -> Self {
+        Self {
+            config,
+            round: 0,
+            done: false,
+        }
+    }
+
+    /// Begin the loop — always spawns round 1.
+    pub fn start(&mut self) -> LoopAction {
+        self.round = 1;
+        LoopAction::Spawn { round: 1 }
+    }
+
+    /// Feed the just-completed round's report and get the next action.
+    pub fn feed(&mut self, report: RoundReport) -> LoopAction {
+        if self.done {
+            return LoopAction::Done {
+                rounds_used: self.round,
+                reason: StopReason::MaxRounds,
+            };
+        }
+
+        if let Some(reason) = self.first_triggered(&report) {
+            self.done = true;
+            return LoopAction::Done {
+                rounds_used: self.round,
+                reason,
+            };
+        }
+
+        self.round += 1;
+        LoopAction::Spawn { round: self.round }
+    }
+
+    /// Return the reason for the first stop condition (in configured order) that fires for
+    /// the just-completed round (`self.round`).
+    fn first_triggered(&self, report: &RoundReport) -> Option<StopReason> {
+        for cond in &self.config.conditions {
+            let hit = match cond {
+                StopCondition::NoNewFindings => report.new_findings == 0,
+                StopCondition::NoErrors => report.errors == 0,
+                StopCondition::MaxRounds(max) => self.round >= *max,
+            };
+            if hit {
+                return Some(match cond {
+                    StopCondition::NoNewFindings => StopReason::NoNewFindings,
+                    StopCondition::NoErrors => StopReason::NoErrors,
+                    StopCondition::MaxRounds(_) => StopReason::MaxRounds,
+                });
+            }
+        }
+        None
+    }
+
+    pub fn is_done(&self) -> bool {
+        self.done
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn report(new_findings: u32, errors: u32) -> RoundReport {
+        RoundReport {
+            new_findings,
+            errors,
+        }
+    }
+
+    #[test]
+    fn default_injects_max_rounds_backstop() {
+        let cfg = LoopConfig::default();
+        assert!(
+            cfg.conditions()
+                .iter()
+                .any(|c| matches!(c, StopCondition::MaxRounds(DEFAULT_MAX_ROUNDS)))
+        );
+    }
+
+    #[test]
+    fn explicit_max_rounds_not_duplicated() {
+        let cfg = LoopConfig::new(vec![StopCondition::MaxRounds(5)]);
+        let maxes: Vec<_> = cfg
+            .conditions()
+            .iter()
+            .filter(|c| matches!(c, StopCondition::MaxRounds(_)))
+            .collect();
+        assert_eq!(maxes.len(), 1);
+    }
+
+    #[test]
+    fn start_spawns_round_one() {
+        let mut l = LoopUntilDone::new(LoopConfig::default());
+        assert_eq!(l.start(), LoopAction::Spawn { round: 1 });
+    }
+
+    #[test]
+    fn stops_on_no_new_findings() {
+        let mut l = LoopUntilDone::new(LoopConfig::new(vec![StopCondition::NoNewFindings]));
+        l.start();
+        // round 1 found things → continue
+        assert_eq!(l.feed(report(3, 0)), LoopAction::Spawn { round: 2 });
+        // round 2 found nothing → stop
+        assert_eq!(
+            l.feed(report(0, 9)),
+            LoopAction::Done {
+                rounds_used: 2,
+                reason: StopReason::NoNewFindings
+            }
+        );
+        assert!(l.is_done());
+    }
+
+    #[test]
+    fn stops_on_no_errors() {
+        let mut l = LoopUntilDone::new(LoopConfig::new(vec![StopCondition::NoErrors]));
+        l.start();
+        assert_eq!(l.feed(report(0, 2)), LoopAction::Spawn { round: 2 });
+        assert_eq!(
+            l.feed(report(0, 0)),
+            LoopAction::Done {
+                rounds_used: 2,
+                reason: StopReason::NoErrors
+            }
+        );
+    }
+
+    #[test]
+    fn max_rounds_caps_the_loop() {
+        let mut l = LoopUntilDone::new(LoopConfig::new(vec![StopCondition::MaxRounds(3)]));
+        l.start();
+        assert_eq!(l.feed(report(1, 1)), LoopAction::Spawn { round: 2 });
+        assert_eq!(l.feed(report(1, 1)), LoopAction::Spawn { round: 3 });
+        assert_eq!(
+            l.feed(report(1, 1)),
+            LoopAction::Done {
+                rounds_used: 3,
+                reason: StopReason::MaxRounds
+            }
+        );
+    }
+
+    #[test]
+    fn default_backstop_terminates_unbounded_predicate() {
+        // NoErrors configured but errors never reach 0 → default MaxRounds(50) must fire.
+        let mut l = LoopUntilDone::new(LoopConfig::new(vec![StopCondition::NoErrors]));
+        let mut action = l.start();
+        let mut last = action;
+        for _ in 0..100 {
+            match action {
+                LoopAction::Spawn { .. } => {
+                    last = action;
+                    action = l.feed(report(1, 1));
+                }
+                LoopAction::Done { .. } => break,
+            }
+        }
+        let _ = last;
+        assert_eq!(
+            action,
+            LoopAction::Done {
+                rounds_used: DEFAULT_MAX_ROUNDS,
+                reason: StopReason::MaxRounds
+            }
+        );
+    }
+
+    #[test]
+    fn first_configured_condition_wins() {
+        // Both NoNewFindings and NoErrors would fire on (0,0); configured order picks the first.
+        let mut l = LoopUntilDone::new(LoopConfig::new(vec![
+            StopCondition::NoNewFindings,
+            StopCondition::NoErrors,
+        ]));
+        l.start();
+        assert_eq!(
+            l.feed(report(0, 0)),
+            LoopAction::Done {
+                rounds_used: 1,
+                reason: StopReason::NoNewFindings
+            }
+        );
+    }
+}

{deepstrike-0.2.6 → deepstrike-0.2.7}/crates/deepstrike-core/src/orchestration/mod.rs

@@ -1,4 +1,7 @@
 pub mod executor;
 pub mod gen_eval;
+pub mod loop_until_done;
 pub mod planner;
 pub mod task_graph;
+pub mod tournament;
+pub mod workflow;

deepstrike-0.2.7/crates/deepstrike-core/src/orchestration/tournament.rs

@@ -0,0 +1,347 @@
+//! Single-elimination tournament — pairwise comparative judging.
+//!
+//! Pattern mirrors [`super::gen_eval::GenEvalLoop`]: a pure control state machine that
+//! holds the bracket and emits **abstract actions**; the SDK runs a fresh-context judge
+//! agent per match and feeds back winners. No prompt assembly, no I/O, no clock.
+//!
+//! Why a tournament instead of absolute scoring: comparative judgment ("which of these
+//! two is better?") is more reliable than asking one agent to score 1000 items, and only
+//! the current round's match-ups ever enter context — the deterministic loop holds the
+//! whole bracket.
+//!
+//! ```text
+//! entrants ──▶ JudgeRound{round 1, matches} ──▶ SDK runs N parallel pairwise judges
+//!                    ▲                                      │
+//!                    └────────── feed_round(winners) ◀──────┘
+//!          (repeat until one survivor) ──▶ Done{winner}
+//! ```
+
+use crate::types::error::{DeepStrikeError, Result};
+
+/// A participant. The SDK maps the id back to the real item being compared.
+pub type EntrantId = String;
+
+/// One pairwise match-up in a round.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Match {
+    /// Index of this match within its round (0-based).
+    pub id: u32,
+    pub left: EntrantId,
+    pub right: EntrantId,
+}
+
+/// What the SDK should do next.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum TournamentAction {
+    /// Run one fresh-context judge per match this round (matches are independent — run
+    /// them in parallel), then call [`Tournament::feed_round`] with the winners.
+    JudgeRound { round: u32, matches: Vec<Match> },
+    /// The bracket is resolved.
+    Done { winner: EntrantId, rounds_used: u32 },
+}
+
+/// Single-elimination bracket control state machine.
+#[derive(Debug)]
+pub struct Tournament {
+    /// Entrants advancing into the next round to be played.
+    survivors: Vec<EntrantId>,
+    /// Matches emitted for the current round, awaiting results.
+    pending: Vec<Match>,
+    /// Entrant that drew a bye this round (odd survivor count) — auto-advances.
+    bye: Option<EntrantId>,
+    /// Number of the most recently emitted round (0 before `start`).
+    round: u32,
+    done: bool,
+}
+
+impl Tournament {
+    /// Build a tournament. Requires at least one entrant.
+    pub fn new(entrants: Vec<EntrantId>) -> Result<Self> {
+        if entrants.is_empty() {
+            return Err(DeepStrikeError::InvalidConfig(
+                "tournament requires at least one entrant".into(),
+            ));
+        }
+        Ok(Self {
+            survivors: entrants,
+            pending: Vec::new(),
+            bye: None,
+            round: 0,
+            done: false,
+        })
+    }
+
+    /// Begin the tournament. A single entrant wins immediately (zero rounds);
+    /// otherwise the first round of match-ups is emitted.
+    pub fn start(&mut self) -> TournamentAction {
+        self.emit_round_or_done()
+    }
+
+    /// Report the winners of the round last emitted by [`TournamentAction::JudgeRound`].
+    /// `winners` must align one-to-one with that round's `matches`, and each winner must
+    /// be one of the two entrants in its match.
+    pub fn feed_round(&mut self, winners: Vec<EntrantId>) -> Result<TournamentAction> {
+        if self.done {
+            return Err(DeepStrikeError::InvalidConfig(
+                "tournament already complete".into(),
+            ));
+        }
+        if winners.len() != self.pending.len() {
+            return Err(DeepStrikeError::InvalidConfig(format!(
+                "expected {} winner(s) for round {}, got {}",
+                self.pending.len(),
+                self.round,
+                winners.len()
+            )));
+        }
+        for (w, m) in winners.iter().zip(&self.pending) {
+            if w != &m.left && w != &m.right {
+                return Err(DeepStrikeError::InvalidConfig(format!(
+                    "winner '{w}' is not a participant in match {}",
+                    m.id
+                )));
+            }
+        }
+
+        let mut next = winners;
+        if let Some(bye) = self.bye.take() {
+            next.push(bye);
+        }
+        self.survivors = next;
+        self.pending.clear();
+        Ok(self.emit_round_or_done())
+    }
+
+    /// Emit the next round of match-ups, or finish if only one survivor remains.
+    fn emit_round_or_done(&mut self) -> TournamentAction {
+        if self.survivors.len() == 1 {
+            self.done = true;
+            return TournamentAction::Done {
+                winner: self.survivors[0].clone(),
+                rounds_used: self.round,
+            };
+        }
+
+        self.round += 1;
+        let mut matches = Vec::with_capacity(self.survivors.len() / 2);
+        let mut i = 0;
+        while i + 1 < self.survivors.len() {
+            matches.push(Match {
+                id: (i / 2) as u32,
+                left: self.survivors[i].clone(),
+                right: self.survivors[i + 1].clone(),
+            });
+            i += 2;
+        }
+        // Odd count → the trailing entrant draws a bye and advances untouched.
+        self.bye = if self.survivors.len() % 2 == 1 {
+            self.survivors.last().cloned()
+        } else {
+            None
+        };
+        self.pending = matches.clone();
+        TournamentAction::JudgeRound {
+            round: self.round,
+            matches,
+        }
+    }
+
+    pub fn is_done(&self) -> bool {
+        self.done
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn ids(xs: &[&str]) -> Vec<EntrantId> {
+        xs.iter().map(|s| s.to_string()).collect()
+    }
+
+    #[test]
+    fn empty_entrants_is_error() {
+        assert!(Tournament::new(vec![]).is_err());
+    }
+
+    #[test]
+    fn single_entrant_wins_immediately() {
+        let mut t = Tournament::new(ids(&["a"])).unwrap();
+        match t.start() {
+            TournamentAction::Done {
+                winner,
+                rounds_used,
+            } => {
+                assert_eq!(winner, "a");
+                assert_eq!(rounds_used, 0);
+            }
+            _ => panic!("expected immediate Done"),
+        }
+        assert!(t.is_done());
+    }
+
+    #[test]
+    fn two_entrants_one_round() {
+        let mut t = Tournament::new(ids(&["a", "b"])).unwrap();
+        match t.start() {
+            TournamentAction::JudgeRound { round, matches } => {
+                assert_eq!(round, 1);
+                assert_eq!(matches.len(), 1);
+                assert_eq!(
+                    matches[0],
+                    Match {
+                        id: 0,
+                        left: "a".into(),
+                        right: "b".into()
+                    }
+                );
+            }
+            _ => panic!("expected JudgeRound"),
+        }
+        match t.feed_round(ids(&["b"])).unwrap() {
+            TournamentAction::Done {
+                winner,
+                rounds_used,
+            } => {
+                assert_eq!(winner, "b");
+                assert_eq!(rounds_used, 1);
+            }
+            _ => panic!("expected Done"),
+        }
+    }
+
+    #[test]
+    fn four_entrants_two_rounds() {
+        let mut t = Tournament::new(ids(&["a", "b", "c", "d"])).unwrap();
+        let r1 = t.start();
+        match r1 {
+            TournamentAction::JudgeRound { round, matches } => {
+                assert_eq!(round, 1);
+                assert_eq!(matches.len(), 2);
+            }
+            _ => panic!(),
+        }
+        // a beats b, d beats c
+        let r2 = t.feed_round(ids(&["a", "d"])).unwrap();
+        match r2 {
+            TournamentAction::JudgeRound { round, matches } => {
+                assert_eq!(round, 2);
+                assert_eq!(matches.len(), 1);
+                assert_eq!(
+                    matches[0],
+                    Match {
+                        id: 0,
+                        left: "a".into(),
+                        right: "d".into()
+                    }
+                );
+            }
+            _ => panic!(),
+        }
+        match t.feed_round(ids(&["d"])).unwrap() {
+            TournamentAction::Done {
+                winner,
+                rounds_used,
+            } => {
+                assert_eq!(winner, "d");
+                assert_eq!(rounds_used, 2);
+            }
+            _ => panic!(),
+        }
+    }
+
+    #[test]
+    fn three_entrants_bye_advances() {
+        let mut t = Tournament::new(ids(&["a", "b", "c"])).unwrap();
+        match t.start() {
+            TournamentAction::JudgeRound { round, matches } => {
+                assert_eq!(round, 1);
+                // only (a,b) plays; c gets a bye
+                assert_eq!(matches.len(), 1);
+                assert_eq!(
+                    matches[0],
+                    Match {
+                        id: 0,
+                        left: "a".into(),
+                        right: "b".into()
+                    }
+                );
+            }
+            _ => panic!(),
+        }
+        // a beats b; survivors = [a, c (bye)]
+        match t.feed_round(ids(&["a"])).unwrap() {
+            TournamentAction::JudgeRound { round, matches } => {
+                assert_eq!(round, 2);
+                assert_eq!(
+                    matches[0],
+                    Match {
+                        id: 0,
+                        left: "a".into(),
+                        right: "c".into()
+                    }
+                );
+            }
+            _ => panic!(),
+        }
+        match t.feed_round(ids(&["c"])).unwrap() {
+            TournamentAction::Done {
+                winner,
+                rounds_used,
+            } => {
+                assert_eq!(winner, "c");
+                assert_eq!(rounds_used, 2);
+            }
+            _ => panic!(),
+        }
+    }
+
+    #[test]
+    fn eight_entrants_three_rounds() {
+        let mut t = Tournament::new(ids(&["1", "2", "3", "4", "5", "6", "7", "8"])).unwrap();
+        let mut action = t.start();
+        let mut last_round = 0;
+        loop {
+            match action {
+                TournamentAction::JudgeRound { round, matches } => {
+                    last_round = round;
+                    // winners = the left entrant of each match (deterministic)
+                    let winners: Vec<EntrantId> = matches.iter().map(|m| m.left.clone()).collect();
+                    action = t.feed_round(winners).unwrap();
+                }
+                TournamentAction::Done {
+                    winner,
+                    rounds_used,
+                } => {
+                    assert_eq!(winner, "1");
+                    assert_eq!(rounds_used, 3);
+                    assert_eq!(last_round, 3);
+                    break;
+                }
+            }
+        }
+    }
+
+    #[test]
+    fn wrong_winner_count_is_error() {
+        let mut t = Tournament::new(ids(&["a", "b", "c", "d"])).unwrap();
+        t.start();
+        // round 1 has 2 matches; feeding 1 winner is invalid
+        assert!(t.feed_round(ids(&["a"])).is_err());
+    }
+
+    #[test]
+    fn winner_not_in_match_is_error() {
+        let mut t = Tournament::new(ids(&["a", "b"])).unwrap();
+        t.start();
+        assert!(t.feed_round(ids(&["zzz"])).is_err());
+    }
+
+    #[test]
+    fn feed_after_done_is_error() {
+        let mut t = Tournament::new(ids(&["a", "b"])).unwrap();
+        t.start();
+        t.feed_round(ids(&["a"])).unwrap();
+        assert!(t.feed_round(ids(&["a"])).is_err());
+    }
+}