Sector AI Telegram Bot
This repository contains the implementation of the Sector AI Telegram Bot, an advanced chatbot designed to interact with users on Telegram. The secret sauce is LangChain. The bot supports various functionalities, including autoreply decision-making, structured output parsing for polls, multimodal image processing, emoji responses, code generation, and more. Below is a detailed description of all components of this repository.
Installing Ollama
To download and manage the recommended models, you will need to install Ollama. Follow these steps to install Ollama and download the models:
-
Install Ollama: https://ollama.com/download
-
Download the recommended models:
ollama pull llama3.2-vision:11b-instruct-fp16
Make sure you have enough storage space and a stable internet connection to download these models.
Recommended Models
- Llama 3.2
- Gemma 2
- Qwen 2.5
- Phi 4
- Mistral Nemo or Small
- Almost anything will work for the basics. However, some models aren't powerful enough for the structured output parsing involved in autoreply, decision, poll, and topic commands.
Features
This project uses the python-telegram-bot library, with various command handlers and message handlers to manage different interactions. Below is a summary of each command:
Introduction (/start)
- Description: Sends a welcome message introducing the bot and its basic commands.
- Usage:
/start
Generate Response (/chat)
- Description: Initiates or continues a chat interaction with the user, using AI to generate responses based on the context of the conversation.
- Usage:
/chat [text](where[text]is the user's input)
Summarize Chat Messages (/summarize)
- Description: Provides a summary of the current chat messages in context, potentially generated by the AI to quickly grasp the conversation’s essence.
- Usage:
/summarize
Generate Emojis Based on Prompt (/emoji)
- Description: Creates emojis based on user input or specific prompts related to emotions or themes relevant to the chat.
- Usage:
/emoji [prompt](where[prompt]is a description of what kind of emoji you want)
Generate a Poll Based on Question or Prompt (/poll)
- Description: Creates a poll with multiple options based on user input, useful for gathering feedback.
- Usage:
/poll [question](where[question]is the description of the poll)
Generate a Poll with Chat Related Topics (/topic)
- Description: Creates a poll where users can vote on topics discussed recently in the chat context.
- Usage:
/topic
Return "True" or "False" Based on Prompt (/decide)
- Description: Uses AI to decide between two possible outcomes based on user input.
- Usage:
/decide [prompt](where[prompt]is the question you want decided by the bot)
Generate a Code Block Based on Specification (/code)
- Description: Generates a code snippet according to specific requirements or inputs provided by the user.
- Usage:
/code [specification](where[specification]describes what kind of code to generate, e.g., Python function)
Generate Fake Website Based on Specification (/html)
- Description: Renders a mock HTML website based on given specifications or details from the user.
- Usage:
/html [specification](where[specification]includes layout and content requirements)
Generate Horrible SVG Image Based on Description (/svg)
- Description: Creates an SVG graphic according to detailed descriptions provided by users, often with humorous or nonsensical results.
- Usage:
/svg [description](where[description]can be anything from a simple shape to a complex scene)
Get Current Context Length (/tokens)
- Description: Checks the current length of the chat context in terms of tokens used, which could be relevant for understanding memory or performance constraints.
- Usage:
/tokens
Toggle Automatic Replies (/autoreply)
- Description: Enables or disables automatic replies triggered by the LLM decision. When enabled, the bot will automatically respond to user messages and images.
- Usage:
/autoreplyto toggle the feature
Reset Chat Context (/clear)
- Description: Resets the context of the conversation, effectively starting a new chat from scratch.
- Usage:
/clear
View This Model (/model)
- Description: Displays information about the current AI model being used by the bot.
- Usage:
/model
Set System Prompt (Admin Only) (/system)
- Description: Allows administrators to set or modify the system prompt that guides the behavior of the AI within the chat context.
- Usage:
/system [prompt]where[prompt]is the new system message you want the bot to follow.
Generate System Prompt (Admin Only) (/characterize)
- Description: Similar to setting a system prompt but might be used for generating more detailed or specialized instructions for the AI based on specific user requirements.
- Usage:
/characterize [details]where[details]are a thing for the LLM to roleplay as.
Set the Model (Admin Only) (/models)
- Description: Allows administrators to switch or configure different AI models used by the bot, which can affect response quality and style.
Getting Started
From PyPI
pip install sector-ai
Create a .env in the directory you will run from, or export the variables directly. The Configuration table lists every setting; at minimum you need TELEGRAM_BOT_TOKEN and a reachable Ollama.
sector-ai
sector-ai reads .env from the current directory. python -m sector_ai is equivalent.
From a clone
- Prerequisites: Python 3.11 or newer, and Ollama running (see above).
- Clone and install:
git clone https://github.com/roryeckel/sector-ai.git cd sector-ai pip install .
- Configure: copy
.env.exampleto.envand set at leastTELEGRAM_BOT_TOKEN. - Run:
sector-ai
Upgrading from 1.3.x: the --config flag and config.json are gone. Move the values you had changed into .env; .env.example lists every setting and its default.
Docker
Images are published to the GitHub Container Registry for linux/amd64 and linux/arm64. The bot makes no inbound connections, so no ports are exposed.
docker run -d --name sector-ai --restart unless-stopped \
-e TELEGRAM_BOT_TOKEN=your-token \
-e OLLAMA_URL=http://host.docker.internal:11434 \
--add-host host.docker.internal:host-gateway \
ghcr.io/roryeckel/sector-ai:latest
Or, from a clone, compose.yaml does the same:
cp .env.example .env # set TELEGRAM_BOT_TOKEN and OLLAMA_URL
docker compose up -d
Inside the container, localhost is the container itself, so Ollama on the host needs host.docker.internal (Docker Desktop resolves it automatically; the --add-host flag or the extra_hosts entry in compose.yaml covers Linux).
Image tags:
| Tag | Meaning |
|---|---|
latest |
latest published release, not a prerelease |
1.4.0 |
exact release |
1.4 |
latest patch of that minor |
edge |
latest commit on master |
sha-abc1234 |
exact commit |
Configuration
There is no configuration file. Settings come from environment variables, an optional .env file in the working directory, or the command line (which wins over both).
| Variable | Default | Purpose |
|---|---|---|
TELEGRAM_BOT_TOKEN |
required | Token from @BotFather. SECTOR_AI_TELEGRAM_BOT_TOKEN is also accepted. |
OLLAMA_URL |
http://localhost:11434 |
Ollama endpoint. SECTOR_AI_OLLAMA_URL is also accepted. |
SECTOR_AI_DEFAULT_MODEL |
llama3.2-vision:11b-instruct-fp16 |
Model loaded at start-up. |
SECTOR_AI_VISION_MODEL |
llama3.2-vision:11b-instruct-fp16 |
Model used for photos. |
SECTOR_AI_ADMIN_USERNAMES |
ex0dus |
Comma separated usernames allowed to use admin commands. |
SECTOR_AI_DEFAULT_SVG_SIZE |
250 |
Base size for /svg; the rendered PNG is twice this. |
SECTOR_AI_STREAMING_CURSOR |
🦙 |
Cursor shown while a reply streams. |
SECTOR_AI_STREAMING_INTERVAL_SEC |
0.7 |
Minimum seconds between Telegram edits. |
SECTOR_AI_STREAMING_CHUNK_SIZE |
150 |
Characters buffered before an edit. |
SECTOR_AI_OLLAMA_TIMEOUT |
200.0 |
Request timeout in seconds. |
SECTOR_AI_OLLAMA_CONTEXT_LENGTH |
2048 |
num_ctx passed to Ollama; set to null (or leave it empty) to leave it to the model. |
SECTOR_AI_OLLAMA_DISALLOWED_MODELS |
empty | Comma separated models hidden from /models. |
SECTOR_AI_OLLAMA_HEADERS |
{} |
JSON object of extra HTTP headers for Ollama. |
SECTOR_AI_SYSTEM_PROMPTS__<NAME> |
built-in | Override one system prompt, e.g. SECTOR_AI_SYSTEM_PROMPTS__SVG. |
SECTOR_AI_LOG_LEVEL |
INFO |
CRITICAL, ERROR, WARNING, INFO or DEBUG. |
The flags worth changing per run are also on the command line: --model, --vision-model, --ollama-url, --admin (repeatable), --log-level and --version. Secrets are intentionally environment-only, so a bot token never lands in shell history or ps output.
Contributions Welcome
Metadata
Release files for sector-ai 1.4.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sector_ai-1.4.1.tar.gz | 55.1 kB | With provenance | Details for sector_ai-1.4.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sector_ai-1.4.1-py3-none-any.whl | Python 3 | none | any | Details for sector_ai-1.4.1-py3-none-any.whl |
Total release size: 94.1 kB
Release files / sector_ai-1.4.1.tar.gz
| Download URL | sector_ai-1.4.1.tar.gz |
|---|---|
| Size | 55.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c7b75b9d449706d4cbba49eccb58b61cee1602ce6d23286e9b978eb5a7ae0dd6
|
|
BLAKE2b-256 checksum How to use checksums |
1ab7bda355d91a6685d0511d41cf39a11607ee341c572c426185b3655ee3dc47
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / sector_ai-1.4.1-py3-none-any.whl
| Download URL | sector_ai-1.4.1-py3-none-any.whl |
|---|---|
| Size | 39.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c9025105867f97f2809c38023bbc2e9b4979519c294bd07ad5ef8029f096d1ed
|
|
BLAKE2b-256 checksum How to use checksums |
c476dc942926afe9fd1c52eb25baac6e87b098cc42f87bc51d9e2e0b591908c1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logSecurity for sector-ai 1.4.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for sector_ai-1.4.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.