11"""Graph Management Client
22
33Provides high-level graph management operations with automatic operation monitoring.
4+ Supports both SSE (Server-Sent Events) for real-time updates and polling fallback.
45"""
56
67from dataclasses import dataclass
78from typing import Dict , Any , Optional , Callable
89import time
10+ import json
911import logging
1012
13+ import httpx
14+
1115logger = logging .getLogger (__name__ )
1216
1317
@@ -62,19 +66,24 @@ def create_graph_and_wait(
6266 timeout : int = 60 ,
6367 poll_interval : int = 2 ,
6468 on_progress : Optional [Callable [[str ], None ]] = None ,
69+ use_sse : bool = True ,
6570 ) -> str :
6671 """
6772 Create a graph and wait for completion.
6873
74+ Uses SSE (Server-Sent Events) for real-time progress updates with
75+ automatic fallback to polling if SSE connection fails.
76+
6977 Args:
7078 metadata: Graph metadata
7179 initial_entity: Optional initial entity data
7280 create_entity: Whether to create the entity node and upload initial data.
7381 Only applies when initial_entity is provided. Set to False to create
7482 graph without populating entity data (useful for file-based ingestion).
7583 timeout: Maximum time to wait in seconds
76- poll_interval: Time between status checks in seconds
84+ poll_interval: Time between status checks in seconds (for polling fallback)
7785 on_progress: Callback for progress updates
86+ use_sse: Whether to try SSE first (default True). Falls back to polling on failure.
7887
7988 Returns:
8089 graph_id when creation completes
@@ -84,7 +93,6 @@ def create_graph_and_wait(
8493 """
8594 from ..client import AuthenticatedClient
8695 from ..api .graphs .create_graph import sync_detailed as create_graph
87- from ..api .operations .get_operation_status import sync_detailed as get_status
8896 from ..models .create_graph_request import CreateGraphRequest
8997 from ..models .graph_metadata import GraphMetadata as APIGraphMetadata
9098
@@ -151,13 +159,165 @@ def create_graph_and_wait(
151159 on_progress (f"Graph created: { graph_id } " )
152160 return graph_id
153161
154- # Otherwise, poll operation until complete
162+ # Otherwise, wait for operation to complete
155163 if not operation_id :
156164 raise RuntimeError ("No graph_id or operation_id in response" )
157165
158166 if on_progress :
159167 on_progress (f"Graph creation queued (operation: { operation_id } )" )
160168
169+ # Try SSE first, fall back to polling
170+ if use_sse :
171+ try :
172+ return self ._wait_with_sse (operation_id , timeout , on_progress )
173+ except Exception as e :
174+ logger .debug (f"SSE connection failed, falling back to polling: { e } " )
175+ if on_progress :
176+ on_progress ("SSE unavailable, using polling..." )
177+
178+ # Fallback to polling
179+ return self ._wait_with_polling (
180+ operation_id , timeout , poll_interval , on_progress , client
181+ )
182+
183+ def _wait_with_sse (
184+ self ,
185+ operation_id : str ,
186+ timeout : int ,
187+ on_progress : Optional [Callable [[str ], None ]],
188+ ) -> str :
189+ """
190+ Wait for operation completion using SSE stream.
191+
192+ Args:
193+ operation_id: Operation ID to monitor
194+ timeout: Maximum time to wait in seconds
195+ on_progress: Callback for progress updates
196+
197+ Returns:
198+ graph_id when operation completes
199+
200+ Raises:
201+ RuntimeError: If operation fails
202+ TimeoutError: If operation times out
203+ """
204+ stream_url = f"{ self .base_url } /v1/operations/{ operation_id } /stream"
205+ headers = {"X-API-Key" : self .token , "Accept" : "text/event-stream" }
206+
207+ with httpx .Client (timeout = httpx .Timeout (timeout + 5.0 )) as http_client :
208+ with http_client .stream ("GET" , stream_url , headers = headers ) as response :
209+ if response .status_code != 200 :
210+ raise RuntimeError (f"SSE connection failed: { response .status_code } " )
211+
212+ start_time = time .time ()
213+ event_type = None
214+ event_data = ""
215+
216+ for line in response .iter_lines ():
217+ # Check timeout
218+ if time .time () - start_time > timeout :
219+ raise TimeoutError (f"Graph creation timed out after { timeout } s" )
220+
221+ line = line .strip ()
222+
223+ if not line :
224+ # Empty line = end of event, process it
225+ if event_type and event_data :
226+ result = self ._process_sse_event (event_type , event_data , on_progress )
227+ if result is not None :
228+ return result
229+ event_type = None
230+ event_data = ""
231+ continue
232+
233+ if line .startswith ("event:" ):
234+ event_type = line [6 :].strip ()
235+ elif line .startswith ("data:" ):
236+ event_data = line [5 :].strip ()
237+ # Ignore other lines (comments, id, retry, etc.)
238+
239+ raise TimeoutError (f"SSE stream ended without completion after { timeout } s" )
240+
241+ def _process_sse_event (
242+ self ,
243+ event_type : str ,
244+ event_data : str ,
245+ on_progress : Optional [Callable [[str ], None ]],
246+ ) -> Optional [str ]:
247+ """
248+ Process a single SSE event.
249+
250+ Returns:
251+ graph_id if operation completed, None to continue waiting
252+
253+ Raises:
254+ RuntimeError: If operation failed
255+ """
256+ try :
257+ data = json .loads (event_data )
258+ except json .JSONDecodeError :
259+ logger .debug (f"Failed to parse SSE event data: { event_data } " )
260+ return None
261+
262+ if event_type == "operation_progress" :
263+ if on_progress :
264+ message = data .get ("message" , "Processing..." )
265+ percent = data .get ("progress_percent" )
266+ if percent is not None :
267+ on_progress (f"{ message } ({ percent :.0f} %)" )
268+ else :
269+ on_progress (message )
270+ return None
271+
272+ elif event_type == "operation_completed" :
273+ result = data .get ("result" , {})
274+ graph_id = result .get ("graph_id" ) if isinstance (result , dict ) else None
275+
276+ if graph_id :
277+ if on_progress :
278+ on_progress (f"Graph created: { graph_id } " )
279+ return graph_id
280+ else :
281+ raise RuntimeError ("Operation completed but no graph_id in result" )
282+
283+ elif event_type == "operation_error" :
284+ error = data .get ("error" , "Unknown error" )
285+ raise RuntimeError (f"Graph creation failed: { error } " )
286+
287+ elif event_type == "operation_cancelled" :
288+ reason = data .get ("reason" , "Operation was cancelled" )
289+ raise RuntimeError (f"Graph creation cancelled: { reason } " )
290+
291+ # Ignore other event types (keepalive, etc.)
292+ return None
293+
294+ def _wait_with_polling (
295+ self ,
296+ operation_id : str ,
297+ timeout : int ,
298+ poll_interval : int ,
299+ on_progress : Optional [Callable [[str ], None ]],
300+ client : Any ,
301+ ) -> str :
302+ """
303+ Wait for operation completion using polling.
304+
305+ Args:
306+ operation_id: Operation ID to monitor
307+ timeout: Maximum time to wait in seconds
308+ poll_interval: Time between status checks
309+ on_progress: Callback for progress updates
310+ client: Authenticated HTTP client
311+
312+ Returns:
313+ graph_id when operation completes
314+
315+ Raises:
316+ RuntimeError: If operation fails
317+ TimeoutError: If operation times out
318+ """
319+ from ..api .operations .get_operation_status import sync_detailed as get_status
320+
161321 max_attempts = timeout // poll_interval
162322 for attempt in range (max_attempts ):
163323 time .sleep (poll_interval )
0 commit comments