Updated readme

README.md

@@ -1,29 +1,83 @@
-# titbot
-Title-bot for Jupiter Broadcasting's "The Launch" chat room. Why didn't I just use the old bot?
+# titlebot-ng
+A Matrix chat bot for Jupiter Broadcasting's "The Lunch" chat room that collects and posts title suggestions.
 
-## Usage
-- Create python venv and source it
-- Install matrix-nio, pyyaml, and requests
-- Run 'python3 scraper.py' and 'python3 post_results.py'
-- Configuration:
-  - config.yaml (ignored by git) or environment variables:
-    - TITLEBOT_USERNAME, TITLEBOT_PASSWORD, TITLEBOT_ROOM_ID, TITLEBOT_HOMESERVER
-    - TITLEBOT_LOOKBACK_LIMIT, TITLEBOT_BATCH_SIZE, TITLEBOT_DB_NAME
-  - dbName is optional; if unset, a per-room DB name is derived automatically.
+## Features
+- **Suggestion Collection**: Monitors chat for messages starting with `!suggest`, `!Suggest`, `!suggestion`, `!Suggestion`, `SUGGEST`, or `!sug`
+- **Interactive Voting**: Posts suggestions individually with 👍 reactions for voting
+- **Command System**: 
+  - `!gettitles` - Triggers posting of collected suggestions
+  - `!mayhem` - Generates chaotic text using Ollama AI
+  - `!countvotes` - Counts upvotes on posted suggestions
+- **Persistent Storage**: SQLite database per room with duplicate prevention
+- **Acknowledgment System**: Reacts with ✅ to confirm suggestion collection
+
+## Quick Start
+1. Create and activate a Python virtual environment:
+   ```bash
+   python3 -m venv .env
+   source .env/bin/activate
+   ```
+
+2. Install dependencies:
+   ```bash
+   pip install matrix-nio pyyaml requests
+   ```
+
+3. Configure the bot:
+   ```bash
+   cp config_example.yaml config.yaml
+   # Edit config.yaml with your Matrix credentials and room ID
+   ```
+
+4. Run the bot components:
+   ```bash
+   # Terminal 1: Collect suggestions
+   python3 scraper.py
+   
+   # Terminal 2: Post suggestions when requested
+   python3 post_results.py
+   ```
+
+## Configuration
+Create `config.yaml` based on `config_example.yaml`:
+
+```yaml
+username: "your_bot_username"
+password: "your_bot_password"
+room_id: "!your_room_id:homeserver.com"
+homeserver: "https://matrix.org"  # Optional, defaults to matrix.org
+lookback_limit: 7200  # Seconds to look back for suggestions (2 hours)
+batch_size: 100       # Messages to fetch per batch
+dbName: "suggestions.db"  # Optional, auto-generated if not set
+```
+
+## Architecture
+- **`room.py`**: Core `Room` class handling Matrix connection, database operations, and command processing
+- **`post.py`**: `Post` class representing individual suggestions
+- **`scraper.py`**: Main suggestion collection loop
+- **`post_results.py`**: Suggestion posting service that waits for `!gettitles` commands
+- **`customOllama/`**: Custom Ollama model for mayhem text generation
+
+## Database Schema
+- **suggestions**: Stores collected suggestions with metadata
+- **gettitles/mayhem/countvotes**: Command execution logs to prevent duplicates
+- **last_run/last_post**: Timestamps for state management
+
+## Dependencies
+- **matrix-nio**: Matrix client library
+- **pyyaml**: Configuration file parsing
+- **requests**: HTTP requests for Ollama integration
+- **sqlite3**: Built-in database support
+
+## Optional: Ollama Integration
+For `!mayhem` command functionality:
+1. Install [Ollama](https://ollama.ai/)
+2. Build the custom model: `ollama create mad_cat_man:latest -f customOllama/Modelfile`
+3. Ensure Ollama is running on `localhost:11434`
 
 ## Notes
-- scraper.py and post_results.py are deprecated wrappers around titlebot.py.
-- db.py is deprecated; DB logic lives in room.Room.
-- Do not commit virtualenvs. Remove the tracked .env folder:
-  - git rm -r --cached .env
-  - git commit -m "Remove tracked venv"
-  - .gitignore already ignores `.env/`
-
-## TODO:
-- Re-write in Rust
-- Re-write in Go
-- Re-write in Zig
-
-- Lookback time is being a PITA. Someone who knows what the hell they're doing should do something about that. 
-
-- <s>Current work invovles re-writing the old program as a more OOP based setup. See oop2 branch.</s>
+- Each room gets its own SQLite database for suggestions
+- The bot acknowledges collected suggestions with ✅ reactions
+- Voting uses 👍 reactions on individual suggestion posts
+- Command deduplication prevents spam and duplicate executions
+- Safe database naming handles special characters in room IDs