tweet-optimizer-v2/README.md

# DSPy Tweet Optimizer - Modaic Agent

https://img.freepik.com/free-vector/twitter-new-2023-x-logo-white-background-vector_1017-45422.jpg?semt=ais_hybrid&w=740&q=80

A composable DSPy agent that optimizes tweets using a reflective generate-evaluate algorithim, packaged for the [Modaic Hub](https://modaic.dev). 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

```python
# 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](https://openrouter.ai/))
- Modaic account (for hub deployment)

### Setup

1. **Clone the repository:**
```bash
git clone https://git.modaic.dev/farouk1/tweet-optimizer-v2.git
cd tweet-optimizer
```

2. **Install dependencies:**
```bash
uv sync
```

3. **Set up your API key and Modaic Token:**
```bash
export OPENROUTER_API_KEY='your-api-key-here'
export MODAIC_TOKEN='your-modaic-token'
```

## Usage

### Basic Agent Usage

```python
from tweet_optimizer_agent 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']}")
```

### Full Optimization Process

```python

```

### Custom Configuration

```python
# 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

```python
# 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

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](LICENSE) file for details.

## Credits

This Modaic agent implementation is based on the original DSPy Tweet Optimizer by [tom-doerr](https://github.com/tom-doerr/dspy-tweet-optimizer), 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](https://github.com/tom-doerr))
**Original Repository**: [dspy-tweet-optimizer](https://github.com/tom-doerr/dspy-tweet-optimizer)

### Modifications for Modaic

- Packaged as a Modaic PrecompiledAgent
- Added hub deployment functionality
- Enhanced configuration options
- Extended usage examples