diff --git a/common-features/integration-with-telerik-ai-smartcomponents-extensions.md b/common-features/integration-with-telerik-ai-smartcomponents-extensions.md new file mode 100644 index 000000000..c513d41a8 --- /dev/null +++ b/common-features/integration-with-telerik-ai-smartcomponents-extensions.md @@ -0,0 +1,307 @@ +--- +title: Integration with Telerik.AI.SmartComponents.Extensions +page_title: Integration with Telerik.AI.SmartComponents.Extensions +description: How to integrate the UI for Blazor components with Telerik.AI.SmartComponents.Extensions +slug: common-features-telerik-ai-smartcomponents-extensions-integration +tags: telerik,blazor,aiprompt,ai,extensions,integration +published: True +position: 45 +--- + +# Getting Started with Telerik.AI.SmartComponents.Extensions + +## Overview + +The `Telerik.AI.SmartComponents.Extensions` library provides AI-powered functionality for Grid operations, enabling natural language processing for filtering, sorting, grouping, and highlighting data. This library integrates seamlessly with Microsoft.Extensions.AI and Azure OpenAI to provide intelligent Grid interactions. + +## Prerequisites + +- .NET 8.0 or later +- `Microsoft.Extensions.AI` package +- Azure OpenAI or OpenAI API access +- ASP.NET Core (for web API scenarios) + +## Installation + +1. Add the [`Telerik.AI.SmartComponents.Extensions` NuGet package](https://www.nuget.org/packages/Telerik.AI.SmartComponents.Extensions) to your project. +1. Add the required dependency packages: + * `Microsoft.Extensions.AI` + * `Azure.AI.OpenAI` + +## Configuration + +### 1. Configure AI Services in Program.cs + +```csharp +using Microsoft.Extensions.AI; +using Azure.AI.OpenAI; + +var builder = WebApplication.CreateBuilder(args); + +// Configure Azure OpenAI Chat Client +builder.Services.AddSingleton(serviceProvider => +{ + var configuration = serviceProvider.GetRequiredService(); + var endpoint = configuration["AI:AzureOpenAI:Endpoint"]; + var apiKey = configuration["AI:AzureOpenAI:Key"]; + var modelId = configuration["AI:AzureOpenAI:Chat:ModelId"]; + + var client = new AzureOpenAIClient(new Uri(endpoint), new Azure.AzureKeyCredential(apiKey)); + return client.AsChatClient(modelId); +}); + +builder.Services.AddControllers(); +var app = builder.Build(); +``` + +### 2. Configure appsettings.json + +```json +{ + "AI": { + "AzureOpenAI": { + "Endpoint": "https://your-openai-resource.openai.azure.com/", + "Key": "your-api-key-here", + "Chat": { + "ModelId": "gpt-4" + } + } + } +} +``` + +## Basic Usage + +### 1. Create a Grid Controller + +```csharp +using Microsoft.AspNetCore.Mvc; +using Microsoft.Extensions.AI; +using OpenAI.Chat; +using Telerik.AI.SmartComponents.Extensions; + +[ApiController] +[Route("[controller]/[action]")] +public class GridController : Controller +{ + private readonly IChatClient _chatClient; + + public GridController(IChatClient chatClient) + { + _chatClient = chatClient; + } + + [HttpPost] + [Route("/grid/smart-state")] + public async Task SmartState([FromBody] GridAIRequest request) + { + // Create chat completion options + var options = new ChatCompletionOptions(); + + // Add Grid-specific chat tools for AI processing + ChatTools.AddGridChatTools( + request.Columns.Select(x => new GridAIColumn { + Field = x.Field, + Values = x.Values + }).ToList(), + options + ); + + // Convert request contents to chat messages + var conversationMessages = request.Contents + .Select(m => new UserChatMessage(m.Text)) + .ToList(); + + // Get the chat service and process the request + var chatService = _chatClient.GetService(); + var completion = await chatService.CompleteChatAsync(conversationMessages, options); + + // Extract Grid options from AI response + var gridOptions = completion.ToolCalls.ExtractGridOptions(); + + return Json(gridOptions); + } +} +``` + +### 2. Define Your Data Model + +```csharp +public class Employee +{ + public string FirstName { get; set; } + public string LastName { get; set; } + public int Age { get; set; } + public string Department { get; set; } + public decimal Salary { get; set; } + public string City { get; set; } + public string Gender { get; set; } +} +``` + +### 3. Create Grid AI Request + +```csharp +var request = new GridAIRequest +{ + Columns = new List + { + new() { Field = "FirstName" }, + new() { Field = "LastName" }, + new() { Field = "Age" }, + new() { Field = "Department", Values = new[] { "IT", "HR", "Finance", "Marketing" } }, + new() { Field = "Salary" }, + new() { Field = "City", Values = new[] { "New York", "London", "Paris", "Tokyo" } }, + new() { Field = "Gender", Values = new[] { "Male", "Female" } } + }, + Contents = new List + { + new() { Type = "text", Text = "Show me all employees in IT department" } + } +}; +``` + +## Advanced Features + +### 1. Filtering Operations + +The library supports various natural language filtering queries: + +```csharp +// Example queries that work with the AI: +"Show me employees older than 30" +"Filter people in IT department" +"Get employees whose name starts with J" +"Show me men with salary greater than 60000" +``` + +### 2. Sorting Operations + +```csharp +// Natural language sorting examples: +"Sort by age descending" +"Order by salary ascending" +"Sort by department, then by name" +``` + +### 3. Grouping Operations + +```csharp +// Grouping examples: +"Group by department" +"Group by city, then by age" +"Group employees by gender descending" +``` + +### 4. Highlighting Operations + +```csharp +// Highlighting examples: +"Highlight employees whose name starts with A" +"Mark salary cells of people older than 30" +"Highlight lastname cells of IT employees" +``` + +## Working with Grid Responses + +The AI service returns a `GridAIResponse` object containing the processed operations: + +```csharp +public async Task ProcessGridRequest(GridAIRequest request) +{ + var options = new ChatCompletionOptions(); + ChatTools.AddGridChatTools(request.Columns, options); + + var messages = request.Contents.Select(m => new UserChatMessage(m.Text)).ToList(); + var completion = await _chatClient.CompleteChatAsync(messages, options); + + var response = completion.ToolCalls.ExtractGridOptions(); + + // The response contains: + // - response.Filter: Composite filter conditions + // - response.Sort: Array of sort descriptors + // - response.Group: Array of group descriptors + // - response.Highlight: Array of highlight descriptors + // - response.Messages: Status/info messages + + return response; +} +``` + +## Filter Types + +The library supports various filter operators: + +- `equalto`: Exact match +- `contains`: Contains substring +- `startswith`: Starts with text +- `endswith`: Ends with text +- `greaterthan`: Greater than (numeric) +- `lessthan`: Less than (numeric) +- `greaterthanorequal`: Greater than or equal +- `lessthanorequal`: Less than or equal + +## Best Practices + +### 1. Column Configuration + +When the options for the column are of Enum type provide meaningful column values to help the AI understand your data: + +```csharp +new GridAIColumn +{ + Field = "Status", + // only when only a set of values are used + Values = new[] { "Active", "Inactive", "Pending" } +} +``` + +### 2. Error Handling + +```csharp +try +{ + var completion = await chatService.CompleteChatAsync(messages, options); + var response = completion.ToolCalls.ExtractGridOptions(); + return Json(response); +} +catch (Exception ex) +{ + return StatusCode(500, $"AI processing failed: {ex.Message}"); +} +``` + +### 3. Input Validation + +```csharp +if (request?.Columns == null || !request.Columns.Any()) +{ + return BadRequest("Columns are required"); +} + +if (request.Contents == null || !request.Contents.Any()) +{ + return BadRequest("Content is required"); +} +``` + +## Testing + +The library includes comprehensive test coverage. You can run tests to verify functionality: + +```bash +cd tests +dotnet test +``` + +For integration testing with your specific data model, create test cases that verify AI responses match expected Grid operations. + +## Troubleshooting + +### Common Issues + +* Invalid URI Format: Ensure your Azure OpenAI endpoint is correctly formatted in configuration. +* API Key Issues: Verify your API key has proper permissions and is not expired. +* Model Availability: Ensure the specified model ID is deployed in your Azure OpenAI resource. +* Token Limits: Be mindful of token limits when processing large datasets. + diff --git a/components/grid/smart-ai-features/ai-column-assistant.md b/components/grid/smart-ai-features/ai-column-assistant.md new file mode 100644 index 000000000..52b0c60c4 --- /dev/null +++ b/components/grid/smart-ai-features/ai-column-assistant.md @@ -0,0 +1,139 @@ +--- +title: AI Column Assistant +page_title: Grid - AI Column Assistant +description: Learn how to use the Telerik Grid for Blazor together with an InlineAIPrompt component to generate AI content and update the Grid data items. +slug: grid-ai-column +tags: telerik,blazor,grid,ai +published: True +position: 30 +--- + +# Grid AI Column Assistant + +The Grid AI Column Assistant is an integration between the Telerik Inline AI Prompt and Grid components. This article shows how to display an Inline AI Prompt from a Grid column template to allow users to use AI for a specific Grid data item. Depending on the business requirements, the AI model can analyze the Grid data item and suggest additions or modifications. + +The suggested algorithm for implementation is the following: + +1. [Configure an InlineAIPrompt component that receives and provides the user prompt](#define-inlineaiprompt-component). +1. [Add a Grid column with a button that displays the InlineAIPrompt component](#add-grid-column-with-button). +1. (optional) [Implement an additional property of the Grid model class for AI content](#add-grid-column-for-ai-content). +1. [Update the Grid data or perform another action, based on the AI response](#update-grid-data). + +## Define InlineAIPrompt Component + +Follow the [InlineAIPrompt component documentation](slug:inlineaiprompt-overview) to configure an Inline AI Prompt component. Users can type an arbitrary prompt or optionally, pick from a predefined list of suggestions. + +````RAZOR.skip-repl + + +@code { + private TelerikInlineAIPrompt? InlineAIPromptRef { get; set; } + + private string UserPrompt { get; set; } = string.Empty; + + // List optional predefined prompt suggestions. + private List PredefinedPromptSuggestions { get; set; } = new(); + + // Define possible actions over the AI response. + private List ActionsOverAIResponse { get; set; } = new(); + + private void OnPredefinedPromptSuggestionSelect(InlineAIPromptCommandExecuteEventArgs args) + { + // This handler executes when the user selects a predefined prompt. + + Prompt = args.Command.Prompt; + } + + private async Task SendAIRequestAndGetResponse(InlineAIPromptPromptRequestEventArgs args) + { + // This handler executes when the user submits their AI prompt. + // Set the AI service response to args.Output. + + args.Output = "The AI response to the user prompt."; + } + + private async Task OnAIResponseActionClick(InlineAIPromptOutputActionClickEventArgs args) + { + // This handler executes when the user clicks on an action from ActionsOverAIResponse. + // You can modify the Grid data source here. + } +} +```` + +## Add Grid Column with Button + +Add a Grid column with no `Field`. The column must have a `