marketing-agent

An agent that learns which TikTok formats earn organic views and turns them into product videos. Three modules in one repo, one SQLite store, one CLI (mkt):

module	what it does	status
research/	Concept radar. Scrapes public TikTok hashtag pages in a real Chrome (no login, no API key), stores every video and its stats over time, ranks by an early-traction score, clusters videos into reusable concepts with an LLM. Polls any public video URL for views/likes/shares (scoreboard input).	working
classifier/	Watches a video (frames every 3s + transcript + caption + sound) and returns strict JSON tags: hook type and text, visual style, pacing, concept, product-by-5s, demo score. gpt-5.4 by default (gpt-5.4-mini flips labels between runs).	working
video/	Remixes a concept to a product (10-20 scripts, 1-3s hook, product on screen by 5s, scored for demoability), generates clips with Seedance 2.5 on fal.ai (Seedance 2.0 fast on Replicate as the cheap fallback), and cuts a captioned 1080x1920 H.264 with ffmpeg. --provider stub renders colour cards so the pipeline runs with no key.	working, needs FAL_KEY for real clips

Not in scope by design: automated account warming, bot-run posting accounts, posting via API. Real each clip is posted from a real account only after a person presses Post on it; the agent runs everything around that.

Two kinds of video

Every video in the store is in exactly one of two groups, and they are never pooled:

• Reference: other people's videos scraped from niche hashtags for research. They feed the radar, concept clustering, the cohort panel and the controlled findings: what the market rewards right now.
• Ours: posts from our registered accounts (mkt own add, including their older posts, which set the baseline). They feed the picker's observed reward, the "our posts" section of the script prompt and the throttled-account check. mkt own research downloads and classifies them so we know which hook and style each one actually used.

mkt scoreboard prints both, --group reference|ours prints one. The daily report has a section for each.

Setup

uv venv && . .venv/bin/activate
uv pip install -e ".[dev]"
cp .env.example .env   # fill in OPENAI_API_KEY, FAL_KEY

The scraper drives an existing Chrome over CDP (CDP_URL, default http://localhost:29229). Start Chrome with --remote-debugging-port=29229 or point it at any CDP endpoint. ffmpeg must be on PATH.

Daily loop

mkt run tanning tanning selftanner --product "Glow, an app that previews your tan before you book"

which is the same as:

mkt scrape tanning selftanner         # ~30 videos per hashtag per scroll, newest first
mkt radar --max-age-h 72              # rank by early score (views/h, discounted by follower count)
mkt download --top 8                  # fetch the top videos through the browser
mkt classify                          # tag them (hook, style, concept, demo score)
mkt classify --niche tanning --limit 40  # tag the scored research panel instead, newest first
mkt concepts tanning                  # cluster into 3-8 reusable formats, flag early ones
mkt scripts <concept_id> "Glow, ..."  # 12 scripts, keep demo_score >= 3
mkt render <script_id> --duration 10  # Seedance clip + captions -> data/renders/s<id>.mp4
mkt poll <url> ...                    # record stats for posted videos
mkt scoreboard                        # reward per video, hooks/concepts ranked, throttled accounts
mkt compare                           # our posts vs the market: each hook/style/concept side by side
mkt dashboard tanning                 # static HTML (data/site/index.html) with clips copied next to it

Scoreboard

mkt scoreboard turns raw views into a reward: log10(views+1), winsorized at the 95th percentile, minus the account's own median (or the niche median for accounts with under 3 videos). +1 means 10x what that account normally gets. Hook types, concepts and visual styles are ranked by mean reward with n, standard error and win rate, so a hook that won once on a huge account does not outrank one that wins consistently. Videos under 24 h old are listed but not scored. Accounts whose last 3+ posts all sit under 1k views are flagged as possibly throttled.

Feedback loop

mkt run ... --product X no longer scripts the concept with the highest early score. policy.pick_concept samples a score per concept from the radar prior plus what has been learned about it (noise shrinks with n). "Learned" is (SHRINK_K * trait bonus + sum of its own posts' rewards) / (SHRINK_K + n): each concept is a bundle of traits (hook type, visual style, product on screen by 5s, pace, the majority over its classified member videos), and every trait value keeps a running, shrunk score from our posts (plus a quarter-weight one from the niche's reference videos). So a concept we never posted inherits what similar ones taught us, a concept that comes back under a new name after the next research run keeps its lessons, and with no data at all it follows the radar. mkt scripts passes the scoreboard's winning and losing hooks, concepts and styles into the prompt. mkt policy <niche> shows what the loop has learned.

Known limits

One-account login and feedback

# Supply TIKTOK_POST_HANDLE and TIKTOK_POST_PASSWORD through protected secrets, not CLI arguments.
# TIKTOK_POST_EMAIL / TIKTOK_POST_EMAIL_PASSWORD: the Gmail inbox on the TikTok account, read only
# for TikTok's email verification codes.
mkt own login
mkt own add @youraccount --product "your product"
mkt own sync                      # niche and hashtags from campaign.toml
mkt own list

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗