DSPy Tweet Optimizer - Modaic Agent

A composable DSPy agent that optimizes tweets using a reflective generate-evaluate algorithim, packaged for the Modaic Hub. Generate, evaluate, and iteratively improve tweets with configurable evaluation categories and automated optimization.

Features

• Modaic Agent: Deployable on Modaic Hub for easy sharing and reuse
• Hill-Climbing Optimization: Iteratively improves tweets through automated evaluation
• Customizable Categories: Define evaluation criteria (engagement, clarity, tone, etc.)
• Multiple Usage Modes: Single generation, full optimization, or standalone evaluation
• Structured Evaluation: 1-9 scoring with detailed reasoning per category
• CLI Compatibility: Same functionality as the original CLI tool
• Easy Configuration: Flexible model, iteration, and patience settings

Installation

Prerequisites

• Python 3.11+
• OpenRouter API key (Get one here)
• Modaic account (for hub deployment)

Setup

1. Clone the repository:

git clone https://git.modaic.dev/farouk1/tweet-optimizer-v2.git
cd tweet-optimizer

2. Install dependencies:

uv sync

3. Set up your API key and Modaic Token:

export OPENROUTER_API_KEY='your-api-key-here'
export MODAIC_TOKEN='your-modaic-token'

Usage

Basic Agent Usage

from tweet_optimizer_agent import TweetOptimizerAgent, TweetOptimizerConfig

# Create agent with default settings
config = TweetOptimizerConfig()
agent = TweetOptimizerAgent(config)

# Single tweet generation
tweet = agent(
    input_text="Create a tweet about HuggingFace transformers",
    current_tweet="",
    previous_evaluation=None
)
print(f"Generated: {tweet}")

Full Optimization Process

# Run complete optimization (like CLI)
results = agent.optimize(
    input_text="Create a tweet about HuggingFace transformers",
    iterations=10,
    patience=5
)

print(f"Original: {results['initial_text']}")
print(f"Optimized: {results['final_tweet']}")
print(f"Score: {results['best_score']:.2f}")
print(f"Iterations: {results['iterations_run']}")

Custom Configuration

# Custom evaluation categories and settings
config = TweetOptimizerConfig(
    lm="openrouter/anthropic/claude-sonnet-4.5",
    categories=[
        "Engagement potential",
        "Clarity and readability",
        "Professional tone",
        "Call-to-action strength"
    ],
    max_iterations=15,
    patience=8
)

agent = TweetOptimizerAgent(config)

Tweet Evaluation

# Evaluate a specific tweet
evaluation = agent.evaluate_tweet(
    tweet_text="Excited to share our new AI model!",
    original_text="We released a new AI model",
    current_best_tweet=""
)

for eval in evaluation.evaluations:
    print(f"{eval.category}: {eval.score}/9 - {eval.reasoning}")

Deploy to Modaic Hub

# Push your trained agent to Modaic Hub
agent.push_to_hub(
    "your-username/tweet-optimizer",
    commit_message="Deploy tweet optimizer agent",
    with_code=True
)

Load from Hub

# Load a pre-trained agent from Modaic Hub
agent = TweetOptimizerAgent.from_precompiled("your-username/tweet-optimizer")

# Use immediately
optimized = agent("Your tweet content here")

CLI Tool

The original CLI functionality is still available:

# Basic usage
python cli.py "Create a tweet about AI breakthroughs"

# With custom settings
python cli.py "Product launch announcement" \
  --model "Claude Sonnet 4.5" \
  --iterations 15 \
  --patience 8 \
  --categories "Excitement" "Clarity" "Call-to-action"

# List available models
python cli.py --list-models

# Quiet mode (output only final tweet)
python cli.py "Content here" --quiet

Configuration Options

TweetOptimizerConfig

Parameter	Type	Default	Description
lm	str	"openrouter/google/gemini-2.5-flash"	Language model to use
eval_lm	str	"openrouter/openai/gpt-5"	Evaluator language model to use
categories	List[str]	Default evaluation categories	Custom evaluation criteria
max_iterations	int	10	Maximum optimization iterations
patience	int	5	Stop after N iterations without improvement

Default Categories

1. Engagement potential - How likely users are to like, retweet, or reply
2. Clarity and readability - How easy the tweet is to understand
3. Emotional impact - How well the tweet evokes feelings or reactions
4. Relevance to target audience - How well it resonates with intended readers

Architecture

dspy-tweet-optimizer/
 tweet_optimizer_agent.py    # Main Modaic agent implementation
 cli.py                      # Command-line interface
 modules.py                  # DSPy generator and evaluator modules
 hill_climbing.py            # Optimization algorithm
 models.py                   # Pydantic data models
 helpers.py                  # Utility functions
 utils.py                    # File I/O and DSPy utilities
 constants.py                # Configuration constants
 tests/                      # Test suite

Core Components

• TweetOptimizerAgent: Main Modaic agent with optimization methods
• TweetGeneratorModule: DSPy module for generating/improving tweets
• TweetEvaluatorModule: DSPy module for structured evaluation
• HillClimbingOptimizer: Iterative improvement algorithm

License

MIT License - see LICENSE file for details.

Credits

This Modaic agent implementation is based on the original DSPy Tweet Optimizer by tom-doerr, licensed under MIT. The original project provided the foundation including:

• Core DSPy modules (TweetGeneratorModule, TweetEvaluatorModule)
• Hill-climbing optimization algorithm
• CLI interface and utilities
• Comprehensive testing framework

Original Author: Tom Doerr (@tom-doerr) Original Repository: dspy-tweet-optimizer

Modifications for Modaic

• Packaged as a Modaic PrecompiledAgent
• Added hub deployment functionality
• Enhanced configuration options
• Maintained CLI compatibility
• Extended usage examples