telegroq 0.1.0__tar.gz

telegroq-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 2026-10-30
+
+### Added
+- `telegroq.createBot(token)` returning `TeleGroqBot`, a wrapper around `telebot.TeleBot`.
+- `bot.set_groq_key(api_key, model=...)` and `telegroq.configure_groq(...)`.
+- `telegroq.setCh(system_prompt, max_history)` returning `Character`: per-user memory,
+  `get_response` / `ask` (with a `Reply` status object), async variants, `clear_history`.
+- Friendly fallback messages for Groq rate limits, bad keys, timeouts and outages.
+- `@bot.cmd`, `@bot.on_message`, `@bot.callback` (exact / prefix / regex), `@bot.on_error`,
+  `bot.auto_reply(character)`; handlers receive `(user, msg)` / `(user, call)`.
+- `Message` and `CallbackContext` wrappers (`msg.text` is always a `str`, `call.edit()`,
+  automatic callback answers).
+- Inline keyboard helpers `button()` and `inline_keyboard()`.
+- Pluggable history stores: `MemoryHistoryStore`, `SQLiteHistoryStore`, `HistoryStore` base class.
+- `bot.send_message` / `bot.reply`: automatic splitting of long texts, plain-text retry on
+  formatting errors, `reply_markup` on the last part.
+- Command menu publishing (`@bot.cmd("start", description="...")`), non-text message notice.

telegroq-0.1.0/LICENSE

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

telegroq-0.1.0/PKG-INFO

@@ -0,0 +1,222 @@
+Metadata-Version: 2.5
+Name: telegroq
+Version: 0.1.0
+Summary: Deploy a Groq-powered Telegram bot with a custom persona in a few lines (pyTelegramBotAPI + Groq).
+Keywords: telegram,bot,groq,llm,chatbot,ai,persona,pytelegrambotapi,telebot
+Author: AYM
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+License-File: LICENSE
+Requires-Dist: pyTelegramBotAPI>=4.16
+Requires-Dist: groq>=0.9
+Requires-Dist: pytest>=7.0 ; extra == "dev"
+Requires-Dist: ruff>=0.5 ; extra == "dev"
+Requires-Dist: flit>=3.11 ; extra == "dev"
+Requires-Dist: twine>=6.1 ; extra == "dev"
+Project-URL: Changelog, https://github.com/kkkik/telegroq/blob/main/CHANGELOG.md
+Project-URL: Homepage, https://github.com/kkkik/telegroq
+Project-URL: Issues, https://github.com/kkkik/telegroq/issues
+Project-URL: Source, https://github.com/kkkik/telegroq
+Provides-Extra: dev
+Import-Name: telegroq
+
+# telegroq
+
+**A Groq-powered Telegram bot with its own personality in a few lines of Python.**
+
+`telegroq` bridges [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI) (`telebot`) and the
+[Groq API](https://console.groq.com/docs). You get decorators for commands, messages and inline buttons,
+characters with per-user memory, and sensible behaviour when things go wrong (rate limits, bad keys,
+photos and stickers instead of text) - without writing the glue yourself.
+
+> Unofficial project. Not affiliated with or endorsed by Telegram or Groq.
+
+## Install
+
+```bash
+pip install telegroq
+```
+
+Requires Python 3.10+. You need a Telegram bot token from [@BotFather](https://t.me/BotFather) and a Groq API key from
+[console.groq.com](https://console.groq.com/keys).
+
+## Quickstart
+
+```python
+import telegroq
+
+bot = telegroq.createBot("123456:TELEGRAM_BOT_TOKEN")
+bot.set_groq_key("gsk_...", model="llama-3.3-70b-versatile")
+
+character = telegroq.setCh(
+    system_prompt="You are a funny, witty, and energetic AI assistant.",
+    max_history=10,
+)
+
+@bot.cmd("/start")
+def start(user, msg):
+    bot.send_message(user.id, f"Hello {user.first_name}! I am ready.")
+
+@bot.cmd("/reset")
+def reset(user, msg):
+    character.clear_history(user.id)
+    bot.send_message(user.id, "Conversation memory cleared!")
+
+@bot.on_message()
+def chat(user, msg):
+    bot.reply(user.id, character.get_response(user.id, msg.text), message_id=msg.message_id)
+
+bot.run()
+```
+
+Even shorter - let telegroq answer every text message for you: replace the `chat` handler with
+`bot.auto_reply(character)`.
+
+Keep secrets out of your code: read them from environment variables (see [`examples/main.py`](examples/main.py)).
+
+## Concepts
+
+### Handlers receive `(user, msg)`
+
+* `user` is telebot's `User` (`.id`, `.username`, `.first_name`, ...).
+* `msg` is a `telegroq.Message`. `msg.text` is **always a string** (`""` for photos, stickers and voice notes),
+  `msg.args` is the text after a command, `msg.chat_id` / `msg.is_private` describe the chat, and
+  `msg.reply(text)` answers in the chat the message came from. Everything else (`msg.message_id`,
+  `msg.caption`, `msg.photo`, ...) is forwarded to the raw telebot message (`msg.raw`).
+
+> **Groups:** `bot.send_message(user.id, ...)` writes to the user's *private* chat. In group chats use
+> `msg.reply(...)` or `bot.send_message(msg.chat_id, ...)`. Restrict AI handlers with
+> `@bot.on_message(chat_types=["private"])` if you do not want the bot to answer everything in a group.
+
+### Commands
+
+```python
+@bot.cmd("/start", description="Say hello")   # description appears in Telegram's command menu
+@bot.cmd("help", "about")                     # several names, slash optional, any letter case
+```
+
+Registered commands are never delivered to `@bot.on_message()`, whatever order you declare them in.
+
+### Characters (personas with memory)
+
+```python
+character = telegroq.setCh("You are a pirate.", max_history=10, temperature=0.9, model="llama-3.1-8b-instant")
+
+character.get_response(user.id, "Hi!")       # -> str (never raises on Groq errors)
+character.ask(user.id, "Hi!")                # -> Reply(text, ok, error_kind, error)
+await character.aget_response(user.id, "Hi") # async variant (runs in a worker thread)
+character.clear_history(user.id)
+character.get_history(user.id)
+```
+
+* History is kept **per user id** and trimmed to the last `max_history` messages (`0` = stateless).
+  Calls for the same user are serialised, so quick successive messages cannot scramble the conversation.
+* `system_prompt` may also be a callable `(user_id) -> str` for per-user prompts.
+* `extra_params={"top_p": 0.9}` is forwarded to `chat.completions.create`.
+* Pass `client=` to use your own Groq-compatible client, or `bot=` / `.bind(bot)` to pick which bot's key is used.
+  Without either, the most recently configured key is used.
+
+### Inline buttons and callbacks
+
+```python
+from telegroq import inline_keyboard
+
+@bot.cmd("persona")
+def choose(user, msg):
+    bot.send_message(msg.chat_id, "Who am I?", reply_markup=inline_keyboard(
+        [("Pirate", "persona:pirate"), ("Poet", "persona:poet")],
+    ))
+
+@bot.callback(prefix="persona:")          # or @bot.callback("exact:data") / @bot.callback(regex=...)
+def picked(user, call):
+    call.answer(f"OK, {call.args}!")      # optional: telegroq answers for you if you don't
+    call.edit(f"Persona: {call.args}")    # edit the message that holds the buttons
+```
+
+`call` is a `CallbackContext` with `.data`, `.args` (data after the prefix), `.message`, `.answer()`,
+`.edit()`, `.edit_keyboard()` and `.reply()`. The button's loading spinner is cleared automatically.
+`button(text, callback_data)` enforces Telegram's 64-byte limit; `button(text, url=...)` makes link buttons.
+
+### Persistent memory
+
+```python
+from telegroq import SQLiteHistoryStore
+
+character = telegroq.setCh("...", store=SQLiteHistoryStore("history.db"))
+```
+
+Implement `telegroq.HistoryStore` (`load`, `save`, `clear`) to use Redis, Postgres, etc. The default
+`MemoryHistoryStore` forgets everything on restart.
+
+### Errors never take the bot down
+
+| Situation | What happens |
+|---|---|
+| Groq rate limit, bad key, timeout, outage | The user gets a friendly fallback message; the failed turn is not saved. Customise with `setCh(..., fallbacks={"rate_limit": "..."})`. |
+| Your handler raises | The error is logged, the user gets `bot.error_reply` (or run your own `@bot.on_error`), polling continues. |
+| Photo, sticker, voice note, ... | `msg.text == ""`; in private chats the user gets `bot.non_text_reply` unless you handle that type (`@bot.on_message(content_types=["photo"])`). Set it to `None` to stay silent. |
+| Model output breaks Markdown/HTML | `send_message(..., parse_mode=...)` retries as plain text. |
+| Reply longer than 4096 characters | Split into several messages automatically. |
+| Network errors while polling | `bot.run()` keeps retrying. |
+
+Forgetting `set_groq_key` raises `telegroq.ConfigurationError` - a setup bug, not a runtime failure.
+
+### Logging
+
+telegroq logs to the `telegroq` logger and is silent by default. Enable it with
+`logging.basicConfig(level=logging.INFO)`.
+
+## API summary
+
+| | |
+|---|---|
+| `telegroq.createBot(token, **telebot_kwargs)` | Create a `TeleGroqBot` (wraps `telebot.TeleBot`, available as `bot.telebot`; unknown attributes forward to it). |
+| `bot.set_groq_key(api_key, model=...)` | Create the Groq client (`timeout`, `max_retries` optional). |
+| `telegroq.setCh(system_prompt, max_history=10, **opts)` | Create a `Character`. |
+| `@bot.cmd(*names, description=None, chat_types=None)` | Command handler `fn(user, msg)`. |
+| `@bot.on_message(content_types=None, chat_types=None, regexp=None, func=None, typing=True)` | Wildcard handler `fn(user, msg)`. |
+| `bot.auto_reply(character, ...)` | Answer every text message with a character. |
+| `@bot.callback(*data, prefix=None, regex=None)` | Inline-button handler `fn(user, call)`. |
+| `@bot.on_error` | `fn(exc, user, update)` called when a handler raises. |
+| `bot.send_message(user_id, text, **kw)` / `bot.reply(user_id, text, message_id=None, **kw)` | Sending helpers (splitting, plain-text retry). |
+| `bot.run()` / `bot.stop()` | Start / stop long polling. |
+| `telegroq.button`, `telegroq.inline_keyboard` | Keyboard helpers. |
+| `HistoryStore`, `MemoryHistoryStore`, `SQLiteHistoryStore` | Conversation storage. |
+
+Every public function and class has a docstring; try `help(telegroq.Character)`.
+
+## Development
+
+```bash
+git clone https://github.com/kkkik/telegroq && cd telegroq
+python -m pip install -e ".[dev]"
+pytest          # no network or API keys needed (Telegram and Groq are faked)
+ruff check .
+```
+
+### Releasing to PyPI (with flit)
+
+1. Bump `__version__` in `src/telegroq/__init__.py` and add a section to `CHANGELOG.md`.
+2. Build and check: `flit build && twine check --strict dist/*`.
+3. Try it on TestPyPI first:
+   `FLIT_INDEX_URL=https://test.pypi.org/legacy/ FLIT_USERNAME=__token__ FLIT_PASSWORD=<testpypi-token> flit publish`.
+4. Publish: `FLIT_USERNAME=__token__ FLIT_PASSWORD=<pypi-token> flit publish`, or create a GitHub
+   release and let `.github/workflows/publish.yml` publish via PyPI trusted publishing.
+
+## License
+
+MIT - see [LICENSE](LICENSE).
+

telegroq-0.1.0/README.md

@@ -0,0 +1,186 @@
+# telegroq
+
+**A Groq-powered Telegram bot with its own personality in a few lines of Python.**
+
+`telegroq` bridges [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI) (`telebot`) and the
+[Groq API](https://console.groq.com/docs). You get decorators for commands, messages and inline buttons,
+characters with per-user memory, and sensible behaviour when things go wrong (rate limits, bad keys,
+photos and stickers instead of text) - without writing the glue yourself.
+
+> Unofficial project. Not affiliated with or endorsed by Telegram or Groq.
+
+## Install
+
+```bash
+pip install telegroq
+```
+
+Requires Python 3.10+. You need a Telegram bot token from [@BotFather](https://t.me/BotFather) and a Groq API key from
+[console.groq.com](https://console.groq.com/keys).
+
+## Quickstart
+
+```python
+import telegroq
+
+bot = telegroq.createBot("123456:TELEGRAM_BOT_TOKEN")
+bot.set_groq_key("gsk_...", model="llama-3.3-70b-versatile")
+
+character = telegroq.setCh(
+    system_prompt="You are a funny, witty, and energetic AI assistant.",
+    max_history=10,
+)
+
+@bot.cmd("/start")
+def start(user, msg):
+    bot.send_message(user.id, f"Hello {user.first_name}! I am ready.")
+
+@bot.cmd("/reset")
+def reset(user, msg):
+    character.clear_history(user.id)
+    bot.send_message(user.id, "Conversation memory cleared!")
+
+@bot.on_message()
+def chat(user, msg):
+    bot.reply(user.id, character.get_response(user.id, msg.text), message_id=msg.message_id)
+
+bot.run()
+```
+
+Even shorter - let telegroq answer every text message for you: replace the `chat` handler with
+`bot.auto_reply(character)`.
+
+Keep secrets out of your code: read them from environment variables (see [`examples/main.py`](examples/main.py)).
+
+## Concepts
+
+### Handlers receive `(user, msg)`
+
+* `user` is telebot's `User` (`.id`, `.username`, `.first_name`, ...).
+* `msg` is a `telegroq.Message`. `msg.text` is **always a string** (`""` for photos, stickers and voice notes),
+  `msg.args` is the text after a command, `msg.chat_id` / `msg.is_private` describe the chat, and
+  `msg.reply(text)` answers in the chat the message came from. Everything else (`msg.message_id`,
+  `msg.caption`, `msg.photo`, ...) is forwarded to the raw telebot message (`msg.raw`).
+
+> **Groups:** `bot.send_message(user.id, ...)` writes to the user's *private* chat. In group chats use
+> `msg.reply(...)` or `bot.send_message(msg.chat_id, ...)`. Restrict AI handlers with
+> `@bot.on_message(chat_types=["private"])` if you do not want the bot to answer everything in a group.
+
+### Commands
+
+```python
+@bot.cmd("/start", description="Say hello")   # description appears in Telegram's command menu
+@bot.cmd("help", "about")                     # several names, slash optional, any letter case
+```
+
+Registered commands are never delivered to `@bot.on_message()`, whatever order you declare them in.
+
+### Characters (personas with memory)
+
+```python
+character = telegroq.setCh("You are a pirate.", max_history=10, temperature=0.9, model="llama-3.1-8b-instant")
+
+character.get_response(user.id, "Hi!")       # -> str (never raises on Groq errors)
+character.ask(user.id, "Hi!")                # -> Reply(text, ok, error_kind, error)
+await character.aget_response(user.id, "Hi") # async variant (runs in a worker thread)
+character.clear_history(user.id)
+character.get_history(user.id)
+```
+
+* History is kept **per user id** and trimmed to the last `max_history` messages (`0` = stateless).
+  Calls for the same user are serialised, so quick successive messages cannot scramble the conversation.
+* `system_prompt` may also be a callable `(user_id) -> str` for per-user prompts.
+* `extra_params={"top_p": 0.9}` is forwarded to `chat.completions.create`.
+* Pass `client=` to use your own Groq-compatible client, or `bot=` / `.bind(bot)` to pick which bot's key is used.
+  Without either, the most recently configured key is used.
+
+### Inline buttons and callbacks
+
+```python
+from telegroq import inline_keyboard
+
+@bot.cmd("persona")
+def choose(user, msg):
+    bot.send_message(msg.chat_id, "Who am I?", reply_markup=inline_keyboard(
+        [("Pirate", "persona:pirate"), ("Poet", "persona:poet")],
+    ))
+
+@bot.callback(prefix="persona:")          # or @bot.callback("exact:data") / @bot.callback(regex=...)
+def picked(user, call):
+    call.answer(f"OK, {call.args}!")      # optional: telegroq answers for you if you don't
+    call.edit(f"Persona: {call.args}")    # edit the message that holds the buttons
+```
+
+`call` is a `CallbackContext` with `.data`, `.args` (data after the prefix), `.message`, `.answer()`,
+`.edit()`, `.edit_keyboard()` and `.reply()`. The button's loading spinner is cleared automatically.
+`button(text, callback_data)` enforces Telegram's 64-byte limit; `button(text, url=...)` makes link buttons.
+
+### Persistent memory
+
+```python
+from telegroq import SQLiteHistoryStore
+
+character = telegroq.setCh("...", store=SQLiteHistoryStore("history.db"))
+```
+
+Implement `telegroq.HistoryStore` (`load`, `save`, `clear`) to use Redis, Postgres, etc. The default
+`MemoryHistoryStore` forgets everything on restart.
+
+### Errors never take the bot down
+
+| Situation | What happens |
+|---|---|
+| Groq rate limit, bad key, timeout, outage | The user gets a friendly fallback message; the failed turn is not saved. Customise with `setCh(..., fallbacks={"rate_limit": "..."})`. |
+| Your handler raises | The error is logged, the user gets `bot.error_reply` (or run your own `@bot.on_error`), polling continues. |
+| Photo, sticker, voice note, ... | `msg.text == ""`; in private chats the user gets `bot.non_text_reply` unless you handle that type (`@bot.on_message(content_types=["photo"])`). Set it to `None` to stay silent. |
+| Model output breaks Markdown/HTML | `send_message(..., parse_mode=...)` retries as plain text. |
+| Reply longer than 4096 characters | Split into several messages automatically. |
+| Network errors while polling | `bot.run()` keeps retrying. |
+
+Forgetting `set_groq_key` raises `telegroq.ConfigurationError` - a setup bug, not a runtime failure.
+
+### Logging
+
+telegroq logs to the `telegroq` logger and is silent by default. Enable it with
+`logging.basicConfig(level=logging.INFO)`.
+
+## API summary
+
+| | |
+|---|---|
+| `telegroq.createBot(token, **telebot_kwargs)` | Create a `TeleGroqBot` (wraps `telebot.TeleBot`, available as `bot.telebot`; unknown attributes forward to it). |
+| `bot.set_groq_key(api_key, model=...)` | Create the Groq client (`timeout`, `max_retries` optional). |
+| `telegroq.setCh(system_prompt, max_history=10, **opts)` | Create a `Character`. |
+| `@bot.cmd(*names, description=None, chat_types=None)` | Command handler `fn(user, msg)`. |
+| `@bot.on_message(content_types=None, chat_types=None, regexp=None, func=None, typing=True)` | Wildcard handler `fn(user, msg)`. |
+| `bot.auto_reply(character, ...)` | Answer every text message with a character. |
+| `@bot.callback(*data, prefix=None, regex=None)` | Inline-button handler `fn(user, call)`. |
+| `@bot.on_error` | `fn(exc, user, update)` called when a handler raises. |
+| `bot.send_message(user_id, text, **kw)` / `bot.reply(user_id, text, message_id=None, **kw)` | Sending helpers (splitting, plain-text retry). |
+| `bot.run()` / `bot.stop()` | Start / stop long polling. |
+| `telegroq.button`, `telegroq.inline_keyboard` | Keyboard helpers. |
+| `HistoryStore`, `MemoryHistoryStore`, `SQLiteHistoryStore` | Conversation storage. |
+
+Every public function and class has a docstring; try `help(telegroq.Character)`.
+
+## Development
+
+```bash
+git clone https://github.com/kkkik/telegroq && cd telegroq
+python -m pip install -e ".[dev]"
+pytest          # no network or API keys needed (Telegram and Groq are faked)
+ruff check .
+```
+
+### Releasing to PyPI (with flit)
+
+1. Bump `__version__` in `src/telegroq/__init__.py` and add a section to `CHANGELOG.md`.
+2. Build and check: `flit build && twine check --strict dist/*`.
+3. Try it on TestPyPI first:
+   `FLIT_INDEX_URL=https://test.pypi.org/legacy/ FLIT_USERNAME=__token__ FLIT_PASSWORD=<testpypi-token> flit publish`.
+4. Publish: `FLIT_USERNAME=__token__ FLIT_PASSWORD=<pypi-token> flit publish`, or create a GitHub
+   release and let `.github/workflows/publish.yml` publish via PyPI trusted publishing.
+
+## License
+
+MIT - see [LICENSE](LICENSE).

telegroq-0.1.0/examples/main.py

@@ -0,0 +1,61 @@
+"""Minimal Groq-powered Telegram bot with a persona.
+
+Setup:
+    pip install telegroq
+    export TELEGRAM_BOT_TOKEN="123456:ABC..."   # from @BotFather
+    export GROQ_API_KEY="gsk_..."               # from console.groq.com
+    python main.py
+"""
+
+import logging
+import os
+import sys
+
+import telegroq
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+
+TELEGRAM_TOKEN = os.environ.get("TELEGRAM_BOT_TOKEN")
+GROQ_KEY = os.environ.get("GROQ_API_KEY")
+if not TELEGRAM_TOKEN or not GROQ_KEY:
+    sys.exit("Set TELEGRAM_BOT_TOKEN and GROQ_API_KEY first (see the top of this file).")
+
+# 1. Initialize the bot
+bot = telegroq.createBot(TELEGRAM_TOKEN)
+bot.set_groq_key(GROQ_KEY, model="llama-3.3-70b-versatile")
+
+# 2. Define the AI persona (remembers the last 10 messages per user)
+character = telegroq.setCh(
+    system_prompt=(
+        "You are a funny, witty, and energetic AI assistant. "
+        "Keep answers short and punchy, and use plain text (no Markdown)."
+    ),
+    max_history=10,
+)
+
+
+# 3. Custom commands (the description shows up in Telegram's command menu)
+@bot.cmd("/start", description="Say hello")
+def start(user, msg):
+    bot.send_message(user.id, f"Hello {user.first_name}! I am ready. Send me anything.")
+
+
+@bot.cmd("/reset", description="Forget our conversation")
+def reset(user, msg):
+    character.clear_history(user.id)
+    bot.send_message(user.id, "Conversation memory cleared!")
+
+
+# 4. AI auto-responder: every text message that is not a command ends up here.
+#    Photos, stickers and voice notes get a polite "text only" notice automatically.
+@bot.on_message()
+def chat_handler(user, msg):
+    reply = character.get_response(user.id, msg.text)
+    bot.reply(user.id, reply, message_id=msg.message_id)
+
+    # Shorter alternative: replace this whole handler with  bot.auto_reply(character)
+
+
+# 5. Launch (Ctrl+C to stop)
+if __name__ == "__main__":
+    bot.run()

telegroq-0.1.0/examples/persona_switcher.py

@@ -0,0 +1,75 @@
+"""Inline buttons choose the persona; conversations survive restarts (SQLite).
+
+Setup:
+    pip install telegroq
+    export TELEGRAM_BOT_TOKEN="123456:ABC..."
+    export GROQ_API_KEY="gsk_..."
+    python persona_switcher.py
+
+Try /persona, press a button, then chat.
+"""
+
+import logging
+import os
+import sys
+
+import telegroq
+from telegroq import SQLiteHistoryStore, inline_keyboard
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+
+TELEGRAM_TOKEN = os.environ.get("TELEGRAM_BOT_TOKEN")
+GROQ_KEY = os.environ.get("GROQ_API_KEY")
+if not TELEGRAM_TOKEN or not GROQ_KEY:
+    sys.exit("Set TELEGRAM_BOT_TOKEN and GROQ_API_KEY first (see the top of this file).")
+
+bot = telegroq.createBot(TELEGRAM_TOKEN)
+bot.set_groq_key(GROQ_KEY)
+
+PROMPTS = {
+    "pirate": "You are a swashbuckling pirate. Answer in pirate speak, briefly.",
+    "teacher": "You are a patient teacher. Explain step by step, in simple words.",
+    "poet": "You are a poet. Reply in a short rhyming verse.",
+}
+# One character per persona; one SQLite file, one table per persona.
+personas = {
+    name: telegroq.setCh(prompt, max_history=12, store=SQLiteHistoryStore("history.db", table=name))
+    for name, prompt in PROMPTS.items()
+}
+chosen: dict[int, str] = {}  # user id -> persona name (use a database for real deployments)
+
+
+@bot.cmd("start", description="Start the bot")
+@bot.cmd("persona", description="Choose who I am")
+def persona_menu(user, msg):
+    keyboard = inline_keyboard([(name.title(), f"persona:{name}") for name in personas])
+    bot.send_message(msg.chat_id, "Who should I be?", reply_markup=keyboard)
+
+
+@bot.callback(prefix="persona:")
+def persona_chosen(user, call):
+    chosen[user.id] = call.args  # e.g. "persona:pirate" -> "pirate"
+    call.answer(f"Now chatting with the {call.args}!")
+    call.edit(f"Persona: {call.args.title()}. Say something!")
+
+
+@bot.cmd("reset", description="Forget our conversation")
+def reset(user, msg):
+    personas[chosen.get(user.id, "pirate")].clear_history(user.id)
+    msg.reply("Memory cleared.")
+
+
+@bot.on_message(chat_types=["private"])
+def chat(user, msg):
+    character = personas[chosen.get(user.id, "pirate")]
+    msg.reply(character.get_response(user.id, msg.text))
+
+
+@bot.on_error
+def log_errors(exc, user, update):
+    logging.getLogger(__name__).error("handler failed for user %s: %r", user.id, exc)
+    update.reply("Sorry, that went wrong. Try again?")  # works for messages and button presses
+
+
+if __name__ == "__main__":
+    bot.run()

telegroq-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["flit_core>=3.11,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "telegroq"
+dynamic = ["version"]
+description = "Deploy a Groq-powered Telegram bot with a custom persona in a few lines (pyTelegramBotAPI + Groq)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "AYM" }]
+keywords = ["telegram", "bot", "groq", "llm", "chatbot", "ai", "persona", "pytelegrambotapi", "telebot"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Communications :: Chat",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pyTelegramBotAPI>=4.16",
+    "groq>=0.9",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.5",
+    "flit>=3.11",
+    "twine>=6.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/kkkik/telegroq"
+Source = "https://github.com/kkkik/telegroq"
+Issues = "https://github.com/kkkik/telegroq/issues"
+Changelog = "https://github.com/kkkik/telegroq/blob/main/CHANGELOG.md"
+
+[tool.flit.module]
+name = "telegroq"  # found in src/telegroq; version is read from __version__ in src/telegroq/__init__.py
+
+[tool.flit.sdist]
+include = ["tests/", "examples/", "CHANGELOG.md"]
+exclude = ["**/__pycache__/", "**/*.pyc", "publish.sh", "token.txt"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["E501"]