If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/VowpalWabbit/vowpal_wabbit shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 1d ago
• 3 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Small team — 3 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 98% of recent commits
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live VowpalWabbit/vowpal_wabbit repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/VowpalWabbit/vowpal_wabbit.

What it runs against: a local clone of VowpalWabbit/vowpal_wabbit — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in VowpalWabbit/vowpal_wabbit | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of VowpalWabbit/vowpal_wabbit. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/VowpalWabbit/vowpal_wabbit.git
#   cd vowpal_wabbit
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of VowpalWabbit/vowpal_wabbit and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "VowpalWabbit/vowpal_wabbit(\\.git)?\\b" \\
  && ok "origin remote is VowpalWabbit/vowpal_wabbit" \\
  || miss "origin remote is not VowpalWabbit/vowpal_wabbit (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f ".github/workflows" \\
  && ok ".github/workflows" \\
  || miss "missing critical file: .github/workflows"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"
test -f ".scripts/linux/build.sh" \\
  && ok ".scripts/linux/build.sh" \\
  || miss "missing critical file: .scripts/linux/build.sh"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/VowpalWabbit/vowpal_wabbit"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Vowpal Wabbit is a high-performance online machine learning system optimized for streaming data and massive datasets. It implements state-of-the-art algorithms including contextual bandits, learning-to-search, and active learning with a focus on memory-bounded operation (using the hashing trick) and sparse gradient descent optimization that doesn't require loading full datasets into memory. Monorepo with core C++ engine in the root directory compiled via CMake, language-specific bindings in language-named subdirectories, build scripts in .scripts/ (separated by OS: linux/, macos/), GitHub Actions workflows in .github/workflows/, and Python packaging configuration (setup.py / pyproject.toml implied by pip dependency specs). The C++ core implements online learning algorithms (hashing, allreduce, reductions) compiled to a shared library consumed by wrapper bindings.

Machine learning practitioners and researchers building real-time recommendation systems, contextual bandit applications, and large-scale online learning pipelines who need fast, memory-efficient alternatives to batch-oriented frameworks like scikit-learn or XGBoost.

Highly mature and production-ready. The codebase spans 5.4M lines of C++ core with multi-language bindings (C#, Python, Java), extensive CI/CD across Linux/macOS/Windows (.github/workflows/ contains 20+ automated workflows including CodeQL security analysis), and comprehensive test coverage (upload_coverage.yml and test-with-coverage.sh indicate continuous coverage tracking). Active development is evident from the breadth of maintained build scripts and GitHub Actions pipelines.

Low risk for core functionality, but moderate complexity for contributors. The monorepo spans 15+ languages with C++ as the dominant engine (5.4M LOC), requiring C++ expertise to modify core algorithms. No obvious single-maintainer risk given institutional backing (GitHub org implies team), but the polyglot nature (C++/C#/Python/Java/Scala) means onboarding friction for changes crossing language boundaries. Dependency management spans vcpkg (Windows), CMake build system, and multiple language package managers (Python via numpy/scipy/scikit-learn, Java via Maven implied).

Active development across multiple dimensions: Python wheel builds and C# NuGet packaging (dotnet_nugets.yml, python_wheels.yml workflows), Java module publishing (java-publish.yml), WASM compilation support (wasm.yml), macOS-specific optimizations (build_macos.yml), benchmark automation (run_benchmarks.yml), and security scanning (codeql-analysis.yml, zizmor.yml). The breadth of CI workflows indicates parallel work across bindings and platforms.

Clone the repo, install dependencies, and build:

git clone https://github.com/VowpalWabbit/vowpal_wabbit.git
cd vowpal_wabbit
# For Linux/macOS:
bash .scripts/linux/build.sh
# Or use CMake directly:
mkdir build && cd build && cmake .. && make
# For Python bindings:
pip install -e .

See .scripts/ directory for OS-specific build scripts.

Daily commands: The system is primarily a library, not a standalone service. After building:

# Command-line usage:
vw [options] training_data.txt
# Python API:
import vowpalwabbit
model = vowpalwabbit.Workspace()
# See .scripts/linux/test.sh for full test suite execution
bash .scripts/linux/test.sh

• CMakeLists.txt — Core build configuration orchestrating compilation across C++, Python, Java, and .NET bindings; essential for any contributor setting up the development environment.
• README.md — High-level overview of Vowpal Wabbit's online learning algorithms and key techniques (hashing, allreduce, reductions); required reading to understand project scope and goals.
• .github/workflows — CI/CD pipeline definitions covering Linux, macOS, Windows, WASM, Java, and Python packages; defines the continuous integration contract all contributors must respect.
• CONTRIBUTING.md — Contributor guidelines documenting coding standards, PR process, and expected development practices for this multi-language ML system.
• .scripts/linux/build.sh — Primary Linux build entry point; demonstrates the canonical build process and dependencies required for local development.
• ThirdPartyNotices.txt — License compliance documentation; critical for understanding dependency obligations and legal constraints.
• Makefile — High-level build targets and task automation; quick reference for common developer operations like testing and packaging.

Add Support for a New Platform/Language Binding

1. Create a new workflow file in .github/workflows/ following the naming convention (e.g., build_rust.yml) that mirrors vendor_build.yml or build_macos.yml (.github/workflows/build_rust.yml)
2. Update CMakeLists.txt to add build targets and conditional compilation for the new language binding using if(ENABLE_<LANG>) blocks (CMakeLists.txt)
3. Add a build script in .scripts/<platform>/ that handles language-specific compilation and linking (.scripts/linux/rust.sh)
4. Create integration tests in big_tests/ with expected output files in big_tests/expected/ to validate end-to-end functionality (big_tests/HOWTO.write_new_tests.txt)
5. Update CONTRIBUTING.md with language-specific contribution guidelines and development setup instructions (CONTRIBUTING.md)

Add a New Machine Learning Reduction or Algorithm

1. Create a new C++ source file following the reduction pattern (e.g., src/core/reductions/my_reduction.cc) that implements the learner interface (src/core/reductions/my_reduction.cc)
2. Register the reduction in CMakeLists.txt under the appropriate source file list (e.g., VW_SOURCE_FILES) with proper compilation flags (CMakeLists.txt)
3. Add command-line argument parsing in the main CLI argument handler (reference .vscode/new_reduction.code-snippets for boilerplate) (.vscode/new_reduction.code-snippets)
4. Write integration tests in big_tests/ with test data and expected output to validate the reduction across different feature spaces (big_tests/HOWTO.write_new_tests.txt)
5. Document the algorithm, parameters, and usage examples in CONTRIBUTING.md under the algorithms section (CONTRIBUTING.md)

Improve Build Performance or Add a New Build Configuration

1. Add a new CMakePresets.json configuration entry for your build scenario (e.g., 'release-minimal' or 'debug-coverage'), following the existing preset structure (CMakePresets.json)
2. Create or modify a corresponding script in .scripts/linux/, .scripts/macos/, or .scripts/ that invokes CMake with your preset (.scripts/linux/build.sh)
3. Update the Makefile with a new target that calls your script, making it accessible via 'make <target>' (Makefile)
4. Add a new GitHub Actions workflow in .github/workflows/ to validate the build configuration in CI (e.g., build_minimal.yml) (.github/workflows/build_windows_cmake.yml)
5. Document the build option and rationale in CONTRIBUTING.md under the build configuration section (CONTRIBUTING.md)

Add Code Quality or Security Checks

1. Create a new GitHub Actions workflow file in .github/workflows/ (e.g., security_scan.yml) that defines the check job, triggers, and reporting (.github/workflows/zizmor.yml)
2. Update .clang-tidy or .clang-format to include new static analysis rules or formatting standards specific to your check (.clang-tidy)
3. Configure the check to run on all pull requests by setting appropriate triggers (on: [pull_request, push]) in your workflow (.github/workflows/lint.yml)
4. Document the rationale and how developers can run the check locally in CONTRIBUTING.md, linking to the workflow definition (CONTRIBUTING.md)

• CMake — Cross-platform build system supporting Windows, macOS, Linux, and WASM; enables multi-language binding generation (Python, Java, .NET, R) from single source tree
• C++ — Core ML engine requiring high-performance online learning with lock-free algorithms; enables memory-efficient streaming on large datasets
• GitHub Actions — Multi-

1. Polyglot build complexity: Changing C++ core requires rebuilding bindings for all languages (Python wheels, C# NuGet, Java JAR); broken C++ can silently fail in language-specific CI. 2) CMake intricacies: Build system uses vcpkg for Windows dependencies (see .github/workflows/vcpkg_build.yml); missing vcpkg manifest can cause platform-specific failures. 3) Python binding versioning: setup.py / pyproject.toml must match C++ version; mismatches cause runtime import failures. 4) Feature hashing behavior: The core feature hashing mechanism has non-obvious collision semantics; changing hash parameters breaks existing model serialization. 5) Test data paths: Build scripts assume specific relative paths (.scripts/linux/test.sh); running tests from wrong directory fails silently. 6) Flatbuffers serialization: See .scripts/linux/test-flatbuffers.sh and .scripts/linux/install-flatbuffers.sh; flatbuffers is a hidden dependency for model serialization.

• Feature Hashing (Hashing Trick) — VW's core feature to achieve bounded memory footprint independent of feature cardinality; critical to understanding why VW scales to billion-feature datasets that would OOM other systems
• Online Learning / Stochastic Gradient Descent — VW's foundational algorithm that learns incrementally from streaming data without loading full dataset; enables real-time model updates rare in batch systems
• Contextual Bandit Algorithms — VW's primary specialization (implemented algorithms like LinUCB, etc.); essential for understanding VW's advantage in reinforcement learning / recommendation scenarios
• AllReduce (Distributed Aggregation) — VW supports distributed training via AllReduce consensus; enables scaling across machines without centralized aggregator, critical for large-scale deployments
• Reductions Framework — VW's modular architecture reducing complex ML problems to simpler ones (e.g., multi-class to binary classification); understanding reductions is key to extending VW with new algorithms
• Learning-to-Search (L2S) — VW algorithm for structured prediction (sequence labeling, parsing); differentiates VW from general-purpose frameworks and powers NLP use cases
• Flatbuffers Serialization — VW uses Flatbuffers (not Protocol Buffers) for model serialization; understanding this format is critical for model persistence, versioning, and cross-language compatibility

• scikit-learn/scikit-learn — Alternative ML library; scikit-learn is batch-oriented while VW is online/streaming, solving complementary use cases for real-time learning
• tensorflow/tensorflow — General-purpose ML framework; TensorFlow supports online learning via eager execution, but lacks VW's memory-bounded guarantees and contextual bandit specialization
• facebook/vowpal_wabbit_js — Official JavaScript binding for VW; allows running VW models in browser/Node.js environments, extending the ecosystem
• apache/mahout — Distributed ML library with online learning; Mahout runs on Spark while VW is single-machine optimized, representing different scaling philosophies
• online-ml/river — Modern pure-Python online learning library; River serves similar use cases (streaming ML) but with pure-Python simplicity vs. VW's C++ performance

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive CI workflow for Python package validation across all supported versions

The repo has python_checks.yml and python_wheels.yml workflows, but there's no dedicated workflow testing the vowpalwabbit Python package against the dependency matrix (numpy>=1.6.1, scipy>=0.9, scikit-learn>=0.17, pandas>=0.24.2, matplotlib>=3.4.0) on multiple Python versions (3.8-3.12). This would catch compatibility regressions early and validate the MANIFEST.in configuration works correctly.

• [ ] Create .github/workflows/python_package_matrix_test.yml
• [ ] Add matrix strategy for Python versions 3.8, 3.9, 3.10, 3.11, 3.12
• [ ] Add matrix strategy for dependency versions (minimum versions vs latest)
• [ ] Include test step that imports vowpalwabbit and runs basic functionality
• [ ] Reference dependencies from setup.py/setup.cfg or pyproject.toml
• [ ] Add badge to README.md

Add integration tests for Java/JNI bindings in native build pipeline

The repo has java.yml and java-publish.yml workflows, but reviewing the structure shows no dedicated integration test workflow that validates the Java bindings work correctly against the native C++ library across platforms. Add tests that compile JNI code, load the native library, and run basic prediction/training operations.

• [ ] Create .github/workflows/java_integration_tests.yml
• [ ] Add matrix for Linux, macOS, Windows platforms
• [ ] Include steps to build native library and Java bindings together
• [ ] Add unit tests that verify JNI method signatures match native implementations
• [ ] Include sample Java code execution test (e.g., train/predict loop)
• [ ] Integrate with existing java.yml workflow

Add WebAssembly (WASM) functional test suite with E2E validation

The repo has wasm.yml workflow for building WASM, but no corresponding test suite validating that the compiled WASM module works correctly in browser/Node.js environments with actual model training/prediction. The current setup likely only verifies compilation, not functionality.

• [ ] Create .github/workflows/wasm_functional_tests.yml or enhance existing wasm.yml
• [ ] Add test suite in a new directory (e.g., test/wasm/ or contrib/wasm_tests/)
• [ ] Include Node.js-based tests for WASM module instantiation and basic operations
• [ ] Add browser-based tests using headless Chrome/Firefox for DOM interaction
• [ ] Test serialization/deserialization of models to/from WASM
• [ ] Validate memory usage and performance characteristics
• [ ] Reference the test suite in CONTRIBUTING.md for WASM development

• Add missing Python docstrings to the public API in python/ bindings; currently many functions lack examples in their docstrings, making the library harder to discover. Start by running pydoc vowpalwabbit and comparing to actual usage in wiki examples.
• Extend .editorconfig and add rules for ANTLR grammar files (seen in file list: .antlr files present but no linting enforcement); these are currently style-inconsistent. Check .github/workflows/lint.yml to understand lint pipeline, then propose rules.
• Create a minimal Dockerfile in .devcontainer/ for consistent cross-platform CI testing; currently .devcontainer/devcontainer.json exists but has no accompanying build script. This would reduce 'works on my machine' issues for contributors.

The Vowpal Wabbit repository demonstrates a moderate security posture with active security tooling (CodeQL, ASAN, Valgrind) integrated into CI/CD pipelines. However, critical concerns include outdated minimum dependency versions with known vulnerabilities and incomplete security documentation. The project should prioritize updating dependency constraints to current versions, implementing automated vulnerability scanning in the dependency pipeline, and establishing formal security disclosure policies. The large codebase (C++, Python, Java, .NET components) increases attack surface, but multi-platform testing workflows suggest quality assurance practices are in place.

• Medium · Outdated Dependency Versions — Package dependencies specification. The dependencies file specifies minimum versions that are significantly outdated. numpy>=1.6.1 (released 2013), scipy>=0.9 (released 2012), scikit-learn>=0.17 (released 2016), and pandas>=0.24.2 (released 2019) have multiple security patches and vulnerability fixes in newer versions. These old versions may contain known CVEs. Fix: Update minimum versions to recent stable releases: numpy>=1.24.0, scipy>=1.10.0, scikit-learn>=1.3.0, pandas>=2.0.0, matplotlib>=3.7.0. Regularly audit dependencies using tools like safety, pip-audit, or dependabot.
• Medium · Potential Missing Security Headers Configuration — Repository root and configuration files. No visible security configuration files (.env.example, security.json, or SECURITY.md) for managing sensitive configuration. The project lacks evidence of security header configurations or environment variable validation patterns in the provided file structure. Fix: Implement SECURITY.md file documenting security policies, create .env.example for environment variable documentation, and ensure all configuration handling validates and sanitizes inputs. Use environment variables for sensitive data rather than hardcoding.
• Low · Code Quality Analysis Tools May Be Underutilized — .github/workflows/ and configuration files. While the repository includes .clang-tidy and CodeQL configuration, the effectiveness depends on enforcement in CI/CD. The presence of multiple workflow files suggests varying levels of security gate implementation. Fix: Ensure all security-related workflows (codeql-analysis.yml, asan.yml, valgrind.yml) are mandatory for PR merges. Enable branch protection rules that require passing security checks.
• Low · Third-Party Dependencies Documentation — ThirdPartyNotices.txt and dependency management. ThirdPartyNotices.txt exists, but the visibility and maintenance of third-party license and security tracking is unclear. Machine learning libraries often have complex transitive dependencies. Fix: Maintain an automated Software Bill of Materials (SBOM) using tools like CycloneDX or SPDX. Implement automated dependency vulnerability scanning in CI/CD pipeline with tools like Snyk or Dependabot.
• Low · Lack of Security Contact Information — Repository root. No visible SECURITY.md or security contact information in the provided file listing. This makes it difficult for security researchers to responsibly report vulnerabilities. Fix: Create a SECURITY.md file at the repository root documenting the vulnerability disclosure policy and security contact email as per GitHub's recommended practices.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.