1DP Azure AI Projects Typespec

specification/ai/Azure.AI.Projects/client.tsp

@@ -0,0 +1,39 @@
+import "@azure-tools/typespec-client-generator-core";
+import "./main.tsp";
+
+using Azure.ClientGenerator.Core;
+
+@@clientName(Azure.AI.Projects, "AIProjectClient");
+
+// Shorter method names for SDK datasets operations
+@@clientName(Azure.AI.Projects.Datasets.listLatest, "list");
+@@clientName(Azure.AI.Projects.Datasets.getVersion, "get");
+@@clientName(Azure.AI.Projects.Datasets.deleteVersion, "delete");
+@@clientName(Azure.AI.Projects.Datasets.createOrUpdateVersion,
+  "createOrUpdate"
+);
+@@clientName(Azure.AI.Projects.Datasets.startPendingUploadVersion,
+  "pendingUpload"
+);
+
+// Shorter method names for SDK Index operations
+@@clientName(Azure.AI.Projects.Indexes.listLatest, "list");
+@@clientName(Azure.AI.Projects.Indexes.getVersion, "get");
+@@clientName(Azure.AI.Projects.Indexes.deleteVersion, "delete");
+@@clientName(Azure.AI.Projects.Indexes.createOrUpdateVersion, "createOrUpdate");
+
+// In Python, the emitter changes "keys" to "keys_property", since there is already
+// a "keys" method in the generated code due to usage of MutableMapping. Call it credential_keys instead.
+@@clientName(Azure.AI.Projects.CustomCredential.keys,
+  "credential_keys",
+  "python"
+);
+
+// Make these two internal, since all SDKs hand-write a single public method with boolean "includeCredentials"
+// input parameter that calls either on these two.
+@@access(Azure.AI.Projects.Connections.get, Access.internal);
+@@access(Azure.AI.Projects.Connections.getWithCredentials, Access.internal);
+
+// For some reason for Python the emitter creates an empty ServicePatternsOperations operation
+// class. Mark it as internal here. Apply to all languages just in case.
+//@@access(Azure.AI.Projects.ServicePatterns, Access.internal);  <== this did not work. It makes all methods internal.

specification/ai/Azure.AI.Projects/common/models.tsp

@@ -0,0 +1,117 @@
+import "@typespec/rest";
+import "@typespec/versioning";
+import "@azure-tools/typespec-azure-core";
+import "@azure-tools/typespec-azure-resource-manager";
+
+namespace Azure.AI.Projects;
+
+alias AssetBase = {
+  @doc("Asset ID, a unique identifier for the asset")
+  @visibility(Lifecycle.Read)
+  id?: string;
+
+  @doc("The name of the resource")
+  @visibility(Lifecycle.Read)
+  @key
+  name: string;
+
+  @doc("The version of the resource")
+  @visibility(Lifecycle.Read)
+  version: string;
+
+  @doc("The asset description text.")
+  @visibility(Lifecycle.Create, Lifecycle.Update)
+  description?: string;
+
+  @doc("Tag dictionary. Tags can be added, removed, and updated.")
+  @visibility(Lifecycle.Create, Lifecycle.Update)
+  tags?: Record<string>;
+};
+
+#suppress "@azure-tools/typespec-providerhub/no-inline-model" "Need to create responses correctly"
+alias ResourceCreatedResponse<T extends TypeSpec.Reflection.Model> = TypeSpec.Http.Response<201> &
+  T;
+
+#suppress "@azure-tools/typespec-providerhub/no-inline-model" "Need to create responses correctly"
+alias OkResponse<T extends TypeSpec.Reflection.Model> = TypeSpec.Http.Response<200> &
+  T;
+
+// Pending upload spec
+
+// Define a URI alias for clarity.
+alias Uri = string;
+
+@doc("The type of pending upload.")
+union PendingUploadType {
+  string,
+
+  @doc("No pending upload.")
+  none: "None",
+
+  @doc("Blob Reference is the only supported type.")
+  BlobReference: "BlobReference",
+}
+
+@doc("The type of credential used to access the storage account.")
+union PendingUploadCredentialType {
+  string,
+
+  @doc("SAS credential type.")
+  sas: "SAS",
+}
+
+@doc("Represents a request for a pending upload.")
+model PendingUploadRequest {
+  @doc("If PendingUploadId is not provided, a random GUID will be used.")
+  pendingUploadId?: string;
+
+  @doc("Azure Storage Account connection name to use for generating temporary SAS token")
+  connectionName?: string;
+
+  @doc("BlobReference is the only supported type.")
+  pendingUploadType: PendingUploadType.BlobReference;
+}
+
+@doc("Represents the response for a pending upload request")
+model PendingUploadResponse {
+  @doc("Container-level read, write, list SAS.")
+  blobReference: BlobReference;
+
+  @doc("ID for this upload request.")
+  pendingUploadId: string;
+
+  @doc("Version of asset to be created if user did not specify version when initially creating upload")
+  version?: string;
+
+  @doc("BlobReference is the only supported type")
+  pendingUploadType: PendingUploadType.BlobReference;
+}
+
+@doc("SAS Credential definition")
+model SasCredential {
+  @doc("SAS uri")
+  @visibility(Lifecycle.Read)
+  sasUri: string;
+
+  @visibility(Lifecycle.Read)
+  @doc("Type of credential")
+  type: "SAS";
+}
+
+@doc("Blob reference details.")
+model BlobReference {
+  @doc("Blob URI path for client to upload data. Example: https://blob.windows.core.net/Container/Path")
+  blobUri: Uri;
+
+  @doc("ARM ID of the storage account to use.")
+  storageAccountArmId: string;
+
+  @doc("Credential info to access the storage account.")
+  credential: SasCredential;
+}
+
+@doc("Represents a reference to a blob for consumption")
+model AssetCredentialResponse {
+  @doc("Credential info to access the storage account.")
+  blobReference: BlobReference;
+}

specification/ai/Azure.AI.Projects/connections/models.tsp

@@ -0,0 +1,157 @@
+import "@typespec/rest";
+import "@azure-tools/typespec-autorest";
+import "@typespec/versioning";
+import "@azure-tools/typespec-azure-core";
+import "@typespec/openapi";
+import "@typespec/versioning";
+
+using TypeSpec.Rest;
+using TypeSpec.Versioning;
+
+namespace Azure.AI.Projects;
+
+@doc("Response from the list and get connections operations")
+@resource("connections")
+@added(Versions.v2025_05_01)
+model Connection {
+  @doc("The friendly name of the connection, provided by the user.")
+  @visibility(Lifecycle.Read)
+  @key("name")
+  name: string;
+
+  @doc("A unique identifier for the connection, generated by the service")
+  @visibility(Lifecycle.Read)
+  id: string;
+
+  @doc("Category of the connection")
+  @visibility(Lifecycle.Read)
+  type: ConnectionType;
+
+  @doc("The connection URL to be used for this service")
+  @visibility(Lifecycle.Read)
+  target: string;
+
+  @doc("Whether the connection is tagged as the default connection of its type")
+  @visibility(Lifecycle.Read)
+  isDefault: boolean;
+
+  @doc("The credentials used by the connection")
+  @visibility(Lifecycle.Read)
+  credentials: BaseCredentials;
+
+  @doc("Metadata of the connection")
+  @visibility(Lifecycle.Read)
+  metadata: Record<string>;
+}
+
+@doc("A base class for connection credentials")
+@discriminator("type")
+model BaseCredentials {
+  @doc("The type of credential used by the connection")
+  @visibility(Lifecycle.Read)
+  type: CredentialType;
+}
+
+@doc("API Key Credential definition")
+model ApiKeyCredentials extends BaseCredentials {
+  @doc("The credential type")
+  @visibility(Lifecycle.Read)
+  type: CredentialType.apiKey;
+
+  @doc("API Key")
+  @visibility(Lifecycle.Read)
+  @encodedName("application/json", "key")
+  apiKey?: string;
+}
+
+#suppress "@azure-tools/typespec-azure-core/casing-style"
+@doc("Entra ID credential definition")
+model EntraIDCredentials extends BaseCredentials {
+  @doc("The credential type")
+  @visibility(Lifecycle.Read)
+  type: CredentialType.entraId;
+}
+
+@doc("Custom credential definition")
+model CustomCredential extends BaseCredentials {
+  @doc("The credential type")
+  @visibility(Lifecycle.Read)
+  type: CredentialType.custom;
+
+  @doc("The credential type")
+  @visibility(Lifecycle.Read)
+  keys: Record<string>;
+}
+
+#suppress "@azure-tools/typespec-azure-core/casing-style"
+@doc("Shared Access Signature (SAS) credential definition")
+model SASCredentials extends BaseCredentials {
+  @doc("The credential type")
+  @visibility(Lifecycle.Read)
+  type: CredentialType.SAS;
+
+  @doc("SAS token")
+  @visibility(Lifecycle.Read)
+  @encodedName("application/json", "SAS")
+  sasToken?: string;
+}
+
+@doc("Credentials that do not require authentication")
+model NoAuthenticationCredentials extends BaseCredentials {
+  @doc("The credential type ")
+  @visibility(Lifecycle.Read)
+  type: CredentialType.None;
+}
+
+// https://learn.microsoft.com/rest/api/azureml/workspace-connections/list-secrets?view=rest-azureml-2024-04-01&tabs=HTTP#ConnectionType
+@doc("The Type (or category) of the connection")
+union ConnectionType {
+  string,
+
+  @doc("Azure OpenAI Service")
+  AzureOpenAI: "AzureOpenAI", //TODO: In Python this results in .AZURE_OPEN_AI. How do I make it .AZURE_OPENAI?
+
+  @doc("Azure Blob Storage, with specified container")
+  AzureBlobStorage: "AzureBlob",
+
+  @doc("Azure Blob Storage, with container not specified (used by Agents)")
+  AzureStorageAccount: "AzureStorageAccount",
+
+  @doc("Azure AI Search")
+  AzureAISearch: "CognitiveSearch",
+
+  @doc("CosmosDB")
+  CosmosDB: "CosmosDB",
+
+  @doc("Generic connection that uses API Key authentication")
+  APIKey: "ApiKey",
+
+  @doc("Application Configuration")
+  ApplicationConfiguration: "AppConfig",
+
+  @doc("Application Insights")
+  ApplicationInsights: "AppInsights",
+
+  @doc("Custom Keys")
+  Custom: "CustomKeys",
+}
+
+@doc("The credential type used by the connection")
+union CredentialType {
+  string,
+
+  @doc("API Key credential")
+  apiKey: "ApiKey",
+
+  @doc("Entra ID credential (formerly known as AAD)")
+  entraId: "AAD",
+
+  @doc("Shared Access Signature (SAS) credential")
+  SAS: "SAS",
+
+  @doc("Custom credential")
+  custom: "CustomKeys",
+
+  @doc("No credential")
+  None: "None",
+}

specification/ai/Azure.AI.Projects/connections/routes.tsp

@@ -0,0 +1,47 @@
+import "@typespec/rest";
+import "@azure-tools/typespec-autorest";
+import "@typespec/versioning";
+import "@azure-tools/typespec-azure-core";
+import "./models.tsp";
+
+using TypeSpec.Http;
+using Azure.Core.Traits;
+using TypeSpec.Versioning;
+
+namespace Azure.AI.Projects;
+
+alias ConnectionServiceTraits = SupportsClientRequestId &
+  NoRepeatableRequests &
+  NoConditionalRequests;
+
+alias ConnectionOperations = Azure.Core.ResourceOperations<ConnectionServiceTraits>;
+
+@added(Versions.v2025_05_01)
+interface Connections {
+  @doc("Get a connection by name, without populating connection credentials")
+  get is ConnectionOperations.ResourceRead<Connection>;
+
+  @doc("Get a connection by name, with its connection credentials")
+  @TypeSpec.Http.post
+  @Rest.actionSeparator("/")
+  @Rest.action("getConnectionWithCredentials")
+  getWithCredentials is ConnectionOperations.ResourceAction<
+    Connection,
+    {},
+    Connection
+  >;
+
+  @doc("List all connections in the project, without populating connection credentials")
+  list is ConnectionOperations.ResourceList<
+    Connection,
+    ListQueryParametersTrait<{
+      @doc("List connections of this specific type")
+      @query("connectionType")
+      connectionType?: ConnectionType;
+
+      @doc("List connections that are default connections")
+      @query("defaultConnection")
+      defaultConnection?: boolean;
+    }>
+  >;
+}