Azure OpenAI: reuse LRO response model as status polling model (Azure#24556)

* Azure OpenAI: reuse LRO response model as status polling model

* incorporate unreachable type omission for limitation of breaking change triggers

* batch rename for new LRO tack

* Updates after clarification on sync parity snap

* Update: adjustments after re-snap to plans for converged sync API

* Adjustments based on feedback and .NET viability experiments

* Example naming update (caught by CI)

* Example update

* PR feedback and re-disabling ts (will treat separately)

Author: trrwilson

specification/cognitiveservices/OpenAI.Inference/.gitignore

@@ -0,0 +1,2 @@
+**/package.json
+**/package-lock.json

specification/cognitiveservices/OpenAI.Inference/client.tsp

@@ -3,8 +3,12 @@ import "./main.tsp";
 
 using Azure.ClientGenerator.Core;
 
-// Azure-specific long-running operations should be treated as implementation details
-@@internal(Azure.OpenAI.startGenerateImage);
+// Azure-specific long-running operations should be treated as implementation details that are wrapped into
+// appropriately merged public surface.
+@@internal(Azure.OpenAI.beginAzureBatchImageGeneration);
+@@internal(Azure.OpenAI.getAzureBatchImageGenerationOperationStatus);
 
-// Some models from client-internal LROs are still desired for custom public surface
+// Some models from client-internal LROs are still desired for custom public surface.
 @@include(Azure.OpenAI.ImageGenerationOptions);
+@@include(Azure.OpenAI.ImageLocation);
+@@include(Azure.OpenAI.ImageGenerations);

specification/cognitiveservices/OpenAI.Inference/examples/2023-06-01-preview/get_image_operation_status.json

@@ -1,5 +1,5 @@
 {
-  "operationId": "GetImageOperationStatus",
+  "operationId": "GetAzureBatchImageGenerationOperationStatus",
   "title": "Returns the status of the images operation",
   "parameters": {
     "endpoint": "{endpoint}",

specification/cognitiveservices/OpenAI.Inference/examples/2023-06-01-preview/start_generate_image.json

@@ -1,5 +1,5 @@
 {
-  "operationId": "StartGenerateImage",
+  "operationId": "BeginAzureBatchImageGeneration",
   "title": "Starts the generation of a batch of images from a text caption",
   "parameters": {
     "endpoint": "{endpoint}",

specification/cognitiveservices/OpenAI.Inference/models/images.tsp

@@ -1,6 +1,7 @@
 import "@azure-tools/typespec-azure-core";
 import "@typespec/http";
 import "@typespec/versioning";
+import "./operations.common.tsp";
 
 using Azure.Core;
 using TypeSpec.Http;
@@ -21,45 +22,76 @@ enum ImageSize {
   Size1024x1024: "1024x1024",
 }
 
+@doc("The format in which the generated images are returned.")
+@added(ServiceApiVersions.v2023_06_01_Preview)
+enum ImageGenerationResponseFormat {
+  @doc("Image generation response items should provide a URL from which the image may be retrieved.")
+  Url: "url",
+
+  @doc("Image generation response items should provide image data as a base64-encoded string.")
+  Base64: "b64_json",
+}
+
 @doc("Represents the request data used to generate images.")
 @added(ServiceApiVersions.v2023_06_01_Preview)
 model ImageGenerationOptions {
   @doc("A description of the desired images.")
   prompt: string;
 
   @doc("The number of images to generate (defaults to 1).")
+  @projectedName("csharp", "ImageCount")
   n?: int32 = 1;
 
   @doc("The desired size of the generated images. Must be one of 256x256, 512x512, or 1024x1024 (defaults to 1024x1024).")
   size?: ImageSize = ImageSize.Size1024x1024;
 
+  @doc("""
+    The format in which image generation response items should be presented.
+    Azure OpenAI only supports URL response items.
+  """)
+  @projectedName("json", "response_format")
+  responseFormat?: ImageGenerationResponseFormat;
+
   @doc("A unique identifier representing your end-user, which can help to monitor and detect abuse.")
   user?: string;
 }
 
-@doc("The image url if successful, and an error otherwise.")
+@doc("An image response item that provides a URL from which an image may be accessed.")
 @added(ServiceApiVersions.v2023_06_01_Preview)
+@projectedName("csharp", "InternalImageLocation")
 model ImageLocation {
   @doc("The URL that provides temporary access to download the generated image.")
-  url?: url;
+  url: url;
+}
 
-  @doc("The error if the operation failed.")
-  error?: Foundations.Error;
+@doc("An image response item that directly represents the image data as a base64-encoded string.")
+@added(ServiceApiVersions.v2023_06_01_Preview)
+model ImagePayload {
+  @doc("The complete data for an image represented as a base64-encoded string.")
+  @projectedName("json", "b64_json")
+  base64Data: string;
 }
 
 @doc("The result of the operation if the operation succeeded.")
 @added(ServiceApiVersions.v2023_06_01_Preview)
-model ImageResponse {
+model ImageGenerations {
   @doc("A timestamp when this job or item was created (in unix epochs).")
+  @projectedName("csharp", "InternalCreatedSecondsAfterUnixEpoch")
   created: int64;
 
+  #suppress "@azure-tools/typespec-autorest/union-unsupported" "openapi v2 not required"
   @doc("The images generated by the operator.")
-  data: ImageLocation[];
+  @projectedName("csharp", "InternalEmittedImageResponseItems")
+  data: ImageLocation[] | ImagePayload[];
 }
 
-@doc("The result of the operation if the operation succeeded.")
+// Note: pending resolution of  cross-language code emission behavior for long-running operations, image generation
+//        reuses its final operation response model as its status polling model.
+
+// @lroStatus
+@doc("A polling status update or final response payload for an image operation.")
 @added(ServiceApiVersions.v2023_06_01_Preview)
-model ImageOperationResponse {
+model BatchImageGenerationOperationResponse {
   @doc("The ID of the operation.")
   id: string;
 
@@ -70,74 +102,11 @@ model ImageOperationResponse {
   expires?: int64;
 
   @doc("The result of the operation if the operation succeeded.")
-  result?: ImageResponse;
+  result?: ImageGenerations;
 
   @doc("The status of the operation")
-  status: State;
+  status: AzureOpenAIOperationState;
 
   @doc("The error if the operation failed.")
   error?: Foundations.Error;
 }
-
-@lroStatus
-@doc("The state of a job or item.")
-@added(ServiceApiVersions.v2023_06_01_Preview)
-enum State {
-  @doc("The operation was created and is queued to be processed in the future.")
-  notRunning,
-
-  @doc("The operation has started to be processed.")
-  running,
-
-  @lroSucceeded
-  @doc("The operation has successfully be processed and is ready for consumption.")
-  succeeded,
-
-  @lroCanceled
-  @doc("The operation has been canceled and is incomplete.")
-  canceled,
-
-  @lroFailed
-  @doc("The operation has completed processing with a failure and cannot be further consumed.")
-  failed,
-}
-
-@doc("Provides status details for long running operations.")
-@added(ServiceApiVersions.v2023_06_01_Preview)
-model ImageOperationStatus {
-  @key("operationId")
-  @visibility("read", "query")
-  @doc("The unique ID of the operation.")
-  id: string;
-
-  @doc("The status of the operation")
-  status: State;
-}
-
-#suppress "@azure-tools/typespec-azure-core/long-running-polling-operation-required" "template"
-@Foundations.Private.needsRoute
-@post
-@doc("Long running operation template to match Azure OpenAI .")
-op OaiLongRunningRpcOperation<
-  TParams extends TypeSpec.Reflection.Model,
-  TResponse extends TypeSpec.Reflection.Model,
-  TStatusResult extends TypeSpec.Reflection.Model,
-  TStatusError = Foundations.Error,
-  Traits extends TypeSpec.Reflection.Model = {},
-  TErrorResponse = Azure.Core.Foundations.ErrorResponse
-> is Foundations.Operation<
-  TParams &
-    Azure.Core.Traits.Private.TraitProperties<
-      Traits,
-      Azure.Core.Traits.TraitLocation.Parameters
-    >,
-  Azure.Core.Foundations.AcceptedResponse &
-    TResponse &
-    Foundations.LongRunningStatusLocation<TStatusResult> &
-    Azure.Core.Traits.Private.TraitProperties<
-      Traits,
-      Azure.Core.Traits.TraitLocation.Response
-    >,
-  Traits,
-  TErrorResponse
->;

specification/cognitiveservices/OpenAI.Inference/models/operations.common.tsp

@@ -0,0 +1,57 @@
+import "@azure-tools/typespec-azure-core";
+import "@typespec/http";
+
+using Azure.Core;
+using TypeSpec.Http;
+
+namespace Azure.OpenAI;
+
+@lroStatus
+@doc("The state of a job or item.")
+enum AzureOpenAIOperationState {
+  @doc("The operation was created and is queued to be processed in the future.")
+  notRunning,
+
+  @doc("The operation has started to be processed.")
+  running,
+
+  @lroSucceeded
+  @doc("The operation has successfully be processed and is ready for consumption.")
+  succeeded,
+
+  @lroCanceled
+  @doc("The operation has been canceled and is incomplete.")
+  canceled,
+
+  @lroFailed
+  @doc("The operation has completed processing with a failure and cannot be further consumed.")
+  failed,
+}
+
+#suppress "@azure-tools/typespec-azure-core/long-running-polling-operation-required" "template"
+@Foundations.Private.needsRoute
+@post
+@doc("Long running operation template to match Azure OpenAI .")
+op OaiLongRunningRpcOperation<
+  TParams extends TypeSpec.Reflection.Model,
+  TResponse extends TypeSpec.Reflection.Model,
+  TStatusResult extends TypeSpec.Reflection.Model,
+  TStatusError = Foundations.Error,
+  Traits extends TypeSpec.Reflection.Model = {},
+  TErrorResponse = Azure.Core.Foundations.ErrorResponse
+> is Foundations.Operation<
+  TParams &
+    Azure.Core.Traits.Private.TraitProperties<
+      Traits,
+      Azure.Core.Traits.TraitLocation.Parameters
+    >,
+  Azure.Core.Foundations.AcceptedResponse &
+    TResponse &
+    Foundations.LongRunningStatusLocation<TStatusResult> &
+    Azure.Core.Traits.Private.TraitProperties<
+      Traits,
+      Azure.Core.Traits.TraitLocation.Response
+    >,
+  Traits,
+  TErrorResponse
+>;

specification/cognitiveservices/OpenAI.Inference/routes.tsp

@@ -52,29 +52,32 @@ op getChatCompletions is ResourceAction<
   ChatCompletions
 >;
 
+// Note: pending resolution of  cross-language code emission behavior for long-running operations, image generation
+//        reuses its final operation response model as its status polling model.
+
 #suppress "@azure-tools/typespec-azure-core/no-rpc-path-params" "Allowed because this is a non-standard status polling operation."
 @doc("Returns the status of the images operation")
 @added(ServiceApiVersions.v2023_06_01_Preview)
 @route("/operations/images/{operationId}")
-op getImageOperationStatus is RpcOperation<
+op getAzureBatchImageGenerationOperationStatus is RpcOperation<
   {
     @doc(".") @path operationId: string;
   },
-  ImageOperationResponse
+  BatchImageGenerationOperationResponse
 >;
 
 #suppress "@azure-tools/typespec-azure-core/use-standard-operations" ""
 @doc("Starts the generation of a batch of images from a text caption")
 @added(ServiceApiVersions.v2023_06_01_Preview)
 @route("/images/generations:submit")
 @pollingOperation(
-  getImageOperationStatus,
+  getAzureBatchImageGenerationOperationStatus,
   {
     operationId: ResponseProperty<"id">,
   }
 )
-op startGenerateImage is OaiLongRunningRpcOperation<
+op beginAzureBatchImageGeneration is OaiLongRunningRpcOperation<
   ImageGenerationOptions,
-  ImageOperationResponse,
-  ImageOperationStatus
+  BatchImageGenerationOperationResponse,
+  BatchImageGenerationOperationResponse
 >;

specification/cognitiveservices/OpenAI.Inference/tspconfig.yaml

@@ -11,28 +11,18 @@ options:
     output-file: "{azure-resource-provider-folder}/AzureOpenAI/inference/{version-status}/{version}/generated.json"
     azure-resource-provider-folder: "data-plane"
     examples-directory: examples
-  # Uncomment this line and add "@azure-tools/cadl-python" to your package.json to generate Python code
-  # "@azure-tools/cadl-python":
-  #   "basic-setup-py": true
-  #   "package-version":
-  #   "package-name":
-  #   "output-path":
-  # Uncomment this line and add "@azure-tools/cadl-java" to your package.json to generate Java code
-  # "@azure-tools/cadl-java": true
-  # Uncomment this line and add "@azure-tools/cadl-csharp" to your package.json to generate C# code
+    omit-unreachable-types: true
   "@azure-tools/typespec-csharp":
     package-dir: "Azure.AI.OpenAI"
     namespace: "Azure.AI.OpenAI"
     clear-output-folder: true
     model-namespace: false
-  # https://github.com/Azure/azure-rest-api-specs/issues/24497
   "@azure-tools/typespec-java":
     package-dir: "azure-ai-openai"
     namespace: "com.azure.ai.openai"
     partial-update: true
     enable-sync-stack: true
     generate-tests: false
-  # https://github.com/Azure/azure-rest-api-specs/issues/24498
   # "@azure-tools/typespec-ts":
   #   package-dir: "azure-ai-openai"
   #   emitter-output-dir: "{project-root}/generated"

specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2023-06-01-preview/examples/get_image_operation_status.json

@@ -1,5 +1,5 @@
 {
-  "operationId": "GetImageOperationStatus",
+  "operationId": "GetAzureBatchImageGenerationOperationStatus",
   "title": "Returns the status of the images operation",
   "parameters": {
     "endpoint": "{endpoint}",

specification/cognitiveservices/data-plane/AzureOpenAI/inference/preview/2023-06-01-preview/examples/start_generate_image.json

@@ -1,5 +1,5 @@
 {
-  "operationId": "StartGenerateImage",
+  "operationId": "BeginAzureBatchImageGeneration",
   "title": "Starts the generation of a batch of images from a text caption",
   "parameters": {
     "endpoint": "{endpoint}",