Add hosted npm client

README.md

@@ -27,6 +27,29 @@ The app includes two modes:
 
 The model never edits code directly. It only proposes comments, and the app rejects any annotated file whose semantic AST changes.
 
+## CLI Usage
+
+Use the hosted Space from Node/npm without installing anything:
+
+```bash
+npx between-the-lines-cli path/to/file.py --model base --summary
+```
+
+By default, this creates an annotated sibling file next to the input:
+
+```text
+path/to/file.annotated.py
+```
+
+You can also choose an output path or replace the input file:
+
+```bash
+npx between-the-lines-cli path/to/file.py --model base --output annotated.py
+npx between-the-lines-cli path/to/file.py --model tuned --in-place
+```
+
+`--model base` uses the richer Mellum2 GGUF path. `--model tuned` uses the LoRA adapter for shorter comments. Both modes run the AST validation before writing output.
+
 ## Hackathon Fit
 
 - **Track:** Backyard AI

app.py

@@ -1,12 +1,11 @@
-import ast
 import html
-from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
 import gradio as gr
 
-from btl.model import ModelUnavailableError, generate_comment, generate_comment_with_llm, load_llm
+from btl.annotate import annotate_python, collect_blocks, parse_python
+from btl.model import ModelUnavailableError
 
 
 CSS = """
@@ -156,130 +155,18 @@ code {
 """
 
 
-@dataclass(frozen=True)
-class BlockInfo:
-    kind: str
-    name: str
-    lineno: int
-    source: str
-
-
-def _parse_python(source: str) -> ast.Module:
-    return ast.parse(source)
-
-
-def _strip_docstrings(node: ast.AST) -> ast.AST:
-    copied = ast.fix_missing_locations(ast.parse(ast.unparse(node)))
-    for child in ast.walk(copied):
-        if isinstance(child, (ast.Module, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
-            if (
-                child.body
-                and isinstance(child.body[0], ast.Expr)
-                and isinstance(child.body[0].value, ast.Constant)
-                and isinstance(child.body[0].value.value, str)
-            ):
-                child.body = child.body[1:]
-    return copied
-
-
-def _semantic_ast_dump(source: str) -> str:
-    tree = _parse_python(source)
-    stripped = _strip_docstrings(tree)
-    return ast.dump(stripped, include_attributes=False)
-
-
-def _collect_blocks(tree: ast.Module, source: str) -> list[BlockInfo]:
-    blocks: list[BlockInfo] = []
-    for node in ast.walk(tree):
-        if isinstance(node, ast.ClassDef):
-            block_source = ast.get_source_segment(source, node) or ast.unparse(node)
-            blocks.append(BlockInfo("class", node.name, node.lineno, block_source))
-        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            kind = "async function" if isinstance(node, ast.AsyncFunctionDef) else "function"
-            block_source = ast.get_source_segment(source, node) or ast.unparse(node)
-            blocks.append(BlockInfo(kind, node.name, node.lineno, block_source))
-    return sorted(blocks, key=lambda item: item.lineno)
-
-
-def _placeholder_summary(blocks: list[BlockInfo]) -> str:
-    if not blocks:
-        return "This Python file has no classes or functions to annotate yet."
-    names = ", ".join(f"{block.kind} `{block.name}`" for block in blocks[:8])
-    overflow = "" if len(blocks) <= 8 else f", plus {len(blocks) - 8} more"
-    return f"This file defines {names}{overflow}. Model-generated summaries will replace this deterministic placeholder."
-
-
-def _insert_comments(source: str, comments: dict[int, str]) -> str:
-    lines = source.splitlines()
-    inserts: dict[int, list[str]] = {}
-    for lineno, comment_text in comments.items():
-        indent = len(lines[lineno - 1]) - len(lines[lineno - 1].lstrip())
-        inserts.setdefault(lineno - 1, []).append(" " * indent + comment_text)
-
-    annotated: list[str] = []
-    for index, line in enumerate(lines):
-        annotated.extend(inserts.get(index, []))
-        annotated.append(line)
-    return "\n".join(annotated) + ("\n" if source.endswith("\n") else "")
-
-
 MODEL_LABELS = {
     "Base Mellum2 (richer)": "base",
     "Fine-tuned LoRA (concise)": "tuned",
 }
 
 
-def _generate_block_comments(blocks: list[BlockInfo], model_label: str) -> tuple[dict[int, str], list[str]]:
-    comments: dict[int, str] = {}
-    notes: list[str] = []
-    model_variant = MODEL_LABELS.get(model_label, "base")
-    llm = load_llm() if model_variant == "base" else None
-    for block in blocks:
-        try:
-            if model_variant == "base":
-                comments[block.lineno] = generate_comment_with_llm(llm, block.kind, block.name, block.source)
-            else:
-                comments[block.lineno] = generate_comment(block.kind, block.name, block.source, variant="tuned")
-        except Exception as exc:
-            comments[block.lineno] = f"# TODO(model): Could not explain {block.kind} `{block.name}`."
-            notes.append(f"{block.name}: model generation failed ({type(exc).__name__}).")
-    return comments, notes
-
-
 def annotate_code(source: str, model_label: str) -> tuple[str, str, str]:
-    source = source.strip("\ufeff")
-    if not source.strip():
-        return "", "", "Paste a Python file to annotate."
-
-    try:
-        original_tree = _parse_python(source)
-    except SyntaxError as exc:
-        return "", "", f"Syntax error on line {exc.lineno}: {html.escape(exc.msg)}"
-
-    blocks = _collect_blocks(original_tree, source)
-    if not blocks:
-        return _placeholder_summary(blocks), source, "Parsed successfully. No classes or functions to annotate."
-
     try:
-        comments, generation_notes = _generate_block_comments(blocks, model_label)
+        result = annotate_python(source, MODEL_LABELS.get(model_label, "base"))
     except ModelUnavailableError as exc:
-        return _placeholder_summary(blocks), source, f"Model unavailable: {html.escape(str(exc))}"
-
-    annotated = _insert_comments(source, comments)
-
-    try:
-        same_ast = _semantic_ast_dump(source) == _semantic_ast_dump(annotated)
-    except SyntaxError as exc:
-        return "", annotated, f"Generated annotation failed to parse on line {exc.lineno}: {html.escape(exc.msg)}"
-
-    status = (
-        f"Validated: parsed {len(blocks)} block(s), inserted {model_label} comments, semantic AST unchanged."
-        if same_ast
-        else "Rejected: annotation changed the semantic AST."
-    )
-    if generation_notes:
-        status += "\n" + "\n".join(generation_notes)
-    return _placeholder_summary(blocks), annotated if same_ast else source, status
+        return "", source, f"Model unavailable: {html.escape(str(exc))}"
+    return result.summary, result.annotated_source, result.status
 
 
 def load_uploaded_python(file_obj: Any) -> tuple[str, str]:
@@ -298,11 +185,11 @@ def load_uploaded_python(file_obj: Any) -> tuple[str, str]:
         return "", f"Could not read `{path.name}`: {exc}"
 
     try:
-        tree = _parse_python(source)
+        tree = parse_python(source)
     except SyntaxError as exc:
         return source, f"Loaded `{path.name}`, but parsing failed on line {exc.lineno}: {html.escape(exc.msg)}"
 
-    blocks = _collect_blocks(tree, source)
+    blocks = collect_blocks(tree, source)
     return source, f"Loaded `{path.name}`. Parsed {len(blocks)} class/function block(s)."
 
 
@@ -373,6 +260,7 @@ def build_app() -> gr.Blocks:
                 annotate_code,
                 inputs=[input_code, model_choice],
                 outputs=[summary, output_code, status],
+                api_name="annotate",
             )
             upload_file.upload(
                 load_uploaded_python,

btl/annotate.py

@@ -0,0 +1,152 @@
+import ast
+from dataclasses import dataclass
+from typing import Literal
+
+from .model import ModelUnavailableError, generate_comment, generate_comment_with_llm, load_llm
+
+
+ModelChoice = Literal["base", "tuned"]
+
+
+@dataclass(frozen=True)
+class BlockInfo:
+    kind: str
+    name: str
+    lineno: int
+    source: str
+
+
+@dataclass(frozen=True)
+class AnnotationResult:
+    summary: str
+    annotated_source: str
+    status: str
+    valid: bool
+    block_count: int
+    notes: tuple[str, ...] = ()
+
+
+def parse_python(source: str) -> ast.Module:
+    return ast.parse(source)
+
+
+def strip_docstrings(node: ast.AST) -> ast.AST:
+    copied = ast.fix_missing_locations(ast.parse(ast.unparse(node)))
+    for child in ast.walk(copied):
+        if isinstance(child, (ast.Module, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            if (
+                child.body
+                and isinstance(child.body[0], ast.Expr)
+                and isinstance(child.body[0].value, ast.Constant)
+                and isinstance(child.body[0].value.value, str)
+            ):
+                child.body = child.body[1:]
+    return copied
+
+
+def semantic_ast_dump(source: str) -> str:
+    tree = parse_python(source)
+    stripped = strip_docstrings(tree)
+    return ast.dump(stripped, include_attributes=False)
+
+
+def collect_blocks(tree: ast.Module, source: str) -> list[BlockInfo]:
+    blocks: list[BlockInfo] = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            block_source = ast.get_source_segment(source, node) or ast.unparse(node)
+            blocks.append(BlockInfo("class", node.name, node.lineno, block_source))
+        elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            kind = "async function" if isinstance(node, ast.AsyncFunctionDef) else "function"
+            block_source = ast.get_source_segment(source, node) or ast.unparse(node)
+            blocks.append(BlockInfo(kind, node.name, node.lineno, block_source))
+    return sorted(blocks, key=lambda item: item.lineno)
+
+
+def summarize_blocks(blocks: list[BlockInfo]) -> str:
+    if not blocks:
+        return "This Python file has no classes or functions to annotate yet."
+    names = ", ".join(f"{block.kind} `{block.name}`" for block in blocks[:8])
+    overflow = "" if len(blocks) <= 8 else f", plus {len(blocks) - 8} more"
+    return f"This file defines {names}{overflow}."
+
+
+def insert_comments(source: str, comments: dict[int, str]) -> str:
+    lines = source.splitlines()
+    inserts: dict[int, list[str]] = {}
+    for lineno, comment_text in comments.items():
+        indent = len(lines[lineno - 1]) - len(lines[lineno - 1].lstrip())
+        inserts.setdefault(lineno - 1, []).append(" " * indent + comment_text)
+
+    annotated: list[str] = []
+    for index, line in enumerate(lines):
+        annotated.extend(inserts.get(index, []))
+        annotated.append(line)
+    return "\n".join(annotated) + ("\n" if source.endswith("\n") else "")
+
+
+def generate_block_comments(blocks: list[BlockInfo], model_choice: ModelChoice = "base") -> tuple[dict[int, str], list[str]]:
+    comments: dict[int, str] = {}
+    notes: list[str] = []
+    llm = load_llm() if model_choice == "base" else None
+
+    for block in blocks:
+        try:
+            if model_choice == "base":
+                comments[block.lineno] = generate_comment_with_llm(llm, block.kind, block.name, block.source)
+            else:
+                comments[block.lineno] = generate_comment(block.kind, block.name, block.source, variant="tuned")
+        except ModelUnavailableError:
+            raise
+        except Exception as exc:
+            comments[block.lineno] = f"# TODO(model): Could not explain {block.kind} `{block.name}`."
+            notes.append(f"{block.name}: model generation failed ({type(exc).__name__}).")
+    return comments, notes
+
+
+def annotate_python(source: str, model_choice: ModelChoice = "base") -> AnnotationResult:
+    source = source.strip("\ufeff")
+    if not source.strip():
+        return AnnotationResult("", "", "Paste a Python file to annotate.", False, 0)
+
+    try:
+        original_tree = parse_python(source)
+    except SyntaxError as exc:
+        return AnnotationResult("", "", f"Syntax error on line {exc.lineno}: {exc.msg}", False, 0)
+
+    blocks = collect_blocks(original_tree, source)
+    summary = summarize_blocks(blocks)
+    if not blocks:
+        return AnnotationResult(summary, source, "Parsed successfully. No classes or functions to annotate.", True, 0)
+
+    comments, generation_notes = generate_block_comments(blocks, model_choice)
+    annotated = insert_comments(source, comments)
+
+    try:
+        same_ast = semantic_ast_dump(source) == semantic_ast_dump(annotated)
+    except SyntaxError as exc:
+        return AnnotationResult(
+            "",
+            annotated,
+            f"Generated annotation failed to parse on line {exc.lineno}: {exc.msg}",
+            False,
+            len(blocks),
+            tuple(generation_notes),
+        )
+
+    status = (
+        f"Validated: parsed {len(blocks)} block(s), inserted {model_choice} model comments, semantic AST unchanged."
+        if same_ast
+        else "Rejected: annotation changed the semantic AST."
+    )
+    if generation_notes:
+        status += "\n" + "\n".join(generation_notes)
+
+    return AnnotationResult(
+        summary,
+        annotated if same_ast else source,
+        status,
+        same_ast,
+        len(blocks),
+        tuple(generation_notes),
+    )

packages/npm/README.md

@@ -0,0 +1,41 @@
+# between-the-lines-cli
+
+Hosted CLI client for [between-the-lines](https://huggingface.co/spaces/build-small-hackathon/between-the-lines).
+
+Run without installing:
+
+```bash
+npx between-the-lines-cli path/to/file.py --model base --summary
+```
+
+By default, the CLI creates a sibling file next to the input:
+
+```text
+path/to/file.annotated.py
+```
+
+Install globally if you prefer a reusable command:
+
+```bash
+npm install -g between-the-lines-cli
+between-the-lines path/to/file.py --model base
+```
+
+Choose an exact output path or replace the input file:
+
+```bash
+npx between-the-lines-cli path/to/file.py --model base --output annotated.py
+npx between-the-lines-cli path/to/file.py --model tuned --in-place
+```
+
+The CLI sends the file contents to the hosted Hugging Face Space and writes back the AST-validated annotated code.
+
+## Options
+
+```text
+--model base|tuned       Comment model to use. Default: base
+--output <file.py>       Write annotated code to a specific file
+--in-place               Replace the input file after validation
+--summary                Print summary and validation status to stderr
+--space <repo-id|url>    Override the hosted Gradio Space
+```

packages/npm/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "between-the-lines-cli",
+  "version": "0.1.0",
+  "description": "CLI client for the hosted between-the-lines Python annotator.",
+  "type": "module",
+  "bin": {
+    "between-the-lines": "./src/cli.js",
+    "btl": "./src/cli.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@gradio/client": "^1.15.0"
+  },
+  "keywords": [
+    "huggingface",
+    "gradio",
+    "python",
+    "ast",
+    "code-comments",
+    "cli"
+  ],
+  "license": "MIT"
+}

packages/npm/src/cli.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+
+const DEFAULT_SPACE = "build-small-hackathon/between-the-lines";
+const MODEL_LABELS = {
+  base: "Base Mellum2 (richer)",
+  tuned: "Fine-tuned LoRA (concise)"
+};
+
+function usage() {
+  return `between-the-lines <file.py> [options]
+
+Options:
+  --model base|tuned       Comment model to use. Default: base
+  --output <file.py>       Write annotated code to a specific file
+  --in-place               Replace the input file after validation
+  --summary                Print summary and validation status to stderr
+  --space <repo-id|url>    Hosted Gradio Space. Default: ${DEFAULT_SPACE}
+  -h, --help               Show this help
+`;
+}
+
+function parseArgs(argv) {
+  const args = {
+    input: "",
+    model: "base",
+    output: "",
+    inPlace: false,
+    summary: false,
+    space: DEFAULT_SPACE
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "-h" || arg === "--help") {
+      args.help = true;
+    } else if (arg === "--model") {
+      args.model = argv[++index] ?? "";
+    } else if (arg === "--output" || arg === "-o") {
+      args.output = argv[++index] ?? "";
+    } else if (arg === "--in-place") {
+      args.inPlace = true;
+    } else if (arg === "--summary") {
+      args.summary = true;
+    } else if (arg === "--space") {
+      args.space = argv[++index] ?? "";
+    } else if (!args.input) {
+      args.input = arg;
+    } else {
+      throw new Error(`unexpected argument: ${arg}`);
+    }
+  }
+
+  if (args.help) {
+    return args;
+  }
+  if (!args.input) {
+    throw new Error("missing input file");
+  }
+  if (!Object.hasOwn(MODEL_LABELS, args.model)) {
+    throw new Error("--model must be 'base' or 'tuned'");
+  }
+  if (args.output && args.inPlace) {
+    throw new Error("use either --output or --in-place, not both");
+  }
+  return args;
+}
+
+function defaultOutputPath(inputPath) {
+  const parsed = path.parse(inputPath);
+  return path.join(parsed.dir, `${parsed.name}.annotated${parsed.ext || ".py"}`);
+}
+
+async function predict(client, source, modelLabel) {
+  try {
+    return await client.predict("/annotate", [source, modelLabel]);
+  } catch (arrayError) {
+    try {
+      return await client.predict("/annotate", {
+        source,
+        model_label: modelLabel
+      });
+    } catch {
+      throw arrayError;
+    }
+  }
+}
+
+async function main() {
+  let args;
+  try {
+    args = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    console.error(`error: ${error.message}\n`);
+    console.error(usage());
+    return 2;
+  }
+
+  if (args.help) {
+    console.log(usage());
+    return 0;
+  }
+
+  const source = await readFile(args.input, "utf8");
+  const { Client } = await import("@gradio/client");
+  const client = await Client.connect(args.space);
+  const result = await predict(client, source, MODEL_LABELS[args.model]);
+  const [summary, annotated, status] = result.data;
+
+  if (args.summary) {
+    if (summary) {
+      console.error(summary);
+    }
+    console.error(status);
+  }
+
+  if (!String(status).startsWith("Validated:") && !String(status).startsWith("Parsed successfully.")) {
+    console.error(status);
+    return 1;
+  }
+
+  if (args.inPlace) {
+    await writeFile(args.input, annotated, "utf8");
+  } else if (args.output) {
+    await writeFile(args.output, annotated, "utf8");
+  } else {
+    const outputPath = defaultOutputPath(args.input);
+    await writeFile(outputPath, annotated, "utf8");
+    console.error(`Wrote ${outputPath}`);
+  }
+  return 0;
+}
+
+main()
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((error) => {
+    console.error(`error: ${error.message}`);
+    process.exitCode = 1;
+  });

pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "between-the-lines"
+version = "0.1.0"
+description = "Annotate Python files with small-model comments and AST validation."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "accelerate",
+    "bitsandbytes",
+    "gradio==5.50.0",
+    "huggingface_hub",
+    "llama-cpp-python",
+    "peft",
+    "safetensors",
+    "torch",
+    "transformers @ git+https://github.com/huggingface/transformers.git",
+    "truststore",
+]
+
+[tool.setuptools.packages.find]
+include = ["btl*"]