Skip to main content

Sector AI Telegram Bot

CI PyPI Docker License

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:

  1. Install Ollama: https://ollama.com/download

  2. 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.

  • 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)
  • 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: /autoreply to 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

  1. Prerequisites: Python 3.11 or newer, and Ollama running (see above).
  2. Clone and install:
    git clone https://github.com/roryeckel/sector-ai.git
    cd sector-ai
    pip install .
    
  3. Configure: copy .env.example to .env and set at least TELEGRAM_BOT_TOKEN.
  4. 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)

Source distribution for sector-ai 1.4.1
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)

Table of built distributions (wheels) for sector-ai 1.4.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

1.4.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page