diff --git a/.gitignore b/.gitignore index a3aaae2..9070819 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,4 @@ __pycache__ /build /dist /src/chap/__version__.py +/venv diff --git a/README.md b/README.md index 81f9381..5ee9552 100644 --- a/README.md +++ b/README.md @@ -13,25 +13,57 @@ SPDX-License-Identifier: MIT ## System requirements -Chap is developed on Linux with Python 3.11. Due to use of the `list[int]` style of type hints, it is known not to work on 3.8 and older; the target minimum Python version is 3.9 (debian oldstable). +Chap is developed on Linux with Python 3.11. Due to use of the `list[int]` style of type hints, it is known to not work on Python 3.8 and older. The target minimum Python version is 3.9 (debian oldstable). ## Installation -Install with e.g., `pipx install chap`, or `pip install chap` in a virtual environment. +If you want `chap` available as a command, just install with `pipx install chap` or `pip install chap`. + +Use a virtual environment unless you want it installed globally. ## Installation for development -Install in developer mode e.g., with `pip install -e .`. -In this mode, you get the "chap" commandline program installed but can edit the source files in place. -This is the [recommended practice per PyPA](https://setuptools.pypa.io/en/latest/userguide/development_mode.html). +Use one of the following two methods to run `chap` as a command, with the ability to edit the source files. You are welcome to submit valuable changes as [a pull request](https://github.com/jepler/chap/pulls). -A shim script `chap.py` is included so that the older development style of `pip install -r requirements.txt` + `python chap.py` (or `./chap.py`) functions as well. +### Via `pip install --editable .` + +This is an "editable install", as [recommended by the Python Packaging Authority](https://setuptools.pypa.io/en/latest/userguide/development_mode.html). + +Change directory to the root of the `chap` project. + +Activate your virtual environment, then install `chap` in development mode: + +```shell +pip install --editable . +``` + +In this mode, you get the `chap` command-line program installed, but you are able to edit the source files in the `src` directory in place. + +### Via `chap-dev.py` + +A simple shim script called `chap-dev.py` is included to demonstrate how to load and run the `chap` library without installing `chap` in development mode. This method may be more familiar to some developers. + +Change directory to the root of the `chap` project. + +Activate your virtual environment, then install requirements: + +```shell +pip install -r requirements.txt +``` + +Run the shim script (with optional command flags as appropriate): + +```shell +./chap-dev.py +``` + +In this mode, you can edit the source files in the `src` directory in place, and the shim script will pick up the changes via the `import` directive. ## Configuration Put your OpenAI API key in the platform configuration directory for chap, e.g., on linux/unix systems at `~/.config/chap/openai_api_key` -## Commandline usage +## Command-line usage * `chap ask "What advice would you give a 20th century human visiting the 21st century for the first time?"` @@ -42,11 +74,11 @@ Put your OpenAI API key in the platform configuration directory for chap, e.g., * `chap grep needle` ## Interactive terminal usage - * chap tui + * `chap tui` -## Sessions & Commandline Parameters +## Sessions & Command-line Parameters -Details of session handling & commandline arguments are in flux. +Details of session handling & command-line arguments are in flux. By default, a new session is created. It is saved to the user's state directory (e.g., `~/.local/state/chap` on linux/unix systems). @@ -68,12 +100,16 @@ You can select the text generating backend with the `-b` flag: ## Environment variables -The backend can be set with `CHAP_BACKEND`. +The backend can be set with the `CHAP_BACKEND` environment variable. + Backend settings can be set with `CHAP__`, with `backend_name` and `parameter_name` all in caps. + For instance, `CHAP_LLAMA_CPP_URL=http://server.local:8080/completion` changes the default server URL for the llama\_cpp back-end. ## Importing from ChatGPT -The userscript https://github.com/pionxzh/chatgpt-exporter can export chat logs from chat.openai.com in a json format. -This format is different than chap's, especially since chap currently only represents a single branch of conversation in one log. -You can use the `chap import` command to import all the branches of a chatgpt-style chatlog in json format into a series of chap-style chat logs. +The userscript https://github.com/pionxzh/chatgpt-exporter can export chat logs from chat.openai.com in a JSON format. + +This format is different than chap's, especially since `chap` currently only represents a single branch of conversation in one log. + +You can use the `chap import` command to import all the branches of a chatgpt-style chatlog in JSON format into a series of `chap`-style chat logs. diff --git a/chap-dev.py b/chap-dev.py new file mode 100755 index 0000000..7926f1b --- /dev/null +++ b/chap-dev.py @@ -0,0 +1,22 @@ +#!/usr/bin/env python3 +# SPDX-FileCopyrightText: 2023 Jeff Epler +# +# SPDX-License-Identifier: MIT + +# chap-dev.py - Simple shim script to demonstrate how to use the chap library. + +import pathlib +import sys + +# Ensure the 'src' directory is on the system path so we can import 'chap' +project_root = pathlib.Path(__file__).parent +src_path = project_root / "src" +sys.path.insert(0, str(src_path)) + +if __name__ == "__main__": + # pylint: disable=import-error,no-name-in-module + from chap.core import main + + main() +else: + raise ImportError("'chap-dev.py' is meant for direct execution, not for import.") diff --git a/chap.py b/chap.py deleted file mode 100755 index c597cde..0000000 --- a/chap.py +++ /dev/null @@ -1,19 +0,0 @@ -#!/usr/bin/env python3 -# SPDX-FileCopyrightText: 2023 Jeff Epler -# -# SPDX-License-Identifier: MIT - -import pathlib -import sys - -sys.path[0] = str(pathlib.Path(__file__).parent / "src") - -if __name__ == "__main__": - # pylint: disable=import-error,no-name-in-module - from chap.core import main - - main() -else: - raise ImportError( - "this script exists to facilitate running 'python -mchap' in the top directory; it should not be imported" - )