nlshell 0.1.0__tar.gz

nlshell-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Mattias Brycke
+
+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.

nlshell-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.1
+Name: nlshell
+Version: 0.1.0
+Summary: Creates shell command from a description using an LLM
+License: MIT
+Author: Mattias Brycke
+Author-email: mattias.brycke@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: openai (>=1.52.2,<2.0.0)
+Description-Content-Type: text/markdown
+
+# nlshell 
+
+A very small Python package that generates shell commands from a "natural language" description.
+It will provide a explanation of the command and prefill the command line with the generated command.
+
+Useses an LLM model to generate the shell commands.
+
+### _IMPORTANT! Never run a generated command without understanding what it does. The generated command may be harmful. There is no guarantee whatsoever that what the LLM suggests is correct! DON'T BLINDLY TRUST THE GENERATED SUGGESTION!_
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [License](#license)
+- [GitHub](#github)
+
+## Installation
+
+Instructions on how to install your package. Include both the pip and poetry methods.
+
+```bash
+# Using pip
+pip install nlshell
+
+# Using poetry
+poetry add nlshell
+
+```
+
+## Usage
+
+Activate the virtual environment where the package is installed to use the nlshell command.
+
+
+### Set the base_url
+The package uses the openai client to call an LLM. By specifying a `base-url` you can use your own model, e.g. a local model.
+```shell
+c --base-url http://localhost:11434/v1
+```
+If no `base_url` is explicitly set, the package will ask which url to use.
+
+
+### Create a command
+```shell
+c list all files in the current directory, including hidden files
+```
+where c is the nlshell command.
+This command will generate a response like this:
+```text
+The 'ls' command lists directory contents. The option '-l' provides a long listing format which includes file permissions, number of links, owner, group, size, and time of last modification. The '-a' option ensures hidden files (those starting with a dot .) are also listed.
+$ ls -la
+```
+
+
+### Set the api_key
+```shell
+c --api-key your-api-key
+```
+Even if you run a local model you need to set an api_key since the openai client requires it, even if the key is just a dummy key.
+
+### Set the model
+
+```shell
+c --model-name qwen2.5-coder:7b
+```
+If no model is specified the package will ask which model to use.
+
+
+
+## License
+Distributed under the MIT License. See `LICENSE` for more information.      
+
+## GitHub
+[https://github.com/mbrycke/nlshell](https://github.com/mbrycke/nlshell)
+

nlshell-0.1.0/README.md

@@ -0,0 +1,74 @@
+# nlshell 
+
+A very small Python package that generates shell commands from a "natural language" description.
+It will provide a explanation of the command and prefill the command line with the generated command.
+
+Useses an LLM model to generate the shell commands.
+
+### _IMPORTANT! Never run a generated command without understanding what it does. The generated command may be harmful. There is no guarantee whatsoever that what the LLM suggests is correct! DON'T BLINDLY TRUST THE GENERATED SUGGESTION!_
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [License](#license)
+- [GitHub](#github)
+
+## Installation
+
+Instructions on how to install your package. Include both the pip and poetry methods.
+
+```bash
+# Using pip
+pip install nlshell
+
+# Using poetry
+poetry add nlshell
+
+```
+
+## Usage
+
+Activate the virtual environment where the package is installed to use the nlshell command.
+
+
+### Set the base_url
+The package uses the openai client to call an LLM. By specifying a `base-url` you can use your own model, e.g. a local model.
+```shell
+c --base-url http://localhost:11434/v1
+```
+If no `base_url` is explicitly set, the package will ask which url to use.
+
+
+### Create a command
+```shell
+c list all files in the current directory, including hidden files
+```
+where c is the nlshell command.
+This command will generate a response like this:
+```text
+The 'ls' command lists directory contents. The option '-l' provides a long listing format which includes file permissions, number of links, owner, group, size, and time of last modification. The '-a' option ensures hidden files (those starting with a dot .) are also listed.
+$ ls -la
+```
+
+
+### Set the api_key
+```shell
+c --api-key your-api-key
+```
+Even if you run a local model you need to set an api_key since the openai client requires it, even if the key is just a dummy key.
+
+### Set the model
+
+```shell
+c --model-name qwen2.5-coder:7b
+```
+If no model is specified the package will ask which model to use.
+
+
+
+## License
+Distributed under the MIT License. See `LICENSE` for more information.      
+
+## GitHub
+[https://github.com/mbrycke/nlshell](https://github.com/mbrycke/nlshell)

nlshell-0.1.0/nlshell/main.py

@@ -0,0 +1,197 @@
+import argparse
+import json
+import openai
+import os
+import pydantic
+import readline
+from openai import OpenAI
+from pydantic import BaseModel
+from nlshell.settings import (
+    handle_warning_message,
+    set_config,
+    get_base_url,
+    get_model,
+    get_api_key,
+)
+
+N_GENERATION_ATTEMPTS = 3
+
+
+class Command(BaseModel):
+    command: str
+    explanation: str
+
+
+def extract_json_content(s):
+    if "```json" not in s:
+        # if markdown json  not present, return the whole string
+        return s.replace("\n", "")
+
+    # Find the start and end indices for the markdown JSON content
+    start_index = s.find("```json") + len("```json\n")
+    end_index = s.rfind("```")
+    return s[start_index:end_index].strip().replace("\n", "")
+
+
+# TODO: implement `return_format` when available
+def generate_command(prompt, url, model="qwen2.5-coder:7b", api_key="abc123"):
+    """
+    Use the OpenAI client to generate a command.
+
+    Args:
+        prompt (str): The description of the command to generate.
+        url (str): The URL of the OpenAI API.
+
+    Returns:
+        dict: A dictionary containing the generated command and an explanation.
+    """
+
+    client = OpenAI(api_key=api_key, base_url=url)
+
+    try:
+        response = client.chat.completions.create(
+            model=model,
+            messages=[
+                {
+                    "role": "system",
+                    "content": 'Answer with a linux shell command. The answer should be json in the form {"command": <command>, "explanation":<explanation>}',
+                },
+                {"role": "user", "content": prompt},
+            ],
+        )
+    except openai.APIConnectionError as e:
+        print(
+            f"Error: can't connect to LLM at url:{url}. Please set the correct url using 'c --set-base-url <url>'"
+        )
+        raise e
+
+    str_json = response.choices[0].message.content
+    str_json = extract_json_content(str_json)
+    try:
+        return json.loads(str_json)
+    except json.JSONDecodeError as e:
+        print("Error decoding json: ", e)
+
+
+def prefill_input(prefill_text):
+    def hook():
+        readline.insert_text(prefill_text)
+
+    # Set the hook to prefill the input
+    readline.set_startup_hook(hook)
+
+    try:
+        return input("$ ")  # Print the prompt once, let readline handle the rest
+    finally:
+        readline.set_startup_hook()  # Clear the hook after use
+
+
+def add_to_history(command):
+    # history is stored in ~/.bash_history
+    readline.add_history(command)
+    with open(os.path.expanduser("~/.bash_history"), "a") as f:
+        f.write(command + "\n")
+
+
+def parse_arguments():
+
+    parser = argparse.ArgumentParser(
+        description="Generates a shell command from a description."
+    )
+    parser.add_argument(
+        "description_str",
+        nargs="*",
+        help="A description of the command to generate. Example: c list all files in the current directory",
+    )
+    parser.add_argument(
+        "--disable-warning",
+        action="store_true",
+        help="Disable the warning message.",
+        default=False,
+    )
+
+    parser.add_argument(
+        "--enable-warning",
+        action="store_true",
+        help="Enable the warning message.",
+        default=False,
+    )
+
+    parser.add_argument(
+        "--set-base-url",
+        type=str,
+        help="Set the base url for the OpenAI API.",
+    )
+
+    parser.add_argument(
+        "--set-model",
+        type=str,
+        help="Set the model for the OpenAI API.",
+    )
+
+    parser.add_argument(
+        "--api-key",
+        type=str,
+        help="Set the API key for the OpenAI API.",
+    )
+
+    return parser
+
+
+def main():
+
+    parser = parse_arguments()
+    args = parser.parse_args()
+
+    command_instr = " ".join(
+        args.description_str
+    ).strip()  # The instruction to generate a command
+
+    if args.disable_warning:
+        set_config("default", "disable_warning", "True")
+        return
+
+    if args.enable_warning:
+        set_config("default", "disable_warning", "False")
+        return
+
+    if args.set_base_url:
+        set_config("default", "base_url", args.set_base_url)
+        return
+
+    if args.set_model:
+        set_config("default", "model", args.set_model)
+        return
+    
+    if args.api_key:
+        set_config("default", "api_key", args.api_key)
+        return 
+
+    if command_instr == "" or command_instr == "--help" or command_instr == "-h":
+        parser.print_help()
+        return
+
+    handle_warning_message()
+
+    url = get_base_url()
+    model = get_model()
+    api_key = get_api_key()
+
+    # Try to generate a valid command N_GENERATION_ATTEMPTS times
+    for _ in range(N_GENERATION_ATTEMPTS):
+        json_command = generate_command(command_instr, url, model, api_key=api_key)
+        try:
+            _ = Command(**json_command)  # check if the generated command is valid
+            break
+        except pydantic.ValidationError as e:
+            pass
+    else:
+        print("Error: Could not generate a valid command. Please try again.")
+        return
+
+    print(
+        "\033[90m" + json_command["explanation"] + "\033[0m"
+    )  # Print the explanation in gray
+    edited_command = prefill_input(json_command["command"])
+    add_to_history(edited_command)  # Add the command to the history
+    os.system(edited_command)

nlshell-0.1.0/nlshell/settings.py

@@ -0,0 +1,99 @@
+import configparser
+import functools
+import os
+
+SETTINGS_FILE_PATH = os.path.expanduser("~/.config/nlshell/settings.ini")
+DEFAULT_URL = "http://localhost:11434/v1"  # default url for local ollama
+DEFAULT_MODEL = "qwen2.5-coder:7b"
+
+
+@functools.lru_cache(maxsize=None)
+def get_config(section, key):
+    """
+    Loads the configuration file and returns the 'disable_warning' setting.
+    The cache is cleared when the `set_config` function is called.
+    """
+    config = configparser.ConfigParser()
+    config.read(SETTINGS_FILE_PATH)
+    return config.get(section, key, fallback=None)
+
+
+def set_config(section, key, value):
+    """
+    Create a new configuration file if it doesn't exist, then add the setting.
+    And clear the cache for the `get_config` function.
+    """
+
+    get_config.cache_clear()
+
+    # Create the directory if it doesn't exist
+    os.makedirs(os.path.dirname(SETTINGS_FILE_PATH), exist_ok=True)
+
+    config = configparser.ConfigParser()
+    config.read(SETTINGS_FILE_PATH)
+    if not config.has_section(section):
+        config.add_section(section)
+    config.set(section, key, value)
+    with open(SETTINGS_FILE_PATH, "w") as f:
+        config.write(f)
+
+
+def handle_warning_message():
+    """Displays a warning unless it's disabled in the settings."""
+    if not get_config("default", "disable_warning"):
+        # print in red color
+        print(
+            "\033[91m"
+            + "WARNING: Using the genereated command can cause serious harm. Never run a command you are not 100% sure of what it will do."
+            + "\033[0m"
+        )
+        print("Disable this warning by running 'c --disable-warning'")
+
+
+def get_base_url():
+    """
+    Retrieve the base url from the settings file.
+    If the base url is not set, get input from the user.
+    """
+
+    base_url = get_config("default", "base_url")
+    if not base_url:
+        base_url = input(
+            f"Base URL for LLM is not set. \nEnter the base url for the API (default {DEFAULT_URL} (local ollama)): "
+        )
+        if not base_url:
+            base_url = DEFAULT_URL
+        set_config("default", "base_url", base_url)
+    return base_url
+
+
+def get_model():
+    """
+    Retrieve the model from the settings file.
+    If the model is not set, get input from the user.
+    """
+
+    model = get_config("default", "model")
+    if not model:
+        model = input(
+            f"Model for LLM is not set. \nEnter the model for the API: (default {DEFAULT_MODEL}): "
+        )
+        if not model:
+            model = DEFAULT_MODEL
+        set_config("default", "model", model)
+    return model
+
+
+def get_api_key():
+    """
+    Retrieve the API key from the settings file.
+    If the API key is not set, get input from the user.
+    """
+
+    api_key = get_config("default","api_key")
+    if not api_key:
+        api_key = input(
+            f"API key for OpenAI is not set. \nEnter the API key for the API: "
+        )
+        set_config("default","api_key",api_key)
+    return api_key

nlshell-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[tool.poetry]
+name = "nlshell"
+version = "0.1.0"
+description = "Creates shell command from a description using an LLM"
+authors = ["Mattias Brycke <mattias.brycke@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+openai = "^1.52.2"
+
+[tool.poetry.scripts]
+c = "nlshell.main:main"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[project.urls]
+
+