From 78515593d5b760795ba47ffa028b9890b6ae52df Mon Sep 17 00:00:00 2001 From: sealad886 Date: Mon, 27 Jan 2025 09:42:07 +0000 Subject: [PATCH 1/4] feat(ollama): add plugin for managing and running language models with autocompletion and man page support --- plugins/ollama/README.md | 94 ++++++++++++++++++++ plugins/ollama/ollama.plugin.zsh | 146 +++++++++++++++++++++++++++++++ 2 files changed, 240 insertions(+) create mode 100644 plugins/ollama/README.md create mode 100644 plugins/ollama/ollama.plugin.zsh diff --git a/plugins/ollama/README.md b/plugins/ollama/README.md new file mode 100644 index 000000000..8a30c622a --- /dev/null +++ b/plugins/ollama/README.md @@ -0,0 +1,94 @@ +# Ollama Plugin for Oh-My-Zsh + +This plugin enhances your Zsh shell environment by integrating powerful features for managing, running, and creating large language models locally using the [Ollama CLI](https://ollama.ai/). The plugin provides streamlined workflows, autocompletion, and man page support, making it easier than ever to interact with your local AI models. + +## Features + +- **Command Autocompletion**: Full support for Ollama CLI commands, options, and arguments. +- **Dynamic Model Suggestions**: Automatically suggests available models based on the output of `ollama list`. + +## Installation + +### Prerequisites + +- A working installation of [Oh-My-Zsh](https://ohmyz.sh/). +- The Ollama CLI installed on your system. Refer to the [official Ollama documentation](https://github.com/ollama/ollama) for setup instructions. + +### Steps + +1. **Enable the Plugin** + Add `ollama` to the `plugins` array in your `.zshrc` file: + + ```sh + # in your ~/.zshrc file + plugins=(... ollama) + ``` + + or + + ```sh + # from shell + omz plugin enable ollama + ``` + + +2. **Restart Your Shell** + Apply the changes by reloading Oh-My-Zsh: + + ```sh + omz reload + ``` + +## Usage + +### Commands + +The plugin provides autocompletion and enhanced functionality for the following Ollama commands: + +| Command | Description | +|-------------|------------------------------------------| +| `serve`, `start`| Start the Ollama server locally. | +| `create` | Create a model from a Modelfile. | +| `show` | Display information about a specific model. | +| `run` | Execute a model with a given prompt. | +| `stop` | Terminate a running model. | +| `pull` | Download a model from a registry. | +| `push` | Upload a model to a registry. | +| `list`, `ls` | List all available models. | +| `ps` | Show currently running models. | +| `cp` | Duplicate an existing model locally. | +| `rm` | Remove a model from the local system. | +| `help [command]` | Provide help information for a command. | + +### Alias + +The plugin includes an alias for convenience: + +- `o`: This is an alias for the `ollama` command, allowing you to use `o` as a shorthand for executing Ollama commands. Useful when jumping around the command line frequently. + +```sh +>>> o ls +NAME ID SIZE MODIFIED +deepseek-r1:14b-qwen-distill-q8_0 022efe288297 15 GB 3 hours ago +deepseek-r1:32b 38056bbcbb2d 19 GB 3 days ago +deepseek-r1:8b 28f8fd6cdc67 4.9 GB 3 days ago +deepseek-r1:70b 0c1615a8ca32 42 GB 3 days ago +``` + +## Notes + +- **Model Naming**: Models follow a `model:tag` format. If no tag is provided, Ollama defaults to `latest`. The model can be invoked with or without `latest` (e.g. `ollama run llama3.2` is equivalent to `ollama run llama3.2:latest`) +- **Multiline Input**: Use triple quotes (`"""`) for multiline prompts: + + ```zsh + > """What is the impact of AI on society? + ... Include specific examples.""" + ``` + +## License + +This project is licensed under the MIT License. + +For more details, visit the [Ollama CLI GitHub repository](https://github.com/ollama/ollama). + +Currently maintained by [sealad886](https://github.com/sealad886) diff --git a/plugins/ollama/ollama.plugin.zsh b/plugins/ollama/ollama.plugin.zsh new file mode 100644 index 000000000..64ee87e0c --- /dev/null +++ b/plugins/ollama/ollama.plugin.zsh @@ -0,0 +1,146 @@ +install_ollama_manpage() { + local manpage_source="${0:A:h}/ollama.1" # Path to the manpage in the plugin directory + local manpage_target_dir + local manpage_target + + # Determine the appropriate man directory based on the operating system + case "$(uname)" in + Linux|Darwin) + manpage_target_dir="/usr/local/share/man/man1" + ;; + *) + echo "Unsupported OS: $(uname). Manpage installation skipped." + return + ;; + esac + + manpage_target="${manpage_target_dir}/ollama.1" + + # Check if the manpage already exists + if [[ -f "$manpage_target" ]]; then + # silently stop if the manpage entry already exists + return + fi + + # Manpage does not exist; proceed with installation + if [[ -f "$manpage_source" ]]; then + # Ensure the target directory exists + if [[ ! -d "$manpage_target_dir" ]]; then + sudo mkdir -p "$manpage_target_dir" + fi + # Copy the manpage to the target directory + sudo cp "$manpage_source" "$manpage_target" + else + echo "Manpage source file not found: $manpage_source" + fi +} + +# Call the function to install the manpage +install_ollama_manpage + +# Function to retrieve available models for completion +_ollama_get_models() { + # Execute 'ollama list' and capture its output, suppressing any error messages + local models_output + models_output="$(ollama list 2>/dev/null)" + + # Initialize an array to hold the model suggestions + local -a models + local line + + # Read the output line by line + while IFS=" " read -r line; do + # Skip blank lines + [[ -z "$line" ]] && continue + + # Skip the header line that starts with 'NAME' + if [[ "$line" =~ ^NAME ]]; then + continue + fi + + # Split the line into words and extract the first word (model name:tag) + set -- $line + local suggestion="${$(echo $1 | cut -d ' ' -f 1)/:/\\:}" # Escape ':' by replacing it with '\:' + models+=( "$suggestion" ) # Add the escaped model name to the array + done <<< "$models_output" + + # Use the '_describe' function to provide the model suggestions for completion + _describe -t models 'models' models +} + +# Main completion function for the 'ollama' command +_ollama() { + # Define an array of available commands with their descriptions + local -a commands + commands=( + 'serve:Start the Ollama server' + 'create:Create a model from a Modelfile' + 'show:Display information about a specific model' + 'run:Execute a model with a given prompt' + 'stop:Terminate a running model' + 'pull:Download a model from the registry' + 'push:Upload a model to the registry' + 'list:Display all available models' + 'ps:Show currently running models' + 'cp:Duplicate an existing model' + 'rm:Delete a model from the local system' + 'help:Provide help information for a command' + ) + + # Initialize context variables for the completion + local context curcontext="$curcontext" state line + local -A opt_args + + # Define the arguments and options for the 'ollama' command + _arguments -C \ + '(-h --help)'{-h,--help}'[Display help information]' \ + '(-v --version)'{-v,--version}'[Show version information]' \ + '1: :->command' \ + '*:: :->args' + + # Determine the state of the completion (command or arguments) + case $state in + command) + # Provide command suggestions + _describe -t commands 'ollama commands' commands + ;; + args) + # Handle argument completion based on the specified command + case $words[1] in + run|rm|stop|show|pull|push) + # For these commands, provide model name suggestions + _ollama_get_models + ;; + cp) + if [[ $CURRENT -eq 2 ]]; then + # For the 'cp' command, suggest source model names + _ollama_get_models + elif [[ $CURRENT -eq 3 ]]; then + # For the 'cp' command, prompt for the destination model name + _message 'destination model name' + fi + ;; + create) + # For the 'create' command, suggest Modelfile paths + _arguments \ + '(-f --filename)'{-f,--filename}'[Specify the path to the Modelfile]:Modelfile:_files' + ;; + serve) + # For the 'serve' command, suggest specifying the port number + _arguments \ + '(-p --port)'{-p,--port}'[Specify the port number]:port number:' + ;; + *) + # For any other commands, use the default completion + _default + ;; + esac + ;; + esac +} + +# Register the '_ollama' function as the completion handler for the 'ollama' command +compdef _ollama ollama + +# Register aliases +alias o=ollama From 7e4b330e98993f0b2b437fac92bed9c27375657d Mon Sep 17 00:00:00 2001 From: sealad886 Date: Mon, 27 Jan 2025 09:49:43 +0000 Subject: [PATCH 2/4] Took out the manpage parts. --- plugins/ollama/ollama.plugin.zsh | 40 -------------------------------- 1 file changed, 40 deletions(-) diff --git a/plugins/ollama/ollama.plugin.zsh b/plugins/ollama/ollama.plugin.zsh index 64ee87e0c..14412e32f 100644 --- a/plugins/ollama/ollama.plugin.zsh +++ b/plugins/ollama/ollama.plugin.zsh @@ -1,43 +1,3 @@ -install_ollama_manpage() { - local manpage_source="${0:A:h}/ollama.1" # Path to the manpage in the plugin directory - local manpage_target_dir - local manpage_target - - # Determine the appropriate man directory based on the operating system - case "$(uname)" in - Linux|Darwin) - manpage_target_dir="/usr/local/share/man/man1" - ;; - *) - echo "Unsupported OS: $(uname). Manpage installation skipped." - return - ;; - esac - - manpage_target="${manpage_target_dir}/ollama.1" - - # Check if the manpage already exists - if [[ -f "$manpage_target" ]]; then - # silently stop if the manpage entry already exists - return - fi - - # Manpage does not exist; proceed with installation - if [[ -f "$manpage_source" ]]; then - # Ensure the target directory exists - if [[ ! -d "$manpage_target_dir" ]]; then - sudo mkdir -p "$manpage_target_dir" - fi - # Copy the manpage to the target directory - sudo cp "$manpage_source" "$manpage_target" - else - echo "Manpage source file not found: $manpage_source" - fi -} - -# Call the function to install the manpage -install_ollama_manpage - # Function to retrieve available models for completion _ollama_get_models() { # Execute 'ollama list' and capture its output, suppressing any error messages From d94d2bf8d12d559020cd5e4be73149f164043929 Mon Sep 17 00:00:00 2001 From: sealad886 Date: Mon, 27 Jan 2025 13:08:12 +0000 Subject: [PATCH 3/4] alias stuff removed --- plugins/ollama/README.md | 6 ------ plugins/ollama/ollama.plugin.zsh | 9 ++++----- 2 files changed, 4 insertions(+), 11 deletions(-) diff --git a/plugins/ollama/README.md b/plugins/ollama/README.md index 8a30c622a..f26f38cf9 100644 --- a/plugins/ollama/README.md +++ b/plugins/ollama/README.md @@ -60,12 +60,6 @@ The plugin provides autocompletion and enhanced functionality for the following | `rm` | Remove a model from the local system. | | `help [command]` | Provide help information for a command. | -### Alias - -The plugin includes an alias for convenience: - -- `o`: This is an alias for the `ollama` command, allowing you to use `o` as a shorthand for executing Ollama commands. Useful when jumping around the command line frequently. - ```sh >>> o ls NAME ID SIZE MODIFIED diff --git a/plugins/ollama/ollama.plugin.zsh b/plugins/ollama/ollama.plugin.zsh index 14412e32f..b288bbc18 100644 --- a/plugins/ollama/ollama.plugin.zsh +++ b/plugins/ollama/ollama.plugin.zsh @@ -68,8 +68,10 @@ _ollama() { # Handle argument completion based on the specified command case $words[1] in run|rm|stop|show|pull|push) - # For these commands, provide model name suggestions - _ollama_get_models + # For these commands, provide model name suggestions exactly once + if [[ $CURRENT -eq 2 ]]; then + _ollama_get_models + fi ;; cp) if [[ $CURRENT -eq 2 ]]; then @@ -101,6 +103,3 @@ _ollama() { # Register the '_ollama' function as the completion handler for the 'ollama' command compdef _ollama ollama - -# Register aliases -alias o=ollama From 1b1e6c9546f7cce0dfefd59d039e7458d168745b Mon Sep 17 00:00:00 2001 From: sealad886 Date: Mon, 27 Jan 2025 15:25:01 +0000 Subject: [PATCH 4/4] trying to get flags to work. some movement, but not quite there yet. --- plugins/ollama/README.md | 7 ++ plugins/ollama/ollama.plugin.zsh | 194 +++++++++++++++++++++---------- 2 files changed, 137 insertions(+), 64 deletions(-) diff --git a/plugins/ollama/README.md b/plugins/ollama/README.md index f26f38cf9..9224f9320 100644 --- a/plugins/ollama/README.md +++ b/plugins/ollama/README.md @@ -31,6 +31,13 @@ This plugin enhances your Zsh shell environment by integrating powerful features omz plugin enable ollama ``` + In order to get the most benefit from completions, with helpful usage hints, etc: + ```sh + # ~/.zshrc + # add the following zstyle entry wherever you want + zstyle ':completion:*:*:*:*:descriptions' format '%F{green}%d%f' + ``` + 2. **Restart Your Shell** Apply the changes by reloading Oh-My-Zsh: diff --git a/plugins/ollama/ollama.plugin.zsh b/plugins/ollama/ollama.plugin.zsh index b288bbc18..e57e3b080 100644 --- a/plugins/ollama/ollama.plugin.zsh +++ b/plugins/ollama/ollama.plugin.zsh @@ -1,38 +1,50 @@ -# Function to retrieve available models for completion -_ollama_get_models() { - # Execute 'ollama list' and capture its output, suppressing any error messages - local models_output - models_output="$(ollama list 2>/dev/null)" +# ------------------------------------------------------------------------------ +# ollama.plugin.zsh +# +# Plugin providing Zsh completions for the `ollama` command. +# ------------------------------------------------------------------------------ - # Initialize an array to hold the model suggestions +# ------------------------------------------------------------------------------ +# Function: _ollama_get_models +# Purpose: Retrieves the list of available models for completion. +# Uses `ollama list` with a short timeout and provides candidates. +# ------------------------------------------------------------------------------ +_ollama_get_models() { + local models_output + local timeout=5 # Timeout duration in seconds + + # Attempt to fetch models via `ollama list`; if it fails, show a short message. + models_output="$(timeout $timeout ollama list 2>/dev/null)" || { + _message "Failed to fetch models" + return 1 + } + + # Accumulate parsed model names here local -a models local line + while IFS= read -r line; do + # Skip blank lines and header lines (starting with NAME) + [[ -z "$line" || "$line" =~ ^NAME ]] && continue - # Read the output line by line - while IFS=" " read -r line; do - # Skip blank lines - [[ -z "$line" ]] && continue - - # Skip the header line that starts with 'NAME' - if [[ "$line" =~ ^NAME ]]; then - continue - fi - - # Split the line into words and extract the first word (model name:tag) - set -- $line - local suggestion="${$(echo $1 | cut -d ' ' -f 1)/:/\\:}" # Escape ':' by replacing it with '\:' - models+=( "$suggestion" ) # Add the escaped model name to the array + # Extract the first column and escape any colons for safety + local suggestion="${line%% *}" + suggestion="${suggestion/:/\\:}" + models+=("$suggestion") done <<< "$models_output" - # Use the '_describe' function to provide the model suggestions for completion + # Provide model suggestions using `_describe` _describe -t models 'models' models } -# Main completion function for the 'ollama' command +# ------------------------------------------------------------------------------ +# Function: _ollama +# Purpose: The main completion function for the `ollama` CLI. Determines which +# subcommand is being completed, then sets up the corresponding flags +# and suggestions. +# ------------------------------------------------------------------------------ _ollama() { - # Define an array of available commands with their descriptions - local -a commands - commands=( + # List of top-level commands and their descriptions + local -a commands=( 'serve:Start the Ollama server' 'create:Create a model from a Modelfile' 'show:Display information about a specific model' @@ -47,59 +59,113 @@ _ollama() { 'help:Provide help information for a command' ) - # Initialize context variables for the completion - local context curcontext="$curcontext" state line + # Standard local variables used by _arguments + local curcontext="$curcontext" state line local -A opt_args - # Define the arguments and options for the 'ollama' command + # The main `_arguments` call for handling top-level options (e.g. -h, -v) + # and capturing the first positional argument -> subcommand, then the rest. _arguments -C \ '(-h --help)'{-h,--help}'[Display help information]' \ '(-v --version)'{-v,--version}'[Show version information]' \ '1: :->command' \ '*:: :->args' - # Determine the state of the completion (command or arguments) + # If the user is trying to complete the first argument (the subcommand), + # then we present them the `commands` array above. case $state in command) - # Provide command suggestions _describe -t commands 'ollama commands' commands + return ;; - args) - # Handle argument completion based on the specified command - case $words[1] in - run|rm|stop|show|pull|push) - # For these commands, provide model name suggestions exactly once - if [[ $CURRENT -eq 2 ]]; then - _ollama_get_models - fi - ;; - cp) - if [[ $CURRENT -eq 2 ]]; then - # For the 'cp' command, suggest source model names - _ollama_get_models - elif [[ $CURRENT -eq 3 ]]; then - # For the 'cp' command, prompt for the destination model name - _message 'destination model name' - fi - ;; - create) - # For the 'create' command, suggest Modelfile paths - _arguments \ - '(-f --filename)'{-f,--filename}'[Specify the path to the Modelfile]:Modelfile:_files' - ;; - serve) - # For the 'serve' command, suggest specifying the port number - _arguments \ - '(-p --port)'{-p,--port}'[Specify the port number]:port number:' - ;; - *) - # For any other commands, use the default completion - _default - ;; - esac + esac + + # If the first argument is known, proceed with subcommand-specific completions + case $words[1] in + serve) + _arguments \ + '(-p --port)'{-p,--port}'[Specify the port number]:port number:' + ;; + + create) + # If user typed only `ollama create ` (with no second arg), + # display a short message to remind them to name the new model + if [[ $CURRENT -eq 2 ]]; then + _message 'Specify the new model name' + else + # Otherwise, offer flags for `create` + _arguments \ + '(-f --filename)'{-f,--filename}'[Path to the Modelfile]:Modelfile:_files' \ + '(-q --quantize)'{-q,--quantize}'[Quantization method (e.g. q4_0)]' \ + '--prefix[Set a prefix for the created model]' \ + '(-h --help)--help[Show help for create]' + fi + ;; + + show) + _message 'Usage: ollama show MODEL [flags]' + if [[ $CURRENT -eq 2 ]]; then + _ollama_get_models + else + _arguments \ + '--license[Show the model’s license]' \ + '--modelfile[Show the model’s Modelfile]' \ + '--parameters[Show model parameters]' \ + '--system[Show the system message of the model]' \ + '--template[Show the model’s template]' \ + '(-h --help)--help[Show help for show]' + fi + ;; + + run) + # Display usage message only if there's no argument yet + if [[ $CURRENT -eq 2 ]]; then + _message "Usage: ollama run MODEL [PROMPT] [flags]" + _ollama_get_models + else + # Define flags for the `run` command + local -a _run_flags=( + '--format-string=[Format string for the output (e.g. json)]' + '--insecure[Use an insecure registry]' + '--keepalive=[Time to keep the model loaded (e.g. 5m)]' + '--nowordwrap[Disable word wrapping]' + '--verbose[Show response timings]' + '(-h --help)--help[Show help for run]' + ) + + # Use a mix of `_arguments` and manual handling for freeform input + if [[ $CURRENT -eq 3 ]]; then + # Suggest a freeform prompt (arbitrary input) + _message "Enter a prompt as a string" + else + # Provide flag completions + _arguments -S "${_run_flags[@]}" + fi + fi + ;; + + cp) + # The `cp` command expects `ollama cp SOURCE DEST` + if [[ $CURRENT -eq 2 ]]; then + _ollama_get_models + elif [[ $CURRENT -eq 3 ]]; then + _message 'Specify the destination model name' + fi + ;; + + rm|stop|pull|push) + # All of these commands accept one or more model names + if [[ $CURRENT -eq 2 ]]; then + _ollama_get_models + fi + ;; + + # If the subcommand doesn’t match anything above, fall back to default + *) + _default ;; esac } -# Register the '_ollama' function as the completion handler for the 'ollama' command +# Finally, register the completion function for the `ollama` command compdef _ollama ollama