Avatar Ilya Mateyko

go.astrophena.name/tools Module

GitHub repository | Commit (90b6d01)

Personal tools.

starlet

Starlet is a Telegram bot runner that uses Starlark.

Starlet fetches your bot code from a GitHub Gist, executes it within a Starlark interpreter, and exposes specific modules for interacting with Telegram and other services. When a Telegram update arrives via webhook, Starlet parses it, converts it to a Starlark dictionary, and calls the handle function defined in your bot's Starlark code.

Starlet periodically pings itself to prevent Render from idling, ensuring continuous operation.

Usage

$ starlet [flags...]

Starlark Environment

The following modules are available to your bot code: 

config: Contains bot configuration.
	- bot_id (int): The Telegram user ID of the bot.
	- bot_username (str): The Telegram username of the bot.
	- owner_id (int): The Telegram user ID of the bot owner.
	- version (str): The bot's version string.

convcache: Provides a way to cache bot conversations.
	- get(chat_id: int) -> list: Retrieves the conversation history for the given chat ID.
	- append(chat_id: int, message: str): Appends a message to the conversation history for the given chat ID.
	- reset(chat_id: int): Clears the conversation history for the given chat ID.

debug: Provides debugging utilities.
	- stack(): Returns the current Starlark call stack as a string.
	- go_stack(): Returns the current Go call stack as a string.

files: Allows retrieval of files from the GitHub Gist containing the bot code.
	- read(name: str) -> str: Retrieves a file from the GitHub Gist. Causes an error if the file is not present.

gemini: Enables interaction with the Gemini API.
	- generate_content(model, contents, system, unsafe): Generates text using Gemini.
		- model (str): The name of the model to use for generation.
		- contents (list of strings): The text to provide to Gemini for generation.
		- system (dict, optional): System instructions to guide Gemini's response, containing a single key "text" with a string value.
		- unsafe (bool, optional): Disables all model safety measures.

markdown: Facilitates operations with Markdown text.
	- convert(text: str) -> dict: Converts Markdown text to Telegram-flavored message markup suitable for inclusion in sendMessage Telegram Bot API call payloads.

telegram: Allows interaction with the Telegram Bot API.
	- call(method, args): Calls a Telegram Bot API method.
		- method (str): The Telegram Bot API method to call.
		- args (dict): The arguments to pass to the method.

time: Provides time-related functions. See https://pkg.go.dev/go.starlark.net/lib/time#Module for documentation.

GitHub Gist Structure

The GitHub Gist containing the bot code must have the following structure:

Entry Point

The bot code must define a function called handle that takes a single argument — a dictionary representing the Telegram update. This function is called by Starlet for each incoming update.

If you define an on_load function, Starlet will call it whenever it loads bot code from the GitHub Gist, including the initial load and after reloads triggered via the /reload endpoint. This can be useful for tasks like updating the command list in Telegram.

Environment Variables

The following environment variables can be used to configure Starlet:

Debug Interface

Starlet provides a debug interface at /debug with the following endpoints:

When running on Render, authentication through Telegram is required to access the debug interface. The user must be the bot owner to authenticate successfully. See https://core.telegram.org/widgets/login for guidance. Use https://<bot URL>/login as the login URL.