CLI Improvements (#1021)

* Add gpt4all-bindings/cli/README.md

* Unify version information
- Was previously split; base one on the other
- Add VERSION_INFO as the "source of truth":
  - Modelled after sys.version_info.
  - Implemented as a tuple, because it's much easier for (partial)
    programmatic comparison.
- Previous API is kept intact.

* Add gpt4all-bindings/cli/developer_notes.md
- A few notes on what's what, especially regarding docs

* Add gpt4all-bindings/python/docs/gpt4all_cli.md
- The CLI user documentation

* Bump CLI version to 0.3.5

* Finalise docs & add to index.md
- Amend where necessary
- Fix typo in gpt4all_cli.md
- Mention and add link to CLI doc in index.md

* Add docstings to gpt4all-bindings/cli/app.py

* Better 'groovy' link & fix typo
- Documentation: point to the Hugging Face model card for 'groovy'
- Correct typo in app.py

gpt4all-bindings/cli/README.md

@@ -0,0 +1,44 @@
+# GPT4All Command-Line Interface (CLI)
+
+GPT4All on the command-line.
+
+## Documentation
+<https://docs.gpt4all.io/gpt4all_cli.html>
+
+## Quickstart
+
+The CLI is based on the `gpt4all` Python bindings and the `typer` package.
+
+The following shows one way to get started with the CLI, the documentation has more information.
+Typically, you will want to replace `python` with `python3` on _Unix-like_ systems and `py -3` on
+_Windows_. Also, it's assumed you have all the necessary Python components already installed.
+
+The CLI is a self-contained Python script named [app.py] ([download][app.py-download]). As long as
+its package dependencies are present, you can download and run it from wherever you like.
+
+[app.py]: https://github.com/nomic-ai/gpt4all/blob/main/gpt4all-bindings/cli/app.py
+[app.py-download]: https://raw.githubusercontent.com/nomic-ai/gpt4all/main/gpt4all-bindings/cli/app.py
+
+```shell
+# optional but recommended: create and use a virtual environment
+python -m venv gpt4all-cli
+```
+_Windows_ and _Unix-like_ systems differ slightly in how you activate a _virtual environment_:
+- _Unix-like_, typically: `. gpt4all-cli/bin/activate`
+- _Windows_: `gpt4all-cli\Scripts\activate`
+
+Then:
+```shell
+# pip-install the necessary packages; omit '--user' if using a virtual environment
+python -m pip install --user --upgrade gpt4all typer
+# run the CLI
+python app.py repl
+```
+By default, it will automatically download the `groovy` model to `.cache/gpt4all/` in your user
+directory, if necessary.
+
+If you have already saved a model beforehand, specify its path with the `-m`/`--model` argument,
+for example:
+```shell
+python app.py repl --model /home/user/my-gpt4all-models/GPT4All-13B-snoozy.ggmlv3.q4_0.bin
+```

gpt4all-bindings/cli/app.py

@@ -1,9 +1,17 @@
+"""GPT4All CLI
+
+The GPT4All CLI is a self-contained script based on the `gpt4all` and `typer` packages. It offers a
+REPL to communicate with a language model similar to the chat GUI application, but more basic.
+"""
+
 import sys
 import typer
 
+from collections import namedtuple
 from typing_extensions import Annotated
 from gpt4all import GPT4All
 
+
 MESSAGES = [
     {"role": "system", "content": "You are a helpful assistant."},
     {"role": "user", "content": "Hello there."},
@@ -17,7 +25,9 @@ SPECIAL_COMMANDS = {
     "/help": lambda _: print("Special commands: /reset, /exit, /help and /clear"),
 }
 
-VERSION = "0.3.4"
+VersionInfo = namedtuple('VersionInfo', ['major', 'minor', 'micro'])
+VERSION_INFO = VersionInfo(0, 3, 5)
+VERSION = '.'.join(map(str, VERSION_INFO))  # convert to string form, like: '1.2.3'
 
 CLI_START_MESSAGE = f"""
     
@@ -47,6 +57,7 @@ def repl(
         typer.Option("--n-threads", "-t", help="Number of threads to use for chatbot"),
     ] = None,
 ):
+    """The CLI read-eval-print loop."""
     gpt4all_instance = GPT4All(model)
 
     # if threads are passed, set them
@@ -103,7 +114,8 @@ def repl(
 
 @app.command()
 def version():
-    print("gpt4all-cli v0.3.4")
+    """The CLI version command."""
+    print(f"gpt4all-cli v{VERSION}")
 
 
 if __name__ == "__main__":

gpt4all-bindings/cli/developer_notes.md

@@ -0,0 +1,25 @@
+# Developing the CLI
+## Documentation
+Documentation can be found in three places:
+- `app.py` docstrings & comments
+- a Readme: `gpt4all-bindings/cli/README.md`
+- the actual CLI documentation: `gpt4all-bindings/python/docs/gpt4all_cli.md`
+
+The _docstrings_ are meant for programmatic use. Since the CLI is primarily geared towards users and
+not to build on top, they're kept terse.
+
+The _Readme_ is mostly meant for users and includes:
+- a link to the _CLI documentation_ (on the [website])
+- a Quickstart section with some guidance on how to get started with a sane setup
+
+The _CLI documentation_ and other documentation are located in the above mentioned `docs/` folder.
+They're in Markdown format and built for the [website]. Of the three, they should be the most
+detailed.
+
+[website]: https://docs.gpt4all.io/gpt4all_cli.html
+
+
+## Versioning
+The version number should now follow the `gpt4all` PyPI package, so compatibility is more clear.
+
+The one place to change it is the `namedtuple` called `VERSION_INFO`.

gpt4all-bindings/python/docs/gpt4all_cli.md

@@ -0,0 +1,198 @@
+# GPT4All CLI
+
+The GPT4All command-line interface (CLI) is a Python script which is built on top of the
+[Python bindings][docs-bindings-python] ([repository][repo-bindings-python]) and the [typer]
+package. The source code, README, and local build instructions can be found
+[here][repo-bindings-cli].
+
+[docs-bindings-python]: gpt4all_python.html
+[repo-bindings-python]: https://github.com/nomic-ai/gpt4all/tree/main/gpt4all-bindings/python
+[repo-bindings-cli]: https://github.com/nomic-ai/gpt4all/tree/main/gpt4all-bindings/cli
+[typer]: https://typer.tiangolo.com/
+
+## Installation
+### The Short Version
+
+The CLI is a Python script called [app.py]. If you're already familiar with Python best practices,
+the short version is to [download app.py][app.py-download] into a folder of your choice, install
+the two required dependencies with some variant of:
+```shell
+pip install gpt4all typer
+```
+
+Then run it with a variant of:
+```shell
+python app.py repl
+```
+In case you're wondering, _REPL_ is an acronym for [read-eval-print loop][wiki-repl].
+
+[app.py]: https://github.com/nomic-ai/gpt4all/blob/main/gpt4all-bindings/cli/app.py
+[app.py-download]: https://raw.githubusercontent.com/nomic-ai/gpt4all/main/gpt4all-bindings/cli/app.py
+[wiki-repl]: https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop
+
+### Recommendations & The Long Version
+
+Especially if you have several applications/libraries which depend on Python, to avoid descending
+into dependency hell at some point, you should:
+- Consider to always install into some kind of [_virtual environment_][venv].
+- On a _Unix-like_ system, don't use `sudo` for anything other than packages provided by the system
+  package manager, i.e. never with `pip`.
+
+[venv]: https://docs.python.org/3/library/venv.html
+
+There are several ways and tools available to do this, so below are descriptions on how to install
+with a _virtual environment_ (recommended) or a user installation on all three main platforms.
+
+Different platforms can have slightly different ways to start the Python interpreter itself.
+
+Note: _Typer_ has an optional dependency for more fanciful output. If you want that, replace `typer`
+with `typer[all]` in the pip-install instructions below.
+
+#### Virtual Environment Installation
+You can name your _virtual environment_ folder for the CLI whatever you like. In the following,
+`gpt4all-cli` is used throughout.
+
+##### macOS
+
+There are at least three ways to have a Python installation on _macOS_, and possibly not all of them
+provide a full installation of Python and its tools. When in doubt, try the following:
+```shell
+python3 -m venv --help
+python3 -m pip --help
+```
+Both should print the help for the `venv` and `pip` commands, respectively. If they don't, consult
+the documentation of your Python installation on how to enable them, or download a separate Python
+variant, for example try an [unified installer package from python.org][python.org-downloads].
+
+[python.org-downloads]: https://www.python.org/downloads/
+
+Once ready, do:
+```shell
+python3 -m venv gpt4all-cli
+. gpt4all-cli/bin/activate
+python3 -m pip install gpt4all typer
+```
+
+##### Windows
+
+Download the [official installer from python.org][python.org-downloads] if Python isn't already
+present on your system.
+
+A _Windows_ installation should already provide all the components for a _virtual environment_. Run:
+```shell
+py -3 -m venv gpt4all-cli
+gpt4all-cli\Scripts\activate
+py -m pip install gpt4all typer
+```
+
+##### Linux
+
+On Linux, a Python installation is often split into several packages and not all are necessarily
+installed by default. For example, on Debian/Ubuntu and derived distros, you will want to ensure
+their presence with the following:
+```shell
+sudo apt-get install python3-venv python3-pip
+```
+The next steps are similar to the other platforms:
+```shell
+python3 -m venv gpt4all-cli
+. gpt4all-cli/bin/activate
+python3 -m pip install gpt4all typer
+```
+On other distros, the situation might be different. Especially the package names can vary a lot.
+You'll have to look it up in the documentation, software directory, or package search.
+
+#### User Installation
+##### macOS
+
+There are at least three ways to have a Python installation on _macOS_, and possibly not all of them
+provide a full installation of Python and its tools. When in doubt, try the following:
+```shell
+python3 -m pip --help
+```
+That should print the help for the `pip` command. If it doesn't, consult the documentation of your
+Python installation on how to enable them, or download a separate Python variant, for example try an
+[unified installer package from python.org][python.org-downloads].
+
+Once ready, do:
+```shell
+python3 -m pip install --user --upgrade gpt4all typer
+```
+
+##### Windows
+
+Download the [official installer from python.org][python.org-downloads] if Python isn't already
+present on your system. It includes all the necessary components. Run:
+```shell
+py -3 -m pip install --user --upgrade gpt4all typer
+```
+
+##### Linux
+
+On Linux, a Python installation is often split into several packages and not all are necessarily
+installed by default. For example, on Debian/Ubuntu and derived distros, you will want to ensure
+their presence with the following:
+```shell
+sudo apt-get install python3-pip
+```
+The next steps are similar to the other platforms:
+```shell
+python3 -m pip install --user --upgrade gpt4all typer
+```
+On other distros, the situation might be different. Especially the package names can vary a lot.
+You'll have to look it up in the documentation, software directory, or package search.
+
+## Running the CLI
+
+The CLI is a self-contained script called [app.py]. As such, you can [download][app.py-download]
+and save it anywhere you like, as long as the Python interpreter has access to the mentioned
+dependencies.
+
+Note: different platforms can have slightly different ways to start Python. Whereas below the
+interpreter command is written as `python` you typically want to type instead:
+- On _Unix-like_ systems: `python3`
+- On _Windows_: `py -3`
+
+The simplest way to start the CLI is:
+```shell
+python app.py repl
+```
+This automatically selects the [groovy] model and downloads it into the `.cache/gpt4all/` folder
+of your home directory, if not already present.
+
+[groovy]: https://huggingface.co/nomic-ai/gpt4all-j#model-details
+
+If you want to use a different model, you can do so with the `-m`/`--model` parameter. If only a
+model file name is provided, it will again check in `.cache/gpt4all/` and might start downloading.
+If instead given a path to an existing model, the command could for example look like this:
+```shell
+python app.py repl --model /home/user/my-gpt4all-models/GPT4All-13B-snoozy.ggmlv3.q4_0.bin
+```
+
+When you're done and want to end a session, simply type `/exit`.
+
+To get help and information on all the available commands and options on the command-line, run:
+```shell
+python app.py --help
+```
+And while inside the running _REPL_, write `/help`.
+
+Note that if you've installed the required packages into a _virtual environment_, you don't need
+to activate that every time you want to run the CLI. Instead, you can just start it with the Python
+interpreter in the folder `gpt4all-cli/bin/` (_Unix-like_) or `gpt4all-cli/Script/` (_Windows_).
+
+That also makes it easy to set an alias e.g. in [Bash][bash-aliases] or [PowerShell][posh-aliases]:
+- Bash: `alias gpt4all="'/full/path/to/gpt4all-cli/bin/python' '/full/path/to/app.py' repl"`
+- PowerShell:
+  ```posh
+  Function GPT4All-Venv-CLI {"C:\full\path\to\gpt4all-cli\Scripts\python.exe" "C:\full\path\to\app.py" repl}
+  Set-Alias -Name gpt4all -Value GPT4All-Venv-CLI
+  ```
+
+Don't forget to save these in the start-up file of your shell.
+
+[bash-aliases]: https://www.gnu.org/software/bash/manual/html_node/Aliases.html
+[posh-aliases]: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/set-alias
+
+Finally, if on _Windows_ you see a box instead of an arrow `⇢` as the prompt character, you should
+change the console font to one which offers better Unicode support.

gpt4all-bindings/python/docs/index.md

@@ -12,7 +12,7 @@ is organized as a monorepo with the following structure:
 
 - **gpt4all-backend**: The GPT4All backend maintains and exposes a universal, performance optimized C API for running inference with multi-billion parameter transformer decoders.
 This C API is then bound to any higher level programming language such as C++, Python, Go, etc.
-- **gpt4all-bindings**: GPT4All bindings contain a variety of high-level programming languages that implement the C API. Each directory is a bound programming language.
+- **gpt4all-bindings**: GPT4All bindings contain a variety of high-level programming languages that implement the C API. Each directory is a bound programming language. The [CLI](gpt4all_cli.md) is included here, as well.
 - **gpt4all-api**: The GPT4All API (under initial development) exposes REST API endpoints for gathering completions and embeddings from large language models.
 - **gpt4all-chat**: GPT4All Chat is an OS native chat application that runs on OSX, Windows and Ubuntu. It is the easiest way to run local, privacy aware chat assistants on everyday hardware. You can download it on the [GPT4All Website](https://gpt4all.io) and read its source code in the monorepo.