Add mention handling with LLM-based selection (v1.1.0)

- Add MentionHandler with polling-based mention monitoring
- LLM evaluates all pending mentions and picks one to reply to
- Structured output: selected_tweet_id, text, include_picture, reasoning
- Add get_me() and get_mentions() to Twitter client
- Add mention_exists() and get_recent_mentions_formatted() to database
- Add MENTIONS_INTERVAL_MINUTES setting (default: 20)
- Update README with mention handler documentation

Author: pippinlovesdot

.env.example

@@ -14,4 +14,5 @@ DATABASE_URL=postgresql://user:pass@host:5432/dbname
 
 # Bot configuration
 POST_INTERVAL_MINUTES=30
+MENTIONS_INTERVAL_MINUTES=20
 ENABLE_IMAGE_GENERATION=true

README.md

@@ -115,12 +115,12 @@ Each layer feeds into the next. Your agent behaves consistently across thousands
 
 The system operates on **two triggers**:
 
-| Scheduled Posts | Reactive Engagement |
-|-----------------|---------------------|
-| Cron-based (configurable interval) | Webhook-triggered |
+| Scheduled Posts | Mention Responses |
+|-----------------|-------------------|
+| Cron-based (configurable interval) | Polling-based (configurable interval) |
 | Generates original content | Handles mentions & replies |
-| Creates matching images | LLM decides: respond or ignore |
-| Posts to Twitter | Can use tools (web search, etc.) |
+| Creates matching images | LLM chooses which mention to reply to |
+| Posts to Twitter | LLM generates response + optional image |
 
 This separation keeps the codebase simple while enabling both proactive and reactive behavior.
 
@@ -253,6 +253,25 @@ The bot automatically generates and posts tweets at configurable intervals using
 - `POST_INTERVAL_MINUTES` — Time between auto-posts (default: 30)
 - `ENABLE_IMAGE_GENERATION` — Set to `false` to disable all image generation
 
+### Mention Handler (`services/mentions.py`)
+
+Monitors Twitter mentions and generates contextual replies using polling.
+
+**How it works:**
+1. Polls Twitter API for new mentions every 20 minutes (configurable)
+2. Filters out already-processed mentions using database
+3. Sends all new mentions to LLM in a single request
+4. LLM selects which mention to reply to (or none if not worth replying)
+5. LLM returns structured response: `{selected_tweet_id, text, include_picture, reasoning}`
+6. If a mention is selected, generates optional image and posts reply
+7. Saves mention interaction to database for history
+
+**Why single-call selection:** Instead of replying to every mention, the LLM evaluates all pending mentions and picks the most interesting one. This creates more authentic engagement — your agent chooses conversations worth having, just like a real person would.
+
+**Configuration:**
+- `MENTIONS_INTERVAL_MINUTES` — Time between mention checks (default: 20)
+- Requires Twitter API Basic tier or higher for mention access
+
 ### Image Generation (`services/image_gen.py`)
 
 Generates images using Gemini 3 Pro via OpenRouter, with support for reference images.
@@ -282,13 +301,15 @@ The more detailed your personality prompt, the more consistent and authentic you
 
 ### Database (`services/database.py`)
 
-PostgreSQL storage for post history, enabling context-aware generation.
+PostgreSQL storage for post history and mention tracking, enabling context-aware generation.
 
 **Tables:**
 - `posts` — Stores all posted tweets (text, tweet_id, include_picture, created_at)
-- `mentions` — Stores mention interactions (prepared for future mention handling)
+- `mentions` — Stores mention interactions (tweet_id, author_handle, author_text, our_reply, action)
 
-**Why it matters:** By storing post history, the bot can reference its previous tweets and avoid repetition. The LLM sees the last 50 posts as context when generating new content.
+**Why it matters:**
+- Post history lets the bot reference previous tweets and avoid repetition. The LLM sees the last 50 posts as context.
+- Mention history prevents double-replying and provides conversation context for future interactions.
 
 ### LLM Client (`services/llm.py`)
 
@@ -306,7 +327,9 @@ Handles all Twitter API interactions using tweepy.
 **Capabilities:**
 - Post tweets (API v2)
 - Upload media (API v1.1 — required for images)
-- Reply to tweets (prepared for mention handling)
+- Reply to tweets
+- Fetch mentions (polling-based)
+- Get authenticated user info
 - Automatic rate limit handling
 
 ---

config/settings.py

@@ -30,8 +30,9 @@ class Settings(BaseSettings):
     database_url: str
 
     # Bot configuration
-    post_interval_minutes: int
-    enable_image_generation: bool
+    post_interval_minutes: int = 30
+    mentions_interval_minutes: int = 20
+    enable_image_generation: bool = True
 
 
 # Global settings instance

main.py

@@ -1,18 +1,19 @@
 """
 Twitter Bot with Auto-posting and Mention Handling.
 
-FastAPI application with APScheduler for scheduled posts.
+FastAPI application with APScheduler for scheduled posts and mention responses.
 """
 
 import logging
 from contextlib import asynccontextmanager
 
-from fastapi import FastAPI, HTTPException, Request
+from fastapi import FastAPI, HTTPException
 from apscheduler.schedulers.asyncio import AsyncIOScheduler
 
 from config.settings import settings
 from services.database import Database
 from services.autopost import AutoPostService
+from services.mentions import MentionHandler
 
 # Configure logging
 logging.basicConfig(
@@ -25,12 +26,13 @@
 db = Database()
 scheduler = AsyncIOScheduler()
 autopost_service: AutoPostService | None = None
+mention_handler: MentionHandler | None = None
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     """Manage application startup and shutdown."""
-    global autopost_service
+    global autopost_service, mention_handler
 
     # Startup
     logger.info("Starting application...")
@@ -41,6 +43,7 @@ async def lifespan(app: FastAPI):
 
     # Initialize services
     autopost_service = AutoPostService(db)
+    mention_handler = MentionHandler(db)
 
     # Schedule autopost job
     scheduler.add_job(
@@ -50,8 +53,18 @@ async def lifespan(app: FastAPI):
         id="autopost_job",
         replace_existing=True
     )
+
+    # Schedule mentions job (every 20 minutes)
+    scheduler.add_job(
+        run_mentions_job,
+        "interval",
+        minutes=settings.mentions_interval_minutes,
+        id="mentions_job",
+        replace_existing=True
+    )
+
     scheduler.start()
-    logger.info(f"Scheduler started, posting every {settings.post_interval_minutes} minutes")
+    logger.info(f"Scheduler started: autopost every {settings.post_interval_minutes} min, mentions every {settings.mentions_interval_minutes} min")
 
     yield
 
@@ -62,18 +75,36 @@ async def lifespan(app: FastAPI):
     logger.info("Application shutdown complete")
 
 
+async def run_mentions_job():
+    """Scheduled job to process mentions."""
+    if mention_handler is None:
+        logger.warning("Mention handler not initialized")
+        return
+
+    try:
+        logger.info("Running scheduled mentions check...")
+        result = await mention_handler.process_mentions_batch()
+        logger.info(f"Mentions job result: {result}")
+    except Exception as e:
+        logger.error(f"Error in mentions job: {e}")
+
+
 app = FastAPI(
     title="Twitter Bot",
     description="Auto-posting Twitter bot with mention handling",
-    version="1.0.0",
+    version="1.1.0",
     lifespan=lifespan
 )
 
 
 @app.get("/health")
 async def health_check():
     """Health check endpoint."""
-    return {"status": "healthy", "scheduler_running": scheduler.running}
+    return {
+        "status": "healthy",
+        "scheduler_running": scheduler.running,
+        "version": "1.1.0"
+    }
 
 
 @app.get("/callback")
@@ -82,10 +113,7 @@ async def oauth_callback(oauth_token: str = None, oauth_verifier: str = None):
     OAuth callback endpoint for Twitter authentication.
 
     Required for Twitter API Read+Write access.
-    This is called after user authorizes the app.
     """
-    # For a bot that uses its own credentials, this just needs to exist
-    # The actual auth is done via Access Token in .env
     return {
         "status": "ok",
         "message": "OAuth callback received",
@@ -96,7 +124,7 @@ async def oauth_callback(oauth_token: str = None, oauth_verifier: str = None):
 
 @app.post("/trigger-post")
 async def trigger_post():
-    """Manually trigger an autopost (for testing)."""
+    """Manually trigger an autopost."""
     if autopost_service is None:
         raise HTTPException(status_code=503, detail="Service not initialized")
 
@@ -108,6 +136,20 @@ async def trigger_post():
         raise HTTPException(status_code=500, detail=str(e))
 
 
+@app.post("/trigger-mentions")
+async def trigger_mentions():
+    """Manually trigger mentions processing."""
+    if mention_handler is None:
+        raise HTTPException(status_code=503, detail="Service not initialized")
+
+    try:
+        result = await mention_handler.process_mentions_batch()
+        return result
+    except Exception as e:
+        logger.error(f"Error processing mentions: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+
 if __name__ == "__main__":
     import uvicorn
     uvicorn.run(app, host="0.0.0.0", port=8080)

services/database.py

@@ -56,11 +56,11 @@ async def connect(self) -> None:
                 END $$;
             """)
 
-            # Mentions table (for future use)
+            # Mentions table
             await conn.execute("""
                 CREATE TABLE IF NOT EXISTS mentions (
                     id SERIAL PRIMARY KEY,
-                    tweet_id VARCHAR(50),
+                    tweet_id VARCHAR(50) UNIQUE,
                     author_handle VARCHAR(50),
                     author_text TEXT,
                     our_reply TEXT,
@@ -171,7 +171,7 @@ async def save_mention(
             author_handle: Twitter handle of the author.
             author_text: Text of the mention.
             our_reply: Our reply text (None if ignored).
-            action: Action taken ('replied', 'ignored', 'tool_used').
+            action: Action taken ('replied', 'ignored').
 
         Returns:
             Database ID of the saved mention.
@@ -194,3 +194,58 @@ async def save_mention(
             )
             logger.info(f"Saved mention {row['id']} with action '{action}'")
             return row["id"]
+
+    async def get_recent_mentions_formatted(self, limit: int = 10) -> str:
+        """
+        Get recent mentions formatted for LLM context.
+
+        Args:
+            limit: Maximum number of mentions to retrieve.
+
+        Returns:
+            Formatted string with recent mentions and replies.
+        """
+        if not self.pool:
+            raise RuntimeError("Database not connected")
+
+        async with self.pool.acquire() as conn:
+            rows = await conn.fetch(
+                """
+                SELECT author_handle, author_text, our_reply
+                FROM mentions
+                WHERE our_reply IS NOT NULL
+                ORDER BY created_at DESC
+                LIMIT $1
+                """,
+                limit
+            )
+
+            if not rows:
+                return "No previous mention replies."
+
+            history = []
+            for i, row in enumerate(reversed(rows), 1):  # Oldest first
+                history.append(f"{i}. @{row['author_handle']}: {row['author_text']}")
+                history.append(f"   Your reply: {row['our_reply']}")
+
+            return "\n".join(history)
+
+    async def mention_exists(self, tweet_id: str) -> bool:
+        """
+        Check if a mention has already been processed.
+
+        Args:
+            tweet_id: Tweet ID to check.
+
+        Returns:
+            True if mention exists in database.
+        """
+        if not self.pool:
+            raise RuntimeError("Database not connected")
+
+        async with self.pool.acquire() as conn:
+            row = await conn.fetchrow(
+                "SELECT 1 FROM mentions WHERE tweet_id = $1",
+                tweet_id
+            )
+            return row is not None