Skip to main content

Sector AI Telegram Bot

CI PyPI Docker License

Sector AI is a Telegram bot that brings a chat model into your conversations. The secret sauce is LangChain. It supports autoreply decision-making, structured output parsing for polls, multimodal image processing, emoji responses, code generation, and more.

Backends

The bot runs on either of two backends. Both are first-class: streaming replies, vision, autoreply decisions, model switching and token counting all work the same.

  • Ollama (default) — Ollama's native API.
  • OpenAI-compatible — Chat Completions against any /v1 endpoint: LM Studio, vLLM, llama.cpp, OpenRouter, OpenAI itself, or your own inference server.

No models are bundled. Point the bot at a server you already run and set SECTOR_AI_DEFAULT_MODEL (and SECTOR_AI_VISION_MODEL for photos) to a model it serves. Vision commands need a multimodal model; the rest works with any text model that can follow structured output.

Ollama

Install Ollama, then pull a model:

ollama pull <model>

SECTOR_AI_LLM_PROVIDER defaults to ollama, so nothing else needs enabling. Set SECTOR_AI_DEFAULT_MODEL to the model you pulled, or let an admin pick one at runtime with /models.

OpenAI-compatible

Set the provider and point the bot at the server's /v1 root:

SECTOR_AI_LLM_PROVIDER=openai
SECTOR_AI_OPENAI_BASE_URL=https://your-server.example/v1
SECTOR_AI_OPENAI_API_KEY=...

The URL must include /v1. Leave the key empty for a server that does not check one; the bot sends dummy. Use the server's own model names in SECTOR_AI_DEFAULT_MODEL and SECTOR_AI_VISION_MODEL, for example vendor/model on OpenRouter.

Server SECTOR_AI_OPENAI_BASE_URL
Ollama http://localhost:11434/v1
LM Studio http://localhost:1234/v1
vLLM http://localhost:8000/v1
llama.cpp http://localhost:8080/v1
OpenRouter https://openrouter.ai/api/v1
OpenAI https://api.openai.com/v1

Ollama also has an OpenAI-compatible /v1 route, so switching that server to the openai provider is only a URL and provider change.

Context length

Context length is set on the server. For Ollama, use OLLAMA_CONTEXT_LENGTH in its environment or PARAMETER num_ctx in a Modelfile; for other servers use their equivalent, such as vLLM's --max-model-len.

The bot reads the window the server advertises, so /tokens can show a percentage and compaction knows when to run. It checks, in order: SECTOR_AI_CONTEXT_LENGTH when set above zero, then the model's own metadata (/v1/models context_length or max_model_len, Ollama's /api/ps or /api/show), then a conservative 8192. The lookup happens once per endpoint and model, not on every message.

Context compaction

Instead of dropping the oldest messages at a fixed count, the bot keeps a running summary. When the next request would pass SECTOR_AI_COMPACTION_THRESHOLD of the context window, the oldest messages are folded into the summary and only the most recent SECTOR_AI_COMPACTION_KEEP_MESSAGES stay verbatim. The summary is sent as a second system message, so a custom system prompt keeps working.

Compaction uses the model server itself, so it works the same on every backend. OpenAI's native Responses compaction is not used: it returns an opaque item that is only valid on that API, and most compatible servers, including Ollama and most self-hosted ones, do not implement it.

If summarization fails, the oldest messages are dropped to fit the window instead and the bot keeps chatting; SECTOR_AI_COMPACTION_MAX_MESSAGES still bounds the history as a safety net. /compact (admin only) forces a compaction and reports the token change.

Message formatting

Model replies are rendered with Telegram formatting: bold and italic, inline and fenced code with the language label, links, block quotes, spoilers, and list markers. Headings become bold or underlined text and tables become monospace blocks, because Telegram has no heading, list or table entities.

Rendering uses Telegram message entities rather than parse_mode, so nothing is escaped and a half-written reply cannot break delivery. If Telegram rejects a formatted edit, the same text is sent without formatting and the rest of that reply stays plain; formatting is never allowed to cost a message. Set SECTOR_AI_MARKDOWN=false to send raw text.

Replies longer than Telegram's 4096-character limit are split across messages at line breaks, with entities continuing across the split.

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 the Current Context Size (/tokens) (Admin Only)

  • Description: Counts the system prompt and current chat history with the model server's tokenizer when available, so messages that have not been processed yet are included. On an OpenAI-compatible server it first uses OpenAI's free /responses/input_tokens endpoint, which counts the Responses API input and can differ slightly from a Chat Completions request. If that endpoint is missing, it falls back to a one-token probe for the exact chat count; on a paid endpoint that probe sends the whole prompt as a normal request. The result is cached until the context or model changes. If the server reports no count, the reply is marked as an estimate. When the server also reports its context window, the reply shows the count as a percentage of it. Ollama can truncate a prompt that exceeds the server's context window, so the reported number is then a lower bound.
  • Usage: /tokens

Compact the Context (/compact) (Admin Only)

  • Description: Folds the older messages into the running summary immediately, keeps the most recent messages verbatim, and reports the token count before and after. Normally runs on its own before a reply; this command is for testing or for shrinking the context on demand.
  • Usage: /compact

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: Lists available models in pages of 40 and switches the bot to the selected one. Use /models 2 to open a later page directly.

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

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 one reachable backend — Ollama or any OpenAI-compatible server.
  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, then set TELEGRAM_BOT_TOKEN and the backend and model values you need.
  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.

The example below reaches Ollama on the host. For an OpenAI-compatible server, add -e SECTOR_AI_LLM_PROVIDER=openai -e SECTOR_AI_OPENAI_BASE_URL=http://host.docker.internal:11434/v1 (or the server's public /v1 URL), plus -e SECTOR_AI_OPENAI_API_KEY=... if it checks one.

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 a server 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). A remote OpenAI-compatible server needs no special host entry — set SECTOR_AI_OPENAI_BASE_URL to its public URL.

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.
SECTOR_AI_LLM_PROVIDER ollama Backend: ollama for the native API, or openai for any OpenAI-compatible endpoint.
OLLAMA_URL http://localhost:11434 Ollama endpoint, used by the ollama provider. SECTOR_AI_OLLAMA_URL is also accepted.
SECTOR_AI_OPENAI_BASE_URL http://localhost:11434/v1 Base URL for the openai provider; must include /v1.
SECTOR_AI_OPENAI_API_KEY empty Key for the openai provider. Empty sends dummy, which local servers ignore.
SECTOR_AI_DEFAULT_MODEL llama3.2-vision:11b-instruct-fp16 Chat model at start-up. Set it to a model the backend serves.
SECTOR_AI_VISION_MODEL llama3.2-vision:11b-instruct-fp16 Model used for photos; must accept images.
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_MARKDOWN true Render model markdown as Telegram formatting. false sends raw text.
SECTOR_AI_LLM_TIMEOUT 200.0 Request timeout in seconds. SECTOR_AI_OLLAMA_TIMEOUT is also accepted.
SECTOR_AI_LLM_DISALLOWED_MODELS empty Comma separated models hidden from /models. SECTOR_AI_OLLAMA_DISALLOWED_MODELS is also accepted.
SECTOR_AI_LLM_HEADERS {} JSON object of extra HTTP headers. SECTOR_AI_OLLAMA_HEADERS is also accepted.
SECTOR_AI_CONTEXT_LENGTH 0 Context window in tokens. 0 detects it from the server and falls back to 8192.
SECTOR_AI_COMPACTION_ENABLED true Fold old messages into a summary instead of dropping them.
SECTOR_AI_COMPACTION_THRESHOLD 0.75 Share of the context window that triggers a compaction.
SECTOR_AI_COMPACTION_KEEP_MESSAGES 8 Recent messages kept verbatim after a compaction.
SECTOR_AI_COMPACTION_MAX_MESSAGES 500 Safety cap used when compaction is off or fails.
SECTOR_AI_COMPACTION_SUMMARY_MAX_CHARS 4000 Maximum summary length; longer summaries are truncated.
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.

Context length is detected from the server when possible; see Context length and Context compaction.

Upgrading: SECTOR_AI_OLLAMA_CONTEXT_LENGTH is no longer read. Remove it and configure the context length on the Ollama server or in a Modelfile.

The flags worth changing per run are also on the command line: --model, --vision-model, --provider, --ollama-url, --openai-url, --admin (repeatable), --log-level and --version. Secrets are intentionally environment-only, so a bot token or API key never lands in shell history or ps output.

Contributions Welcome

Metadata

Release files for sector-ai 1.5.0

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.5.0
File Size Uploaded Provenance Actions
sector_ai-1.5.0.tar.gz 84.8 kB With provenance Details for sector_ai-1.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sector-ai 1.5.0
File Interpreter ABI Platform Actions
sector_ai-1.5.0-py3-none-any.whl Python 3 none any Details for sector_ai-1.5.0-py3-none-any.whl

Total release size: 142.1 kB

Release files / sector_ai-1.5.0.tar.gz

Download URL sector_ai-1.5.0.tar.gz
Size 84.8 kB
Tags Source
SHA-256 checksum
How to use checksums
c8856313f4027b476d5f2f8cb94a50b44a508f4cd2a8907c0e2fce40211ede58
BLAKE2b-256 checksum
How to use checksums
7eb19e83dd750b2db3e737332840a8a23f8b890f9254abf532b25d545a8a9cae
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 22, 2026.

Transparency log

Release files / sector_ai-1.5.0-py3-none-any.whl

Download URL sector_ai-1.5.0-py3-none-any.whl
Size 57.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5197c97d4eb452be693d1706fed0471d7d712da48731ecffad46e48d2e873374
BLAKE2b-256 checksum
How to use checksums
2261c0515aaa82cc53a9fc99c90b5fdbac4766ac93cd5e8c2c97b728d8b678d6
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 22, 2026.

Transparency log

Security for sector-ai 1.5.0

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.5.0.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 22, 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.5.0 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