TeLLMgramBot 3.13.1__tar.gz → 3.13.3__tar.gz

{tellmgrambot-3.13.1 → tellmgrambot-3.13.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.13.1
+Version: 3.13.3
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -82,11 +82,11 @@ TeLLMgramBot creates the following directories:
   - `test_personality.prmpt` - Sample bot personality (multi-provider, can be renamed)
   - `url_analysis.prmpt` - URL summarization prompt template
   - 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 +102,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 `telegram_api_key` in `config.yaml` or its env var (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` | `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,12 +151,13 @@ 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: TELLMGRAMBOT_TELEGRAM_API_KEY env var -> config field.
    - `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.
+   - `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.
    - `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.
 4. **Disable group privacy mode in BotFather:**
    ```

{tellmgrambot-3.13.1 → tellmgrambot-3.13.3}/README.md

@@ -50,11 +50,11 @@ TeLLMgramBot creates the following directories:
   - `test_personality.prmpt` - Sample bot personality (multi-provider, can be renamed)
   - `url_analysis.prmpt` - URL summarization prompt template
   - 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 +70,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 `telegram_api_key` in `config.yaml` or its env var (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` | `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,12 +119,13 @@ 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: TELLMGRAMBOT_TELEGRAM_API_KEY env var -> config field.
    - `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.
+   - `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.
    - `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.
 4. **Disable group privacy mode in BotFather:**
    ```

{tellmgrambot-3.13.1 → tellmgrambot-3.13.3}/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:
@@ -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,18 +1104,15 @@ 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.
-        allow_local = config.get('allow_local_webhooks', False)
-        webhook_schemas, webhook_defs = build_tool_registry(
-            config.get('tools') or [],
-            allow_local=allow_local,
-        )
+        # 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)
 
         # Discover MCP tools from any 'mcp_server:' entries in the tools config.
         mcp_entries = [
@@ -1148,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.1 → tellmgrambot-3.13.3}/TeLLMgramBot/initialize.py

@@ -96,28 +96,31 @@ 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,
     'archive_days': None,
+    'allow_local_webhooks': None,
     'persona_prompt': 'You are a generic test bot powered by a user-configured LLM.'
 }
 
 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)',
     'archive_days': '# Optional, days before messages are eligible for Tier 1 archival (default: 60, min: 1). Tier 2 triggers at 2x this value.',
+    'allow_local_webhooks': '# Optional, set to true to permit webhook/MCP URLs targeting loopback or link-local addresses (default: false)',
 }
 
 # Append the framework-owned system appendix to the persona prompt.
@@ -163,24 +166,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
@@ -242,7 +245,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.
@@ -264,66 +267,77 @@ 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.
 
-    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.
+    Lookup order: TELLMGRAMBOT_TELEGRAM_API_KEY env var -> bot config `telegram_api_key`.
+    No .key file support. Exits on placeholder, missing, or malformed key.
 
-    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.
+    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..."
+        )
+
+
+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]
@@ -331,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]
@@ -372,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).
@@ -410,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'
@@ -530,15 +523,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.
+    - 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 files (test_personality.prmpt, url_analysis.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.
@@ -561,19 +554,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'))

{tellmgrambot-3.13.1 → tellmgrambot-3.13.3}/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.1 → tellmgrambot-3.13.3}/TeLLMgramBot.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.13.1
+Version: 3.13.3
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -82,11 +82,11 @@ TeLLMgramBot creates the following directories:
   - `test_personality.prmpt` - Sample bot personality (multi-provider, can be renamed)
   - `url_analysis.prmpt` - URL summarization prompt template
   - 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 +102,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 `telegram_api_key` in `config.yaml` or its env var (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` | `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,12 +151,13 @@ 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: TELLMGRAMBOT_TELEGRAM_API_KEY env var -> config field.
    - `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.
+   - `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.
    - `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.
 4. **Disable group privacy mode in BotFather:**
    ```

{tellmgrambot-3.13.1 → tellmgrambot-3.13.3}/setup.py

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