Installation

Requirements

Install from PyPI

Install the latest stable release:

uv pip install bead

Install from Source

For the latest development version:

git clone https://github.com/FACTSlab/bead.git
cd bead
uv sync

Development Installation

For contributing to bead, install with all development dependencies:

uv sync --all-extras

This installs: - dev: testing and linting tools (pytest, ruff, pyright) - api: model adapters (OpenAI, Anthropic, Google, HuggingFace) - training: active learning dependencies (PyTorch, transformers)

Verify Installation

Check that bead is installed correctly:

uv run python -c "import bead; print(bead.__version__)"

Or use the CLI:

uv run bead --version

Optional Dependencies

Install specific dependency groups as needed:

# HuggingFace models for template filling and active learning
uv sync --extra api

# Active learning with PyTorch
uv sync --extra training

# Tokenization and dependency parsing (spaCy, Stanza)
uv sync --extra tokenization

# Corpus ingestion, including Zstandard-compressed (.zst) files
uv sync --extra corpus

# All dependencies
uv sync --all-extras

Structural corpus sampling (parsing a corpus and keeping only sentences whose dependency structure matches a constraint) needs both the corpus and tokenization extras:

uv sync --extra corpus --extra tokenization

TypeScript Development (jsPsych Plugins)

If you need to modify or rebuild the jsPsych plugins, install Node.js dependencies:

# Install pnpm (if not installed)
npm install -g pnpm

# Install TypeScript dependencies
cd bead/deployment/jspsych
pnpm install

# Build TypeScript to JavaScript
pnpm build

# Run type checking
pnpm typecheck

# Run linting (Biome)
pnpm check

The compiled JavaScript is output to bead/deployment/jspsych/dist/.

Troubleshooting

Python Version

Verify you have Python 3.14+:

python --version

If not, install from python.org or use pyenv:

pyenv install 3.14.0
pyenv local 3.14.0

Common Issues

Issue: ModuleNotFoundError: No module named 'bead' Solution: Ensure you are using uv run to execute Python commands.

Issue: ImportError for optional dependencies Solution: Install the required extra, e.g., uv sync --extra api

Next Steps

Continue to the Quick Start guide for a complete tutorial.