TeLLMgramBot 3.13.0__tar.gz → 3.13.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.13.0
+Version: 3.13.2
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -82,9 +82,9 @@ 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, e.g. `tellmgrambot_2026-03-29_10-30-45.log`)
-  - Logs include anonymized Telegram IDs for privacy. Console shows INFO-level TeLLMgramBot messages only.
-  - Bot keeps the 10 most recent logs, automatically pruning older ones.
+- **`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).
+  - 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
   - Users manage their data via `/forget` and `/private` commands.
@@ -153,9 +153,11 @@ When the bot is triggered in a group and about to respond (not deferring to anot
    - `url_model`: LLM model for URL analysis (e.g. `gpt-4o` or `claude-haiku-4-5`)
    - `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.
    - `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.0 → tellmgrambot-3.13.2}/README.md

@@ -50,9 +50,9 @@ 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, e.g. `tellmgrambot_2026-03-29_10-30-45.log`)
-  - Logs include anonymized Telegram IDs for privacy. Console shows INFO-level TeLLMgramBot messages only.
-  - Bot keeps the 10 most recent logs, automatically pruning older ones.
+- **`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).
+  - 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
   - Users manage their data via `/forget` and `/private` commands.
@@ -121,9 +121,11 @@ When the bot is triggered in a group and about to respond (not deferring to anot
    - `url_model`: LLM model for URL analysis (e.g. `gpt-4o` or `claude-haiku-4-5`)
    - `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.
    - `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.0 → tellmgrambot-3.13.2}/TeLLMgramBot/TeLLMgramBot.py

@@ -36,6 +36,7 @@ from .archive import run_archival
 from .initialize import (
     INIT_BOT_CONFIG,
     ApiKeyStatus,
+    bind_log_identity,
     init_logging,
     init_structure,
 )
@@ -102,6 +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)
         except Exception as e:
             # Fail fast if the bot's identity cannot be fetched to avoid
             # continuing with an uninitialized self.telegram['username'].
@@ -962,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 = 'tellmgrambot',
+        log_name: str | None = None,
         webhook_schemas: list | None = None,
         webhook_defs: dict | None = None,
     ):
@@ -981,6 +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.
             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.
@@ -997,10 +1001,11 @@ class TelegramBot:
         """
         # Starting to initialize, not online yet
         self._online = False
+        self._log_name = log_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(log_name=log_name)[0]
-        init_logging(log_name)
+        self.key_status = key_status if key_status is not None else init_structure()[0]
+        init_logging()
 
         # Initialize some variables
         self.token_warning = {}  # Determines whether user has reached token limit by AI model
@@ -1077,7 +1082,7 @@ class TelegramBot:
         # Bot is now ready and active by default
         self._online = True
 
-    def set(config_file: str = 'config.yaml', prompt_file: str = 'test_personality.prmpt', log_name: str = 'tellmgrambot'):
+    def set(config_file: str = 'config.yaml', prompt_file: str = 'test_personality.prmpt'):
         """
         Instantiate a TelegramBot from configuration and prompt files.
 
@@ -1092,8 +1097,6 @@ class TelegramBot:
                          Resolved relative to TELLMGRAMBOT_CONFIGS_PATH env var, not as a literal path.
             prompt_file: Filename of the bot persona prompt (default: 'test_personality.prmpt').
                          Resolved relative to TELLMGRAMBOT_PROMPTS_PATH env var, not as a literal path.
-            log_name: Base name for the log file (default: 'tellmgrambot').
-                      Produces e.g. 'mybot_2026-03-29_10-30-45.log' when set to 'mybot'.
 
         Returns:
             A fully initialized TelegramBot instance.
@@ -1102,16 +1105,14 @@ class TelegramBot:
             - 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.
         """
         # Bootstrap directories, logging, config, prompt (with appendix), and API keys in one call.
-        key_status, config, prompt = init_structure(config_file, prompt_file, log_name)
+        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,
-        )
+        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 = [
@@ -1144,7 +1145,7 @@ class TelegramBot:
             archive_days    = config['archive_days'],
             persona_prompt  = prompt,
             key_status      = key_status,
-            log_name        = log_name,
+            log_name        = config['log_name'],
             webhook_schemas = webhook_schemas,
             webhook_defs    = webhook_defs,
         )

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

@@ -103,19 +103,23 @@ INIT_BOT_CONFIG = {
     'chat_model': 'gpt-5-mini',
     'url_model': 'gpt-5',
     'db_name': None,
+    'log_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',
     '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.
@@ -130,27 +134,21 @@ _SYSTEM_APPENDIX = (
 )
 
 
-def init_logging(log_name: str = 'tellmgrambot'):
+def init_logging():
     """
-    Configure the Python logging system for TeLLMgramBot.
+    Configure the Python logging system for TeLLMgramBot (console handler only).
 
-    Sets up a console handler (INFO, TeLLMgramBot-only, real IDs) and a per-instance file
-    handler (INFO by default, anonymized IDs) in TELLMGRAMBOT_LOGS_PATH. Pass -v or
-    --verbose on the command line to enable DEBUG-level file logging. Prunes old bot
-    instance log files on startup, keeping the 10 most recent.
+    Sets up a console handler (INFO, TeLLMgramBot-only, no ID redaction). The file handler
+    and console username prefix are added later by bind_log_identity() once the bot's Telegram
+    username is known.
 
-    Must be called after TELLMGRAMBOT_LOGS_PATH has been resolved by init_directories().
-
-    Args:
-        log_name: Base name for the log file (e.g. 'mybot' -> 'mybot_2026-03-29_10-30-45.log').
-                  Defaults to 'tellmgrambot'.
+    Does not depend on TELLMGRAMBOT_LOGS_PATH or init_directories(). Only
+    bind_log_identity() requires the logs path to have been resolved.
     """
     global _logging_initialized
     if _logging_initialized:
         return
 
-    verbose = '-v' in sys.argv or '--verbose' in sys.argv
-
     root_logger = logging.getLogger()
     root_logger.setLevel(logging.DEBUG)
 
@@ -159,23 +157,57 @@ def init_logging(log_name: str = 'tellmgrambot'):
     console_handler.setFormatter(_ConsoleFormatter('%(levelname)s: %(message)s'))
     console_handler.addFilter(lambda r: r.name.startswith('TeLLMgramBot'))
 
-    logs_dir = os.environ.get('TELLMGRAMBOT_LOGS_PATH') or gettempdir()
-    os.makedirs(logs_dir, exist_ok=True)
-    log_path = os.path.join(logs_dir, generate_filename(log_name))
-    file_handler = logging.FileHandler(log_path, encoding='utf-8')
-    file_handler.setLevel(logging.DEBUG if verbose else logging.INFO)
-    file_handler.setFormatter(_RedactedFileFormatter('%(asctime)s %(levelname)s %(name)s: %(message)s'))
-
     root_logger.addHandler(console_handler)
-    root_logger.addHandler(file_handler)
     _logging_initialized = True
 
     # Suppress noisy third-party INFO logs from appearing in the file
     logging.getLogger('httpx').setLevel(logging.WARNING)
     logging.getLogger('httpcore').setLevel(logging.WARNING)
 
-    # Prune old bot instance log files - keep the 10 most recent (sort by name = sort by timestamp)
-    instance_logs = sorted(glob(os.path.join(logs_dir, f'{log_name}_*.log')))
+
+def bind_log_identity(username: str, log_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.
+
+    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.
+    """
+    raw_label = log_name or username
+    # Sanitize: strip path separators so a misconfigured log_name cannot escape TELLMGRAMBOT_LOGS_PATH
+    label = os.path.basename(raw_label).strip()
+    if not label:
+        label = username
+
+    root_logger = logging.getLogger()
+
+    # Idempotency: skip if a FileHandler is already attached (e.g. multiple TelegramBot instances)
+    if any(isinstance(h, logging.FileHandler) for h in root_logger.handlers):
+        return
+
+    for handler in root_logger.handlers:
+        if isinstance(handler, logging.StreamHandler) and not isinstance(handler, logging.FileHandler):
+            handler.setFormatter(_ConsoleFormatter(f'[{label}] %(levelname)s: %(message)s'))
+
+    verbose = '-v' in sys.argv or '--verbose' in sys.argv
+    logs_dir = os.environ.get('TELLMGRAMBOT_LOGS_PATH') or gettempdir()
+    os.makedirs(logs_dir, exist_ok=True)
+    log_path = os.path.join(logs_dir, generate_filename(label))
+    file_handler = logging.FileHandler(log_path, encoding='utf-8')
+    file_handler.setLevel(logging.DEBUG if verbose else logging.INFO)
+    file_handler.setFormatter(_RedactedFileFormatter('%(asctime)s %(levelname)s %(name)s: %(message)s'))
+    root_logger.addHandler(file_handler)
+
+    # Prune old log files for this bot - keep the 10 most recent
+    instance_logs = sorted(glob(os.path.join(logs_dir, f'{label}_*.log')))
     for old_log in instance_logs[:-10]:
         try:
             os.remove(old_log)
@@ -495,12 +527,11 @@ def init_url_prompt(file: str = 'url_analysis.prmpt') -> str:
 def init_structure(
     config_file: str = 'config.yaml',
     prompt_file: str = 'test_personality.prmpt',
-    log_name: str = 'tellmgrambot',
 ) -> tuple[ApiKeyStatus, dict, str]:
     """
     Performs the whole TeLLMgramBot first-run setup including:
     - Directories for configurations, prompts, and conversation/error logs.
-    - Logging configuration (console + per-instance file handler).
+    - 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.
@@ -519,15 +550,13 @@ def init_structure(
                      Resolved relative to TELLMGRAMBOT_CONFIGS_PATH.
         prompt_file: Name of the bot persona prompt file (default: 'test_personality.prmpt').
                      Resolved relative to TELLMGRAMBOT_PROMPTS_PATH.
-        log_name: Base name for the per-instance log file (default: 'tellmgrambot').
-                  Passed through to init_logging().
 
     Returns:
         Tuple of (ApiKeyStatus, parsed config dict, persona prompt string with framework-owned
                   system appendix automatically appended).
     """
     init_directories()
-    init_logging(log_name)
+    init_logging()
 
     # Configurations for bot and LLM models
     config = init_bot_config(config_file)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.13.0
+Version: 3.13.2
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -82,9 +82,9 @@ 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, e.g. `tellmgrambot_2026-03-29_10-30-45.log`)
-  - Logs include anonymized Telegram IDs for privacy. Console shows INFO-level TeLLMgramBot messages only.
-  - Bot keeps the 10 most recent logs, automatically pruning older ones.
+- **`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).
+  - 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
   - Users manage their data via `/forget` and `/private` commands.
@@ -153,9 +153,11 @@ When the bot is triggered in a group and about to respond (not deferring to anot
    - `url_model`: LLM model for URL analysis (e.g. `gpt-4o` or `claude-haiku-4-5`)
    - `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.
    - `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.0 → tellmgrambot-3.13.2}/setup.py

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