New parameters for streaming and background processing for Get/Request-Response

Author: mkht

Docs/Get-Response.md

@@ -15,6 +15,11 @@ Retrieves a model response with the given ID.
 ```
 Get-Response
     [-ResponseId] <String>
+    [-Include] <String[]>
+    [-Stream]
+    [-StreamOutputType <String>]
+    [-StartingAfter <Int32>]
+    [-OutputRawResponse]
     [-TimeoutSec <Int32>]
     [-MaxRetryCount <Int32>]
     [-ApiBase <Uri>]
@@ -49,6 +54,55 @@ Position: 0
 Accept pipeline input: True (ByPropertyName, ByValue)
 ```
 
+### -Include
+Specify additional output data to include in the model response.
+
+```yaml
+Type: String[]
+Required: False
+Position: Named
+```
+
+### -Stream
+If set, the model response data will be streamed to the client.
+
+```yaml
+Type: SwitchParameter
+Required: False
+Position: Named
+```
+
+### -StreamOutputType
+Specifying the format that the function output. This parameter is only valid for the stream output. This parameter is only valid for the stream output.
+  - `text`   : Output only text deltas that the model generated. (Default)  
+  - `object` : Output all events that the API respond.  
+
+```yaml
+Type: String
+Accepted values: text, object
+Required: False
+Position: Named
+Default value: text
+```
+
+### -StartingAfter
+The sequence number of the event after which to start streaming. This parameter is only valid for the stream output.
+
+```yaml
+Type: Int32
+Required: False
+Position: Named
+```
+
+### -OutputRawResponse
+If specifies this switch, an output of this function to be a raw response value from the API. (Normally JSON formatted string.)
+
+```yaml
+Type: SwitchParameter
+Required: False
+Position: Named
+```
+
 ### -TimeoutSec
 Specifies how long the request can be pending before it times out.  
 The default value is `0` (infinite).

Docs/Request-Response.md

@@ -68,6 +68,7 @@ Request-Response
     [-Temperature <Double>] 
     [-TopP <Double>] 
     [-Store <Boolean>]
+    [-Background]
     [-Stream]
     [-StreamOutputType <String>] 
     [-ReasoningEffort <String>] 
@@ -639,6 +640,15 @@ Position: Named
 Default value: True
 ```
 
+### -Background
+Whether to run the model response in the background. The default is `$false`.
+
+```yaml
+Type: SwitchParameter
+Required: False
+Position: Named
+```
+
 ### -Stream
 If set, the model response data will be streamed to the client.
 

Private/Invoke-OpenAIAPIRequestSSE.ps1

@@ -62,7 +62,10 @@ function Invoke-OpenAIAPIRequestSSE {
         [string]$AuthType = 'openai',
 
         [Parameter()]
-        [bool]$ReturnRawResponse = $false
+        [bool]$ReturnRawResponse = $false,
+
+        [Parameter()]
+        [uint64]$First = [uint64]::MaxValue
     )
 
     $InternalParams = Initialize-OpenAIAPIRequestParam @PSBoundParameters
@@ -78,6 +81,9 @@ function Invoke-OpenAIAPIRequestSSE {
     # Create HttpClient that has 5 min lifetime to reuse
     if ($null -eq $script:HttpClientHandler.HttpClient -or $script:HttpClientHandler.Expires -lt [datetime]::Now) {
         $script:HttpClientHandler.HttpClient = [System.Net.Http.HttpClient]::new()
+        if ($TimeoutSec -gt 0) {
+            $script:HttpClientHandler.HttpClient.Timeout = [TimeSpan]::FromSeconds($TimeoutSec)
+        }
         $script:HttpClientHandler.Expires = [datetime]::Now.AddMinutes(5)
     }
 
@@ -208,14 +214,45 @@ function Invoke-OpenAIAPIRequestSSE {
                     -Target ($ApiKey, $Organization) -First $startIdx -Last $lastIdx -MaxNumberOfAsterisks 45)
         }
 
-        while (-not $StreamReader.EndOfStream) {
+        [uint64]$DataCounter = 0
+        while ($DataCounter -lt $First) {
             $data = $null
             #Timeout
             $CancelToken.ThrowIfCancellationRequested()
-            #Retrive response content
-            $data = [string]$StreamReader.ReadLine()
+
+            # Note:
+            # In some situations, the server may unilaterally close the connection without sending any data.
+            # To avoid long blocking waits that prevent user cancellation, we use a polling interval.
+            # We allow a maximum total wait of 30 seconds while checking for cancellation every 500 ms.
+            $timeoutMs = 30000
+            $pollInterval = 500  # milliseconds
+            $stopwatch = [System.Diagnostics.Stopwatch]::StartNew()
+
+            $readTask = $StreamReader.ReadLineAsync()
+            while (-not $CancelToken.IsCancellationRequested -and $stopwatch.ElapsedMilliseconds -lt $timeoutMs) {
+                if ($readTask.Wait($pollInterval, $CancelToken)) {
+                    break
+                }
+            }
+
+            if (-not $readTask.IsCompleted) {
+                Write-Warning 'Timeout while waiting for response. It seems that the server is not sending any data.'
+                $cts.Cancel()  # Cancel the request
+                $CancelToken.ThrowIfCancellationRequested()
+                break
+            }
+
+            # Read data
+            $data = $readTask.Result
+            # Check end of stream
+            if ($null -eq $data) {
+                Write-Verbose -Message ('End of stream signal received.')
+                break
+            }
             # Skip on empty
-            if ([string]::IsNullOrWhiteSpace($data)) { continue }
+            elseif ([string]::IsNullOrWhiteSpace($data)) {
+                continue
+            }
             else {
                 # Debug output
                 if ($IsDebug) {
@@ -237,17 +274,19 @@ function Invoke-OpenAIAPIRequestSSE {
                 elseif ($data.StartsWith('data: ', [StringComparison]::Ordinal)) {
                     # End of stream
                     if ($data -eq 'data: [DONE]') {
-                        Write-Verbose -Message ('Received the signal of the end of stream')
+                        Write-Verbose -Message ('End of data received.')
                         break
                     }
                     else {
+                        # Increment counter
+                        $DataCounter++
+
                         #Output
                         Write-Output $data.Substring(6)    # ("data: ").Length -> 6
                     }
                 }
             }
         }
-
     }
     catch [OperationCanceledException] {
         # Convert OperationCanceledException to TimeoutException
@@ -268,7 +307,7 @@ function Invoke-OpenAIAPIRequestSSE {
         try {
             if ($null -ne $cts) { $cts.Dispose() }
             if ($null -ne $HttpResponse) { $HttpResponse.Dispose() }
-            if ($null -ne $ResponseStream) { $ResponseStream.Dispose() }
+            if ($null -ne $StreamReader) { $StreamReader.Dispose() }
             if ($null -ne $RequestMessage) { $RequestMessage.Dispose() }
         }
         catch {}

Public/Responses/Get-Response.ps1

@@ -10,6 +10,27 @@ function Get-Response {
         [Alias('response_id')]
         [string][UrlEncodeTransformation()]$ResponseId,
 
+        [Parameter()]
+        [Completions('file_search_call.results', 'message.input_image.image_url', 'computer_call_output.output.image_url', 'reasoning.encrypted_content')]
+        [AllowEmptyCollection()]
+        [string[]]$Include,
+
+        #region Stream
+        [Parameter()]
+        [switch]$Stream = $false,
+
+        [Parameter()]
+        [ValidateSet('text', 'object')]
+        [string]$StreamOutputType = 'text',
+
+        [Parameter()]
+        [Alias('starting_after')]
+        [int]$StartingAfter,
+        #endregion Stream
+
+        [Parameter()]
+        [switch]$OutputRawResponse,
+
         # For internal use
         [Parameter(DontShow)]
         [switch]$Primitive,
@@ -63,11 +84,26 @@ function Get-Response {
         #region Construct Query URI
         $UriBuilder = [System.UriBuilder]::new($OpenAIParameter.Uri)
         $UriBuilder.Path += "/$ResponseId"
+        $QueryParam = [System.Web.HttpUtility]::ParseQueryString($UriBuilder.Query)
+
+        if ($Stream) {
+            $QueryParam.Add('stream', ($Stream.ToString().ToLowerInvariant()))
+        }
+        if ($PSBoundParameters.ContainsKey('StartingAfter')) {
+            $QueryParam.Add('starting_after', $StartingAfter)
+        }
+        if ($PSBoundParameters.ContainsKey('Include')) {
+            foreach ($IncludeItem in $Include) {
+                $QueryParam.Add('include[]', $IncludeItem)
+            }
+        }
+
+        $UriBuilder.Query = $QueryParam.ToString()
         $QueryUri = $UriBuilder.Uri
         #endregion
 
         #region Send API Request
-        $params = @{
+        $splat = @{
             Method            = 'Get'
             Uri               = $QueryUri
             # ContentType       = $OpenAIParameter.ContentType
@@ -80,21 +116,65 @@ function Get-Response {
             AdditionalHeaders = $AdditionalHeaders
             AdditionalBody    = $AdditionalBody
         }
-        $Response = Invoke-OpenAIAPIRequest @params
 
-        # error check
-        if ($null -eq $Response) {
+        #region Send API Request (Stream)
+        if ($Stream) {
+            # Stream output
+            Invoke-OpenAIAPIRequestSSE @splat |
+                Where-Object {
+                    -not [string]::IsNullOrEmpty($_)
+                } | ForEach-Object -Process {
+                    if ($OutputRawResponse) {
+                        Write-Output $_
+                    }
+                    else {
+                        # Parse response object
+                        try {
+                            $Response = $_ | ConvertFrom-Json -ErrorAction Stop
+                        }
+                        catch {
+                            Write-Error -Exception $_.Exception
+                        }
+
+                        if ($StreamOutputType -eq 'text') {
+                            if ($Response.type -cne 'response.output_text.delta') {
+                                continue
+                            }
+                            Write-Output $Response.delta
+                        }
+                        else {
+                            Write-Output $Response
+                        }
+                    }
+                }
+
             return
         }
         #endregion
 
-        #region Parse response object
-        try {
-            $Response = $Response | ConvertFrom-Json -ErrorAction Stop
-        }
-        catch {
-            Write-Error -Exception $_.Exception
-            return
+        #region Send API Request (No Stream)
+        else {
+            $Response = Invoke-OpenAIAPIRequest @splat
+
+            # error check
+            if ($null -eq $Response) {
+                return
+            }
+            #endregion
+
+            #region Parse response object
+            if ($OutputRawResponse) {
+                Write-Output $Response
+                return
+            }
+            try {
+                $Response = $Response | ConvertFrom-Json -ErrorAction Stop
+            }
+            catch {
+                Write-Error -Exception $_.Exception
+                return
+            }
+            #endregion
         }
         #endregion