Metadata-Version: 2.4
Name: sector-ai
Version: 1.5.0
Summary: Python Telegram Bot powered by LangChain, Ollama or any OpenAI-compatible endpoint
Author: Rory Eckel
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://github.com/roryeckel/sector-ai
Project-URL: Issues, https://github.com/roryeckel/sector-ai/issues
Project-URL: Changelog, https://github.com/roryeckel/sector-ai/releases
Keywords: telegram,bot,ollama,openai,langchain,llm
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: langchain-core==1.8.4
Requires-Dist: langchain-ollama==1.1.0
Requires-Dist: langchain-openai==1.8.5
Requires-Dist: python-telegram-bot==22.8
Requires-Dist: telegramify-markdown==1.4.2
Requires-Dist: svglib==2.4.0
Requires-Dist: reportlab==5.1.0
Requires-Dist: pypdfium2==5.15.2
Requires-Dist: pydantic==2.14.4
Requires-Dist: pydantic-settings==2.16.3
Requires-Dist: python-dotenv==1.2.4
Requires-Dist: httpx==0.28.1
Provides-Extra: dev
Requires-Dist: ruff==0.17.6; extra == "dev"
Requires-Dist: pytest==9.2.0; extra == "dev"
Requires-Dist: pytest-asyncio==1.5.0; extra == "dev"
Requires-Dist: pytest-cov==7.1.0; extra == "dev"
Requires-Dist: packaging==26.3; extra == "dev"
Dynamic: license-file

# Sector AI Telegram Bot

[![CI](https://github.com/roryeckel/sector-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/roryeckel/sector-ai/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/sector-ai.svg)](https://pypi.org/project/sector-ai/)
[![Docker](https://img.shields.io/github/v/release/roryeckel/sector-ai?label=ghcr.io&logo=docker&logoColor=white&color=2496ED)](https://github.com/roryeckel/sector-ai/pkgs/container/sector-ai)
[![License](https://img.shields.io/github/license/roryeckel/sector-ai.svg)](https://github.com/roryeckel/sector-ai/blob/master/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](https://ollama.com/download), then pull a model:

```sh
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:

```sh
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)

### 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 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

```sh
pip install sector-ai
```

Create a `.env` in the directory you will run from, or export the variables directly. The [Configuration](#configuration) table lists every setting; at minimum you need `TELEGRAM_BOT_TOKEN` and a reachable [backend](#backends).

```sh
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](#backends) — Ollama or any OpenAI-compatible server.
2. **Clone and install**:
    ```sh
    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.

```sh
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:

```sh
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](https://t.me/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](#context-length) and [Context compaction](#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
