fix(docs): correct stale flush() docstrings and restore before_galileo examples (SAO-16166)

splunk-ao-migration-tool/README.md

@@ -391,6 +391,7 @@ logger = GalileoLogger(project="my-project", log_stream="production")
 logger.start_session(name="my-session")
 logger.add_llm_span(input="Hello", output="Hi", model="gpt-4")
 logger.conclude()   # closes current span; no flush kwarg
+logger.flush()      # uploads traces
 ```
 
 ### After (splunk-ao)

splunk-ao-migration-tool/examples/before_galileo.py

@@ -21,3 +21,4 @@ def call_llm(prompt: str) -> str:
 logger.start_session(name="my-session")
 logger.add_llm_span(input="Hello", output="Hi", model="gpt-4")
 logger.conclude()   # closes current span; no flush kwarg
+logger.flush()      # uploads traces

src/splunk_ao/decorator.py

@@ -1309,9 +1309,9 @@ def flush(
         on_error: Callable[[Exception], None] | None = None,
     ) -> None:
         """
-        Upload all captured traces under a project and agent stream context to Splunk AO.
+        Drain completed spans for the given project and agent stream context; does not conclude open spans.
 
-        If no project or agent stream is provided, then the currently initialized context is used.
+        Falls back to the currently initialized context when no project or agent stream is provided.
 
         Parameters
         ----------
@@ -1349,9 +1349,7 @@ def _on_flush_error(exc: Exception) -> None:
 
     def flush_all(self) -> None:
         """
-        Upload all captured traces under all contexts to Splunk AO.
-
-        This method flushes all traces regardless of project or log stream.
+        Drain completed spans across all contexts; does not conclude open spans.
         """
         SplunkAOLoggerSingleton().flush_all()
 

src/splunk_ao/utils/singleton.py

@@ -295,11 +295,10 @@ def flush(
         agent_stream_id: str | None = None,
     ) -> None:
         """
-        Flush (upload and clear) a SplunkAOLogger instance.
+        Drain completed spans for a SplunkAOLogger instance; does not conclude open spans.
 
-        If both project and agent_stream are None, then all cached loggers are flushed
-        and cleared. Otherwise, only the specific logger corresponding to the provided
-        key (project, agent_stream) is flushed and removed.
+        If both project and agent_stream are None all cached loggers are drained,
+        otherwise only the logger for the given (project, agent_stream) key is drained.
 
         Parameters
         ----------
@@ -331,7 +330,7 @@ def flush(
                 self._splunk_ao_loggers[key].flush()
 
     def flush_all(self) -> None:
-        """Flush (upload and clear) all SplunkAOLogger instances."""
+        """Drain completed spans for all SplunkAOLogger instances; does not conclude open spans."""
         with self._lock:
             # Terminate and clear all logger instances.
             for logger in self._splunk_ao_loggers.values():