Metadata-Version: 2.4
Name: sector-ai
Version: 1.4.1
Summary: Python Telegram Bot powered by LangChain and Ollama
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,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: python-telegram-bot==22.8
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: 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)

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

```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 Ollama.

```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 Ollama running (see above).
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` 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.

```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 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](https://t.me/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
