Add AzureComputerVisionService (#261)

## Purpose
This PR adds AzureComputerVisionService, which will be used to create
image embedding and generate image embedding from text query.


## Does this introduce a breaking change?
<!-- Mark one with an "x". -->
```
[ ] Yes
[x] No
```

## Pull Request Type
What kind of change does this Pull Request introduce?

#257 
<!-- Please check the one that applies to this PR using "x". -->
```
[ ] Bugfix
[x] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Documentation content changes
[ ] Other... Please describe:
```

## How to Test
*  Get the code

```
git clone [repo-address]
cd [repo-name]
git checkout [branch-name]
npm install
```

* Test the code
<!-- Add steps to run the tests suite and/or manually test -->
```
```

## What to Check
Verify that the following are valid
* ...

## Other Information
<!-- Add any other helpful information that may be needed here. -->

---------

Co-authored-by: David Pine <[email protected]>

Author: LittleLittleCloud

app/Directory.Packages.props

@@ -43,5 +43,7 @@
     <PackageVersion Include="System.Linq.Async" Version="6.0.1" />
     <PackageVersion Include="xunit.runner.visualstudio" Version="2.5.4" />
     <PackageVersion Include="xunit" Version="2.6.2" />
+    <PackageVersion Include="FluentAssertions" Version="6.8.0" />
+    <PackageVersion Include="NSubstitute" Version="5.1.0" />
   </ItemGroup>
 </Project>

app/app.sln

@@ -27,6 +27,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "PrepareDocs", "prepdocs\Pre
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "EmbedFunctions", "functions\EmbedFunctions\EmbedFunctions.csproj", "{54099AF3-CFA8-4EA9-9118-A26E3E63745B}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "MinimalApi.Tests", "tests\MinimalApi.Tests\MinimalApi.Tests.csproj", "{C687997A-A569-47AA-A808-504F7DFCA97B}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -57,6 +59,10 @@ Global
 		{54099AF3-CFA8-4EA9-9118-A26E3E63745B}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{54099AF3-CFA8-4EA9-9118-A26E3E63745B}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{54099AF3-CFA8-4EA9-9118-A26E3E63745B}.Release|Any CPU.Build.0 = Release|Any CPU
+		{C687997A-A569-47AA-A808-504F7DFCA97B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C687997A-A569-47AA-A808-504F7DFCA97B}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C687997A-A569-47AA-A808-504F7DFCA97B}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C687997A-A569-47AA-A808-504F7DFCA97B}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

app/backend/Program.cs

@@ -15,6 +15,7 @@
 builder.Services.AddCrossOriginResourceSharing();
 builder.Services.AddAzureServices();
 builder.Services.AddAntiforgery(options => { options.HeaderName = "X-CSRF-TOKEN-HEADER"; options.FormFieldName = "X-CSRF-TOKEN-FORM"; });
+builder.Services.AddHttpClient();
 
 if (builder.Environment.IsDevelopment())
 {

app/backend/Services/AzureComputerVisionService.cs

@@ -0,0 +1,92 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Net.Http.Headers;
+using System.Text;
+
+namespace MinimalApi.Services;
+
+public class AzureComputerVisionService(IHttpClientFactory httpClientFactory, string endPoint, string apiKey)
+{
+    // add virtual keyword to make it mockable
+    public virtual async Task<ImageEmbeddingResponse> VectorizeImageAsync(string imagePathOrUrl, CancellationToken ct = default)
+    {
+        var api = $"{endPoint}/computervision/retrieval:vectorizeImage?api-version=2023-02-01-preview&modelVersion=latest";
+        // first try to read as local file
+        if (File.Exists(imagePathOrUrl))
+        {
+            using var request = new HttpRequestMessage(HttpMethod.Post, api);
+
+            // set authorization header
+            request.Headers.Add("Ocp-Apim-Subscription-Key", apiKey);
+
+            // set body
+            var bytes = await File.ReadAllBytesAsync(imagePathOrUrl, ct);
+            request.Content = new ByteArrayContent(bytes);
+            request.Content.Headers.ContentType = new MediaTypeHeaderValue("image/*");
+
+            // send request
+            using var client = httpClientFactory.CreateClient();
+            using var response = await client.SendAsync(request, ct);
+            response.EnsureSuccessStatusCode();
+
+            // read response
+            var json = await response.Content.ReadAsStringAsync();
+            var result = JsonSerializer.Deserialize<ImageEmbeddingResponse>(json);
+
+            return result ?? throw new InvalidOperationException("Failed to deserialize response");
+        }
+        else
+        {
+            // retrieve as url
+            using var request = new HttpRequestMessage(HttpMethod.Post, api);
+
+            // set content type to application/json
+            request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
+
+            // set authorization header
+            request.Headers.Add("Ocp-Apim-Subscription-Key", apiKey);
+
+            // set body
+            var body = new { url = imagePathOrUrl };
+            request.Content = new StringContent(JsonSerializer.Serialize(body), Encoding.UTF8, "application/json");
+
+            // send request
+            using var client = httpClientFactory.CreateClient();
+            using var response = await client.SendAsync(request, ct);
+            response.EnsureSuccessStatusCode();
+
+            // read response
+            var json = await response.Content.ReadAsStringAsync();
+            var result = JsonSerializer.Deserialize<ImageEmbeddingResponse>(json);
+
+            return result ?? throw new InvalidOperationException("Failed to deserialize response");
+        }
+    }
+
+    public virtual async Task<ImageEmbeddingResponse> VectorizeTextAsync(string text, CancellationToken ct = default)
+    {
+        var api = $"{endPoint}/computervision/retrieval:vectorizeText?api-version=2023-02-01-preview&modelVersion=latest";
+
+        using var request = new HttpRequestMessage(HttpMethod.Post, api);
+
+        // set content type to application/json
+        request.Headers.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
+
+        // set authorization header
+        request.Headers.Add("Ocp-Apim-Subscription-Key", apiKey);
+
+        // set body
+        var body = new { text };
+        request.Content = new StringContent(JsonSerializer.Serialize(body), Encoding.UTF8, "application/json");
+
+        // send request
+        using var client = new HttpClient();
+        using var response = await client.SendAsync(request, ct);
+        response.EnsureSuccessStatusCode();
+
+        // read response
+        var json = await response.Content.ReadAsStringAsync();
+        var result = JsonSerializer.Deserialize<ImageEmbeddingResponse>(json);
+        return result ?? throw new InvalidOperationException("Failed to deserialize response");
+    }
+}

app/shared/Shared/Models/ImageEmbeddingResponse.cs

@@ -0,0 +1,2 @@
+// Copyright (c) Microsoft. All rights reserved.
+public record ImageEmbeddingResponse(string modelVersion, float[] vector);

app/tests/MinimalApi.Tests/Attribute/EnvironmentSpecificFactAttribute.cs

@@ -0,0 +1,46 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Xunit;
+
+/// <summary>
+/// A base class for environment-specific fact attributes.
+/// </summary>
+[AttributeUsage(AttributeTargets.Method, AllowMultiple = false, Inherited = true)]
+public abstract class EnvironmentSpecificFactAttribute : FactAttribute
+{
+    private readonly string _skipMessage;
+
+    /// <summary>
+    /// Creates a new instance of the <see cref="EnvironmentSpecificFactAttribute" /> class.
+    /// </summary>
+    /// <param name="skipMessage">The message to be used when skipping the test marked with this attribute.</param>
+    protected EnvironmentSpecificFactAttribute(string skipMessage)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(skipMessage);
+        
+        _skipMessage = skipMessage;
+    }
+
+    public sealed override string Skip => IsEnvironmentSupported() ? null! : _skipMessage;
+
+    /// <summary>
+    /// A method used to evaluate whether to skip a test marked with this attribute. Skips iff this method evaluates to false.
+    /// </summary>
+    protected abstract bool IsEnvironmentSupported();
+}
+
+public sealed class ApiKeyFactAttribute : EnvironmentSpecificFactAttribute
+{
+    private readonly string[] _envVariableNames;
+    
+    public ApiKeyFactAttribute(params string[] envVariableNames) : base($"{string.Join(", ", envVariableNames)} is not found in env")
+    {
+        _envVariableNames = envVariableNames;
+    }
+
+    /// <inheritdoc />
+    protected override bool IsEnvironmentSupported()
+    {
+        return _envVariableNames.Any(Environment.GetEnvironmentVariables().Contains);
+    }
+}

app/tests/MinimalApi.Tests/AzureComputerVisionServiceTest.cs

@@ -0,0 +1,62 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using FluentAssertions;
+using MinimalApi.Services;
+using NSubstitute;
+
+namespace MinimalApi.Tests;
+
+public class AzureComputerVisionServiceTest
+{
+    [ApiKeyFact("AZURE_COMPUTER_VISION_API_KEY", "AZURE_COMPUTER_VISION_ENDPOINT")]
+    public async Task VectorizeImageTestAsync()
+    {
+        var endpoint = Environment.GetEnvironmentVariable("AZURE_COMPUTER_VISION_ENDPOINT") ?? throw new InvalidOperationException();
+        var apiKey = Environment.GetEnvironmentVariable("AZURE_COMPUTER_VISION_API_KEY") ?? throw new InvalidOperationException();
+        var httpClientFactory = Substitute.For<IHttpClientFactory>();
+        httpClientFactory.CreateClient().ReturnsForAnyArgs(x => new HttpClient());
+        var service = new AzureComputerVisionService(httpClientFactory, endpoint, apiKey);
+        var imageUrl = @"https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png";
+
+        var result = await service.VectorizeImageAsync(imageUrl);
+
+        result.modelVersion.Should().NotBeNullOrEmpty();
+
+        // download image to local file, and verify the api on local image.
+        var tempFile = Path.GetTempFileName();
+        tempFile = Path.ChangeExtension(tempFile, ".png");
+        try
+        {
+            using var client = new HttpClient();
+            using var stream = await client.GetStreamAsync(imageUrl);
+            using var fileStream = File.OpenWrite(tempFile);
+            await stream.CopyToAsync(fileStream);
+            fileStream.Flush();
+            fileStream.Close();
+
+            var localResult = await service.VectorizeImageAsync(tempFile);
+
+            localResult.modelVersion.Should().NotBeNullOrEmpty();
+            localResult.vector.Should().BeEquivalentTo(result.vector);
+        }
+        finally
+        {
+            File.Delete(tempFile);
+        }
+    }
+
+    [ApiKeyFact("AZURE_COMPUTER_VISION_API_KEY", "AZURE_COMPUTER_VISION_ENDPOINT")]
+    public async Task VectorizeTextTestAsync()
+    {
+        var endpoint = Environment.GetEnvironmentVariable("AZURE_COMPUTER_VISION_ENDPOINT") ?? throw new InvalidOperationException();
+        var apiKey = Environment.GetEnvironmentVariable("AZURE_COMPUTER_VISION_API_KEY") ?? throw new InvalidOperationException();
+        var httpClientFactory = Substitute.For<IHttpClientFactory>();
+        httpClientFactory.CreateClient().ReturnsForAnyArgs(x => new HttpClient());
+        var service = new AzureComputerVisionService(httpClientFactory, endpoint, apiKey);
+        var text = "Hello world";
+        var result = await service.VectorizeTextAsync(text);
+
+        result.modelVersion.Should().NotBeNullOrEmpty();
+        result.vector.Length.Should().Be(1024);
+    }
+}

app/tests/MinimalApi.Tests/GlobalUsings.cs

@@ -0,0 +1,2 @@
+// Copyright (c) Microsoft. All rights reserved.
+

app/tests/MinimalApi.Tests/MinimalApi.Tests.csproj

@@ -0,0 +1,30 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+    <LangVersion>preview</LangVersion>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.NET.Test.Sdk" />
+    <PackageReference Include="xunit" />
+    <PackageReference Include="xunit.runner.visualstudio">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <PackageReference Include="coverlet.collector">
+      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+      <PrivateAssets>all</PrivateAssets>
+    </PackageReference>
+    <PackageReference Include="FluentAssertions" />
+    <PackageReference Include="NSubstitute" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\backend\MinimalApi.csproj" />
+  </ItemGroup>
+
+</Project>