Merge pull request #217 from dvonthenen/implement-analyze-client

Implements Analyze Client

Deepgram.Tests/UnitTests/UtilitiesTests/QueryParameterUtilTests.cs

@@ -1,4 +1,4 @@
-using Deepgram.Models.Manage;
+using Deepgram.Models.Manage.v1;
 using Deepgram.Models.PreRecorded.v1;
 
 namespace Deepgram.Tests.UnitTests.UtilitiesTests;

Deepgram/AnalyzeClient.cs

@@ -0,0 +1,148 @@
+using Deepgram.Models.Analyze.v1;
+using Deepgram.Models.Authenticate.v1;
+
+namespace Deepgram;
+
+/// <summary>
+///  Client containing methods for interacting with Read API's
+/// </summary>
+/// <param name="apiKey">Required DeepgramApiKey</param>
+/// <param name="deepgramClientOptions"><see cref="DeepgramClientOptions"/> for HttpClient Configuration</param>
+public class ReadClient(string apiKey, DeepgramClientOptions? deepgramClientOptions = null)
+    : AbstractRestClient(apiKey, deepgramClientOptions)
+{
+    #region NoneCallBacks
+    /// <summary>
+    ///  Transcribe a file by providing a url 
+    /// </summary>
+    /// <param name="source">Url to the file that is to be transcribed <see cref="UrlSource"></param>
+    /// <param name="analyzeSchema">Options for the transcription <see cref="AnalyzeSchema"/></param>
+    /// <returns><see cref="SyncResponse"/></returns>
+    public async Task<SyncResponse> TranscribeUrl(UrlSource source, AnalyzeSchema? analyzeSchema, CancellationToken cancellationToken = default)
+    {
+        VerifyNoCallBack(nameof(TranscribeUrl), analyzeSchema);
+        var stringedOptions = QueryParameterUtil.GetParameters(analyzeSchema);
+        return await PostAsync<SyncResponse>(
+            $"{UriSegments.ANALYZE}?{stringedOptions}",
+            RequestContentUtil.CreatePayload(source), cancellationToken);
+    }
+    /// <summary>
+    /// Transcribes a file using the provided byte array
+    /// </summary>
+    /// <param name="source">file is the form of a byte[]</param>
+    /// <param name="analyzeSchema">Options for the transcription <see cref="AnalyzeSchema"/></param>
+    /// <returns><see cref="SyncResponse"/></returns>
+    public async Task<SyncResponse> TranscribeFile(byte[] source, AnalyzeSchema? analyzeSchema, CancellationToken cancellationToken = default)
+    {
+        VerifyNoCallBack(nameof(TranscribeFile), analyzeSchema);
+        var stringedOptions = QueryParameterUtil.GetParameters(analyzeSchema);
+        var stream = new MemoryStream();
+        stream.Write(source, 0, source.Length);
+        return await PostAsync<SyncResponse>(
+            $"{UriSegments.ANALYZE}?{stringedOptions}",
+            RequestContentUtil.CreateStreamPayload(stream), cancellationToken);
+    }
+
+    /// <summary>
+    /// Transcribes a file using the provided stream
+    /// </summary>
+    /// <param name="source">file is the form of a stream <see cref="Stream"/></param>
+    /// <param name="analyzeSchema">Options for the transcription <see cref="AnalyzeSchema"/></param>
+    /// <returns><see cref="SyncResponse"/></returns>
+    public async Task<SyncResponse> TranscribeFile(Stream source, AnalyzeSchema? analyzeSchema, CancellationToken cancellationToken = default)
+    {
+        VerifyNoCallBack(nameof(TranscribeFile), analyzeSchema);
+        var stringedOptions = QueryParameterUtil.GetParameters(analyzeSchema);
+        return await PostAsync<SyncResponse>(
+            $"{UriSegments.ANALYZE}?{stringedOptions}",
+            RequestContentUtil.CreateStreamPayload(source), cancellationToken);
+    }
+
+    #endregion
+
+    #region  CallBack Methods
+    /// <summary>
+    /// Transcribes a file using the provided byte array and providing a CallBack
+    /// </summary>
+    /// <param name="source">file is the form of a byte[]</param>  
+    /// <param name="callBack">CallBack url</param>    
+    /// <param name="analyzeSchema">Options for the transcription<see cref="AnalyzeSchema"></param>
+    /// <returns><see cref="AsyncResponse"/></returns>
+    public async Task<AsyncResponse> TranscribeFileCallBack(byte[] source, string? callBack, AnalyzeSchema? analyzeSchema, CancellationToken cancellationToken = default)
+    {
+        VerifyOneCallBackSet(nameof(TranscribeFileCallBack), callBack, analyzeSchema);
+
+        if (callBack != null)
+            analyzeSchema.CallBack = callBack;
+        var stringedOptions = QueryParameterUtil.GetParameters(analyzeSchema);
+        var stream = new MemoryStream();
+        stream.Write(source, 0, source.Length);
+        return await PostAsync<AsyncResponse>(
+            $"{UriSegments.ANALYZE}?{stringedOptions}",
+            RequestContentUtil.CreateStreamPayload(stream), cancellationToken);
+    }
+
+    /// <summary>
+    /// Transcribes a file using the provided stream and providing a CallBack
+    /// </summary>
+    /// <param name="source">file is the form of a stream <see cref="Stream"></param>  
+    /// <param name="callBack">CallBack url</param>    
+    /// <param name="analyzeSchema">Options for the transcription<see cref="AnalyzeSchema"></param>
+    /// <returns><see cref="AsyncResponse"/></returns>
+    public async Task<AsyncResponse> TranscribeFileCallBack(Stream source, string? callBack, AnalyzeSchema? analyzeSchema, CancellationToken cancellationToken = default)
+    {
+        VerifyOneCallBackSet(nameof(TranscribeFileCallBack), callBack, analyzeSchema);
+        if (callBack != null)
+            analyzeSchema.CallBack = callBack;
+        var stringedOptions = QueryParameterUtil.GetParameters(analyzeSchema);
+        return await PostAsync<AsyncResponse>(
+            $"{UriSegments.ANALYZE}?{stringedOptions}",
+            RequestContentUtil.CreateStreamPayload(source), cancellationToken);
+    }
+
+    /// <summary>
+    /// Transcribe a file by providing a url and a CallBack
+    /// </summary>
+    /// <param name="source">Url to the file that is to be transcribed <see cref="UrlSource"/></param>
+    /// <param name="callBack">CallBack url</param>    
+    /// <param name="analyzeSchema">Options for the transcription<see cref="AnalyzeSchema"></param>
+    /// <returns><see cref="AsyncResponse"/></returns>
+    public async Task<AsyncResponse> TranscribeUrlCallBack(UrlSource source, string? callBack, AnalyzeSchema? analyzeSchema, CancellationToken cancellationToken = default)
+    {
+        VerifyOneCallBackSet(nameof(TranscribeUrlCallBack), callBack, analyzeSchema);
+
+        if (callBack != null)
+            analyzeSchema.CallBack = callBack;
+        var stringedOptions = QueryParameterUtil.GetParameters(analyzeSchema);
+        return await PostAsync<AsyncResponse>(
+            $"{UriSegments.ANALYZE}?{stringedOptions}",
+            RequestContentUtil.CreatePayload(source), cancellationToken);
+    }
+    #endregion
+
+    #region CallbackChecks
+    private void VerifyNoCallBack(string method, AnalyzeSchema? analyzeSchema)
+    {
+        if (analyzeSchema != null && analyzeSchema.CallBack != null)
+            throw new ArgumentException($"CallBack cannot be provided as schema option to a synchronous transcription when calling {method}. Use {nameof(TranscribeFileCallBack)} or {nameof(TranscribeUrlCallBack)}");
+    }
+
+    private void VerifyOneCallBackSet(string callingMethod, string? callBack, AnalyzeSchema? analyzeSchema)
+    {
+
+        if (analyzeSchema.CallBack == null && callBack == null)
+        { //check if no CallBack set in either callBack parameter or AnalyzeSchema
+            var ex = new ArgumentException($"Either provide a CallBack url or set AnalyzeSchema.CallBack.  If no CallBack needed either {nameof(TranscribeUrl)} or {nameof(TranscribeFile)}");
+            Log.Exception(_logger, $"While calling {callingMethod} no callback set", ex);
+            throw ex;
+        }
+        else if (!string.IsNullOrEmpty(analyzeSchema.CallBack) && !string.IsNullOrEmpty(callBack))
+        {
+            //check that only one CallBack is set in either callBack parameter or AnalyzeSchema
+            var ex = new ArgumentException("CallBack should be set in either the CallBack parameter or AnalyzeSchema.CallBack not in both.");
+            Log.Exception(_logger, $"While calling {callingMethod}, callback set in both parameter and property", ex);
+            throw ex;
+        }
+    }
+    #endregion 
+}

Deepgram/Constants/UriSegments.cs

@@ -15,4 +15,5 @@ public static class UriSegments
     public const string LISTEN = "listen";
     public const string ONPREM = "onprem/distribution/credentials";
     public const string TRANSCRIPTION = "listen";
+    public const string ANALYZE = "read";
 }

Deepgram/Logger/Log.cs

@@ -1,4 +1,4 @@
-using Deepgram.Models.Manage;
+using Deepgram.Models.Manage.v1;
 
 namespace Deepgram.Logger;
 internal static partial class Log

Deepgram/ManageClient.cs

@@ -1,5 +1,4 @@
-using Deepgram.Models.Manage;
-using Deepgram.Models.Manage.v1;
+using Deepgram.Models.Manage.v1;
 using Deepgram.Models.Authenticate.v1;
 
 namespace Deepgram;

Deepgram/Models/Analyze/v1/AnalyzeSchema.cs

@@ -0,0 +1,71 @@
+namespace Deepgram.Models.Analyze.v1;
+
+public class AnalyzeSchema
+{
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("callback")]
+    public string? CallBack { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("callback_method")]
+    public string? CallbackMethod { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("custom_intent")]
+    public List<string>? CustomIntent { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("custom_intent_mode")]
+    public string? CustomIntentMode { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("custom_topic")]
+    public List<string>? CustomTopic { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("custom_topic_mode")]
+    public string? CustomTopicMode { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("intents")]
+    public bool? Intents { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("language")]
+    public string? Language { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("sentiment")]
+    public bool? Sentiment { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("summarize")]
+    public bool? Summarize { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("topics")]
+    public bool? Topics { get; set; }
+}
+

Deepgram/Models/Analyze/v1/AsyncResponse.cs

@@ -0,0 +1,12 @@
+namespace Deepgram.Models.Analyze.v1;
+
+public record AsyncResponse
+{
+    /// <summary>
+    /// Id of transcription request returned when
+    /// a CallBack has been supplied in request
+    /// </summary>
+    [JsonPropertyName("request_id")]
+    public string? RequestId { get; set; }
+}
+

Deepgram/Models/Analyze/v1/Average.cs

@@ -0,0 +1,16 @@
+namespace Deepgram.Models.Analyze.v1;
+
+public record Average
+{
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("sentiment")]
+    public string? Sentiment { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("sentiment_score")]
+    public double? SentimentScore { get; set; }
+}

Deepgram/Models/Analyze/v1/Intent.cs

@@ -0,0 +1,19 @@
+namespace Deepgram.Models.Analyze.v1;
+
+public record Intent
+{
+    /// <summary>
+    /// <see href="https://developers.deepgram.com/reference/audio-intelligence-apis#intent-recognition"/>
+    /// </summary>
+    [JsonPropertyName("intent")]
+    public string? Intention { get; set; }
+
+    /// <summary>
+    /// <see href="https://developers.deepgram.com/reference/audio-intelligence-apis#intent-recognition"/>
+    /// </summary>
+    [JsonPropertyName("confidence_score")]
+    public double? ConfidenceScore { get; set; }
+}
+
+
+

Deepgram/Models/Analyze/v1/IntentGroup.cs

@@ -0,0 +1,11 @@
+namespace Deepgram.Models.Analyze.v1;
+
+public record IntentGroup
+{
+    /// <summary> 
+    /// <see href="https://developers.deepgram.com/reference/audio-intelligence-apis#intent-recognition"/>
+    /// <see cref="IntentSegment"/>
+    /// </summary>
+    [JsonPropertyName("segments")]
+    public IReadOnlyList<Segment>? Segments { get; set; }
+}

Deepgram/Models/Analyze/v1/IntentsInfo.cs

@@ -0,0 +1,24 @@
+namespace Deepgram.Models.Analyze.v1;
+
+public record IntentsInfo
+{
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("input_tokens")]
+    public int? InputTokens { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("model_uuid")]
+    public string? ModelUuid { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("output_tokens")]
+    public int? OutputTokens { get; set; }
+}
+
+

Deepgram/Models/Analyze/v1/Metadata.cs

@@ -0,0 +1,46 @@
+namespace Deepgram.Models.Analyze.v1;
+
+public record Metadata
+{
+    /// <summary>
+    /// Unique identifier for the submitted audio and derived data returned.
+    /// </summary>
+    [JsonPropertyName("request_id")]
+    public string? RequestId { get; set; }
+
+    /// <summary>
+    /// Timestamp that indicates when the audio was submitted.
+    /// </summary>
+    [JsonPropertyName("created")]
+    public DateTime? Created { get; set; }
+
+    /// <summary>
+    /// Language detected
+    /// </summary>
+    [JsonPropertyName("language")]
+    public string? Language { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("intents_info")]
+    public IntentsInfo? IntentsInfo { get; set; }
+
+    /// <summary>
+    /// TODO.
+    /// </summary>
+    [JsonPropertyName("sentiment_info")]
+    public SentimentInfo? SentimentInfo { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("summary_info")]
+    public SummaryInfo? SummaryInfo { get; set; }
+
+    /// <summary>
+    /// TODO
+    /// </summary>
+    [JsonPropertyName("topics_info")]
+    public TopicsInfo? TopicsInfo { get; set; }
+}