PyBlackwell

Blackwell approachability primitives for finite vector-payoff games, with explicit numerical certificates and reproducible experiment tooling.

Documentation · PyPI · Examples · Changelog · Security

PyBlackwell connects target-set geometry, finite games, minimax action selection, repeated-game solvers, and diagnostics in one NumPy-first API. The classical path covers bounded finite vector-payoff games, closed convex targets, full-information or expected-payoff updates, and exact or tolerance-controlled projection and minimax oracles. Extensions for calibration, partial feedback, online learning, and RL expose their additional assumptions instead of presenting numerical diagnostics as stronger guarantees.

Install

Install the base package, which depends only on NumPy, SciPy, and typing-extensions:

python -m pip install pyblackwell

PyBlackwell requires Python 3.10 or newer. The project CI currently tests CPython 3.10, 3.11, and 3.12 on Linux.

Quick start

This matching game has scalar payoffs -1 and 1; mixing both learner actions equally keeps the running payoff average at the point target {0}.

import numpy as np

from pyblackwell import BlackwellApproachability, MatrixGame, PointTarget

payoffs = np.array(
    [
        [[-1.0], [1.0]],
        [[1.0], [-1.0]],
    ]
)

game = MatrixGame(payoffs)
solver = BlackwellApproachability(game, PointTarget([0.0]))

for env_action in [0, 1] * 25:
    strategy = solver.strategy()
    solver.update(game.payoff(strategy, env_action), env_action=env_action)

certificate = solver.certificate()
print(
    {
        "iterations": certificate.iteration,
        "average": certificate.average.tolist(),
        "distance": certificate.distance,
    }
)

{'iterations': 50, 'average': [0.0], 'distance': 0.0}

The certificate records the running average, target projection, distance, separating normal, numerical status, and decision-time oracle result. Use solver.trace() for per-iteration histories or summary_only=True for bounded memory when only aggregate diagnostics are needed.

Why PyBlackwell?

• Closed-form and optimization-backed targets expose projection, containment, support, and separation through consistent result objects.
• Classical, OCO, regret-reduction, predictive, delayed, and adaptive solver variants share explicit state, certificate, and trace conventions.
• Full-information, bandit, and partial-monitoring helpers keep observation assumptions visible in diagnostics.
• Optional integrations stay behind extras and lazy imports, so the base package remains lightweight.
• Seeded examples, trace archives, benchmark metadata, and experiment manifests support reproducible numerical work.
• Stable, experimental, and private import paths are documented explicitly.

Compatibility and optional extras

Install only what a workflow needs, for example:

python -m pip install "pyblackwell[cvx,plot]"

PyBlackwell is currently an alpha 0.x project. The API policy identifies supported and experimental namespaces; pin a version when relying on experimental modules or numerical backend behavior.

Scope and limitations

PyBlackwell is for target-set approachability and related online-learning reductions. It is not a general convex optimization toolkit, an extensive-form game solver, or a proof that an arbitrary bandit or RL training loop satisfies the classical Blackwell assumptions. External game packages should own trees, information sets, CFR, sequence-form optimization, and equilibrium claims, with PyBlackwell consuming validated payoff or regret records through adapters.

Certificates describe the numerical computation that ran. Exact finite-game, approximate-oracle, bandit, sampled-calibration, and RL claims have different assumptions. Read the guarantee boundaries before interpreting positive residuals, approximation statuses, or realized sample paths.

Documentation

• Installation and extras
• Guided quickstart
• Application tutorials
• Concepts and theory
• API reference and stability policy
• Executable examples
• Architecture

Packaged example configurations and saved traces also have command-line entry points:

pyblackwell-example --list
pyblackwell-example matching-pennies-point
pyblackwell-trace-summary path/to/trace.npz
pyblackwell-benchmark run --mode smoke --iterations 20

Reproducible research

Library examples teach supported APIs; benchmarks/ tracks stable performance workloads; experiments/ evaluates scientific claims. Generated runs are not source files and belong under the ignored runs/ directory.

The corrected article experiment uses a frozen protocol, disjoint validation and test decisions, explicit seed streams, environment and source provenance, and checksummed result bundles:

OMP_NUM_THREADS=1 MKL_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 \
PYTHONPATH=src python experiments/article_contract_monitor_v2.py \
  --profile smoke --output-dir runs/article_v2_smoke

Use the immutable article profile only from a clean checkout. See the experiment policy, frozen protocol, and correction note. The comparison does not claim that Blackwell eliminates scalarization, and it keeps expected-update calibration separate from realized forecast error.

Support and development

Use the issue tracker for reproducible bugs and scoped feature requests. Read SUPPORT.md for the information to include and SECURITY.md for private vulnerability reporting.

Contributors can create the locked environment and run the same command contract used by CI:

uv sync --locked
make check
make package-check

Read the contribution guide and code of conduct before opening a merge request.

License and citation

PyBlackwell is released under the MIT License. For research use, cite the software using CITATION.cff and pin the release version used by the experiment.