OpenAI: TypeSpec project for Assistants

specification/ai/OpenAI.Assistants/.gitignore

@@ -0,0 +1,3 @@
+**/package.json
+**/package-lock.json
+tsp-output/**

specification/ai/OpenAI.Assistants/README.md

@@ -0,0 +1,5 @@
+title: OpenAIAssistants
+clear-output-folder: false
+guessResourceKey: true
+isAzureSpec: true
+namespace: azure.openai.assistants

specification/ai/OpenAI.Assistants/assistants/main.tsp

@@ -0,0 +1,2 @@
+import "./models.tsp";
+import "./routes.tsp";

specification/ai/OpenAI.Assistants/assistants/models.tsp

@@ -0,0 +1,131 @@
+import "@typespec/versioning";
+import "../common/models.tsp";
+import "../tools/models.tsp";
+
+namespace Azure.AI.OpenAI.Assistants;
+
+using TypeSpec.Versioning;
+
+@doc("Represents an assistant that can call the model and use tools.")
+@added(ServiceApiVersions.v2023_11_06_beta)
+model Assistant {
+  @doc("The identifier, which can be referenced in API endpoints.")
+  id: string;
+
+  @doc("The object type, which is always assistant.")
+  object: "assistant";
+
+  @projectedName("json", "created_at")
+  @encode(DateTimeKnownEncoding.unixTimestamp, int32)
+  @doc("The Unix timestamp, in seconds, representing when this object was created.")
+  createdAt: utcDateTime;
+
+  #suppress "@azure-tools/typespec-azure-core/no-nullable" "explicitly required+nullable in mirrored API"
+  @doc("The name of the assistant.")
+  name: string | null;
+
+  #suppress "@azure-tools/typespec-azure-core/no-nullable" "explicitly required+nullable in mirrored API"
+  @doc("The description of the assistant.")
+  description: string | null;
+
+  @doc("The ID of the model to use.")
+  `model`: string;
+
+  #suppress "@azure-tools/typespec-azure-core/no-nullable" "explicitly required+nullable in mirrored API"
+  @doc("The system instructions for the assistant to use.")
+  instructions: string | null;
+
+  @doc("The collection of tools enabled for the assistant.")
+  tools: ToolDefinition[];
+
+  @projectedName("json", "file_ids")
+  @doc("A list of attached file IDs, ordered by creation date in ascending order.")
+  fileIds: string[];
+
+  ...OptionalMetadata;
+}
+
+@doc("The request details to use when creating a new assistant.")
+@added(ServiceApiVersions.v2023_11_06_beta)
+model AssistantCreationOptions {
+  @doc("The ID of the model to use.")
+  `model`: string;
+
+  @doc("The name of the new assistant.")
+  name?: string;
+
+  @doc("The description of the new assistant.")
+  description?: string;
+
+  @doc("The system instructions for the new assistant to use.")
+  instructions?: string;
+
+  @doc("The collection of tools to enable for the new assistant.")
+  tools?: ToolDefinition[];
+
+  @projectedName("json", "file_ids")
+  @doc("A list of previously uploaded file IDs to attach to the assistant.")
+  fileIds?: string[];
+
+  ...OptionalMetadata;
+}
+
+@doc("The request details to use when modifying an existing assistant.")
+@added(ServiceApiVersions.v2023_11_06_beta)
+model AssistantModificationOptions {
+  @doc("The ID of the model to use.")
+  `model`?: string;
+
+  @doc("The modified name for the assistant to use.")
+  name?: string;
+
+  @doc("The modified description for the assistant to use.")
+  description?: string;
+
+  @doc("The modified system instructions for the new assistant to use.")
+  instructions?: string;
+
+  @doc("The modified collection of tools to enable for the assistant.")
+  tools?: ToolDefinition[];
+
+  @projectedName("json", "file_ids")
+  @doc("The modified list of previously uploaded fileIDs to attach to the assistant.")
+  fileIds?: string[];
+
+  ...OptionalMetadata;
+}
+
+#suppress "@azure-tools/typespec-azure-core/composition-over-inheritance" "https://github.com/Azure/autorest.csharp/issues/4041"
+@doc("The status of an assistant deletion operation.")
+@added(ServiceApiVersions.v2023_11_06_beta)
+model AssistantDeletionStatus extends DeletionStatus {
+  @doc("The object type, which is always 'assistant.deleted'.")
+  object: "assistant.deleted";
+}
+
+@doc("Information about a file attached to an assistant, as used by tools that can read files.")
+@added(ServiceApiVersions.v2023_11_06_beta)
+model AssistantFile {
+  @doc("The identifier, which can be referenced in API endpoints.")
+  id: string;
+
+  @doc("The object type, which is always 'assistant.file'.")
+  object: "assistant.file";
+
+  @projectedName("json", "created_at")
+  @encode(DateTimeKnownEncoding.unixTimestamp, int32)
+  @doc("The Unix timestamp, in seconds, representing when this object was created.")
+  createdAt: utcDateTime;
+
+  @projectedName("json", "assistant_id")
+  @doc("The assistant ID that the file is attached to.")
+  assistantId: string;
+}
+
+#suppress "@azure-tools/typespec-azure-core/composition-over-inheritance" "https://github.com/Azure/autorest.csharp/issues/4041"
+@doc("The status of an assistant file deletion operation.")
+@added(ServiceApiVersions.v2023_11_06_beta)
+model AssistantFileDeletionStatus extends DeletionStatus {
+  @doc("The object type, which is always 'assistant.file.deleted'.")
+  object: "assistant.file.deleted";
+}

specification/ai/OpenAI.Assistants/assistants/routes.tsp

@@ -0,0 +1,159 @@
+import "@typespec/rest";
+import "@typespec/http";
+import "@typespec/versioning";
+import "./models.tsp";
+
+using TypeSpec.Rest;
+using TypeSpec.Http;
+using TypeSpec.Versioning;
+
+namespace Azure.AI.OpenAI.Assistants;
+
+@route("/assistants")
+interface Assistants {
+  /**
+   * Creates a new assistant.
+   *
+   * @returns The new assistant instance.
+   */
+  #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "not yet an Azure operation"
+  #suppress "@azure-tools/typespec-azure-core/no-operation-id" "non-standard operations"
+  #suppress "@azure-tools/typespec-azure-core/operation-missing-api-version" "not yet versioned"
+  @post
+  @added(ServiceApiVersions.v2023_11_06_beta)
+  createAssistant(...AssistantCreationOptions): Assistant;
+
+  /**
+   * Gets a list of assistants that were previously created.
+   *
+   * @returns The requested list of assistants.
+   */
+  #suppress "@azure-tools/typespec-azure-core/use-standard-names" "mirrored API responds with a container"
+  #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "not yet an Azure operation"
+  #suppress "@azure-tools/typespec-azure-core/no-operation-id" "non-standard operations"
+  #suppress "@azure-tools/typespec-azure-core/operation-missing-api-version" "not yet versioned"
+  @get
+  @added(ServiceApiVersions.v2023_11_06_beta)
+  listAssistants(...OpenAIListRequestOptions): OpenAIPageableListOf<Assistant>;
+
+  /**
+   * Retrieves an existing assistant.
+   *
+   * @param assistantId The ID of the assistant to retrieve.
+   * @returns The requested assistant instance.
+   */
+  #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "not yet an Azure operation"
+  #suppress "@azure-tools/typespec-azure-core/no-operation-id" "non-standard operations"
+  #suppress "@azure-tools/typespec-azure-core/operation-missing-api-version" "not yet versioned"
+  #suppress "@azure-tools/typespec-azure-core/use-standard-names" "mirrored API name parity"
+  @get
+  @route("{assistantId}")
+  @added(ServiceApiVersions.v2023_11_06_beta)
+  retrieveAssistant(@path assistantId: string): Assistant;
+
+  /**
+   * Modifies an existing assistant.
+   *
+   * @param assistantId The ID of the assistant to modify.
+   * @param modificationOptions The details of the modification to perform on the specified assistant.
+   * @returns The updated assistant instance.
+   */
+  #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "not yet an Azure operation"
+  #suppress "@azure-tools/typespec-azure-core/no-operation-id" "non-standard operations"
+  #suppress "@azure-tools/typespec-azure-core/operation-missing-api-version" "not yet versioned"
+  @post
+  @route("{assistantId}")
+  @added(ServiceApiVersions.v2023_11_06_beta)
+  modifyAssistant(
+    @path assistantId: string,
+    @body modificationOptions: AssistantModificationOptions,
+  ): Assistant;
+
+  /**
+   * Deletes an assistant.
+   *
+   * @param assistantId The ID of the assistant to delete.
+   * @returns Status information about the requested deletion operation.
+   */
+  #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "not yet an Azure operation"
+  #suppress "@azure-tools/typespec-azure-core/no-operation-id" "non-standard operations"
+  #suppress "@azure-tools/typespec-azure-core/operation-missing-api-version" "not yet versioned"
+  @delete
+  @route("{assistantId}")
+  @added(ServiceApiVersions.v2023_11_06_beta)
+  deleteAssistant(@path assistantId: string): AssistantDeletionStatus;
+
+  /**
+   * Attaches a previously uploaded file to an assistant for use by tools that can read files.
+   *
+   * @param assistantId The ID of the assistant to attach the file to.
+   * @param fileId The ID of the previously uploaded file to attach.
+   * @returns Information about the attached file.
+   */
+  #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "not yet an Azure operation"
+  #suppress "@azure-tools/typespec-azure-core/no-operation-id" "non-standard operations"
+  #suppress "@azure-tools/typespec-azure-core/operation-missing-api-version" "not yet versioned"
+  @post
+  @route("{assistantId}/files")
+  @added(ServiceApiVersions.v2023_11_06_beta)
+  createAssistantFile(
+    @path assistantId: string,
+    @projectedName("json", "file_id") fileId: string,
+  ): AssistantFile;
+
+  /**
+   * Gets a list of files attached to a specific assistant, as used by tools that can read files.
+   *
+   * @param assistantId The ID of the assistant to retrieve the list of attached files for.
+   * @returns The requested list of files attached to the specified assistant.
+   */
+  #suppress "@azure-tools/typespec-azure-core/use-standard-names" "mirrored API responds with a container"
+  #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "not yet an Azure operation"
+  #suppress "@azure-tools/typespec-azure-core/no-operation-id" "non-standard operations"
+  #suppress "@azure-tools/typespec-azure-core/operation-missing-api-version" "not yet versioned"
+  @get
+  @route("{assistantId}/files")
+  @added(ServiceApiVersions.v2023_11_06_beta)
+  listAssistantFiles(
+    @path assistantId: string,
+    ...OpenAIListRequestOptions,
+  ): OpenAIPageableListOf<AssistantFile>;
+
+  /**
+   * Retrieves a file attached to an assistant.
+   *
+   * @param assistantId The ID of the assistant associated with the attached file.
+   * @param fileId The ID of the file to retrieve.
+   * @returns A representation of the attached file.
+   */
+  #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "not yet an Azure operation"
+  #suppress "@azure-tools/typespec-azure-core/no-operation-id" "non-standard operations"
+  #suppress "@azure-tools/typespec-azure-core/operation-missing-api-version" "not yet versioned"
+  #suppress "@azure-tools/typespec-azure-core/use-standard-names" "mirrored API name parity"
+  @get
+  @route("{assistantId}/files/{fileId}")
+  @added(ServiceApiVersions.v2023_11_06_beta)
+  retrieveAssistantFile(
+    @path assistantId: string,
+    @path fileId: string,
+  ): AssistantFile;
+
+  /**
+   * Unlinks a previously attached file from an assistant, rendering it unavailable for use by tools that can read
+   * files.
+   *
+   * @param assistantId The ID of the assistant from which the specified file should be unlinked.
+   * @param fileId The ID of the file to unlink from the specified assistant.
+   * @returns Status information about the requested file association deletion.
+   */
+  #suppress "@azure-tools/typespec-azure-core/use-standard-operations" "not yet an Azure operation"
+  #suppress "@azure-tools/typespec-azure-core/no-operation-id" "non-standard operations"
+  #suppress "@azure-tools/typespec-azure-core/operation-missing-api-version" "not yet versioned"
+  @delete
+  @route("{assistantId}/files/{fileId}")
+  @added(ServiceApiVersions.v2023_11_06_beta)
+  deleteAssistantFile(
+    @path assistantId: string,
+    @path fileId: string,
+  ): AssistantFileDeletionStatus;
+}