Quick Start¶

Get a complete social media analysis running in under 10 minutes.

Prerequisites¶

Social Scout installed
APIFY_API_TOKEN set in ~/.config/social-scout/.env
GEMINI_API_KEY or ANTHROPIC_API_KEY set in ~/.config/social-scout/.env

Option A — One command (fastest)¶

The scout run command chains all four pipeline steps automatically:

scout project create agentic-commerce

scout run agentic-commerce \
  --keywords "agentic commerce,AI shopping,autonomous purchasing" \
  --communities technology,futurology \
  --sort top --time year \
  --max-items 2000 \
  --all-techniques

When it finishes, your report is at:

projects/agentic-commerce/reports/report.md

Option B — Step by step¶

Running steps individually lets you inspect and re-run each stage without restarting from scratch.

1. Create a project¶

scout project create agentic-commerce \
  --description "Public discourse on AI-driven autonomous purchasing agents"

This creates a directory at projects/agentic-commerce/ with the required subdirectories.

2. Collect data¶

scout collect agentic-commerce \
  --keywords "agentic commerce,AI shopping,autonomous purchasing" \
  --communities technology,futurology,singularity \
  --sort top \
  --time year \
  --max-items 5000 \
  --include-comments

Option	Default	Description
`--keywords`	—	Comma-separated search terms
`--communities`	—	Subreddit names (without `r/`)
`--platform`	`reddit`	Platform to collect from
`--sort`	`relevance`	`top`, `new`, `hot`, `relevance`
`--time`	`all`	`day`, `week`, `month`, `year`, `all`
`--max-items`	`1000`	Maximum records to collect
`--include-comments`	off	Also collect post comments

Output: projects/agentic-commerce/raw/raw_data.ndjson

3. Preprocess¶

scout preprocess agentic-commerce --min-length 30

Cleans text, removes duplicates, and optionally extracts named entities or sentiment:

scout preprocess agentic-commerce \
  --min-length 30 \
  --extract-entities \
  --entity-labels "BRAND,PRODUCT,PERSON,ORG" \
  --entity-threshold 0.5 \
  --sentiment

Option	Default	Description
`--min-length`	`20`	Minimum character length for cleaned text
`--extract-entities`	off	Run GLiNER NER extraction
`--sentiment`	off	Add `sentiment_label`/`sentiment_score` columns

Output: projects/agentic-commerce/cleaned/cleaned_data.parquet

4. Model topics¶

# Quick: run just the basic technique
scout model agentic-commerce --techniques basic

# Full: run all 7 techniques
scout model agentic-commerce --all-techniques

Available techniques: basic, dynamic, hierarchical, class-based, sentiment-topic, network, zero-shot

Output: projects/agentic-commerce/topics/topics.parquet

5. Run multi-agent analysis¶

scout analyze agentic-commerce

Five AI agents (Data Analyst, Consumer Psychologist, Strategy Advisor, Critical Reviewer, Chief Theorist) analyze the topic model and produce a structured report.

# Korean-language report with Claude + Gemini ensemble
scout analyze agentic-commerce \
  --llm ensemble \
  --report-language korean

Option	Default	Description
`--llm`	`ensemble`	`claude`, `gemini`, or `ensemble` (mixed)
`--report-language`	`english`	`english` or `korean`

Output: - projects/agentic-commerce/reports/report.md — Markdown report - projects/agentic-commerce/reports/analysis_meta.json — Run metadata

Reading the output¶

# Project status overview
scout project info agentic-commerce

# Read the report
cat projects/agentic-commerce/reports/report.md

# Or open in your editor
$EDITOR projects/agentic-commerce/reports/report.md

The report contains:

Executive Summary — high-level synthesis from the Chief Theorist
Key Findings by Perspective — findings from each agent with source citations
Source Citations Index — numbered index of all cited records

Generating the dashboard¶

# Basic interactive HTML dashboard
scout visualize agentic-commerce --open

# With LLM interpretations + PNG export (requires pip install 'social-scout[viz]')
scout visualize agentic-commerce \
  --interpret \
  --export-png \
  --report-language korean \
  --open

Option	Description
`--open`	Open dashboard in browser immediately
`--interpret`	Add LLM-written interpretation boxes per section
`--export-png`	Export all charts as high-res PNGs + write `visualization_report.md`
`--report-language`	`english` or `korean` for interpretation text
`--llm`	`claude` (default) or `gemini` for interpretations

Output directory: projects/agentic-commerce/visualizations/

Next steps¶

Read the Tutorial for a deeper walkthrough with interpretation guidance
See Sentiment Analysis for sentiment scoring and perception charts
See Configuration for advanced settings and LLM model selection