awaken 0.4.0

Production AI agent runtime for Rust — type-safe state, phase execution, multi-protocol serving
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

//! The `awaken` facade crate — the primary entry point for building AI agents.
//!
//! This crate re-exports everything you need from the underlying `awaken-*` crates
//! so that user code only needs a single dependency. Start with [`prelude`] for a
//! one-import convenience layer, or access individual modules directly.
//!
//! # Quick start
//!
//! ```rust,ignore
//! use awaken::prelude::*;
//! use awaken::engine::GenaiExecutor;
//!
//! # async fn run() -> Result<(), Box<dyn std::error::Error>> {
//! let runtime = AgentRuntimeBuilder::new()
//!     .with_agent_spec(AgentSpec::new("assistant").with_model_id("gpt-4o-mini"))
//!     .with_provider("openai", Arc::new(GenaiExecutor::new()))
//!     .with_model_binding("gpt-4o-mini", ModelBinding {
//!         provider_id: "openai".into(),
//!         upstream_model: "gpt-4o-mini".into(),
//!     })
//!     .build()?;
//!
//! let request = RunRequest::new("thread-1", vec![Message::user("Hello")])
//!     .with_agent_id("assistant");
//!
//! let result = runtime.run_to_completion(request).await?;
//! let response = result.response;
//! # let _ = response;
//! # Ok(())
//! # }
//! ```
//!
//! # Module layout
//!
//! | Path | Description |
//! |------|-------------|
//! | [`prelude`] | One-stop import for common agent-building types |
//! | [`contract`] | Core protocol traits: tools, inference, events, lifecycle |
//! | [`model`] | Data-model primitives: phases, effects, scheduled actions |
//! | [`state`] | State key/value types and mutation primitives |
//! | [`registry`] | Agent registry and resolution |
//! | [`builder`] | [`AgentRuntimeBuilder`] — fluent runtime construction |
//! | [`plugins`] | Plugin trait and descriptor types |
//! | [`phase`] | Phase execution context and hooks |
//! | [`engine`] | Low-level agent execution engine |
//! | [`stores`] | Storage backend implementations |
//! | [`server`] | HTTP server layer (feature `server`) |

pub mod prelude;

/// Storage backend implementations (in-memory, file, PostgreSQL, SQLite mailbox).
pub use awaken_stores as stores;

/// Generative-UI extension (feature `generative-ui`).
#[cfg(feature = "generative-ui")]
pub use awaken_ext_generative_ui as ext_generative_ui;

/// MCP (Model Context Protocol) tool-bridge extension (feature `mcp`).
#[cfg(feature = "mcp")]
pub use awaken_ext_mcp as ext_mcp;

/// Observability / tracing extension (feature `observability`).
#[cfg(feature = "observability")]
pub use awaken_ext_observability as ext_observability;

/// Tool-permission / human-in-the-loop extension (feature `permission`).
#[cfg(feature = "permission")]
pub use awaken_ext_permission as ext_permission;

/// Reminder / periodic-context-injection extension (feature `reminder`).
#[cfg(feature = "reminder")]
pub use awaken_ext_reminder as ext_reminder;

/// Skills discovery and dispatch extension (feature `skills`).
#[cfg(feature = "skills")]
pub use awaken_ext_skills as ext_skills;

/// HTTP server layer (feature `server`).
#[cfg(feature = "server")]
pub use awaken_server as server;

// ── Sub-crate module re-exports ──

/// Core protocol traits: tools, inference, events, lifecycle, storage contracts.
pub use awaken_contract::contract;

/// Data-model primitives: phases, effects, scheduled actions.
pub use awaken_contract::model;

/// Agent-registry specification types.
pub use awaken_contract::registry_spec;

/// Fluent builder for constructing an [`AgentRuntime`].
pub use awaken_runtime::builder;

/// Execution context and request/response wrappers.
pub use awaken_runtime::context;

/// Low-level agent execution engine.
pub use awaken_runtime::engine;

/// Execution-environment helpers and run orchestration.
pub use awaken_runtime::execution;

/// Extension-point traits for integrating with the runtime.
pub use awaken_runtime::extensions;

/// Agent run-loop runner.
pub use awaken_runtime::loop_runner;

/// Phase execution context, hooks, and phase-level runtime.
pub use awaken_runtime::phase;

/// Plugin loading, descriptor registry, and registration API.
pub use awaken_runtime::plugins;

/// Stop policies and run-termination conditions.
pub use awaken_runtime::policies;

/// Agent registry lookup and resolution.
pub use awaken_runtime::registry;

/// [`AgentRuntime`] and [`RunRequest`] — the top-level run API.
pub use awaken_runtime::runtime;

/// Agent configuration and instance types.
pub use awaken_runtime::agent;

/// Combined state types from both the contract and runtime layers.
pub mod state {
    pub use awaken_contract::state::*;
    pub use awaken_runtime::state::{
        CommitEvent, CommitHook, MutationBatch, StateCommand, StateStore,
    };
}

// ── Flat re-exports: most commonly used types at crate root ──

// contract types
pub use awaken_contract::{
    AgentSpec, EffectSpec, FailedScheduledActions, JsonValue, KeyScope, MergeStrategy,
    PendingScheduledActions, PersistedState, Phase, PluginConfigKey, RedactedString,
    ScheduledActionSpec, Snapshot, StateError, StateKey, StateKeyOptions, StateMap, TypedEffect,
    TypedTool, UnknownKeyPolicy, generate_tool_schema, sanitize_for_llm, validate_against_schema,
};

// runtime types
pub use awaken_runtime::{
    AgentResolver, AgentRuntime, AgentRuntimeBuilder, BuildError, CancellationToken, CommitEvent,
    CommitHook, DEFAULT_MAX_PHASE_ROUNDS, ExecutionEnv, MutationBatch, PhaseContext, PhaseHook,
    PhaseRuntime, Plugin, PluginDescriptor, PluginRegistrar, ResolvedAgent, RunRequest,
    RuntimeError, StateCommand, StateStore, ToolGateHook, TypedEffectHandler,
    TypedScheduledActionHandler,
};