mhome-conversation-api 2.0.0

Typed wire contract for the mHome conversation API
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

use crate::{InteractionDecision, MessageContent};
use serde::{Deserialize, Serialize};

#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct ThreadListRequest {}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct ThreadCreateRequest {
    pub operation_id: String,
    pub expected_catalog_version: u64,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct ThreadArchiveRequest {
    pub thread_id: String,
    pub expected_catalog_version: u64,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct ThreadRotateRequest {
    pub operation_id: String,
    pub thread_id: String,
    pub expected_catalog_version: u64,
    pub expected_snapshot_version: u64,
    pub expected_setting_version: u64,
    pub reason: ThreadRotateReason,
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum ThreadRotateReason {
    IdleTimeout,
    UserRequested,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct ThreadLoadRequest {
    pub thread_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub known_snapshot_version: Option<u64>,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct MessageEnqueueRequest {
    pub thread_id: String,
    pub request_id: String,
    pub content: MessageContent,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub access_mode: Option<ConversationAccessMode>,
    pub agent_model_mode: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub temperature: Option<f32>,
    pub allow_tools: bool,
    pub debug: bool,
}

/// Submits one user turn without requiring the caller to select or manage a thread.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct TurnSubmitRequest {
    pub request_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub title: Option<String>,
    pub content: MessageContent,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub access_mode: Option<ConversationAccessMode>,
    pub agent_model_mode: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub temperature: Option<f32>,
    pub allow_tools: bool,
    pub debug: bool,
    pub occurred_at_unix_ms: i64,
}

/// Starts a new active session without exposing thread storage preconditions to the caller.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct SessionStartRequest {
    pub operation_id: String,
    pub reason: SessionStartReason,
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum SessionStartReason {
    UserRequested,
}

/// Answers the current pending interaction without requiring thread or policy state.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct InteractionAnswerRequest {
    pub request_id: String,
    pub batch_id: String,
    pub decisions: Vec<InteractionDecision>,
    pub occurred_at_unix_ms: i64,
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum ConversationAccessMode {
    NoAccess,
    Interactive,
    FullAccess,
}

#[cfg(test)]
mod access_mode_tests {
    use super::ConversationAccessMode;

    #[test]
    fn no_access_is_a_distinct_canonical_wire_value() {
        let mode: ConversationAccessMode = serde_json::from_str("\"no_access\"").unwrap();
        assert_eq!(mode, ConversationAccessMode::NoAccess);
        assert_eq!(serde_json::to_string(&mode).unwrap(), "\"no_access\"");
        assert!(serde_json::from_str::<ConversationAccessMode>("\"deny\"").is_err());
        assert!(serde_json::from_str::<ConversationAccessMode>("\"always_deny\"").is_err());
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct QueueReorderRequest {
    pub thread_id: String,
    pub expected_queue_version: u64,
    pub ordered_request_ids: Vec<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct RequestCancelRequest {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub thread_id: Option<String>,
    pub request_id: String,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct InteractionSubmitRequest {
    pub thread_id: String,
    pub batch_id: String,
    pub decisions: Vec<InteractionDecision>,
}