outfox_openai/spec/chatkit/
session.rs

1use std::collections::HashMap;
2
3use derive_builder::Builder;
4use serde::{Deserialize, Serialize};
5
6use crate::error::OpenAIError;
7
8/// Represents a ChatKit session and its resolved configuration.
9#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
10pub struct ChatSessionResource {
11    /// Identifier for the ChatKit session.
12    pub id: String,
13    /// Type discriminator that is always `chatkit.session`.
14    #[serde(default = "default_session_object")]
15    pub object: String,
16    /// Unix timestamp (in seconds) for when the session expires.
17    pub expires_at: u64,
18    /// Ephemeral client secret that authenticates session requests.
19    pub client_secret: String,
20    /// Workflow metadata for the session.
21    pub workflow: ChatkitWorkflow,
22    /// User identifier associated with the session.
23    pub user: String,
24    /// Resolved rate limit values.
25    pub rate_limits: ChatSessionRateLimits,
26    /// Convenience copy of the per-minute request limit.
27    pub max_requests_per_1_minute: u32,
28    /// Current lifecycle state of the session.
29    pub status: ChatSessionStatus,
30    /// Resolved ChatKit feature configuration for the session.
31    pub chatkit_configuration: ChatSessionChatkitConfiguration,
32}
33
34fn default_session_object() -> String {
35    "chatkit.session".to_string()
36}
37
38/// Workflow metadata and state returned for the session.
39#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
40pub struct ChatkitWorkflow {
41    /// Identifier of the workflow backing the session.
42    pub id: String,
43    /// Specific workflow version used for the session. Defaults to null when using the latest
44    /// deployment.
45    #[serde(skip_serializing_if = "Option::is_none")]
46    pub version: Option<String>,
47    /// State variable key-value pairs applied when invoking the workflow. Defaults to null when no
48    /// overrides were provided.
49    #[serde(skip_serializing_if = "Option::is_none")]
50    pub state_variables: Option<HashMap<String, serde_json::Value>>,
51    /// Tracing settings applied to the workflow.
52    pub tracing: ChatkitWorkflowTracing,
53}
54
55/// Controls diagnostic tracing during the session.
56#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
57pub struct ChatkitWorkflowTracing {
58    /// Indicates whether tracing is enabled.
59    pub enabled: bool,
60}
61
62/// Active per-minute request limit for the session.
63#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
64pub struct ChatSessionRateLimits {
65    /// Maximum allowed requests per one-minute window.
66    pub max_requests_per_1_minute: u32,
67}
68
69/// Current lifecycle state of the session.
70#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
71#[serde(rename_all = "snake_case")]
72pub enum ChatSessionStatus {
73    Active,
74    Expired,
75    Cancelled,
76}
77
78/// ChatKit configuration for the session.
79#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
80pub struct ChatSessionChatkitConfiguration {
81    /// Automatic thread titling preferences.
82    pub automatic_thread_titling: ChatSessionAutomaticThreadTitling,
83    /// Upload settings for the session.
84    pub file_upload: ChatSessionFileUpload,
85    /// History retention configuration.
86    pub history: ChatSessionHistory,
87}
88
89/// Automatic thread title preferences for the session.
90#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
91pub struct ChatSessionAutomaticThreadTitling {
92    /// Whether automatic thread titling is enabled.
93    pub enabled: bool,
94}
95
96/// Upload permissions and limits applied to the session.
97#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
98pub struct ChatSessionFileUpload {
99    /// Indicates if uploads are enabled for the session.
100    pub enabled: bool,
101    /// Maximum upload size in megabytes.
102    #[serde(skip_serializing_if = "Option::is_none")]
103    pub max_file_size: Option<u32>,
104    /// Maximum number of uploads allowed during the session.
105    #[serde(skip_serializing_if = "Option::is_none")]
106    pub max_files: Option<u32>,
107}
108
109/// History retention preferences returned for the session.
110#[derive(Clone, Serialize, Debug, Deserialize, PartialEq)]
111pub struct ChatSessionHistory {
112    /// Indicates if chat history is persisted for the session.
113    pub enabled: bool,
114    /// Number of prior threads surfaced in history views. Defaults to null when all history is
115    /// retained.
116    #[serde(skip_serializing_if = "Option::is_none")]
117    pub recent_threads: Option<u32>,
118}
119
120/// Parameters for provisioning a new ChatKit session.
121#[derive(Clone, Serialize, Debug, Deserialize, Builder, PartialEq, Default)]
122#[builder(name = "CreateChatSessionRequestArgs")]
123#[builder(pattern = "mutable")]
124#[builder(setter(into, strip_option), default)]
125#[builder(derive(Debug))]
126#[builder(build_fn(error = "OpenAIError"))]
127pub struct CreateChatSessionBody {
128    /// Workflow that powers the session.
129    pub workflow: WorkflowParam,
130    /// A free-form string that identifies your end user; ensures this Session can access other
131    /// objects that have the same `user` scope.
132    pub user: String,
133    /// Optional override for session expiration timing in seconds from creation. Defaults to 10
134    /// minutes.
135    #[serde(skip_serializing_if = "Option::is_none")]
136    pub expires_after: Option<ExpiresAfterParam>,
137    /// Optional override for per-minute request limits. When omitted, defaults to 10.
138    #[serde(skip_serializing_if = "Option::is_none")]
139    pub rate_limits: Option<RateLimitsParam>,
140    /// Optional overrides for ChatKit runtime configuration features
141    #[serde(skip_serializing_if = "Option::is_none")]
142    pub chatkit_configuration: Option<ChatkitConfigurationParam>,
143}
144
145/// Workflow reference and overrides applied to the chat session.
146#[derive(Clone, Serialize, Debug, Deserialize, Builder, PartialEq, Default)]
147#[builder(name = "WorkflowParamArgs")]
148#[builder(pattern = "mutable")]
149#[builder(setter(into, strip_option), default)]
150#[builder(derive(Debug))]
151#[builder(build_fn(error = "OpenAIError"))]
152pub struct WorkflowParam {
153    /// Identifier for the workflow invoked by the session.
154    pub id: String,
155    /// Specific workflow version to run. Defaults to the latest deployed version.
156    #[serde(skip_serializing_if = "Option::is_none")]
157    pub version: Option<String>,
158    /// State variables forwarded to the workflow. Keys may be up to 64 characters, values must be
159    /// primitive types, and the map defaults to an empty object.
160    #[serde(skip_serializing_if = "Option::is_none")]
161    pub state_variables: Option<HashMap<String, serde_json::Value>>,
162    /// Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by
163    /// default.
164    #[serde(skip_serializing_if = "Option::is_none")]
165    pub tracing: Option<WorkflowTracingParam>,
166}
167
168/// Controls diagnostic tracing during the session.
169#[derive(Clone, Serialize, Default, Debug, Deserialize, Builder, PartialEq)]
170#[builder(name = "WorkflowTracingParamArgs")]
171#[builder(pattern = "mutable")]
172#[builder(setter(into, strip_option), default)]
173#[builder(derive(Debug))]
174#[builder(build_fn(error = "OpenAIError"))]
175pub struct WorkflowTracingParam {
176    /// Whether tracing is enabled during the session. Defaults to true.
177    #[serde(skip_serializing_if = "Option::is_none")]
178    pub enabled: Option<bool>,
179}
180
181/// Controls when the session expires relative to an anchor timestamp.
182#[derive(Clone, Serialize, Debug, Deserialize, Builder, PartialEq, Default)]
183#[builder(name = "ExpiresAfterParamArgs")]
184#[builder(pattern = "mutable")]
185#[builder(setter(into, strip_option), default)]
186#[builder(derive(Debug))]
187#[builder(build_fn(error = "OpenAIError"))]
188pub struct ExpiresAfterParam {
189    /// Base timestamp used to calculate expiration. Currently fixed to `created_at`.
190    #[serde(default = "default_anchor")]
191    #[builder(default = "default_anchor()")]
192    pub anchor: String,
193    /// Number of seconds after the anchor when the session expires.
194    pub seconds: u32,
195}
196
197fn default_anchor() -> String {
198    "created_at".to_string()
199}
200
201/// Controls request rate limits for the session.
202#[derive(Clone, Serialize, Debug, Deserialize, Builder, PartialEq, Default)]
203#[builder(name = "RateLimitsParamArgs")]
204#[builder(pattern = "mutable")]
205#[builder(setter(into, strip_option), default)]
206#[builder(derive(Debug))]
207#[builder(build_fn(error = "OpenAIError"))]
208pub struct RateLimitsParam {
209    /// Maximum number of requests allowed per minute for the session. Defaults to 10.
210    #[serde(skip_serializing_if = "Option::is_none")]
211    pub max_requests_per_1_minute: Option<u32>,
212}
213
214/// Optional per-session configuration settings for ChatKit behavior.
215#[derive(Clone, Serialize, Debug, Deserialize, Builder, PartialEq, Default)]
216#[builder(name = "ChatkitConfigurationParamArgs")]
217#[builder(pattern = "mutable")]
218#[builder(setter(into, strip_option), default)]
219#[builder(derive(Debug))]
220#[builder(build_fn(error = "OpenAIError"))]
221pub struct ChatkitConfigurationParam {
222    /// Configuration for automatic thread titling. When omitted, automatic thread titling is
223    /// enabled by default.
224    #[serde(skip_serializing_if = "Option::is_none")]
225    pub automatic_thread_titling: Option<AutomaticThreadTitlingParam>,
226    /// Configuration for upload enablement and limits. When omitted, uploads are disabled by
227    /// default (max_files 10, max_file_size 512 MB).
228    #[serde(skip_serializing_if = "Option::is_none")]
229    pub file_upload: Option<FileUploadParam>,
230    /// Configuration for chat history retention. When omitted, history is enabled by default with
231    /// no limit on recent_threads (null).
232    #[serde(skip_serializing_if = "Option::is_none")]
233    pub history: Option<HistoryParam>,
234}
235
236/// Controls whether ChatKit automatically generates thread titles.
237#[derive(Clone, Serialize, Debug, Deserialize, Builder, PartialEq, Default)]
238#[builder(name = "AutomaticThreadTitlingParamArgs")]
239#[builder(pattern = "mutable")]
240#[builder(setter(into, strip_option), default)]
241#[builder(derive(Debug))]
242#[builder(build_fn(error = "OpenAIError"))]
243pub struct AutomaticThreadTitlingParam {
244    /// Enable automatic thread title generation. Defaults to true.
245    #[serde(skip_serializing_if = "Option::is_none")]
246    pub enabled: Option<bool>,
247}
248
249/// Controls whether users can upload files.
250#[derive(Clone, Serialize, Debug, Deserialize, Builder, PartialEq, Default)]
251#[builder(name = "FileUploadParamArgs")]
252#[builder(pattern = "mutable")]
253#[builder(setter(into, strip_option), default)]
254#[builder(derive(Debug))]
255#[builder(build_fn(error = "OpenAIError"))]
256pub struct FileUploadParam {
257    /// Enable uploads for this session. Defaults to false.
258    #[serde(skip_serializing_if = "Option::is_none")]
259    pub enabled: Option<bool>,
260    /// Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum
261    /// allowable size.
262    #[serde(skip_serializing_if = "Option::is_none")]
263    pub max_file_size: Option<u32>,
264    /// Maximum number of files that can be uploaded to the session. Defaults to 10.
265    #[serde(skip_serializing_if = "Option::is_none")]
266    pub max_files: Option<u32>,
267}
268
269/// Controls how much historical context is retained for the session.
270#[derive(Clone, Serialize, Debug, Deserialize, Builder, PartialEq, Default)]
271#[builder(name = "HistoryParamArgs")]
272#[builder(pattern = "mutable")]
273#[builder(setter(into, strip_option), default)]
274#[builder(derive(Debug))]
275#[builder(build_fn(error = "OpenAIError"))]
276pub struct HistoryParam {
277    /// Enables chat users to access previous ChatKit threads. Defaults to true.
278    #[serde(skip_serializing_if = "Option::is_none")]
279    pub enabled: Option<bool>,
280    /// Number of recent ChatKit threads users have access to. Defaults to unlimited when unset.
281    #[serde(skip_serializing_if = "Option::is_none")]
282    pub recent_threads: Option<u32>,
283}
outfox_openai/spec/chatkit/session.rs

outfox_openai/spec/chatkit/
session.rs
