Add Telegram ads simulator for RuneWager campaign optimization#142
Merged
Conversation
Adds scripts/telegram-ads-simulator.js — a standalone Node.js simulation engine for RuneWager Telegram Ads campaigns. Features: - Validates 30 ad creatives for Telegram Ads compliance (<=160 chars, single line, no HTML/Markdown, Telegram links only, forbidden wording check) - Categorizes ads by dominant appeal: freeCode, leaderboard, wagerBonus, global, brand, and mixed variants - Simulates 45,360 combinations per run (30 ads x 6 time buckets x 7 days x 6 channel types x 6 user personas) using seeded LCG PRNG for reproducibility - Models 6 channel types: HighRollerCasinoChat, CasinoDealsChannel, CryptoSignalsChannel, AirdropChannel, GeneralCryptoChat, CasualGamingChannel - Models 6 personas: BonusHunter, LeaderboardGrinder, CryptoRedeemer, CasualTester, NightOwlUS, GlobalGrinder with category affinity boosts - Bid sensitivity model at 0.5 / 1.0 / 2.0 with placement quality factors - 3-iteration auto-optimization loop with per-category copy tweaks - Selects top 3 ads by composite score (50% ROI, 30% prize redemption, 20% leaderboard participation) - Outputs PART A machine-readable JSON + PART B plain-text summary - Supports --output <file>, --summary-only, --json-only flags Usage: node scripts/telegram-ads-simulator.js node scripts/telegram-ads-simulator.js --output results/ads-sim.json node scripts/telegram-ads-simulator.js --summary-only https://claude.ai/code/session_01QSkvVSYsiNQ9udQ3fvVopJ
Reviewer's GuideAdds a standalone Node.js CLI script that validates 30 predefined Telegram ad creatives for compliance, deterministically simulates their performance across multiple dimensions, runs a copy-optimization loop, performs bid sensitivity analysis, and outputs both structured JSON and a human-readable summary to stdout or file, with flexible CLI flags. Sequence diagram for CLI execution and simulation pipelinesequenceDiagram
actor User
participant NodeCLI as Node_cli
participant Script as telegram_ads_simulator_js
participant FS as File_system
participant Stdout
participant Stderr
User->>NodeCLI: node scripts/telegram-ads-simulator.js [--output|--summary-only|--json-only]
NodeCLI->>Script: load and execute main()
Script->>Stderr: log "Simulator v1.0" and config
Script->>Script: parse CLI args
Script->>Script: validateAd() over RAW_ADS
Script->>Stderr: log validation summary
Script->>Script: compute total combinations
Script->>Stderr: log simulation start
loop for each validated ad (30)
Script->>Script: runAdSimulation(ad)
Script->>Script: categorizeAd()
Script->>Script: simulateCombination() 1,512 times
Script->>Script: aggregate baseline metrics
Script->>Script: bidSensitivity()
Script->>Script: optimizeText() + iterMetrics() for 3 iterations
end
Script->>Stderr: log simulation finished
Script->>Script: selectTopAds(ad_results, validated_ads)
Script->>Stderr: log top ad IDs
Script->>Script: build output object
Script->>Script: JSON.stringify(output)
Script->>Script: generateSummary(output)
alt --output provided
Script->>FS: write JSON + summary to file
Script->>Stdout: print summary only
else summary-only
Script->>Stdout: print summary only
else json-only
Script->>Stdout: print JSON only
else default
Script->>Stdout: print JSON
Script->>Stdout: print summary
end
Script->>Stderr: log "Simulation complete."
Class-style diagram for main functions in telegram ads simulatorclassDiagram
class TelegramAdsSimulator {
+main()
+validateAd(text, idx)
+categorizeAd(text)
+simulateCombination(adId, timeBucket, day, channel, persona, bid)
+runAdSimulation(validatedAd)
+bidSensitivity(baselineCTR, baselineCPC, baselineROI)
+getPersonaMod(persona, category)
+optimizeText(text, category, iteration)
+iterMetrics(baseline, iteration)
+selectTopAds(adResults, validatedAds)
+generateSummary(output)
}
class Config {
+MAX_LENGTH : number
+BOT_LINK : string
+FORBIDDEN_WORDS : string[]
+TIME_BUCKETS : string[]
+DAYS_OF_WEEK : string[]
+CHANNEL_TYPES : string[]
+PERSONAS : string[]
+BASE_METRICS : object
+TIME_MODS : object
+DAY_MODS : object
+CHANNEL_MODS : object
+COPY_TWEAKS : object
}
class RNG {
+lcgRng(seed)
+hashSeed(adId, timeBucket, day, channel, persona)
}
class MetricsUtils {
+clamp(value, lo, hi)
+r4(value)
+r2(value)
+pct(value)
}
class IO {
+writeFile(outputFile, content)
+log(msg)
}
TelegramAdsSimulator --> Config : uses
TelegramAdsSimulator --> RNG : uses
TelegramAdsSimulator --> MetricsUtils : uses
TelegramAdsSimulator --> IO : uses
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughWalkthroughIntroduces Changes
Sequence Diagram(s)sequenceDiagram
actor User
participant Script
participant Validator
participant Simulator
participant Optimizer
participant Ranker
participant OutputGen
User->>Script: Run telegram-ads-simulator.js
Script->>Validator: Validate 30 ads
Validator->>Validator: Check forbidden words,<br/>link compliance,<br/>length constraints
Validator-->>Script: Return validated ads
Script->>Simulator: Configure simulation<br/>(dimensions, metrics, modifiers)
Script->>Simulator: Run multidimensional<br/>ad simulation
Simulator->>Simulator: Generate baseline metrics<br/>across all combinations
Simulator->>Simulator: Compute top-20<br/>ROI combinations
Simulator-->>Script: Return ad results
Script->>Optimizer: Run 3-iteration<br/>copy optimization
Optimizer->>Optimizer: Apply tweaks & lift factors<br/>per iteration
Optimizer-->>Script: Return optimized versions
Script->>Ranker: Select top ads<br/>(composite score)
Ranker-->>Script: Return ranked top 3 ads
Script->>OutputGen: Generate JSON +<br/>human-readable summary
OutputGen-->>Script: Return formatted output
Script-->>User: Output to stdout/file
Estimated code review effort🎯 4 (Complex) | ⏱️ ~75 minutes Suggested labels
Poem
✨ Finishing Touches
🧪 Generate unit tests (beta)
Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- The CLI argument handling around
--outputis brittle (e.g.,--outputas the last arg with no path, or combining--summary-onlyand--json-only); consider explicitly validating arguments and failing fast with a clear usage message when the combination is invalid. - Several values are hard-coded in multiple places (e.g.,
30ads,10000impressions,3optimization iterations, progress log strings); centralizing these as constants would make future adjustments less error-prone and keep the logs consistent with the simulation config. - The
selectTopAdsaggregation of best time windows currently takes only the first time bucket per channel from the top 5 combinations; if you intend to recommend robust windows, consider aggregating counts and selecting the most frequent/highest-ROI time buckets and days instead of an arbitrary first element.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The CLI argument handling around `--output` is brittle (e.g., `--output` as the last arg with no path, or combining `--summary-only` and `--json-only`); consider explicitly validating arguments and failing fast with a clear usage message when the combination is invalid.
- Several values are hard-coded in multiple places (e.g., `30` ads, `10000` impressions, `3` optimization iterations, progress log strings); centralizing these as constants would make future adjustments less error-prone and keep the logs consistent with the simulation config.
- The `selectTopAds` aggregation of best time windows currently takes only the first time bucket per channel from the top 5 combinations; if you intend to recommend robust windows, consider aggregating counts and selecting the most frequent/highest-ROI time buckets and days instead of an arbitrary first element.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduces a comprehensive Telegram ads simulator that validates ad creatives for compliance, simulates user behavior across multiple dimensions, and optimizes ad copy through iterative testing. This tool enables data-driven campaign planning for the RuneWager Telegram bot.
Key Changes
Notable Implementation Details
--output(file path),--summary-only,--json-onlyhttps://claude.ai/code/session_01QSkvVSYsiNQ9udQ3fvVopJ
Summary by Sourcery
Add a CLI Telegram ads simulation script that validates predefined ad creatives, models their performance across multiple audience dimensions, and produces both JSON and human-readable reports, including bid sensitivity and optimization insights for selecting top-performing ads.
New Features:
Enhancements:
Build:
Summary by CodeRabbit