added helpers

wm_interactive/static/styles.css

@@ -354,4 +354,98 @@ h1 {
 
 .floating-btn.generating .stop-icon {
     display: block;
+}
+
+/* Help documentation styles */
+.param-help-icon {
+    color: #6e6e80;
+    font-size: 14px;
+    cursor: pointer;
+}
+
+.help-modal-body {
+    max-height: 70vh;
+    overflow-y: auto;
+}
+
+.help-modal-body h4 {
+    margin-top: 1.5rem;
+    margin-bottom: 0.75rem;
+    font-size: 1.1rem;
+    font-weight: 600;
+    color: #10a37f;
+}
+
+.help-modal-body h4:first-child {
+    margin-top: 0;
+}
+
+.help-modal-body p {
+    margin-bottom: 1rem;
+    line-height: 1.6;
+}
+
+.help-modal-body ol, .help-modal-body ul {
+    margin-bottom: 1rem;
+    padding-left: 1.5rem;
+}
+
+.help-modal-body li {
+    margin-bottom: 0.5rem;
+}
+
+.help-description-list dt {
+    font-weight: 600;
+    margin-bottom: 0.25rem;
+}
+
+.help-description-list dd {
+    margin-bottom: 1rem;
+    margin-left: 1rem;
+}
+
+.paper-references {
+    list-style: none;
+    padding-left: 0;
+}
+
+.paper-references li {
+    margin-bottom: 0.75rem;
+    padding-left: 1rem;
+    border-left: 3px solid #e5e5e5;
+}
+
+.paper-references a {
+    display: block;
+    color: #10a37f;
+    font-weight: 500;
+    margin-bottom: 0.25rem;
+}
+
+.paper-authors {
+    display: block;
+    color: #6e6e80;
+    font-size: 0.9rem;
+    font-style: italic;
+}
+
+/* Tooltip adjustments for parameter help icons */
+.tooltip {
+    --bs-tooltip-max-width: 300px;
+    --bs-tooltip-opacity: 1;
+    --bs-tooltip-padding-y: 0.5rem;
+    --bs-tooltip-padding-x: 0.75rem;
+    --bs-tooltip-bg: rgba(26, 26, 26, 0.95);
+    font-size: 13px;
+    line-height: 1.4;
+}
+
+@media (max-width: 768px) {
+    .help-modal-body {
+        max-height: 60vh;
+    }
+    
+    .tooltip {
+        --bs-tooltip-max-width: 200px;
+    }
 }

wm_interactive/templates/index.html

@@ -11,9 +11,97 @@
     <div class="container">
         <div class="d-flex justify-content-between align-items-center">
             <h1>Interactive watermark detector</h1>
-            <button class="btn btn-outline-secondary" data-bs-toggle="modal" data-bs-target="#paramsModal">
-                <i class="bi bi-gear"></i>
-            </button>
+            <div class="d-flex gap-2">
+                <button class="btn btn-outline-secondary" data-bs-toggle="modal" data-bs-target="#helpModal">
+                    <i class="bi bi-question-circle"></i>
+                </button>
+                <button class="btn btn-outline-secondary" data-bs-toggle="modal" data-bs-target="#paramsModal">
+                    <i class="bi bi-gear"></i>
+                </button>
+            </div>
+        </div>
+
+        <!-- Help Modal -->
+        <div class="modal fade" id="helpModal" tabindex="-1">
+            <div class="modal-dialog modal-lg">
+                <div class="modal-content">
+                    <div class="modal-header">
+                        <h5 class="modal-title">Watermark Detection Help</h5>
+                        <button type="button" class="btn-close" data-bs-dismiss="modal"></button>
+                    </div>
+                    <div class="modal-body help-modal-body">
+                        <h4>What is LLM watermarking?</h4>
+                        <p>LLM watermarking is a technique that slightly modifies how language models generate text, making it possible to detect if text was generated by a specific AI model without visibly changing the text quality.</p>
+                        
+                        <h4>How to use this demo</h4>
+                        <ol>
+                            <li>Enter a prompt in the top text area to generate watermarked text</li>
+                            <li>The generated text will appear in the second text box</li>
+                            <li>The text will be automatically analyzed to show which tokens (parts of text) were influenced by the watermark</li>
+                            <li>The statistics at the bottom show the detection results</li>
+                            <li>You can also paste any text in the second box to test if it contains a watermark</li>
+                        </ol>
+                        
+                        <h4>Detection Methods</h4>
+                        <p><strong>Maryland</strong>: A token-level detection algorithm that analyzes how unexpected each token is, based on the paper "<a href="https://arxiv.org/abs/2301.10226" target="_blank">A Watermark for Large Language Models</a>" by Kirchenbauer et al.</p>
+                        <p><strong>Maryland Z-score</strong>: A variant of the Maryland detector that uses z-scores for better statistical interpretation.</p>
+                        <p><strong>OpenAI</strong>: A watermarking method similar to what was described in "<a href="https://arxiv.org/abs/2306.04634" target="_blank">A Watermark for Large Language Models</a>" by Kirchenbauer et al., inspired by initial reports from OpenAI.</p>
+                        <p><strong>OpenAI Z-score</strong>: A variant of the OpenAI detector that uses z-scores for better statistical interpretation.</p>
+                        
+                        <h4>Parameters Explained</h4>
+                        <dl class="help-description-list">
+                            <dt>Detector Type</dt>
+                            <dd>The algorithm used to detect watermarks in the text. Different detectors perform better in different scenarios.</dd>
+                            
+                            <dt>Seed</dt>
+                            <dd>The random seed used for watermarking. The detector must use the same seed that was used when generating the text. In a real-world scenario, this would be kept private by the model provider.</dd>
+                            
+                            <dt>N-gram Size</dt>
+                            <dd>The number of previous tokens considered when choosing "greenlist" tokens. Larger values make the watermark more robust against edits but may reduce text quality.</dd>
+                            
+                            <dt>Delta</dt>
+                            <dd>The bias added to "greenlist" tokens during generation. Higher values make the watermark stronger but might affect text quality. Typical values range from 1.0 to 5.0.</dd>
+                            
+                            <dt>Temperature</dt>
+                            <dd>Controls randomness in text generation. Higher values (e.g., 1.0) produce more diverse outputs; lower values (e.g., 0.2) make outputs more focused and deterministic.</dd>
+                        </dl>
+                        
+                        <h4>Understanding Results</h4>
+                        <dl class="help-description-list">
+                            <dt>Tokens</dt>
+                            <dd>The total number of tokens in the analyzed text. Tokens are units of text that may represent words, parts of words, or punctuation.</dd>
+                            
+                            <dt>Scored Tokens</dt>
+                            <dd>The number of tokens that were actually evaluated by the detector (excludes first few tokens that don't have enough context).</dd>
+                            
+                            <dt>Final Score</dt>
+                            <dd>A measure of how likely the text contains a watermark. Higher scores indicate stronger evidence of watermarking.</dd>
+                            
+                            <dt>P-value</dt>
+                            <dd>The statistical significance of the detection. Lower values (especially p &lt; 0.05) indicate strong evidence that the text was watermarked. Values close to 0.5 suggest no watermark is present.</dd>
+                        </dl>
+                        
+                        <h4>Related Papers</h4>
+                        <ul class="paper-references">
+                            <li>
+                                <a href="https://arxiv.org/abs/2301.10226" target="_blank">A Watermark for Large Language Models</a>
+                                <span class="paper-authors">Kirchenbauer, Geiping, et al. (2023)</span>
+                            </li>
+                            <li>
+                                <a href="https://arxiv.org/abs/2306.04634" target="_blank">Robust Distortion-free Watermarks for Language Models</a>
+                                <span class="paper-authors">Kuditipudi, Thickstun, et al. (2023)</span>
+                            </li>
+                            <li>
+                                <a href="https://arxiv.org/abs/2305.08883" target="_blank">Provable Robust Watermarking for AI-Generated Text</a>
+                                <span class="paper-authors">Christ, Mireshghallah, et al. (2023)</span>
+                            </li>
+                        </ul>
+                    </div>
+                    <div class="modal-footer">
+                        <button type="button" class="btn btn-primary" data-bs-dismiss="modal">Close</button>
+                    </div>
+                </div>
+            </div>
         </div>
 
         <!-- Advanced Parameters Modal -->
@@ -26,7 +114,10 @@
                     </div>
                     <div class="modal-body">
                         <div class="mb-3">
-                            <label for="detectorType" class="form-label">Detector Type</label>
+                            <div class="d-flex align-items-center">
+                                <i class="bi bi-info-circle param-help-icon me-2" data-bs-toggle="tooltip" title="The algorithm used to detect watermarks in the text. Different algorithms have different strengths and weaknesses."></i>
+                                <label for="detectorType" class="form-label mb-0">Detector Type</label>
+                            </div>
                             <select class="form-select" id="detectorType">
                                 <option value="maryland">Maryland</option>
                                 <option value="marylandz">Maryland Z-score</option>
@@ -36,22 +127,34 @@
                             <div class="form-text">Type of watermark detection algorithm</div>
                         </div>
                         <div class="mb-3">
-                            <label for="seed" class="form-label">Seed</label>
+                            <div class="d-flex align-items-center">
+                                <i class="bi bi-info-circle param-help-icon me-2" data-bs-toggle="tooltip" title="The random seed used for watermarking. For detection to work, this must match the seed used during generation."></i>
+                                <label for="seed" class="form-label mb-0">Seed</label>
+                            </div>
                             <input type="number" class="form-control" id="seed" value="0">
                             <div class="form-text">Random seed for the watermark detector</div>
                         </div>
                         <div class="mb-3">
-                            <label for="ngram" class="form-label">N-gram Size</label>
+                            <div class="d-flex align-items-center">
+                                <i class="bi bi-info-circle param-help-icon me-2" data-bs-toggle="tooltip" title="The number of previous tokens considered when determining the token distribution. Higher values are more secure but may affect quality."></i>
+                                <label for="ngram" class="form-label mb-0">N-gram Size</label>
+                            </div>
                             <input type="number" class="form-control" id="ngram" value="1">
                             <div class="form-text">Size of the n-gram window used for detection</div>
                         </div>
                         <div class="mb-3">
-                            <label for="delta" class="form-label">Delta</label>
+                            <div class="d-flex align-items-center">
+                                <i class="bi bi-info-circle param-help-icon me-2" data-bs-toggle="tooltip" title="The bias added to greenlist tokens during generation. Higher values (2.0-5.0) make watermarks easier to detect but might affect text quality."></i>
+                                <label for="delta" class="form-label mb-0">Delta</label>
+                            </div>
                             <input type="number" step="0.1" class="form-control" id="delta" value="2.0">
                             <div class="form-text">Bias added to greenlist tokens (for Maryland method)</div>
                         </div>
                         <div class="mb-3">
-                            <label for="temperature" class="form-label">Temperature</label>
+                            <div class="d-flex align-items-center">
+                                <i class="bi bi-info-circle param-help-icon me-2" data-bs-toggle="tooltip" title="Controls randomness in generation. Higher values (closer to 1.0) create more diverse outputs but might make watermarks harder to detect."></i>
+                                <label for="temperature" class="form-label mb-0">Temperature</label>
+                            </div>
                             <input type="number" step="0.1" class="form-control" id="temperature" value="0.8">
                             <div class="form-text">Temperature for sampling (higher = more random)</div>
                         </div>
@@ -137,6 +240,20 @@
         const deltaInput = document.getElementById('delta');
         const temperatureInput = document.getElementById('temperature');
 
+        // Initialize tooltips
+        document.addEventListener('DOMContentLoaded', function() {
+            // Initialize Bootstrap tooltips
+            const tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'));
+            const tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
+                return new bootstrap.Tooltip(tooltipTriggerEl);
+            });
+            
+            // Initialize our tokenization
+            updateTokenization().catch(error => {
+                console.error('Error during initial tokenization:', error);
+            });
+        });
+
         function startGeneration() {
             const prompt = promptArea.value.trim();
             if (!prompt) {
@@ -439,13 +556,6 @@
             });
         });
 
-        // Initial tokenization with error handling
-        document.addEventListener('DOMContentLoaded', function() {
-            updateTokenization().catch(error => {
-                console.error('Error during initial tokenization:', error);
-            });
-        });
-
         // Add this helper function for formatting p-values
         function formatPValue(value) {
             if (value >= 0.001) {