izzilis/README.md

# izzilis gpt-2 bot

Meant to be used with a [finetuned GPT-2 model](https://medium.com/ai-innovation/beginners-guide-to-retrain-gpt-2-117m-to-generate-custom-text-content-8bb5363d8b7f)

## Usage

To run the bot, you need a valid `bot_config.json` file at the path where you're running the bot.
If you do not have one, izzilis will generate a default one for you to fill out.

This bot currently *requires* a Telegram bot token to work, as there is no option to disable curation.
To create a bot, please use the [Botfather](https://t.me/botfather). Once created, and running, set a channel for the bot to post curation options in via the `/setmain` bot command. Usually this requires sending `/setmain@bot_username` to the chat with the bot (can be group chats).

This default uses the `Misskey` publisher. If you want to publish to Mastodon, Pleroma, or any other mastodon-compatible API, please replace `Misskey` in the `publisher` object with `Mastodon`.

## Config values

| Name               | Value                                                                                          |
|--------------------|------------------------------------------------------------------------------------------------|
| `python_path`      | The path to the system's python3 interpreter                                                   |
| `model_name`       | The name of the GPT-2 model to use (see gpt-2 docs)                                            |
| `temperature`      | The `temperature` value to call gpt-2 with (see gpt-2 docs)                                    |
| `top_k`            | The `top_k` value to call gpt-2 with (see gpt-2 docs)                                          |
| `gpt_code_path`    | The path to where the gpt-2 source & models are located                                        |
| `interval_seconds` | See [interval_seconds](#interval_seconds)                                                      |
| `bot_token`        | Telegram Bot API token                                                                         |
| `chat_ref`         | The chat reference ID for the telegram bot, leave at 0, will be filled once `/setmain` is sent |
| `post_buffer`      | How many curated samples the bot will hold at maximum at a time                                |
| `publisher`        | See [publisher](#publisher)                                                                    |


### interval_seconds

| Name  | Value                                           |
|-------|-------------------------------------------------|
| `min` | Minimum amount of seconds to wait between posts |
| `max` | Maximum amount of seconds to wait between posts |

### publisher

The publisher can currently hold one of two JSON objects, named either `Mastodon` or `Misskey`, which determines which posting API it will use. Whether the object is `Misskey` or `Mastodon`, it has the following members:

| Name         | Value                                                                                                      |
|--------------|------------------------------------------------------------------------------------------------------------|
| `base_url`   | The base URL of the instance                                                                               |
| `token`      | The auth token for the account, leave empty for `Mastodon` as you will be prompted to log in and authorize |
| `visibility` | The visibility scope of the statuses to be posted. These differ between publishers, see the list below     |

**Misskey visibility values**

* `Public` (Global)
* `Home`
* `Followers`
* `Specified` (DMs)

**Mastodon-comptaibles visibility values**

* `public` (Global)
* `unlisted` (Home)
* `private` (Followers only)
* `direct` (DMs)

An example `Misskey` publisher entry looks like this:
```json
	"publisher": {
		"Misskey": {
			"base_url": "",
			"token": "",
			"visibility": "Public"
		}
	}
```

And for mastodon/pleroma:
```json
	"publisher": {
		"Mastodon": {
			// Token will be set by izzilis on authentication (requires interactive)
			"base_url": "",
			"visibility": "public"
		}
	}
```