sherpa-dev 0.1.1__tar.gz

sherpa_dev-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RishiiGamer2201
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sherpa_dev-0.1.1/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: sherpa-dev
+Version: 0.1.1
+Summary: Explains your terminal errors in plain English. Fully local, no API key.
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# 🏔️ Sherpa
+
+**Explains your terminal errors in plain English. Fully local, no API key.**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/sherpa-dev.svg)](https://pypi.org/project/sherpa-dev/)
+
+</div>
+
+---
+
+![Sherpa Demo](assets/demo.gif)
+
+```
+$ python app.py
+TypeError: unsupported operand type(s) for +: 'int' and 'str'  [line 42]
+
+$ sherpa
+
+sherpa is thinking...
+
+╭─ Why it failed ──────────────────────────────────────────────╮
+│ You're trying to add an integer and a string at line 42.     │
+│ Python requires both sides of + to be the same type —        │
+│ it won't auto-convert like JavaScript does.                  │
+╰──────────────────────────────────────────────────────────────╯
+╭─ Fix ────────────────────────────────────────────────────────╮
+│ total + int(user_input)                                      │
+╰──────────────────────────────────────────────────────────────╯
+```
+
+## Install
+
+```bash
+pip install sherpa-dev
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/RishiiGamer2201/sherpa
+cd sherpa
+pip install -e .
+```
+
+## First Run
+
+```bash
+sherpa
+```
+
+On first run, Sherpa will prompt you to download a local AI model (~4GB). After that, **everything runs offline** — no internet, no API key, no external server. Ever.
+
+## Usage
+
+```bash
+# Explain last terminal error (default)
+sherpa
+
+# Explain a specific line in a file
+sherpa explain app.py:42
+
+# Ask a freeform question
+sherpa ask why is my API returning 403 only in production
+
+# Show current config
+sherpa cfg show
+
+# Switch to a different model
+sherpa cfg set-model /path/to/custom-model.gguf
+```
+
+## Why Sherpa?
+
+Every developer hits errors in their terminal every day. The usual workflow:
+
+1. Read the error → feel confused
+2. Copy the error → open browser → Google/ChatGPT → read results → come back
+
+That's a context switch. You leave your flow, lose your mental state, and waste 3–5 minutes on something that should take 5 seconds.
+
+**Sherpa eliminates that loop.** The explanation and fix come to you, right where the error happened.
+
+> 🔒 **Your code never leaves your machine.** Sherpa runs entirely locally using a quantized AI model. No data is sent anywhere. Ever.
+
+## How It Works
+
+```
+sherpa (you type this)
+  │
+  ├─ config.py    → checks if model exists
+  ├─ setup.py     → downloads model on first run
+  ├─ history.py   → reads last command + stderr from shell history
+  ├─ ai.py        → loads local model, runs inference
+  └─ display.py   → prints explanation + fix with rich styling
+```
+
+| Component | Library | Why |
+|---|---|---|
+| CLI | `click` | Clean command routing, auto help text |
+| Output | `rich` | Colors, panels, syntax highlighting, progress bars |
+| AI | `llama-cpp-python` | Runs `.gguf` models inline, no server needed |
+| Model | CodeLlama 7B Q4 | Code-optimized, ~4GB, runs on CPU with 8GB RAM |
+
+### Supported Models
+
+| Model | Size | Best for |
+|---|---|---|
+| `codellama-7b-instruct.Q4_K_M.gguf` | 4GB | Default — code-specific, fast |
+| `deepseek-coder-6.7b.Q4_K_M.gguf` | 4GB | Slightly better on debug tasks |
+| `mistral-7b-instruct.Q4_K_M.gguf` | 4GB | Good general fallback |
+| `gemma-2b-it.Q4_K_M.gguf` | 1.6GB | Low RAM machines (4GB or less) |
+| `llama3.2-3b-instruct.Q4_K_M.gguf` | 2GB | Fast, decent quality, mid-range |
+
+Switch models anytime:
+
+```bash
+sherpa cfg set-model /path/to/model.gguf
+```
+
+## Comparison
+
+| Tool | Leaves Terminal? | Explains Why? | Works Offline? | Needs API Key? |
+|---|---|---|---|---|
+| **Sherpa** | ❌ No | ✅ Yes | ✅ Yes | ❌ No |
+| Stack Overflow | ✅ Yes | Sometimes | ❌ No | — |
+| ChatGPT / Claude | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
+| GitHub Copilot | N/A (IDE) | ✅ Yes | ❌ No | ✅ Yes |
+| `thefuck` | ❌ No | ❌ No | ✅ Yes | ❌ No |
+
+## Supported Shells
+
+- ✅ Bash
+- ✅ Zsh
+- ✅ Fish
+
+## Requirements
+
+- Python 3.10+
+- 8GB RAM (for default 7B model)
+- ~4GB disk space for the model
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for open tasks and guidelines.
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+<div align="center">
+
+*Built with Python and llama-cpp-python. Fully local. Your code never leaves your machine.*
+
+</div>

sherpa_dev-0.1.1/README.md

@@ -0,0 +1,160 @@
+<div align="center">
+
+# 🏔️ Sherpa
+
+**Explains your terminal errors in plain English. Fully local, no API key.**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/sherpa-dev.svg)](https://pypi.org/project/sherpa-dev/)
+
+</div>
+
+---
+
+![Sherpa Demo](assets/demo.gif)
+
+```
+$ python app.py
+TypeError: unsupported operand type(s) for +: 'int' and 'str'  [line 42]
+
+$ sherpa
+
+sherpa is thinking...
+
+╭─ Why it failed ──────────────────────────────────────────────╮
+│ You're trying to add an integer and a string at line 42.     │
+│ Python requires both sides of + to be the same type —        │
+│ it won't auto-convert like JavaScript does.                  │
+╰──────────────────────────────────────────────────────────────╯
+╭─ Fix ────────────────────────────────────────────────────────╮
+│ total + int(user_input)                                      │
+╰──────────────────────────────────────────────────────────────╯
+```
+
+## Install
+
+```bash
+pip install sherpa-dev
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/RishiiGamer2201/sherpa
+cd sherpa
+pip install -e .
+```
+
+## First Run
+
+```bash
+sherpa
+```
+
+On first run, Sherpa will prompt you to download a local AI model (~4GB). After that, **everything runs offline** — no internet, no API key, no external server. Ever.
+
+## Usage
+
+```bash
+# Explain last terminal error (default)
+sherpa
+
+# Explain a specific line in a file
+sherpa explain app.py:42
+
+# Ask a freeform question
+sherpa ask why is my API returning 403 only in production
+
+# Show current config
+sherpa cfg show
+
+# Switch to a different model
+sherpa cfg set-model /path/to/custom-model.gguf
+```
+
+## Why Sherpa?
+
+Every developer hits errors in their terminal every day. The usual workflow:
+
+1. Read the error → feel confused
+2. Copy the error → open browser → Google/ChatGPT → read results → come back
+
+That's a context switch. You leave your flow, lose your mental state, and waste 3–5 minutes on something that should take 5 seconds.
+
+**Sherpa eliminates that loop.** The explanation and fix come to you, right where the error happened.
+
+> 🔒 **Your code never leaves your machine.** Sherpa runs entirely locally using a quantized AI model. No data is sent anywhere. Ever.
+
+## How It Works
+
+```
+sherpa (you type this)
+  │
+  ├─ config.py    → checks if model exists
+  ├─ setup.py     → downloads model on first run
+  ├─ history.py   → reads last command + stderr from shell history
+  ├─ ai.py        → loads local model, runs inference
+  └─ display.py   → prints explanation + fix with rich styling
+```
+
+| Component | Library | Why |
+|---|---|---|
+| CLI | `click` | Clean command routing, auto help text |
+| Output | `rich` | Colors, panels, syntax highlighting, progress bars |
+| AI | `llama-cpp-python` | Runs `.gguf` models inline, no server needed |
+| Model | CodeLlama 7B Q4 | Code-optimized, ~4GB, runs on CPU with 8GB RAM |
+
+### Supported Models
+
+| Model | Size | Best for |
+|---|---|---|
+| `codellama-7b-instruct.Q4_K_M.gguf` | 4GB | Default — code-specific, fast |
+| `deepseek-coder-6.7b.Q4_K_M.gguf` | 4GB | Slightly better on debug tasks |
+| `mistral-7b-instruct.Q4_K_M.gguf` | 4GB | Good general fallback |
+| `gemma-2b-it.Q4_K_M.gguf` | 1.6GB | Low RAM machines (4GB or less) |
+| `llama3.2-3b-instruct.Q4_K_M.gguf` | 2GB | Fast, decent quality, mid-range |
+
+Switch models anytime:
+
+```bash
+sherpa cfg set-model /path/to/model.gguf
+```
+
+## Comparison
+
+| Tool | Leaves Terminal? | Explains Why? | Works Offline? | Needs API Key? |
+|---|---|---|---|---|
+| **Sherpa** | ❌ No | ✅ Yes | ✅ Yes | ❌ No |
+| Stack Overflow | ✅ Yes | Sometimes | ❌ No | — |
+| ChatGPT / Claude | ✅ Yes | ✅ Yes | ❌ No | ✅ Yes |
+| GitHub Copilot | N/A (IDE) | ✅ Yes | ❌ No | ✅ Yes |
+| `thefuck` | ❌ No | ❌ No | ✅ Yes | ❌ No |
+
+## Supported Shells
+
+- ✅ Bash
+- ✅ Zsh
+- ✅ Fish
+
+## Requirements
+
+- Python 3.10+
+- 8GB RAM (for default 7B model)
+- ~4GB disk space for the model
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for open tasks and guidelines.
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+<div align="center">
+
+*Built with Python and llama-cpp-python. Fully local. Your code never leaves your machine.*
+
+</div>

sherpa_dev-0.1.1/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=77.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sherpa-dev"
+version = "0.1.1"
+description = "Explains your terminal errors in plain English. Fully local, no API key."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+dependencies = [
+    "click>=8.1",
+    "rich>=13.0",
+]
+
+[project.scripts]
+sherpa = "sherpa.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+]
+
+[tool.setuptools.packages.find]
+include = ["sherpa*"]

sherpa_dev-0.1.1/setup.cfg

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

sherpa_dev-0.1.1/sherpa/__init__.py

@@ -0,0 +1 @@
+# intentionally empty

sherpa_dev-0.1.1/sherpa/__main__.py

@@ -0,0 +1,10 @@
+"""
+Allows Sherpa to be run as a module: python -m sherpa
+Useful as a reliable fallback on Windows when the sherpa.exe
+entry point has sys.argv issues with editable installs.
+"""
+
+from sherpa.cli import main
+
+if __name__ == "__main__":
+    main()

sherpa_dev-0.1.1/sherpa/ai.py

@@ -0,0 +1,112 @@
+"""
+The AI engine. Loads the GGUF model once via llama-cpp-python and
+caches it for the lifetime of the process. Sends structured prompts
+to the model and parses responses into {"reason": ..., "fix": ...} dicts.
+"""
+
+from sherpa.config import load
+
+_llm = None  # loaded once, reused across calls
+
+
+def _get_model():
+    """Load the model on first call, reuse on subsequent calls."""
+    global _llm
+    if _llm is None:
+        from llama_cpp import Llama  # lazy import — only needed at runtime
+        cfg = load()
+        _llm = Llama(
+            model_path=cfg["model_path"],
+            n_ctx=cfg["n_ctx"],
+            verbose=cfg["verbose"],
+        )
+    return _llm
+
+
+SYSTEM_PROMPT = """\
+You are a senior developer assistant embedded in a terminal.
+When given a shell command and its error output, you:
+1. Explain in 2-3 plain English sentences WHY the error happened.
+2. Give ONE exact, copy-pasteable fix.
+3. Never give walls of text. Be direct and specific.
+Format your response exactly like this:
+REASON: <why it failed>
+FIX: <exact code or command fix>
+"""
+
+
+def explain(command: str, stderr: str) -> dict:
+    """Explain a terminal error from a command and its stderr."""
+    llm = _get_model()
+    prompt = f"""{SYSTEM_PROMPT}
+
+Command: {command}
+Error:
+{stderr}
+
+Response:"""
+
+    output = llm(
+        prompt,
+        max_tokens=load()["max_tokens"],
+        stop=["Command:", "Error:", "\n\n\n"],
+        echo=False,
+    )
+
+    raw = output["choices"][0]["text"].strip()
+    return _parse(raw)
+
+
+def explain_line(filepath: str, line_number: int) -> dict:
+    """Explain a specific line of code in a file."""
+    try:
+        lines   = open(filepath).readlines()
+        start   = max(0, line_number - 4)
+        end     = min(len(lines), line_number + 3)
+        snippet = "".join(lines[start:end])
+        target  = lines[line_number - 1].strip()
+    except Exception as e:
+        return {"reason": str(e), "fix": "Check the file path and line number."}
+
+    llm = _get_model()
+    prompt = f"""{SYSTEM_PROMPT}
+
+File: {filepath}, line {line_number}
+Line in question: {target}
+Context:
+{snippet}
+
+Response:"""
+
+    output = llm(
+        prompt, max_tokens=load()["max_tokens"], stop=["\n\n\n"], echo=False
+    )
+    return _parse(output["choices"][0]["text"].strip())
+
+
+def ask_question(question: str) -> dict:
+    """Answer a freeform developer question."""
+    llm = _get_model()
+    prompt = f"""{SYSTEM_PROMPT}
+
+Developer question: {question}
+
+Response:"""
+
+    output = llm(
+        prompt, max_tokens=load()["max_tokens"], stop=["\n\n\n"], echo=False
+    )
+    return _parse(output["choices"][0]["text"].strip())
+
+
+def _parse(raw: str) -> dict:
+    """Parse model output into {reason, fix} dict."""
+    reason, fix = "", ""
+    for line in raw.splitlines():
+        if line.upper().startswith("REASON:"):
+            reason = line.split(":", 1)[-1].strip()
+        elif line.upper().startswith("FIX:"):
+            fix = line.split(":", 1)[-1].strip()
+    if not reason:
+        reason = raw  # fallback — show raw output if parsing fails
+    return {"reason": reason, "fix": fix}

sherpa_dev-0.1.1/sherpa/cli.py

@@ -0,0 +1,115 @@
+"""
+CLI entry point for Sherpa.
+Routes commands: default (explain last error), explain (specific line),
+ask (freeform question), and cfg (configuration management).
+"""
+
+import click
+from rich.console import Console
+
+from sherpa import config, setup, history, ai, display
+
+console = Console()
+
+
+@click.group(invoke_without_command=True)
+@click.pass_context
+def main(ctx):
+    """Sherpa — explains your terminal errors. Fully local, no API key."""
+    if ctx.invoked_subcommand is None:
+        _explain_last()
+
+
+@main.command()
+@click.argument("target")   # format: file.py:42
+def explain(target):
+    """Explain a specific line. Usage: sherpa explain app.py:42"""
+    _ensure_model()
+    try:
+        filepath, line = target.rsplit(":", 1)
+        line_number = int(line)
+    except ValueError:
+        display.show_error(
+            "Format must be file.py:LINE — e.g. sherpa explain app.py:42"
+        )
+        return
+    display.show_thinking()
+    result = ai.explain_line(filepath, line_number)
+    display.show_result(result)
+
+
+@main.command()
+@click.argument("question", nargs=-1)
+def ask(question):
+    """Ask anything. Usage: sherpa ask why is my loop infinite"""
+    _ensure_model()
+    q = " ".join(question)
+    if not q:
+        display.show_error(
+            "Provide a question. e.g. sherpa ask why is my dict empty"
+        )
+        return
+    display.show_thinking()
+    result = ai.ask_question(q)
+    display.show_result(result)
+
+
+@main.group()
+def cfg():
+    """Manage sherpa config."""
+    pass
+
+
+@cfg.command("show")
+def cfg_show():
+    """Show current config."""
+    import json
+    c = config.load()
+    console.print_json(json.dumps(c))
+
+
+@cfg.command("set-model")
+@click.argument("path")
+def cfg_set_model(path):
+    """Point sherpa to a different .gguf model file."""
+    c = config.load()
+    c["model_path"] = path
+    config.save(c)
+    console.print(f"[green]Model path updated to:[/green] {path}")
+
+
+# ─── Internal helpers ────────────────────────────────────────
+
+
+def _ensure_model():
+    """Trigger llama install + download wizard if needed."""
+    from sherpa.setup import ensure_llama
+    if not ensure_llama():
+        raise SystemExit(1)
+
+    if not config.model_exists():
+        setup.download_model()
+        raise SystemExit(0)
+
+
+def _explain_last():
+    """Default command — explain the last terminal error."""
+    _ensure_model()
+    err = history.get_last_error()
+
+    if not err["command"]:
+        display.show_error(
+            "Could not read shell history. "
+            "Run a command first, then try `sherpa` again."
+        )
+        return
+
+    if not err["stderr"]:
+        display.show_error(
+            f"No error output found for: {err['command']}"
+        )
+        return
+
+    display.show_thinking()
+    result = ai.explain(err["command"], err["stderr"])
+    display.show_result(result, command=err["command"])

sherpa_dev-0.1.1/sherpa/config.py

@@ -0,0 +1,46 @@
+"""
+Manages the ~/.sherpa/ directory, config.json, and model path.
+Everything Sherpa needs to know about its environment lives here.
+"""
+
+import json
+import os
+from pathlib import Path
+
+SHERPA_DIR   = Path.home() / ".sherpa"
+CONFIG_FILE  = SHERPA_DIR / "config.json"
+MODEL_PATH   = SHERPA_DIR / "model.gguf"
+
+MODEL_URL = (
+    "https://huggingface.co/TheBloke/CodeLlama-7B-Instruct-GGUF"
+    "/resolve/main/codellama-7b-instruct.Q4_K_M.gguf"
+)
+
+DEFAULTS = {
+    "model_path": str(MODEL_PATH),
+    "n_ctx":      2048,
+    "max_tokens": 350,
+    "verbose":    False,
+}
+
+
+def load() -> dict:
+    """Load config from ~/.sherpa/config.json, creating defaults if needed."""
+    SHERPA_DIR.mkdir(exist_ok=True)
+    if not CONFIG_FILE.exists():
+        save(DEFAULTS)
+    with open(CONFIG_FILE) as f:
+        return json.load(f)
+
+
+def save(cfg: dict):
+    """Save config dict to ~/.sherpa/config.json."""
+    SHERPA_DIR.mkdir(exist_ok=True)
+    with open(CONFIG_FILE, "w") as f:
+        json.dump(cfg, f, indent=2)
+
+
+def model_exists() -> bool:
+    """Check if the configured model file exists on disk."""
+    cfg = load()
+    return Path(cfg["model_path"]).exists()