# RoboTooter
A Python framework for easily creating Mastodon bots with pluggable content generation and filtering capabilities.
## Features
- **Multiple Bot Types**: Currently supports Markov chain-based text generation
- **Plugin Architecture**: Extensible plugin system for adding new bot types and functionality
- **Flexible Filtering**: Extensible filter system for processing input text (Gutenberg, blank line removal, paragraph combining)
- **Mastodon Integration**: Built-in support for posting to Mastodon instances
- **CLI Interface**: Comprehensive command line interface for bot and plugin management
- **Configuration Management**: Simple bot configuration and data management
## Why?
I've built a few bots over the years, for fun. Recently I was reminded of a Twitter bot I wrote back in 2019 that
generated sentences from a Markov chain generator trained on the text of Conan the Barbarian stories. I decided to
reimplement it, this time for Mastodon.
I also wanted to be able to easily create other bots to do other things, and so built a simple plugin architecture.
## Examples
- **[Conan-o-matic](https://social.naughtybaptist.com/@conanomatic)** The original reason for this project. Yes, it's silly. I still find it funny.
- **[Chapter By Chapter](https://social.naughtybaptist.com/@chapterbychapter)]** Posts a chapter a day from Public Domain litereature. Victorian-era Netflix.
## Installation
### As a Package
```bash
# Create a virtual environment
$ python3 -m venv .venv
# Activtate it
$ . .venv/bin/activate
# Install via pip
$ pip install robotooter
```
### From Source
This project uses Poetry for dependency management. To install:
```bash
git clone ssh://git@codeberg.org/bfordham/robotooter.git
cd robotooter
poetry install
```
## Quick Start
1. **Configure the framework**:
```bash
robotooter configure
```
2. **Create a new bot**:
```bash
robotooter create
```
3. **Set up your bot's data** (for Markov bots, add a `sources.txt` file to the bot directory):
```bash
robotooter --bot <bot-name> setup
```
4. **Authorize your bot with Mastodon**:
```bash
robotooter --bot <bot-name> authorize
```
5. **Generate content locally**:
```bash
robotooter --bot <bot-name> speak
```
6. **Post to Mastodon**:
```bash
robotooter --bot <bot-name> toot
```
## Bot Types
### Markov Bot
The Markov bot generates text using Markov chains trained on source material.
**Setup Requirements**:
- Create a `sources.txt` file in your bot's working directory
- Each line should contain a URL to a text file to use as training data
- Run `robotooter --bot <bot-name> setup` to download and process the sources
## Plugin Architecture
RoboTooter now supports a plugin system that allows you to extend the framework with custom bot types and functionality. Plugins inherit from the `BasePlugin` class and can define their own filters and bot implementations.
**Plugin Development**:
- Extend the `BasePlugin` class to create custom bot types
- Register plugins using `robotooter plugins register <plugin-name>`
- Remove plugins with `robotooter plugins remove <plugin-name>`
## CLI Commands
### General Commands
- `robotooter info` - Display information about the local setup
- `robotooter configure` - Initialize configuration
- `robotooter create` - Create a new bot
- `robotooter list` - List all configured bots
- `robotooter version` - Display the current version
- `robotooter help` - Display help information
### Bot-Specific Commands
- `robotooter --bot <name> setup` - Download and process bot training data
- `robotooter --bot <name> authorize [--force]` - Authorize bot with Mastodon
- `robotooter --bot <name> speak [--count N]` - Generate content locally
- `robotooter --bot <name> toot` - Generate and post content to Mastodon
### Plugin Management
- `robotooter plugins register <plugin-name>` - Register a new plugin
- `robotooter plugins remove <plugin-name>` - Remove a plugin
- `robotooter plugins help` - Display plugin management help
## Project Structure
```
src/robotooter/
bots/ # Bot implementations
base_bot.py # Base bot class
markov/ # Markov chain bot
cli/ # Command line interface
filters/ # Text processing filters
mastodon_manager.py # Mastodon API integration
models.py # Data models
util.py # Utility functions
```
## Development
### Requirements
- Python 3.12+
- Poetry for dependency management
### Development Setup
```bash
poetry install --with dev
```
### Running Tests
```bash
poetry run pytest
```
### Code Quality
The project uses Ruff for linting and MyPy for type checking:
```bash
# Linting
./scripts/lint
# Type checking
./scripts/type
```
## Dependencies
- **requests**: HTTP client for downloading source material
- **markovify**: Markov chain text generation
- **mastodon.py**: Mastodon API client
- **pydantic**: Data validation and settings management
- **jinja2**: Template engine
## Contributing
If you would like to add features, please feel free. If you use this yourself, [please let me know](https://infosec.exchange/@bfordham)!
## License
This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the [LICENSE](LICENSE) file for details.
The AGPL-3.0 is a copyleft license that requires anyone who distributes the code or runs it on a server to make the source code available under the same license terms.
Raw data
{
"_id": null,
"home_page": "https://github.com/bfordham/robotooter",
"name": "robotooter",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": "mastodon, bot, social-media, markov, automation",
"author": "Bryan L. Fordham",
"author_email": "bfordham@naughtybaptist.com",
"download_url": "https://files.pythonhosted.org/packages/f9/44/87b1d65aa8a6b949bbbb8e3d8e622d45eb11a48558a89a376e33308bb3a0/robotooter-0.2.1.tar.gz",
"platform": null,
"description": "# RoboTooter\n\nA Python framework for easily creating Mastodon bots with pluggable content generation and filtering capabilities.\n\n## Features\n\n- **Multiple Bot Types**: Currently supports Markov chain-based text generation\n- **Plugin Architecture**: Extensible plugin system for adding new bot types and functionality\n- **Flexible Filtering**: Extensible filter system for processing input text (Gutenberg, blank line removal, paragraph combining)\n- **Mastodon Integration**: Built-in support for posting to Mastodon instances\n- **CLI Interface**: Comprehensive command line interface for bot and plugin management\n- **Configuration Management**: Simple bot configuration and data management\n\n## Why?\n\nI've built a few bots over the years, for fun. Recently I was reminded of a Twitter bot I wrote back in 2019 that\ngenerated sentences from a Markov chain generator trained on the text of Conan the Barbarian stories. I decided to\nreimplement it, this time for Mastodon.\n\nI also wanted to be able to easily create other bots to do other things, and so built a simple plugin architecture.\n\n## Examples\n\n- **[Conan-o-matic](https://social.naughtybaptist.com/@conanomatic)** The original reason for this project. Yes, it's silly. I still find it funny.\n- **[Chapter By Chapter](https://social.naughtybaptist.com/@chapterbychapter)]** Posts a chapter a day from Public Domain litereature. Victorian-era Netflix.\n\n## Installation\n\n### As a Package\n\n```bash\n# Create a virtual environment\n$ python3 -m venv .venv\n# Activtate it\n$ . .venv/bin/activate\n# Install via pip\n$ pip install robotooter\n```\n\n### From Source\nThis project uses Poetry for dependency management. To install:\n\n```bash\ngit clone ssh://git@codeberg.org/bfordham/robotooter.git\ncd robotooter\npoetry install\n```\n\n## Quick Start\n\n1. **Configure the framework**:\n ```bash\n robotooter configure\n ```\n\n2. **Create a new bot**:\n ```bash\n robotooter create\n ```\n\n3. **Set up your bot's data** (for Markov bots, add a `sources.txt` file to the bot directory):\n ```bash\n robotooter --bot <bot-name> setup\n ```\n\n4. **Authorize your bot with Mastodon**:\n ```bash\n robotooter --bot <bot-name> authorize\n ```\n\n5. **Generate content locally**:\n ```bash\n robotooter --bot <bot-name> speak\n ```\n\n6. **Post to Mastodon**:\n ```bash\n robotooter --bot <bot-name> toot\n ```\n\n## Bot Types\n\n### Markov Bot\n\nThe Markov bot generates text using Markov chains trained on source material. \n\n**Setup Requirements**:\n- Create a `sources.txt` file in your bot's working directory\n- Each line should contain a URL to a text file to use as training data\n- Run `robotooter --bot <bot-name> setup` to download and process the sources\n\n## Plugin Architecture\n\nRoboTooter now supports a plugin system that allows you to extend the framework with custom bot types and functionality. Plugins inherit from the `BasePlugin` class and can define their own filters and bot implementations.\n\n**Plugin Development**:\n- Extend the `BasePlugin` class to create custom bot types\n- Register plugins using `robotooter plugins register <plugin-name>`\n- Remove plugins with `robotooter plugins remove <plugin-name>`\n\n## CLI Commands\n\n### General Commands\n- `robotooter info` - Display information about the local setup\n- `robotooter configure` - Initialize configuration\n- `robotooter create` - Create a new bot\n- `robotooter list` - List all configured bots\n- `robotooter version` - Display the current version\n- `robotooter help` - Display help information\n\n### Bot-Specific Commands\n- `robotooter --bot <name> setup` - Download and process bot training data\n- `robotooter --bot <name> authorize [--force]` - Authorize bot with Mastodon\n- `robotooter --bot <name> speak [--count N]` - Generate content locally\n- `robotooter --bot <name> toot` - Generate and post content to Mastodon\n\n### Plugin Management\n- `robotooter plugins register <plugin-name>` - Register a new plugin\n- `robotooter plugins remove <plugin-name>` - Remove a plugin\n- `robotooter plugins help` - Display plugin management help\n\n## Project Structure\n\n```\nsrc/robotooter/\n bots/ # Bot implementations\n base_bot.py # Base bot class\n markov/ # Markov chain bot\n cli/ # Command line interface\n filters/ # Text processing filters\n mastodon_manager.py # Mastodon API integration\n models.py # Data models\n util.py # Utility functions\n```\n\n## Development\n\n### Requirements\n\n- Python 3.12+\n- Poetry for dependency management\n\n### Development Setup\n\n```bash\npoetry install --with dev\n```\n\n### Running Tests\n\n```bash\npoetry run pytest\n```\n\n### Code Quality\n\nThe project uses Ruff for linting and MyPy for type checking:\n\n```bash\n# Linting\n./scripts/lint\n\n# Type checking \n./scripts/type\n```\n\n## Dependencies\n\n- **requests**: HTTP client for downloading source material\n- **markovify**: Markov chain text generation\n- **mastodon.py**: Mastodon API client\n- **pydantic**: Data validation and settings management\n- **jinja2**: Template engine\n\n## Contributing\n\nIf you would like to add features, please feel free. If you use this yourself, [please let me know](https://infosec.exchange/@bfordham)!\n\n## License\n\nThis project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the [LICENSE](LICENSE) file for details.\n\nThe AGPL-3.0 is a copyleft license that requires anyone who distributes the code or runs it on a server to make the source code available under the same license terms.\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "A Python framework for easily creating Mastodon bots with pluggable content generation and filtering capabilities",
"version": "0.2.1",
"project_urls": {
"Documentation": "https://github.com/bfordham/robotooter#readme",
"Homepage": "https://github.com/bfordham/robotooter",
"Repository": "https://github.com/bfordham/robotooter"
},
"split_keywords": [
"mastodon",
" bot",
" social-media",
" markov",
" automation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1a7e76a9875c00be100e57a3a73cdd3dd5a42ef0d129b6b4f95256f667921015",
"md5": "14f9947a92a19873d462df181bc7b2d0",
"sha256": "4afe10a12fcff0855be8d10deab64b9e5c285d2d1d56f6a900a6def1fa1ab191"
},
"downloads": -1,
"filename": "robotooter-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "14f9947a92a19873d462df181bc7b2d0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 37249,
"upload_time": "2025-08-16T04:14:09",
"upload_time_iso_8601": "2025-08-16T04:14:09.178000Z",
"url": "https://files.pythonhosted.org/packages/1a/7e/76a9875c00be100e57a3a73cdd3dd5a42ef0d129b6b4f95256f667921015/robotooter-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f94487b1d65aa8a6b949bbbb8e3d8e622d45eb11a48558a89a376e33308bb3a0",
"md5": "a8f5870e08b1a6ecf9061ec1bfd4a9ae",
"sha256": "4f3e8673a2e6064acf17ac21db7d89d8cdeb0e1da676ae9ec873c03f05a7cfbb"
},
"downloads": -1,
"filename": "robotooter-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "a8f5870e08b1a6ecf9061ec1bfd4a9ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 30383,
"upload_time": "2025-08-16T04:14:10",
"upload_time_iso_8601": "2025-08-16T04:14:10.278596Z",
"url": "https://files.pythonhosted.org/packages/f9/44/87b1d65aa8a6b949bbbb8e3d8e622d45eb11a48558a89a376e33308bb3a0/robotooter-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-16 04:14:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bfordham",
"github_project": "robotooter",
"github_not_found": true,
"lcname": "robotooter"
}
JSON
