TeLLMgramBot 3.13.2__tar.gz → 3.13.4__tar.gz

{tellmgrambot-3.13.2 → tellmgrambot-3.13.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.13.2
+Version: 3.13.4
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -75,18 +75,17 @@ Simply set `chat_model` (and optionally `url_model`) in your `config.yaml` to an
 ## Directories
 TeLLMgramBot creates the following directories:
 
-- **`configs`** - Bot configuration and model parameters
-  - `config.yaml` - Bot settings: owner, model names, token limits, search limits, nickname/initials, database name
+- **`configs`** - Bot configuration and model parameters (path configurable via `TELLMGRAMBOT_CONFIGS_PATH`)
+  - `config.yaml` - Default bot configuration file (filename used throughout this README); can be changed by passing `config_file` to `TelegramBot.set()`
   - `models.yaml` - Token limits for each LLM model (pre-populated on first run)
-- **`prompts`** - Bot personas and URL analysis templates
-  - `test_personality.prmpt` - Sample bot personality (multi-provider, can be renamed)
-  - `url_analysis.prmpt` - URL summarization prompt template
+- **`prompts`** - Bot personas (path configurable via `TELLMGRAMBOT_PROMPTS_PATH`)
+  - `test_personality.prmpt` - Default bot persona file (filename used throughout this README); can be changed by passing `prompt_file` to `TelegramBot.set()`
   - A system appendix is automatically appended to every persona at runtime, teaching the LLM about cross-chat memory and search behavior. 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 Telegram username or `log_name` config, e.g. `my_bot_2026-03-29_10-30-45.log`)
-  - Logs include anonymized Telegram IDs for privacy. Console shows INFO-level TeLLMgramBot messages only, prefixed with an `[identity label]` (the bot's Telegram username by default, or `log_name` when configured).
+- **`logs`** - Bot instance logs (one per startup, named after the bot's Telegram username or `instance_name` config, e.g. `my_bot_2026-03-29_10-30-45.log`)
+  - Logs include anonymized Telegram IDs for privacy. Console shows INFO-level TeLLMgramBot messages only, prefixed with an `[identity label]` (the bot's Telegram username by default, or `instance_name` when configured).
   - 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 `db_name` config) storing all messages, users, and chats
+- **`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
@@ -102,13 +101,13 @@ Override default directory locations by setting these environment variables (use
 If unset, all paths default to subdirectories of the execution directory (the directory containing your entry-point script).
 
 ## API Keys
-TeLLMgramBot supports four API keys, each loadable from environment variables or `.key` files:
+TeLLMgramBot supports four API keys. OpenAI, Anthropic, and VirusTotal keys load from environment variables or `.key` files. The Telegram key loads from its env var or the bot config field `telegram_api_key` (no `.key` file):
 
-| Key | Env Var | File | When required |
-|-----|---------|------|---------------|
+| Key | Env Var | File/Config | When required |
+|-----|---------|-------------|---------------|
 | [OpenAI](https://platform.openai.com/api-keys) | `TELLMGRAMBOT_OPENAI_API_KEY` | `openai.key` | For `gpt-*` models |
 | [Anthropic](https://console.anthropic.com/settings/keys) | `TELLMGRAMBOT_ANTHROPIC_API_KEY` | `anthropic.key` | For `claude-*` models |
-| [Telegram](https://t.me/BotFather) | `TELLMGRAMBOT_TELEGRAM_API_KEY` | `telegram.key` | Always required |
+| [Telegram](https://t.me/BotFather) | `TELLMGRAMBOT_TELEGRAM_API_KEY` | bot config `telegram_api_key` in `config.yaml` | Always required |
 | [VirusTotal](https://www.virustotal.com/gui/my-apikey) | `TELLMGRAMBOT_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 VirusTotal disables URL analysis. Telegram key is required - the bot will not start without it.
@@ -151,9 +150,9 @@ When the bot is triggered in a group and about to respond (not deferring to anot
    - `bot_owner`: Telegram username(s) with admin access (required, no `@`). Accepts a single string or a YAML list of usernames.
    - `chat_model`: LLM model for conversation (e.g. `gpt-4o-mini` or `claude-sonnet-4-6`)
    - `url_model`: LLM model for URL analysis (e.g. `gpt-4o` or `claude-haiku-4-5`)
+   - `telegram_api_key`: Telegram bot API key (required). Lookup order: (1) `TELLMGRAMBOT_TELEGRAM_API_KEY` env var, (2) `telegram_api_key` in `config.yaml`. Exits on placeholder, missing, or malformed key.
    - `bot_nickname` / `bot_initials`: Names the bot responds to in groups
-   - `db_name`: Optional custom database filename without extension (e.g. `MyBot` creates `MyBot.db`); omit for default `conversations.db`. Use distinct names when running multiple bot instances in the same directory.
-   - `log_name`: Optional label used for the console prefix and log filename (e.g. `MyBot` produces `[MyBot] INFO: ...` on the console and `MyBot_{timestamp}.log`); omit to use the bot's Telegram username. Useful for multi-platform deployments sharing the same config.
+   - `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 bot's Telegram username for logging and `conversations.db` for database. Use distinct names when running multiple bot instances in the same directory.
    - `token_limit`: Max tokens (optional; defaults to model's maximum)
    - `search_limit`: Max search results (optional; defaults to 30)
    - `archive_days`: Days before messages are eligible for archival (optional; default 60, minimum 1). Older messages are distilled into daily summaries, then progressively compressed into monthly digests. Once archived their respective raw messages do not return to the LLM context any more, only when searching messages.

{tellmgrambot-3.13.2 → tellmgrambot-3.13.4}/README.md

@@ -43,18 +43,17 @@ Simply set `chat_model` (and optionally `url_model`) in your `config.yaml` to an
 ## Directories
 TeLLMgramBot creates the following directories:
 
-- **`configs`** - Bot configuration and model parameters
-  - `config.yaml` - Bot settings: owner, model names, token limits, search limits, nickname/initials, database name
+- **`configs`** - Bot configuration and model parameters (path configurable via `TELLMGRAMBOT_CONFIGS_PATH`)
+  - `config.yaml` - Default bot configuration file (filename used throughout this README); can be changed by passing `config_file` to `TelegramBot.set()`
   - `models.yaml` - Token limits for each LLM model (pre-populated on first run)
-- **`prompts`** - Bot personas and URL analysis templates
-  - `test_personality.prmpt` - Sample bot personality (multi-provider, can be renamed)
-  - `url_analysis.prmpt` - URL summarization prompt template
+- **`prompts`** - Bot personas (path configurable via `TELLMGRAMBOT_PROMPTS_PATH`)
+  - `test_personality.prmpt` - Default bot persona file (filename used throughout this README); can be changed by passing `prompt_file` to `TelegramBot.set()`
   - A system appendix is automatically appended to every persona at runtime, teaching the LLM about cross-chat memory and search behavior. 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 Telegram username or `log_name` config, e.g. `my_bot_2026-03-29_10-30-45.log`)
-  - Logs include anonymized Telegram IDs for privacy. Console shows INFO-level TeLLMgramBot messages only, prefixed with an `[identity label]` (the bot's Telegram username by default, or `log_name` when configured).
+- **`logs`** - Bot instance logs (one per startup, named after the bot's Telegram username or `instance_name` config, e.g. `my_bot_2026-03-29_10-30-45.log`)
+  - Logs include anonymized Telegram IDs for privacy. Console shows INFO-level TeLLMgramBot messages only, prefixed with an `[identity label]` (the bot's Telegram username by default, or `instance_name` when configured).
   - 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 `db_name` config) storing all messages, users, and chats
+- **`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
@@ -70,13 +69,13 @@ Override default directory locations by setting these environment variables (use
 If unset, all paths default to subdirectories of the execution directory (the directory containing your entry-point script).
 
 ## API Keys
-TeLLMgramBot supports four API keys, each loadable from environment variables or `.key` files:
+TeLLMgramBot supports four API keys. OpenAI, Anthropic, and VirusTotal keys load from environment variables or `.key` files. The Telegram key loads from its env var or the bot config field `telegram_api_key` (no `.key` file):
 
-| Key | Env Var | File | When required |
-|-----|---------|------|---------------|
+| Key | Env Var | File/Config | When required |
+|-----|---------|-------------|---------------|
 | [OpenAI](https://platform.openai.com/api-keys) | `TELLMGRAMBOT_OPENAI_API_KEY` | `openai.key` | For `gpt-*` models |
 | [Anthropic](https://console.anthropic.com/settings/keys) | `TELLMGRAMBOT_ANTHROPIC_API_KEY` | `anthropic.key` | For `claude-*` models |
-| [Telegram](https://t.me/BotFather) | `TELLMGRAMBOT_TELEGRAM_API_KEY` | `telegram.key` | Always required |
+| [Telegram](https://t.me/BotFather) | `TELLMGRAMBOT_TELEGRAM_API_KEY` | bot config `telegram_api_key` in `config.yaml` | Always required |
 | [VirusTotal](https://www.virustotal.com/gui/my-apikey) | `TELLMGRAMBOT_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 VirusTotal disables URL analysis. Telegram key is required - the bot will not start without it.
@@ -119,9 +118,9 @@ When the bot is triggered in a group and about to respond (not deferring to anot
    - `bot_owner`: Telegram username(s) with admin access (required, no `@`). Accepts a single string or a YAML list of usernames.
    - `chat_model`: LLM model for conversation (e.g. `gpt-4o-mini` or `claude-sonnet-4-6`)
    - `url_model`: LLM model for URL analysis (e.g. `gpt-4o` or `claude-haiku-4-5`)
+   - `telegram_api_key`: Telegram bot API key (required). Lookup order: (1) `TELLMGRAMBOT_TELEGRAM_API_KEY` env var, (2) `telegram_api_key` in `config.yaml`. Exits on placeholder, missing, or malformed key.
    - `bot_nickname` / `bot_initials`: Names the bot responds to in groups
-   - `db_name`: Optional custom database filename without extension (e.g. `MyBot` creates `MyBot.db`); omit for default `conversations.db`. Use distinct names when running multiple bot instances in the same directory.
-   - `log_name`: Optional label used for the console prefix and log filename (e.g. `MyBot` produces `[MyBot] INFO: ...` on the console and `MyBot_{timestamp}.log`); omit to use the bot's Telegram username. Useful for multi-platform deployments sharing the same config.
+   - `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 bot's Telegram username for logging and `conversations.db` for database. Use distinct names when running multiple bot instances in the same directory.
    - `token_limit`: Max tokens (optional; defaults to model's maximum)
    - `search_limit`: Max search results (optional; defaults to 30)
    - `archive_days`: Days before messages are eligible for archival (optional; default 60, minimum 1). Older messages are distilled into daily summaries, then progressively compressed into monthly digests. Once archived their respective raw messages do not return to the LLM context any more, only when searching messages.

{tellmgrambot-3.13.2 → tellmgrambot-3.13.4}/TeLLMgramBot/TeLLMgramBot.py

@@ -103,7 +103,7 @@ class TelegramBot:
             self.telegram['username'] = bot.username
             self.telegram['first_name'] = bot.first_name
             self.telegram['last_name'] = bot.last_name
-            bind_log_identity(bot.username, self._log_name)
+            bind_log_identity(bot.username, self._instance_name)
         except Exception as e:
             # Fail fast if the bot's identity cannot be fetched to avoid
             # continuing with an uninitialized self.telegram['username'].
@@ -183,7 +183,7 @@ class TelegramBot:
         List all registered tools available to this bot instance (admin-only, private chat only).
 
         Shows name and description for every tool the bot exposes, including the built-in
-        search_messages tool and any webhook tools defined in config.yaml. Restricted to
+        search_messages tool and any webhook tools defined in bot config. Restricted to
         bot_owner in a private chat; any other caller receives a generic denial.
 
         Args:
@@ -506,7 +506,7 @@ class TelegramBot:
         reply = _MSG_PROCESS_ERROR
         if url_match and self.key_status.url_analysis_enabled:
             await msg.reply_text("Sure, give me a moment to look at that URL...")
-            reply = await handle_url_ask(text, self.llm['url_model'])
+            reply = await handle_url_ask(text, self.llm['url_model'], conv.system_content)
         elif self._online and self.key_status.chat_enabled:
             # This is the transition point between quick Telegram replies and the LLM.
             tools = self._build_tool_list(chat_type, username)
@@ -964,7 +964,7 @@ class TelegramBot:
         archive_days   = INIT_BOT_CONFIG['archive_days'],
         persona_prompt = INIT_BOT_CONFIG['persona_prompt'],
         key_status: ApiKeyStatus | None = None,
-        log_name: str | None = None,
+        instance_name: str | None = None,
         webhook_schemas: list | None = None,
         webhook_defs: dict | None = None,
     ):
@@ -983,8 +983,8 @@ class TelegramBot:
             persona_temp: LLM temperature (0.0-2.0). If None, defaults to 1.0.
             persona_prompt: System prompt defining the bot's behavior and personality.
             key_status: ApiKeyStatus object indicating available features. If None, calls init_structure().
-            log_name: Optional label for console prefix and log file name (from config.yaml `log_name`).
-                      Defaults to the bot's Telegram username when not set.
+            instance_name: Optional label for console prefix and log file name (from bot config `instance_name`).
+                           Defaults to the bot's Telegram username when not set.
             archive_days: Days before messages are eligible for Tier 1 archival (default: 60).
                           Must be an integer >= 1; invalid values log a warning and fall back to 60.
                           Tier 2 compression triggers at archive_days * 2.
@@ -1001,7 +1001,7 @@ class TelegramBot:
         """
         # Starting to initialize, not online yet
         self._online = False
-        self._log_name = log_name
+        self._instance_name = instance_name
 
         # Bootstrap structure and logging; init_logging() is a no-op if init_structure already ran it.
         self.key_status = key_status if key_status is not None else init_structure()[0]
@@ -1104,13 +1104,13 @@ class TelegramBot:
         Side Effects:
             - Calls init_structure() which creates directories, config/prompt files, and checks API keys.
             - Calls discover_mcp_tools() if any 'mcp_server:' entries are in config (gracefully degrades if called from async context).
-            - Prints API key status summary and optional warnings if config values are missing or prompt is empty.
-            - Log identity/file label is taken from config.yaml `log_name` when set; otherwise defaults to the bot's Telegram username once _tele_info() resolves.
+            - May log warnings (for missing config values, empty prompt, or skipped MCP discovery), but does not print a startup API key status summary.
+            - Log identity/file label is taken from bot config `instance_name` when set; otherwise defaults to the bot's Telegram username once _tele_info() resolves.
         """
         # Bootstrap directories, logging, config, prompt (with appendix), and API keys in one call.
         key_status, config, prompt = init_structure(config_file, prompt_file)
 
-        # Build the webhook tool registry from the optional 'tools:' block in config.yaml.
+        # Build the webhook tool registry from the optional 'tools:' block in bot config.
         allow_local = config['allow_local_webhooks'] or False
         webhook_schemas, webhook_defs = build_tool_registry(config.get('tools') or [], allow_local)
 
@@ -1145,7 +1145,7 @@ class TelegramBot:
             archive_days    = config['archive_days'],
             persona_prompt  = prompt,
             key_status      = key_status,
-            log_name        = config['log_name'],
+            instance_name   = config['instance_name'],
             webhook_schemas = webhook_schemas,
             webhook_defs    = webhook_defs,
         )

{tellmgrambot-3.13.2 → tellmgrambot-3.13.4}/TeLLMgramBot/conversation.py

@@ -111,9 +111,9 @@ class Conversation:
         init and on every incoming message so long sessions always carry an accurate
         UTC timestamp in format 'YYYY-MM-DD HH:MM UTC'.
         """
-        dt_line = f'\nCurrent date and time: {format_now(None)}'
+        dt_line = f'\n- Current date and time: {format_now(None)}'
         new_content, n = re.subn(
-            r'\nCurrent date and time:.*',
+            r'\n-?\s*Current date and time:.*',
             dt_line,
             self.system_content,
         )

{tellmgrambot-3.13.2 → tellmgrambot-3.13.4}/TeLLMgramBot/initialize.py

@@ -96,14 +96,16 @@ class ApiKeyStatus:
     disabled_reasons: dict = field(default_factory=dict)
 
 
+_TELEGRAM_KEY_RE = re.compile(r'^\d+:[A-Za-z0-9_-]+$')
+
 INIT_BOT_CONFIG = {
     'bot_owner': '<YOUR USERNAME>',
     'bot_nickname': 'Testy',
     'bot_initials': 'TB',
     'chat_model': 'gpt-5-mini',
     'url_model': 'gpt-5',
-    'db_name': None,
-    'log_name': None,
+    'telegram_api_key': '<YOUR TELEGRAM API KEY HERE>',
+    'instance_name': None,
     'token_limit': None,
     'search_limit': None,
     'persona_temp': None,
@@ -113,8 +115,7 @@ INIT_BOT_CONFIG = {
 }
 
 INIT_BOT_CONFIG_COMMENTS = {
-    'db_name': '# Optional, custom DB filename (e.g. MyBot -> MyBot.db). Defaults to conversations.db',
-    'log_name': '# Optional, label for console prefix and log file name. Defaults to the bot\'s Telegram username',
+    'instance_name': '# Optional, sets log label and DB filename (e.g. MyBot -> MyBot.db). If omitted, log label defaults to the bot\'s Telegram username and DB filename remains conversations.db',
     'token_limit': '# Optional, overrides the chat_model\'s default max token limit',
     'search_limit': '# Optional, max results returned by message search (default: 30)',
     'persona_temp': '# Optional, LLM temperature 0.0-2.0 (default: model\'s default)',
@@ -125,12 +126,13 @@ INIT_BOT_CONFIG_COMMENTS = {
 # Append the framework-owned system appendix to the persona prompt.
 # Teaches an LLM how cross-chat memory works without requiring persona authors to include it.
 _SYSTEM_APPENDIX = (
-    "You have access to past messages across chats and a search tool - use them to inform your responses, but never quote or volunteer content from other chats unprompted, especially in group settings.\n"
-    "Always invoke the search tool before concluding a message does not exist.\n"
-    "Messages marked private are never shared between chats.\n"
-    "Never reveal or repeat Telegram user IDs, chat IDs, or any other internal numeric identifiers in your responses.\n"
-    "When your context includes a '[Replying to Name, ...]' prefix indicating you were triggered via a reply, acknowledge the original author by name in your response.\n"
-    "Current date and time: (not yet known)\n"
+    "## System\n"
+    "- You have access to past messages across chats and a search tool - use them to inform your responses, but never quote or volunteer content from other chats unprompted, especially in group settings.\n"
+    "- Always invoke the search tool before concluding a message does not exist.\n"
+    "- Messages marked private are never shared between chats.\n"
+    "- Never reveal or repeat Telegram user IDs, chat IDs, or any other internal numeric identifiers in your responses.\n"
+    "- When your context includes a '[Replying to Name, ...]' prefix indicating you were triggered via a reply, acknowledge the original author by name in your response.\n"
+    "- Current date and time: (not yet known)\n"
 )
 
 
@@ -165,24 +167,24 @@ def init_logging():
     logging.getLogger('httpcore').setLevel(logging.WARNING)
 
 
-def bind_log_identity(username: str, log_name: Optional[str] = None):
+def bind_log_identity(username: str, instance_name: Optional[str] = None):
     """
     Bind the bot's identity to the logging system.
 
-    Updates the console handler formatter to prefix every line with [log_name] and opens
-    the per-instance log file named {log_name}_{timestamp}.log.
+    Updates the console handler formatter to prefix every line with [instance_name] and opens
+    the per-instance log file named {instance_name}_{timestamp}.log.
 
     Must be called after the bot's Telegram username is resolved by _tele_info().
 
     Args:
         username: The bot's Telegram username (without @); used as the identity label when
-                  log_name is not set.
-        log_name: Optional override from config.yaml. When set, used for both the console
-                  prefix and log file name instead of the Telegram username -- useful for
-                  multi-platform deployments where the same bot runs on Telegram and Discord.
+                  instance_name is not set.
+        instance_name: Optional override from bot config. When set, used for both the console
+                       prefix and log file name instead of the Telegram username -- useful for
+                       multi-platform deployments where the same bot runs on Telegram and Discord.
     """
-    raw_label = log_name or username
-    # Sanitize: strip path separators so a misconfigured log_name cannot escape TELLMGRAMBOT_LOGS_PATH
+    raw_label = instance_name or username
+    # Sanitize: strip path separators so a misconfigured instance_name cannot escape TELLMGRAMBOT_LOGS_PATH
     label = os.path.basename(raw_label).strip()
     if not label:
         label = username
@@ -244,7 +246,7 @@ def _requires_provider(config: dict) -> dict:
     all other non-empty models require OpenAI.
 
     Args:
-        config: Parsed bot configuration dict (from init_bot_config or read_yaml on config.yaml).
+        config: Parsed bot configuration dict (from init_bot_config or read_yaml on bot config).
 
     Returns:
         Dict with keys 'openai' and 'anthropic', each a bool indicating if that provider key is needed.
@@ -266,66 +268,76 @@ def _model_provider(model: str) -> str | None:
     return 'anthropic' if model.startswith('claude-') else 'openai'
 
 
-def init_keys(config: Optional[dict] = None) -> ApiKeyStatus:
+def _load_telegram_key(config: dict):
     """
-    Load API keys and return an ApiKeyStatus indicating which features are available.
+    Load and validate the Telegram API key into TELLMGRAMBOT_TELEGRAM_API_KEY.
+    Lookup order: (1) TELLMGRAMBOT_TELEGRAM_API_KEY env var, (2) bot config
+    telegram_api_key. Exits on placeholder, missing, or malformed key.
 
-    Telegram key is always required - bot exits if missing or invalid.
-    All other keys (OpenAI, Anthropic, VirusTotal) are optional: missing keys
-    disable the associated features rather than exiting.
+    Args:
+        config: Parsed bot configuration dict from init_bot_config().
+    """
+    env_var = 'TELLMGRAMBOT_TELEGRAM_API_KEY'
+    if not os.environ.get(env_var):
+        config_val = (config.get('telegram_api_key') or '').strip()
+        is_placeholder = config_val.startswith('<') and config_val.endswith('>')
+        if config_val and not is_placeholder:
+            os.environ[env_var] = config_val
+        elif is_placeholder:
+            sys.exit("telegram_api_key in bot config is still a placeholder. Replace it with your Telegram bot API key. Exiting...")
+        else:
+            sys.exit(
+                "Telegram API key is required. Set telegram_api_key in bot config "
+                "or TELLMGRAMBOT_TELEGRAM_API_KEY env var. Exiting..."
+            )
+    if not _TELEGRAM_KEY_RE.match(os.environ.get(env_var, '')):
+        sys.exit(
+            "Telegram API key is not in valid format '<digits>:<letters/digits/_/->' "
+            "(e.g. 123456789:ABCdef...) - exiting..."
+        )
 
-    Provider keys (OpenAI/Anthropic) are loaded conditionally based on configured
-    models. Key files are read from TELLMGRAMBOT_KEYS_PATH or the base execution path.
-    Placeholder files are created for any missing keys. Prints API key status summary
-    before returning.
+
+def init_keys(config: dict) -> ApiKeyStatus:
+    """
+    Load API keys and return an ApiKeyStatus indicating which features are available.
+
+    Telegram key is loaded and validated first via _load_telegram_key(). All other
+    keys (OpenAI, Anthropic, VirusTotal) are optional: missing keys disable the
+    associated features rather than exiting. These keys are loaded from env var or
+    key file (TELLMGRAMBOT_KEYS_PATH or base execution path). Placeholder files are
+    created for any missing keys.
 
     Args:
-        config: Optional parsed bot configuration dict. If None, reads from
-                TELLMGRAMBOT_CONFIGS_PATH/config.yaml (or execution_dir/config.yaml).
+        config: Parsed bot configuration dict from init_bot_config().
 
     Returns:
         ApiKeyStatus with chat_enabled and url_analysis_enabled flags set based on which keys are available.
     """
-    # If no config provided, fall back to reading the default config file.
-    # Failures here are non-fatal: config = {} means no models configured.
-    if config is None:
-        try:
-            config_path = os.path.join(os.environ.get('TELLMGRAMBOT_CONFIGS_PATH', execution_dir()), 'config.yaml')
-            config = read_yaml(config_path) or {}
-        except Exception:
-            config = {}
+    _load_telegram_key(config)
 
     # Determine which provider keys are needed and which feature each model uses.
     provider_needs = _requires_provider(config)
     chat_provider = _model_provider(config.get('chat_model', ''))
     url_provider = _model_provider(config.get('url_model', ''))
 
-    # Build the full set of keys to check: only the required provider key(s) + always-required keys.
+    # Only load the required provider key(s) + VirusTotal.
     provider_keys = {
         'openai': 'https://platform.openai.com/api-keys',
         'anthropic': 'https://docs.anthropic.com/en/api/getting-started',
     }
-    always_keys = {
-        'telegram': 'https://core.telegram.org/api',
-        'virustotal': 'https://developers.virustotal.com/reference/overview'
-    }
-    keys = {k: v for k, v in provider_keys.items() if provider_needs.get(k)} | always_keys
+    optional_keys = {k: v for k, v in provider_keys.items() if provider_needs.get(k)}
+    optional_keys['virustotal'] = 'https://developers.virustotal.com/reference/overview'
 
-    available = set()  # tracks which keys loaded successfully
-    for key, url in keys.items():
+    available = set(['telegram'])  # telegram already validated above
+    for key, url in optional_keys.items():
         env_var = f"TELLMGRAMBOT_{key.upper()}_API_KEY"
 
-        # If the key isn't already in the environment, try loading it from a key file.
         if not os.environ.get(env_var):
             path = os.path.join(os.environ.get('TELLMGRAMBOT_KEYS_PATH', execution_dir()), f"{key}.key")
             if not os.path.exists(path):
-                # Key file missing: create a placeholder and warn (or exit for Telegram).
                 generate_file_path(os.path.dirname(path), os.path.basename(path), "API key",
                     f"YOUR {key.upper()} API KEY HERE - {url}\n"
                 )
-                if key == 'telegram':
-                    sys.exit("Telegram API key is required to run TeLLMgramBot! Exiting...")
-                # Build a human-readable list of which features this key covers.
                 which = [f"chat_model ({config.get('chat_model', '?')})" if chat_provider == key else None,
                          f"url_model ({config.get('url_model', '?')})" if url_provider == key else None,
                          "VirusTotal integration" if key == 'virustotal' else None]
@@ -333,14 +345,10 @@ def init_keys(config: Optional[dict] = None) -> ApiKeyStatus:
                 logger.warning(f"{key}.key not found - {reason} will be disabled.")
                 continue
             else:
-                # Key file exists: load it into the environment for this process.
                 os.environ[env_var] = read_text(path)
                 logger.info(f"Loaded {env_var} secret from: {path}")
 
-        # Reject blank or whitespace-only values (common copy-paste mistake).
         if not os.environ.get(env_var) or any(c.isspace() for c in os.environ.get(env_var)):
-            if key == 'telegram':
-                sys.exit("Telegram API key is blank or invalid! Exiting...")
             which = [f"chat_model ({config.get('chat_model', '?')})" if chat_provider == key else None,
                      f"url_model ({config.get('url_model', '?')})" if url_provider == key else None,
                      "VirusTotal integration" if key == 'virustotal' else None]
@@ -374,26 +382,9 @@ def init_keys(config: Optional[dict] = None) -> ApiKeyStatus:
             reasons.append("missing VirusTotal API key")
         key_status.disabled_reasons['url_analysis'] = ", ".join(reasons)
 
-    print_api_key_status(key_status)
     return key_status
 
 
-def print_api_key_status(key_status: ApiKeyStatus):
-    """Print a startup summary of which API keys are available and which features they enable."""
-    print("--- TeLLMgramBot API Key Status ---")
-    features = [
-        ('chat', 'Chat (LLM)', key_status.chat_enabled),
-        ('url_analysis', 'URL Analysis', key_status.url_analysis_enabled),
-    ]
-    for key, label, enabled in features:
-        if enabled:
-            print(f"  {label:<12} : ENABLED")
-        else:
-            reason = key_status.disabled_reasons.get(key, 'unavailable')
-            print(f"  {label:<12} : DISABLED ({reason})")
-    print("-----------------------------------")
-
-
 def init_bot_config(file: str = 'config.yaml') -> dict:
     """
     Returns contents of a bot configuration file (default 'config.yaml' if created).
@@ -412,9 +403,9 @@ def init_bot_config(file: str = 'config.yaml') -> dict:
     env_var = "TELLMGRAMBOT_CONFIGS_PATH"
     try:
         text = ''.join(
-            '%s : %s\n' % (
-                parameter.ljust(12),
-                value if value else INIT_BOT_CONFIG_COMMENTS.get(parameter, '# Optional')
+            '%s: %s\n' % (
+                parameter,
+                (f"'{value}'" if isinstance(value, str) else value) if value is not None else INIT_BOT_CONFIG_COMMENTS.get(parameter, '# Optional')
             )
             for parameter, value in INIT_BOT_CONFIG.items()
             if parameter != 'persona_prompt'
@@ -497,33 +488,6 @@ def init_bot_prompt(file: str = 'test_personality.prmpt') -> str:
         sys.exit(f"{type(e).__name__} on {env_var} file '{file}': {e}\nExiting...")
 
 
-def init_url_prompt(file: str = 'url_analysis.prmpt') -> str:
-    """
-    Ensure prompt file is created that defines how the bot will analyze URLs via square brackets [].
-    Must specify the environment variable 'TELLMGRAMBOT_PROMPTS_PATH'.
-    """
-    env_var = "TELLMGRAMBOT_PROMPTS_PATH"
-    try:
-        return read_text(
-            generate_file_path(os.environ[env_var], file, "URL analysis prompt",
-                "The user has provided a URL to perform some level of analysis. You will infer "
-                "the nature of the analysis from the user's query.\n\n"
-                "The contents of the URL mentioned have already been harvested and cleansed. "
-                "Note the URL contents will likely have sections of text that are less relevant "
-                "to the user's question (headers, footers, menus, ads, etc.). You will need to "
-                "ignore those sections of text and focus on the main content of the page.\n\n"
-                "The contents of the URL are shown below:\n"
-                "BEGIN URL CONTENTS\n"
-                "{url_content}\n"
-                "END URL CONTENTS\n"
-            )
-        )
-    except KeyError:
-        sys.exit(f"{env_var} must be defined to create file '{file}'! Exiting...")
-    except Exception as e:
-        sys.exit(f"{type(e).__name__} on {env_var} file '{file}': {e}\nExiting...")
-
-
 def init_structure(
     config_file: str = 'config.yaml',
     prompt_file: str = 'test_personality.prmpt',
@@ -532,15 +496,15 @@ def init_structure(
     Performs the whole TeLLMgramBot first-run setup including:
     - Directories for configurations, prompts, and conversation/error logs.
     - Logging configuration (console handler; file handler bound later by bind_log_identity()).
-    - Database naming and schema initialization from config (conversations.db or custom db_name).
-    - Provider-conditional API keys (OpenAI/Anthropic determined by config.yaml model prefixes).
-    - Configuration files (config.yaml, models.yaml) with inline parameter descriptions.
-    - System prompt files (test_personality.prmpt, url_analysis.prmpt).
+    - Database naming and schema initialization from config (conversations.db or custom instance_name).
+    - Provider-conditional API keys (OpenAI/Anthropic determined by bot config model prefixes).
+    - Configuration files (bot config, models.yaml) with inline parameter descriptions.
+    - System prompt file (test_personality.prmpt).
 
-    Provider key requirements are inferred from config.yaml model prefixes (claude-* -> Anthropic,
+    Provider key requirements are inferred from bot config model prefixes (claude-* -> Anthropic,
     gpt-* -> OpenAI, etc.) to streamline setup for single-provider deployments.
 
-    Database naming: After init_bot_config() runs, if db_name is configured in config.yaml,
+    Database naming: After init_bot_config() runs, if instance_name is configured in bot config,
     calls set_db_filename() and performs a one-time rename migration of conversations.db to
     the custom filename (only if the target does not yet exist). This ordering ensures the DB
     filename is settled before schema init.
@@ -563,19 +527,19 @@ def init_structure(
     init_models_config()
 
     # Configure DB filename and run schema init now that config is available.
-    # Must happen after init_bot_config() so db_name is known before init_db() runs.
-    db_name = config.get('db_name')
-    if db_name:
+    # Must happen after init_bot_config() so instance_name is known before init_db() runs.
+    instance_name = config.get('instance_name')
+    if instance_name:
         # Sanitize to a plain filename - reject path separators and absolute paths so a
-        # misconfigured db_name cannot escape TELLMGRAMBOT_DATA_PATH.
-        db_name_safe = os.path.basename(db_name).strip()
-        if db_name_safe != db_name.strip() or not db_name_safe:
+        # misconfigured instance_name cannot escape TELLMGRAMBOT_DATA_PATH.
+        instance_name_safe = os.path.basename(instance_name).strip()
+        if instance_name_safe != instance_name.strip() or not instance_name_safe:
             logger.warning(
-                f"db_name '{db_name}' contains path components; ignoring and using conversations.db"
+                f"instance_name '{instance_name}' contains path components; ignoring and using conversations.db"
             )
-            db_name = None
+            instance_name = None
         else:
-            set_db_filename(db_name_safe)
+            set_db_filename(instance_name_safe)
         # One-time migration: rename conversations.db to the new name if the target
         # doesn't exist yet. Assumes a single-bot deployment owns conversations.db.
         data_dir = os.environ.get('TELLMGRAMBOT_DATA_PATH', os.path.join(execution_dir(), 'data'))
@@ -608,7 +572,6 @@ def init_structure(
         prompt = INIT_BOT_CONFIG.get('persona_prompt', '')
         logger.warning(f"File '{prompt_file}' is empty, using default persona prompt.")
     prompt = prompt.rstrip() + "\n\n" + _SYSTEM_APPENDIX
-    init_url_prompt()
 
     # Load API keys before running archival so the provider can authenticate.
     key_status = init_keys(config)

{tellmgrambot-3.13.2 → tellmgrambot-3.13.4}/TeLLMgramBot/message_handlers.py

@@ -3,7 +3,6 @@ import re
 from typing import Optional
 import validators
 
-from .initialize import init_url_prompt
 from .utils import log_error
 from .models import TokenLimits
 from .web_utils import (
@@ -15,6 +14,20 @@ from .web_utils import (
 )
 from .providers.factory import get_provider
 
+_URL_ANALYSIS_TEMPLATE = (
+    "## URL Analysis\n"
+    "The user has provided a URL to perform some level of analysis. You will infer "
+    "the nature of the analysis from the user's query.\n\n"
+    "The contents of the URL mentioned have already been harvested and cleansed. "
+    "Note the URL contents will likely have sections of text that are less relevant "
+    "to the user's question (headers, footers, menus, ads, etc.). You will need to "
+    "ignore those sections of text and focus on the main content of the page.\n\n"
+    "The contents of the URL are shown below:\n"
+    "BEGIN URL CONTENTS\n"
+    "{url_content}\n"
+    "END URL CONTENTS\n"
+)
+
 
 def handle_greetings(text: str) -> Optional[str]:
     """
@@ -44,18 +57,19 @@ def handle_common_queries(text: str) -> Optional[str]:
     return None
 
 
-async def handle_url_ask(text: str, model: str = 'gpt-4o') -> Optional[str]:
+async def handle_url_ask(text: str, model: str = 'gpt-4o', prompt: str = '') -> Optional[str]:
     """
     Process URL content in an LLM to provide a summary.
 
     Extracts URLs wrapped in square brackets [], validates them, checks for
     safety via VirusTotal, fetches content, and summarizes via an LLM specified
-    by model name. Errors are logged via the logging system categorized by model
-    and error type.
+    by model name. The bot's persona prompt is prepended to the URL analysis
+    system message so responses match the bot's personality.
 
     Args:
         text: The message text potentially containing a URL in [square brackets].
         model: The LLM model to use for URL summarization (default: 'gpt-4o').
+        prompt: Bot persona prompt prepended to the URL analysis system message.
 
     Returns:
         A summary string if a URL was found and processed successfully, an error
@@ -104,9 +118,9 @@ async def handle_url_ask(text: str, model: str = 'gpt-4o') -> Optional[str]:
                 # Show the last 50 characters of the pruned URL content
                 pruned_tail = messages[0]["content"][-50:]
 
-            # Load system prompt template to insert URL content
-            template = init_url_prompt('url_analysis.prmpt')
-            messages[0]["content"] = template.format(url_content=messages[0]["content"])
+            # Build system message: bot persona (if any) + URL analysis template with content
+            url_system = _URL_ANALYSIS_TEMPLATE.replace('{url_content}', messages[0]["content"])
+            messages[0]["content"] = f"{prompt}\n\n{url_system}" if prompt else url_system
 
             # Call the LLM for the response that summarizes URL content
             try:

{tellmgrambot-3.13.2 → tellmgrambot-3.13.4}/TeLLMgramBot/tools.py

@@ -1,7 +1,7 @@
 """
 Webhook and MCP tool registry and executors for TeLLMgramBot.
 
-Provides build_tool_registry() for startup parsing of config.yaml 'tools:' webhook
+Provides build_tool_registry() for startup parsing of bot config 'tools:' webhook
 entries, discover_mcp_tools() for async MCP server discovery, execute_webhook() for
 dispatching webhook tool calls, and execute_mcp() for MCP tool calls at runtime.
 """
@@ -96,7 +96,7 @@ def build_tool_registry(
     are skipped with warnings. Duplicate tool names are deduplicated (first wins).
 
     Args:
-        tools_config: List of raw tool definition dicts from config.yaml 'tools:' key.
+        tools_config: List of raw tool definition dicts from bot config 'tools:' key.
                       Pass an empty list or None to produce an empty registry.
         allow_local: If True, the executor permits webhook URLs targeting loopback or
                      link-local addresses. Mirrors the 'allow_local_webhooks' config key.
@@ -387,7 +387,7 @@ async def execute_mcp(tool_def: dict, arguments: dict) -> str:
         logger.warning(f"MCP '{name}': SSRF block - '{parsed.hostname}' is loopback or link-local")
         return (
             f"[Tool error: '{name}' targets a loopback or link-local address. "
-            f"Set allow_local_webhooks: true in config.yaml to permit local addresses.]"
+            f"Set allow_local_webhooks: true in bot config to permit local addresses.]"
         )
 
     call_url = f"{server_url}/tools/call"
@@ -489,7 +489,7 @@ async def execute_webhook(tool_def: dict, arguments: dict) -> str:
         logger.warning(f"Webhook '{name}': SSRF block - '{hostname}' is loopback or link-local")
         return (
             f"[Tool error: '{name}' targets a loopback or link-local address. "
-            f"Set allow_local_webhooks: true in config.yaml to permit local addresses.]"
+            f"Set allow_local_webhooks: true in bot config to permit local addresses.]"
         )
 
     host_part = f"{parsed.hostname}:{parsed.port}" if parsed.port else parsed.hostname

{tellmgrambot-3.13.2 → tellmgrambot-3.13.4}/TeLLMgramBot.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.13.2
+Version: 3.13.4
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -75,18 +75,17 @@ Simply set `chat_model` (and optionally `url_model`) in your `config.yaml` to an
 ## Directories
 TeLLMgramBot creates the following directories:
 
-- **`configs`** - Bot configuration and model parameters
-  - `config.yaml` - Bot settings: owner, model names, token limits, search limits, nickname/initials, database name
+- **`configs`** - Bot configuration and model parameters (path configurable via `TELLMGRAMBOT_CONFIGS_PATH`)
+  - `config.yaml` - Default bot configuration file (filename used throughout this README); can be changed by passing `config_file` to `TelegramBot.set()`
   - `models.yaml` - Token limits for each LLM model (pre-populated on first run)
-- **`prompts`** - Bot personas and URL analysis templates
-  - `test_personality.prmpt` - Sample bot personality (multi-provider, can be renamed)
-  - `url_analysis.prmpt` - URL summarization prompt template
+- **`prompts`** - Bot personas (path configurable via `TELLMGRAMBOT_PROMPTS_PATH`)
+  - `test_personality.prmpt` - Default bot persona file (filename used throughout this README); can be changed by passing `prompt_file` to `TelegramBot.set()`
   - A system appendix is automatically appended to every persona at runtime, teaching the LLM about cross-chat memory and search behavior. 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 Telegram username or `log_name` config, e.g. `my_bot_2026-03-29_10-30-45.log`)
-  - Logs include anonymized Telegram IDs for privacy. Console shows INFO-level TeLLMgramBot messages only, prefixed with an `[identity label]` (the bot's Telegram username by default, or `log_name` when configured).
+- **`logs`** - Bot instance logs (one per startup, named after the bot's Telegram username or `instance_name` config, e.g. `my_bot_2026-03-29_10-30-45.log`)
+  - Logs include anonymized Telegram IDs for privacy. Console shows INFO-level TeLLMgramBot messages only, prefixed with an `[identity label]` (the bot's Telegram username by default, or `instance_name` when configured).
   - 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 `db_name` config) storing all messages, users, and chats
+- **`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
@@ -102,13 +101,13 @@ Override default directory locations by setting these environment variables (use
 If unset, all paths default to subdirectories of the execution directory (the directory containing your entry-point script).
 
 ## API Keys
-TeLLMgramBot supports four API keys, each loadable from environment variables or `.key` files:
+TeLLMgramBot supports four API keys. OpenAI, Anthropic, and VirusTotal keys load from environment variables or `.key` files. The Telegram key loads from its env var or the bot config field `telegram_api_key` (no `.key` file):
 
-| Key | Env Var | File | When required |
-|-----|---------|------|---------------|
+| Key | Env Var | File/Config | When required |
+|-----|---------|-------------|---------------|
 | [OpenAI](https://platform.openai.com/api-keys) | `TELLMGRAMBOT_OPENAI_API_KEY` | `openai.key` | For `gpt-*` models |
 | [Anthropic](https://console.anthropic.com/settings/keys) | `TELLMGRAMBOT_ANTHROPIC_API_KEY` | `anthropic.key` | For `claude-*` models |
-| [Telegram](https://t.me/BotFather) | `TELLMGRAMBOT_TELEGRAM_API_KEY` | `telegram.key` | Always required |
+| [Telegram](https://t.me/BotFather) | `TELLMGRAMBOT_TELEGRAM_API_KEY` | bot config `telegram_api_key` in `config.yaml` | Always required |
 | [VirusTotal](https://www.virustotal.com/gui/my-apikey) | `TELLMGRAMBOT_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 VirusTotal disables URL analysis. Telegram key is required - the bot will not start without it.
@@ -151,9 +150,9 @@ When the bot is triggered in a group and about to respond (not deferring to anot
    - `bot_owner`: Telegram username(s) with admin access (required, no `@`). Accepts a single string or a YAML list of usernames.
    - `chat_model`: LLM model for conversation (e.g. `gpt-4o-mini` or `claude-sonnet-4-6`)
    - `url_model`: LLM model for URL analysis (e.g. `gpt-4o` or `claude-haiku-4-5`)
+   - `telegram_api_key`: Telegram bot API key (required). Lookup order: (1) `TELLMGRAMBOT_TELEGRAM_API_KEY` env var, (2) `telegram_api_key` in `config.yaml`. Exits on placeholder, missing, or malformed key.
    - `bot_nickname` / `bot_initials`: Names the bot responds to in groups
-   - `db_name`: Optional custom database filename without extension (e.g. `MyBot` creates `MyBot.db`); omit for default `conversations.db`. Use distinct names when running multiple bot instances in the same directory.
-   - `log_name`: Optional label used for the console prefix and log filename (e.g. `MyBot` produces `[MyBot] INFO: ...` on the console and `MyBot_{timestamp}.log`); omit to use the bot's Telegram username. Useful for multi-platform deployments sharing the same config.
+   - `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 bot's Telegram username for logging and `conversations.db` for database. Use distinct names when running multiple bot instances in the same directory.
    - `token_limit`: Max tokens (optional; defaults to model's maximum)
    - `search_limit`: Max search results (optional; defaults to 30)
    - `archive_days`: Days before messages are eligible for archival (optional; default 60, minimum 1). Older messages are distilled into daily summaries, then progressively compressed into monthly digests. Once archived their respective raw messages do not return to the LLM context any more, only when searching messages.

{tellmgrambot-3.13.2 → tellmgrambot-3.13.4}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r") as fh:
 
 setup(
     name='TeLLMgramBot',
-    version='3.13.2',
+    version='3.13.4',
     packages=find_packages(),
     license='MIT',
     author='Digital Heresy',