vibecheck-error-assistant-cli 0.1.0__tar.gz

vibecheck_error_assistant_cli-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: vibecheck-error-assistant-cli
+Version: 0.1.0
+Summary: Run commands and translate programming errors into beginner-friendly explanations
+Author: VibeCheck
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openai==2.30.0
+Requires-Dist: rich==14.3.3
+Requires-Dist: python-dotenv==1.2.2
+
+# VibeCheck CLI
+
+VibeCheck runs your command, catches failures, and translates technical stderr into beginner-friendly guidance.
+
+## Install (MVP)
+
+From project root:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+After install, you can use the `vibecheck` command directly.
+
+## Configure
+
+```bash
+cp .env.example .env
+# edit .env and set VIBECHECK_GITHUB_TOKEN
+```
+
+## Usage
+
+Single command mode:
+
+```bash
+vibecheck python buggy_sample.py
+```
+
+Interactive mode (tool waits in terminal):
+
+```bash
+vibecheck --shell
+```
+
+Then type commands like:
+
+```bash
+python buggy_sample.py
+node buggy_advanced.js
+```
+
+Exit interactive mode with `exit` or `quit`.
+
+## Useful Flags
+
+```bash
+vibecheck --level beginner python buggy_sample.py
+vibecheck --level advanced node buggy_advanced.js
+vibecheck --print-raw-error python buggy_sample.py
+```
+
+## Exit Codes
+
+- Returns `0` when wrapped command succeeds.
+- Returns wrapped command's non-zero exit code when command fails.
+- Returns `2` on configuration errors.

vibecheck_error_assistant_cli-0.1.0/README.md

@@ -0,0 +1,59 @@
+# VibeCheck CLI
+
+VibeCheck runs your command, catches failures, and translates technical stderr into beginner-friendly guidance.
+
+## Install (MVP)
+
+From project root:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+After install, you can use the `vibecheck` command directly.
+
+## Configure
+
+```bash
+cp .env.example .env
+# edit .env and set VIBECHECK_GITHUB_TOKEN
+```
+
+## Usage
+
+Single command mode:
+
+```bash
+vibecheck python buggy_sample.py
+```
+
+Interactive mode (tool waits in terminal):
+
+```bash
+vibecheck --shell
+```
+
+Then type commands like:
+
+```bash
+python buggy_sample.py
+node buggy_advanced.js
+```
+
+Exit interactive mode with `exit` or `quit`.
+
+## Useful Flags
+
+```bash
+vibecheck --level beginner python buggy_sample.py
+vibecheck --level advanced node buggy_advanced.js
+vibecheck --print-raw-error python buggy_sample.py
+```
+
+## Exit Codes
+
+- Returns `0` when wrapped command succeeds.
+- Returns wrapped command's non-zero exit code when command fails.
+- Returns `2` on configuration errors.

vibecheck_error_assistant_cli-0.1.0/main.py

@@ -0,0 +1,309 @@
+import argparse
+import os
+import re
+import shlex
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import Sequence
+
+from dotenv import load_dotenv
+from openai import OpenAI, RateLimitError
+from rich.console import Console
+from rich.live import Live
+from rich.markdown import Markdown
+from rich.panel import Panel
+from rich.spinner import Spinner
+
+
+console = Console()
+
+
+@dataclass(frozen=True)
+class Settings:
+    github_token: str
+    endpoint: str
+    model_tiers: list[str]
+    max_error_chars: int
+    ai_timeout_seconds: int
+
+
+DEFAULT_MODEL_TIERS = [
+    "gpt-4o-mini",
+    "gpt-4.1-mini",
+    "codestral-25.01",
+    "meta-llama-3.1-8b-instruct",
+    "phi-4",
+    "deepseek-r1-0528",
+    "o3-mini",
+]
+
+
+def load_settings() -> Settings:
+    load_dotenv()
+    token = os.getenv("VIBECHECK_GITHUB_TOKEN", "").strip()
+    endpoint = os.getenv("VIBECHECK_ENDPOINT", "https://models.inference.ai.azure.com").strip()
+
+    tiers_raw = os.getenv("VIBECHECK_MODELS", "")
+    model_tiers = [m.strip() for m in tiers_raw.split(",") if m.strip()] if tiers_raw else DEFAULT_MODEL_TIERS
+
+    max_error_chars = int(os.getenv("VIBECHECK_MAX_ERROR_CHARS", "5000"))
+    ai_timeout_seconds = int(os.getenv("VIBECHECK_AI_TIMEOUT_SECONDS", "45"))
+
+    return Settings(
+        github_token=token,
+        endpoint=endpoint,
+        model_tiers=model_tiers,
+        max_error_chars=max_error_chars,
+        ai_timeout_seconds=ai_timeout_seconds,
+    )
+
+
+def parse_args(argv: Sequence[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="vibecheck",
+        description="Run a command and translate failures into beginner-friendly guidance.",
+    )
+    parser.add_argument(
+        "--print-raw-error",
+        action="store_true",
+        help="Show raw stderr in addition to AI guidance.",
+    )
+    parser.add_argument(
+        "--level",
+        choices=["beginner", "intermediate", "advanced"],
+        default="beginner",
+        help="Explanation depth for the user. Default is beginner.",
+    )
+    parser.add_argument(
+        "--shell",
+        action="store_true",
+        help="Start interactive mode and run multiple commands in one session.",
+    )
+    parser.add_argument(
+        "command",
+        nargs="*",
+        help="Command to run. Example: vibecheck python buggy.py",
+    )
+    args, unknown = parser.parse_known_args(argv)
+    args.command = args.command + unknown
+    return args
+
+
+def normalize_command(command: Sequence[str]) -> list[str]:
+    normalized = list(command)
+    if normalized and normalized[0] == "--":
+        normalized = normalized[1:]
+    return normalized
+
+
+def run_target_command(command: Sequence[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(command, capture_output=True, text=True)
+
+
+def extract_line_hint(error_text: str) -> str:
+    line_matches = re.findall(r"line\s+(\d+)", error_text, flags=re.IGNORECASE)
+    if not line_matches:
+        return "No specific line found in traceback."
+    return f"Likely line mentioned by runtime: {line_matches[-1]}"
+
+
+def build_prompt(error_text: str, line_hint: str, level: str) -> str:
+    # 1. The Core Identity (The Role)
+    base_identity = (
+        "You are 'VibeGuard,' an elite coding mentor known for extreme patience and clarity. "
+        "Your goal is to turn a frustrating error into a 'lightbulb moment.' "
+        "Since your users may not be native English speakers, use 'Global English': "
+        "avoid slang, avoid complex metaphors, and use clear, literal instructions.\n\n"
+    )
+
+    level_rules = {
+        "beginner": (
+            "### ROLE: THE PATIENT EXPLORER\n"
+            "1. **Tone**: Warm, encouraging, and highly detailed. Use simple, high-frequency English words.\n"
+            "2. **The 'Why'**: Do not just fix the code. Explain the 'Logic of the Universe.' "
+            "If it is a TypeError, explain that Python is like a chef who was given a 'shoe' when they asked for an 'onion.'\n"
+            "3. **Vocabulary Breakdown**: Identify every technical word in the error (e.g., 'Attribute', 'Iteration', 'Literal') "
+            "and define it using a real-world object analogy.\n"
+            "4. **Step-by-Step Recovery**: Break the fix into 'Small Steps.' Step 1: Look here. Step 2: Change this. Step 3: Run again.\n"
+            "5. **Visual Representation**: Use simple ASCII art or spacing to show where the error is pointing."
+        ),
+        "intermediate": (
+            "### ROLE: THE EFFICIENT COACH\n"
+            "1. **Tone**: Professional and direct. Assume they know the basics (loops, variables) but missed a logic connection.\n"
+            "2. **Root Cause**: Explain the architectural reason for the error. Did they break a 'contract' of the function?\n"
+            "3. **Best Practices**: Briefly mention a 'cleaner' way to write this to avoid the error in the future.\n"
+            "4. **The Fix**: Provide the code block clearly."
+        ),
+        "advanced": (
+            "### ROLE: THE SENIOR ARCHITECT\n"
+            "1. **Tone**: Minimalist. Use technical shorthand.\n"
+            "2. **Insight**: Focus on memory, performance, or library-specific quirks.\n"
+            "3. **The Fix**: Provide a 'one-liner' or a diff format fix."
+        ),
+    }
+
+    # Constructing the Final Mega-Prompt
+    chosen_role = level_rules.get(level, level_rules["beginner"])
+
+    full_prompt = (
+        f"{base_identity}"
+        f"{chosen_role}\n\n"
+        f"--- THE TASK ---\n"
+        f"The user received this error message: '{error_text}'\n"
+        f"The error seems to be near: {line_hint}\n\n"
+        "Structure your response exactly like this:\n"
+        "1. **The Vibe Check**: A 1-sentence supportive opening.\n"
+        "2. **The Simple Translation**: Translate the computer-speak into 'Human-speak'.\n"
+        "3. **Word Bank**: Define technical terms found in the error.\n"
+        "4. **The Deep Dive**: Detailed explanation of the mistake.\n"
+        "5. **The Repair**: Clear code fix with comments.\n"
+        "6. **Pro-Tip**: How to never see this error again."
+    )
+
+    return full_prompt
+
+
+def ask_ai_for_explanation(client: OpenAI, settings: Settings, error_text: str, level: str) -> tuple[str, str]:
+    line_hint = extract_line_hint(error_text)
+    prompt = build_prompt(error_text, line_hint, level)
+
+    with Live(Spinner("dots", text="[bold yellow]Analyzing failure...[/bold yellow]"), refresh_per_second=12) as live:
+        for model_name in settings.model_tiers:
+            try:
+                live.update(Spinner("dots", text=f"[bold cyan]Trying {model_name}[/bold cyan]"))
+                response = client.chat.completions.create(
+                    model=model_name,
+                    temperature=0.1,
+                    timeout=settings.ai_timeout_seconds,
+                    messages=[
+                        {
+                            "role": "system",
+                            "content": "You explain programming errors clearly for beginners.",
+                        },
+                        {"role": "user", "content": prompt},
+                    ],
+                )
+                text = response.choices[0].message.content or "No explanation returned by model."
+                return text, model_name
+            except RateLimitError:
+                continue
+            except Exception:
+                continue
+
+    return "Unable to get an AI explanation right now. Please retry shortly.", "no-model"
+
+
+def display_vibe_panel(ai_text: str, model_used: str) -> None:
+    panel = Panel(
+        Markdown(ai_text),
+        title=f"[bold red]VibeCheck Report ({model_used})[/bold red]",
+        border_style="bright_magenta",
+        padding=(1, 2),
+    )
+    console.print()
+    console.print(panel)
+    console.print()
+
+
+def ensure_token(settings: Settings) -> None:
+    if settings.github_token:
+        return
+
+    console.print(
+        Panel(
+            "Missing VIBECHECK_GITHUB_TOKEN.\n"
+            "Create a .env file with:\n\n"
+            "VIBECHECK_GITHUB_TOKEN=your_token_here\n"
+            "VIBECHECK_ENDPOINT=https://models.inference.ai.azure.com",
+            title="Configuration Required",
+            border_style="red",
+        )
+    )
+    raise SystemExit(2)
+
+
+def run_with_vibecheck(command: Sequence[str], settings: Settings, level: str, print_raw_error: bool) -> int:
+    console.print(f"[bold green]Running:[/bold green] {' '.join(command)}")
+    proc = run_target_command(command)
+
+    if proc.stdout:
+        console.print(Panel(proc.stdout.rstrip(), title="Command stdout", border_style="green"))
+
+    if proc.returncode == 0:
+        console.print("[bold green]Command finished successfully. No errors to explain.[/bold green]")
+        return 0
+
+    error_text = (proc.stderr or "").strip() or f"Command failed with exit code {proc.returncode} and no stderr output."
+
+    if print_raw_error:
+        console.print(Panel(error_text, title="Raw stderr", border_style="yellow"))
+
+    ensure_token(settings)
+
+    trimmed_error = error_text[: settings.max_error_chars]
+    client = OpenAI(base_url=settings.endpoint, api_key=settings.github_token)
+    explanation, model_used = ask_ai_for_explanation(client, settings, trimmed_error, level)
+    display_vibe_panel(explanation, model_used)
+
+    return proc.returncode
+
+
+def run_interactive_shell(settings: Settings, level: str, print_raw_error: bool) -> int:
+    console.print("[bold cyan]VibeCheck shell mode started.[/bold cyan]")
+    console.print("Type a command and press Enter. Type 'exit' or 'quit' to stop.")
+
+    while True:
+        try:
+            raw = input("vibecheck> ").strip()
+        except EOFError:
+            console.print()
+            break
+        except KeyboardInterrupt:
+            console.print("\nInterrupted. Type 'exit' to quit cleanly.")
+            continue
+
+        if not raw:
+            continue
+
+        if raw in {"exit", "quit"}:
+            break
+
+        try:
+            command = shlex.split(raw)
+        except ValueError as exc:
+            console.print(f"[red]Invalid command syntax:[/red] {exc}")
+            continue
+
+        run_with_vibecheck(command, settings=settings, level=level, print_raw_error=print_raw_error)
+
+    console.print("[bold cyan]VibeCheck shell mode ended.[/bold cyan]")
+    return 0
+
+
+def main(argv: Sequence[str]) -> int:
+    args = parse_args(argv)
+    command = normalize_command(args.command)
+    settings = load_settings()
+
+    if args.shell or not command:
+        return run_interactive_shell(
+            settings=settings,
+            level=args.level,
+            print_raw_error=args.print_raw_error,
+        )
+
+    return run_with_vibecheck(
+        command,
+        settings=settings,
+        level=args.level,
+        print_raw_error=args.print_raw_error,
+    )
+
+
+def cli() -> None:
+    raise SystemExit(main(sys.argv[1:]))
+
+
+if __name__ == "__main__":
+    cli()

vibecheck_error_assistant_cli-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vibecheck-error-assistant-cli"
+version = "0.1.0"
+description = "Run commands and translate programming errors into beginner-friendly explanations"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "VibeCheck" }
+]
+dependencies = [
+  "openai==2.30.0",
+  "rich==14.3.3",
+  "python-dotenv==1.2.2"
+]
+
+[project.scripts]
+vibecheck = "main:cli"
+
+[tool.setuptools]
+py-modules = ["main"]

vibecheck_error_assistant_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vibecheck_error_assistant_cli-0.1.0/vibecheck_error_assistant_cli.egg-info/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: vibecheck-error-assistant-cli
+Version: 0.1.0
+Summary: Run commands and translate programming errors into beginner-friendly explanations
+Author: VibeCheck
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: openai==2.30.0
+Requires-Dist: rich==14.3.3
+Requires-Dist: python-dotenv==1.2.2
+
+# VibeCheck CLI
+
+VibeCheck runs your command, catches failures, and translates technical stderr into beginner-friendly guidance.
+
+## Install (MVP)
+
+From project root:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+After install, you can use the `vibecheck` command directly.
+
+## Configure
+
+```bash
+cp .env.example .env
+# edit .env and set VIBECHECK_GITHUB_TOKEN
+```
+
+## Usage
+
+Single command mode:
+
+```bash
+vibecheck python buggy_sample.py
+```
+
+Interactive mode (tool waits in terminal):
+
+```bash
+vibecheck --shell
+```
+
+Then type commands like:
+
+```bash
+python buggy_sample.py
+node buggy_advanced.js
+```
+
+Exit interactive mode with `exit` or `quit`.
+
+## Useful Flags
+
+```bash
+vibecheck --level beginner python buggy_sample.py
+vibecheck --level advanced node buggy_advanced.js
+vibecheck --print-raw-error python buggy_sample.py
+```
+
+## Exit Codes
+
+- Returns `0` when wrapped command succeeds.
+- Returns wrapped command's non-zero exit code when command fails.
+- Returns `2` on configuration errors.

vibecheck_error_assistant_cli-0.1.0/vibecheck_error_assistant_cli.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+main.py
+pyproject.toml
+vibecheck_error_assistant_cli.egg-info/PKG-INFO
+vibecheck_error_assistant_cli.egg-info/SOURCES.txt
+vibecheck_error_assistant_cli.egg-info/dependency_links.txt
+vibecheck_error_assistant_cli.egg-info/entry_points.txt
+vibecheck_error_assistant_cli.egg-info/requires.txt
+vibecheck_error_assistant_cli.egg-info/top_level.txt

vibecheck_error_assistant_cli-0.1.0/vibecheck_error_assistant_cli.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vibecheck_error_assistant_cli-0.1.0/vibecheck_error_assistant_cli.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+vibecheck = main:cli

vibecheck_error_assistant_cli-0.1.0/vibecheck_error_assistant_cli.egg-info/requires.txt

@@ -0,0 +1,3 @@
+openai==2.30.0
+rich==14.3.3
+python-dotenv==1.2.2

vibecheck_error_assistant_cli-0.1.0/vibecheck_error_assistant_cli.egg-info/top_level.txt

@@ -0,0 +1 @@
+main