From 3d6eee2cc3ea7a80bf029657ad784b7aa6a3f279 Mon Sep 17 00:00:00 2001
From: mshannon-sil <matthew_shannon@sil.org>
Date: Mon, 17 Aug 2026 23:34:08 -0400
Subject: [PATCH 1/2] add low book confidence checker

---
 .../QualityEstimation/BookConfidence.cs       | 24 ++++++++
 .../QualityEstimation/BookConfidenceTests.cs  | 59 +++++++++++++++++++
 2 files changed, 83 insertions(+)
 create mode 100644 src/SIL.Machine/QualityEstimation/BookConfidence.cs
 create mode 100644 tests/SIL.Machine.Tests/QualityEstimation/BookConfidenceTests.cs

diff --git a/src/SIL.Machine/QualityEstimation/BookConfidence.cs b/src/SIL.Machine/QualityEstimation/BookConfidence.cs
new file mode 100644
index 00000000..d899d670
--- /dev/null
+++ b/src/SIL.Machine/QualityEstimation/BookConfidence.cs
@@ -0,0 +1,24 @@
+using System;
+
+namespace SIL.Machine.QualityEstimation
+{
+    public static class BookConfidence
+    {
+        public const double LowBookConfidenceThreshold = 0.42;
+
+        public static bool IsBookConfidenceUnusuallyLow(double confidence, string bookId = null, string model = null)
+        {
+            if (!(confidence >= 0 && confidence <= 1))
+            {
+                throw new ArgumentOutOfRangeException(
+                    nameof(confidence),
+                    confidence,
+                    "The book confidence is invalid. It is calculated as the geometric mean of the segment "
+                        + "confidences, and it must be between 0 and 1, inclusive."
+                );
+            }
+
+            return confidence < LowBookConfidenceThreshold;
+        }
+    }
+}
diff --git a/tests/SIL.Machine.Tests/QualityEstimation/BookConfidenceTests.cs b/tests/SIL.Machine.Tests/QualityEstimation/BookConfidenceTests.cs
new file mode 100644
index 00000000..145758fc
--- /dev/null
+++ b/tests/SIL.Machine.Tests/QualityEstimation/BookConfidenceTests.cs
@@ -0,0 +1,59 @@
+using NUnit.Framework;
+
+namespace SIL.Machine.QualityEstimation;
+
+[TestFixture]
+public class BookConfidenceTests
+{
+    [Test]
+    public void IsBookConfidenceUnusuallyLow_AtThreshold()
+    {
+        Assert.That(BookConfidence.IsBookConfidenceUnusuallyLow(BookConfidence.LowBookConfidenceThreshold), Is.False);
+    }
+
+    [Test]
+    public void IsBookConfidenceUnusuallyLow_MinConfidence()
+    {
+        Assert.That(BookConfidence.IsBookConfidenceUnusuallyLow(0.0), Is.True);
+    }
+
+    [Test]
+    public void IsBookConfidenceUnusuallyLow_MaxConfidence()
+    {
+        Assert.That(BookConfidence.IsBookConfidenceUnusuallyLow(1.0), Is.False);
+    }
+
+    [Test]
+    public void IsBookConfidenceUnusuallyLow_WithBookIdAndModel()
+    {
+        using (Assert.EnterMultipleScope())
+        {
+            Assert.That(
+                BookConfidence.IsBookConfidenceUnusuallyLow(0.3, "MAT", "facebook/nllb-200-distilled-1.3B"),
+                Is.True
+            );
+            Assert.That(
+                BookConfidence.IsBookConfidenceUnusuallyLow(0.9, "MAT", "facebook/nllb-200-distilled-1.3B"),
+                Is.False
+            );
+        }
+    }
+
+    [Test]
+    public void IsBookConfidenceUnusuallyLow_Negative()
+    {
+        Assert.Throws<ArgumentOutOfRangeException>(() => BookConfidence.IsBookConfidenceUnusuallyLow(-0.5));
+    }
+
+    [Test]
+    public void IsBookConfidenceUnusuallyLow_GreaterThanOne()
+    {
+        Assert.Throws<ArgumentOutOfRangeException>(() => BookConfidence.IsBookConfidenceUnusuallyLow(1.5));
+    }
+
+    [Test]
+    public void IsBookConfidenceUnusuallyLow_Nan()
+    {
+        Assert.Throws<ArgumentOutOfRangeException>(() => BookConfidence.IsBookConfidenceUnusuallyLow(double.NaN));
+    }
+}

From e2aba145dc68583b2661f1e636aab5e496cc0ad7 Mon Sep 17 00:00:00 2001
From: mshannon-sil <matthew_shannon@sil.org>
Date: Tue, 18 Aug 2026 14:04:02 -0400
Subject: [PATCH 2/2] add codedoc comment; simplify exception message

---
 .../QualityEstimation/BookConfidence.cs       | 22 ++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/src/SIL.Machine/QualityEstimation/BookConfidence.cs b/src/SIL.Machine/QualityEstimation/BookConfidence.cs
index d899d670..c9567fef 100644
--- a/src/SIL.Machine/QualityEstimation/BookConfidence.cs
+++ b/src/SIL.Machine/QualityEstimation/BookConfidence.cs
@@ -4,8 +4,25 @@ namespace SIL.Machine.QualityEstimation
 {
     public static class BookConfidence
     {
-        public const double LowBookConfidenceThreshold = 0.42;
+        public static readonly double LowBookConfidenceThreshold = 0.42;
 
+        /// <summary>
+        /// Determines whether a book confidence is unusually low, i.e. below
+        /// <see cref="LowBookConfidenceThreshold"/>.
+        /// </summary>
+        /// <param name="confidence">
+        /// The book confidence, calculated as the geometric mean of the segment confidences. Must be between 0 and 1,
+        /// inclusive.
+        /// </param>
+        /// <param name="bookId">The book id. Reserved for future book-specific logic; not currently used.</param>
+        /// <param name="model">The model name. Reserved for future model-specific logic; not currently used.</param>
+        /// <returns>
+        /// <c>true</c> if <paramref name="confidence"/> is below <see cref="LowBookConfidenceThreshold"/>; otherwise,
+        /// <c>false</c>.
+        /// </returns>
+        /// <exception cref="ArgumentOutOfRangeException">
+        /// <paramref name="confidence"/> is not between 0 and 1, inclusive.
+        /// </exception>
         public static bool IsBookConfidenceUnusuallyLow(double confidence, string bookId = null, string model = null)
         {
             if (!(confidence >= 0 && confidence <= 1))
@@ -13,8 +30,7 @@ public static bool IsBookConfidenceUnusuallyLow(double confidence, string bookId
                 throw new ArgumentOutOfRangeException(
                     nameof(confidence),
                     confidence,
-                    "The book confidence is invalid. It is calculated as the geometric mean of the segment "
-                        + "confidences, and it must be between 0 and 1, inclusive."
+                    "The book confidence must be between 0 and 1, inclusive."
                 );
             }