Merge pull request #45383 from dotnet/main

Merge main into live

Author: dotnet-policy-service[bot]

README.md

@@ -11,10 +11,25 @@
 
 This repository contains the conceptual documentation for .NET. The [.NET documentation site](https://learn.microsoft.com/dotnet) is built from multiple repositories in addition to this one:
 
+- [ASP.NET Core](https://github.com/dotnet/AspNetCore.Docs)
 - [.NET Aspire](https://github.com/dotnet/docs-aspire)
 - [.NET Desktop workloads](https://github.com/dotnet/docs-desktop)
-- [API reference](https://github.com/dotnet/dotnet-api-docs)
-- [C# Language design](https://github.com/dotnet/csharplang)
+- [.NET MAUI](https://github.com/dotnet/docs-maui)
+- [Entity Framework 6/Core](https://github.com/dotnet/EntityFramework.Docs)
+- [Community toolkit](https://github.com/MicrosoftDocs/communitytoolkit)
+
+API reference documentation is published from the following repositories. The following reference API repositories are public. Only some accept issues and pull requests, although some folders in `dotnet-api-docs` use the product repository as the source of truth. Others are pass-through repositories because API reference is generated directly from the `///` in the product source. 
+
+- [.NET API reference](https://github.com/dotnet/dotnet-api-docs)
+- [.NET MAUI API reference](https://github.com/dotnet/maui-api-docs)
+- [Android API reference](https://github.com/dotnet/android-api-docs)
+- [Entity Framework 6/Core API reference](https://github.com/dotnet/EntityFramework.ApiDocs)
+- [Roslyn API reference](https://github.com/dotnet/roslyn-api-docs)
+- [Community toolkit API reference](https://github.com/MicrosoftDocs/community-toolkit-api-ref-dotnet)
+
+The C# language specification documentation comes from the following two repositories:
+
+- [C# language design](https://github.com/dotnet/csharplang)
 - [C# specification - draft](https://github.com/dotnet/csharpstandard)
 
 Our team's tasks are tracked in our [project boards](https://github.com/dotnet/docs/projects?query=is%3Aopen). You'll see monthly sprint projects, along with long-running projects for major documentation updates. The projects contain documentation issues across the repositories that build .NET docs. Issues are tracked in the relevant repositories. We have a large community using these resources. We make our best effort to respond to issues in a timely fashion. To create a new issue, click the "Open a documentation issue" button at the bottom of any of our published docs, or [choose one of the available templates](https://github.com/dotnet/docs/issues/new/choose). The control at the bottom of each article automatically routes you to the correct repo and fills in some relevant information based on the article.

docs/ai/index.yml

@@ -79,6 +79,8 @@ landingContent:
             url: get-started-app-chat-template.md
           - text: Implement RAG using vector search
             url: tutorials/tutorial-ai-vector-search.md
+          - text: Evaluate a model's response
+            url: tutorials/evaluate-with-reporting.md
 
   # Card (Optional; Remove if not applicable.)
   - title: Training

docs/ai/quickstarts/build-vector-search-app.md

@@ -46,12 +46,12 @@ The abstractions in `Microsoft.Extensions.VectorData.Abstractions` provide libra
 
 ## Create the app
 
-Complete the following steps to create a .NET console app that can accomplish the following:
+Complete the following steps to create a .NET console app that can:
 
 - Create and populate a vector store by generating embeddings for a data set
 - Generate an embedding for the user prompt
 - Query the vector store using the user prompt embedding
-- Displays the relevant results from the vector search
+- Display the relevant results from the vector search
 
 1. In an empty directory on your computer, use the `dotnet new` command to create a new console app:
 
@@ -85,7 +85,7 @@ Complete the following steps to create a .NET console app that can accomplish th
     - [`Azure.AI.OpenAI`](https://www.nuget.org/packages/Azure.AI.OpenAI) is the official package for using OpenAI's .NET library with the Azure OpenAI Service.
     - [`Microsoft.SemanticKernel.Connectors.InMemory`](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.InMemory) provides an in-memory vector store class to hold queryable vector data records.
     - [`Microsoft.Extensions.VectorData.Abstractions`](https://www.nuget.org/packages/Microsoft.Extensions.AI) enables Create-Read-Update-Delete (CRUD) and search operations on vector stores.
-    - [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration) provides implementation of key-value pair based configuration.
+    - [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration) provides an implementation of key-value pair—based configuration.
     - [`Microsoft.Extensions.Configuration.UserSecrets`](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.UserSecrets) is a user secrets configuration provider implementation for `Microsoft.Extensions.Configuration`.
 
     :::zone-end
@@ -105,7 +105,7 @@ Complete the following steps to create a .NET console app that can accomplish th
     - [`Microsoft.Extensions.AI.OpenAI`](https://www.nuget.org/packages/Microsoft.Extensions.AI.OpenAI) provides AI abstractions for OpenAI-compatible models or endpoints. This library also includes the official [`OpenAI`](https://www.nuget.org/packages/OpenAI) library for the OpenAI service API as a dependency.
     - [`Microsoft.SemanticKernel.Connectors.InMemory`](https://www.nuget.org/packages/Microsoft.SemanticKernel.Connectors.InMemory) provides an in-memory vector store class to hold queryable vector data records.
     - [`Microsoft.Extensions.VectorData.Abstractions`](https://www.nuget.org/packages/Microsoft.Extensions.AI) enables Create-Read-Update-Delete (CRUD) and search operations on vector stores.
-    - [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration) provides implementation of key-value pair based configuration.
+    - [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration) provides an implementation of key-value pair—based configuration.
     - [`Microsoft.Extensions.Configuration.UserSecrets`](https://www.nuget.org/packages/Microsoft.Extensions.Configuration.UserSecrets) is a user secrets configuration provider implementation for `Microsoft.Extensions.Configuration`.
 
     :::zone-end

docs/ai/quickstarts/create-assistant.md

@@ -39,14 +39,14 @@ In this quickstart, you'll learn how to create a minimal AI assistant using the
 
 ## Core components of AI assistants
 
-AI assistants are based around conversational threads with a user. The user sends prompts to the assistant on a conversation thread, which directs the assistant to complete tasks using the tools it has available. Assistants can process and analyze data, make decisions, and interact with users or other systems to achieve specific goals. Most assistants include the following components:
+AI assistants are based around conversational threads with a user. The user sends prompts to the assistant on a conversation thread, which direct the assistant to complete tasks using the tools it has available. Assistants can process and analyze data, make decisions, and interact with users or other systems to achieve specific goals. Most assistants include the following components:
 
 | **Component** | **Description** |
-|---|---|
+|---------------|-----------------|
 | **Assistant** | The core AI client and logic that uses Azure OpenAI models, manages conversation threads, and utilizes configured tools. |
-| **Thread** | A conversation session between an assistant and a user. Threads store messages and automatically handle truncation to fit content into a model's context. |
-| **Message** | A message created by an assistant or a user. Messages can include text, images, and other files. Messages are stored as a list on the thread. |
-| **Run** | Activation of an assistant to begin running based on the contents of the thread. The assistant uses its configuration and the thread's messages to perform tasks by calling models and tools. As part of a run, the assistant appends messages to the thread. |
+| **Thread**    | A conversation session between an assistant and a user. Threads store messages and automatically handle truncation to fit content into a model's context. |
+| **Message**   | A message created by an assistant or a user. Messages can include text, images, and other files. Messages are stored as a list on the thread. |
+| **Run**       | Activation of an assistant to begin running based on the contents of the thread. The assistant uses its configuration and the thread's messages to perform tasks by calling models and tools. As part of a run, the assistant appends messages to the thread. |
 | **Run steps** | A detailed list of steps the assistant took as part of a run. An assistant can call tools or create messages during its run. Examining run steps allows you to understand how the assistant is getting to its final results. |
 
 Assistants can also be configured to use multiple tools in parallel to complete tasks, including the following:

docs/ai/quickstarts/evaluate-ai-response.md

@@ -10,6 +10,9 @@ ms.custom: devx-track-dotnet, devx-track-dotnet-ai
 
 In this quickstart, you create an MSTest app to evaluate the chat response of a model. The test app uses the [Microsoft.Extensions.AI.Evaluation](https://www.nuget.org/packages/Microsoft.Extensions.AI.Evaluation) libraries.
 
+> [!NOTE]
+> This quickstart demonstrates the simplest usage of the evaluation API. Notably, it doesn't demonstrate use of the [response caching](../conceptual/evaluation-libraries.md#cached-responses) and [reporting](../conceptual/evaluation-libraries.md#reporting) functionality, which are important if you're authoring unit tests that run as part of an "offline" evaluation pipeline. The scenario shown in this quickstart is suitable in use cases such as "online" evaluation of AI responses within production code and logging scores to telemetry, where caching and reporting aren't relevant. For a tutorial that demonstrates the caching and reporting functionality, see [Tutorial: Evaluate a model's response with response caching and reporting](../tutorials/evaluate-with-reporting.md)
+
 ## Prerequisites
 
 - [Install .NET 8.0](https://dotnet.microsoft.com/download) or a later version
@@ -86,7 +89,7 @@ Complete the following steps to create an MSTest project that connects to your l
 
    :::code language="csharp" source="./snippets/evaluate-ai-responses/MyTests.cs" id="Initialize":::
 
-    This methods accomplishes the following tasks:
+    This method accomplishes the following tasks:
 
    - Sets up the <xref:Microsoft.Extensions.AI.Evaluation.ChatConfiguration>.
    - Sets the <xref:Microsoft.Extensions.AI.ChatOptions>, including the <xref:Microsoft.Extensions.AI.ChatOptions.Temperature> and the <xref:Microsoft.Extensions.AI.ChatOptions.ResponseFormat>.

docs/ai/quickstarts/use-function-calling.md

@@ -107,7 +107,7 @@ Complete the following steps to create a .NET console app to connect to an AI mo
 
 The app uses the [`Microsoft.Extensions.AI`](https://www.nuget.org/packages/Microsoft.Extensions.AI/) package to send and receive requests to the AI model.
 
-1. In the **Program.cs** file, add the following code to connect and authenticate to the AI model. The `ChatClient` is also configured to use function invocation, which allows .NET functions in your code to be called by the AI model.
+1. In the **Program.cs** file, add the following code to connect and authenticate to the AI model. The `ChatClient` is also configured to use function invocation, which allows the AI model to call .NET functions in your code.
 
     :::zone target="docs" pivot="azure-openai"
 
@@ -124,7 +124,7 @@ The app uses the [`Microsoft.Extensions.AI`](https://www.nuget.org/packages/Micr
 
     :::zone-end
 
-1. Create a new `ChatOptions` object that contains an inline function the AI model can call to get the current weather. The function declaration includes a delegate to run logic and name and description parameters to describe the purpose of the function to the AI model.
+1. Create a new `ChatOptions` object that contains an inline function the AI model can call to get the current weather. The function declaration includes a delegate to run logic, and name and description parameters to describe the purpose of the function to the AI model.
 
     :::code language="csharp" source="snippets/function-calling/openai/program.cs" range="16-26":::
 
@@ -138,7 +138,7 @@ The app uses the [`Microsoft.Extensions.AI`](https://www.nuget.org/packages/Micr
     dotnet run
     ```
 
-    The app prints the completion response from the AI model that includes data provided by the .NET function. The AI model understood the registered function was available and called it automatically to generate a proper response.
+    The app prints the completion response from the AI model, which includes data provided by the .NET function. The AI model understood that the registered function was available and called it automatically to generate a proper response.
 
 :::zone target="docs" pivot="azure-openai"
 

docs/ai/toc.yml

@@ -79,6 +79,8 @@ items:
     href: conceptual/evaluation-libraries.md
   - name: "Quickstart: Evaluate a model's response"
     href: quickstarts/evaluate-ai-response.md
+  - name: "Tutorial: Evaluate a response with response caching and reporting"
+    href: tutorials/evaluate-with-reporting.md
   - name: "Tutorial: Evaluate LLM prompt completions"
     href: tutorials/llm-eval.md
 - name: Resources