{"id":25058317,"url":"https://github.com/glav/cognitiveservicesfluentapi","last_synced_at":"2025-04-14T12:41:20.299Z","repository":{"id":29291024,"uuid":"83289010","full_name":"glav/CognitiveServicesFluentApi","owner":"glav","description":"A fluent API to use with Microsoft Cortana suite of cognitive services","archived":false,"fork":false,"pushed_at":"2022-12-07T20:04:34.000Z","size":4952,"stargazers_count":4,"open_issues_count":11,"forks_count":0,"subscribers_count":2,"default_branch":"trunk","last_synced_at":"2025-03-28T01:51:05.336Z","etag":null,"topics":["cognitive-services","fluent-api","netcore","netstandard"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/glav.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-27T08:54:10.000Z","updated_at":"2024-04-18T04:18:44.000Z","dependencies_parsed_at":"2023-01-14T14:36:34.329Z","dependency_job_id":null,"html_url":"https://github.com/glav/CognitiveServicesFluentApi","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glav%2FCognitiveServicesFluentApi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glav%2FCognitiveServicesFluentApi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glav%2FCognitiveServicesFluentApi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glav%2FCognitiveServicesFluentApi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/glav","download_url":"https://codeload.github.com/glav/CognitiveServicesFluentApi/tar.gz/refs/heads/trunk","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248883056,"owners_count":21177146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cognitive-services","fluent-api","netcore","netstandard"],"created_at":"2025-02-06T14:25:03.740Z","updated_at":"2025-04-14T12:41:20.265Z","avatar_url":"https://github.com/glav.png","language":"C#","readme":"# CognitiveServicesFluentApi\nA fluent API to use with the Microsoft Cortana suite of cognitive services. Currently this API supports the following Cognitive Services API's:\n* TextAnalytics\n* ComputerVision\n* Face\n* LUIS\n\nThe objective is to make the set of Cognitive service API's really easy to consume from .Net applications. In addition, a set of helper extension methods are available to try and make common functionality super easy to access.\n\nIf you are new to this project, please see the getting started section below. For those wanting detailed documentation, here you go:\n* [Common/Core Fluent API](./Wiki/Common.md)\n* [TextAnalytics Fluent API](./Wiki/TextAnalytics.md)\n* [ComputerVision Fluent API](./Wiki/ComputerVision.md)\n* [Face Fluent API](./Wiki/Face.md)\n* [LUIS Fluent API](./Wiki/Luis.md)\n* [Scoring system](./Wiki/Scoring.md)\n\n#### Build Status\n[![Github - Glav.CognitiveServices CI](https://github.com/glav/CognitiveServicesFluentApi/actions/workflows/ci-build.yml/badge.svg)](https://github.com/glav/CognitiveServicesFluentApi/actions/workflows/ci-build.yml)\n\n#### Sonarqube Code Analaysis\n[Sonarqube Code Analysis report](https://sonarcloud.io/dashboard?id=CognitiveFluentApi)\n\n#### LGTM Analysis\n[![Total alerts](https://img.shields.io/lgtm/alerts/g/glav/CognitiveServicesFluentApi.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/glav/CognitiveServicesFluentApi/alerts/)\n\n## How to get started.\nEasiest way is to install the nuget package for your specific analysis functionality. \nNote that the fluent API for each cognitive service has a set of convenience or extension methods which is located in a separate package for ease of updates. \nIt is recommended (at least initially) to install the 'Extensions' package as that includes the dependent fluent API package and provides extra convenience. More\ndetails on those extension/convenience methods is provided within the specific fluent API documentation.\n\n#### For text analyitics (such as Sentiment analysis):\n\n```powershell\nInstall-Package Glav.CognitiveServices.FluentApi.TextAnalytic.Extensions # Fluent API with included extension/convenience methods\n# -or-\nInstall-Package Glav.CognitiveServices.FluentApi.TextAnalytic  # Just the Fluent API\n```\nor using dotnet CLI\n```\ndotnet add package Glav.CognitiveServices.FluentApi.TextAnalytic.Extensions\n```\n\n#### For ComputerVision (such as image description or adult content detection in images)\n```powershell\nInstall-Package Glav.CognitiveServices.FluentApi.ComputerVision.Extensions # Fluent API with included extension/convenience methods\n# -or-\nInstall-Package Glav.CognitiveServices.FluentApi.ComputerVision # Just the Fluent API\n```\nor using dotnet CLI\n```\ndotnet add package Glav.CognitiveServices.FluentApi.ComputerVision.Extensions\n```\n\n#### For Face\n```powershell\nInstall-Package Glav.CognitiveServices.FluentApi.Face.Extensions # Fluent API with included extension/convenience methods\n# -or-\nInstall-Package Glav.CognitiveServices.FluentApi.Face # Just the Fluent API\n```\nor using dotnet CLI\n```\ndotnet add package Glav.CognitiveServices.FluentApi.Face.Extensions\n```\n\n#### For LUIS\n```powershell\nInstall-Package Glav.CognitiveServices.FluentApi.Luis.Extensions # Fluent API with included extension/convenience methods\n# -or-\nInstall-Package Glav.CognitiveServices.FluentApi.Luis # Just the Fluent API\n```\nor using dotnet CLI\n```\ndotnet add package Glav.CognitiveServices.FluentApi.Luis.Extensions\n```\n\n\n#### Azure Cognitive Services Setup\nIn order to make use of Cognitive services, you need to have an instance of the cognitive service setup in your Azure subscription. [This link](https://docs.microsoft.com/en-us/azure/cognitive-services/cognitive-services-apis-create-account) shows you how to do this. You will then have two crucial pieces of information:\n1. An API Key\n2. A Location where your service is hosted.\n\nYou will need these to supply to the fluent API to allow it to call the correct service.\n\n#### Start coding\n\nCreate a new console project (or any type, but console is easiest to start).\nDepending on what cognitive service you are using, add the following using statement:\n``` c#\n// For TextAnalytics API\nusing Glav.CognitiveServices.FluentApi.TextAnalytic;\n\n// For Face API\nusing Glav.CognitiveServices.FluentApi.Face;\n\n// For ComputerVision API\nusing Glav.CognitiveServices.FluentApi.ComputerVision;\n\n```\n\nAlso add in these common using statements regardless of what service you are using:\n``` c#\nusing Glav.CognitiveServices.FluentApi.Core.Configuration;\nusing Glav.CognitiveServices.FluentApi.Core;\n```\nNow we can begin by creating a configuration setting for a particular cognitive service using the API key and location of our service we created in Azure. Let's start with TextAnalytics:\n``` c#\nvar result = await TextAnalyticConfigurationSettings.CreateUsingApiKey(\"YOUR-API-KEY\", LocationKeyIdentifier.WestUs)\n```\nWhere:\n* '**YOUR-API-KEY**': String API key obtained from the Azure portal for your instance of the cognitive service to be used.\n* '**LocationKeyIdentifier**': The enumeration of type `Glav.CognitiveServices.FluentApi.Core.LocationKeyIdentifier` which specifies the location in which your cognitive service was provisioned. This is important as it dictates how the Url is formed when communicating with the service.\n\nWe can now continue to configure how the core components should work with the cognitive service API. We can typically specify what logging to use and the type of communication. \n\n```c#\nvar result = await TextAnalyticConfigurationSettings.CreateUsingApiKey(\"YOUR-API-KEY\", LocationKeyIdentifier.WestUs)\n    .SetDiagnosticLoggingLevel(LoggingLevel.Everything)\n    .AddDebugDiagnosticLogging()  // Using System.Diagnostics.Debug\n    .UsingHttpCommunication()\n```\nNow we can start to define what actions to take. For TextAnalytics, this takes the form of the extension method:\n``` c#\n.WithTextAnalyticAnalysisActions()\n```\n\nNow we can add in our actions to perform with the associated data. To add in sentiment analysis for some text:\n``` c#\n.AddSentimentAnalysis(\"This is great.\")\n```\nFor Keyphrase analysis:\n``` c#\n.AddKeyPhraseAnalysis(\"This is a snippet of text\")\n```\nFor Language analysis:\n``` c#\n.AddLanguageAnalysis(\"I think I am in english\")\n```\nOnce our actions are added, we can invoke the processing of that data. For TextAnalytics, this is using:\n``` c#\n.AnalyseAllAsync();\n```\nMany actions can be added, and the respective cognitive services API's will be called and the results provided into an object that can be easily examined, and has it's own extension methods. However, to continue to use TextAnalytics as the example, putting it all together:\n``` c#\nvar result = await TextAnalyticConfigurationSettings.CreateUsingApiKey(\"YOUR-API-KEY\", LocationKeyIdentifier.WestUs)\n    .SetDiagnosticLoggingLevel(LoggingLevel.Everything)\n    .AddDebugDiagnosticLogging()  // Using System.Diagnostics.Debug\n    .UsingHttpCommunication()\n    .WithTextAnalyticAnalysisActions()\n    .AddSentimentAnalysis(\"This is great.\")\n    .AddKeyPhraseAnalysis(\"This is a snippet of text\")\n    .AddLanguageAnalysis(\"I think I am in english\")\n    .AnalyseAllAsync();\n```\n\n#### Examining the results\nEach cognitive service API (such as TextAnalytics or Face) provides a different type of results since they are performing different actions. However there are some similarities or patterns. Each result will contain a property that houses all the input data and result data for any operations performed. Continuing with the TextAnalytic theme using the above example, the resultof the analyse call contains properties to hold the Sentiment analysis, keyphrase analysis, and language analysis.\n``` c#\nresult.SentimentAnalysis;\nresult.KeyPhraseAnalysis;\nresult.LanguageAnalysis;\n``` \nEach property has a GetResults() method to conveniently return the ist of results. Alternatively, you can drill down into properties of the analysis object but it can be quite verbose.\n``` c#\nresult.SentimentAnalysis.GetResults();\nresult.KeyPhraseAnalysis.GetResults();\nresult.LanguageAnalysis.GetResults();\n``` \nIt is best to look at the specific documentation for each set of operations to further determine what actions can be performed against the result set. Often, specific methods are avlailable to extract or examine the results.\n\n#### The scoring system\nCommon to almost all cognitive service operations is a confidence score for the returned result. This value is always in between 0 and 1 inclusive. 0 represents a negative, or low confidence score whereas 1 represents a positive, or high confidence score. A score of 0.5 is considered neutral. The values of the scores and the variation in the scores will mean different things to different actions. This fluent API provides a default set of score levels for each API set, that is, one for TextAnalytics, one for Face etc. These are the defaults but can be completely customised to suit.\n\nThe default score levels are the following:\n* 0 - 0.35 : \"Negative\"\n* 0.35 - 0.45 : \"Slightly Negative\"\n* 0.45 - 0.55 : \"Neutral\"\n* 0.55 - 0.75 : \"Slightly Positive\"\n* 0.75 - 1 : \"Positive\"\n\nIn the default scoring engine, the \"upper bound\" is not inclusive (using the default/supplied scoring engine). For example, a value must be greater than or equal to 0 and less than 0.35 to be considered \"Negative\". All upper bounds are non inclusive, with the exception of 1.\n\nTextAnalystics uses these scores by default. Face has a slightly different default set of scores.\n* 0 - 0.15 : \"Definitely Negative\"\n* 0.15 - 0.35 : \"Probably Negative\"\n* 0.35 - 0.49 : \"Possibly Negative\"\n* 0.49 - 0.51 : \"Neutral\"\n* 0.51 - 0.65 : \"Possibly Positive\"\n* 0.65 - 0.85 : \"Probably Positive\"\n* 0.85 - 1 : \"Definitely Positive\"\n\nThis is all well and good, but how do we use this?\n\nEach result set or context has a scoring engine with scoring levels attached to it. This can be used as shown in the following Sentiment analysis example:\n``` c#\nvar items = result.SentimentAnalysis.GetResults();\nvar firstItem = items.First();\nvar score = result.SentimentAnalysis.Score(firstItem);\nConsole.WriteLine($\"Score level is: {score.Name}\");\n```\nAlternatively, you can also provide the confidence level directly:\n``` c#\nvar score = result.SentimentAnalysis.Score(0.987);\n``` \nEach API operates a little different in terms of scoring and the fluent API differs a little for the specific API to accomodate this. For example, for Sentiment analysis, you can find all the results with a negative sentiment with the following:\n``` c#\nvar negativeResults = result.SentimentAnalysis.GetResults(DefaultScoreLevels.Negative);\n```\n\nThis is just the beginning though. For full details on all the fluent API options available for each API set, please use the links for the detailed documentation around each fluent API. Similarly, for further details on usage and customisation of the scoring levels, please see the links on that section.\n\n### Change/Modification Log\n* [Detailed change log](./Wiki/ReleaseNotes.md)\n\n### Note\nThis API is only in early stages and many refinements are yet to be applied.\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglav%2Fcognitiveservicesfluentapi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglav%2Fcognitiveservicesfluentapi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglav%2Fcognitiveservicesfluentapi/lists"}