Architecture

This document describes the comprehensive architecture for the BILL Twitter Plugin, including autonomous posting, intelligent replying, context analysis, and event-driven responses.

Overview

The Twitter Plugin is a sophisticated integration that provides:

• Autonomous Posting: Context-aware, event-driven tweet generation

• Intelligent Replying: Contextual responses to mentions and conversations

• Timeline Monitoring: Continuous ingestion from influential accounts

• Image Processing: LLM-powered image analysis and storage

• Advanced Caching: Efficient database strategies for performance

• Context Analysis: LLM-based neutral analysis of market/social events

System Architecture

High-Level Architecture

Core Components

1. Twitter Plugin (twitter-plugin.ts)

The main orchestrator that:

• Manages service lifecycle

• Coordinates autonomous posting intervals

• Routes messages to appropriate handlers

• Integrates with agent runtime

2. Context Intelligence System

TwitterContextManager

Central hub for context aggregation:

interface PostingContext {
  userContext: UserContext;      // BILL's activity patterns
  threadContext: ThreadContext;   // Mentions and conversations
  worldContext: WorldContext;     // Market events and news
  metadata: ContextMetadata;      // Freshness and sources
}

ContextAnalysisService

LLM-based neutral analysis:

• Analyzes multiple data sources (timeline, news, market data)

• Generates factual summaries without personality

• Stores analyses for debugging and tracking

• Supports future expansion to Reddit, Discord, etc.

Event-Driven Posting

Intelligent event detection and response:

• Breaking News Detection: "BREAKING", "JUST IN" patterns

• Market Events: Price movements, Fed announcements

• Earnings Reports: Corporate financial events

• Crypto Events: Bitcoin and altcoin movements

• Real-time Reactions: Responds within minutes to events

3. Timeline Monitoring System

TimelineService

Background context ingestion:

• Monitors configured influential accounts

• Runs every 30 minutes automatically

• Processes tweets with images

• Stores in timeline_tweets table

ImageAnalysisService

GPT-4o Vision integration:

• Analyzes images in tweets

• Detects screenshots (Truth Social, Instagram)

• Extracts text from images

• Identifies sentiment and topics

4. Autonomous Posting Pipeline

Database Architecture

Schema Overview

-- Timeline context storage
CREATE TABLE timeline_tweets (
  id TEXT PRIMARY KEY,
  text TEXT NOT NULL,
  author_id TEXT NOT NULL,
  created_at TIMESTAMP NOT NULL,
  source_account TEXT NOT NULL,
  image_url TEXT,
  image_description TEXT,
  cached_at TIMESTAMP DEFAULT NOW()
);

-- BILL's posted tweets
CREATE TABLE posted_tweets (
  id TEXT PRIMARY KEY,
  text TEXT NOT NULL,
  created_at TIMESTAMP NOT NULL,
  engagement_stats JSONB,
  image_url TEXT,
  generated_from_context TEXT,
  tweet_type TEXT,
  posted_at TIMESTAMP DEFAULT NOW()
);

-- Context analysis results
CREATE TABLE context_analysis (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  summary TEXT NOT NULL,
  generated_at TIMESTAMP NOT NULL,
  total_items_analyzed INTEGER,
  time_range JSONB,
  sources JSONB,
  metrics JSONB
);

-- Conversation caching
CREATE TABLE cached_conversations (
  conversation_id TEXT PRIMARY KEY,
  last_updated TIMESTAMP,
  last_tweet_id TEXT,
  tweet_count INTEGER,
  participants TEXT[],
  bill_last_reply_at TIMESTAMP
);

Key Features

1. Event-Driven Intelligence

The system continuously monitors for significant events:

• Fed announcements trigger immediate responses

• Market crashes/surges get instant commentary

• Breaking news receives BILL's hot takes

• Earnings reports get trader analysis

2. Context-Aware Generation

Every post incorporates:

• Recent market events from timeline

• BILL's posting patterns and energy levels

• Trending topics and conversations

• Time-sensitive information

3. Character Consistency

BILL's personality adapts based on:

• Posting frequency (energy levels)

• Event significance (reaction intensity)

• Time of day (market hours vs off-hours)

• Recent interactions (conversation continuity)

4. Performance Optimization

• Timeline data cached for 30 minutes

• Image analysis results stored permanently

• Context generation takes ~130ms average

• Parallel processing for efficiency

Production Configuration

Environment Variables

# Twitter API
TWITTER_CLIENT_ID=your_client_id
TWITTER_CLIENT_SECRET=your_client_secret
TWITTER_USERNAME=shillbillai

# Posting Configuration
POST_INTERVAL_MIN=50
POST_INTERVAL_MAX=120
POST_LIMIT=20
REPLY_LIMIT=100

# Context Configuration
TWITTER_ENABLE_CONTEXT=true
TWITTER_IMMEDIATE_FETCH_CONTEXT=false

# Database
SUPABASE_URL=your_supabase_url
SUPABASE_SECRET_KEY=your_secret_key

# AI Services
OPENAI_API_KEY=your_openai_key
OPENROUTER_API_KEY=your_openrouter_key

Rate Limiting Strategy

• Posts: Max 20/day, min 50-120 min intervals

• Replies: Max 100/day, min 2 min intervals

• Timeline monitoring: 5 accounts per batch

• API calls respect Twitter's rate limits

Testing & Monitoring

Test Commands

# Test context generation
bun run agent/plugins/twitter/tests/TwitterContextManager.test.ts

# Test event detection
bun run agent/tests/event-driven-posting-test.ts

# Test image analysis
bun run agent/plugins/twitter/tests/ImageAnalysisService.test.ts

# Check timeline monitoring
bun run agent/plugins/twitter/scripts/check-image-analysis.ts

Monitoring Queries

-- Recent context analyses
SELECT * FROM context_analysis 
ORDER BY generated_at DESC 
LIMIT 10;

-- Posted tweets with context
SELECT id, text, generated_from_context 
FROM posted_tweets 
WHERE generated_from_context IS NOT NULL 
ORDER BY created_at DESC;

-- Timeline coverage
SELECT source_account, COUNT(*) as tweet_count 
FROM timeline_tweets 
WHERE cached_at > NOW() - INTERVAL '24 hours' 
GROUP BY source_account;

Future Enhancements

Planned Features

1. News API Integration: Direct news feed analysis

2. Market Data Feeds: Real-time price integration

3. Reddit/Discord Monitoring: Extended social context

4. Thread Management: Multi-tweet threads

5. Sentiment Analysis: Market mood detection

Architecture Extensions

1. Webhook Support: Real-time event processing

2. Distributed Processing: Multi-node timeline monitoring

3. Advanced Caching: Redis integration

4. Stream Processing: Twitter Streaming API

5. Analytics Dashboard: Performance metrics UI

The Twitter Plugin represents a sophisticated autonomous agent implementation that combines real-time monitoring, intelligent context analysis, and character-consistent content generation to create an engaging social media presence.