swarm_engine_core/
lib.rs

1//! # SwarmEngine Core
2//!
3//! A general-purpose foundation for high-throughput, low-latency agent swarm processing.
4//!
5//! ## Design Philosophy
6//!
7//! - Game engine-like architecture, specialized for agent swarms
8//! - Tick-driven execution (10ms intervals) for stable operation
9//! - Long-running support (24+ hours)
10//! - Zero-copy, lock-free design
11//!
12//! ## Core Concepts
13//!
14//! ### Two-Tier Memory Model
15//!
16//! - **SharedState**: Read-only shared region accessed by all workers
17//! - **WorkerStates**: Per-worker persistent state (optimized for parallel access)
18//!
19//! ### Tick Lifecycle
20//!
21//! ```text
22//! Tick N
23//! ├─ 1. Collect Async Results
24//! ├─ 2. Read Phase (Scheduler)
25//! ├─ 3. Execute Phase (Workers)
26//! ├─ 4. Merge Phase
27//! ├─ 5. Tick++
28//! └─ 6. Wait for next tick
29//! ```
30//!
31//! ## SwarmApp
32//!
33//! `SwarmApp` is an integrated application container providing:
34//!
35//! - **Unified Runtime**: Easy-to-use interface wrapping the Orchestrator
36//! - **External Control**: Control from outside via `tick()` / `inject_state()` etc.
37//! - **Hierarchical Hook System**: 4-layer intervention at Tick / Manager / Worker / Action
38//! - **Effect System**: Declarative expression of hook side effects
39//! - **Extensions**: Bevy-style dynamic resource management
40//!
41//! ```ignore
42//! use swarm_engine_core::app::prelude::*;
43//!
44//! let app = SwarmApp::<()>::builder()
45//!     .config(AppConfig::default())
46//!     .workers(workers)
47//!     .tick_hook(LoggingTickHook::new())
48//!     .build(runtime.handle().clone())?;
49//!
50//! let outcome = app.run();
51//! ```
52
53pub mod actions;
54pub mod agent;
55pub mod analysis;
56// pub mod app;  // TODO: Orchestrator 安定後に再統合
57pub mod async_task;
58pub mod config;
59pub mod context;
60pub mod debug;
61pub mod environment;
62pub mod error;
63pub mod events;
64pub mod exploration;
65pub mod extensions;
66pub mod learn;
67pub mod online_stats;
68pub mod orchestrator;
69pub mod pipeline;
70pub mod snapshot;
71pub mod state;
72pub mod telemetry;
73pub mod types;
74pub mod util;
75pub mod validation;
76
77/// Prelude - commonly used types for convenient import
78pub mod prelude {
79    pub use crate::actions::{
80        ActionDef, ActionGroup, ActionValidationError, ActionsConfig, ParamDef,
81    };
82    pub use crate::agent::{
83        BatchDecisionRequest, DecisionResponse, Guidance, ManagementDecision, ManagementStrategy,
84        ManagerAgent, ManagerId, Priority, ScheduledAction, TaskContext, WorkResult, WorkerAgent,
85        WorkerDecisionRequest,
86    };
87    pub use crate::async_task::{AsyncTask, AsyncTaskResult, AsyncTaskSystem, TaskStatus};
88    pub use crate::config::{GlobalConfig, PathResolver};
89    pub use crate::environment::{DefaultEnvironment, Environment, EnvironmentBox};
90    pub use crate::error::SwarmError;
91    pub use crate::events::{
92        create_action_event_publisher, ActionContext, ActionEvent, ActionEventBuilder,
93        ActionEventId, ActionEventPublisher, ActionEventResult, JsonlWriter,
94    };
95    pub use crate::extensions::Extensions;
96    pub use crate::online_stats::{
97        ActionStats, DumpableStats, GlobalStats, StatsSubscriber, SwarmStats,
98    };
99    pub use crate::orchestrator::{Orchestrator, OrchestratorBuilder, SwarmConfig, SwarmResult};
100    pub use crate::snapshot::{
101        CompactFormatter, ConsoleFormatter, JsonFormatter, SnapshotFormatter, SnapshotOutput,
102    };
103    pub use crate::state::{
104        ActionResultSnapshot, Escalation, EscalationReason, ManagerPhaseSnapshot, SharedState,
105        SwarmState, TickSnapshot, WorkResultSnapshot, WorkerResultSnapshot, WorkerState,
106        WorkerStates,
107    };
108    pub use crate::types::{
109        Action, ActionParams, ActionResult, AgentId, GroupId, SwarmTask, TaskId, WorkerId,
110    };
111
112    // Debug
113    pub use crate::debug::{DebugSnapshot, Dumpable, StderrDumpSubscriber, TickDumper};
114
115    // Pipeline
116    pub use crate::pipeline::{
117        DebounceTransform, EventSink, EventSource, EventTransform, LearningSink,
118        LocalFileWatcherSource, PassthroughTransform, Pipeline, WatchEvent,
119    };
120
121    // Validation
122    pub use crate::validation::{
123        Absolute, Improvement, NoRegression, ValidationResult, ValidationStrategy, Validator,
124    };
125}
swarm_engine_core/lib.rs

swarm_engine_core/
lib.rs
