ainl_runtime/
hooks.rs

1//! Integration seam for hosts (e.g. OpenFang) — all methods default to no-ops.
2
3use uuid::Uuid;
4
5use crate::engine::{MemoryContext, TurnOutcome};
6use ainl_graph_extractor::ExtractionReport;
7
8#[cfg(feature = "async")]
9use crate::engine::{PatchDispatchContext, TurnInput};
10
11/// Hooks for observability and host wiring. Every method has a default empty body.
12pub trait TurnHooks: Send + Sync {
13    fn on_artifact_loaded(&self, _agent_id: &str, _node_count: usize) {}
14    fn on_persona_compiled(&self, _contribution: Option<&str>) {}
15    fn on_memory_context_ready(&self, _ctx: &MemoryContext) {}
16    fn on_episode_recorded(&self, _episode_id: Uuid) {}
17    fn on_patch_dispatched(&self, _label: &str, _fitness: f32) {}
18    fn on_extraction_complete(&self, _report: &ExtractionReport) {}
19    fn on_emit(&self, _target: &str, _payload: &serde_json::Value) {}
20    fn on_turn_complete(&self, _outcome: &TurnOutcome) {}
21}
22
23/// Default hook implementation (no side effects).
24pub struct NoOpHooks;
25
26impl TurnHooks for NoOpHooks {}
27
28/// Async observability hooks for [`crate::AinlRuntime::run_turn_async`] (Tokio-friendly).
29///
30/// Graph SQLite I/O for that path runs on `tokio::task::spawn_blocking`; the graph itself stays
31/// under `Arc<std::sync::Mutex<_>>` (not `tokio::sync::Mutex`) so the runtime can be constructed and
32/// queried from any thread. See the crate root docs and `README.md`.
33#[cfg(feature = "async")]
34#[async_trait::async_trait]
35pub trait TurnHooksAsync: Send + Sync {
36    async fn on_turn_start(&self, _input: &TurnInput) {}
37
38    async fn on_patch_dispatched(
39        &self,
40        _ctx: &PatchDispatchContext<'_>,
41    ) -> Result<serde_json::Value, String> {
42        Ok(serde_json::Value::Null)
43    }
44
45    async fn on_turn_complete(&self, _outcome: &TurnOutcome) {}
46}
47
48/// Default async hook implementation (no side effects).
49#[cfg(feature = "async")]
50pub struct NoOpAsyncHooks;
51
52#[cfg(feature = "async")]
53#[async_trait::async_trait]
54impl TurnHooksAsync for NoOpAsyncHooks {}
ainl_runtime/hooks.rs

ainl_runtime/
hooks.rs
