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 legacy auto-flatten behavior.
101    pub promotions: Vec<PromotionContract>,
102}
103
104/// A field promotion declaration.
105#[derive(Debug, Clone, Serialize, Deserialize)]
106pub struct PromotionContract {
107    /// Field in raw extractor output.
108    pub field: String,
109    /// Canonical state key written on acceptance.
110    pub state_key: String,
111    /// Merge policy.
112    pub merge: String,
113    /// Whether this promotion has an acceptance predicate.
114    pub has_predicate: bool,
115}
116
117/// A computed state declaration.
118#[derive(Debug, Clone, Serialize, Deserialize)]
119pub struct ComputedContract {
120    /// Derived key without the `derived:` prefix.
121    pub key: String,
122    /// Source dependencies.
123    pub dependencies: Vec<String>,
124}
125
126/// A watcher declaration.
127#[derive(Debug, Clone, Serialize, Deserialize)]
128pub struct WatcherContract {
129    /// Watched state key.
130    pub key: String,
131    /// Predicate debug label.
132    pub predicate: String,
133    /// Whether the watcher blocks the control lane while running.
134    pub blocking: bool,
135}
136
137/// Runtime control-plane settings.
138#[derive(Debug, Clone, Serialize, Deserialize)]
139pub struct ControlContract {
140    /// Soft-turn timeout in milliseconds.
141    pub soft_turn_timeout_ms: Option<u64>,
142    /// Steering mode.
143    pub steering_mode: String,
144    /// Context delivery mode.
145    pub context_delivery: String,
146    /// Whether phase transition tool advisory is enabled.
147    pub tool_advisory: bool,
148    /// Telemetry interval in milliseconds.
149    pub telemetry_interval_ms: Option<u64>,
150    /// Whether repair is configured.
151    pub repair_enabled: bool,
152    /// Whether persistence is configured.
153    pub persistence_enabled: bool,
154}
155
156impl Default for ControlContract {
157    fn default() -> Self {
158        Self {
159            soft_turn_timeout_ms: None,
160            steering_mode: "default".to_string(),
161            context_delivery: "default".to_string(),
162            tool_advisory: true,
163            telemetry_interval_ms: None,
164            repair_enabled: false,
165            persistence_enabled: false,
166        }
167    }
168}
gemini_adk_rs/live/contract.rs

gemini_adk_rs/live/
contract.rs
