UI help tooltips + simplify incomplete shard upload behavior

app.py

@@ -267,6 +267,24 @@ APP_CSS = """
   font-size: 0.83rem;
   padding: 0.24rem 0.3rem;
 }
+
+.setting-help-q {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.05rem;
+  height: 1.05rem;
+  margin-left: 0.42rem;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  color: var(--text-main);
+  background: color-mix(in srgb, var(--bg-panel) 90%, transparent);
+  font-size: 0.74rem;
+  font-weight: 700;
+  cursor: help;
+  line-height: 1;
+  vertical-align: middle;
+}
 """
 
 THEME_JS = """
@@ -328,6 +346,42 @@ SEED_WIDGET_JS = """
 }
 """
 
+SETTING_HELP_JS = """
+() => {
+  const helpByPrefix = [
+    ["Theme", "Switch between visual color themes."],
+    ["Seed URL List (one URL per line)", "Provide crawl entry points. Put one URL per line; duplicates are ignored."],
+    ["Shard Size Rows", "Rows written per parquet shard before a full shard is emitted."],
+    ["Max Links Per Page", "Maximum discovered links to enqueue from each parsed page."],
+    ["Request Timeout (seconds)", "HTTP request timeout per URL."],
+    ["Max Response Bytes", "Maximum response body bytes to read per page."],
+    ["Upload shards to my HF repo", "Enable direct upload of produced shards to your Hugging Face Space repo."],
+    ["HF Repo ID", "Target Hugging Face repo in owner/name format."],
+    ["HF Token (write permissions)", "Token with write access to the target repo."],
+    ["Private HF Repo", "Create the target repo as private if it does not exist."],
+    ["HF Path Prefix", "Folder path inside the repo where shards are uploaded."],
+    ["Upload incomplete shard buffers", "On crawl finish/stop, flush the current partial shard buffer and upload it too."],
+  ];
+
+  const clean = (value) => String(value || "").replace(/\\s+/g, " ").trim();
+  const labels = document.querySelectorAll(".gradio-container label");
+
+  for (const label of labels) {
+    if (label.querySelector(".setting-help-q")) continue;
+    const text = clean(label.textContent);
+    const match = helpByPrefix.find(([prefix]) => text.startsWith(prefix));
+    if (!match) continue;
+
+    const q = document.createElement("span");
+    q.className = "setting-help-q";
+    q.textContent = "?";
+    q.title = match[1];
+    label.appendChild(q);
+  }
+  return [];
+}
+"""
+
 
 def utc_now_iso() -> str:
     return datetime.now(timezone.utc).isoformat(timespec="seconds")
@@ -461,7 +515,6 @@ def build_crawler_config(
     shard_size_rows: int,
     enable_hf_upload: bool,
     upload_incomplete_shards: bool,
-    incomplete_shard_flush_seconds: float,
     hf_repo_id: str,
     hf_token: str,
     hf_private_repo: bool,
@@ -480,7 +533,6 @@ def build_crawler_config(
         output_dir=Path(__file__).resolve().parent / "shards",
         enable_hf_upload=bool(enable_hf_upload),
         upload_incomplete_shards=bool(upload_incomplete_shards),
-        incomplete_shard_flush_seconds=float(incomplete_shard_flush_seconds),
         hf_repo_id=hf_repo_id.strip(),
         hf_token=hf_token.strip(),
         hf_private_repo=bool(hf_private_repo),
@@ -699,7 +751,6 @@ def _start_crawl(
     shard_size_rows: int,
     enable_hf_upload: bool,
     upload_incomplete_shards: bool,
-    incomplete_shard_flush_seconds: float,
     hf_repo_id: str,
     hf_token: str,
     hf_private_repo: bool,
@@ -714,7 +765,6 @@ def _start_crawl(
             shard_size_rows=shard_size_rows,
             enable_hf_upload=enable_hf_upload,
             upload_incomplete_shards=upload_incomplete_shards,
-            incomplete_shard_flush_seconds=incomplete_shard_flush_seconds,
             hf_repo_id=hf_repo_id,
             hf_token=hf_token,
             hf_private_repo=hf_private_repo,
@@ -737,7 +787,6 @@ def start_crawl_standard(
     shard_size_rows: int,
     enable_hf_upload: bool,
     upload_incomplete_shards: bool,
-    incomplete_shard_flush_seconds: float,
     hf_repo_id: str,
     hf_token: str,
     hf_private_repo: bool,
@@ -752,7 +801,6 @@ def start_crawl_standard(
         shard_size_rows=shard_size_rows,
         enable_hf_upload=enable_hf_upload,
         upload_incomplete_shards=upload_incomplete_shards,
-        incomplete_shard_flush_seconds=incomplete_shard_flush_seconds,
         hf_repo_id=hf_repo_id,
         hf_token=hf_token,
         hf_private_repo=hf_private_repo,
@@ -768,7 +816,6 @@ def start_crawl_super(
     shard_size_rows: int,
     enable_hf_upload: bool,
     upload_incomplete_shards: bool,
-    incomplete_shard_flush_seconds: float,
     hf_repo_id: str,
     hf_token: str,
     hf_private_repo: bool,
@@ -783,7 +830,6 @@ def start_crawl_super(
         shard_size_rows=shard_size_rows,
         enable_hf_upload=enable_hf_upload,
         upload_incomplete_shards=upload_incomplete_shards,
-        incomplete_shard_flush_seconds=incomplete_shard_flush_seconds,
         hf_repo_id=hf_repo_id,
         hf_token=hf_token,
         hf_private_repo=hf_private_repo,
@@ -807,13 +853,6 @@ def toggle_hf_fields(enable_hf_upload: bool) -> tuple[Any, Any, Any, Any, Any]:
     return update, update, update, update, update
 
 
-def toggle_incomplete_flush_field(
-    enable_hf_upload: bool,
-    upload_incomplete_shards: bool,
-) -> Any:
-    return gr.update(visible=bool(enable_hf_upload and upload_incomplete_shards))
-
-
 def build_ui() -> gr.Blocks:
     defaults = CrawlerConfig(
         seed_urls=[
@@ -931,14 +970,6 @@ def build_ui() -> gr.Blocks:
                 value=False,
                 visible=False,
             )
-            incomplete_shard_flush_seconds = gr.Slider(
-                label="Incomplete Upload Flush Interval (seconds)",
-                minimum=5,
-                maximum=300,
-                step=1,
-                value=int(defaults.incomplete_shard_flush_seconds),
-                visible=False,
-            )
 
         with gr.Row():
             start_button = gr.Button("Start Crawl (12 Threads)", variant="primary")
@@ -958,7 +989,6 @@ def build_ui() -> gr.Blocks:
             shard_size_rows,
             enable_hf_upload,
             upload_incomplete_shards,
-            incomplete_shard_flush_seconds,
             hf_repo_id,
             hf_token,
             hf_private_repo,
@@ -982,16 +1012,6 @@ def build_ui() -> gr.Blocks:
                 upload_incomplete_shards,
             ],
         )
-        enable_hf_upload.change(
-            toggle_incomplete_flush_field,
-            inputs=[enable_hf_upload, upload_incomplete_shards],
-            outputs=[incomplete_shard_flush_seconds],
-        )
-        upload_incomplete_shards.change(
-            toggle_incomplete_flush_field,
-            inputs=[enable_hf_upload, upload_incomplete_shards],
-            outputs=[incomplete_shard_flush_seconds],
-        )
 
         seed_urls_input.change(
             fn=None,
@@ -1001,6 +1021,7 @@ def build_ui() -> gr.Blocks:
         )
 
         theme_name.change(fn=None, inputs=theme_name, outputs=[], js=THEME_JS)
+        demo.load(fn=None, inputs=[], outputs=[], js=SETTING_HELP_JS)
         demo.load(
             fn=None,
             inputs=[],
@@ -1014,6 +1035,8 @@ def build_ui() -> gr.Blocks:
             js=SEED_WIDGET_JS,
         )
         demo.load(fn=poll_dashboard, inputs=[], outputs=outputs)
+        enable_hf_upload.change(fn=None, inputs=[], outputs=[], js=SETTING_HELP_JS)
+        upload_incomplete_shards.change(fn=None, inputs=[], outputs=[], js=SETTING_HELP_JS)
 
         timer = gr.Timer(value=1.0)
         timer.tick(fn=poll_dashboard, inputs=[], outputs=outputs)