gemini_adk_rs/live/
contract.rs

1//! Runtime contract introspection for Live sessions.
2//!
3//! A contract is a serializable description of the runtime configuration:
4//! phases, tools, extractors, promotions, watchers, and control-plane knobs.
5//! It intentionally describes stable metadata only; closures are represented
6//! as booleans or human-readable predicate/debug labels.
7
8use serde::{Deserialize, Serialize};
9
10/// Serializable description of a configured Live runtime.
11#[derive(Debug, Clone, Serialize, Deserialize, Default)]
12pub struct RuntimeContract {
13    /// Contract schema version.
14    pub version: u32,
15    /// Configured Gemini model id.
16    pub model: String,
17    /// Tool declarations visible to the model.
18    pub tools: Vec<ToolContract>,
19    /// Conversation phase graph.
20    pub phases: Vec<PhaseContract>,
21    /// Initial phase name, when configured.
22    pub initial_phase: Option<String>,
23    /// Turn extractors and their promotion policy.
24    pub extractors: Vec<ExtractorContract>,
25    /// Computed state declarations.
26    pub computed: Vec<ComputedContract>,
27    /// State watcher declarations.
28    pub watchers: Vec<WatcherContract>,
29    /// Runtime and voice control settings.
30    pub controls: ControlContract,
31}
32
33/// A tool declaration in the runtime contract.
34#[derive(Debug, Clone, Serialize, Deserialize)]
35pub struct ToolContract {
36    /// Function/tool name.
37    pub name: String,
38    /// Tool description.
39    pub description: String,
40    /// Tool behavior, when declared by the target platform.
41    pub behavior: Option<String>,
42}
43
44/// A conversation phase declaration.
45#[derive(Debug, Clone, Serialize, Deserialize)]
46pub struct PhaseContract {
47    /// Phase name.
48    pub name: String,
49    /// Whether this phase is terminal.
50    pub terminal: bool,
51    /// Tools enabled in the phase; `None` means all tools.
52    pub tools_enabled: Option<Vec<String>>,
53    /// State keys this phase gathers.
54    pub needs: Vec<String>,
55    /// State keys required before entering the phase.
56    pub requires: Vec<String>,
57    /// Preparation effects registered for this phase.
58    pub preparations: Vec<PreparationContract>,
59    /// Semantic concepts presented on phase entry.
60    pub presents: Vec<String>,
61    /// State keys cleared on phase entry.
62    pub clear_on_enter: Vec<String>,
63    /// Outbound transitions.
64    pub transitions: Vec<TransitionContract>,
65    /// Whether the phase has an entry guard closure.
66    pub has_guard: bool,
67    /// Whether the phase prompts the model immediately on entry.
68    pub prompt_on_enter: bool,
69}
70
71/// A phase transition declaration.
72#[derive(Debug, Clone, Serialize, Deserialize)]
73pub struct TransitionContract {
74    /// Target phase.
75    pub target: String,
76    /// Human-readable transition description, when provided.
77    pub description: Option<String>,
78    /// Guards are closures, so this marks that a guard exists.
79    pub has_guard: bool,
80}
81
82/// A phase preparation declaration.
83#[derive(Debug, Clone, Serialize, Deserialize)]
84pub struct PreparationContract {
85    /// Preparation name.
86    pub name: String,
87    /// State keys this preparation is expected to produce.
88    pub produces: Vec<String>,
89}
90
91/// A turn extractor declaration.
92#[derive(Debug, Clone, Serialize, Deserialize)]
93pub struct ExtractorContract {
94    /// Extractor name.
95    pub name: String,
96    /// Recent transcript turns consumed.
97    pub window_size: usize,
98    /// Trigger mode.
99    pub trigger: String,
100    /// Explicit promotion policy. Empty means every top-level non-null field
101    /// is auto-flattened into state under its own name.
102    pub promotions: Vec<PromotionContract>,
103}
104
105/// A field promotion declaration.
106#[derive(Debug, Clone, Serialize, Deserialize)]
107pub struct PromotionContract {
108    /// Field in raw extractor output.
109    pub field: String,
110    /// Canonical state key written on acceptance.
111    pub state_key: String,
112    /// Merge policy.
113    pub merge: String,
114    /// Whether this promotion has an acceptance predicate.
115    pub has_predicate: bool,
116}
117
118/// A computed state declaration.
119#[derive(Debug, Clone, Serialize, Deserialize)]
120pub struct ComputedContract {
121    /// Derived key without the `derived:` prefix.
122    pub key: String,
123    /// Source dependencies.
124    pub dependencies: Vec<String>,
125}
126
127/// A watcher declaration.
128#[derive(Debug, Clone, Serialize, Deserialize)]
129pub struct WatcherContract {
130    /// Watched state key.
131    pub key: String,
132    /// Predicate debug label.
133    pub predicate: String,
134    /// Whether the watcher blocks the control lane while running.
135    pub blocking: bool,
136}
137
138/// Runtime control-plane settings.
139#[derive(Debug, Clone, Serialize, Deserialize)]
140pub struct ControlContract {
141    /// Soft-turn timeout in milliseconds.
142    pub soft_turn_timeout_ms: Option<u64>,
143    /// Steering mode.
144    pub steering_mode: String,
145    /// Context delivery mode.
146    pub context_delivery: String,
147    /// Whether phase transition tool advisory is enabled.
148    pub tool_advisory: bool,
149    /// Telemetry interval in milliseconds.
150    pub telemetry_interval_ms: Option<u64>,
151    /// Whether repair is configured.
152    pub repair_enabled: bool,
153    /// Whether persistence is configured.
154    pub persistence_enabled: bool,
155}
156
157impl Default for ControlContract {
158    fn default() -> Self {
159        Self {
160            soft_turn_timeout_ms: None,
161            steering_mode: "default".to_string(),
162            context_delivery: "default".to_string(),
163            tool_advisory: true,
164            telemetry_interval_ms: None,
165            repair_enabled: false,
166            persistence_enabled: false,
167        }
168    }
169}
gemini_adk_rs/live/contract.rs

gemini_adk_rs/live/
contract.rs
