About Lite

Grapevine Lite

Investigate a focused question in YouTube comments with an estimate before collection, a local record of observations, and source links for follow-up.

The public Lite release is version 1.0.0 under the MIT License. It uses local regex scoring and requires your own YouTube Data API v3 key.

Install the agent skill

~~~bash npx skills add 0xfth/grapevine-lite --skill grapevine-lite ~~~

Install the Python package

~~~bash git clone https://github.com/0xfth/grapevine-lite.git cd grapevine-lite python -m pip install . ~~~

Python 3.10 or later is required. The Python distribution keeps its compatibility name voc-listener-lite; import and command examples use voc and python -m voc. The agent skill has its own name, grapevine-lite.

Run a first research question

Set your YouTube Data API v3 key in the local environment as YOUTUBE_API_KEY before collection. Define a small area with two to six concrete search phrases, terms that describe who and what you are investigating, and a collection depth:

~~~bash python -m voc add-area --name sourdough --db q.db \ --queries "sourdough starter troubleshooting" \ --person-terms baker "home baker" \ --topic-terms "sourdough starter" \ --depth shallow ~~~

Review the estimate before collection:

~~~bash python -m voc estimate --area sourdough --db q.db ~~~

After reviewing and approving that estimate, run a bounded collection and inspect the saved observations:

~~~bash python -m voc query --area sourdough --db q.db --yes --max-new-hits 10 python -m voc inbox --area sourdough --db q.db python -m voc fidelity --db q.db ~~~

Query output streams hits, progress, and a summary as JSON lines. Stopping early keeps completed video results in the local database, but the resulting sample may be incomplete.

What Lite includes

• Estimate-first, on-demand research over selected YouTube search phrases and comments.
• Local regex scoring based on the configured vocabulary and quality signals; it does not send comments to an inference provider.
• A local SQLite database for areas, observations, and query history.
• An inbox for reviewing saved observations, with source links preserved for follow-up.
• Helpers for checking saved results and query history, including grep, diagnose, videos, simulate, and fidelity.

Lite covers YouTube comments only. It does not run a background monitor or schedule collections. It does not include the broader source set or optional model scoring described for Grapevine Pro.

Data and coverage

Collections call the YouTube Data API using your key. The library does not intentionally store that key in its SQLite research database. Research data and query history are stored locally.

Results are limited to videos and comments reached by the chosen phrases, depth, timing, and API limits. A zero-hit run does not show that a topic is absent from YouTube. Scores help rank observations for review; they do not establish truth, identity, sentiment, or prevalence.

References

• Worked example
• MIT License

Grapevine Pro is a separate edition in development. This guide describes only the available Lite 1.0.0 release.

About Pro

Grapevine Pro

Research public conversation from a focused question to a source-linked brief. Explore product feedback, requests, praise, comparisons, and buying intent, not only complaints. Estimate the work first, collect a bounded sample, and review what the evidence can and cannot show.

What it does

Grapevine is an on-demand voice-of-customer research skill for AI agents. Point it at a question and it collects bounded evidence from the public discussions where buyers actually talk, then prepares a source-linked brief: recurring complaints, problems, requests, praise, and themes. Twenty-one sources, no scraping. A typical investigation:

1. Frame a question and choose public sources. 2. Provide two to six source-specific search phrases and optional topic or audience terms. 3. Review estimated API work, wall time, and quota use before anything runs. 4. Collect within the request's authorization and configured limits. 5. Review source-linked observations and prepare a brief.

The ask command saves the exact question and estimates work without collecting. A natural-language question is context for the research; it is not silently converted into one broad search. Collection is separate. A new area defaults to public Hacker News unless a source is selected. Nothing runs continuously or on a schedule.

Sources and access

Twenty-one sources. Fifteen use public endpoints with no provider key; six require credentials supplied by the operator.

No-key: Hacker News, Stack Exchange, Steam, Lemmy, App Store, Discourse, Mastodon, Bluesky, Lobste.rs, Firefox Add-ons, WordPress.org, Hugging Face, dev.to, Apple Podcasts, Open VSX. Keyed: YouTube (YOUTUBE_API_KEY), GitHub (GITHUB_TOKEN), Product Hunt (PRODUCTHUNT_API_TOKEN), Trustpilot (TRUSTPILOT_API_KEY), GitHub Discussions (same GITHUB_TOKEN), Agensi (AGENSI_SUPABASE_ANON_KEY).

Notable bounds: HN returns up to 20 comment hits per query (nested replies not collected); Stack Exchange up to 20 questions and 100 answers per question; Steam up to 300 reviews per game; Lemmy up to 50 comments per query per instance; App Store up to 60 recent reviews per app; Mastodon up to three tags and two timeline pages per query (no anonymous full-text search); Bluesky up to 25 posts per query with reply trees; YouTube discovers up to two search pages per phrase at shallow or deep comment depth; GitHub searches up to 10 pages of 30 results; dev.to maps queries to tags only (no full-text search); Apple Podcasts collects the ~50 most recent reviews per podcast at 1 request per 3 seconds.

No-key means no provider credential is needed; it does not mean unlimited or instantaneous. Every source uses bounded requests, has its own coverage rules, and may return partial results. Reviewed local custom adapters can extend the source set, but they are not built-in platforms.

Review and scoring

Collected observations are stored in local SQLite. The workflow can stream new hits and progress as JSON lines, review saved observations in an inbox, and create a Markdown research brief with source links. Briefs retain low-scoring and opposing observations by default, so a score does not silently discard counter-evidence.

Local regex scoring is the default and makes no inference API request. It ranks text using configured terms and signals; it does not determine truth, identity, prevalence, or market demand.

Optional model scoring uses a selected native OpenAI, Anthropic, or Gemini provider, or optional Cloudflare-based scoring. The operator supplies the credentials. When model scoring is selected, bounded comment text and its question or context are sent to that provider. Plans report model cost as unknown rather than calling the provider to estimate cost. Model scores are one review signal; they do not write research conclusions.

Honest limits

• On demand, not tracking. It does not monitor continuously.
• Public sources only. Nothing behind a login.
• Buyer brings their own API keys (YouTube, GitHub, Product Hunt, Trustpilot). Zero credential custody: I never see, store, or handle your keys.
• A bounded search can miss rare or older observations; zero hits do not establish absence. Counts depend on source coverage, query choices, timing, and scoring settings.
• Saved receipts describe completed batches, not exhaustive history cursors. A change in hit counts alone does not show a change in demand or severity.
• dev.to supports tag lookup, not full-text search; set expectations when choosing sources.
• Podcasts reviews are paced at 1 request per 3 seconds; larger sweeps take longer.

Data and limits

Research databases, reports, and quota history stay on the operator's machine. Source credentials are supplied by the operator and are not intentionally written to research databases. YouTube requests go to Google's API, GitHub requests go to GitHub, and selected text goes to a model provider only if the operator enables that scoring path.

Try the offline example

From a source checkout with Python 3.11 or later, choose a new output directory and run:

python3 examples/research_offline.py --out research-example

The example blocks network connections and uses fictional records; it needs no keys, model provider, or extra package. It writes synthetic briefs that show grouped text, visible counter-evidence, source context, partial-coverage handling, and a saved follow-up. These outputs do not establish live-source quality or demand. See the offline example guide.