awaken-runtime 0.5.0

Phase-based execution engine, plugin system, and agent loop for Awaken
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

//! Credential management for LLM providers.
//!
//! All provider auth — static bearer tokens, OAuth via service-account JWT,
//! and (future) AWS SigV4 / Azure client secret — flows through the
//! [`CredentialBroker`] trait. The broker:
//! - parses credential material from `ProviderSpec` at config write time,
//! - caches minted tokens until near expiry,
//! - serialises concurrent refreshes ("single-flight") so a token rotation
//!   does not stampede the upstream OAuth endpoint.
//!
//! ## Why a broker?
//! Earlier revisions of awaken passed credentials directly to genai via
//! `with_auth_resolver_fn`, which works fine for pre-signed bearers but
//! fans out into ad-hoc per-provider refresh code as soon as you add
//! anything dynamic (Vertex AI service accounts, AWS SigV4, …). The
//! broker is the dedicated owner: one place to look at all auth, one
//! trait to mock in tests, one observability hook to instrument.
//!
//! Static bearers bypass the broker on the production hot path (see
//! `awaken_server::services::config_runtime::build_genai_provider_executor`)
//! because there is no token to refresh — it is identical to 0.4.0 wiring.
//! The broker still accepts static-bearer material for embedders that
//! want everything funnelled through one chokepoint and for tests.
//!
//! ## Configuration discriminator
//! `ProviderSpec.adapter_options.credentials_kind` selects how the broker
//! interprets `ProviderSpec.api_key`:
//!
//! | `credentials_kind`         | `api_key` payload                  | Refresh         |
//! |----------------------------|------------------------------------|-----------------|
//! | absent / `"bearer"`        | OAuth bearer or static API key     | operator-managed|
//! | `"service_account_json"`   | full Google service-account JSON   | broker, automatic|
//!
//! Compatibility rules and validation live in [`material::build_material`].
//!
//! ## Disabled-feature gating
//! `service_account_json` requires the `credentials-google` cargo feature.
//! When the feature is off, `build_material` rejects the configuration at
//! the server boundary (config write time) with a clear error — there is
//! no runtime stub mod swapped in via cfg.

pub mod broker;
pub mod error;
pub mod material;
mod minter;

#[cfg(any(test, feature = "credentials-google"))]
pub mod google_oauth;

mod token;

pub use broker::{AwakenCredentialBroker, CredentialBroker, CredentialRetryPolicy};
pub use error::CredentialError;
pub use material::{CredentialKind, CredentialMaterial, GoogleServiceAccountKey, build_material};
pub use token::IssuedToken;