pehloo-shell 0.1.0__py3-none-any.whl

pehloo_shell/__init__.py

@@ -0,0 +1,4 @@
+"""lfm-shell package."""
+
+__version__ = "0.1.0"
+

pehloo_shell/cli.py

@@ -0,0 +1,348 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+from pehloo_shell.onboarding import run_wizard
+from pehloo_shell.providers import LOCAL_PROVIDER, PROVIDERS, provider_for
+
+load_dotenv()
+
+CONFIG_PATH = Path.home() / ".pehloo" / "shell-config.json"
+SYSTEM_PROMPT = """You translate requests into shell commands.
+Return exactly one shell command and nothing else: no explanation, no prompt symbol,
+and no Markdown fence. Prefer portable commands unless the request requires a
+platform-specific feature. Never invent placeholder paths or values. Words such as
+\"here\" and \"current folder\" mean the shell's current working directory."""
+EXAMPLE_REQUEST = "List the 10 largest directories in the current folder."
+EXAMPLE_ANSWER = "du -h --max-depth=1 | sort -hr | head -n 10"
+# Sent as a follow-up turn when the user presses `c` at the confirmation prompt.
+REVISION_PROMPT = "Change that command: {change}"
+ACTION_PROMPT = "[y] run  [n] reject  [c] change > "
+# Exit status for Ctrl-C / Ctrl-D at a prompt (128 + SIGINT, the shell convention).
+INTERRUPTED = 130
+
+
+def clean_request(value: str) -> str:
+    """Remove a leading shell-comment marker while preserving the request."""
+    return re.sub(r"^\s*(?://|#)\s*", "", value).strip()
+
+
+def clean_response(value: str) -> str:
+    """Tolerate Markdown fences even though the model is asked not to use them."""
+    value = value.strip()
+    match = re.fullmatch(r"```(?:bash|sh|shell|zsh)?\s*\n?(.*?)\n?```", value, re.DOTALL | re.IGNORECASE)
+    return (match.group(1) if match else value).strip()
+
+
+def config_path() -> Path:
+    return Path(os.environ.get("PEHLOO_SHELL_CONFIG", CONFIG_PATH))
+
+
+def load_config() -> dict[str, str]:
+    path = config_path()
+    if not path.exists():
+        return {}
+    try:
+        raw_config = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as error:
+        raise RuntimeError(f"invalid config file {path}: {error}") from error
+    if not isinstance(raw_config, dict):
+        raise RuntimeError(f"invalid config file {path}: expected a JSON object")
+
+    config: dict[str, str] = {}
+    aliases = {
+        "inference_provider": "inference_provider",
+        "provider": "inference_provider",
+        "url": "url",
+        "model_slug": "model_slug",
+        "model": "model_slug",
+        "api_key": "api_key",
+        "apikey": "api_key",
+    }
+    for key, value in raw_config.items():
+        normalized_key = aliases.get(str(key).strip().lower().replace("-", "_").replace(" ", "_"))
+        if normalized_key and value:
+            config[normalized_key] = str(value)
+    return config
+
+
+def setting_from_env(name: str, fallback: str) -> str:
+    return os.environ.get(name) or fallback
+
+
+def api_key_for(provider, config: dict[str, str]) -> str:
+    """Resolve the API key: the provider's own env var, a generic override, then the config file."""
+    candidates = [
+        os.environ.get(provider.key_env, "") if provider.key_env else "",
+        os.environ.get("PEHLOO_SHELL_API_KEY", ""),
+        config.get("api_key", ""),
+    ]
+    for candidate in candidates:
+        if candidate:
+            return candidate
+    return ""
+
+
+def resolve_settings(config: dict[str, str]) -> tuple[str, str, str, str]:
+    provider = provider_for(setting_from_env("PEHLOO_SHELL_PROVIDER", config.get("inference_provider", LOCAL_PROVIDER.name)))
+    url = setting_from_env("LFM_SHELL_URL", config.get("url", provider.chat_url))
+    model = setting_from_env("LFM_SHELL_MODEL", config.get("model_slug", provider.default_model))
+    return provider.name, url, model, api_key_for(provider, config)
+
+
+def auth_headers(provider: str, api_key: str = "") -> dict[str, str]:
+    """Headers for the chat request. The key is only sent when we have one."""
+    backend = provider_for(provider)
+    headers = {
+        "Content-Type": "application/json",
+        "User-Agent": "pehloo-shell/0.1",
+    }
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    elif backend.api_key_required:
+        raise RuntimeError(f"{backend.name} needs an API key: export {backend.key_env} or run `pls --setup`")
+    return headers
+
+
+def build_messages(prompt: str, previous_command: str = "", change: str = "") -> list[dict[str, str]]:
+    """Build the chat payload, appending the revision turn when the user asked for a change."""
+    messages = [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": EXAMPLE_REQUEST},
+        {"role": "assistant", "content": EXAMPLE_ANSWER},
+        {"role": "user", "content": prompt},
+    ]
+    if previous_command:
+        messages.append({"role": "assistant", "content": previous_command})
+        messages.append({"role": "user", "content": REVISION_PROMPT.format(change=change)})
+    return messages
+
+
+def generate_command(
+    prompt: str,
+    url: str,
+    model: str,
+    timeout: float,
+    provider: str = "llama.cpp",
+    api_key: str = "",
+    previous_command: str = "",
+    change: str = "",
+) -> str:
+    """Ask the model for one command; `previous_command` + `change` ask it to revise one."""
+    payload = {
+        "model": model,
+        "messages": build_messages(prompt, previous_command, change),
+        "temperature": 0.2,
+        "max_tokens": 8192,
+    }
+    request = urllib.request.Request(
+        url,
+        data=json.dumps(payload).encode("utf-8"),
+        headers=auth_headers(provider, api_key),
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            result = json.load(response)
+    except urllib.error.HTTPError as error:
+        detail = error.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"server returned HTTP {error.code}: {detail}") from error
+    except urllib.error.URLError as error:
+        raise RuntimeError(f"could not reach {url}: {error.reason}") from error
+    except (TimeoutError, json.JSONDecodeError) as error:
+        raise RuntimeError(f"invalid or timed-out response from {url}: {error}") from error
+
+    try:
+        content = result["choices"][0]["message"]["content"]
+    except (KeyError, IndexError, TypeError) as error:
+        raise RuntimeError(f"unexpected server response: {result!r}") from error
+
+    command = clean_response(content)
+    if not command:
+        raise RuntimeError("the model returned an empty command")
+    return command
+
+
+def stdin_is_interactive() -> bool:
+    """True when both ends are a terminal, so asking the user a question is safe."""
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def print_command(command: str, markdown: bool) -> None:
+    """Print the command, optionally fenced so it can be pasted into Markdown."""
+    print(f"```bash\n{command}\n```" if markdown else command)
+
+
+def choose_action(answer: str) -> str:
+    """Map a typed reply to `run`, `reject`, `revise` — or `ask` for anything else.
+
+    Enter and `n` reject: a stray newline must never run a command.
+    """
+    answer = answer.strip().lower()
+    if answer in {"y", "yes"}:
+        return "run"
+    if answer in {"c", "change", "revise"}:
+        return "revise"
+    if answer in {"n", "no", ""}:
+        return "reject"
+    return "ask"
+
+
+def read_line(prompt: str) -> str | None:
+    """Read one line, or None when the user interrupts or closes the prompt."""
+    try:
+        return input(prompt).strip()
+    except (EOFError, KeyboardInterrupt):
+        print()
+        return None
+
+
+def run_command(command: str) -> int:
+    """Run the confirmed command in the user's shell, passing its exit status through."""
+    try:
+        return subprocess.run(command, shell=True, check=False).returncode
+    except KeyboardInterrupt:
+        print()
+        return INTERRUPTED
+
+
+def confirm_and_run(prompt: str, command: str, args: argparse.Namespace, api_key: str) -> int:
+    """Show the command and act on the user's choice: run it, reject it, or change it.
+
+    `c` sends the requested change back to the model together with the previous
+    command, so iterating does not mean retyping the request. Returns the exit
+    status `pls` should exit with.
+    """
+    while True:
+        print_command(command, args.markdown)
+        answer = read_line(ACTION_PROMPT)
+        if answer is None:
+            return INTERRUPTED
+
+        action = choose_action(answer)
+        if action == "reject":
+            return 0
+        if action == "ask":
+            continue
+        if action == "run":
+            return run_command(command)
+
+        change = read_line("how should it change? ")
+        if change is None:
+            return INTERRUPTED
+        if not change:
+            continue
+
+        try:
+            command = generate_command(
+                prompt,
+                args.url,
+                args.model,
+                args.timeout,
+                args.provider,
+                api_key,
+                previous_command=command,
+                change=change,
+            )
+        except RuntimeError as error:
+            print(f"pls: {error}", file=sys.stderr)
+            return 1
+
+
+def offer_setup(force: bool) -> dict[str, str]:
+    """Run the setup wizard, or explain why we cannot.
+
+    Reached when `--setup` was passed, or when there is no config file yet and the
+    user can answer questions. Without a terminal we keep the old behaviour — no
+    prompts, default settings — so piping a request into `pls` still works.
+    """
+    if not stdin_is_interactive():
+        if force:
+            raise RuntimeError("--setup needs an interactive terminal")
+        return {}
+    try:
+        return run_wizard(config_path())
+    except (EOFError, KeyboardInterrupt):
+        print("\npls: setup skipped, using default settings", file=sys.stderr)
+        return {}
+
+
+def build_parser(
+    provider: str = LOCAL_PROVIDER.name,
+    url: str = LOCAL_PROVIDER.chat_url,
+    model: str = LOCAL_PROVIDER.default_model,
+) -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="pls",
+        description=(
+            "Generate a shell command with an OpenAI-compatible model API, then choose "
+            "whether to run it, reject it, or change it."
+        ),
+        epilog="pehloo-shell · a Pehloo tool (https://pehloo.xyz)",
+    )
+    parser.add_argument("request", nargs="*", help='request, for example: "list files by size"')
+    parser.add_argument("--provider", default=provider, choices=sorted(PROVIDERS))
+    parser.add_argument("--url", default=url)
+    parser.add_argument("--model", default=model)
+    parser.add_argument("--timeout", type=float, default=30.0, help="request timeout in seconds")
+    parser.add_argument("--markdown", action="store_true", help="wrap output in a bash Markdown fence")
+    parser.add_argument("--setup", action="store_true", help="run the backend setup wizard again")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    setup_requested = "--setup" in argv
+
+    try:
+        config = load_config()
+        if setup_requested or (not config and stdin_is_interactive()):
+            config = offer_setup(force=setup_requested)
+        provider, url, model, api_key = resolve_settings(config)
+    except RuntimeError as error:
+        print(f"pls: {error}", file=sys.stderr)
+        return 1
+
+    args = build_parser(provider, url, model).parse_args(argv)
+    if args.setup and not args.request:
+        return 0  # `pls --setup` on its own is only the wizard
+
+    raw_request = " ".join(args.request)
+    if not raw_request and not sys.stdin.isatty():
+        raw_request = sys.stdin.read()
+    if not raw_request:
+        answer = read_line("// ")
+        if answer is None:
+            return INTERRUPTED
+        raw_request = answer
+
+    prompt = clean_request(raw_request)
+    if not prompt:
+        print("pls: a request is required", file=sys.stderr)
+        return 2
+
+    try:
+        command = generate_command(prompt, args.url, args.model, args.timeout, args.provider, api_key)
+    except RuntimeError as error:
+        print(f"pls: {error}", file=sys.stderr)
+        return 1
+
+    if not stdin_is_interactive():
+        # Piped or redirected: print the command and stay out of the way.
+        print_command(command, args.markdown)
+        return 0
+    return confirm_and_run(prompt, command, args, api_key)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pehloo_shell/onboarding.py

@@ -0,0 +1,160 @@
+"""First-run setup: pick a backend, find its models, write shell-config.json.
+
+`pls` calls `run_wizard()` when there is no config file yet, so a new user gets a
+working backend instead of a connection error. The wizard is plain question/answer
+flow over stdin — no terminal-cursor tricks — so it stays readable and testable.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from pehloo_shell.providers import (
+    HOSTED_PROVIDERS,
+    LOCAL_PROVIDER,
+    Provider,
+    chat_url,
+    list_models,
+)
+
+# Terminal branding, matching pehloo.xyz: boxed status tags and ▸ progress lines.
+BANNER = """\
+╔══════════════════════════════╗
+║   PLS_SETUP: MODEL_BACKEND   ║
+╚══════════════════════════════╝
+▸ pehloo-shell · a Pehloo tool (pehloo.xyz)"""
+
+
+def ask(question: str, default: str = "") -> str:
+    """Prompt for one line, returning `default` when the user presses Enter."""
+    suffix = f" [{default}]" if default else ""
+    answer = input(f"{question}{suffix}: ").strip()
+    return answer or default
+
+
+def ask_yes_no(question: str, default: bool = True) -> bool:
+    """Ask a yes/no question; anything unrecognised asks again rather than guessing."""
+    hint = "Y/n" if default else "y/N"
+    while True:
+        answer = input(f"{question} [{hint}]: ").strip().lower()
+        if not answer:
+            return default
+        if answer in {"y", "yes"}:
+            return True
+        if answer in {"n", "no"}:
+            return False
+        print("  please answer y or n")
+
+
+def choose_model(models: list[str], default: str) -> str:
+    """Let the user pick a detected model by number, or type one that is not listed."""
+    # A provider's default model is often not installed on a local server, so the
+    # first detected model becomes the default instead of an unusable name.
+    fallback = default if default in models else (models[0] if models else default)
+    for index, model in enumerate(models, start=1):
+        marker = "  (default)" if model == fallback else ""
+        print(f"  {index}. {model}{marker}")
+    while True:
+        answer = ask("Model number or name", fallback)
+        if answer.isdigit() and 1 <= int(answer) <= len(models):
+            return models[int(answer) - 1]
+        if answer:
+            return answer
+        print("  a model is required")
+
+
+def discover_models(url: str, api_key: str) -> list[str]:
+    """List the server's models, retrying when it is unreachable.
+
+    Returns an empty list when the user gives up, so the caller can fall back to
+    a typed-in model name instead of losing the whole setup.
+    """
+    while True:
+        try:
+            models = list_models(url, api_key)
+        except RuntimeError as error:
+            print(f"  ! {error}")
+            models = []
+        if models:
+            return models
+        if not ask_yes_no("Try the model list again?", default=False):
+            return []
+
+
+def configure_local() -> dict[str, str]:
+    """Collect settings for a self-hosted OpenAI-compatible server."""
+    print(f"\nLocal server: {LOCAL_PROVIDER.label} — any OpenAI-compatible server.")
+    url = ask("Server URL", LOCAL_PROVIDER.url)
+    api_key = ask("API key (leave blank if the server has none)", "")
+    models = discover_models(url, api_key)
+    if not models:
+        print("  starting without a model list; type the model name your server serves")
+    model = choose_model(models, LOCAL_PROVIDER.default_model)
+    return _config(provider=LOCAL_PROVIDER, url=url, model=model, api_key=api_key)
+
+
+def configure_hosted() -> dict[str, str]:
+    """Collect settings for one of the hosted OpenAI-compatible providers."""
+    print("\nHosted providers:")
+    for index, provider in enumerate(HOSTED_PROVIDERS, start=1):
+        print(f"  {index}. {provider.label}")
+
+    while True:
+        answer = ask("Provider number", "1")
+        if answer.isdigit() and 1 <= int(answer) <= len(HOSTED_PROVIDERS):
+            provider = HOSTED_PROVIDERS[int(answer) - 1]
+            break
+        print("  please pick one of the numbers above")
+
+    from_env = os.environ.get(provider.key_env, "") if provider.key_env else ""
+    if from_env:
+        print(f"  found {provider.key_env} in your environment")
+    else:
+        print(f"  create a key at {provider.key_url}")
+
+    api_key = ask(f"{provider.key_env or 'API key'} (stored in your config file)", from_env)
+    # A key that already lives in the environment is not copied into the config
+    # file; the CLI reads the environment variable first anyway.
+    stored_key = "" if api_key == from_env else api_key
+
+    models = discover_models(provider.url, api_key)
+    if not models:
+        print(f"  starting without a model list; the default is {provider.default_model}")
+    model = choose_model(models, provider.default_model)
+    return _config(provider=provider, url=provider.url, model=model, api_key=stored_key)
+
+
+def _config(provider: Provider, url: str, model: str, api_key: str) -> dict[str, str]:
+    """Assemble the config file body, omitting an empty API key."""
+    config = {
+        "inference_provider": provider.name,
+        "url": chat_url(url),
+        "model_slug": model,
+    }
+    if api_key:
+        config["api_key"] = api_key
+    return config
+
+
+def write_config(config: dict[str, str], path: Path) -> Path:
+    """Write shell-config.json readable only by the user — it may hold an API key."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+    os.chmod(path, 0o600)
+    return path
+
+
+def run_wizard(path: Path) -> dict[str, str]:
+    """Run the whole setup flow and save the result to `path`."""
+    print(BANNER)
+    print(f"▸ your answers are saved to {path} (re-run any time with `pls --setup`)")
+    if ask_yes_no("\nUse a local model server?", default=True):
+        config = configure_local()
+    else:
+        config = configure_hosted()
+    write_config(config, path)
+    print(f"▸ saved {path}")
+    print(f"▸ provider={config['inference_provider']}  url={config['url']}  model={config['model_slug']}")
+    return config

pehloo_shell/providers.py

@@ -0,0 +1,158 @@
+"""Inference backends `pls` can talk to, and model discovery against them.
+
+Every backend here speaks the OpenAI chat-completions API, so the transport in
+`cli.py` stays a single urllib call. This module only carries what the rest of
+the CLI needs per backend: where the API lives, which model to fall back on, and
+where the API key comes from.
+
+`url` is always the *base* URL (`.../v1`); `.chat_url` and `.models_url` derive
+the two endpoints from it. Stored config keeps the full chat-completions URL,
+which is what earlier versions wrote, and `chat_url()` accepts both spellings so
+hand-written config files keep working.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Provider:
+    """One OpenAI-compatible backend."""
+
+    name: str  # canonical id, stored in shell-config.json
+    label: str  # human wording for the setup wizard
+    url: str  # base URL, no /chat/completions suffix
+    default_model: str
+    key_env: str  # environment variable holding the API key ("" if not needed)
+    key_url: str  # where a user can create a key ("" if not needed)
+    api_key_required: bool
+
+    @property
+    def chat_url(self) -> str:
+        return chat_url(self.url)
+
+    @property
+    def models_url(self) -> str:
+        return models_url(self.url)
+
+
+LOCAL_PROVIDER = Provider(
+    name="llama.cpp",
+    label="llama.cpp, Ollama, LM Studio or vLLM",
+    url="http://127.0.0.1:8080/v1",
+    default_model="LFM2.5-1.2B-Instruct-Q8_0.gguf",
+    key_env="",
+    key_url="",
+    api_key_required=False,
+)
+
+HOSTED_PROVIDERS = (
+    Provider(
+        name="cerebras",
+        label="Cerebras — very fast hosted models, free tier",
+        url="https://api.cerebras.ai/v1",
+        default_model="gpt-oss-120b",
+        key_env="CEREBRAS_API_KEY",
+        key_url="https://cloud.cerebras.ai",
+        api_key_required=True,
+    ),
+    Provider(
+        name="groq",
+        label="Groq — very fast hosted models, free tier",
+        url="https://api.groq.com/openai/v1",
+        default_model="llama-3.3-70b-versatile",
+        key_env="GROQ_API_KEY",
+        key_url="https://console.groq.com/keys",
+        api_key_required=True,
+    ),
+    Provider(
+        name="openrouter",
+        label="OpenRouter — many models behind one key",
+        url="https://openrouter.ai/api/v1",
+        default_model="openai/gpt-4o-mini",
+        key_env="OPENROUTER_API_KEY",
+        key_url="https://openrouter.ai/keys",
+        api_key_required=True,
+    ),
+)
+
+PROVIDERS: dict[str, Provider] = {p.name: p for p in (LOCAL_PROVIDER, *HOSTED_PROVIDERS)}
+
+# Spellings users (and the earlier Cerebras-only version) may already have in a
+# config file or environment variable.
+ALIASES = {
+    "llama.cpp": "llama.cpp",
+    "llamacpp": "llama.cpp",
+    "llama_cpp": "llama.cpp",
+    "local": "llama.cpp",
+    "cerebras.ai": "cerebras",
+    "openrouter.ai": "openrouter",
+}
+
+
+def provider_for(name: str) -> Provider:
+    """Look up a provider, or raise a RuntimeError naming the supported ones.
+
+    Silently falling back to the local default on a typo would send requests to
+    the wrong server, so an unknown name stops the CLI instead.
+    """
+    key = name.strip().lower()
+    if not key:
+        return LOCAL_PROVIDER
+    canonical = ALIASES.get(key, key)
+    if canonical in PROVIDERS:
+        return PROVIDERS[canonical]
+    supported = ", ".join(PROVIDERS)
+    raise RuntimeError(f"unknown provider {name!r} (supported: {supported}; or pass --url for any OpenAI-compatible server)")
+
+
+def chat_url(url: str) -> str:
+    """The chat-completions endpoint for `url`, accepting a base or a full URL."""
+    base = url.strip().rstrip("/")
+    if base.endswith("/chat/completions"):
+        return base
+    return base + "/chat/completions"
+
+
+def models_url(url: str) -> str:
+    """The `/models` endpoint that pairs with a chat-completions URL."""
+    base = url.strip().rstrip("/")
+    return base.removesuffix("/chat/completions") + "/models"
+
+
+def list_models(url: str, api_key: str = "", timeout: float = 5.0) -> list[str]:
+    """Ask the server which models it serves, in the order it reports them.
+
+    Raises RuntimeError with a readable message: the setup wizard prints it and
+    offers a retry, which is how a user notices a server that is not running yet.
+    """
+    endpoint = models_url(url)
+    headers = {"User-Agent": "pehloo-shell/0.1"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    request = urllib.request.Request(endpoint, headers=headers, method="GET")
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            payload = json.load(response)
+    except urllib.error.HTTPError as error:
+        detail = error.read().decode("utf-8", errors="replace")[:200]
+        raise RuntimeError(f"{endpoint} returned HTTP {error.code}: {detail}") from error
+    except urllib.error.URLError as error:
+        raise RuntimeError(f"could not reach {endpoint}: {error.reason}") from error
+    except (TimeoutError, json.JSONDecodeError) as error:
+        raise RuntimeError(f"invalid or timed-out response from {endpoint}: {error}") from error
+
+    entries = payload.get("data") if isinstance(payload, dict) else None
+    if not isinstance(entries, list):
+        raise RuntimeError(f"unexpected response from {endpoint}: expected a JSON object with a 'data' list")
+
+    models: list[str] = []
+    for entry in entries:
+        model_id = entry.get("id") if isinstance(entry, dict) else None
+        if model_id and str(model_id) not in models:
+            models.append(str(model_id))
+    return models

pehloo_shell-0.1.0.dist-info/METADATA

@@ -0,0 +1,126 @@
+Metadata-Version: 2.5
+Name: pehloo-shell
+Version: 0.1.0
+Summary: Natural language in, shell command out — review it, then press y to run. A Pehloo tool.
+Project-URL: Homepage, https://pehloo.xyz
+Author: Ribhu
+License: MIT
+License-File: LICENSE
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Requires-Dist: python-dotenv>=1
+Description-Content-Type: text/markdown
+
+```
+██████╗ ███████╗██╗  ██╗██╗      ██████╗  ██████╗
+██╔══██╗██╔════╝██║  ██║██║     ██╔═══██╗██╔═══██╗
+██████╔╝█████╗  ███████║██║     ██║   ██║██║   ██║
+██╔═══╝ ██╔══╝  ██╔══██║██║     ██║   ██║██║   ██║
+██║     ███████╗██║  ██║███████╗╚██████╔╝╚██████╔╝
+╚═╝     ╚══════╝╚═╝  ╚═╝╚══════╝ ╚═════╝  ╚═════╝
+```
+
+# pls
+
+**Natural language in, shell command out. Review it, then press `y`.**
+
+`pls` is the Pehloo shell assistant — from [Pehloo](https://pehloo.xyz), AI
+tools for builders who ship. It asks an OpenAI-compatible model to turn your
+request into one shell command, shows it to you, and waits:
+
+```console
+$ pls "list the 10 largest directories in the current folder"
+du -h --max-depth=1 | sort -hr | head -n 10
+[y] run  [n] reject  [c] change >
+```
+
+- `y` runs the command in your shell; `pls` exits with its status.
+- `n` or Enter rejects it — nothing runs.
+- `c` asks the model to change it (e.g. type `sort by size instead`) and shows
+  the revision, with the previous command as context.
+
+## Install
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/ribhu97/pehloo-shell/main/install.sh | sh
+sh install.sh                                     # from a checkout
+```
+
+The installer works at user level — no sudo, no system Python — using uv, pipx
+or pip, whichever you have, and prints the installed `pls` path plus the
+`export PATH=…` line if you need one. It installs the `pehloo-shell` package
+from PyPI, falling back to this repository while the package is unpublished.
+Point it elsewhere with `--source` / `$PEHLOO_SHELL_SOURCE`:
+
+```bash
+sh install.sh --source "git+https://github.com/ribhu97/pehloo-shell"
+```
+
+Already have a Python tool runner? Skip the script:
+
+```bash
+uv tool install pehloo-shell     # or: pipx install pehloo-shell
+```
+
+For development see [AGENTS.md](AGENTS.md) (`uv sync`, then `.venv/bin/pls`).
+Note that `pipx install .` and `uv tool install .` copy the code — rerun them
+after changing the CLI.
+
+## Setup
+
+The first run with no config asks which backend to use:
+
+```console
+╔══════════════════════════════╗
+║   PLS_SETUP: MODEL_BACKEND   ║
+╚══════════════════════════════╝
+▸ pehloo-shell · a Pehloo tool (pehloo.xyz)
+▸ your answers are saved to ~/.pehloo/shell-config.json (re-run any time with `pls --setup`)
+
+Use a local model server? [Y/n]: y
+
+Local server: llama.cpp, Ollama, LM Studio or vLLM — any OpenAI-compatible server.
+Server URL [http://127.0.0.1:8080/v1]:
+API key (leave blank if the server has none):
+  1. LFM2.5-1.2B-Instruct-Q8_0.gguf  (default)
+  2. MiniCPM5-2B
+Model number or name [1]:
+```
+
+- **Local** (`y`): any OpenAI-compatible server — llama.cpp, Ollama, LM Studio,
+  vLLM. `pls` reads its `/v1/models` list so you can pick a model instead of
+  guessing a name.
+- **Hosted** (`n`): Cerebras, Groq or OpenRouter. The wizard tells you where to
+  create a key and detects the provider's models with it. A key already in your
+  environment is used without being copied into the config file.
+
+Re-run setup any time with `pls --setup`, or edit `~/.pehloo/shell-config.json`
+by hand.
+
+## Non-interactive
+
+```bash
+echo "show files changed today" | pls    # prints the command, runs nothing
+pls --markdown "show my current directory"
+```
+
+When stdin is not a terminal — pipes, scripts, CI — `pls` prints the command and
+stops. Nothing executes without an explicit `y` at a terminal.
+
+## Environment variables
+
+Handy for CI, or to keep the API key out of the config file. They override the
+config file; command-line flags override both.
+
+| Variable | Meaning |
+| --- | --- |
+| `PEHLOO_SHELL_CONFIG` | where the config file lives (default `~/.pehloo/shell-config.json`) |
+| `PEHLOO_SHELL_PROVIDER` | `llama.cpp`, `cerebras`, `groq` or `openrouter` |
+| `PEHLOO_SHELL_API_KEY` | API key for any provider |
+| `CEREBRAS_API_KEY`, `GROQ_API_KEY`, `OPENROUTER_API_KEY` | provider-specific keys |
+| `LFM_SHELL_URL` | chat-completions URL of any OpenAI-compatible server |
+| `LFM_SHELL_MODEL` | model name to send |
+
+Read the command before you press `y`: model output can be destructive.

pehloo_shell-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pehloo_shell/__init__.py,sha256=2Knag3nEzNeB_p-yLd5zF4wDcyGBTquyTkU9g0tnsH8,49
+pehloo_shell/cli.py,sha256=RaQ8krDZWgYMsmMfJJJE77OzxnAp0KhY9-kxH0XkJ9U,12568
+pehloo_shell/onboarding.py,sha256=2ZRYU22nasC3uN_eEOMO4nnkiNDgl0NRSwBqlc_sKY8,6269
+pehloo_shell/providers.py,sha256=3lvecfiyZKbh-pEKthu-TMheD5meftKhUwlgWZdM-IU,5679
+pehloo_shell-0.1.0.dist-info/METADATA,sha256=5vVrqycQ7Vd0syWPepknhsAf08JDoxrl4xEU_UOjL0o,5156
+pehloo_shell-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pehloo_shell-0.1.0.dist-info/entry_points.txt,sha256=sKSI6gXz9matj4mXS3s3Pej89pj1_AROwoBQwVSskqI,46
+pehloo_shell-0.1.0.dist-info/licenses/LICENSE,sha256=qWj0J2VpC5ZXkKM_u3On6kcgSqFXUsPc5WX5jUxmku0,1062
+pehloo_shell-0.1.0.dist-info/RECORD,,

pehloo_shell-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pehloo_shell-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pls = pehloo_shell.cli:main

pehloo_shell-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ribhu
+
+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.