digitalheresy-forgellm 1.0.0__tar.gz

digitalheresy_forgellm-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023-2026 Digital Heresy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

digitalheresy_forgellm-1.0.0/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: digitalheresy-forgellm
+Version: 1.0.0
+Summary: LLM-powered multi-platform bot framework (Telegram + Discord; OpenAI + Anthropic)
+Home-page: https://github.com/Digital-Heresy/ForgeLLM
+Author: Digital Heresy
+Author-email: ronin.atx@gmail.com
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>2.0
+Requires-Dist: anthropic>=0.40
+Requires-Dist: PyYAML
+Requires-Dist: httpx
+Requires-Dist: beautifulsoup4
+Requires-Dist: validators
+Requires-Dist: tiktoken>=0.12
+Requires-Dist: python-telegram-bot>=20.8
+Requires-Dist: discord.py>=2.4
+Requires-Dist: aiosqlite>=0.19
+Requires-Dist: tzdata>=2025.2
+Requires-Dist: pypdf>=6.0
+Requires-Dist: defusedxml>=0.7
+Requires-Dist: charset-normalizer>=3.0
+Requires-Dist: python-docx>=1.2
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: Pillow>=11.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# ForgeLLM
+ForgeLLM bridges a chat platform and a Large Language Model (OpenAI GPT or Anthropic Claude). One bot identity can run multiple platform adapters at once, sharing the same persona and memory - see [Supported Platforms](#supported-platforms).
+
+<img src="assets/ForgeLLM_Logo.png" width=200 align=center />
+
+## Supported Platforms
+
+| Platform | Requirements | Bot creation |
+|---|---|---|
+| Telegram | A Telegram account **with a username** (not just a phone number) - [create one](https://telegram.org/). In groups, the bot must be [administrator](https://www.alphr.com/add-admin-telegram/) to respond to its name/nickname/initials. | [BotFather](https://t.me/BotFather) |
+| Discord | Invite the bot with the `bot` and `applications.commands` scopes. Guild channels are opt-in - run `/enable` in each channel you want it active in (see [Commands and Interactions](#commands-and-interactions)). | [Discord Developer Portal](https://discord.com/developers/applications) |
+
+Every feature below - conversation memory, tools, image generation, search, account linking - is implemented once in the shared response engine (`core/base_adapter.py`) and works identically on every platform. Adding a future platform means adding a row here and a new adapter under `forgellm/<platform>/`, not touching the feature logic itself.
+
+## Core Features
+* Each platform's interface handles special commands and basic "chatty" responses that don't require an LLM, like "Hello". Dynamic conversations are handed off to the LLM while the platform acts as the interaction broker.
+* Pass URLs in [square brackets] and mention how the bot should interpret them.
+  * Example: "What do you think of this article? [https://some_site/article]"
+  * Uses a separate model (configurable via `url_model`) to handle larger URL content.
+* Share documents and text files for analysis and summarisation.
+  * Supported formats: PDF (via pypdf), Microsoft Office documents (.docx via python-docx, .xlsx via openpyxl), plain-text files (.txt, .md, .rst, .csv, .json, etc.), HTML, and XML (via defusedxml).
+  * The bot extracts and summarises content, with automatic encoding detection for non-UTF-8 files. Files over 20 MB are rejected.
+  * Can be disabled via `document_processing: false` in config.
+* Share images for visual analysis.
+  * The bot analyzes photos using your configured LLM's vision capabilities. Optional captions are preserved; EXIF metadata is stripped before sending to any provider.
+  * Can be disabled via `image_analysis: false` in config. Requires the chat_model to support vision (controlled per-model in models.yaml, default true).
+* Generate images from text descriptions.
+  * Request images using natural language. The bot creates them via gpt-image-1 and sends them to your chat with a brief description as the caption.
+  * Requires an OpenAI API key. Supports three sizes: 1024x1024 (default), 1536x1024, and 1024x1536.
+  * Configurable cooldown between requests via `image_gen_cooldown_s` (default 30 seconds per user).
+  * The bot stores generation prompts in conversation history (the full prompt, not the caption), enabling it to recall past images and refine them across sessions. Ask for variations (e.g., "make it darker", "different composition") without repeating the full original prompt.
+* Ask questions about message history across all your chats using natural language; the bot will search, attribute messages to speakers, and include messages from other bots.
+  * Example: "Who said thanks for the breakdown?" or "What did George say about the project?" or "Show me the last few messages."
+  * All search filters (speaker, chat, date) are optional. Results are ordered most-recent-first. Configure `search_limit` to control how many results to return (default: 30).
+  * Search automatically finds users and chats by their current or past names, so you can reference them however you remember them.
+* Token limits measure conversation length and determine when to prune oldest messages to stay within model limits.
+  * The bot loads the user's full history across all chats up to 50% of the token budget. In private chats, shared group context fills the remaining budget, enabling the bot to reference group conversations from a private context.
+  * This eliminates amnesia when switching between private and group chats.
+* Conversation archive preserves long-term context without consuming token budget.
+  * Older messages are automatically distilled into concise daily summaries (Tier 1), then progressively compressed into monthly digests (Tier 2). Raw messages are never deleted; archive rows surface seamlessly in search results and context loading.
+  * Configurable via `archive_days` (default 60 days before Tier 1 triggers; Tier 2 triggers at 2x this value).
+* Persistent tone preference, carried across every chat and linked platform.
+  * Just ask, in natural conversation - e.g. "talk to me in a cute voice from now on" or "be more formal with me." The bot recognizes the request and remembers it for you specifically, without affecting how it talks to anyone else in a shared chat.
+  * Clear it the same way (e.g. "go back to normal"). Not a slash command - the LLM detects and applies the request automatically.
+* Users can manage privacy via two commands:
+  * `/forget` - In private chats, clears your full conversation and resets all active sessions. In group/guild chats, removes only your messages and cleans up paired bot replies.
+  * `/private` - Show status, or use `/private on`/`/private off` to change it (private chats only). When ON, your messages in private chats are excluded from group conversation contexts, enabling selective privacy even in shared groups.
+* Link your accounts across platforms with `/link`/`/unlink`, so the bot shares one unified memory for you regardless of which platform you're talking on - facts, search results, and tone preference all carry over.
+
+## Why a Chat Platform?
+Using a chat platform as the interface not only solves "exposing" the interface, but gives you boatloads of interactivity over a standard Command Line interface, or trying to create a website with input boxes and submit buttons to try to handle everything:
+1. Chat platforms already let you paste in verbose, multiline messages.
+2. Chat platforms already let you paste in pictures, videos, links, etc.
+3. Chat platforms already let you react with emojis, stickers, etc.
+4. Message reactions (👀) provide a lightweight read receipt without breaking conversation flow.
+
+## Supported LLM Providers
+ForgeLLM selects the LLM provider automatically based on the model name:
+
+| Model prefix | Provider | Example models |
+|---|---|---|
+| `gpt-` | OpenAI | `gpt-4o`, `gpt-4o-mini`, `gpt-5-mini` |
+| `claude-` | Anthropic | `claude-sonnet-4-6`, `claude-haiku-4-5` |
+
+Simply set `chat_model` (and optionally `url_model`) in your `config.yaml` to any supported model and supply the corresponding API key - no other changes needed. A future provider only needs a new prefix mapping in `core/providers/factory.py`.
+
+## Directories
+ForgeLLM creates the following directories:
+
+- **`configs`** - Bot configuration and model parameters (path configurable via `FORGELLM_CONFIGS_PATH`)
+  - `config.yaml` - Default bot configuration file (filename used throughout this README); can be changed by passing `config_file` to any adapter's `.set()`
+  - `models.yaml` - Token limits for each LLM model. Sensible defaults are built into the code, so the bot runs without this file. To override or add models, copy `configs/models.yaml.example` to `models.yaml` in this directory and edit it (an instance `models.yaml` replaces the built-in defaults entirely - list every model you use, not just the ones you change)
+- **`prompts`** - Bot personas (path configurable via `FORGELLM_PROMPTS_PATH`)
+  - `test_personality.prmpt` - Default bot persona file (filename used throughout this README); can be changed by passing `prompt_file` to any adapter's `.set()`
+  - A system appendix is automatically appended to every persona at runtime, teaching the LLM about cross-chat memory, search behavior, self-addressing, and confidentiality guidelines. User messages include speaker annotations with chat context and timestamps so the LLM always knows who is speaking, in which chat, and when.
+- **`logs`** - Bot instance logs (one per startup, named after the bot's platform username or `instance_name` config, e.g. `my_bot_2026-03-29_10-30-45.log`)
+  - Logs include anonymized platform IDs (user/chat/channel numeric identifiers) for privacy. Console shows INFO-level ForgeLLM messages only, prefixed with an `[identity label]` (the bot's platform username by default, or `instance_name` when configured).
+  - Log file timestamps are UTC in `[YYYY-MM-DD HH:MM:SS.mmm]` format.
+  - Bot keeps the 10 most recent logs per bot instance, automatically pruning older ones.
+  - Pass `-v` or `--verbose` on startup for DEBUG-level logging.
+- **`data`** - SQLite database (default `conversations.db`, customizable via `instance_name` config) storing all messages, users, and chats
+  - Users manage their data via `/forget` and `/private` commands.
+
+### Environment Variables for Paths
+Override default directory locations by setting these environment variables (useful for containerized deployments):
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `FORGELLM_CONFIGS_PATH` | Directory containing `config.yaml` and `models.yaml` | `{exec_dir}/configs` |
+| `FORGELLM_PROMPTS_PATH` | Directory containing prompt files | `{exec_dir}/prompts` |
+| `FORGELLM_LOGS_PATH` | Directory for log files | `{exec_dir}/logs` |
+| `FORGELLM_DATA_PATH` | Directory containing `conversations.db` | `{exec_dir}/data` |
+
+If unset, all paths default to subdirectories of the execution directory (the directory containing your entry-point script).
+
+## API Keys
+ForgeLLM supports five API keys. OpenAI, Anthropic, and VirusTotal keys load from environment variables or `.key` files. Platform keys load from their own `platforms.<name>.api_key` config field or env var (no `.key` file); config wins when explicitly set:
+
+| Key | Env Var | File/Config | When required |
+|-----|---------|-------------|---------------|
+| [OpenAI](https://platform.openai.com/api-keys) | `FORGELLM_OPENAI_API_KEY` | `openai.key` | For `gpt-*` models, or for image generation in any deployment |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `FORGELLM_ANTHROPIC_API_KEY` | `anthropic.key` | For `claude-*` models |
+| [Telegram](https://t.me/BotFather) | `FORGELLM_TELEGRAM_API_KEY` | `platforms.telegram.api_key` in `config.yaml` | Required to run the Telegram adapter |
+| [Discord](https://discord.com/developers/applications) | `FORGELLM_DISCORD_API_KEY` | `platforms.discord.api_key` in `config.yaml` | Required to run the Discord adapter |
+| [VirusTotal](https://www.virustotal.com/gui/my-apikey) | `FORGELLM_VIRUSTOTAL_API_KEY` | `virustotal.key` | For URL analysis |
+
+Missing provider keys (OpenAI or Anthropic) disable chat and URL analysis but allow the bot to start. Missing OpenAI key disables image generation. Missing VirusTotal disables URL analysis. At least one platform key is required - whichever adapter(s) you `.set()` will not start without its own key.
+
+Key files are created in the execution directory (or `FORGELLM_KEYS_PATH` for legacy deployments). Alternatively, set environment variables before launching, e.g.:
+```python
+os.environ['FORGELLM_OPENAI_API_KEY'] = my_vault.get('openai_key')
+os.environ['FORGELLM_ANTHROPIC_API_KEY'] = my_vault.get('anthropic_key')
+os.environ['FORGELLM_TELEGRAM_API_KEY'] = my_vault.get('telegram_key')
+os.environ['FORGELLM_DISCORD_API_KEY'] = my_vault.get('discord_key')
+os.environ['FORGELLM_VIRUSTOTAL_API_KEY'] = my_vault.get('virustotal_key')
+```
+
+## Commands and Interactions
+
+### User Commands
+- `/nick <name>` - Set your nickname (for bot use in group/guild chats).
+- `/forget` - Clear your conversation history. Shows a confirmation prompt before deletion. In private chats, clears everything and resets all active sessions. In group/guild chats, removes only your messages.
+- `/private` - Show your current private mode status (private/DM chats only). Use `/private on` or `/private off` to change it. When ON, your messages are excluded from group context loading; turning OFF permanently deletes your private-flagged messages.
+- `/link [code]` - Without a code, issues a 15-minute single-use linking code. Redeem it from another platform with `/link <code>` to merge your accounts into one shared memory. Private/DM chats only.
+- `/unlink` - Remove your account from its linked group. Private/DM chats only.
+
+### Admin Commands
+- `/tools` - List tools available to this bot instance (admin-only; private, group/guild, and supergroup chats - channels always denied). Shows the built-in search_messages and generate_image tools plus any webhook or MCP tools defined in config.yaml; in group/guild chats only tools with `allow_groups: true` are listed.
+- `/start` / `/stop` - Bring the bot online or offline (admin-only).
+- `/wipe` - Permanently delete all bot data (admin-only; confirmation prompt before deletion).
+- `/help` - Display available commands and usage information. In private/DM chats, if you are a bot owner, also shows administrator-only commands.
+- `/enable` / `/disable` (**Discord only**) - Opt the current guild channel into or out of bot activity (admin-only). Discord channels are opt-in by default; there's no Telegram equivalent since a Telegram group is always implicitly active.
+
+### Group/Guild Chat Triggers
+The bot responds in a group (Telegram) or guild channel (Discord) when you mention the bot, mention it by nickname/initials (configured via `config.yaml`), or reply directly to one of its messages.
+
+When multiple bots are @mentioned in the same message, the bot coexists: if you mention its nickname/initials or reply to its message, it always engages (you may be intentionally addressing both bots). If the only trigger is a reply to the bot's message AND the message exclusively addresses a different bot via @mention or plain-text name-address (e.g., "Cesura, response?" or "thoughts, Cesura?"), the bot yields silently - this supports threaded context without redundant responses. Plain-text addresses must match a known bot in the chat (its current username, or its current or past display name) to trigger a yield.
+
+Admin slash commands (`/help`, `/nick`, `/forget`, `/private`, `/tools`, `/start`, `/stop`, `/wipe`) work identically everywhere in private/DM chats. In groups/guilds, addressing differs per platform - see the mechanics table below.
+
+### Private Chat Behavior
+In a private/DM chat, the bot responds to all your messages. If you reply to an earlier message not already in the bot's context window, that message is automatically surfaced as inline context so the bot understands the full conversation thread.
+
+### Read Receipt
+As soon as the bot is triggered and about to respond (not deferring to another bot), it sends a 👀 emoji reaction on your message and shows a typing indicator while composing the reply - both arrive before the full LLM response, so you get quick feedback that the bot received your message.
+
+### Platform Mechanics
+Everything above is shared, platform-neutral behavior. Only the underlying wire protocol differs:
+
+| | Telegram | Discord |
+|---|---|---|
+| Mentioning the bot | `@botname` | native `@` mention |
+| Slash commands in groups need addressing? | Yes - use `/help@botname`, or reply to the bot's message, so co-present bots don't all answer a bare command | No - Discord routes slash commands natively to whichever bot registered them |
+| Read-receipt fallback | Falls back to a "Got it!" text reply on older clients without reaction support | N/A (reactions always supported) |
+
+## Bot Setup
+1. Ensure API keys are set up (see [API Keys](#api-keys)) and create your bot on each platform you plan to run (see [Supported Platforms](#supported-platforms)).
+2. Install ForgeLLM: `pip install digitalheresy-forgellm` (the importable package is `forgellm` regardless of the install name, e.g. `from forgellm.telegram.adapter import TelegramAdapter`).
+3. Configure `config.yaml` (created on first run). Top-level keys apply regardless of platform; each platform gets its own `platforms.<name>` section:
+   - `platforms.<name>.bot_owner`: username(s) with admin access (required, no `@`). Accepts a single string or a YAML list - matched by username string on every platform (no numeric IDs anywhere).
+   - `platforms.<name>.api_key`: that platform's bot API key (required to run that adapter). Lookup order: (1) this config field, (2) the platform's env var from the [API Keys](#api-keys) table. Config wins when explicitly set. Exits on placeholder, missing, or malformed key.
+   - `chat_model` / `url_model`: LLM models for conversation and URL analysis (e.g. `gpt-4o-mini`, `claude-sonnet-4-6`).
+   - `bot_nickname` / `bot_initials`: Names the bot responds to in groups/guilds.
+   - `instance_name`: Optional label for console prefix, log filename, and database name (e.g. `MyBot` produces `[MyBot] INFO: ...` on console, `MyBot_{timestamp}.log` logs, and `MyBot.db` database); omit to use the bot's platform username for logging and `conversations.db` for database. Use distinct names when running multiple bot instances in the same directory.
+   - `token_limit` / `search_limit`: Max tokens (default: model's maximum) / max search results (default: 30).
+   - `archive_days`: Days before messages are eligible for archival (optional; default 60, minimum 1). See [Core Features](#core-features).
+   - `document_processing` / `image_analysis`: Optional bools (default: true) to disable document summarisation / image analysis. `image_analysis` requires the chat_model to support vision (default true per-model in models.yaml).
+   - `image_gen_cooldown_s`: Optional int (default 30, minimum 0). Seconds a user must wait between image generation requests.
+   - `allow_local_webhooks`: Set to `true` to permit webhook/MCP URLs targeting loopback or link-local addresses (optional; default `false`). Useful when tools like Home Assistant run on the same host.
+   - `max_conversations`: Optional max chats kept in memory at once (default: 500, minimum 1). Least-recently-used chats beyond this cap are evicted and reload from the database on their next message.
+   - `tools`: Optional list of webhook and MCP tool definitions (admin-only, private chat only). See [docs/tools.md](docs/tools.md) for schema and examples.
+
+   Example `config.yaml`:
+   ```yaml
+   instance_name: MyBot
+   bot_nickname: Panzer
+   bot_initials: PZ
+   chat_model: gpt-4o
+   url_model: gpt-4o
+
+   platforms:
+     telegram:
+       api_key: abc123...
+       bot_owner: [MyUsername]
+   ```
+   Swap `telegram:` for `discord:` (with a Discord username in `bot_owner`) to run Discord instead - everything else is identical. Include both sections to run both (see [Running Multiple Platforms Together](#running-multiple-platforms-together)).
+4. One-time platform setup:
+
+   | Platform | One-time setup |
+   |---|---|
+   | Telegram | Disable group privacy mode in BotFather: `/setprivacy` -> select your bot -> Disable. Otherwise the bot won't receive group messages that don't mention it, so it can't index other bots or load cross-chat context. |
+   | Discord | Run `/enable` in each guild channel you want the bot active in - channels are opt-in by default. |
+5. Run the bot:
+   ```python
+   from forgellm.telegram.adapter import TelegramAdapter
+   telegram_bot = TelegramAdapter.set()
+   telegram_bot.run()
+   ```
+   Swap in `forgellm.discord.adapter.DiscordAdapter` to run Discord instead - same `.set()`/`.run()` shape. `run()` is synchronous and blocks until the bot is stopped.
+6. Type `/help` to see all available commands.
+
+### Running Multiple Platforms Together
+Construct every adapter you want, then run them concurrently via `start_async()` instead of `run()` (they share one event loop) so they share one bot identity, persona, and memory - the bot's own accounts on each platform are automatically linked to each other on startup, the same way `/link` connects two user accounts:
+```python
+import asyncio
+from forgellm.telegram.adapter import TelegramAdapter
+from forgellm.discord.adapter import DiscordAdapter
+
+async def main():
+    telegram_bot = TelegramAdapter.set()
+    discord_bot = DiscordAdapter.set()
+    await asyncio.gather(telegram_bot.start_async(), discord_bot.start_async())
+
+asyncio.run(main())
+```
+The bundled `run_bots.py` wires this up for you, including the bot's own cross-platform auto-link.
+
+## Resources
+* GitHub repository [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) has guides to create a Telegram bot.
+* GitHub repository [discord.py](https://github.com/Rapptz/discord.py) has guides to create a Discord bot.
+* For more information on OpenAI models and token limits:
+  * [OpenAI model overview and maximum tokens](https://platform.openai.com/docs/models)
+  * [OpenAI message conversion to tokens](https://github.com/openai/openai-python)
+  * [OpenAI custom fine-tuning](https://platform.openai.com/docs/guides/model-optimization)
+  * [OpenAI's tiktoken library](https://github.com/openai/tiktoken/tree/main)
+* For more information on Anthropic Claude models:
+  * [Anthropic model overview and context windows](https://docs.anthropic.com/en/docs/about-claude/models)
+  * [Anthropic Python SDK](https://github.com/anthropic/anthropic-sdk-python)

digitalheresy_forgellm-1.0.0/README.md

@@ -0,0 +1,228 @@
+# ForgeLLM
+ForgeLLM bridges a chat platform and a Large Language Model (OpenAI GPT or Anthropic Claude). One bot identity can run multiple platform adapters at once, sharing the same persona and memory - see [Supported Platforms](#supported-platforms).
+
+<img src="assets/ForgeLLM_Logo.png" width=200 align=center />
+
+## Supported Platforms
+
+| Platform | Requirements | Bot creation |
+|---|---|---|
+| Telegram | A Telegram account **with a username** (not just a phone number) - [create one](https://telegram.org/). In groups, the bot must be [administrator](https://www.alphr.com/add-admin-telegram/) to respond to its name/nickname/initials. | [BotFather](https://t.me/BotFather) |
+| Discord | Invite the bot with the `bot` and `applications.commands` scopes. Guild channels are opt-in - run `/enable` in each channel you want it active in (see [Commands and Interactions](#commands-and-interactions)). | [Discord Developer Portal](https://discord.com/developers/applications) |
+
+Every feature below - conversation memory, tools, image generation, search, account linking - is implemented once in the shared response engine (`core/base_adapter.py`) and works identically on every platform. Adding a future platform means adding a row here and a new adapter under `forgellm/<platform>/`, not touching the feature logic itself.
+
+## Core Features
+* Each platform's interface handles special commands and basic "chatty" responses that don't require an LLM, like "Hello". Dynamic conversations are handed off to the LLM while the platform acts as the interaction broker.
+* Pass URLs in [square brackets] and mention how the bot should interpret them.
+  * Example: "What do you think of this article? [https://some_site/article]"
+  * Uses a separate model (configurable via `url_model`) to handle larger URL content.
+* Share documents and text files for analysis and summarisation.
+  * Supported formats: PDF (via pypdf), Microsoft Office documents (.docx via python-docx, .xlsx via openpyxl), plain-text files (.txt, .md, .rst, .csv, .json, etc.), HTML, and XML (via defusedxml).
+  * The bot extracts and summarises content, with automatic encoding detection for non-UTF-8 files. Files over 20 MB are rejected.
+  * Can be disabled via `document_processing: false` in config.
+* Share images for visual analysis.
+  * The bot analyzes photos using your configured LLM's vision capabilities. Optional captions are preserved; EXIF metadata is stripped before sending to any provider.
+  * Can be disabled via `image_analysis: false` in config. Requires the chat_model to support vision (controlled per-model in models.yaml, default true).
+* Generate images from text descriptions.
+  * Request images using natural language. The bot creates them via gpt-image-1 and sends them to your chat with a brief description as the caption.
+  * Requires an OpenAI API key. Supports three sizes: 1024x1024 (default), 1536x1024, and 1024x1536.
+  * Configurable cooldown between requests via `image_gen_cooldown_s` (default 30 seconds per user).
+  * The bot stores generation prompts in conversation history (the full prompt, not the caption), enabling it to recall past images and refine them across sessions. Ask for variations (e.g., "make it darker", "different composition") without repeating the full original prompt.
+* Ask questions about message history across all your chats using natural language; the bot will search, attribute messages to speakers, and include messages from other bots.
+  * Example: "Who said thanks for the breakdown?" or "What did George say about the project?" or "Show me the last few messages."
+  * All search filters (speaker, chat, date) are optional. Results are ordered most-recent-first. Configure `search_limit` to control how many results to return (default: 30).
+  * Search automatically finds users and chats by their current or past names, so you can reference them however you remember them.
+* Token limits measure conversation length and determine when to prune oldest messages to stay within model limits.
+  * The bot loads the user's full history across all chats up to 50% of the token budget. In private chats, shared group context fills the remaining budget, enabling the bot to reference group conversations from a private context.
+  * This eliminates amnesia when switching between private and group chats.
+* Conversation archive preserves long-term context without consuming token budget.
+  * Older messages are automatically distilled into concise daily summaries (Tier 1), then progressively compressed into monthly digests (Tier 2). Raw messages are never deleted; archive rows surface seamlessly in search results and context loading.
+  * Configurable via `archive_days` (default 60 days before Tier 1 triggers; Tier 2 triggers at 2x this value).
+* Persistent tone preference, carried across every chat and linked platform.
+  * Just ask, in natural conversation - e.g. "talk to me in a cute voice from now on" or "be more formal with me." The bot recognizes the request and remembers it for you specifically, without affecting how it talks to anyone else in a shared chat.
+  * Clear it the same way (e.g. "go back to normal"). Not a slash command - the LLM detects and applies the request automatically.
+* Users can manage privacy via two commands:
+  * `/forget` - In private chats, clears your full conversation and resets all active sessions. In group/guild chats, removes only your messages and cleans up paired bot replies.
+  * `/private` - Show status, or use `/private on`/`/private off` to change it (private chats only). When ON, your messages in private chats are excluded from group conversation contexts, enabling selective privacy even in shared groups.
+* Link your accounts across platforms with `/link`/`/unlink`, so the bot shares one unified memory for you regardless of which platform you're talking on - facts, search results, and tone preference all carry over.
+
+## Why a Chat Platform?
+Using a chat platform as the interface not only solves "exposing" the interface, but gives you boatloads of interactivity over a standard Command Line interface, or trying to create a website with input boxes and submit buttons to try to handle everything:
+1. Chat platforms already let you paste in verbose, multiline messages.
+2. Chat platforms already let you paste in pictures, videos, links, etc.
+3. Chat platforms already let you react with emojis, stickers, etc.
+4. Message reactions (👀) provide a lightweight read receipt without breaking conversation flow.
+
+## Supported LLM Providers
+ForgeLLM selects the LLM provider automatically based on the model name:
+
+| Model prefix | Provider | Example models |
+|---|---|---|
+| `gpt-` | OpenAI | `gpt-4o`, `gpt-4o-mini`, `gpt-5-mini` |
+| `claude-` | Anthropic | `claude-sonnet-4-6`, `claude-haiku-4-5` |
+
+Simply set `chat_model` (and optionally `url_model`) in your `config.yaml` to any supported model and supply the corresponding API key - no other changes needed. A future provider only needs a new prefix mapping in `core/providers/factory.py`.
+
+## Directories
+ForgeLLM creates the following directories:
+
+- **`configs`** - Bot configuration and model parameters (path configurable via `FORGELLM_CONFIGS_PATH`)
+  - `config.yaml` - Default bot configuration file (filename used throughout this README); can be changed by passing `config_file` to any adapter's `.set()`
+  - `models.yaml` - Token limits for each LLM model. Sensible defaults are built into the code, so the bot runs without this file. To override or add models, copy `configs/models.yaml.example` to `models.yaml` in this directory and edit it (an instance `models.yaml` replaces the built-in defaults entirely - list every model you use, not just the ones you change)
+- **`prompts`** - Bot personas (path configurable via `FORGELLM_PROMPTS_PATH`)
+  - `test_personality.prmpt` - Default bot persona file (filename used throughout this README); can be changed by passing `prompt_file` to any adapter's `.set()`
+  - A system appendix is automatically appended to every persona at runtime, teaching the LLM about cross-chat memory, search behavior, self-addressing, and confidentiality guidelines. User messages include speaker annotations with chat context and timestamps so the LLM always knows who is speaking, in which chat, and when.
+- **`logs`** - Bot instance logs (one per startup, named after the bot's platform username or `instance_name` config, e.g. `my_bot_2026-03-29_10-30-45.log`)
+  - Logs include anonymized platform IDs (user/chat/channel numeric identifiers) for privacy. Console shows INFO-level ForgeLLM messages only, prefixed with an `[identity label]` (the bot's platform username by default, or `instance_name` when configured).
+  - Log file timestamps are UTC in `[YYYY-MM-DD HH:MM:SS.mmm]` format.
+  - Bot keeps the 10 most recent logs per bot instance, automatically pruning older ones.
+  - Pass `-v` or `--verbose` on startup for DEBUG-level logging.
+- **`data`** - SQLite database (default `conversations.db`, customizable via `instance_name` config) storing all messages, users, and chats
+  - Users manage their data via `/forget` and `/private` commands.
+
+### Environment Variables for Paths
+Override default directory locations by setting these environment variables (useful for containerized deployments):
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `FORGELLM_CONFIGS_PATH` | Directory containing `config.yaml` and `models.yaml` | `{exec_dir}/configs` |
+| `FORGELLM_PROMPTS_PATH` | Directory containing prompt files | `{exec_dir}/prompts` |
+| `FORGELLM_LOGS_PATH` | Directory for log files | `{exec_dir}/logs` |
+| `FORGELLM_DATA_PATH` | Directory containing `conversations.db` | `{exec_dir}/data` |
+
+If unset, all paths default to subdirectories of the execution directory (the directory containing your entry-point script).
+
+## API Keys
+ForgeLLM supports five API keys. OpenAI, Anthropic, and VirusTotal keys load from environment variables or `.key` files. Platform keys load from their own `platforms.<name>.api_key` config field or env var (no `.key` file); config wins when explicitly set:
+
+| Key | Env Var | File/Config | When required |
+|-----|---------|-------------|---------------|
+| [OpenAI](https://platform.openai.com/api-keys) | `FORGELLM_OPENAI_API_KEY` | `openai.key` | For `gpt-*` models, or for image generation in any deployment |
+| [Anthropic](https://console.anthropic.com/settings/keys) | `FORGELLM_ANTHROPIC_API_KEY` | `anthropic.key` | For `claude-*` models |
+| [Telegram](https://t.me/BotFather) | `FORGELLM_TELEGRAM_API_KEY` | `platforms.telegram.api_key` in `config.yaml` | Required to run the Telegram adapter |
+| [Discord](https://discord.com/developers/applications) | `FORGELLM_DISCORD_API_KEY` | `platforms.discord.api_key` in `config.yaml` | Required to run the Discord adapter |
+| [VirusTotal](https://www.virustotal.com/gui/my-apikey) | `FORGELLM_VIRUSTOTAL_API_KEY` | `virustotal.key` | For URL analysis |
+
+Missing provider keys (OpenAI or Anthropic) disable chat and URL analysis but allow the bot to start. Missing OpenAI key disables image generation. Missing VirusTotal disables URL analysis. At least one platform key is required - whichever adapter(s) you `.set()` will not start without its own key.
+
+Key files are created in the execution directory (or `FORGELLM_KEYS_PATH` for legacy deployments). Alternatively, set environment variables before launching, e.g.:
+```python
+os.environ['FORGELLM_OPENAI_API_KEY'] = my_vault.get('openai_key')
+os.environ['FORGELLM_ANTHROPIC_API_KEY'] = my_vault.get('anthropic_key')
+os.environ['FORGELLM_TELEGRAM_API_KEY'] = my_vault.get('telegram_key')
+os.environ['FORGELLM_DISCORD_API_KEY'] = my_vault.get('discord_key')
+os.environ['FORGELLM_VIRUSTOTAL_API_KEY'] = my_vault.get('virustotal_key')
+```
+
+## Commands and Interactions
+
+### User Commands
+- `/nick <name>` - Set your nickname (for bot use in group/guild chats).
+- `/forget` - Clear your conversation history. Shows a confirmation prompt before deletion. In private chats, clears everything and resets all active sessions. In group/guild chats, removes only your messages.
+- `/private` - Show your current private mode status (private/DM chats only). Use `/private on` or `/private off` to change it. When ON, your messages are excluded from group context loading; turning OFF permanently deletes your private-flagged messages.
+- `/link [code]` - Without a code, issues a 15-minute single-use linking code. Redeem it from another platform with `/link <code>` to merge your accounts into one shared memory. Private/DM chats only.
+- `/unlink` - Remove your account from its linked group. Private/DM chats only.
+
+### Admin Commands
+- `/tools` - List tools available to this bot instance (admin-only; private, group/guild, and supergroup chats - channels always denied). Shows the built-in search_messages and generate_image tools plus any webhook or MCP tools defined in config.yaml; in group/guild chats only tools with `allow_groups: true` are listed.
+- `/start` / `/stop` - Bring the bot online or offline (admin-only).
+- `/wipe` - Permanently delete all bot data (admin-only; confirmation prompt before deletion).
+- `/help` - Display available commands and usage information. In private/DM chats, if you are a bot owner, also shows administrator-only commands.
+- `/enable` / `/disable` (**Discord only**) - Opt the current guild channel into or out of bot activity (admin-only). Discord channels are opt-in by default; there's no Telegram equivalent since a Telegram group is always implicitly active.
+
+### Group/Guild Chat Triggers
+The bot responds in a group (Telegram) or guild channel (Discord) when you mention the bot, mention it by nickname/initials (configured via `config.yaml`), or reply directly to one of its messages.
+
+When multiple bots are @mentioned in the same message, the bot coexists: if you mention its nickname/initials or reply to its message, it always engages (you may be intentionally addressing both bots). If the only trigger is a reply to the bot's message AND the message exclusively addresses a different bot via @mention or plain-text name-address (e.g., "Cesura, response?" or "thoughts, Cesura?"), the bot yields silently - this supports threaded context without redundant responses. Plain-text addresses must match a known bot in the chat (its current username, or its current or past display name) to trigger a yield.
+
+Admin slash commands (`/help`, `/nick`, `/forget`, `/private`, `/tools`, `/start`, `/stop`, `/wipe`) work identically everywhere in private/DM chats. In groups/guilds, addressing differs per platform - see the mechanics table below.
+
+### Private Chat Behavior
+In a private/DM chat, the bot responds to all your messages. If you reply to an earlier message not already in the bot's context window, that message is automatically surfaced as inline context so the bot understands the full conversation thread.
+
+### Read Receipt
+As soon as the bot is triggered and about to respond (not deferring to another bot), it sends a 👀 emoji reaction on your message and shows a typing indicator while composing the reply - both arrive before the full LLM response, so you get quick feedback that the bot received your message.
+
+### Platform Mechanics
+Everything above is shared, platform-neutral behavior. Only the underlying wire protocol differs:
+
+| | Telegram | Discord |
+|---|---|---|
+| Mentioning the bot | `@botname` | native `@` mention |
+| Slash commands in groups need addressing? | Yes - use `/help@botname`, or reply to the bot's message, so co-present bots don't all answer a bare command | No - Discord routes slash commands natively to whichever bot registered them |
+| Read-receipt fallback | Falls back to a "Got it!" text reply on older clients without reaction support | N/A (reactions always supported) |
+
+## Bot Setup
+1. Ensure API keys are set up (see [API Keys](#api-keys)) and create your bot on each platform you plan to run (see [Supported Platforms](#supported-platforms)).
+2. Install ForgeLLM: `pip install digitalheresy-forgellm` (the importable package is `forgellm` regardless of the install name, e.g. `from forgellm.telegram.adapter import TelegramAdapter`).
+3. Configure `config.yaml` (created on first run). Top-level keys apply regardless of platform; each platform gets its own `platforms.<name>` section:
+   - `platforms.<name>.bot_owner`: username(s) with admin access (required, no `@`). Accepts a single string or a YAML list - matched by username string on every platform (no numeric IDs anywhere).
+   - `platforms.<name>.api_key`: that platform's bot API key (required to run that adapter). Lookup order: (1) this config field, (2) the platform's env var from the [API Keys](#api-keys) table. Config wins when explicitly set. Exits on placeholder, missing, or malformed key.
+   - `chat_model` / `url_model`: LLM models for conversation and URL analysis (e.g. `gpt-4o-mini`, `claude-sonnet-4-6`).
+   - `bot_nickname` / `bot_initials`: Names the bot responds to in groups/guilds.
+   - `instance_name`: Optional label for console prefix, log filename, and database name (e.g. `MyBot` produces `[MyBot] INFO: ...` on console, `MyBot_{timestamp}.log` logs, and `MyBot.db` database); omit to use the bot's platform username for logging and `conversations.db` for database. Use distinct names when running multiple bot instances in the same directory.
+   - `token_limit` / `search_limit`: Max tokens (default: model's maximum) / max search results (default: 30).
+   - `archive_days`: Days before messages are eligible for archival (optional; default 60, minimum 1). See [Core Features](#core-features).
+   - `document_processing` / `image_analysis`: Optional bools (default: true) to disable document summarisation / image analysis. `image_analysis` requires the chat_model to support vision (default true per-model in models.yaml).
+   - `image_gen_cooldown_s`: Optional int (default 30, minimum 0). Seconds a user must wait between image generation requests.
+   - `allow_local_webhooks`: Set to `true` to permit webhook/MCP URLs targeting loopback or link-local addresses (optional; default `false`). Useful when tools like Home Assistant run on the same host.
+   - `max_conversations`: Optional max chats kept in memory at once (default: 500, minimum 1). Least-recently-used chats beyond this cap are evicted and reload from the database on their next message.
+   - `tools`: Optional list of webhook and MCP tool definitions (admin-only, private chat only). See [docs/tools.md](docs/tools.md) for schema and examples.
+
+   Example `config.yaml`:
+   ```yaml
+   instance_name: MyBot
+   bot_nickname: Panzer
+   bot_initials: PZ
+   chat_model: gpt-4o
+   url_model: gpt-4o
+
+   platforms:
+     telegram:
+       api_key: abc123...
+       bot_owner: [MyUsername]
+   ```
+   Swap `telegram:` for `discord:` (with a Discord username in `bot_owner`) to run Discord instead - everything else is identical. Include both sections to run both (see [Running Multiple Platforms Together](#running-multiple-platforms-together)).
+4. One-time platform setup:
+
+   | Platform | One-time setup |
+   |---|---|
+   | Telegram | Disable group privacy mode in BotFather: `/setprivacy` -> select your bot -> Disable. Otherwise the bot won't receive group messages that don't mention it, so it can't index other bots or load cross-chat context. |
+   | Discord | Run `/enable` in each guild channel you want the bot active in - channels are opt-in by default. |
+5. Run the bot:
+   ```python
+   from forgellm.telegram.adapter import TelegramAdapter
+   telegram_bot = TelegramAdapter.set()
+   telegram_bot.run()
+   ```
+   Swap in `forgellm.discord.adapter.DiscordAdapter` to run Discord instead - same `.set()`/`.run()` shape. `run()` is synchronous and blocks until the bot is stopped.
+6. Type `/help` to see all available commands.
+
+### Running Multiple Platforms Together
+Construct every adapter you want, then run them concurrently via `start_async()` instead of `run()` (they share one event loop) so they share one bot identity, persona, and memory - the bot's own accounts on each platform are automatically linked to each other on startup, the same way `/link` connects two user accounts:
+```python
+import asyncio
+from forgellm.telegram.adapter import TelegramAdapter
+from forgellm.discord.adapter import DiscordAdapter
+
+async def main():
+    telegram_bot = TelegramAdapter.set()
+    discord_bot = DiscordAdapter.set()
+    await asyncio.gather(telegram_bot.start_async(), discord_bot.start_async())
+
+asyncio.run(main())
+```
+The bundled `run_bots.py` wires this up for you, including the bot's own cross-platform auto-link.
+
+## Resources
+* GitHub repository [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) has guides to create a Telegram bot.
+* GitHub repository [discord.py](https://github.com/Rapptz/discord.py) has guides to create a Discord bot.
+* For more information on OpenAI models and token limits:
+  * [OpenAI model overview and maximum tokens](https://platform.openai.com/docs/models)
+  * [OpenAI message conversion to tokens](https://github.com/openai/openai-python)
+  * [OpenAI custom fine-tuning](https://platform.openai.com/docs/guides/model-optimization)
+  * [OpenAI's tiktoken library](https://github.com/openai/tiktoken/tree/main)
+* For more information on Anthropic Claude models:
+  * [Anthropic model overview and context windows](https://docs.anthropic.com/en/docs/about-claude/models)
+  * [Anthropic Python SDK](https://github.com/anthropic/anthropic-sdk-python)

digitalheresy_forgellm-1.0.0/Tests/test_core/test_admin.py

@@ -0,0 +1,42 @@
+"""
+Unit tests for a4rn - bot_owner normalisation to list[str] (platform-agnostic).
+"""
+import unittest
+
+
+def _normalise_owners(bot_owner):
+    """Mirrors the owner normalisation in TelegramAdapter.__init__."""
+    owners = bot_owner if isinstance(bot_owner, list) else [bot_owner]
+    return [str(u).strip() for u in owners if str(u).strip()]
+
+
+class TestOwnerNormalisation(unittest.TestCase):
+    """Tests for bot_owner normalisation to list[str]."""
+
+    def test_single_string_produces_one_element_list(self):
+        """A single username string must become a one-element list."""
+        self.assertEqual(_normalise_owners('alice'), ['alice'])
+
+    def test_already_normalised_list_remains_unchanged(self):
+        """An already-normalised list of usernames remains unchanged after normalisation."""
+        self.assertEqual(_normalise_owners(['alice', 'bob']), ['alice', 'bob'])
+
+    def test_single_string_with_whitespace_is_stripped(self):
+        """Leading/trailing whitespace in a single username must be stripped."""
+        self.assertEqual(_normalise_owners('  alice  '), ['alice'])
+
+    def test_list_entries_with_whitespace_are_stripped(self):
+        """Leading/trailing whitespace in list entries must be stripped."""
+        self.assertEqual(_normalise_owners(['  alice  ', ' bob']), ['alice', 'bob'])
+
+    def test_empty_string_entries_are_filtered(self):
+        """Empty string entries in a list must be filtered out."""
+        self.assertEqual(_normalise_owners(['alice', '', '  ', 'bob']), ['alice', 'bob'])
+
+    def test_single_empty_string_produces_empty_list(self):
+        """An empty string bot_owner must produce an empty list."""
+        self.assertEqual(_normalise_owners(''), [])
+
+    def test_list_with_single_entry(self):
+        """A one-element list behaves the same as a single string."""
+        self.assertEqual(_normalise_owners(['alice']), ['alice'])