[ Add, Edit ] added tests for audio methods, documnented more models …

…properties and added toMap() for models

example/lib/create_audio_translation.dart

@@ -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;
 }

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

@@ -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,
     };

lib/src/core/models/chat/chat.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/chat/stream/chat.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/stream/sub_models/choices/choices.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/sub_models/choices/sub_models/delta.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/usage.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/sub_models/choices/choices.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)';

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

@@ -1,25 +1,36 @@
+/// {@template openai_chat_completion_choice_message_model}
+/// This represents the message of the [OpenAIChatCompletionChoiceModel] model of the OpenAI API, which is used and get returned while using the [OpenAIChat] methods.
+/// {@endtemplate}
+
 class OpenAIChatCompletionChoiceMessageModel {
+  /// The [role] of the message.
   final String role;
+
+  /// The [content] of the message.
   final String content;
 
   @override
   int get hashCode {
     return role.hashCode ^ content.hashCode;
   }
 
+  /// {@macro openai_chat_completion_choice_message_model}
   OpenAIChatCompletionChoiceMessageModel({
     required this.role,
     required this.content,
   });
 
-  factory OpenAIChatCompletionChoiceMessageModel.fromJson(
+  /// This is used  to convert a [Map<String, dynamic>] object to a [OpenAIChatCompletionChoiceMessageModel] object.
+  factory OpenAIChatCompletionChoiceMessageModel.fromMap(
     Map<String, dynamic> json,
   ) {
     return OpenAIChatCompletionChoiceMessageModel(
       role: json['role'],
       content: json['content'],
     );
   }
+
+  /// This method used to convert the [OpenAIChatCompletionChoiceMessageModel] to a [Map<String, dynamic>] object.
   Map<String, dynamic> toMap() {
     return {
       "role": role,

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

@@ -1,8 +1,17 @@
 export 'choices/sub_models/message.dart';
 
+/// {@template openai_chat_completion_usage}
+/// This class represents the chat completion usage model of the OpenAI API, which is used and get returned while using the [OpenAIChat] methods.
+/// {@endtemplate}
 class OpenAIChatCompletionUsageModel {
+  /// The number of tokens used for the prompt(s).
   final int promptTokens;
+
+  /// The number of tokens used for the chat completion(s).
   final int completionTokens;
+
+  /// The total number of tokens used for the chat completion(s).
+  /// This is the sum of [promptTokens] and [completionTokens].
   final int totalTokens;
 
   @override
@@ -12,20 +21,31 @@ class OpenAIChatCompletionUsageModel {
         totalTokens.hashCode;
   }
 
+  /// {@macro openai_chat_completion_usage}
   OpenAIChatCompletionUsageModel({
     required this.promptTokens,
     required this.completionTokens,
     required this.totalTokens,
   });
 
-  factory OpenAIChatCompletionUsageModel.fromJson(Map<String, dynamic> json) {
+  /// This is used  to convert a [Map<String, dynamic>] object to a [OpenAIChatCompletionUsageModel] object.
+  factory OpenAIChatCompletionUsageModel.fromMap(Map<String, dynamic> json) {
     return OpenAIChatCompletionUsageModel(
       promptTokens: json['prompt_tokens'],
       completionTokens: json['completion_tokens'],
       totalTokens: json['total_tokens'],
     );
   }
 
+  /// This is used to convert a [OpenAIChatCompletionUsageModel] object to a [Map<String, dynamic>] object.
+  Map<String, dynamic> toMap() {
+    return {
+      "prompt_tokens": promptTokens,
+      "completion_tokens": completionTokens,
+      "total_tokens": totalTokens,
+    };
+  }
+
   @override
   String toString() {
     return 'OpenAIChatCompletionUsageModel(promptTokens: $promptTokens, completionTokens: $completionTokens, totalTokens: $totalTokens)';

lib/src/core/models/completion/completion.dart

@@ -40,15 +40,15 @@ class OpenAICompletionModel {
   });
 
   /// This method is used to convert a [Map<String, dynamic>] object to a [OpenAICompletionModel] object.
-  factory OpenAICompletionModel.fromJson(Map<String, dynamic> json) {
+  factory OpenAICompletionModel.fromMap(Map<String, dynamic> json) {
     return OpenAICompletionModel(
       id: json['id'],
       created: DateTime.fromMillisecondsSinceEpoch(json['created'] * 1000),
       model: json['model'],
       choices: (json['choices'] as List)
-          .map((i) => OpenAICompletionModelChoice.fromJson(i))
+          .map((i) => OpenAICompletionModelChoice.fromMap(i))
           .toList(),
-      usage: OpenAICompletionModelUsage.fromJson(json['usage']),
+      usage: OpenAICompletionModelUsage.fromMap(json['usage']),
     );
   }
 

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

@@ -33,12 +33,12 @@ class OpenAIStreamCompletionModel {
   });
 
   /// This method is used to convert a [Map<String, dynamic>] object to a [OpenAIStreamCompletionModel] object.
-  factory OpenAIStreamCompletionModel.fromJson(Map<String, dynamic> json) {
+  factory OpenAIStreamCompletionModel.fromMap(Map<String, dynamic> json) {
     return OpenAIStreamCompletionModel(
       id: json['id'],
       created: DateTime.fromMillisecondsSinceEpoch(json['created'] * 1000),
       choices: (json['choices'] as List)
-          .map((e) => OpenAIStreamCompletionModelChoice.fromJson(e))
+          .map((e) => OpenAIStreamCompletionModelChoice.fromMap(e))
           .toList(),
       model: json['model'],
     );

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

@@ -31,7 +31,7 @@ class OpenAIStreamCompletionModelChoice {
   });
 
   /// This method is used to convert a [Map<String, dynamic>] object to a [OpenAIStreamCompletionModelChoice] object.
-  factory OpenAIStreamCompletionModelChoice.fromJson(
+  factory OpenAIStreamCompletionModelChoice.fromMap(
     Map<String, dynamic> json,
   ) {
     return OpenAIStreamCompletionModelChoice(

lib/src/core/models/completion/sub_models/choice.dart

@@ -31,7 +31,7 @@ class OpenAICompletionModelChoice {
   });
 
   /// This method is used to convert a [Map<String, dynamic>] object to a [OpenAICompletionModelChoice] object.
-  factory OpenAICompletionModelChoice.fromJson(Map<String, dynamic> json) {
+  factory OpenAICompletionModelChoice.fromMap(Map<String, dynamic> json) {
     return OpenAICompletionModelChoice(
       text: json['text'],
       index: json['index'],

lib/src/core/models/completion/sub_models/usage.dart

@@ -23,7 +23,7 @@ class OpenAICompletionModelUsage {
   });
 
   /// This method is used to convert a [Map<String, dynamic>] object to a [OpenAICompletionModelUsage] object.
-  factory OpenAICompletionModelUsage.fromJson(Map<String, dynamic> json) {
+  factory OpenAICompletionModelUsage.fromMap(Map<String, dynamic> json) {
     return OpenAICompletionModelUsage(
       promptTokens: json['prompt_tokens'],
       completionTokens: json['completion_tokens'],

lib/src/core/models/edit/edit.dart

@@ -28,13 +28,13 @@ class OpenAIEditModel {
   });
 
   /// This method is used to convert a [Map<String, dynamic>] object to a [OpenAIEditModel] object.
-  factory OpenAIEditModel.fromJson(Map<String, dynamic> json) {
+  factory OpenAIEditModel.fromMap(Map<String, dynamic> json) {
     return OpenAIEditModel(
       created: DateTime.fromMillisecondsSinceEpoch(json['created'] * 1000),
       choices: (json['choices'] as List)
-          .map((e) => OpenAIEditModelChoice.fromJson(e))
+          .map((e) => OpenAIEditModelChoice.fromMap(e))
           .toList(),
-      usage: OpenAIEditModelUsage.fromJson(json['usage']),
+      usage: OpenAIEditModelUsage.fromMap(json['usage']),
     );
   }