https://github.com/leask/halbot
Just another `ChatGPT` / `Gemini` / `Mistral (by ollama)` Telegram bob, which is simple design, easy to use, extendable and fun.
https://github.com/leask/halbot
ai bing chatgpt gpt telegram
Last synced: about 1 month ago
JSON representation
Just another `ChatGPT` / `Gemini` / `Mistral (by ollama)` Telegram bob, which is simple design, easy to use, extendable and fun.
- Host: GitHub
- URL: https://github.com/leask/halbot
- Owner: Leask
- License: mit
- Created: 2023-03-12T18:17:12.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-05-23T06:17:30.000Z (over 1 year ago)
- Last Synced: 2024-05-23T07:28:52.036Z (over 1 year ago)
- Topics: ai, bing, chatgpt, gpt, telegram
- Language: JavaScript
- Homepage: https://leaskh.com/post/711636926789271552/halbot
- Size: 170 KB
- Stars: 97
- Watchers: 5
- Forks: 17
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# 🤖️ halbot
[](./LICENSE)
[](https://github.com/Leask/halbot/actions/workflows/npm-publish.yml)
Just another `ChatGPT` / `Gemini` / `Claude` / `Azure` / `Jina` / `Ollama` Telegram bot, which is simple design, easy to use, extendable and fun.
Live demo, click to watch on YouTube:
Screenshots: 👈 Click here to see screenshots
## Features
- [Telegram](https://telegram.org/) Bot (`Telegram Bot` token required)
- [ChatGPT](https://openai.com/blog/chatgpt) (`OpenAI` API key required)
- [Gemini](https://ai.google.dev/gemini-api/docs) (Google `Gemini` API Key required)
- [Claude](https://www.anthropic.com/api) (`Anthropic` or Google `Vextex` API Key required)
- [Azure](https://azure.microsoft.com/en-us/solutions/ai) (`Azure` API Key required)
- [Jina](https://jina.ai/api-dashboard/deepsearch) (`Jina` API Key required)
- [Ollama](https://github.com/jmorganca/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 or Imagen (`OpenAI` or Google `Gemini` API key required, or your own engine)
- OCR/OBJECT_DETECT (`OpenAI` or Google `Gemini` API key required, or your own engine)
- DeepSearch (`Jina` API Key required)
- Feeding webpage and [YouTube](https://www.youtube.com/) to enhance your prompt
- Support Tools (Function Calls)
- 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](https://ai.google.dev/gemini-api/docs/models/gemini-v2).
- 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:
```json
{
"telegramToken": "[[Telegram Bot API Token]]",
"openaiApiKey": "[[OpenAI API Key]]"
}
```
All supported configuration fields:
```js
{
// 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".
"openaiModel": "[[Custom OpenAI Model ID]]",
// OPTIONAL, integer.
"openaiPriority": "[[Custom OpenAI 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.
"anthropicApiKey": "[[Anthropic API Key]]",
// OPTIONAL, string.
"anthropicCredentials": "[[Vertex Anthropic Credentials]]",
// OPTIONAL, string.
"anthropicProjectId": "[[Vertex Anthropic Project Id]]",
// OPTIONAL, string, default: `latest claude model`.
"anthropicModel": "[[Custom Anthropic Model ID]]",
// OPTIONAL, integer.
"anthropicPriority": "[[Custom Anthropic Priority]]",
// Set some of these fields if you need SiliconFlow's DeepSearch features.
// OPTIONAL, string.
"siliconflowApiKey": "[[SiliconFlow API Key]]",
// OPTIONAL, string.
"siliconflowModel": "[[Custom SiliconFlow Model ID]]",
// OPTIONAL, integer.
"siliconflowPriority": "[[Custom SiliconFlow Priority]]",
// Set some of these fields if you need Jina's DeepSearch features.
// OPTIONAL, string.
"jinaApiKey": "[[Jina API Key]]",
// OPTIONAL, string.
"jinaModel": "[[Custom Jina Model ID]]",
// OPTIONAL, integer.
"jinaPriority": "[[Custom Jina 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 nee Azure OpenAI's AI features.
// OPTIONAL, string.
"azureOpenaiApiKey": "[[Azure OpenAI API Key]]",
// OPTIONAL, string.
"azureOpenaiEndpoint": "[[Azure OpenAI API Endpoint]]",
// OPTIONAL, string.
"azureOpenaiModel": "[[Custom Azure OpenAI Model ID]]",
// OPTIONAL, integer.
"azureOpenaiPriority": "[[Custom Azure OpenAI 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:
```bash
$ 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:
```bash
$ npm i halbot
```
Code:
```js
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
- `halbot` uses my other project [🧰 utilitas](https://github.com/Leask/utilitas) as the basic framework to handle all the dirty work.
- `halbot` uses [🤖 utilitas.bot](https://github.com/Leask/utilitas/blob/master/lib/bot.mjs) as a Telegram bot engine.
- `halbot` uses [🤖 utilitas.alan](https://github.com/Leask/utilitas/blob/master/lib/alan.mjs) to communicate with the AI engines.
## Contact me
