A modern IRC bot that monitors conversations across multiple servers, automatically detects 5 and 7 syllable phrases, and generates random haiku (5-7-5 format). Features a beautiful React-based web interface for browsing, voting, and statistics.
- 🤖 Multi-Server IRC Support - Connect to multiple IRC servers simultaneously
- 🎭 Auto-Collection - Passively monitors messages and collects 5/7 syllable phrases
- ✍️ Manual Submission - Authorized editors can submit lines with placement preferences
- 🎲 Smart Generation - Placement-aware algorithm for better narrative flow
- 🌐 Modern Web Interface - Browse, filter, and vote on haikus
- 📊 Statistics Dashboard - Track contributions and popular haikus
- 🔴 Live Feed - Real-time WebSocket updates when new haikus are generated
- 🗳️ Voting System - Community-driven haiku ranking
- 🔒 Privacy Options - Opt-out of auto-collection (stealth feature)
Backend:
- Python 3.11+
- FastAPI (web framework)
- SQLAlchemy (ORM)
- pydle (IRC client)
- pyphen + syllables (syllable counting)
- SQLite (database)
Frontend:
- React 18
- Vite (build tool)
- TailwindCSS (styling)
- React Query (data fetching)
- WebSocket (real-time updates)
- Python 3.11 or higher
- Node.js 18 or higher
- Git
- Clone the repository:
git clone https://github.com/Xafloc/HaikuBot-Python.git
cd HaikuBot-Python- Set up Python environment:
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
pip install -r requirements.txt- Configure the bot:
cp config.yaml.example config.yaml
# Edit config.yaml with your IRC servers, channels, and settings- Initialize the database:
python -m backend.main --config config.yaml
# The database will be created automatically on first run- Set up the frontend (for development):
cd frontend
npm install
npm run dev # Runs on http://localhost:5173- Run the bot:
# In the project root, with venv activated:
python -m backend.mainThe bot will:
- Connect to all configured IRC servers
- Start the web API on http://localhost:8000
- Begin monitoring channels and collecting lines
Edit config.yaml to customize:
database:
path: "./haiku.db"
bot:
owner: "YourNickname" # Your IRC nickname (admin access)
web_url: "http://localhost:8000"
trigger_prefix: "!"
servers:
- name: "libera"
host: "irc.libera.chat"
port: 6697
ssl: true
nick: "HaikuBot"
password: "" # Optional
channels: ["#haiku", "#bots"]
features:
auto_collect: true
allow_manual_submission: true
web:
host: "0.0.0.0"
port: 8000!haiku- Generate random haiku!haiku @username- Generate using specific user's lines!haiku #channel- Generate from specific channel's lines!haikustats- Show bot statistics!haikuvote <id>- Upvote a generated haiku!haikutop- Show top voted haikus!myhaiku- Show your contributed lines!mystats- Show your statistics!haikuhelp- Display help
!haiku5 <text>- Submit 5-syllable line!haiku5 --first <text>- Submit 5-syllable line (first position only)!haiku5 --last <text>- Submit 5-syllable line (last position only)!haiku7 <text>- Submit 7-syllable line
!haiku promote @username- Grant editor privileges!haiku demote @username- Revoke editor privileges!haiku editors- List all editors
!haiku optout- Opt out of auto-collection!haiku optin- Opt back into auto-collection
Access the web interface at http://localhost:8000
Pages:
- Home - Live feed and recent haikus with generation button
- Browse - Filter and paginate through all haikus
- Statistics - Global stats and contributor leaderboard
- User Profile - View individual user contributions
The REST API is available at http://localhost:8000/api
Visit http://localhost:8000/docs for interactive API documentation (Swagger UI).
GET /api/haikus- List haikus (with filters)GET /api/haikus/{id}- Get specific haikuPOST /api/haikus/generate- Generate new haikuPOST /api/haikus/{id}/vote- Vote for haikuGET /api/stats- Global statisticsGET /api/leaderboard- Top contributorsGET /api/users/{username}/stats- User statisticsWS /ws/live- WebSocket live feed
cd frontend
npm run buildThe built files will be in frontend/dist/ and will be served automatically by FastAPI.
- Copy the service file:
sudo cp systemd/haikubot.service /etc/systemd/system/- Edit the service file with your paths:
sudo nano /etc/systemd/system/haikubot.service- Enable and start:
sudo systemctl enable haikubot
sudo systemctl start haikubot
sudo systemctl status haikubot- View logs:
sudo journalctl -u haikubot -f# Build image
docker build -t haikubot .
# Run container
docker run -d \
-p 8000:8000 \
-v $(pwd)/config.yaml:/app/config.yaml \
-v $(pwd)/haiku.db:/app/haiku.db \
--name haikubot \
haikubot# Backend tests
pytest backend/tests/
# Frontend tests (if configured)
cd frontend
npm test# Python
black backend/
flake8 backend/
# JavaScript
cd frontend
npm run lintIf you have an existing Perl-based HaikuBot database:
- The new schema is compatible with the old one
- You may need to add new columns (server, channel, source, placement)
- A migration script can be created to import old data
Bot won't connect to IRC:
- Check SSL settings in config.yaml
- Verify firewall allows outbound connections on IRC ports
- Ensure nick isn't already taken
Syllable counting inaccurate:
- The syllable counter uses pyphen + syllables libraries
- Some words (proper nouns, acronyms) may be miscounted
- Consider adding manual corrections for common issues
WebSocket not working:
- Check CORS settings in config.yaml
- Verify firewall allows WebSocket connections
- Check browser console for errors
No haikus generating:
- Ensure database has enough lines (need 5-syl and 7-syl)
- Check logs for errors
- Verify IRC channels have activity
Contributions welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
[License TBD]
- Original Perl Bot: Xafloc
- Python Rewrite: 2025
- Haiku Format: 5-7-5 syllable structure from Japanese poetry tradition
- Project Documentation
- AI Assistant Context
- IRC: Connect to see it in action!
Built with ❤️ and Python