[ Add, Edit ] added tests for audio methods, documnented more models properties and added toMap() for models

Author: anasfik

1678301915024987.png 1678360420020361.png1678301915024987.png renamed to 1678360420020361.png

@@ -11,21 +11,25 @@ Future<void> main() async {
   OpenAI.apiKey = Env.apiKey;
 
 // create the audio transcription.
-  final translation = OpenAI.instance.audio.createTranslation(
+  final translation = await OpenAI.instance.audio.createTranslation(
     file: await getFileFromUrl(
-      'https://www.cbvoiceovers.com/wp-content/uploads/2017/05/Commercial-showreel.mp3',
-    ),
+        'https://www.cbvoiceovers.com/wp-content/uploads/2017/05/Commercial-showreel.mp3',
+        fileExtension: "mp3"),
     model: "whisper-1",
+    responseFormat: "json",
   );
 
   // print the translation.
   print(translation);
 }
 
-Future<File> getFileFromUrl(String networkUrl) async {
+Future<File> getFileFromUrl(
+  String networkUrl, {
+  String fileExtension = 'png',
+}) async {
   final response = await http.get(Uri.parse(networkUrl));
   final uniqueImageName = DateTime.now().microsecondsSinceEpoch;
-  final file = File("$uniqueImageName.mp3");
+  final file = File("$uniqueImageName.$fileExtension");
   await file.writeAsBytes(response.bodyBytes);
   return file;
 }

1678360427710524.mp3

@@ -1,24 +1,32 @@
-class OpenAIAudioModel {
-  // lass from json
-//   {
-//   "text": "Imagine the wildest idea that you've ever had, and you're curious about how it might scale to something that's a 100, a 1,000 times bigger. This is a place where you can get to do that."
-// }
+import 'package:meta/meta.dart';
 
+/// {@template openai_audio}
+/// This class represents the audio model of the OpenAI API, which is used and get returned while using the [OpenAIAudio] methods.
+/// {@endtemplate}
+@immutable
+class OpenAIAudioModel {
+  // This the generated text.
   final String text;
 
   @override
   int get hashCode => text.hashCode;
 
+  /// {@macro openai_audio}
   OpenAIAudioModel({
     required this.text,
   });
-  factory OpenAIAudioModel.fromJson(Map<String, dynamic> json) {
+
+  /// This is used  to convert a [Map<String, dynamic>] object to a [OpenAIAudioModel] object.
+  factory OpenAIAudioModel.fromMap(Map<String, dynamic> json) {
     return OpenAIAudioModel(
       text: json['text'],
     );
   }
 
-  Map<String, dynamic> toJson() {
+  ///  This method used to convert the [OpenAIAudioModel] to a [Map<String, dynamic>] object.
+  ///
+  /// could be useful if you want to save an audio response to a database.
+  Map<String, dynamic> toMap() {
     return {
       'text': text,
     };

example/lib/create_audio_translation.dart

@@ -1,4 +1,5 @@
 import 'package:collection/collection.dart';
+import 'package:meta/meta.dart';
 
 import 'sub_models/choices/choices.dart';
 import 'sub_models/usage.dart';
@@ -7,6 +8,10 @@ export 'sub_models/usage.dart';
 export 'sub_models/choices/choices.dart';
 export 'stream/chat.dart';
 
+/// {@template openai_chat_completion}
+/// This class represents the chat completion response model of the OpenAI API, which is used and get returned while using the [OpenAIChat] methods.
+/// {@endtemplate}
+@immutable
 class OpenAIChatCompletionModel {
   /// The [id] of the chat completion.
   final String id;
@@ -25,24 +30,36 @@ class OpenAIChatCompletionModel {
     return id.hashCode ^ created.hashCode ^ choices.hashCode ^ usage.hashCode;
   }
 
+  /// {@macro openai_chat_completion}
   OpenAIChatCompletionModel({
     required this.id,
     required this.created,
     required this.choices,
     required this.usage,
   });
 
-  factory OpenAIChatCompletionModel.fromJson(Map<String, dynamic> json) {
+  /// This is used  to convert a [Map<String, dynamic>] object to a [OpenAIChatCompletionModel] object.
+  factory OpenAIChatCompletionModel.fromMap(Map<String, dynamic> json) {
     return OpenAIChatCompletionModel(
       id: json['id'],
       created: DateTime.fromMillisecondsSinceEpoch(json['created'] * 1000),
       choices: (json['choices'] as List)
-          .map((e) => OpenAIChatCompletionChoiceModel.fromJson(e))
+          .map((e) => OpenAIChatCompletionChoiceModel.fromMap(e))
           .toList(),
-      usage: OpenAIChatCompletionUsageModel.fromJson(json['usage']),
+      usage: OpenAIChatCompletionUsageModel.fromMap(json['usage']),
     );
   }
 
+  /// This is used to convert a [OpenAIChatCompletionModel] object to a [Map<String, dynamic>] object.
+  Map<String, dynamic> toMap() {
+    return {
+      "id": id,
+      "created": created.millisecondsSinceEpoch,
+      "choices": choices.map((e) => e.toMap()).toList(),
+      "usage": usage.toMap(),
+    };
+  }
+
   @override
   String toString() {
     return 'OpenAIChatCompletionModel(id: $id, created: $created, choices: $choices, usage: $usage)';

lib/src/core/models/audio/audio.dart

@@ -26,12 +26,12 @@ class OpenAIStreamChatCompletionModel {
     required this.choices,
   });
 
-  factory OpenAIStreamChatCompletionModel.fromJson(Map<String, dynamic> json) {
+  factory OpenAIStreamChatCompletionModel.fromMap(Map<String, dynamic> json) {
     return OpenAIStreamChatCompletionModel(
       id: json['id'],
       created: DateTime.fromMillisecondsSinceEpoch(json['created'] * 1000),
       choices: (json['choices'] as List)
-          .map((e) => OpenAIStreamChatCompletionChoiceModel.fromJson(e))
+          .map((e) => OpenAIStreamChatCompletionChoiceModel.fromMap(e))
           .toList(),
     );
   }

lib/src/core/models/chat/chat.dart

@@ -17,12 +17,12 @@ class OpenAIStreamChatCompletionChoiceModel {
     required this.finishReason,
   });
 
-  factory OpenAIStreamChatCompletionChoiceModel.fromJson(
+  factory OpenAIStreamChatCompletionChoiceModel.fromMap(
     Map<String, dynamic> json,
   ) {
     return OpenAIStreamChatCompletionChoiceModel(
       index: json['index'],
-      delta: OpenAIStreamChatCompletionChoiceDeltaModel.fromJson(json['delta']),
+      delta: OpenAIStreamChatCompletionChoiceDeltaModel.fromMap(json['delta']),
       finishReason: json['finish_reason'],
     );
   }

lib/src/core/models/chat/stream/chat.dart

@@ -12,7 +12,7 @@ class OpenAIStreamChatCompletionChoiceDeltaModel {
     required this.content,
   });
 
-  factory OpenAIStreamChatCompletionChoiceDeltaModel.fromJson(
+  factory OpenAIStreamChatCompletionChoiceDeltaModel.fromMap(
     Map<String, dynamic> json,
   ) {
     return OpenAIStreamChatCompletionChoiceDeltaModel(

lib/src/core/models/chat/stream/sub_models/choices/choices.dart

@@ -18,7 +18,7 @@ class OpenAIStreamChatCompletionUsageModel {
     required this.totalTokens,
   });
 
-  factory OpenAIStreamChatCompletionUsageModel.fromJson(
+  factory OpenAIStreamChatCompletionUsageModel.fromMap(
       Map<String, dynamic> json) {
     return OpenAIStreamChatCompletionUsageModel(
       promptTokens: json['prompt_tokens'],

lib/src/core/models/chat/stream/sub_models/choices/sub_models/delta.dart

@@ -1,29 +1,48 @@
 import 'sub_models/message.dart';
 
+/// {@template openai_chat_completion_choice}
+/// This class represents a choice of the [OpenAIChatCompletionModel] model of the OpenAI API, which is used and get returned while using the [OpenAIChat] methods.
+/// {@endtemplate}
 class OpenAIChatCompletionChoiceModel {
+  /// The [index] of the choice.
   final int index;
+
+  /// The [message] of the choice.
   final OpenAIChatCompletionChoiceMessageModel message;
+
+  /// The [finishReason] of the choice.
   final String? finishReason;
 
   @override
   int get hashCode {
     return index.hashCode ^ message.hashCode ^ finishReason.hashCode;
   }
 
+  /// {@macro openai_chat_completion_choice}
   OpenAIChatCompletionChoiceModel({
     required this.index,
     required this.message,
     required this.finishReason,
   });
 
-  factory OpenAIChatCompletionChoiceModel.fromJson(Map<String, dynamic> json) {
+  /// This is used  to convert a [Map<String, dynamic>] object to a [OpenAIChatCompletionChoiceModel] object.
+  factory OpenAIChatCompletionChoiceModel.fromMap(Map<String, dynamic> json) {
     return OpenAIChatCompletionChoiceModel(
       index: json['index'],
-      message: OpenAIChatCompletionChoiceMessageModel.fromJson(json['message']),
+      message: OpenAIChatCompletionChoiceMessageModel.fromMap(json['message']),
       finishReason: json['finish_reason'],
     );
   }
 
+  /// This method used to convert the [OpenAIChatCompletionChoiceModel] to a [Map<String, dynamic>] object.
+  Map<String, dynamic> toMap() {
+    return {
+      "index": index,
+      "message": message.toMap(),
+      "finish_reason": finishReason,
+    };
+  }
+
   @override
   String toString() {
     return 'OpenAIChatCompletionChoiceModel(index: $index, message: $message, finishReason: $finishReason)';