Skip to content

Installation

System Requirements

Requirement Minimum Recommended
Python 3.11 3.12
RAM 4 GB 16 GB
Disk 5 GB 20 GB
OS Linux / macOS / Windows WSL2 Ubuntu 22.04+

Memory for topic modeling

BERTopic loads sentence-transformer embedding models (~500 MB) and keeps topic clusters in memory. For corpora over 50,000 documents, 16 GB RAM is recommended. Use --embedding-model all-MiniLM-L6-v2 for a smaller footprint.

If you just want to use the scout CLI tool, install it globally with uv tool:

uv tool install git+https://github.com/ecoinfoai/social-scout.git

The scout command is immediately available system-wide — no virtual environment activation needed.

scout --version
# Social Scout, version 0.6.0

scout --help

Then jump to Step 3 — Configure API credentials.

Developer Install

For contributing, running tests, or modifying the code:

Step 1 — Clone the repository

git clone https://github.com/ecoinfoai/social-scout.git
cd social-scout

Step 2 — Create a virtual environment

uv venv --python 3.11
source .venv/bin/activate

uv venv --python 3.11
source .venv/bin/activate

The repository ships a flake.nix that provides Python and uv:

nix develop    # enter the dev shell (provides uv + Python 3.11)
uv venv
source .venv/bin/activate

Step 2 — Install dependencies

uv pip install -e ".[dev]"

This installs:

  • All runtime dependencies (Polars, BERTopic, CrewAI, GLiNER, …)
  • Development tools (pytest, mypy, ruff, mkdocs-material)
  • The scout CLI entry point (editable mode)

Alternative: pip

If you don't have uv installed, the standard pip workflow also works: 

python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Both invocation styles work after developer install:

scout --help          # after source .venv/bin/activate
uv run scout --help   # without activating the venv

Run the test suite to confirm everything works:

uv run pytest tests/ --ignore=tests/contract -q
# 268 passed in N.Ns

Step 3 — Configure API credentials

Social Scout reads credentials from ~/.config/social-scout/.env at startup (shell exports always take precedence).

mkdir -p ~/.config/social-scout
cp .env.example ~/.config/social-scout/.env

Then edit the file and fill in your keys:

$EDITOR ~/.config/social-scout/.env

Required API keys

Key Purpose Where to get it
APIFY_API_TOKEN Data collection console.apify.com/account/integrations
GEMINI_API_KEY Multi-agent analysis (Gemini) aistudio.google.com/app/apikey
ANTHROPIC_API_KEY Multi-agent analysis (Claude) console.anthropic.com/settings/keys

At least one LLM key (GEMINI_API_KEY or ANTHROPIC_API_KEY) is required for the analyze step.

Upgrading

uv tool upgrade social-scout

git pull origin master
uv pip install -e ".[dev]"

Troubleshooting

Visualization extras (Plotly + kaleido for PNG export)

The scout visualize command requires optional dependencies:

pip install 'social-scout[viz]'
# or
uv pip install -e ".[viz]"

This installs plotly, wordcloud, and kaleido (for high-resolution PNG export). If kaleido is absent, --export-png is skipped gracefully.

ModuleNotFoundError: No module named 'torch' Run uv pip install -e ".[dev]" — the full dependency set includes PyTorch.

CredentialError: APIFY_API_TOKEN not set Ensure ~/.config/social-scout/.env exists and contains your Apify token, or export it in your shell: export APIFY_API_TOKEN=apify_api_...

Out of memory during embedding Use a smaller embedding model: scout model <project> --embedding-model all-MiniLM-L6-v2

Slow first run The first run downloads sentence-transformer models (~500 MB) from Hugging Face. They are cached in ~/.cache/huggingface/ for subsequent runs.