TeLLMgramBot 3.13.3__tar.gz → 3.13.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.13.3
+Version: 3.13.4
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -75,12 +75,11 @@ 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 `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).
@@ -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. 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):
+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/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_api_key` in config.yaml | 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,7 +150,7 @@ 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.
+   - `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
    - `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)

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

@@ -43,12 +43,11 @@ 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 `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).
@@ -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. 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):
+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/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_api_key` in config.yaml | 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,7 +118,7 @@ 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.
+   - `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
    - `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)

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

@@ -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)

{tellmgrambot-3.13.3 → 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.3 → tellmgrambot-3.13.4}/TeLLMgramBot/initialize.py

@@ -126,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"
 )
 
 
@@ -270,9 +271,8 @@ def _model_provider(model: str) -> str | None:
 def _load_telegram_key(config: dict):
     """
     Load and validate the Telegram API key into TELLMGRAMBOT_TELEGRAM_API_KEY.
-
-    Lookup order: TELLMGRAMBOT_TELEGRAM_API_KEY env var -> bot config `telegram_api_key`.
-    No .key file support. Exits on placeholder, missing, or malformed key.
+    Lookup order: (1) TELLMGRAMBOT_TELEGRAM_API_KEY env var, (2) bot config
+    telegram_api_key. Exits on placeholder, missing, or malformed key.
 
     Args:
         config: Parsed bot configuration dict from init_bot_config().
@@ -488,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',
@@ -526,7 +499,7 @@ def init_structure(
     - 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).
+    - System prompt file (test_personality.prmpt).
 
     Provider key requirements are inferred from bot config model prefixes (claude-* -> Anthropic,
     gpt-* -> OpenAI, etc.) to streamline setup for single-provider deployments.
@@ -599,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.3 → 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.3 → tellmgrambot-3.13.4}/TeLLMgramBot.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: TeLLMgramBot
-Version: 3.13.3
+Version: 3.13.4
 Summary: LLM-powered Telegram bot (OpenAI + Anthropic)
 Home-page: https://github.com/Digital-Heresy/TeLLMgramBot
 Author: Digital Heresy
@@ -75,12 +75,11 @@ 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 `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).
@@ -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. 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):
+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/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_api_key` in config.yaml | 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,7 +150,7 @@ 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.
+   - `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
    - `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)

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

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