# ChatMastermind

ChatMastermind is a Python application that automates conversation with AI, stores question-answer pairs with tags, and composes relevant chat history for the next question.

The project uses the OpenAI API to generate responses and stores the data in YAML files. It also allows you to filter chat history based on tags and supports autocompletion for tags.

Official repository URL: https://kaizenkodo.no/gitea/kaizenkodo/ChatMastermind.git

## Requirements

- Python 3.9 or higher
- openai
- PyYAML
- argcomplete

You can install these requirements using `pip`:

```bash
pip install -r requirements.txt
```

## Installation

You can install the package with the requirements using `pip`:

```bash
pip install .
```

## Usage

The `cmm` script has global options, a list of commands, and options per command:

```bash
cmm [global options] command [command options]
```

### Global Options

- `-C`, `--config`: Config file name (defaults to `.config.yaml`).

### Command Options

#### Question

The `question` command is used to ask, create, and process questions.

```bash
cmm question [-t OTAGS]... [-k ATAGS]... [-x XTAGS]... [-o OUTTAGS]... [-A AI] [-M MODEL] [-n NUM] [-m MAX] [-T TEMP] (-a ASK | -c CREATE | -r REPEAT | -p PROCESS) [-O] [-s SOURCE]... [-S SOURCE]...
```

* `-t, --or-tags OTAGS` : List of tags (one must match)
* `-k, --and-tags ATAGS` : List of tags (all must match)
* `-x, --exclude-tags XTAGS` : List of tags to exclude
* `-o, --output-tags OUTTAGS` : List of output tags (default: use input tags)
* `-A, --AI AI` : AI ID to use
* `-M, --model MODEL` : Model to use
* `-n, --num-answers NUM` : Number of answers to request
* `-m, --max-tokens MAX` : Max. number of tokens
* `-T, --temperature TEMP` : Temperature value
* `-a, --ask ASK` : Ask a question
* `-c, --create CREATE` : Create a question
* `-r, --repeat REPEAT` : Repeat a question
* `-p, --process PROCESS` : Process existing questions
* `-O, --overwrite` : Overwrite existing messages when repeating them
* `-s, --source-text SOURCE` : Add content of a file to the query
* `-S, --source-code SOURCE` : Add source code file content to the chat history

#### Hist

The `hist` command is used to print the chat history.

```bash
cmm hist [-t OTAGS]... [-k ATAGS]... [-x XTAGS]... [-w] [-W] [-S] [-A ANSWER] [-Q QUESTION]
```

* `-t, --or-tags OTAGS` : List of tags (one must match)
* `-k, --and-tags ATAGS` : List of tags (all must match)
* `-x, --exclude-tags XTAGS` : List of tags to exclude
* `-w, --with-tags` : Print chat history with tags
* `-W, --with-files` : Print chat history with filenames
* `-S, --source-code-only` : Print only source code
* `-A, --answer ANSWER` : Search for answer substring
* `-Q, --question QUESTION` : Search for question substring

#### Tags

The `tags` command is used to manage tags.

```bash
cmm tags (-l | -p PREFIX | -c CONTENT)
```

* `-l, --list` : List all tags and their frequency
* `-p, --prefix PREFIX` : Filter tags by prefix
* `-c, --contain CONTENT` : Filter tags by contained substring

#### Config

The `config` command is used to manage the configuration.

```bash
cmm config (-l | -m | -c CREATE)
```

* `-l, --list-models` : List all available models
* `-m, --print-model` : Print the currently configured model
* `-c, --create CREATE` : Create config with default settings in the given file

#### Print

The `print` command is used to print message files.

```bash
cmm print -f FILE [-q | -a | -S]
```

* `-f, --file FILE` : File to print
* `-q, --question` : Print only question
* `-a, --answer` : Print only answer
* `-S, --only-source-code` : Print only source code

### Examples

1. Ask a question:

```bash
cmm question -a "What is the meaning of life?" -t philosophy -x religion
```

2. Display the chat history:

```bash
cmm hist
```

3. Filter chat history by tags:

```bash
cmm hist --or-tags tag1 tag2
```

4. Exclude chat history by tags:

```bash
cmm hist --exclude-tags tag3 tag4
```

5. List all tags and their frequency:

```bash
cmm tags -l
```

6. Print the contents of a file:

```bash
cmm print -f example.yaml
```

## Configuration

The configuration file (`.config.yaml`) should contain the following fields:

- `openai`:
  - `api_key`: Your OpenAI API key.
  - `model`: The name of the OpenAI model to use (e.g. "text-davinci-002").
  - `temperature`: The temperature value for the model.
  - `max_tokens`: The maximum number of tokens for the model.
  - `top_p`: The top P value for the model.
  - `frequency_penalty`: The frequency penalty value.
  - `presence_penalty`: The presence penalty value.
- `system`: The system message used to set the behavior of the AI.
- `db`: The directory where the question-answer pairs are stored in YAML files.

## Autocompletion

To activate autocompletion for tags, add the following line to your shell's configuration file (e.g., `.bashrc`, `.zshrc`, or `.profile`):

```bash
eval "$(register-python-argcomplete cmm)"
```

After adding this line, restart your shell or run `source <your-shell-config-file>` to enable autocompletion for the `cmm` script.

## Contributing

### Enable commit hooks
```
pip install pre-commit
pre-commit install
```
### Execute tests before opening a PR
```
pytest
```
### Consider using `pyenv` / `pyenv-virtualenv`
Short installation instructions:
* install `pyenv`:
```
cd ~
git clone https://github.com/pyenv/pyenv .pyenv
cd ~/.pyenv && src/configure && make -C src
```
* make sure that `~/.pyenv/shims` and `~/.pyenv/bin` are the first entries in your `PATH`, e. g. by setting it in `~/.bashrc`
* add the following to your `~/.bashrc` (after setting `PATH`): `eval "$(pyenv init -)"`
* create a new terminal or source the changes (e. g. `source ~/.bashrc`)
* install `virtualenv`
```
git clone https://github.com/pyenv/pyenv-virtualenv.git $(pyenv root)/plugins/pyenv-virtualenv
```
* add the following to your `~/.bashrc` (after the commands above): `eval "$(pyenv virtualenv-init -)`
* create a new terminal or source the changes (e. g. `source ~/.bashrc`)
* go back to the `ChatMasterMind` repo and create a virtual environment with the latest `Python`, e. g. `3.11.4`:
```
cd <CMM_REPO_PATH>
pyenv install 3.11.4
pyenv virtualenv 3.11.4 py311
pyenv activate py311
```
* see also the [official pyenv documentation](https://github.com/pyenv/pyenv#readme)

## License

This project is licensed under the terms of the WTFPL License.