1993.2.56 • Published 5 months ago

halbot v1993.2.56

Weekly downloads
-
License
MIT
Repository
github
Last release
5 months ago

🤖️ halbot

MIT licensed Node.js Package

Just another Gemini / ChatGPT / Claude / Ollama Telegram bob, which is simple design, easy to use, extendable and fun.

Live demo, click to watch on YouTube:

Features

  • Telegram Bot (Telegram Bot token required)
  • ChatGPT (OpenAI API key required)
  • Gemini (Google Gemini API Key required)
  • Claude (Anthropic API Key required)
  • Ollama (Install Ollama and serve your model)
  • Speech-to-Text (OpenAI or Google Cloud API key required, or your own engine)
  • Text-to-Speech (OpenAI or Google Cloud API key required, or your own engine)
  • Text-to-Image by DALL·E (OpenAI API key required, or your own engine)
  • OCR/OBJECT_DETECT (OpenAI or Google Cloud API key required, or your own engine)
  • Feeding webpage and YouTube to enhance your prompt
  • Custom prompt at your fingertips
  • Support private and public mode, with multiple authenticate methods.
  • Middleware style workflow, easy to extend.
  • Built-in support parsing webpages, YouTube videos, PDFs, images, Office documents, code files, text files...
  • Realtime stream-style response, no more waiting.
  • Multimodal support for all supported models.
  • Automatically selects the optimal model for the task.
  • Audio input and output support for supported models, not just TTS.
  • Google Search as a tool support for Gemini 2.0.
  • Markdown rendering
  • Reference rendering
  • Code block rendering, developers friendly.
  • Threaded conversation support.
  • ESM from the ground up

Basic usage

Configuration

Make the halbot json config file and put it in this path ~/.halbot.json.

Basic config demo:

{
    "telegramToken": "[[Telegram Bot API Token]]",
    "openaiApiKey": "[[OpenAI API Key]]"
}

All supported configuration fields:

{

    // REQUIRED, string.
    "telegramToken": "[[Telegram Bot API Token]]",

    // Set some of these fields if you need OpenAI's ChatGPT, Whisper, Embedding features.
    // OPTIONAL, string.
    "openaiApiKey": "[[OpenAI API Key]]",
    // OPTIONAL, string.
    "openaiEndpoint": "[[Custom OpenAI API endpoint]]",
    // OPTIONAL, string, default: "gpt-3.5-turbo".
    "chatGptModel": "[[Custom ChatGPT Model ID]]",
    // OPTIONAL, integer.
    "chatGptPriority": "[[Custom ChatGPT Priority]]",

    // Set some of these fields if you need Google's Gemini, TTS, STT, OCR, OBJECT_DETECT, Embedding features.
    // OPTIONAL, string.
    "googleApiKey": "[[Google Cloud / Gemini API Key]]",
    // OPTIONAL, string, default: "gemini-pro-vision".
    "geminiModel": "[[Custom Gemini Model ID]]",
    // OPTIONAL, integer
    "geminiPriority": "[[Custom Gemini Priority]]",

    // Set some of these fields if you need Anthropic's Claude features.
    // OPTIONAL, string.
    "claudeApiKey": "[[Anthropic API Key]]",
    // OPTIONAL, string.
    "credentials": "[[Vertex Anthropic Credentials]]",
    // OPTIONAL, string.
    "projectId": "[[Vertex Anthropic Credentials]]",
    // OPTIONAL, string, default: `latest claude model`.
    "claudeModel": "[[Custom Claude Model ID]]",
    // OPTIONAL, integer.
    "claudePriority": "[[Custom Claude Priority]]",

    // Set some of these fields if you need Azure's AI features.
    // OPTIONAL, string.
    "azureApiKey": "[[Azure API Key]]",
    // OPTIONAL, string.
    "azureEndpoint": "[[Azure API Endpoint]]",
    // OPTIONAL, string.
    "azureModel": "[[Custom Azure Model ID]]",
    // OPTIONAL, integer.
    "azurePriority": "[[Custom Azure Priority]]",

    // Set some of these fields if you need Ollama features.
    // OPTIONAL, boolean.
    "ollamaEnabled": "[[Enable Ollama API]]",
    // OPTIONAL, string.
    "ollamaEndpoint": "[[Custom Ollama API endpoint]]",
    // OPTIONAL, string, default: "DeepSeek-R1" (DeepSeek-R1 7B).
    "ollamaModel": "[[Custom Ollama Model ID]]",
    // OPTIONAL, integer.
    "ollamaPriority": "[[Custom Ollama Priority]]",

    // OPTIONAL, string.
    // Using this option along with `googleApiKey` to enable Google Search as a tool.
    "googleCx": "[[Google Search Engine ID]]",

    // OPTIONAL, undefined || array of string.
    // To open the bot to PUBLIC, DO NOT set this field;
    // To restrict the bot to PRIVATE, set chat/group/channel ids in this array.
    "private": ["[[CHAT_ID]]", "[[GROUP_ID]]", "[[CHANNEL_ID]]", ...],

    // OPTIONAL, string.
    // Set some of these fields if you want to use a `magic word` to authenticate the bot.
    "magicWord": "[[Your Magic Word here]]",

    // OPTIONAL, string.
    // Use a HOME GROUP to authentication users.
    // Anyone in this group can access the bot.
    "homeGroup": "[[GROUP_ID]]",

    // OPTIONAL, array of enum string.
    // Enum: 'private', 'mention', 'group', 'channel'.
    // Defaule: ['private', 'mention'].
    // By default, it will only reply to `private` chats and group `mention`s.
    // Adding 'group' or 'channel' may cause too much disturbance.
    "chatType": ["mention", "private"],

    // OPTIONAL, string.
    "hello": "[[initial prompt]]",

    // OPTIONAL, string.
    "info": "[[bot description]]",

    // OPTIONAL, string.
    "help": "[[help information]]",

    // OPTIONAL, object.
    // Sessions/conversations storage.
    // support PostgreSQL, MariaDB/MySQL and Redis for now.
    // If omitted, the bot will use memory storage and sync to this file.
    // Example: (Compatibility: https://node-postgres.com/apis/pool)
    // PostgreSQL is recommended for vector storage.
    "storage": {
        "provider": "POSTGRESQL",
        "host": "[[DATABASE HOST]]",
        "database": "[[DATABASE NAME]]",
        "user": "[[DATABASE USER]]",
        "password": "[[DATABASE PASSWORD]]",
        "vector": true, // REQUIRED
        ...[[OTHER DATABASE OPTIONS]],
    },
    // OR: (Compatibility: https://github.com/sidorares/node-mysql2)
    "storage": {
        "provider": "[["MARIADB" || "MYSQL"]]",
        "host": "[[DATABASE HOST]]",
        "database": "[[DATABASE NAME]]",
        "user": "[[DATABASE USER]]",
        "password": "[[DATABASE PASSWORD]]",
        "charset": "utf8mb4", // REQUIRED
        ...[[OTHER DATABASE OPTIONS]],
    },
    // OR: (Compatibility: https://github.com/luin/ioredis)
    "storage": {
        "provider": "REDIS",
        "host": "[[REDIS HOST]]",
        "password": "[[REDIS PASSWORD]]",
        ...[[OTHER REDIS OPTIONS]],
    },

}

Run it

In peace-of-mind:

$ npx halbot

If you have multible AI engines configed, use '/chatgpt' or '/bing' to switch between them, or you can use '/*' to ask them all at the same time.

Integrate to your project

Install:

$ npm i halbot

Code:

import halbot from 'halbot';

const config = {

    // ...[[ALL THE CONFIG FIELDS SUPPORTED ABOVE]]],

    // OPTIONAL, function.
    // Your own authentication logic.
    // return true if the user is authenticated.
    // return false if the user is not authenticated.
    auth: async (ctx) => {
        // ctx is the `telegraf` context object: https://telegraf.js.org/#context-class
        // It has been extended: https://github.com/Leask/utilitas/blob/master/lib/bot.mjs
        return true;
    },

    // OPTIONAL, object (key renderd as name) or array (name ignored).
    ai: {
        [[aiNameA]]: [[aiConfigA]],
        [[aiNameB]]: [[aiConfigB]],
        // ...
    },

    // OPTIONAL, object.
    // Your own speech-to-text and text-to-speech engine.
    speech: {
        stt: [[sttApi]],
        tts: [[ttsApi]],
    },

    // OPTIONAL, object.
    // Your own computer-vision engine.
    vision: {
        see: [[ocrAndObjectDetectApi]],
        read: [[documentAnnotateApi]],
    },

    // OPTIONAL, object.
    // Your own image-generator engine.
    image: {
        generate: [[textToImageApi]],
    },

    // OPTIONAL, string.
    // Path to your own middlewares.
    // ./skills
    //  |- skill_a.mjs
    //    | const action = async (bot) => {
    //    |     bot.use(async (ctx, next) => {
    //    |         ctx.reply('42');
    //    |         await next();
    //    |     });
    //    | };
    //    |
    //    | export const { run, priority, func } = {
    //    |     run: true,
    //    |     priority: 100,
    //    |     func: action,
    //    | };
    skillPath: [[pathToYourMiddlewares]],

    // OPTIONAL, object.
    // Using customized storage engine.
    // `storage` should Should be compatible with the `Map` interface:
    // https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
    storage: {
        provider: [[POSTGRESQL || MARIADB || MYSQL || REDIS]],
        get: async (key) => { /* Return session object by chatId. */ },
        set: async (key, session) => { /* Save session object by chatId. */ },
        client: { /* Customized database client / pool. */ },
            query: async (topic) => { /* Search history and session by topic. */ },
            upsert: async (event) => { /* Save event for history and session. */ },
        },
    },

    // OPTIONAL, function.
    // Using customized embedding engine for history and session search.
    embedding: async (text) => { /* Return vector embedding of the text. */ },

    // OPTIONAL, array of string.
    // Supported mime types of your vision-enabled AI models.
    // If omitted, bot will use standard OCR and Object Detect to handle images.
    supportedMimeTypes: [...[[mimeTypes]]],

    // OPTIONAL, object.
    // Adding extra commands.
    cmds: {
        [[commandA]]: [[descriptionA]],
        [[commandB]]: [[descriptionB]],
        ...[[OTHER COMMANDS]],
    },

    // OPTIONAL, object.
    // Adding extra configurations
    args: {
        [[argA]]: {
            type: 'string',
            short: [[shortCut]],
            default: [[defaultValue]],
            desc: [[description]],
        },
        [[argB]]: {
            type: 'binary',
            short: [[shortCut]],
            default: [[defaultValue]],
            desc: [[description]],
        },
        ...[[OTHER ARGS]],
    },

};

await halbot(config);

Foundations

Contact me

1993.2.45

6 months ago

1993.2.44

6 months ago

1993.2.47

5 months ago

1993.2.46

6 months ago

1993.2.49

5 months ago

1993.2.48

5 months ago

1993.2.43

6 months ago

1993.2.19

6 months ago

1993.2.12

6 months ago

1993.2.14

6 months ago

1993.2.13

6 months ago

1993.2.16

6 months ago

1993.2.15

6 months ago

1993.2.18

6 months ago

1993.2.17

6 months ago

1993.2.10

6 months ago

1993.2.23

6 months ago

1993.2.22

6 months ago

1993.2.25

6 months ago

1993.2.24

6 months ago

1993.2.27

6 months ago

1993.2.26

6 months ago

1993.2.29

6 months ago

1993.2.28

6 months ago

1993.2.21

6 months ago

1993.2.20

6 months ago

1993.2.8

7 months ago

1993.2.9

6 months ago

1993.2.2

7 months ago

1993.2.3

7 months ago

1993.2.6

7 months ago

1993.2.7

7 months ago

1993.2.4

7 months ago

1993.2.5

7 months ago

1992.1.16

7 months ago

1992.1.15

7 months ago

1992.1.14

7 months ago

1992.1.13

7 months ago

1992.1.12

7 months ago

1992.1.11

7 months ago

1992.1.10

7 months ago

1992.1.8

7 months ago

1992.1.9

7 months ago

1992.1.19

7 months ago

1992.1.18

7 months ago

1992.1.17

7 months ago

1992.1.27

7 months ago

1992.1.26

7 months ago

1992.1.25

7 months ago

1992.1.24

7 months ago

1992.1.23

7 months ago

1992.1.22

7 months ago

1992.1.21

7 months ago

1992.1.20

7 months ago

1992.1.29

7 months ago

1992.1.28

7 months ago

1993.2.56

5 months ago

1993.2.55

5 months ago

1993.2.50

5 months ago

1993.2.52

5 months ago

1993.2.51

5 months ago

1993.2.54

5 months ago

1993.2.53

5 months ago

1992.1.7

11 months ago

1991.1.18

1 year ago

1991.1.17

1 year ago

1991.1.16

1 year ago

1992.1.2

1 year ago

1992.1.3

1 year ago

1992.1.4

1 year ago

1992.1.5

12 months ago

1992.1.6

12 months ago

1991.2.12

1 year ago

1991.2.11

1 year ago

1991.2.10

1 year ago

1991.2.16

1 year ago

1991.2.15

1 year ago

1991.2.14

1 year ago

1991.2.13

1 year ago

1991.2.19

1 year ago

1991.2.18

1 year ago

1991.2.17

1 year ago

1991.2.23

1 year ago

1991.2.22

1 year ago

1991.2.21

1 year ago

1991.2.20

1 year ago

1991.2.24

1 year ago

1991.2.8

1 year ago

1991.2.9

1 year ago

1991.2.6

1 year ago

1991.2.7

1 year ago

1991.2.4

1 year ago

1991.2.5

1 year ago

1991.2.2

1 year ago

1991.2.3

1 year ago

1991.1.15

1 year ago

1991.1.14

1 year ago

1991.1.13

1 year ago

1991.1.12

1 year ago

1991.1.11

2 years ago

1991.1.10

2 years ago

1991.1.9

2 years ago

1991.1.7

2 years ago

1991.1.8

2 years ago

1991.1.5

2 years ago

1991.1.6

2 years ago

1991.1.4

2 years ago

1991.1.2

2 years ago

1990.1.129

2 years ago

1990.1.128

2 years ago

1990.1.127

2 years ago

1991.1.3

2 years ago

1990.1.126

2 years ago

1990.1.125

2 years ago

1990.1.124

2 years ago

1990.1.123

2 years ago

1990.1.122

2 years ago

1990.1.121

2 years ago

1990.1.109

2 years ago

1990.1.108

2 years ago

1990.1.119

2 years ago

1990.1.118

2 years ago

1990.1.117

2 years ago

1990.1.116

2 years ago

1990.1.115

2 years ago

1990.1.114

2 years ago

1990.1.113

2 years ago

1990.1.112

2 years ago

1990.1.111

2 years ago

1990.1.110

2 years ago

1990.1.120

2 years ago

1990.1.107

2 years ago

1990.1.106

2 years ago

1990.1.105

2 years ago

1990.1.104

2 years ago

1990.1.103

2 years ago

1990.1.102

2 years ago

1990.1.101

2 years ago

1990.1.100

2 years ago

1990.1.95

2 years ago

1990.1.96

2 years ago

1990.1.97

2 years ago

1990.1.98

2 years ago

1990.1.99

2 years ago

1990.1.92

2 years ago

1990.1.93

2 years ago

1990.1.94

2 years ago

1990.1.90

2 years ago

1990.1.91

2 years ago

1990.1.85

2 years ago

1990.1.86

2 years ago

1990.1.87

2 years ago

1990.1.88

2 years ago

1990.1.89

2 years ago

1990.1.62

2 years ago

1990.1.63

2 years ago

1990.1.64

2 years ago

1990.1.65

2 years ago

1990.1.66

2 years ago

1990.1.67

2 years ago

1990.1.68

2 years ago

1990.1.69

2 years ago

1990.1.60

2 years ago

1990.1.61

2 years ago

1990.1.59

2 years ago

1990.1.51

2 years ago

1990.1.52

2 years ago

1990.1.53

2 years ago

1990.1.54

2 years ago

1990.1.55

2 years ago

1990.1.56

2 years ago

1990.1.57

2 years ago

1990.1.58

2 years ago

1990.1.50

2 years ago

1990.1.48

2 years ago

1990.1.49

2 years ago

1990.1.40

2 years ago

1990.1.41

2 years ago

1990.1.42

2 years ago

1990.1.43

2 years ago

1990.1.44

2 years ago

1990.1.45

2 years ago

1990.1.46

2 years ago

1990.1.47

2 years ago

1990.1.37

2 years ago

1990.1.38

2 years ago

1990.1.39

2 years ago

1990.1.30

2 years ago

1990.1.31

2 years ago

1990.1.32

2 years ago

1990.1.33

2 years ago

1990.1.34

2 years ago

1990.1.35

2 years ago

1990.1.36

2 years ago

1990.1.27

2 years ago

1990.1.28

2 years ago

1990.1.29

2 years ago

1990.1.84

2 years ago

1990.1.80

2 years ago

1990.1.81

2 years ago

1990.1.82

2 years ago

1990.1.83

2 years ago

1990.1.73

2 years ago

1990.1.74

2 years ago

1990.1.75

2 years ago

1990.1.76

2 years ago

1990.1.77

2 years ago

1990.1.78

2 years ago

1990.1.79

2 years ago

1990.1.70

2 years ago

1990.1.71

2 years ago

1990.1.72

2 years ago

1990.1.26

2 years ago

1990.1.25

2 years ago

1990.1.24

2 years ago

1990.1.23

2 years ago

1990.1.22

2 years ago

1990.1.21

2 years ago

1990.1.20

2 years ago

1990.1.19

2 years ago

1990.1.18

2 years ago

1990.1.17

2 years ago

1990.1.16

2 years ago

1990.1.15

2 years ago

1990.1.14

2 years ago

1990.1.13

2 years ago

1990.1.12

2 years ago

1990.1.11

2 years ago

1990.1.10

2 years ago

1990.1.9

2 years ago

1990.1.8

2 years ago

1990.1.7

2 years ago

1990.1.6

2 years ago

1990.1.5

2 years ago

1990.1.4

2 years ago

1990.1.3

2 years ago

1990.1.2

2 years ago

1989.6.38

2 years ago

1989.6.37

2 years ago

1989.6.36

2 years ago

1989.6.35

2 years ago

1989.6.34

2 years ago

1989.6.33

2 years ago

1989.6.32

2 years ago

1989.6.31

2 years ago

1989.6.30

2 years ago

1989.6.29

2 years ago

1989.6.28

2 years ago

1989.6.27

2 years ago

1989.6.26

2 years ago

1989.6.25

2 years ago

1989.6.24

2 years ago

1989.6.23

2 years ago

1989.6.22

2 years ago

1989.6.21

2 years ago

1989.6.20

2 years ago

1989.6.19

2 years ago

1989.6.18

2 years ago

1989.6.17

2 years ago

1989.6.16

2 years ago

1989.6.15

2 years ago

1989.6.14

2 years ago

1989.6.13

2 years ago

1989.6.12

2 years ago

1989.6.11

2 years ago

1989.6.10

2 years ago

1989.6.9

2 years ago

1989.6.8

2 years ago

1989.6.7

2 years ago

1989.6.6

2 years ago

1989.6.5

2 years ago

1989.6.4

2 years ago