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;
75
76/// Prelude - commonly used types for convenient import
77pub mod prelude {
78    pub use crate::actions::{
79        ActionDef, ActionGroup, ActionValidationError, ActionsConfig, ParamDef,
80    };
81    pub use crate::agent::{
82        BatchDecisionRequest, DecisionResponse, Guidance, ManagementDecision, ManagementStrategy,
83        ManagerAgent, ManagerId, Priority, ScheduledAction, TaskContext, WorkResult, WorkerAgent,
84        WorkerDecisionRequest,
85    };
86    pub use crate::async_task::{AsyncTask, AsyncTaskResult, AsyncTaskSystem, TaskStatus};
87    pub use crate::config::{GlobalConfig, PathResolver};
88    pub use crate::environment::{DefaultEnvironment, Environment, EnvironmentBox};
89    pub use crate::error::SwarmError;
90    pub use crate::events::{
91        create_action_event_publisher, ActionContext, ActionEvent, ActionEventBuilder,
92        ActionEventId, ActionEventPublisher, ActionEventResult, JsonlWriter,
93    };
94    pub use crate::extensions::Extensions;
95    pub use crate::online_stats::{
96        ActionStats, DumpableStats, GlobalStats, StatsSubscriber, SwarmStats,
97    };
98    pub use crate::orchestrator::{Orchestrator, OrchestratorBuilder, SwarmConfig, SwarmResult};
99    pub use crate::snapshot::{
100        CompactFormatter, ConsoleFormatter, JsonFormatter, SnapshotFormatter, SnapshotOutput,
101    };
102    pub use crate::state::{
103        ActionResultSnapshot, Escalation, EscalationReason, ManagerPhaseSnapshot, SharedState,
104        SwarmState, TickSnapshot, WorkResultSnapshot, WorkerResultSnapshot, WorkerState,
105        WorkerStates,
106    };
107    pub use crate::types::{
108        Action, ActionParams, ActionResult, AgentId, GroupId, SwarmTask, TaskId, WorkerId,
109    };
110
111    // Debug
112    pub use crate::debug::{DebugSnapshot, Dumpable, StderrDumpSubscriber, TickDumper};
113
114    // Pipeline
115    pub use crate::pipeline::{
116        DebounceTransform, EventSink, EventSource, EventTransform, LearningSink,
117        LocalFileWatcherSource, PassthroughTransform, Pipeline, WatchEvent,
118    };
119}
swarm_engine_core/lib.rs

swarm_engine_core/
lib.rs
