Universal Image Generation Prompt

v1.4.2 - Universal Image Generation Prompt

Image Generation Prompt Update

Updated the image generation system prompt to be universal and work with any character:

Key changes:

• Prompt now uses generic "Your character" reference
• Removed fixed character size requirement (8-15% of frame)
• Works with any reference images from assets/ folder
• More flexible for different bot personalities

Files Changed

Updated:

• tools/legacy/image_generation.py — New universal IMAGE_SYSTEM_PROMPT

Feature Toggles & Personality Extensions

v1.4.1 - Feature Toggles & Personality Extensions

Feature Toggles

Settings now actually control feature availability:

Setting	Effect
ENABLE_IMAGE_GENERATION=false	Hides generate_image tool and include_image param from agent
ALLOW_MENTIONS=false	Hides get_mentions and create_reply tools from agent

When disabled, these features are completely hidden from the LLM — no tools, no params in schema.

Personality Extensions

New optional personality files:

• config/personality/sample_tweets.py — previous tweets to avoid repetition
• config/personality/never_say.py — topics/content to never mention

These are empty by default. Populate SAMPLE_TWEETS_LIST and NEVER_SAY_CONTENT to use.

Files Changed

Created:

• config/personality/sample_tweets.py
• config/personality/never_say.py

Updated:

• tools/registry.py — filter tools/params by feature toggles
• services/tier_manager.py — check allow_mentions setting
• tools/legacy/image_generation.py — check enable_image_generation
• config/personality/__init__.py — include new personality parts
• config/settings.py — add allow_mentions
• .env.example — add ALLOW_MENTIONS

Unified Agent Architecture

v1.4.0 - Unified Agent Architecture

Overview

The bot now supports two operation modes:

Mode	USE_UNIFIED_AGENT	Description
Legacy	false	Separate autopost + mentions schedulers (v1.3.x behavior)
Unified	true (default)	Single autonomous agent that handles everything

---

Unified Agent (services/unified_agent.py)

A single agent that runs periodically and decides what to do each cycle. It sees recent posts, replies, pending mentions, and rate limits — then chooses actions accordingly.

Agent Loop

1. Build Context — Load recent actions, rate limits, current tier
2. Agent Loop (max 30 iterations):
   • LLM decides next action: {thinking, tool, params}
   • Execute the chosen tool
   • Add tool result to conversation
   • Repeat until finish_cycle is called
3. Return Summary — posts, replies, iterations, duration

Available Tools

Tool	Description	Tier
get_mentions	Fetch unread Twitter mentions	Basic+
create_post	Post tweet with optional image	All
create_reply	Reply to a mention with optional image	Basic+
web_search	Search web for current information	All
get_twitter_profile	Get user's bio, followers, tweet count	All
get_conversation_history	Get past conversation with a user	All
finish_cycle	End the current agent cycle	All

---

Folder-Based Tool System

Tools reorganized into three folders:

tools/
├── registry.py              # Auto-discovery engine
├── shared/                  # Available in BOTH modes
│   ├── web_search.py
│   ├── get_twitter_profile.py
│   └── get_conversation_history.py
├── legacy/                  # Only for legacy mode
│   └── image_generation.py
└── unified/                 # Only for unified agent
    ├── create_post.py
    ├── create_reply.py
    ├── get_mentions.py
    └── finish_cycle.py

Each tool exports TOOL_CONFIG with name, description, params, tier. The description field is automatically injected into agent prompts.

Registry functions:

• get_tools_for_mode(mode, tier) — Get tools filtered by mode and tier
• get_tools_description_for_mode(mode, tier) — Generate tool descriptions for prompts
• get_tool_func(name) — Get tool function by name

---

Step-by-Step LLM Reactions (Legacy Mode)

Improvement for legacy mode: autopost.py and mentions.py now call the LLM after each tool execution. The agent reflects on the tool result before proceeding to the next step. This creates richer context for the final post/reply generation.

New schema: TOOL_REACTION_SCHEMA in config/schemas.py.

---

Database: Actions Table

Unified tracking of posts AND replies:

• action_type — 'post' or 'reply'
• text, tweet_id, include_picture
• reply_to_tweet_id, reply_to_author (for replies)

New methods:

• get_recent_actions_formatted(limit)
• save_action(...)
• count_actions_today(action_type)
• get_user_actions_history(author)

---

New Endpoint

POST /trigger-agent — Manually trigger a unified agent cycle.

---

Configuration

Variable	Default	Description
USE_UNIFIED_AGENT	true	Enable unified agent mode
AGENT_INTERVAL_MINUTES	30	Minutes between agent cycles

Daily post/reply limits are now tier-based (automatic):

Tier	Posts/day	Replies/day
Free	15	0
Basic	50	50
Pro	500	500

---

Files Changed

Created:

• services/unified_agent.py
• config/prompts/unified_agent.py
• tools/shared/* (3 files)
• tools/legacy/* (1 file)
• tools/unified/* (4 files)

Updated:

• tools/registry.py — Complete rewrite
• services/database.py — Actions table + methods
• services/twitter.py — Added get_user_profile()
• services/autopost.py — Step-by-step LLM reactions
• services/mentions.py — Step-by-step LLM reactions
• config/settings.py — 4 new settings
• config/schemas.py — Added TOOL_REACTION_SCHEMA
• main.py — Mode switching + /trigger-agent

Deleted:

• tools/web_search.py → tools/shared/
• tools/image_generation.py → tools/legacy/
• services/image_gen.py — Dead code

Improved Logging & Error Handling

v1.3.2 - Improved Logging & Error Handling

What's New

Plan Validation in Mentions (services/mentions.py)

Added _validate_plan() method to mention handler (previously only in autopost):

• Max 3 tools per plan
• generate_image must be last
• Only known tools allowed
• Invalid plans are rejected with clear error message

Improved Logging

Clearer, more structured log output for better observability:

Autopost logs:

[AUTOPOST] === Starting ===
[AUTOPOST] [1/5] Loading context - 50 posts loaded
[AUTOPOST] [2/5] Plan: 2 tools (web_search -> generate_image)
[AUTOPOST] [3/5] web_search: OK (3 sources)
[AUTOPOST] [4/5] Tweet: "Hello world..." (142 chars)
[AUTOPOST] === Completed in 8.4s ===

Mentions logs:

[MENTIONS] === Starting batch processing ===
[MENTIONS] [1/4] Found 5 mentions, Unprocessed: 2
[MENTIONS] [2/4] Selected 1 mentions for reply
[MENTIONS] @username: Plan: 1 tools (web_search)
[MENTIONS] @username: Reply posted!
[MENTIONS] === Completed in 12.1s ===

Key improvements:

• Step numbers [1/5], [2/5] show progress
• Tool execution status: OK or FAILED
• Duration tracking for performance monitoring
• Summary at end with key metrics

Graceful Error Handling in Tools

tools/web_search.py:

• Returns {"error": True, "content": "..."} on failure instead of raising
• Handles timeout, HTTP errors, and unexpected exceptions
• Agent receives error message and can continue

tools/image_generation.py:

• Returns None on failure instead of raising
• Handles timeout, HTTP errors, and unexpected exceptions
• Post/reply continues without image if generation fails

Files Changed

• services/mentions.py — Added _validate_plan(), improved logging
• services/autopost.py — Improved logging with step progress
• tools/web_search.py — Graceful error handling
• tools/image_generation.py — Graceful error handling, returns None on error
• main.py — Version bump to 1.3.2

Deployment Documentation

v1.3.1 - Deployment Documentation

What's New

Dockerfile

Added universal Dockerfile for container deployments:

• Python 3.11 slim base image
• Production-ready with --no-cache-dir pip install
• Exposes port 8080
• Works with Railway, Render, VPS, and any Docker host

Deployment Guides (docs/)

Comprehensive deployment documentation for multiple platforms:

docs/deployment.md — General requirements

• System requirements (Python 3.11+, PostgreSQL)
• Environment variables reference
• Database schema overview
• Twitter API tier comparison

docs/railway.md — Railway deployment guide

• Step-by-step from fork to deployment
• PostgreSQL addon setup
• Environment variables configuration
• Useful endpoints and troubleshooting

docs/render.md — Render deployment guide

• PostgreSQL database setup
• Web service configuration
• Preventing service sleep (ping services)
• Cost comparison

docs/vps.md — VPS deployment guide

• Server setup for Ubuntu 22.04+
• PostgreSQL installation and configuration
• Systemd service for auto-restart
• Nginx reverse proxy with SSL
• Docker alternative instructions

docs/api-keys.md — API keys guide

• Twitter Developer Portal walkthrough
• OpenRouter account and credits setup
• PostgreSQL options (Railway, Supabase, Neon, self-hosted)
• Security best practices

Agent-Based Mentions & Auto-Discovery Tools

v1.3.0 - Agent-Based Mentions & Auto-Discovery Tools

What's New

Agent-Based Mention Handling (services/mentions.py)

Complete rewrite of mention handling using autonomous agent architecture with 3 LLM calls per mention.

Agent Flow:

1. LLM #1: Selection — Evaluates all unprocessed mentions, selects multiple worth replying to (with priority)
2. LLM #2: Planning — For each selected mention, creates a plan (tools to use)
3. Tool Execution — Executes planned tools (web_search, generate_image)
4. LLM #3: Reply — Generates final reply text based on context and tool results

Key Features:

• Multi-mention selection (not just one)
• Priority-based processing
• Per-mention tool planning
• User conversation history for context
• Tools used tracking for analytics
• Whitelist support

Auto-Discovery Tool System (tools/registry.py)

Tools are now automatically discovered from the tools/ directory.

How it works:

• Scans all Python files in tools/ using pkgutil
• Looks for TOOL_SCHEMA constant in each module
• Registers tool function with matching name
• No manual registry updates needed

To add a new tool:

# tools/my_tool.py
TOOL_SCHEMA = {
    "type": "function",
    "function": {
        "name": "my_tool",
        "description": "What this tool does",
        "parameters": {...}
    }
}

async def my_tool(query: str) -> dict:
    return {"result": "..."}

Tool Updates

• tools/web_search.py — Added TOOL_SCHEMA for auto-discovery
• tools/image_generation.py — Added TOOL_SCHEMA, jfif format support, uses ALL reference images (not random selection)

New Prompts

• config/prompts/mention_selector_agent.py — Instructions for selecting mentions
• config/prompts/mention_reply_agent.py — Instructions for planning and generating replies

New Schemas (config/schemas.py)

• MENTION_SELECTION_SCHEMA — Array of selected mentions with priority
• MENTION_PLAN_SCHEMA — Reply plan format
• REPLY_TEXT_SCHEMA — Final reply format

Documentation Updates

• Updated ARCHITECTURE.md with agent-based mentions flow, auto-discovery tools
• Updated README.md with new architecture, mention handler description, image generation changes

Infrastructure

• TierManager now accepts database for fallback storage

Infrastructure Improvements & Metrics

v1.2.2 - Infrastructure Improvements & Metrics

What's New

Centralized API Configuration (utils/api.py)

Consolidated OpenRouter API configuration into a single module.

What changed:

• New utils/api.py with OPENROUTER_URL and get_openrouter_headers()
• Removed duplicate headers from 5 files (llm.py, autopost.py, web_search.py, image_generation.py)
• All API calls now use the centralized configuration

Centralized Model Configuration (config/models.py)

Model constants moved to a dedicated configuration file.

LLM_MODEL = "anthropic/claude-sonnet-4.5"
IMAGE_MODEL = "google/gemini-3-pro-image-preview"

Benefits:

• Change models in one place
• Clear overview of all models used
• Commented options for max_tokens/temperature overrides

Unified LLM Client

LLMClient now handles all LLM operations including agent conversations.

New method:

• chat(messages, response_format) — Multi-turn conversation for agent flows

Impact:

• AutoPostService now uses LLMClient.chat() instead of direct API calls
• Cleaner code, single HTTP client configuration

Health Check Improvements

Extended /health endpoint with detailed status:

{
  "status": "healthy",
  "database": "connected",
  "scheduler_running": true,
  "tier": "free",
  "version": "1.2.2"
}

New Metrics Endpoint

Added /metrics endpoint for bot statistics:

{
  "posts_total": 13,
  "posts_today": 2,
  "mentions_total": 2,
  "mentions_today": 0,
  "last_post_at": "2025-12-14T10:30:00",
  "last_mention_at": "2025-12-13T15:20:00"
}

Database Improvements

Added metrics methods to Database class:

• ping() — Health check
• count_posts() / count_posts_today()
• count_mentions() / count_mentions_today()
• get_last_post_time() / get_last_mention_time()

Tools Refactoring

Refactored tools/web_search.py and tools/image_generation.py to use centralized configuration:

Before:

# Each tool had its own constants
OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions"
SEARCH_MODEL = "anthropic/claude-sonnet-4.5"
headers = {"Authorization": f"Bearer {settings.openrouter_api_key}", ...}

After:

# Now imports from centralized modules
from config.models import LLM_MODEL
from utils.api import OPENROUTER_URL, get_openrouter_headers

Benefits:

• No duplicate code across files
• Change API config or models in one place
• Consistent headers across all API calls

Automatic Tier Detection & Modular Prompts

v1.2.1 - Automatic Tier Detection & Modular Prompts

What's New

Tier Manager (services/tier_manager.py)

Automatic Twitter API tier detection and limit management system.

Features:

• Auto-detect tier on startup — Queries Twitter Usage API to determine Free/Basic/Pro/Enterprise tier
• Hourly refresh — Automatically detects subscription upgrades within 1 hour
• Feature gating — Blocks unavailable features (e.g., mentions on Free tier)
• Usage monitoring — Tracks monthly usage vs cap
• Auto-pause — Stops operations when 100% cap reached
• Warnings — Logs at 80% and 90% usage

How tier detection works:

GET /2/usage/tweets → project_cap
  100 → Free tier
  10,000 → Basic tier
  1,000,000 → Pro tier
  10,000,000+ → Enterprise tier

New Endpoints

• GET /tier-status — Returns current tier, usage stats, and available features
• POST /tier-refresh — Force tier re-detection (use after subscription change)

Modular Personality System (config/personality/)

Personality definition split into three separate files for easier editing:

config/personality/
  __init__.py       # Combines all parts into SYSTEM_PROMPT
  backstory.py      # Origin story (BACKSTORY)
  beliefs.py        # Values and priorities (BELIEFS)
  instructions.py   # Communication style (INSTRUCTIONS)

Benefits:

• Edit parts independently without touching the whole prompt
• Clearer organization of character traits
• Easier to understand what each part does

Modular Prompts System (config/prompts/)

LLM prompts moved to separate files:

config/prompts/
  agent_autopost.py     # AGENT_PROMPT_TEMPLATE (for autoposting agent)
  mention_selector.py   # MENTION_SELECTOR_PROMPT (for mention handling)

Centralized Schemas (config/schemas.py)

All JSON schemas for structured LLM output in one place:

• PLAN_SCHEMA — Agent plan format
• POST_TEXT_SCHEMA — Final tweet format
• MENTION_SELECTOR_SCHEMA — Mention response format

Service Integration

• AutoPostService.run() checks can_post() before posting
• MentionHandler.process_mentions_batch() checks can_use_mentions() before processing
• Both services receive tier_manager instance via constructor

Example Response (/tier-status)

{
  "tier": "free",
  "project_cap": 100,
  "project_usage": 0,
  "usage_percent": 0.0,
  "cap_reset_day": 7,
  "features": {
    "mentions": false,
    "post_limit": 500,
    "read_limit": 100
  }
}

Agent Architecture

v1.2.0 - Agent Architecture

What's New

Agent-Based Autoposting (services/autopost.py)

Complete rewrite of the autoposting system using an autonomous agent architecture.

How it works:

1. Agent receives context (previous 50 posts)
2. Agent creates a plan — decides which tools to use (or none)
3. Agent executes tools step by step (web_search → generate_image)
4. Tool results feed back into the conversation
5. Agent generates final tweet text based on all gathered information
6. Tweet is posted with optional image

Key features:

• Dynamic tool selection — Agent decides when to use tools based on context
• Continuous conversation — Single LLM conversation with tool results as messages
• Modular tools — Tools auto-discovered from tools/registry.py
• Plan validation — Ensures generate_image is always last, max 3 tools per plan

Dynamic Tool Discovery (tools/registry.py)

• Added get_tools_description() function
• Agent prompt automatically includes all registered tools
• Adding a new tool to TOOLS_SCHEMA makes it available to the agent

Agent Flow

[Scheduler] → AutoPostService.run()
    → Get previous posts for context
    → LLM Call #1: Create plan {reasoning, plan: [{tool, params}]}
    → Validate plan
    → Execute each tool, add results to conversation
    → LLM Call #2: Generate final tweet text
    → Upload image (if generated)
    → Post to Twitter
    → Save to database

Documentation Updates

• Updated ARCHITECTURE.md with agent system documentation
• Updated README.md with agent-based autoposting description

Tools System (Web Search & Image Generation)

v1.1.3 - Tools System (Web Search & Image Generation)

What's New

Web Search Tool (tools/web_search.py)

• Real-time web search using OpenRouter's native plugins API
• Uses plugins: [{id: "web"}] for actual internet search (not Perplexity LLM)
• Returns structured results with source citations (URLs, titles, snippets)
• Configurable max_results parameter (1-10)

Image Generation Tool (tools/image_generation.py)

• Moved image generation from service to standalone tool
• Same functionality: uses reference images from assets/ folder
• Ready for agent architecture integration

Tool Registry (tools/registry.py)

• Registered both tools with OpenAI-style function calling schemas
• web_search — for current information, news, prices
• generate_image — for creating images with consistent character appearance

Architecture Documentation

• Updated ARCHITECTURE.md with new tools documentation
• Added function signatures and usage examples