178 lines
5.8 KiB
Markdown
178 lines
5.8 KiB
Markdown
# DSPy Tweet Optimizer - Modaic Agent
|
|
|
|
|
|
|
|
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 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
|
|
|
|
```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 |