From 2d9a114f6690d1f380e5a4e139e135b4ba74b495 Mon Sep 17 00:00:00 2001
From: SignalRT <admin@signalrt.com>
Date: Mon, 18 Mar 2024 21:23:44 +0100
Subject: [PATCH] Include comments and include some checks

---
 LLama/LLavaWeights.cs                     | 49 ++++++++++++++++++++++-
 LLama/Native/SafeLlavaImageEmbedHandle.cs | 40 +++++++++++++++++-
 2 files changed, 86 insertions(+), 3 deletions(-)

diff --git a/LLama/LLavaWeights.cs b/LLama/LLavaWeights.cs
index 9f93922d..ff8959a5 100644
--- a/LLama/LLavaWeights.cs
+++ b/LLama/LLavaWeights.cs
@@ -4,8 +4,15 @@ using LLama.Native;
 
 namespace LLama;
 
+/// <summary>
+/// A set of llava model weights (mmproj), loaded into memory.
+/// </summary>
 public sealed class LLavaWeights : IDisposable
 {
+    /// <summary>
+    /// The native handle, which is used in the native APIs
+    /// </summary>
+    /// <remarks>Be careful how you use this!</remarks>
     public SafeLlavaModelHandle NativeHandle { get; }   
     
     internal LLavaWeights(SafeLlavaModelHandle weights)
@@ -13,27 +20,67 @@ public sealed class LLavaWeights : IDisposable
         NativeHandle = weights;
     }
     
+    /// <summary>
+    /// Load weights into memory
+    /// </summary>
+    /// <param name="mmProject">path to the "mmproj" model file</param>
+    /// <returns></returns>
     public static LLavaWeights LoadFromFile(string mmProject)
     {
         var weights = SafeLlavaModelHandle.LoadFromFile(mmProject, 1);
         return new LLavaWeights(weights);
     }
 
-    public SafeLlavaImageEmbedHandle CreateImageEmbeddings(LLamaContext ctxLlama, Byte[] image )
+    /// <summary>
+    /// Create the Image Embeddings from the bytes of an image.
+    /// </summary>
+    /// <param name="ctxLlama"></param>
+    /// <param name="image">Image bytes. Supported formats:
+    /// <list type="bullet">
+    ///     <item>JPG</item>
+    ///     <item>PNG</item>
+    ///     <item>BMP</item>
+    ///     <item>TGA</item>
+    /// </list>
+    /// </param>
+    /// <returns></returns>
+    public SafeLlavaImageEmbedHandle CreateImageEmbeddings(LLamaContext ctxLlama, byte[] image )
     {
         return NativeHandle.CreateImageEmbeddings(ctxLlama, image  );
     }
 
+    /// <summary>
+    /// Create the Image Embeddings from the bytes of an image.
+    /// </summary>
+    /// <param name="ctxLlama"></param>
+    /// <param name="image">Path to the image file. Supported formats:
+    /// <list type="bullet">
+    ///     <item>JPG</item>
+    ///     <item>PNG</item>
+    ///     <item>BMP</item>
+    ///     <item>TGA</item>
+    /// </list>
+    /// </param>
+    /// <returns></returns>
+    /// <exception cref="InvalidOperationException"></exception> 
     public SafeLlavaImageEmbedHandle CreateImageEmbeddings(LLamaContext ctxLlama, string image )
     {
         return NativeHandle.CreateImageEmbeddings(ctxLlama, image  );
     }
 
+    /// <summary>
+    /// Eval the image embeddings
+    /// </summary>
+    /// <param name="ctxLlama"></param>
+    /// <param name="imageEmbed"></param>
+    /// <param name="n_past"></param>
+    /// <returns></returns>
     public bool EvalImageEmbed(LLamaContext ctxLlama, SafeLlavaImageEmbedHandle imageEmbed, ref int n_past)
     {
         return NativeHandle.EvalImageEmbed( ctxLlama, imageEmbed,  ref n_past );
     }
 
+    /// <inheritdoc />
     public void Dispose()
     {
         NativeHandle.Dispose();
diff --git a/LLama/Native/SafeLlavaImageEmbedHandle.cs b/LLama/Native/SafeLlavaImageEmbedHandle.cs
index f1c62a2d..37802c40 100644
--- a/LLama/Native/SafeLlavaImageEmbedHandle.cs
+++ b/LLama/Native/SafeLlavaImageEmbedHandle.cs
@@ -10,7 +10,7 @@ using LLama.Exceptions;
 namespace LLama.Native
 {
     /// <summary>
-    /// A Reference to a set of llava Image Embed handle
+    /// A Reference to a llava Image Embed handle
     /// </summary>
     public sealed class SafeLlavaImageEmbedHandle
         : SafeLLamaHandleBase
@@ -24,12 +24,48 @@ namespace LLama.Native
         private SafeLlavaImageEmbedHandle()
         {}
 
+        /// <summary>
+        /// Create an image embed from an image file
+        /// </summary>
+        /// <param name="ctxLlava"></param>
+        /// <param name="ctxLlama"></param>
+        /// <param name="image">Path to the image file. Supported formats:
+        /// <list type="bullet">
+        ///     <item>JPG</item>
+        ///     <item>PNG</item>
+        ///     <item>BMP</item>
+        ///     <item>TGA</item>
+        /// </list>
+        /// </param>
+        /// <returns></returns>
+        /// <exception cref="InvalidOperationException"></exception>
         public static SafeLlavaImageEmbedHandle CreateFromFileName( SafeLlavaModelHandle ctxLlava, LLamaContext ctxLlama, string image )
         {
+            // Try to open the image file, this will check:
+            // - File exists (automatically throws FileNotFoundException)
+            // - File is readable (explicit check)
+            // This provides better error messages that llama.cpp, which would throw an access violation exception in both cases.
+            using (var fs = new FileStream(image, FileMode.Open))
+                if (!fs.CanRead)
+                    throw new InvalidOperationException($"Llava image file '{image}' is not readable");
             return NativeApi.llava_image_embed_make_with_filename(ctxLlava,  (int) ctxLlama.BatchThreads, image);
         }
         
-        public static SafeLlavaImageEmbedHandle CreateFromMemory( SafeLlavaModelHandle ctxLlava, LLamaContext ctxLlama, Byte[] image  )
+        /// <summary>
+        /// Create an image embed from the bytes of an image.
+        /// </summary>
+        /// <param name="ctxLlava"></param>
+        /// <param name="ctxLlama"></param>
+        /// <param name="image">Image bytes. Supported formats:
+        /// <list type="bullet">
+        ///     <item>JPG</item>
+        ///     <item>PNG</item>
+        ///     <item>BMP</item>
+        ///     <item>TGA</item>
+        /// </list>
+        /// </param>
+        /// <returns></returns>
+        public static SafeLlavaImageEmbedHandle CreateFromMemory( SafeLlavaModelHandle ctxLlava, LLamaContext ctxLlama, byte[] image  )
         {
             return NativeApi.llava_image_embed_make_with_bytes(ctxLlava,  (int) ctxLlama.BatchThreads, image, image.Length);
         }