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
Easy Configuration: Flexible model, iteration, and patience settings

Quick Usage

# Load this pre-trained agent from Modaic Hub
from modaic import AutoAgent

tweet_optimizer = AutoAgent.from_precompiled("farouk1/tweet-optimizer-v2")

results = tweet_optimizer(
    input_text="Your tweet content here",
    iterations=20,
    patience=7
)

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}")

Installation

Prerequisites

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

Setup

Clone the repository:

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

Install dependencies:

uv sync

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 agent.index import TweetOptimizerAgent, TweetOptimizerConfig

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

# run complete optimization
results = tweet_optimizer(
    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)

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
)

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

Engagement potential - How likely users are to like, retweet, or reply
Clarity and readability - How easy the tweet is to understand
Emotional impact - How well the tweet evokes feelings or reactions
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
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
Extended usage examples