telegroq 0.0.1__tar.gz

telegroq-0.0.1/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.0.1] - 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.0.1/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.0.1/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.5
+Name: telegroq
+Version: 0.0.1
+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
+
+**Give your Telegram bot a brain and a personality - in 5 lines of Python.**
+
+[![PyPI](https://img.shields.io/pypi/v/telegroq.svg)](https://pypi.org/project/telegroq/)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+[![CI](https://github.com/kkkik/telegroq/actions/workflows/ci.yml/badge.svg)](https://github.com/kkkik/telegroq/actions/workflows/ci.yml)
+
+`telegroq` connects [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI) (`telebot`) with the
+blazing-fast [Groq API](https://console.groq.com/docs). Write handlers with simple decorators, create
+characters that remember each user, and let the library deal with rate limits, bad keys, long messages and
+photos or stickers - so your bot keeps running no matter what.
+
+```python
+import telegroq
+
+bot = telegroq.createBot("TELEGRAM_BOT_TOKEN")
+bot.set_groq_key("GROQ_API_KEY")
+bot.auto_reply(telegroq.setCh("You are a witty, friendly assistant."))
+bot.run()
+```
+
+That's a complete AI chatbot. 🎉
+
+> Unofficial project. Not affiliated with or endorsed by Telegram or Groq.
+
+## ✨ Features
+
+- 🎭 **Characters with memory** - a persona (system prompt) with per-user conversation history.
+- ⚡ **Groq-powered** - fast answers from Llama and other models hosted on Groq.
+- 🧩 **Friendly decorators** - `@bot.cmd`, `@bot.on_message`, `@bot.callback`, `@bot.on_error`.
+- 🔘 **Inline buttons made easy** - keyboards and callbacks in a few lines.
+- 💾 **Pluggable storage** - in-memory by default, SQLite built in, or bring your own.
+- 🛡️ **Never crashes on errors** - rate limits, timeouts, bad keys and handler bugs are handled gracefully.
+- ✂️ **Smart sending** - long replies are split automatically; broken Markdown/HTML falls back to plain text.
+- 🧪 **Typed and tested** - ships with type hints (`py.typed`) and a test suite that needs no network.
+
+## 📦 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()
+```
+
+Want it even shorter? Replace the `chat` handler with `bot.auto_reply(character)`.
+
+🔐 Keep secrets out of your code: read them from environment variables, as in
+[`examples/main.py`](https://github.com/kkkik/telegroq/blob/main/examples/main.py).
+
+## 🧠 Core ideas
+
+### 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.
+
+A complete persona-switching bot lives in
+[`examples/persona_switcher.py`](https://github.com/kkkik/telegroq/blob/main/examples/persona_switcher.py).
+
+### 💾 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 at a glance
+
+| | |
+|---|---|
+| `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 .
+```
+
+Contributions and ideas are welcome - open an
+[issue](https://github.com/kkkik/telegroq/issues) or a pull request.
+
+## 📄 License
+
+MIT - see [LICENSE](https://github.com/kkkik/telegroq/blob/main/LICENSE).
+

telegroq-0.0.1/README.md

@@ -0,0 +1,210 @@
+# 🤖 telegroq
+
+**Give your Telegram bot a brain and a personality - in 5 lines of Python.**
+
+[![PyPI](https://img.shields.io/pypi/v/telegroq.svg)](https://pypi.org/project/telegroq/)
+![Python](https://img.shields.io/badge/python-3.10%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+[![CI](https://github.com/kkkik/telegroq/actions/workflows/ci.yml/badge.svg)](https://github.com/kkkik/telegroq/actions/workflows/ci.yml)
+
+`telegroq` connects [pyTelegramBotAPI](https://github.com/eternnoir/pyTelegramBotAPI) (`telebot`) with the
+blazing-fast [Groq API](https://console.groq.com/docs). Write handlers with simple decorators, create
+characters that remember each user, and let the library deal with rate limits, bad keys, long messages and
+photos or stickers - so your bot keeps running no matter what.
+
+```python
+import telegroq
+
+bot = telegroq.createBot("TELEGRAM_BOT_TOKEN")
+bot.set_groq_key("GROQ_API_KEY")
+bot.auto_reply(telegroq.setCh("You are a witty, friendly assistant."))
+bot.run()
+```
+
+That's a complete AI chatbot. 🎉
+
+> Unofficial project. Not affiliated with or endorsed by Telegram or Groq.
+
+## ✨ Features
+
+- 🎭 **Characters with memory** - a persona (system prompt) with per-user conversation history.
+- ⚡ **Groq-powered** - fast answers from Llama and other models hosted on Groq.
+- 🧩 **Friendly decorators** - `@bot.cmd`, `@bot.on_message`, `@bot.callback`, `@bot.on_error`.
+- 🔘 **Inline buttons made easy** - keyboards and callbacks in a few lines.
+- 💾 **Pluggable storage** - in-memory by default, SQLite built in, or bring your own.
+- 🛡️ **Never crashes on errors** - rate limits, timeouts, bad keys and handler bugs are handled gracefully.
+- ✂️ **Smart sending** - long replies are split automatically; broken Markdown/HTML falls back to plain text.
+- 🧪 **Typed and tested** - ships with type hints (`py.typed`) and a test suite that needs no network.
+
+## 📦 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()
+```
+
+Want it even shorter? Replace the `chat` handler with `bot.auto_reply(character)`.
+
+🔐 Keep secrets out of your code: read them from environment variables, as in
+[`examples/main.py`](https://github.com/kkkik/telegroq/blob/main/examples/main.py).
+
+## 🧠 Core ideas
+
+### 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.
+
+A complete persona-switching bot lives in
+[`examples/persona_switcher.py`](https://github.com/kkkik/telegroq/blob/main/examples/persona_switcher.py).
+
+### 💾 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 at a glance
+
+| | |
+|---|---|
+| `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 .
+```
+
+Contributions and ideas are welcome - open an
+[issue](https://github.com/kkkik/telegroq/issues) or a pull request.
+
+## 📄 License
+
+MIT - see [LICENSE](https://github.com/kkkik/telegroq/blob/main/LICENSE).

telegroq-0.0.1/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.0.1/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()