robosystems-client 0.2.5__py3-none-any.whl → 0.2.6__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of robosystems-client might be problematic. Click here for more details.

Files changed (30) hide show
  1. robosystems_client/api/agent/auto_select_agent.py +164 -32
  2. robosystems_client/api/backup/create_backup.py +72 -0
  3. robosystems_client/api/backup/get_backup_download_url.py +12 -28
  4. robosystems_client/api/backup/restore_backup.py +92 -0
  5. robosystems_client/api/graph_limits/get_graph_limits.py +12 -14
  6. robosystems_client/api/graphs/create_graph.py +136 -36
  7. robosystems_client/api/graphs/get_available_graph_tiers.py +279 -0
  8. robosystems_client/api/query/execute_cypher_query.py +13 -11
  9. robosystems_client/models/__init__.py +22 -8
  10. robosystems_client/models/agent_response.py +1 -1
  11. robosystems_client/models/backup_download_url_response.py +92 -0
  12. robosystems_client/models/backup_limits.py +76 -0
  13. robosystems_client/models/batch_agent_request.py +1 -1
  14. robosystems_client/models/batch_agent_response.py +2 -2
  15. robosystems_client/models/copy_operation_limits.py +100 -0
  16. robosystems_client/models/create_graph_request.py +16 -17
  17. robosystems_client/models/credit_limits.py +84 -0
  18. robosystems_client/models/custom_schema_definition.py +14 -10
  19. robosystems_client/models/execute_cypher_query_response_200.py +135 -0
  20. robosystems_client/models/{get_graph_limits_response_getgraphlimits.py → execute_cypher_query_response_200_data_item.py} +5 -5
  21. robosystems_client/models/graph_limits_response.py +174 -0
  22. robosystems_client/models/initial_entity_data.py +15 -12
  23. robosystems_client/models/query_limits.py +84 -0
  24. robosystems_client/models/rate_limits.py +76 -0
  25. robosystems_client/models/storage_limits.py +90 -0
  26. {robosystems_client-0.2.5.dist-info → robosystems_client-0.2.6.dist-info}/METADATA +1 -1
  27. {robosystems_client-0.2.5.dist-info → robosystems_client-0.2.6.dist-info}/RECORD +29 -20
  28. robosystems_client/models/get_backup_download_url_response_getbackupdownloadurl.py +0 -44
  29. {robosystems_client-0.2.5.dist-info → robosystems_client-0.2.6.dist-info}/WHEEL +0 -0
  30. {robosystems_client-0.2.5.dist-info → robosystems_client-0.2.6.dist-info}/licenses/LICENSE +0 -0
@@ -85,17 +85,50 @@ def sync_detailed(
85
85
  client: AuthenticatedClient,
86
86
  body: AgentRequest,
87
87
  ) -> Response[Union[AgentResponse, Any, ErrorResponse, HTTPValidationError]]:
88
- """Auto-select agent for query
88
+ r"""Auto-select agent for query
89
89
 
90
90
  Automatically select the best agent for your query.
91
91
 
92
- The orchestrator will:
93
- 1. Enrich context with RAG if enabled
94
- 2. Evaluate all available agents
95
- 3. Select the best match based on confidence scores
96
- 4. Execute the query with the selected agent
97
-
98
- Use this endpoint when you want the system to intelligently route your query.
92
+ **Agent Selection Process:**
93
+
94
+ The orchestrator intelligently routes your query by:
95
+ 1. Analyzing query intent and complexity
96
+ 2. Enriching context with RAG if enabled
97
+ 3. Evaluating all available agents against selection criteria
98
+ 4. Selecting the best match based on confidence scores
99
+ 5. Executing the query with the selected agent
100
+
101
+ **Available Agent Types:**
102
+ - `financial`: Financial analysis, SEC filings, company metrics
103
+ - `research`: General research, data exploration, trend analysis
104
+ - `rag`: Knowledge base search using RAG enrichment
105
+
106
+ **Execution Modes:**
107
+ - `quick`: Fast responses (~2-5s), suitable for simple queries
108
+ - `standard`: Balanced approach (~5-15s), default mode
109
+ - `extended`: Comprehensive analysis (~15-60s), deep research
110
+ - `streaming`: Real-time response streaming
111
+
112
+ **Confidence Score Interpretation:**
113
+ - `0.9-1.0`: High confidence, agent is ideal match
114
+ - `0.7-0.9`: Good confidence, agent is suitable
115
+ - `0.5-0.7`: Moderate confidence, agent can handle but may not be optimal
116
+ - `0.3-0.5`: Low confidence, fallback agent used
117
+ - `<0.3`: Very low confidence, consider using specific agent endpoint
118
+
119
+ **Credit Costs:**
120
+ - Quick mode: 5-10 credits per query
121
+ - Standard mode: 15-25 credits per query
122
+ - Extended mode: 30-75 credits per query
123
+ - RAG enrichment: +5-15 credits (if enabled)
124
+
125
+ **Use Cases:**
126
+ - Ask questions without specifying agent type
127
+ - Get intelligent routing for complex multi-domain queries
128
+ - Leverage conversation history for contextual understanding
129
+ - Enable RAG for knowledge base enrichment
130
+
131
+ See request/response examples in the \"Examples\" dropdown below.
99
132
 
100
133
  Args:
101
134
  graph_id (str):
@@ -127,17 +160,50 @@ def sync(
127
160
  client: AuthenticatedClient,
128
161
  body: AgentRequest,
129
162
  ) -> Optional[Union[AgentResponse, Any, ErrorResponse, HTTPValidationError]]:
130
- """Auto-select agent for query
163
+ r"""Auto-select agent for query
131
164
 
132
165
  Automatically select the best agent for your query.
133
166
 
134
- The orchestrator will:
135
- 1. Enrich context with RAG if enabled
136
- 2. Evaluate all available agents
137
- 3. Select the best match based on confidence scores
138
- 4. Execute the query with the selected agent
139
-
140
- Use this endpoint when you want the system to intelligently route your query.
167
+ **Agent Selection Process:**
168
+
169
+ The orchestrator intelligently routes your query by:
170
+ 1. Analyzing query intent and complexity
171
+ 2. Enriching context with RAG if enabled
172
+ 3. Evaluating all available agents against selection criteria
173
+ 4. Selecting the best match based on confidence scores
174
+ 5. Executing the query with the selected agent
175
+
176
+ **Available Agent Types:**
177
+ - `financial`: Financial analysis, SEC filings, company metrics
178
+ - `research`: General research, data exploration, trend analysis
179
+ - `rag`: Knowledge base search using RAG enrichment
180
+
181
+ **Execution Modes:**
182
+ - `quick`: Fast responses (~2-5s), suitable for simple queries
183
+ - `standard`: Balanced approach (~5-15s), default mode
184
+ - `extended`: Comprehensive analysis (~15-60s), deep research
185
+ - `streaming`: Real-time response streaming
186
+
187
+ **Confidence Score Interpretation:**
188
+ - `0.9-1.0`: High confidence, agent is ideal match
189
+ - `0.7-0.9`: Good confidence, agent is suitable
190
+ - `0.5-0.7`: Moderate confidence, agent can handle but may not be optimal
191
+ - `0.3-0.5`: Low confidence, fallback agent used
192
+ - `<0.3`: Very low confidence, consider using specific agent endpoint
193
+
194
+ **Credit Costs:**
195
+ - Quick mode: 5-10 credits per query
196
+ - Standard mode: 15-25 credits per query
197
+ - Extended mode: 30-75 credits per query
198
+ - RAG enrichment: +5-15 credits (if enabled)
199
+
200
+ **Use Cases:**
201
+ - Ask questions without specifying agent type
202
+ - Get intelligent routing for complex multi-domain queries
203
+ - Leverage conversation history for contextual understanding
204
+ - Enable RAG for knowledge base enrichment
205
+
206
+ See request/response examples in the \"Examples\" dropdown below.
141
207
 
142
208
  Args:
143
209
  graph_id (str):
@@ -164,17 +230,50 @@ async def asyncio_detailed(
164
230
  client: AuthenticatedClient,
165
231
  body: AgentRequest,
166
232
  ) -> Response[Union[AgentResponse, Any, ErrorResponse, HTTPValidationError]]:
167
- """Auto-select agent for query
233
+ r"""Auto-select agent for query
168
234
 
169
235
  Automatically select the best agent for your query.
170
236
 
171
- The orchestrator will:
172
- 1. Enrich context with RAG if enabled
173
- 2. Evaluate all available agents
174
- 3. Select the best match based on confidence scores
175
- 4. Execute the query with the selected agent
176
-
177
- Use this endpoint when you want the system to intelligently route your query.
237
+ **Agent Selection Process:**
238
+
239
+ The orchestrator intelligently routes your query by:
240
+ 1. Analyzing query intent and complexity
241
+ 2. Enriching context with RAG if enabled
242
+ 3. Evaluating all available agents against selection criteria
243
+ 4. Selecting the best match based on confidence scores
244
+ 5. Executing the query with the selected agent
245
+
246
+ **Available Agent Types:**
247
+ - `financial`: Financial analysis, SEC filings, company metrics
248
+ - `research`: General research, data exploration, trend analysis
249
+ - `rag`: Knowledge base search using RAG enrichment
250
+
251
+ **Execution Modes:**
252
+ - `quick`: Fast responses (~2-5s), suitable for simple queries
253
+ - `standard`: Balanced approach (~5-15s), default mode
254
+ - `extended`: Comprehensive analysis (~15-60s), deep research
255
+ - `streaming`: Real-time response streaming
256
+
257
+ **Confidence Score Interpretation:**
258
+ - `0.9-1.0`: High confidence, agent is ideal match
259
+ - `0.7-0.9`: Good confidence, agent is suitable
260
+ - `0.5-0.7`: Moderate confidence, agent can handle but may not be optimal
261
+ - `0.3-0.5`: Low confidence, fallback agent used
262
+ - `<0.3`: Very low confidence, consider using specific agent endpoint
263
+
264
+ **Credit Costs:**
265
+ - Quick mode: 5-10 credits per query
266
+ - Standard mode: 15-25 credits per query
267
+ - Extended mode: 30-75 credits per query
268
+ - RAG enrichment: +5-15 credits (if enabled)
269
+
270
+ **Use Cases:**
271
+ - Ask questions without specifying agent type
272
+ - Get intelligent routing for complex multi-domain queries
273
+ - Leverage conversation history for contextual understanding
274
+ - Enable RAG for knowledge base enrichment
275
+
276
+ See request/response examples in the \"Examples\" dropdown below.
178
277
 
179
278
  Args:
180
279
  graph_id (str):
@@ -204,17 +303,50 @@ async def asyncio(
204
303
  client: AuthenticatedClient,
205
304
  body: AgentRequest,
206
305
  ) -> Optional[Union[AgentResponse, Any, ErrorResponse, HTTPValidationError]]:
207
- """Auto-select agent for query
306
+ r"""Auto-select agent for query
208
307
 
209
308
  Automatically select the best agent for your query.
210
309
 
211
- The orchestrator will:
212
- 1. Enrich context with RAG if enabled
213
- 2. Evaluate all available agents
214
- 3. Select the best match based on confidence scores
215
- 4. Execute the query with the selected agent
216
-
217
- Use this endpoint when you want the system to intelligently route your query.
310
+ **Agent Selection Process:**
311
+
312
+ The orchestrator intelligently routes your query by:
313
+ 1. Analyzing query intent and complexity
314
+ 2. Enriching context with RAG if enabled
315
+ 3. Evaluating all available agents against selection criteria
316
+ 4. Selecting the best match based on confidence scores
317
+ 5. Executing the query with the selected agent
318
+
319
+ **Available Agent Types:**
320
+ - `financial`: Financial analysis, SEC filings, company metrics
321
+ - `research`: General research, data exploration, trend analysis
322
+ - `rag`: Knowledge base search using RAG enrichment
323
+
324
+ **Execution Modes:**
325
+ - `quick`: Fast responses (~2-5s), suitable for simple queries
326
+ - `standard`: Balanced approach (~5-15s), default mode
327
+ - `extended`: Comprehensive analysis (~15-60s), deep research
328
+ - `streaming`: Real-time response streaming
329
+
330
+ **Confidence Score Interpretation:**
331
+ - `0.9-1.0`: High confidence, agent is ideal match
332
+ - `0.7-0.9`: Good confidence, agent is suitable
333
+ - `0.5-0.7`: Moderate confidence, agent can handle but may not be optimal
334
+ - `0.3-0.5`: Low confidence, fallback agent used
335
+ - `<0.3`: Very low confidence, consider using specific agent endpoint
336
+
337
+ **Credit Costs:**
338
+ - Quick mode: 5-10 credits per query
339
+ - Standard mode: 15-25 credits per query
340
+ - Extended mode: 30-75 credits per query
341
+ - RAG enrichment: +5-15 credits (if enabled)
342
+
343
+ **Use Cases:**
344
+ - Ask questions without specifying agent type
345
+ - Get intelligent routing for complex multi-domain queries
346
+ - Leverage conversation history for contextual understanding
347
+ - Enable RAG for knowledge base enrichment
348
+
349
+ See request/response examples in the \"Examples\" dropdown below.
218
350
 
219
351
  Args:
220
352
  graph_id (str):
@@ -102,6 +102,23 @@ def sync_detailed(
102
102
  - **Download Support**: Unencrypted backups can be downloaded
103
103
  - **Restore Support**: Future support for encrypted backup restoration
104
104
 
105
+ **Operation State Machine:**
106
+ ```
107
+ pending → processing → completed
108
+ ↘ failed
109
+ ```
110
+ - **pending**: Backup queued, waiting to start
111
+ - **processing**: Actively backing up database
112
+ - **completed**: Backup successfully created and stored
113
+ - **failed**: Backup failed (check error message)
114
+
115
+ **Expected Durations:**
116
+ Operation times vary by database size:
117
+ - **Small** (<1GB): 30 seconds - 2 minutes
118
+ - **Medium** (1-10GB): 2-10 minutes
119
+ - **Large** (10-100GB): 10-30 minutes
120
+ - **Very Large** (>100GB): 30+ minutes
121
+
105
122
  **Progress Monitoring:**
106
123
  Use the returned operation_id to connect to the SSE stream:
107
124
  ```javascript
@@ -109,6 +126,7 @@ def sync_detailed(
109
126
  eventSource.addEventListener('operation_progress', (event) => {
110
127
  const data = JSON.parse(event.data);
111
128
  console.log('Backup progress:', data.progress_percent + '%');
129
+ console.log('Status:', data.status); // pending, processing, completed, failed
112
130
  });
113
131
  ```
114
132
 
@@ -177,6 +195,23 @@ def sync(
177
195
  - **Download Support**: Unencrypted backups can be downloaded
178
196
  - **Restore Support**: Future support for encrypted backup restoration
179
197
 
198
+ **Operation State Machine:**
199
+ ```
200
+ pending → processing → completed
201
+ ↘ failed
202
+ ```
203
+ - **pending**: Backup queued, waiting to start
204
+ - **processing**: Actively backing up database
205
+ - **completed**: Backup successfully created and stored
206
+ - **failed**: Backup failed (check error message)
207
+
208
+ **Expected Durations:**
209
+ Operation times vary by database size:
210
+ - **Small** (<1GB): 30 seconds - 2 minutes
211
+ - **Medium** (1-10GB): 2-10 minutes
212
+ - **Large** (10-100GB): 10-30 minutes
213
+ - **Very Large** (>100GB): 30+ minutes
214
+
180
215
  **Progress Monitoring:**
181
216
  Use the returned operation_id to connect to the SSE stream:
182
217
  ```javascript
@@ -184,6 +219,7 @@ def sync(
184
219
  eventSource.addEventListener('operation_progress', (event) => {
185
220
  const data = JSON.parse(event.data);
186
221
  console.log('Backup progress:', data.progress_percent + '%');
222
+ console.log('Status:', data.status); // pending, processing, completed, failed
187
223
  });
188
224
  ```
189
225
 
@@ -247,6 +283,23 @@ async def asyncio_detailed(
247
283
  - **Download Support**: Unencrypted backups can be downloaded
248
284
  - **Restore Support**: Future support for encrypted backup restoration
249
285
 
286
+ **Operation State Machine:**
287
+ ```
288
+ pending → processing → completed
289
+ ↘ failed
290
+ ```
291
+ - **pending**: Backup queued, waiting to start
292
+ - **processing**: Actively backing up database
293
+ - **completed**: Backup successfully created and stored
294
+ - **failed**: Backup failed (check error message)
295
+
296
+ **Expected Durations:**
297
+ Operation times vary by database size:
298
+ - **Small** (<1GB): 30 seconds - 2 minutes
299
+ - **Medium** (1-10GB): 2-10 minutes
300
+ - **Large** (10-100GB): 10-30 minutes
301
+ - **Very Large** (>100GB): 30+ minutes
302
+
250
303
  **Progress Monitoring:**
251
304
  Use the returned operation_id to connect to the SSE stream:
252
305
  ```javascript
@@ -254,6 +307,7 @@ async def asyncio_detailed(
254
307
  eventSource.addEventListener('operation_progress', (event) => {
255
308
  const data = JSON.parse(event.data);
256
309
  console.log('Backup progress:', data.progress_percent + '%');
310
+ console.log('Status:', data.status); // pending, processing, completed, failed
257
311
  });
258
312
  ```
259
313
 
@@ -320,6 +374,23 @@ async def asyncio(
320
374
  - **Download Support**: Unencrypted backups can be downloaded
321
375
  - **Restore Support**: Future support for encrypted backup restoration
322
376
 
377
+ **Operation State Machine:**
378
+ ```
379
+ pending → processing → completed
380
+ ↘ failed
381
+ ```
382
+ - **pending**: Backup queued, waiting to start
383
+ - **processing**: Actively backing up database
384
+ - **completed**: Backup successfully created and stored
385
+ - **failed**: Backup failed (check error message)
386
+
387
+ **Expected Durations:**
388
+ Operation times vary by database size:
389
+ - **Small** (<1GB): 30 seconds - 2 minutes
390
+ - **Medium** (1-10GB): 2-10 minutes
391
+ - **Large** (10-100GB): 10-30 minutes
392
+ - **Very Large** (>100GB): 30+ minutes
393
+
323
394
  **Progress Monitoring:**
324
395
  Use the returned operation_id to connect to the SSE stream:
325
396
  ```javascript
@@ -327,6 +398,7 @@ async def asyncio(
327
398
  eventSource.addEventListener('operation_progress', (event) => {
328
399
  const data = JSON.parse(event.data);
329
400
  console.log('Backup progress:', data.progress_percent + '%');
401
+ console.log('Status:', data.status); // pending, processing, completed, failed
330
402
  });
331
403
  ```
332
404
 
@@ -5,9 +5,7 @@ import httpx
5
5
 
6
6
  from ... import errors
7
7
  from ...client import AuthenticatedClient, Client
8
- from ...models.get_backup_download_url_response_getbackupdownloadurl import (
9
- GetBackupDownloadUrlResponseGetbackupdownloadurl,
10
- )
8
+ from ...models.backup_download_url_response import BackupDownloadUrlResponse
11
9
  from ...models.http_validation_error import HTTPValidationError
12
10
  from ...types import UNSET, Response, Unset
13
11
 
@@ -35,13 +33,9 @@ def _get_kwargs(
35
33
 
36
34
  def _parse_response(
37
35
  *, client: Union[AuthenticatedClient, Client], response: httpx.Response
38
- ) -> Optional[
39
- Union[Any, GetBackupDownloadUrlResponseGetbackupdownloadurl, HTTPValidationError]
40
- ]:
36
+ ) -> Optional[Union[Any, BackupDownloadUrlResponse, HTTPValidationError]]:
41
37
  if response.status_code == 200:
42
- response_200 = GetBackupDownloadUrlResponseGetbackupdownloadurl.from_dict(
43
- response.json()
44
- )
38
+ response_200 = BackupDownloadUrlResponse.from_dict(response.json())
45
39
 
46
40
  return response_200
47
41
 
@@ -70,9 +64,7 @@ def _parse_response(
70
64
 
71
65
  def _build_response(
72
66
  *, client: Union[AuthenticatedClient, Client], response: httpx.Response
73
- ) -> Response[
74
- Union[Any, GetBackupDownloadUrlResponseGetbackupdownloadurl, HTTPValidationError]
75
- ]:
67
+ ) -> Response[Union[Any, BackupDownloadUrlResponse, HTTPValidationError]]:
76
68
  return Response(
77
69
  status_code=HTTPStatus(response.status_code),
78
70
  content=response.content,
@@ -87,9 +79,7 @@ def sync_detailed(
87
79
  *,
88
80
  client: AuthenticatedClient,
89
81
  expires_in: Union[Unset, int] = 3600,
90
- ) -> Response[
91
- Union[Any, GetBackupDownloadUrlResponseGetbackupdownloadurl, HTTPValidationError]
92
- ]:
82
+ ) -> Response[Union[Any, BackupDownloadUrlResponse, HTTPValidationError]]:
93
83
  """Get temporary download URL for backup
94
84
 
95
85
  Generate a temporary download URL for a backup (unencrypted, compressed .kuzu files only)
@@ -104,7 +94,7 @@ def sync_detailed(
104
94
  httpx.TimeoutException: If the request takes longer than Client.timeout.
105
95
 
106
96
  Returns:
107
- Response[Union[Any, GetBackupDownloadUrlResponseGetbackupdownloadurl, HTTPValidationError]]
97
+ Response[Union[Any, BackupDownloadUrlResponse, HTTPValidationError]]
108
98
  """
109
99
 
110
100
  kwargs = _get_kwargs(
@@ -126,9 +116,7 @@ def sync(
126
116
  *,
127
117
  client: AuthenticatedClient,
128
118
  expires_in: Union[Unset, int] = 3600,
129
- ) -> Optional[
130
- Union[Any, GetBackupDownloadUrlResponseGetbackupdownloadurl, HTTPValidationError]
131
- ]:
119
+ ) -> Optional[Union[Any, BackupDownloadUrlResponse, HTTPValidationError]]:
132
120
  """Get temporary download URL for backup
133
121
 
134
122
  Generate a temporary download URL for a backup (unencrypted, compressed .kuzu files only)
@@ -143,7 +131,7 @@ def sync(
143
131
  httpx.TimeoutException: If the request takes longer than Client.timeout.
144
132
 
145
133
  Returns:
146
- Union[Any, GetBackupDownloadUrlResponseGetbackupdownloadurl, HTTPValidationError]
134
+ Union[Any, BackupDownloadUrlResponse, HTTPValidationError]
147
135
  """
148
136
 
149
137
  return sync_detailed(
@@ -160,9 +148,7 @@ async def asyncio_detailed(
160
148
  *,
161
149
  client: AuthenticatedClient,
162
150
  expires_in: Union[Unset, int] = 3600,
163
- ) -> Response[
164
- Union[Any, GetBackupDownloadUrlResponseGetbackupdownloadurl, HTTPValidationError]
165
- ]:
151
+ ) -> Response[Union[Any, BackupDownloadUrlResponse, HTTPValidationError]]:
166
152
  """Get temporary download URL for backup
167
153
 
168
154
  Generate a temporary download URL for a backup (unencrypted, compressed .kuzu files only)
@@ -177,7 +163,7 @@ async def asyncio_detailed(
177
163
  httpx.TimeoutException: If the request takes longer than Client.timeout.
178
164
 
179
165
  Returns:
180
- Response[Union[Any, GetBackupDownloadUrlResponseGetbackupdownloadurl, HTTPValidationError]]
166
+ Response[Union[Any, BackupDownloadUrlResponse, HTTPValidationError]]
181
167
  """
182
168
 
183
169
  kwargs = _get_kwargs(
@@ -197,9 +183,7 @@ async def asyncio(
197
183
  *,
198
184
  client: AuthenticatedClient,
199
185
  expires_in: Union[Unset, int] = 3600,
200
- ) -> Optional[
201
- Union[Any, GetBackupDownloadUrlResponseGetbackupdownloadurl, HTTPValidationError]
202
- ]:
186
+ ) -> Optional[Union[Any, BackupDownloadUrlResponse, HTTPValidationError]]:
203
187
  """Get temporary download URL for backup
204
188
 
205
189
  Generate a temporary download URL for a backup (unencrypted, compressed .kuzu files only)
@@ -214,7 +198,7 @@ async def asyncio(
214
198
  httpx.TimeoutException: If the request takes longer than Client.timeout.
215
199
 
216
200
  Returns:
217
- Union[Any, GetBackupDownloadUrlResponseGetbackupdownloadurl, HTTPValidationError]
201
+ Union[Any, BackupDownloadUrlResponse, HTTPValidationError]
218
202
  """
219
203
 
220
204
  return (
@@ -104,6 +104,28 @@ def sync_detailed(
104
104
  - **Data Integrity**: Verification ensures successful restore
105
105
  - **Security**: Only encrypted backups to prevent data tampering
106
106
 
107
+ **Operation State Machine:**
108
+ ```
109
+ pending → backing_up_current → downloading → restoring → verifying → completed
110
+ ↘ failed
111
+ ```
112
+ - **pending**: Restore queued, waiting to start
113
+ - **backing_up_current**: Creating safety backup of existing database
114
+ - **downloading**: Downloading backup from storage
115
+ - **restoring**: Replacing database with backup contents
116
+ - **verifying**: Verifying database integrity (if enabled)
117
+ - **completed**: Restore successful, database operational
118
+ - **failed**: Restore failed (rollback may be available)
119
+
120
+ **Expected Durations:**
121
+ Operation times vary by database size (includes backup + restore):
122
+ - **Small** (<1GB): 1-3 minutes
123
+ - **Medium** (1-10GB): 5-15 minutes
124
+ - **Large** (10-100GB): 20-45 minutes
125
+ - **Very Large** (>100GB): 45+ minutes
126
+
127
+ Note: Restore operations take longer than backups due to safety backup step.
128
+
107
129
  **Progress Monitoring:**
108
130
  Use the returned operation_id to connect to the SSE stream:
109
131
  ```javascript
@@ -111,6 +133,7 @@ def sync_detailed(
111
133
  eventSource.addEventListener('operation_progress', (event) => {
112
134
  const data = JSON.parse(event.data);
113
135
  console.log('Restore progress:', data.message);
136
+ console.log('Status:', data.status); // Shows current state
114
137
  });
115
138
  ```
116
139
 
@@ -182,6 +205,28 @@ def sync(
182
205
  - **Data Integrity**: Verification ensures successful restore
183
206
  - **Security**: Only encrypted backups to prevent data tampering
184
207
 
208
+ **Operation State Machine:**
209
+ ```
210
+ pending → backing_up_current → downloading → restoring → verifying → completed
211
+ ↘ failed
212
+ ```
213
+ - **pending**: Restore queued, waiting to start
214
+ - **backing_up_current**: Creating safety backup of existing database
215
+ - **downloading**: Downloading backup from storage
216
+ - **restoring**: Replacing database with backup contents
217
+ - **verifying**: Verifying database integrity (if enabled)
218
+ - **completed**: Restore successful, database operational
219
+ - **failed**: Restore failed (rollback may be available)
220
+
221
+ **Expected Durations:**
222
+ Operation times vary by database size (includes backup + restore):
223
+ - **Small** (<1GB): 1-3 minutes
224
+ - **Medium** (1-10GB): 5-15 minutes
225
+ - **Large** (10-100GB): 20-45 minutes
226
+ - **Very Large** (>100GB): 45+ minutes
227
+
228
+ Note: Restore operations take longer than backups due to safety backup step.
229
+
185
230
  **Progress Monitoring:**
186
231
  Use the returned operation_id to connect to the SSE stream:
187
232
  ```javascript
@@ -189,6 +234,7 @@ def sync(
189
234
  eventSource.addEventListener('operation_progress', (event) => {
190
235
  const data = JSON.parse(event.data);
191
236
  console.log('Restore progress:', data.message);
237
+ console.log('Status:', data.status); // Shows current state
192
238
  });
193
239
  ```
194
240
 
@@ -255,6 +301,28 @@ async def asyncio_detailed(
255
301
  - **Data Integrity**: Verification ensures successful restore
256
302
  - **Security**: Only encrypted backups to prevent data tampering
257
303
 
304
+ **Operation State Machine:**
305
+ ```
306
+ pending → backing_up_current → downloading → restoring → verifying → completed
307
+ ↘ failed
308
+ ```
309
+ - **pending**: Restore queued, waiting to start
310
+ - **backing_up_current**: Creating safety backup of existing database
311
+ - **downloading**: Downloading backup from storage
312
+ - **restoring**: Replacing database with backup contents
313
+ - **verifying**: Verifying database integrity (if enabled)
314
+ - **completed**: Restore successful, database operational
315
+ - **failed**: Restore failed (rollback may be available)
316
+
317
+ **Expected Durations:**
318
+ Operation times vary by database size (includes backup + restore):
319
+ - **Small** (<1GB): 1-3 minutes
320
+ - **Medium** (1-10GB): 5-15 minutes
321
+ - **Large** (10-100GB): 20-45 minutes
322
+ - **Very Large** (>100GB): 45+ minutes
323
+
324
+ Note: Restore operations take longer than backups due to safety backup step.
325
+
258
326
  **Progress Monitoring:**
259
327
  Use the returned operation_id to connect to the SSE stream:
260
328
  ```javascript
@@ -262,6 +330,7 @@ async def asyncio_detailed(
262
330
  eventSource.addEventListener('operation_progress', (event) => {
263
331
  const data = JSON.parse(event.data);
264
332
  console.log('Restore progress:', data.message);
333
+ console.log('Status:', data.status); // Shows current state
265
334
  });
266
335
  ```
267
336
 
@@ -331,6 +400,28 @@ async def asyncio(
331
400
  - **Data Integrity**: Verification ensures successful restore
332
401
  - **Security**: Only encrypted backups to prevent data tampering
333
402
 
403
+ **Operation State Machine:**
404
+ ```
405
+ pending → backing_up_current → downloading → restoring → verifying → completed
406
+ ↘ failed
407
+ ```
408
+ - **pending**: Restore queued, waiting to start
409
+ - **backing_up_current**: Creating safety backup of existing database
410
+ - **downloading**: Downloading backup from storage
411
+ - **restoring**: Replacing database with backup contents
412
+ - **verifying**: Verifying database integrity (if enabled)
413
+ - **completed**: Restore successful, database operational
414
+ - **failed**: Restore failed (rollback may be available)
415
+
416
+ **Expected Durations:**
417
+ Operation times vary by database size (includes backup + restore):
418
+ - **Small** (<1GB): 1-3 minutes
419
+ - **Medium** (1-10GB): 5-15 minutes
420
+ - **Large** (10-100GB): 20-45 minutes
421
+ - **Very Large** (>100GB): 45+ minutes
422
+
423
+ Note: Restore operations take longer than backups due to safety backup step.
424
+
334
425
  **Progress Monitoring:**
335
426
  Use the returned operation_id to connect to the SSE stream:
336
427
  ```javascript
@@ -338,6 +429,7 @@ async def asyncio(
338
429
  eventSource.addEventListener('operation_progress', (event) => {
339
430
  const data = JSON.parse(event.data);
340
431
  console.log('Restore progress:', data.message);
432
+ console.log('Status:', data.status); // Shows current state
341
433
  });
342
434
  ```
343
435