AutoViralAI

<!-- ============================================ -->
<!--            HERO SECTION                      -->
<!-- ============================================ -->

<div align="center">

<a href="https://efektywniejsi.pl/">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/screenshots/efektywniejsi-logo.png">
    <source media="(prefers-color-scheme: light)" srcset="docs/screenshots/efektywniejsi-logo-dark.png">
    <img src="docs/screenshots/efektywniejsi-logo-dark.png" alt="Efektywniejsi.pl" height="60">
  </picture>
</a>

<br/><br/>

<img src="docs/screenshots/banner.png" alt="AutoViralAI Banner" width="100%">

<br/>

# AutoViralAI

### Your social media grows while you sleep.

<p>
An autonomous AI agent that researches what's going viral, generates content,<br/>
publishes it, measures engagement — and <strong>rewrites its own strategy based on what actually worked</strong>.
</p>

<br/>

[![CI](https://github.com/kgarbacinski/AutoViralAI/actions/workflows/ci.yml/badge.svg)](https://github.com/kgarbacinski/AutoViralAI/actions/workflows/ci.yml)
[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![LangGraph](https://img.shields.io/badge/LangGraph-0.3+-orange.svg)](https://github.com/langchain-ai/langgraph)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Docker](https://img.shields.io/badge/Docker-ready-2496ED.svg?logo=docker&logoColor=white)](https://www.docker.com/)
[![Threads API](https://img.shields.io/badge/Threads-API-000000.svg?logo=threads&logoColor=white)](https://developers.facebook.com/docs/threads/)

<br/>

[Real Results](#-real-results) · [Demo](#-demo) · [Quick Start](#-quick-start) · [How It Works](#-how-it-works) · [Configuration](#-configuring-your-niche) · [Roadmap](#-roadmap) · [Contributing](CONTRIBUTING.md)

</div>

<br/>

---

<!-- ============================================ -->
<!--         REAL RESULTS                         -->
<!-- ============================================ -->

## 🔥 Real Results

We've been running AutoViralAI for **~1.5 months** on a tech/programming Threads account. Here are some posts that went viral — **every single one was researched, generated, and ranked by the agent:**

<div align="center">

<img src="docs/screenshots/viral_post_3.png" alt="Viral post: jQuery vs React — 800 likes, 80 comments, 20 reposts" width="70%">

<br/><br/>

<img src="docs/screenshots/viral_post_2.png" alt="Viral post: Turbo Pascal vs modern Go — 481 likes, 90 comments, 13 reposts" width="70%">

<br/><br/>

<img src="docs/screenshots/viral_post_1.png" alt="Viral post: console.log in production — 363 likes, 79 comments" width="70%">

</div>

<br/>

> **800+ likes on a single post.** The agent learned that contrarian "old tech vs new tech" hooks and relatable developer war stories consistently outperform generic tips — and it adapted its strategy automatically.

<br/>

---

<!-- ============================================ -->
<!--            DEMO SECTION                      -->
<!-- ============================================ -->

## 🎬 Demo

<div align="center">

<em>See it in action — the agent researches trends, generates posts, ranks them, and sends you an approval request.</em>

<br/><br/>

<img src="docs/screenshots/showcase_1.png" alt="Pipeline report: research results, extracted patterns, generated variants and ranking" width="90%">

<br/>

<img src="docs/screenshots/showcase_2.png" alt="Approval message with score, alternatives, and approve/reject buttons" width="90%">

<br/>

<img src="docs/screenshots/showcase_3.png" alt="Published post and engagement metrics" width="90%">

</div>

<br/>

---

<!-- ============================================ -->
<!--         PROBLEM / SOLUTION                   -->
<!-- ============================================ -->

## 💡 The Problem

You know you should be posting consistently. You know what kind of content performs. But researching trends, writing posts, tracking what works, adjusting strategy — **it's a full-time job**.

## 💡 The Solution

AutoViralAI does the entire loop autonomously. It doesn't just post — it ***learns***. Every day it gets a little better at understanding what your audience actually engages with.

```
Day 1:   "Here's a generic coding tip"            → 12 likes
Day 7:   "Hot take: most devs don't need Docker"   → 340 likes
Day 14:  Agent learned contrarian hooks work 3x     → adapts strategy automatically
Day 30:  Posts consistently hit 500+ engagement     → you didn't write a single one
Day 45:  Single post hits 800 likes                 → the agent wrote it, not you
```

<br/>

---

<!-- ============================================ -->
<!--         WHY AUTOVIRALAI                      -->
<!-- ============================================ -->

## ⚡ Why AutoViralAI?

Most "AI social media tools" are glorified schedulers with a GPT wrapper. They generate generic content, blast it out, and call it a day.

**AutoViralAI is fundamentally different:**

| | Traditional tools | AutoViralAI |
|:---:|---|---|
| 🔍 | Generate content from a static prompt | Research what's *actually* going viral right now, extract the patterns, and generate content using those patterns |
| 📈 | Same strategy forever | Strategy evolves daily based on real engagement data |
| 📊 | Post and forget | Measure results after 24h, learn what worked and why, feed it back |
| 🏆 | AI picks the post | Multi-signal ranking: AI score + historical pattern performance + novelty scoring |
| 🛡️ | Fully automated (risky) | Human-in-the-loop: you approve every post via Telegram before it goes live |

<br/>

---

<!-- ============================================ -->
<!--            KEY FEATURES                      -->
<!-- ============================================ -->

## ✨ Key Features

<table>
<tr>
<td width="50%" valign="top">

### 🧠 Self-Learning Loop
The agent doesn't just execute. It observes, measures, and adapts. Pattern that got 3x engagement? It'll use it more. Strategy that flopped? Automatically deprioritized.

</td>
<td width="50%" valign="top">

### 🏆 Multi-Signal Ranking
Posts aren't ranked on "AI vibes." Each variant scores on 3 independent signals: AI-evaluated viral potential, historical pattern performance, and novelty (so it doesn't repeat itself).

</td>
</tr>
<tr>
<td width="50%" valign="top">

### 🛡️ Human-in-the-Loop
Nothing gets published without your approval. The agent sends you the top-ranked post via Telegram. You approve, edit, or reject. Built on LangGraph's `interrupt()` — survives server restarts.

</td>
<td width="50%" valign="top">

### 🎯 Niche-Aware
Define your voice, audience, content pillars, and topics to avoid in a single YAML file. The agent stays on-brand in every cycle.

</td>
</tr>
<tr>
<td width="50%" valign="top">

### 🔍 Research-Driven
Before generating anything, the agent scrapes Threads and HackerNews to understand what's trending *right now* in your niche. No hallucinated trends.

</td>
<td width="50%" valign="top">

### 🚀 Production-Ready
PostgreSQL persistence, Docker deployment, CI/CD via GitHub Actions, Telegram webhooks, APScheduler for cron-like execution. Not a toy — this runs 24/7.

</td>
</tr>
</table>

<br/>

---

<!-- ============================================ -->
<!--            QUICK START                       -->
<!-- ============================================ -->

## 🚀 Quick Start

### Prerequisites

- Python 3.13+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
- An [Anthropic API key](https://console.anthropic.com/)

### Setup

```bash
git clone https://github.com/kgarbacinski/AutoViralAI.git
cd AutoViralAI
uv sync
cp .env.example .env
# Edit .env → set ANTHROPIC_API_KEY (minimum required)
```

### Run Your First Cycle

```bash
# Interactive mode — you approve/reject posts in the te

[truncated…]