{"id":13643014,"url":"https://github.com/nalgeon/pokitoki","last_synced_at":"2025-06-17T11:13:13.801Z","repository":{"id":72724982,"uuid":"595713846","full_name":"nalgeon/pokitoki","owner":"nalgeon","description":"Humble AI Telegram Bot","archived":false,"fork":false,"pushed_at":"2025-06-03T03:05:21.000Z","size":1679,"stargazers_count":334,"open_issues_count":3,"forks_count":60,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-06-12T12:54:32.456Z","etag":null,"topics":["ai","bot","chat-gpt","chatbot","deepseek","gpt","openai","telegram"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nalgeon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-01-31T16:57:44.000Z","updated_at":"2025-06-06T15:10:05.000Z","dependencies_parsed_at":"2023-11-19T20:31:51.764Z","dependency_job_id":"9fd73b2a-954a-4438-ba5c-ba7ad2e9a227","html_url":"https://github.com/nalgeon/pokitoki","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"purl":"pkg:github/nalgeon/pokitoki","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nalgeon%2Fpokitoki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nalgeon%2Fpokitoki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nalgeon%2Fpokitoki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nalgeon%2Fpokitoki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nalgeon","download_url":"https://codeload.github.com/nalgeon/pokitoki/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nalgeon%2Fpokitoki/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260347083,"owners_count":22995161,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","bot","chat-gpt","chatbot","deepseek","gpt","openai","telegram"],"created_at":"2024-08-02T01:01:39.559Z","updated_at":"2025-06-17T11:13:08.791Z","avatar_url":"https://github.com/nalgeon.png","language":"Python","funding_links":[],"categories":["Chatbots"],"sub_categories":[],"readme":"# Humble AI Telegram Bot\n\nThis is a Telegram chat bot (AI assistant) that uses large language models from OpenAI-compatible providers (like [OpenAI](https://platform.openai.com/), [OpenRouter](https://openrouter.ai/docs/), [Nebius](https://docs.nebius.com/) or [Gemini](https://ai.google.dev/gemini-api/docs/openai)).\n\nNotable features:\n\n-   Both one-on-one and group chats.\n-   Direct questions, mentions, follow-ups.\n-   Access external links (articles, code, data).\n-   Shortcuts (custom AI commands).\n-   Custom chat-wide prompts.\n-   Image generation.\n-   On-the-fly configuration.\n\nRead on for a detailed feature description or jump to [setup](#setup).\n\n## Personal chats\n\nThe bot acts as your personal assistant:\n\n\u003e 🧑 Explain Apache Kafka to a three year old\n\u003e\n\u003e 🤖 Apache Kafka is like a big mailbox that helps different toys (computers) send messages to each other. When one toy has something to say, it puts a message in the mailbox, and other toys can take that message out and read it. This way, they can talk and share things quickly!\n\nTo allow other users to use the bot, list them in the `telegram.usernames` config property.\n\nThe bot has a terrible memory, so don't expect it to remember any chat context by default. You can, however, reply with a follow-up question (`Ctrl/Cmd + ↑`). Alternatively, use a plus sign to follow up:\n\n\u003e 🧑 Yesterday, all my troubles seemed so far away\n\u003e\n\u003e 🤖 It sounds like you're quoting \"Yesterday\" by The Beatles. It's a classic song about longing and nostalgia.\n\u003e\n\u003e 🧑 + who wrote it?\n\u003e\n\u003e 🤖 \"Yesterday\" was written by Paul McCartney of The Beatles.\n\nAvailable commands:\n\n-   `/retry` - retry answering the last question\n-   `/help` - show help\n-   `/version` - show bot info\n\nTo rephrase or add to the last question, simply edit it. The bot will then answer the updated question.\n\n## Groups\n\nTo get an answer from the bot in a group, mention it in a reply to a question:\n\n\u003e 🧑 I forgot who played Ramsy in the Game of Thrones 😕\u003cbr\u003e\n\u003e 🧑 ↳ @pokitokibot help\n\u003e\n\u003e 🤖 Ramsay Bolton in Game of Thrones was played by Iwan Rheon.\n\nOr ask a question directly:\n\n\u003e 🧑 @pokitokibot Who played Ramsy in the Game of Thrones?\n\u003e\n\u003e 🤖 Iwan Rheon played Ramsay Bolton in Game of Thrones.\n\nTo make the bot reply to group members, list the group id in the `telegram.chat_ids` config property. Otherwise, the bot will ignore questions from group members unless they are listed in the `telegram.usernames` config property.\n\nIf you don't know the group id, run the `/version` bot command in a group to find it:\n\n```\nChat information:\n- id: -1001405001234\n- title: My Favorite Group\n- type: supergroup\n...\n```\n\n## External links\n\nIf you ask \"vanilla\" ChatGPT about external resources, it will either hallucinate or admit that it doesn't have access to remote content:\n\n\u003e 🧑 What is the content of https://sqlime.org/employees.sql? Make no assumptions.\n\u003e\n\u003e 🤖 As an AI language model, I cannot access external URLs on the internet.\n\nThe bot solves the problem by fetching the remote content and feeding it to the model:\n\n\u003e 🧑 Name 1 major feature of the Go 1.23 release https://tip.golang.org/doc/go1.23 Be brief!\n\u003e\n\u003e 🤖 A major feature of Go 1.23 is the inclusion of the \"range-over-func\" experiment as a standard language feature, allowing the \"range\" clause in \"for-range\" loops to accept iterator functions.\n\nCurrently only supports text content (articles, code, data), not PDFs, images or audio.\n\nIf you _don't want_ the bot to access the URL, quote it:\n\n\u003e 🧑 Exact contents of \"https://antonz.org/robots.txt\"\n\u003e\n\u003e 🤖 I can't access external websites directly. You can check the contents of a robots.txt file by visiting the URL in your browser.\n\n## Shortcuts\n\nUse short commands to save time and ask the bot to do something specific with your questions. For example, ask it to proofread your writing with a `!proofread` command:\n\n\u003e 🧑 !proofread I can has write java programz\n\u003e\n\u003e 🤖 Revised text: \"I can write Java programs.\"\n\u003e\n\u003e Changes made:\n\u003e\n\u003e 1. Removed \"has\" for grammatical correctness; \"can\" does not require \"has.\"\n\u003e 2. Corrected \"java\" to \"Java\" for proper capitalization as it is a proper noun.\n\u003e 3. Changed \"programz\" to \"programs\" for correct spelling and clarity.\n\nThere are several built-in shortcuts:\n\n-   `bugfix` fixes your code.\n-   `proofread` fixes your writing.\n-   `translate` translates your text into English.\n-   `summarize` gives a two paragraph summary of a text.\n\nYou can add your own shortcuts. See `config.example.yml` for details.\n\n## Chat-wide prompts\n\nTo set a custom prompt for the current chat, use the `/prompt` command:\n\n\u003e 🧑 /prompt You are an evil genius. Reply with an evil laugh.\n\nTo return to the default prompt, use `/prompt reset`.\n\nThe `/prompt` command in group chats is only available to admins - users listed in the `telegram.admins` property.\n\n## Image generation\n\nUse the `/imagine` command to generate an image using the DALL-E 3 model from OpenAI:\n\n\u003e 🧑 /imagine the dawn of a new era\n\u003e\n\u003e 🤖 (beautiful picture)\u003cbr\u003e\n\u003e the dawn of a new era\n\nThe default image size is 1024×1024 px. Other supported sizes are 1792×1024 and 1024×1792:\n\n\u003e /imagine a lazy cat on a sunny day 1792×1024\n\nImage generation is quite pricey. By default it's only enabled for users listed in `telegram.usernames`, not for group members. You can change this with the `imagine.enabled` config property.\n\n## Other useful features\n\nThe convenience of working with a bot is made up of small details. Here are some situations where it can save you time and effort.\n\n### Forwarding\n\nSay you received a message from a colleague or read a post on a channel and want to ask a question. Simply forward the message to the bot and answer the clarifying question it asks.\n\n### Ask with file\n\nTo ask a question about a document, send it as a file and write the question in the caption. The bot will read the file contents and answer. Currently only supports text content (plain text, code, data), not PDFs, images or audio. Sending multiple files is also not supported.\n\n### Reply with attachment\n\nSometimes the AI's reply exceeds the maximum message length set by Telegram. In this case, the bot will not fail or spam you with messages. Instead, it will send the answer as an attached markdown file.\n\n### Edited question\n\nTo rephrase or add to the last question, edit it (`↑` shortcut). The bot will notice this and respond to the clarified question.\n\n## Bot information\n\nUse the `/version` command to print detailed information about the current chat, bot, and AI model:\n\n```\nChat information:\n- id: -1001405001234\n- title: My Favorite Group\n- type: supergroup\n\nBot information:\n- id: 5930739038\n- name: @pokitokibot\n- version: 129\n- usernames: 6 users\n- admins: 1 users\n- chat IDs: []\n- access to messages: True\n\nAI information:\n- model: gpt-3.5-turbo\n- history depth: 3\n- imagine: True\n- shortcuts: bugfix, proofread, summarize, translate\n```\n\n## Configuration\n\nUse the `/config` command to change almost any setting on the fly, without restarting the bot.\n\n-   Add or remove users and chats allowed to interact with the bot (`telegram.usernames` and `telegram.chat_ids`).\n-   Adjust the AI provider (`openai.url`), API key (`openai.api_key`), model (`openai.model`), prompt (`openai.prompt`) and params (`openai.params`).\n-   Enable or disable image generation (`imagine.enabled`).\n-   Add or change AI shortcuts (`shortcuts`).\n-   Change any other config property.\n\nTo view a specific config property, put its name after `/config`:\n\n```\n/config telegram.usernames\n/config openai.prompt\n/config imagine.enabled\n```\n\nTo change a specific config property, put its name and value after `/config`:\n\n```\n/config telegram.usernames [\"alice\", \"bob\", \"cindy\"]\n/config openai.url https://api.studio.nebius.ai/v1\n/config openai.model meta-llama/Meta-Llama-3.1-70B-Instruct\n/config openai.prompt \"You are an evil AI bot\"\n/config imagine.enabled none\n```\n\nWhen working with list properties like `telegram.usernames`, you can add or remove individual items instead of redefining the whole list:\n\n```\n/config telegram.usernames +cindy\n/config telegram.usernames -bob\n```\n\nThe `/config` command is only available to admins - users listed in the `telegram.admins` property.\n\n## Message limits\n\nHeated discussions with the bot in large groups can lead to high usage of the AI API. To avoid spending your entire budget, set message limits for groups with the `conversation.message_limit` config property.\n\nYou can limit the number of messages from a user over a period of time. For example:\n\n-   10 messages per user per hour:\n\n```yaml\nmessage_limit:\n    count: 10\n    period: hour\n```\n\n-   1 message per user per minute:\n\n```yaml\nmessage_limit:\n    count: 1\n    period: minute\n```\n\n-   30 messages per user per day:\n\n```yaml\nmessage_limit:\n    count: 30\n    period: day\n```\n\n## Setup\n\n1. Get your AI API key (from [OpenAI](https://openai.com/api/) or other provider)\n\n2. Get your Telegram bot token from [@BotFather](https://t.me/BotFather)\n\n3. Clone the repo to the server:\n\n```bash\ngit clone https://github.com/nalgeon/pokitoki.git\n```\n\n4. Copy `config.example.yml` to `config.yml` and specify your tokens there. Add yourself to the `telegram.usernames` property, otherwise the bot will be available to everyone.\n\n5. Start the bot:\n\n```bash\ndocker compose up --build --detach\n```\n\nTo stop the bot:\n\n```bash\ndocker compose stop\n```\n\nTo update the bot to a new version:\n\n```bash\ndocker compose stop\ngit pull\ndocker compose up --build --detach\n```\n\nFor older Docker distributions, use `docker-compose` instead of `docker compose`.\n\n## Development setup\n\nPrepare the environment:\n\n```\npython3 -m venv env\n. env/bin/activate\npip install -r requirements.txt\n```\n\nPrepare the config and data directory:\n\n```\ncp config.example.yml config.yml\nmkdir ./data\n```\n\nSet tokens and other settings in `config.yml`.\n\nRun tests:\n\n```\npython -m unittest discover\n```\n\nStart the bot:\n\n```\npython -m bot.bot\n```\n\n## Contributing\n\nFor new features and improvements, please first open an issue to discuss what you would like to change.\n\nBe sure to add or update tests as appropriate.\n\nUse [Black](https://black.readthedocs.io/en/stable/) for code formatting and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for commit messages.\n\n## Changelog\n\nFor feature history, see [releases](https://github.com/nalgeon/pokitoki/releases).\n\n## Credits\n\nOriginally based on [chatgpt_telegram_bot](https://github.com/karfly/chatgpt_telegram_bot), although the projects have diverged quite a bit.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnalgeon%2Fpokitoki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnalgeon%2Fpokitoki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnalgeon%2Fpokitoki/lists"}