feat: add interactive llm consent and key prompt options

Author: baboonzero

README.md

@@ -146,6 +146,8 @@ python scripts/analyze.py analyze \
   --audience nontech \
   --overview-length medium \
   --enable-llm-descriptions true \
+  --ask-before-llm-use false \
+  --prompt-for-llm-key false \
   --enable-web-enrichment true
 ```
 
@@ -158,6 +160,9 @@ For LLM-based narrative summaries:
 
 - Set `CODE_EXPLAINER_LLM_API_KEY` (or `OPENAI_API_KEY`)
 - Optional: `CODE_EXPLAINER_LLM_BASE_URL`, `CODE_EXPLAINER_LLM_MODEL`
+- Optional interactive controls:
+- `--ask-before-llm-use true` (prompt for permission)
+- `--prompt-for-llm-key true` (securely prompt for key when missing)
 
 ## Install From GitHub (For Other Developers)
 

code-explainer/SKILL.md

@@ -38,6 +38,8 @@ python scripts/analyze.py analyze \
   --include-glob <pattern> \
   --exclude-glob <pattern> \
   --enable-llm-descriptions <true|false> \
+  --ask-before-llm-use <true|false> \
+  --prompt-for-llm-key <true|false> \
   --enable-web-enrichment <true|false>
 ```
 
@@ -47,6 +49,8 @@ Defaults:
 - `audience=nontech`
 - `overview-length=medium`
 - `enable-llm-descriptions=true`
+- `ask-before-llm-use=false`
+- `prompt-for-llm-key=false`
 - `enable-web-enrichment=true`
 
 ## Dependencies
@@ -94,6 +98,9 @@ bash ./scripts/install_runtime.sh
 - Without `mmdc`, fallback rendering is used and flagged in reports.
 - For LLM narrative summaries, set `CODE_EXPLAINER_LLM_API_KEY` (or `OPENAI_API_KEY`).
 - Optional: set `CODE_EXPLAINER_LLM_BASE_URL` and `CODE_EXPLAINER_LLM_MODEL`.
+- If you want interactive control, enable:
+- `--ask-before-llm-use true`
+- `--prompt-for-llm-key true`
 - This skill does not mutate the analyzed target repository.
 
 ## Dependency Troubleshooting

code-explainer/references/mode-behavior.md

@@ -43,6 +43,9 @@ Goal: Maximum fidelity and audit-ready onboarding.
 ## LLM Narrative
 
 - Controlled with `--enable-llm-descriptions <true|false>`.
+- Optional interactive controls:
+- `--ask-before-llm-use true`
+- `--prompt-for-llm-key true`
 - Reads API config from env vars:
 - `CODE_EXPLAINER_LLM_API_KEY` (or `OPENAI_API_KEY`)
 - `CODE_EXPLAINER_LLM_BASE_URL` (optional)

code-explainer/references/output-contract.md

@@ -72,6 +72,8 @@
 - `generated_at`
 - `enabled`
 - `used`
+- `asked_before_use`
+- `prompted_for_key`
 - `provider`
 - `model`
 - `repo_summary_paragraph`

code-explainer/scripts/analyze.py

@@ -124,6 +124,8 @@ def run_pipeline(
     overview_length: str,
     enable_web_enrichment: bool,
     enable_llm_descriptions: bool,
+    ask_before_llm_use: bool = False,
+    prompt_for_llm_key: bool = False,
     include_globs: List[str] | None = None,
     exclude_globs: List[str] | None = None,
 ) -> Dict[str, Any]:
@@ -164,6 +166,8 @@ def run_pipeline(
             docs_payload=coverage_payload,
             out_dir=meta_dir,
             enabled=enable_llm_descriptions,
+            ask_before_use=ask_before_llm_use,
+            prompt_for_key=prompt_for_llm_key,
         )
 
         diagram_manifest = build_diagrams.build_diagrams(
@@ -259,6 +263,8 @@ def _parse_args() -> argparse.Namespace:
     )
     parser.add_argument("--enable-web-enrichment", default="true")
     parser.add_argument("--enable-llm-descriptions", default="true")
+    parser.add_argument("--ask-before-llm-use", default="false")
+    parser.add_argument("--prompt-for-llm-key", default="false")
     return parser.parse_args()
 
 
@@ -271,6 +277,8 @@ def main() -> int:
     mode = common.normalize_mode(args.mode)
     web_enabled = common.bool_from_string(args.enable_web_enrichment)
     llm_enabled = common.bool_from_string(args.enable_llm_descriptions)
+    ask_before_llm_use = common.bool_from_string(args.ask_before_llm_use)
+    prompt_for_llm_key = common.bool_from_string(args.prompt_for_llm_key)
     summary = run_pipeline(
         source=args.source,
         output_root=Path(args.output).resolve(),
@@ -279,6 +287,8 @@ def main() -> int:
         overview_length=args.overview_length,
         enable_web_enrichment=web_enabled,
         enable_llm_descriptions=llm_enabled,
+        ask_before_llm_use=ask_before_llm_use,
+        prompt_for_llm_key=prompt_for_llm_key,
         include_globs=args.include_glob,
         exclude_globs=args.exclude_glob,
     )

code-explainer/scripts/llm_describe.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import argparse
+import getpass
 import json
 import os
 import re
@@ -27,6 +28,25 @@ def _normalize_base_url(url: str) -> str:
     return clean or DEFAULT_BASE_URL
 
 
+def _is_interactive_terminal() -> bool:
+    try:
+        return bool(sys.stdin.isatty() and sys.stdout.isatty())
+    except Exception:
+        return False
+
+
+def _confirm_llm_usage() -> bool:
+    answer = input("Use LLM to generate narrative summaries for this run? [y/N]: ").strip().lower()
+    return answer in {"y", "yes"}
+
+
+def _prompt_api_key() -> str:
+    try:
+        return getpass.getpass("Enter LLM API key (input hidden): ").strip()
+    except Exception:
+        return ""
+
+
 def _post_json(url: str, api_key: str, payload: Dict[str, Any], timeout: int = 90) -> Tuple[int, str]:
     data = json.dumps(payload).encode("utf-8")
     req = urllib.request.Request(
@@ -161,6 +181,8 @@ def _default_llm_payload(enabled: bool, model: str) -> Dict[str, Any]:
         "generated_at": common.now_iso(),
         "enabled": enabled,
         "used": False,
+        "asked_before_use": False,
+        "prompted_for_key": False,
         "provider": "openai_compatible",
         "model": model,
         "repo_summary_paragraph": "",
@@ -184,17 +206,41 @@ def generate_llm_descriptions(
     docs_payload: Dict[str, Any],
     out_dir: Path,
     enabled: bool = True,
+    ask_before_use: bool = False,
+    prompt_for_key: bool = False,
 ) -> Dict[str, Any]:
     model = os.environ.get("CODE_EXPLAINER_LLM_MODEL", DEFAULT_MODEL).strip() or DEFAULT_MODEL
     payload = _default_llm_payload(enabled=enabled, model=model)
     if not enabled:
         common.write_json(out_dir / "llm_summary.json", payload)
         return payload
 
+    interactive = _is_interactive_terminal()
+    if ask_before_use:
+        payload["asked_before_use"] = True
+        if not interactive:
+            payload["enabled"] = False
+            payload["error"] = "LLM ask-before-use requested but terminal is non-interactive; skipped."
+            common.write_json(out_dir / "llm_summary.json", payload)
+            return payload
+        if not _confirm_llm_usage():
+            payload["enabled"] = False
+            payload["error"] = "User declined LLM narrative generation for this run."
+            common.write_json(out_dir / "llm_summary.json", payload)
+            return payload
+
     api_key = (
         os.environ.get("CODE_EXPLAINER_LLM_API_KEY", "").strip()
         or os.environ.get("OPENAI_API_KEY", "").strip()
     )
+    if not api_key and prompt_for_key:
+        payload["prompted_for_key"] = True
+        if not interactive:
+            payload["error"] = "Prompt-for-key requested but terminal is non-interactive and no key was found."
+            common.write_json(out_dir / "llm_summary.json", payload)
+            return payload
+        api_key = _prompt_api_key()
+
     if not api_key:
         payload["error"] = "No API key found (set CODE_EXPLAINER_LLM_API_KEY or OPENAI_API_KEY)."
         common.write_json(out_dir / "llm_summary.json", payload)
@@ -286,6 +332,8 @@ def main() -> int:
     parser.add_argument("--coverage", required=True)
     parser.add_argument("--output", required=True)
     parser.add_argument("--enabled", default="true")
+    parser.add_argument("--ask-before-use", default="false")
+    parser.add_argument("--prompt-for-key", default="false")
     args = parser.parse_args()
 
     payload = generate_llm_descriptions(
@@ -301,6 +349,8 @@ def main() -> int:
         docs_payload=common.read_json(Path(args.coverage), default={}),
         out_dir=Path(args.output).resolve(),
         enabled=common.bool_from_string(args.enabled),
+        ask_before_use=common.bool_from_string(args.ask_before_use),
+        prompt_for_key=common.bool_from_string(args.prompt_for_key),
     )
     print(json.dumps({"used": payload.get("used", False), "error": payload.get("error", "")}, indent=2))
     return 0