vivly 0.5.0b1

Python client + CLI for the Vivly social-data API (X / Reddit) with smart prompt-based routing.

vivly

Python client for the Vivly social-data API. One bearer key, two live sources: X (Twitter) and Reddit, plus a smart router that picks sources from a plain-language prompt.

Install

This is a beta release, so the --pre flag is required:

pip install --pre vivly==0.5.0b1

Authenticate

The client needs a personal access token (looks like vk_live_...). Two ways to provide it:

# Option A: log in interactively (opens a browser, stores the token at
# ~/.config/vivly/config.json with 0600 perms)
vivly login

# Option B: set it yourself if you were handed a token
export VIVLY_API_KEY="vk_live_..."

A .env file in the working directory is auto-loaded. Resolution order: explicit api_key= argument, then VIVLY_API_KEY (or legacy VIVLY_SKILL_KEY), then .env, then ~/.config/vivly/config.json.

Usage

from vivly import VivlyClient

with VivlyClient() as v:
    # Reddit: one-shot retrieval. Auto-discovers subreddits, searches them,
    # and LLM-filters the results for relevance.
    r = v.reddit.search("claude code agents", max_posts=10)
    for post in r["posts"]:
        print(post["score"], post["title"], post["url"])

    # X / Twitter: blocking helper that starts a scrape, polls, and returns items.
    # (Runs a paid third-party actor server-side; expect a few seconds to minutes.)
    tweets = v.x.scrape('"san antonio" arena Spurs lang:en', max_items=50)
    for t in tweets:
        print(t["metrics"]["likes"], t["text"][:80])

    # Smart router: describe what you want; it plans + runs the right sources.
    result = v.route("what are people saying about claude code on reddit",
                     force_sources=["reddit"], max_items=20)

If you'd rather drive the X scrape yourself instead of the blocking helper:

started = v.x.scrape_start("query lang:en", max_items=50)
status  = v.x.scrape_status(started["run_id"])
items   = v.x.scrape_items(started["dataset_id"])

Errors

from vivly import VivlyError, AuthError, RateLimitError, NotFoundError

AuthError (401/403) usually means a missing, revoked, or mistyped token.

License

MIT