Polish UI and generate file summaries

app.py

@@ -48,7 +48,8 @@ CSS = """
 }
 
 #btl-title {
-  padding: 22px 0 10px;
+  padding: 22px 0 12px;
+  text-align: center;
 }
 
 #btl-title h1 {
@@ -62,24 +63,74 @@ CSS = """
 #btl-title p {
   color: var(--btl-muted);
   font-size: 1.02rem;
+  line-height: 1.6;
+  max-width: 850px;
+  margin: 14px auto 0;
+}
+
+#btl-cli {
   max-width: 780px;
-  margin: 14px 0 0;
+  margin: 0 auto 22px;
+}
+
+#btl-cli .btl-cli-label {
+  color: var(--btl-muted);
+  font-size: 0.82rem;
+  font-weight: 750;
+  letter-spacing: 0;
+  margin: 0 0 7px;
+  text-transform: uppercase;
+}
+
+#btl-cli pre {
+  background: #f1f3f5;
+  border: 1px solid #d5d9dd;
+  border-radius: 8px;
+  color: #18201b;
+  margin: 0;
+  overflow-x: auto;
+  padding: 14px 16px;
+  text-align: left;
+}
+
+#btl-cli code {
+  color: #18201b;
+  font-size: 0.94rem;
+  white-space: pre;
 }
 
 .btl-upload .wrap {
   background: rgba(255, 255, 255, 0.76) !important;
 }
 
+#btl-controls,
+#btl-actions {
+  justify-content: center;
+  margin-bottom: 12px;
+}
+
 #btl-controls {
   align-items: end;
-  margin-bottom: 12px;
 }
 
-#btl-controls .form,
-#btl-controls .block {
+#btl-actions {
+  align-items: center;
+}
+
+#btl-controls > .form,
+#btl-controls > .block {
   min-height: 72px !important;
 }
 
+#btl-controls > *,
+#btl-actions > * {
+  flex: 0 1 360px !important;
+}
+
+#btl-actions > * {
+  max-width: 190px;
+}
+
 #model_choice label,
 #input_code label,
 #output_code label,
@@ -135,18 +186,23 @@ code {
 
 #input_code textarea,
 #output_code textarea {
-  min-height: 520px !important;
+  height: min(56vh, 620px) !important;
   line-height: 1.45 !important;
+  overflow: auto !important;
 }
 
 #input_code .cm-editor,
 #output_code .cm-editor {
-  min-height: 520px !important;
+  height: min(56vh, 620px) !important;
+  max-height: 620px !important;
+  border-top: 0 !important;
 }
 
 #input_code .cm-scroller,
 #output_code .cm-scroller {
-  min-height: 520px !important;
+  height: min(56vh, 620px) !important;
+  max-height: 620px !important;
+  overflow: auto !important;
 }
 
 #output_code textarea {
@@ -163,6 +219,13 @@ code {
   background: var(--btl-code-bg) !important;
   color: #dbf8df !important;
 }
+
+#input_code .label-wrap,
+#output_code .label-wrap,
+#input_code .wrap,
+#output_code .wrap {
+  border-top-color: transparent !important;
+}
 """
 
 
@@ -222,8 +285,12 @@ def build_app() -> gr.Blocks:
                 """
                 <header id="btl-title">
                   <h1>between-the-lines</h1>
-                  <p>Upload or paste a Python file, choose a comment model, then generate comments that are checked against the file's AST before they are shown.</p>
+                  <p>Annotate Python files from the web or terminal with semantically meaningful comments. The model comments only on AST-backed code blocks, and the application deterministically verifies that the executable AST is unchanged after annotation.</p>
                 </header>
+                <section id="btl-cli" aria-label="Terminal command">
+                  <p class="btl-cli-label">Run from your terminal</p>
+                  <pre><code>npx between-the-lines-cli path/to/file.py --model base --summary</code></pre>
+                </section>
                 """
             )
 
@@ -242,6 +309,8 @@ def build_app() -> gr.Blocks:
                     elem_id="model_choice",
                     scale=2,
                 )
+
+            with gr.Row(equal_height=False, elem_id="btl-actions"):
                 run_button = gr.Button("Annotate", variant="primary", scale=1)
                 clear_button = gr.ClearButton(value="Clear", components=[], scale=1)
 

btl/annotate.py

@@ -2,7 +2,7 @@ import ast
 from dataclasses import dataclass
 from typing import Literal
 
-from .model import ModelUnavailableError, generate_comment
+from .model import ModelUnavailableError, generate_comment, generate_file_summary
 
 
 ModelChoice = Literal["base", "tuned"]
@@ -71,6 +71,20 @@ def summarize_blocks(blocks: list[BlockInfo]) -> str:
     return f"This file defines {names}{overflow}."
 
 
+def generate_summary(source: str, blocks: list[BlockInfo], model_choice: ModelChoice = "base") -> tuple[str, list[str]]:
+    notes: list[str] = []
+    try:
+        summary = generate_file_summary(source, variant=model_choice)
+        if summary:
+            return summary, notes
+        notes.append("file summary: model returned an empty summary.")
+    except ModelUnavailableError:
+        raise
+    except Exception as exc:
+        notes.append(f"file summary: model generation failed ({type(exc).__name__}).")
+    return summarize_blocks(blocks), notes
+
+
 def insert_comments(source: str, comments: dict[int, str]) -> str:
     lines = source.splitlines()
     inserts: dict[int, list[str]] = {}
@@ -111,11 +125,15 @@ def annotate_python(source: str, model_choice: ModelChoice = "base") -> Annotati
         return AnnotationResult("", "", f"Syntax error on line {exc.lineno}: {exc.msg}", False, 0)
 
     blocks = collect_blocks(original_tree, source)
-    summary = summarize_blocks(blocks)
+    summary, summary_notes = generate_summary(source, blocks, model_choice)
     if not blocks:
-        return AnnotationResult(summary, source, "Parsed successfully. No classes or functions to annotate.", True, 0)
+        status = "Parsed successfully. No classes or functions to annotate."
+        if summary_notes:
+            status += "\n" + "\n".join(summary_notes)
+        return AnnotationResult(summary, source, status, True, 0, tuple(summary_notes))
 
     comments, generation_notes = generate_block_comments(blocks, model_choice)
+    generation_notes = summary_notes + generation_notes
     annotated = insert_comments(source, comments)
 
     try:

btl/model.py

@@ -2,7 +2,7 @@ import os
 from functools import lru_cache
 from typing import Literal
 
-from .prompts import build_comment_messages
+from .prompts import build_comment_messages, build_summary_messages
 
 
 DEFAULT_BASE_TRANSFORMERS_MODEL = "JetBrains/Mellum2-12B-A2.5B-Instruct"
@@ -66,6 +66,16 @@ def _clean_comment(text: str) -> str:
     return line[:240].rstrip()
 
 
+def _clean_summary(text: str) -> str:
+    cleaned = " ".join(line.strip().strip("`") for line in text.strip().splitlines() if line.strip())
+    if cleaned.startswith("Summary:"):
+        cleaned = cleaned.removeprefix("Summary:").strip()
+    cleaned = cleaned.strip('"').strip("'").strip()
+    if cleaned.startswith("#"):
+        cleaned = cleaned.lstrip("# ").strip()
+    return cleaned[:500].rstrip()
+
+
 @lru_cache(maxsize=1)
 def _load_tuned_model():
     adapter_path_or_repo = (
@@ -100,10 +110,39 @@ def generate_comment(kind: str, name: str, source: str, variant: ModelVariant =
     return generate_comment_with_base_model(kind, name, source)
 
 
-def _generate_with_transformers(tokenizer, model, kind: str, name: str, source: str, max_length_env: str) -> str:
+def generate_file_summary(source: str, variant: ModelVariant = "base") -> str:
+    if variant == "tuned":
+        tokenizer, model = _load_tuned_model()
+        return _generate_text_with_transformers(
+            tokenizer,
+            model,
+            build_summary_messages(source),
+            "BTL_TUNED_MODEL_CTX",
+            max_new_tokens=120,
+            cleaner=_clean_summary,
+        )
+
+    tokenizer, model = _load_base_model()
+    return _generate_text_with_transformers(
+        tokenizer,
+        model,
+        build_summary_messages(source),
+        "BTL_MODEL_CTX",
+        max_new_tokens=120,
+        cleaner=_clean_summary,
+    )
+
+
+def _generate_text_with_transformers(
+    tokenizer,
+    model,
+    messages: list[dict[str, str]],
+    max_length_env: str,
+    max_new_tokens: int,
+    cleaner,
+) -> str:
     import torch
 
-    messages = build_comment_messages(kind, name, source)
     prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
     encoded = tokenizer(
         prompt,
@@ -120,21 +159,32 @@ def _generate_with_transformers(tokenizer, model, kind: str, name: str, source:
         output_ids = model.generate(
             **encoded,
             do_sample=False,
-            max_new_tokens=80,
+            max_new_tokens=max_new_tokens,
             pad_token_id=tokenizer.pad_token_id,
             eos_token_id=tokenizer.eos_token_id,
         )[0]
 
     generated_ids = output_ids[encoded["input_ids"].shape[-1] :]
     text = tokenizer.decode(generated_ids, skip_special_tokens=True)
-    return _clean_comment(text)
+    return cleaner(text)
+
+
+def _generate_comment_with_transformers(tokenizer, model, kind: str, name: str, source: str, max_length_env: str) -> str:
+    return _generate_text_with_transformers(
+        tokenizer,
+        model,
+        build_comment_messages(kind, name, source),
+        max_length_env,
+        max_new_tokens=80,
+        cleaner=_clean_comment,
+    )
 
 
 def generate_comment_with_base_model(kind: str, name: str, source: str) -> str:
     tokenizer, model = _load_base_model()
-    return _generate_with_transformers(tokenizer, model, kind, name, source, "BTL_MODEL_CTX")
+    return _generate_comment_with_transformers(tokenizer, model, kind, name, source, "BTL_MODEL_CTX")
 
 
 def generate_comment_with_tuned_model(kind: str, name: str, source: str) -> str:
     tokenizer, model = _load_tuned_model()
-    return _generate_with_transformers(tokenizer, model, kind, name, source, "BTL_TUNED_MODEL_CTX")
+    return _generate_comment_with_transformers(tokenizer, model, kind, name, source, "BTL_TUNED_MODEL_CTX")

btl/prompts.py

@@ -11,6 +11,18 @@ Rules:
 """
 
 
+SUMMARY_SYSTEM_PROMPT = """You summarize Python files for developers.
+
+Rules:
+- Output one or two concise sentences.
+- Explain the file's overall purpose and main responsibilities.
+- Do not output Markdown.
+- Do not wrap the answer in quotes.
+- Do not suggest changes.
+- Do not mention ASTs, prompts, or the annotation tool.
+"""
+
+
 def build_comment_messages(kind: str, name: str, source: str) -> list[dict[str, str]]:
     return [
         {"role": "system", "content": COMMENT_SYSTEM_PROMPT},
@@ -24,3 +36,18 @@ def build_comment_messages(kind: str, name: str, source: str) -> list[dict[str,
             ),
         },
     ]
+
+
+def build_summary_messages(source: str) -> list[dict[str, str]]:
+    return [
+        {"role": "system", "content": SUMMARY_SYSTEM_PROMPT},
+        {
+            "role": "user",
+            "content": (
+                "Summarize this Python file for a developer who is about to read it.\n\n"
+                "Python file:\n"
+                f"```python\n{source.strip()}\n```\n\n"
+                "Summary:"
+            ),
+        },
+    ]