feat: Initial commit

1 files changed, 226 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7e2fad8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,226 @@
+# UmaBot
+
+A modular Reddit bot for automated post moderation built with Python and PRAW.
+
+## Features
+
+- **Spam Detection**: Automatically removes posts from users who post more than 3 times in 24 hours
+- **Roleplay Limiter**: Prevents users from posting multiple times with the "Roleplay" flair
+- **Modular Design**: Easy to add new moderation rules
+- **Configurable Messages**: Customizable removal messages
+- **Dry Run Mode**: Test the bot without actually removing posts
+- **Comprehensive Logging**: Detailed logs for monitoring and debugging
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+# Using Rye (recommended)
+rye sync
+
+# Or using pip
+pip install -r requirements.txt
+```
+
+### 2. Set Up Reddit API
+
+1. Go to https://www.reddit.com/prefs/apps
+2. Click "Create App" or "Create Another App"
+3. Fill in the details:
+   - **Name**: UmaBot
+   - **Type**: Script
+   - **Description**: Reddit moderation bot
+   - **About URL**: (leave blank)
+   - **Redirect URI**: http://localhost:8080
+4. Note down the `client_id` (under the app name) and `client_secret`
+
+### 3. Configure Environment Variables
+
+Create a `.env` file in the project root:
+
+```env
+# Reddit API Credentials
+REDDIT_CLIENT_ID=your_client_id_here
+REDDIT_CLIENT_SECRET=your_client_secret_here
+REDDIT_USERNAME=your_reddit_username
+REDDIT_PASSWORD=your_reddit_password
+REDDIT_USER_AGENT=UmaBot/0.1.0
+
+# Subreddit Configuration
+SUBREDDIT_NAME=your_subreddit_name
+
+# Bot Messages
+SPAM_MESSAGE=Your post has been removed for posting too frequently. Please wait before posting again.
+ROLEPLAY_MESSAGE=Your post has been removed. Only one roleplay post is allowed per user.
+
+# Bot Settings
+CHECK_INTERVAL=60
+MAX_POSTS_PER_DAY=3
+DRY_RUN=false
+```
+
+### 4. Test the Bot
+
+```bash
+# Test Reddit connection
+python -m umabot --test
+
+# Run in dry-run mode (won't actually remove posts)
+python -m umabot --dry-run
+
+# Run the bot normally
+python -m umabot
+```
+
+## Usage
+
+### Command Line Options
+
+```bash
+python -m umabot [OPTIONS]
+
+Options:
+  --verbose, -v    Enable verbose logging
+  --dry-run        Run in dry-run mode (don't actually remove posts)
+  --test           Test Reddit connection and exit
+  --help           Show help message
+```
+
+### Adding New Rules
+
+The bot is designed to be modular. To add a new rule:
+
+1. Create a new file in `src/umabot/rules/`
+2. Inherit from the `Rule` base class
+3. Implement the required methods:
+   - `should_remove(submission)`: Return `True` if the post should be removed
+   - `get_removal_message(submission)`: Return the message to post when removing
+
+Example:
+
+```python
+from .base import Rule
+
+class MyCustomRule(Rule):
+    def should_remove(self, submission):
+        # Your logic here
+        return False
+    
+    def get_removal_message(self, submission):
+        return "Your post was removed for violating our custom rule."
+```
+
+4. Add the rule to the bot in `src/umabot/bot.py`:
+
+```python
+from .rules import MyCustomRule
+
+# In the __init__ method:
+self.rules = [
+    SpamDetector(config),
+    RoleplayLimiter(config),
+    MyCustomRule(config)  # Add your new rule
+]
+```
+
+## Deployment
+
+### Render (Recommended)
+
+1. Fork or clone this repository
+2. Connect your repository to Render
+3. Create a new Web Service
+4. Configure the environment variables in Render's dashboard
+5. Deploy!
+
+The `render.yaml` file is included for easy deployment.
+
+### Other Platforms
+
+The bot can be deployed on any platform that supports Python:
+
+- **Railway**: Use the `railway.toml` configuration
+- **Heroku**: Use the `Procfile` and `requirements.txt`
+- **PythonAnywhere**: Upload the code and set environment variables
+- **Google Cloud**: Use Cloud Functions or App Engine
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `REDDIT_CLIENT_ID` | Reddit API client ID | Required |
+| `REDDIT_CLIENT_SECRET` | Reddit API client secret | Required |
+| `REDDIT_USERNAME` | Reddit bot username | Required |
+| `REDDIT_PASSWORD` | Reddit bot password | Required |
+| `REDDIT_USER_AGENT` | User agent string | `UmaBot/0.1.0` |
+| `SUBREDDIT_NAME` | Target subreddit name | Required |
+| `SPAM_MESSAGE` | Message for spam removals | Customizable |
+| `ROLEPLAY_MESSAGE` | Message for roleplay removals | Customizable |
+| `CHECK_INTERVAL` | Seconds between checks | `60` |
+| `MAX_POSTS_PER_DAY` | Max posts per user per day | `3` |
+| `DRY_RUN` | Enable dry-run mode | `false` |
+
+## Development
+
+### Project Structure
+
+```
+src/umabot/
+├── __init__.py          # Main package entry point
+├── __main__.py          # Module entry point
+├── bot.py              # Main bot class
+├── cli.py              # Command-line interface
+├── config.py           # Configuration management
+└── rules/              # Moderation rules
+    ├── __init__.py
+    ├── base.py         # Base rule class
+    ├── spam_detector.py
+    └── roleplay_limiter.py
+```
+
+### Running Tests
+
+```bash
+# Install dev dependencies
+rye sync
+
+# Run tests
+pytest
+
+# Format code
+black src/
+
+# Lint code
+flake8 src/
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## Support
+
+If you encounter any issues:
+
+1. Check the logs in `umabot.log`
+2. Verify your Reddit API credentials
+3. Ensure the bot has moderator permissions in the subreddit
+4. Check that the subreddit name is correct
+
+## Security Notes
+
+- Never commit your `.env` file or Reddit credentials
+- Use environment variables for all sensitive data
+- The bot account should have moderator permissions in the target subreddit
+- Consider using Reddit's OAuth2 flow for production deployments