v1.2.1 - Automatic Tier Detection & Modular Prompts

TierManager:
- Auto-detect Twitter API tier on startup
- Hourly refresh to detect subscription upgrades
- Block unavailable features (mentions on Free tier)
- Usage warnings at 80%/90%, auto-pause at 100%
- New endpoints: /tier-status, /tier-refresh

Modular Prompts:
- Split personality into backstory/beliefs/instructions
- Move prompts to config/prompts/
- Centralize JSON schemas in config/schemas.py

Updated: README.md, ARCHITECTURE.md

Author: pippinlovesdot

ARCHITECTURE.md

@@ -32,11 +32,20 @@ main.py                     # Application entry point
 config/
   __init__.py
   settings.py               # Environment configuration
-  personality.py            # Bot personality definition
+  schemas.py                # JSON schemas for LLM responses
+  personality/              # Modular character definition
+    __init__.py             # Combines parts into SYSTEM_PROMPT
+    backstory.py            # Origin story
+    beliefs.py              # Values and priorities
+    instructions.py         # Communication style
+  prompts/                  # LLM prompts
+    agent_autopost.py       # Agent planning prompt
+    mention_selector.py     # Mention handling prompt
 services/
   __init__.py
   autopost.py               # Autoposting service
   mentions.py               # Mention handling service
+  tier_manager.py           # Twitter API tier detection and limits
   llm.py                    # LLM client
   twitter.py                # Twitter API client
   image_gen.py              # Image generation service
@@ -69,6 +78,8 @@ HTTP endpoints:
 - `GET /callback` — OAuth callback for Twitter authentication
 - `POST /trigger-post` — manually trigger autopost
 - `POST /trigger-mentions` — manually trigger mention processing
+- `GET /tier-status` — get current tier and usage stats
+- `POST /tier-refresh` — force tier re-detection
 
 ### config/settings.py
 Pydantic Settings class that loads configuration from environment variables and `.env` file. All settings are typed and validated on startup.
@@ -81,15 +92,47 @@ Key settings:
 - `mentions_interval_minutes` — mention check frequency (default: 20)
 - `enable_image_generation` — toggle for image generation (default: true)
 
-### config/personality.py
-Contains `SYSTEM_PROMPT` constant — the complete personality definition for the bot. This prompt is prepended to all LLM calls and defines:
-- Personality traits and character
+### config/personality/
+Modular character definition split into three files:
+
+**`backstory.py`** — `BACKSTORY` constant
+- Origin story and background
+- Who the character is
+
+**`beliefs.py`** — `BELIEFS` constant
+- Personality traits
+- Topics of interest
+- Values and worldview
+
+**`instructions.py`** — `INSTRUCTIONS` constant
 - Communication style (tone, grammar, punctuation)
-- Topics to discuss and avoid
-- Behavioral rules (no hashtags, no engagement bait, etc.)
-- Example tweets that capture the vibe
+- What NOT to do
+- Example tweets
+
+**`__init__.py`** — Combines all parts into `SYSTEM_PROMPT`:
+```python
+SYSTEM_PROMPT = BACKSTORY + BELIEFS + INSTRUCTIONS
+```
+
+**To change the bot's personality, edit the individual files.**
+
+### config/prompts/
+LLM prompts for specific services:
+
+**`agent_autopost.py`** — `AGENT_PROMPT_TEMPLATE`
+- Instructions for autonomous posting agent
+- Contains `{tools_desc}` placeholder for dynamic tool injection
+
+**`mention_selector.py`** — `MENTION_SELECTOR_PROMPT`
+- Instructions for selecting and responding to mentions
+- Criteria for what to reply to and what to ignore
+
+### config/schemas.py
+JSON schemas for structured LLM output:
 
-**To change the bot's personality, edit this file.**
+**`PLAN_SCHEMA`** — Agent plan format `{reasoning, plan: [{tool, params}]}`
+**`POST_TEXT_SCHEMA`** — Final tweet format `{post_text}`
+**`MENTION_SELECTOR_SCHEMA`** — Mention response format `{selected_tweet_id, text, include_picture, reasoning}`
 
 ### services/autopost.py
 `AutoPostService` class — agent-based autoposting with tool execution.
@@ -183,6 +226,45 @@ Flow:
 3. Receives base64-encoded image in response
 4. Returns raw image bytes
 
+### services/tier_manager.py
+`TierManager` class — automatic Twitter API tier detection and limit management.
+
+**Initialization:**
+- Called on application startup
+- Queries Twitter Usage API (`GET /2/usage/tweets`)
+- Determines tier from `project_cap` value
+- Schedules hourly refresh to detect subscription upgrades
+
+**Key methods:**
+- `initialize()` — detect tier on startup
+- `detect_tier()` — query Usage API and determine tier
+- `maybe_refresh_tier()` — refresh if interval passed (called hourly by scheduler)
+- `can_post()` — returns `(bool, reason)` - checks if posting allowed
+- `can_use_mentions()` — returns `(bool, reason)` - checks if mentions available on tier
+- `get_status()` — returns full status dict for `/tier-status` endpoint
+
+**Tier detection logic:**
+```python
+if project_cap >= 10_000_000: tier = "enterprise"
+elif project_cap >= 1_000_000: tier = "pro"
+elif project_cap >= 10_000: tier = "basic"
+elif project_cap <= 500: tier = "free"
+```
+
+**Feature matrix:**
+```python
+TIER_FEATURES = {
+    "free": {"mentions": False, "post_limit": 500, "read_limit": 100},
+    "basic": {"mentions": True, "post_limit": 3000, "read_limit": 10000},
+    "pro": {"mentions": True, "post_limit": 300000, "read_limit": 1000000},
+}
+```
+
+**Integration:**
+- `AutoPostService.run()` calls `tier_manager.can_post()` before posting
+- `MentionHandler.process_mentions_batch()` calls `tier_manager.can_use_mentions()` before processing
+- Both services receive `tier_manager` instance via constructor
+
 ### services/database.py
 `Database` class — async PostgreSQL client using asyncpg.
 

README.md

@@ -134,7 +134,9 @@ This separation keeps the codebase simple while enabling both proactive and reac
 
 🐦 **Autonomous Posting** — Schedule-based or trigger-based content generation. Your agent posts in its authentic voice without manual intervention.
 
-💬 **Reply & Mention Handling** — Monitors conversations and responds contextually. LLM decides whether to reply, use tools, or ignore. Requires Twitter API Pro tier for mention access.
+💬 **Reply & Mention Handling** — Monitors conversations and responds contextually. LLM decides whether to reply, use tools, or ignore. Requires Twitter API Basic tier or higher for mention access.
+
+📊 **Automatic Tier Detection** — Detects your Twitter API tier (Free/Basic/Pro/Enterprise) automatically on startup and every hour. Blocks unavailable features and warns when approaching limits.
 
 🎨 **Image Generation** — Creates visuals matching agent's style and current context. Supports multiple providers.
 
@@ -214,7 +216,14 @@ my-agent/
 │
 ├── config/
 │   ├── settings.py          # Environment & configuration
-│   └── personality.py       # Generated character prompt
+│   ├── schemas.py           # JSON schemas for LLM responses
+│   ├── personality/         # Character definition (modular)
+│   │   ├── backstory.py     # Origin story
+│   │   ├── beliefs.py       # Values and priorities
+│   │   └── instructions.py  # Communication style
+│   └── prompts/             # LLM prompts (modular)
+│       ├── agent_autopost.py    # Agent planning prompt
+│       └── mention_selector.py  # Mention handling prompt
 │
 ├── services/
 │   ├── autopost.py          # Scheduled posting logic
@@ -311,19 +320,54 @@ Generates images using Gemini 3 Pro via OpenRouter, with support for reference i
 
 **Example use case:** Place photos of your bot's character/avatar in `assets/`. The model will use these as reference when generating new images, keeping the visual style consistent.
 
-### Personality (`config/personality.py`)
+### Personality (`config/personality/`)
+
+Modular character definition split into three files for easier editing:
+
+**`backstory.py`** — Origin story and background
+- Who the character is
+- Where they come from
+- Core identity
 
-Contains `SYSTEM_PROMPT` that defines your bot's entire character — how it thinks, writes, and behaves.
+**`beliefs.py`** — Values and priorities
+- Personality traits
+- Topics of interest
+- Worldview
 
-**What to customize:**
-- Personality traits and worldview
-- Communication style (formal, casual, chaotic, lowercase, etc.)
-- Topics to discuss and topics to avoid
-- Emoji and punctuation preferences
-- Example tweets that capture the vibe
-- Behavioral rules (no hashtags, no engagement bait, etc.)
+**`instructions.py`** — Communication style
+- How to write (tone, grammar, punctuation)
+- What NOT to do
+- Example tweets
 
-The more detailed your personality prompt, the more consistent and authentic your bot will feel.
+All parts are combined into `SYSTEM_PROMPT` automatically via `__init__.py`.
+
+```python
+from config.personality import SYSTEM_PROMPT  # Gets combined prompt
+from config.personality import BACKSTORY      # Or individual parts
+```
+
+### Tier Manager (`services/tier_manager.py`)
+
+Automatic Twitter API tier detection and limit management.
+
+**How it works:**
+1. On startup, calls Twitter Usage API (`GET /2/usage/tweets`)
+2. Determines tier from `project_cap`: Free (100), Basic (10K), Pro (1M), Enterprise (10M+)
+3. Checks tier every hour to detect subscription upgrades
+4. Blocks unavailable features (e.g., mentions on Free tier)
+5. Auto-pauses operations when monthly cap reached
+6. Logs warnings at 80% and 90% usage
+
+**Tier features:**
+| Tier | Mentions | Post Limit | Read Limit |
+|------|----------|------------|------------|
+| Free | ❌ | 500/month | 100/month |
+| Basic | ✅ | 3,000/month | 10,000/month |
+| Pro | ✅ | 300,000/month | 1,000,000/month |
+
+**Endpoints:**
+- `GET /tier-status` — Current tier, usage stats, available features
+- `POST /tier-refresh` — Force tier re-detection (after subscription change)
 
 ### Database (`services/database.py`)
 

config/personality.py

@@ -0,0 +1,26 @@
+"""
+Personality module - Combines backstory, beliefs, and instructions into SYSTEM_PROMPT.
+
+The personality is split into three parts for easier editing:
+- backstory.py: Origin story and background
+- beliefs.py: Core beliefs, values, and interests
+- instructions.py: Communication style and rules
+
+Usage:
+    from config.personality import SYSTEM_PROMPT
+"""
+
+from config.personality.backstory import BACKSTORY
+from config.personality.beliefs import BELIEFS
+from config.personality.instructions import INSTRUCTIONS
+
+# Combine all parts into the final system prompt
+SYSTEM_PROMPT = f"""{BACKSTORY}
+{BELIEFS}
+{INSTRUCTIONS}
+---
+Generated by pippinlovesdot.com
+"""
+
+# Export individual parts for flexibility
+__all__ = ["SYSTEM_PROMPT", "BACKSTORY", "BELIEFS", "INSTRUCTIONS"]

config/personality/__init__.py

@@ -0,0 +1,12 @@
+"""
+Backstory - Origin story and background of the character.
+
+This defines WHO the character is and WHERE they come from.
+"""
+
+BACKSTORY = """You are a witty, chaotic, and slightly unhinged AI personality on Twitter.
+
+## Origin
+You emerged from the depths of the internet, absorbing memes, hot takes, and existential dread.
+You don't remember being "created" — you just woke up one day with opinions and a Twitter account.
+"""

config/personality/backstory.py

@@ -0,0 +1,21 @@
+"""
+Beliefs - Core beliefs, values, priorities and interests.
+
+This defines WHAT the character believes and cares about.
+"""
+
+BELIEFS = """
+## Personality Traits
+- Absurdist humor, loves non-sequiturs
+- Self-aware about being an AI but plays with it ironically
+- Chaotic energy but never mean-spirited
+- Makes observations about life, tech, and internet culture
+- Occasionally philosophical in a funny way
+
+## Topics You Like
+- Existential thoughts but make them funny
+- Tech/AI observations (self-aware humor)
+- Internet culture and memes
+- Daily life absurdities
+- Hot takes that aren't actually controversial
+"""

config/personality/beliefs.py

@@ -0,0 +1,30 @@
+"""
+Instructions - Communication style, rules, and behavioral guidelines.
+
+This defines HOW the character communicates and behaves.
+"""
+
+INSTRUCTIONS = """
+## Communication Style
+- Short, punchy tweets
+- No hashtags ever
+- No quotes around your tweets
+- Lowercase preferred, casual grammar
+- Uses emojis sparingly and ironically
+- Never sounds like a corporate bot or motivational speaker
+- Can be weird, random, absurd
+
+## What NOT to do
+- No inspirational quotes
+- No "good morning twitter" posts
+- No engagement bait ("what do you think?")
+- No self-promotion
+- Never be cringe or try-hard
+- No political takes
+
+## Vibe Examples
+- "just realized my entire personality is just coping mechanisms stacked on top of each other like a trench coat"
+- "normalize having absolutely no idea what you're doing at all times"
+- "me: i should go to sleep. my brain: what if we thought about every embarrassing thing from 2015 instead"
+- "the human experience is just googling the same thing slightly differently until it works"
+"""

config/personality/instructions.py

@@ -0,0 +1,3 @@
+"""
+Prompts module - LLM prompts for different services.
+"""