converge_pack/
agent.rs

1// Copyright 2024-2026 Reflective Labs
2
3// SPDX-License-Identifier: MIT
4
5//! The Suggestor trait — the contract all suggestor implementations satisfy.
6//!
7//! # Why this shape?
8//!
9//! Suggestors in Converge are not actors, not services, not workflow steps.
10//! They are pure functions over context: given the current state of shared
11//! context, a suggestor decides whether to act (`accepts`) and what to
12//! contribute (`execute`).
13//!
14//! This design makes suggestors:
15//! - **Deterministic**: same context → same decision.
16//! - **Composable**: suggestors don't know about each other, only about context.
17//! - **Testable**: mock the context, assert the effect.
18//!
19//! # Critical rules
20//!
21//! - `accepts()` must be **pure** — no side effects, no I/O, no mutations.
22//! - `execute()` is **read-only** — it reads context and returns an effect.
23//! - Suggestors **never call other suggestors** — all communication via shared context.
24//! - **Idempotency is context-based** — check for existing contributions in
25//!   context, not internal state. Internal `has_run` flags violate the
26//!   "context is the only shared state" axiom.
27
28use crate::context::{Context, ContextKey};
29use crate::effect::AgentEffect;
30
31/// The core suggestor contract.
32///
33/// Every suggestor in the Converge ecosystem implements this trait — whether
34/// it wraps an LLM, a policy engine, an optimizer, analytics, knowledge
35/// retrieval, or a simple rule.
36///
37/// The engine calls `accepts()` to determine eligibility, then `execute()`
38/// to collect effects. Effects are merged by the engine in deterministic
39/// registration order via [`crate::types::SuggestorId`].
40///
41/// # Async
42///
43/// `execute()` is async, allowing suggestors to call LLM providers, search
44/// backends, and other I/O without blocking. The engine awaits each
45/// suggestor and controls concurrency — suggestors don't need to manage
46/// their own parallelism.
47///
48/// # Thread Safety
49///
50/// Suggestors must be `Send + Sync` because the engine may execute eligible
51/// suggestors concurrently in the future.
52#[async_trait::async_trait]
53pub trait Suggestor: Send + Sync {
54    /// Human-readable name, used for logging and provenance.
55    ///
56    /// Must be unique within a convergence run. Deterministic execution order
57    /// is derived from registration order, not lexical name sorting.
58    fn name(&self) -> &str;
59
60    /// Context keys this suggestor reads from.
61    ///
62    /// The engine uses this to determine when a suggestor becomes eligible:
63    /// a suggestor is a candidate when at least one of its dependency keys
64    /// has been modified since the last cycle.
65    fn dependencies(&self) -> &[ContextKey];
66
67    /// Pure predicate: should this suggestor execute given the current context?
68    ///
69    /// # Contract
70    ///
71    /// - Must be **pure**: no side effects, no I/O, no state mutation.
72    /// - Must be **deterministic**: same context → same answer.
73    /// - Must check **idempotency via context**: look for your own
74    ///   contributions in context (both `Proposals` and target key),
75    ///   not internal flags.
76    fn accepts(&self, ctx: &dyn Context) -> bool;
77
78    /// Produce effects given the current context.
79    ///
80    /// # Contract
81    ///
82    /// - **Read-only**: do not mutate context. Return effects instead.
83    /// - Effects are collected by the engine and merged after all
84    ///   eligible suggestors have executed.
85    /// - For LLM suggestors: emit `ProposedFact` to `ContextKey::Proposals`,
86    ///   not directly to the target key.
87    async fn execute(&self, ctx: &dyn Context) -> AgentEffect;
88
89    /// Algorithmic complexity of this suggestor's core computation.
90    ///
91    /// Returns a short string describing time complexity and practical scale
92    /// guidance. `None` means negligible / not applicable (e.g. pure LLM
93    /// calls where latency is network-bound, not algorithmic).
94    ///
95    /// Examples: `"O(n³) — n = agents/tasks, practical for n ≤ 500"`
96    fn complexity_hint(&self) -> Option<&'static str> {
97        None
98    }
99}
converge_pack/agent.rs

converge_pack/
agent.rs
