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.ai.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,147 @@
+import "@typespec/versioning";
+import "../common/models.tsp";
+import "../tools/models.tsp";
+
+namespace Azure.AI.OpenAI.Assistants;
+
+using TypeSpec.Http;
+using TypeSpec.Versioning;
+
+@doc("Represents an assistant that can call the model and use tools.")
+@added(ServiceApiVersions.v2024_02_15_preview)
+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" "OpenAI uses explicit nullability, distinct from optionality"
+  @doc("The name of the assistant.")
+  name: string | null;
+
+  #suppress "@azure-tools/typespec-azure-core/no-nullable" "OpenAI uses explicit nullability, distinct from optionality"
+  @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" "OpenAI uses explicit nullability, distinct from optionality"
+  @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[] = [];
+
+  ...RequiredNullableMetadata;
+}
+
+@doc("The request details to use when creating a new assistant.")
+@added(ServiceApiVersions.v2024_02_15_preview)
+model AssistantCreationOptions {
+  @doc("The ID of the model to use.")
+  `model`: string;
+
+  #suppress "@azure-tools/typespec-azure-core/no-nullable" "OpenAI uses explicit nullability, distinct from optionality"
+  @doc("The name of the new assistant.")
+  name?: string | null;
+
+  #suppress "@azure-tools/typespec-azure-core/no-nullable" "OpenAI uses explicit nullability, distinct from optionality"
+  @doc("The description of the new assistant.")
+  description?: string | null;
+
+  #suppress "@azure-tools/typespec-azure-core/no-nullable" "OpenAI uses explicit nullability, distinct from optionality"
+  @doc("The system instructions for the new assistant to use.")
+  instructions?: string | null;
+
+  #suppress "@azure-tools/typespec-azure-core/no-nullable" "OpenAI uses explicit nullability, distinct from optionality"
+  @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[] = [];
+
+  ...OptionalNullableMetadata;
+}
+
+@doc("The request details to use when modifying an existing assistant.")
+@added(ServiceApiVersions.v2024_02_15_preview)
+model UpdateAssistantOptions {
+  @path
+  @doc("The ID of the assistant to modify.")
+  assistantId: string;
+
+  @doc("The ID of the model to use.")
+  `model`?: string;
+
+  #suppress "@azure-tools/typespec-azure-core/no-nullable" "OpenAI uses explicit nullability, distinct from optionality"
+  @doc("The modified name for the assistant to use.")
+  name?: string | null;
+
+  #suppress "@azure-tools/typespec-azure-core/no-nullable" "OpenAI uses explicit nullability, distinct from optionality"
+  @doc("The modified description for the assistant to use.")
+  description?: string | null;
+
+  #suppress "@azure-tools/typespec-azure-core/no-nullable" "OpenAI uses explicit nullability, distinct from optionality"
+  @doc("The modified system instructions for the new assistant to use.")
+  instructions?: string | null;
+
+  @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[] = [];
+
+  ...OptionalNullableMetadata;
+}
+
+#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.v2024_02_15_preview)
+model AssistantDeletionStatus {
+  ...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.v2024_02_15_preview)
+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.v2024_02_15_preview)
+model AssistantFileDeletionStatus {
+  ...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,154 @@
+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;
+
+/**
+ * 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.v2024_02_15_preview)
+@route("/assistants")
+op 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.v2024_02_15_preview)
+@route("/assistants")
+op 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("/assistants/{assistantId}")
+@added(ServiceApiVersions.v2024_02_15_preview)
+op getAssistant(@path assistantId: string): Assistant;
+
+/**
+ * Modifies an existing assistant.
+ *
+ * @param updateAssistantOptions The details of the modification to perform on a 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("/assistants/{assistantId}")
+@added(ServiceApiVersions.v2024_02_15_preview)
+op updateAssistant(...UpdateAssistantOptions): 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("/assistants/{assistantId}")
+@added(ServiceApiVersions.v2024_02_15_preview)
+op 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("assistants/{assistantId}/files")
+@added(ServiceApiVersions.v2024_02_15_preview)
+op 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("assistants/{assistantId}/files")
+@added(ServiceApiVersions.v2024_02_15_preview)
+op 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("assistants/{assistantId}/files/{fileId}")
+@added(ServiceApiVersions.v2024_02_15_preview)
+op getAssistantFile(
+  @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("assistants/{assistantId}/files/{fileId}")
+@added(ServiceApiVersions.v2024_02_15_preview)
+op deleteAssistantFile(
+  @path assistantId: string,
+  @path fileId: string,
+): AssistantFileDeletionStatus;