# david-cortes/contextualbandits architecture

> Architecture diagram of the GitHub repository david-cortes/contextualbandits, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/david-cortes/contextualbandits
- Repository: https://github.com/david-cortes/contextualbandits

## Overview

##### Project type and purpose
- This is an open-source Python library for implementing and experimenting with contextual bandit algorithms (online learning, off-policy evaluation, policy evaluation).
- It provides research-grade implementations of many algorithms (LinUCB, Thompson Sampling variants, OffsetTree, Doubly-Robust estimators, etc.), with performance-critical parts in Cython/C++.

##### File structure
Top-level:
- setup.py, pyproject.toml, setup.cfg, requirements.txt – packaging and build scripts (PEP 517, setuptools configuration, Cython compilation flags).
- LICENSE, MANIFEST(.in), .gitignore, .gitattributes – repository metadata and packaging manifests.
- README.md – project overview, usage, algorithms list, dependency notes.
- docs/ – Sphinx documentation (conf.py, index.rst, Makefile, ReadTheDocs config).
- example/ – Jupyter notebooks demonstrating typical workflows (online, off-policy, evaluation).
- plots/ – PNG figures used in README or docs.
Package “contextualbandits/”:
- __init__.py – package entry point and metadata.
- _cy_utils.pyx & cy_cpp_helpers.cpp – Cython wrappers and helper C++ code for performance-critical linear algebra.
- linreg/ – incremental linear regression implementation with Cython kernels (linreg_double.pyx, linreg_float.pyx, untyped .pxi).
- online.py – online learning policies (UCB, Thompson Sampling, Epsilon-Greedy, etc.).
- offpolicy.py – counterfactual learning algorithms (Offset Tree, Doubly-Robust).
- evaluation.py – policy evaluation methods (Rejection Sampling, NCIS, Doubly-Robust evaluation).
- utils.py – shared utilities (matrix conversions, CSR handling, hyperparameter smoothing).

##### README for additional insights
- Core use-cases: prototyping algorithms, reproducing research, learning about contextual bandits.
- Highlights extensibility via any classifier with predict_proba/decision_function.
- Notes on Cython compilation flags (`-march=native`), cross-machine compatibility, pickling via cloudpickle/dill.
- References to academic papers and performance notes.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build & Packaging
    subgraph "Build & Packaging"
        Setup["setup.py / pyproject.toml / setup.cfg / requirements.txt"]:::build
    end

    %% Documentation
    subgraph "Documentation"
        Conf["docs/conf.py"]:::docs
        Index["docs/index.rst"]:::docs
        MakefileD["docs/Makefile"]:::docs
        Rtd["docs/.readthedocs.yaml"]:::docs
        ReqD["docs/requirements.txt"]:::docs
    end

    %% Examples
    subgraph "Example Workflows"
        Ex1["example/online_contextual_bandits.ipynb"]:::examples
        Ex2["example/offpolicy_learning.ipynb"]:::examples
        Ex3["example/policy_evaluation.ipynb"]:::examples
    end

    %% Core Library
    subgraph "Core Library (contextualbandits)"
        API["contextualbandits/__init__.py"]:::api

        subgraph "Policy Modules"
            Online["contextualbandits/online.py"]:::core
            Offpolicy["contextualbandits/offpolicy.py"]:::core
            Evaluation["contextualbandits/evaluation.py"]:::core
        end

        Utils["contextualbandits/utils.py"]:::core

        subgraph "Linreg Kernels"
            LRDouble["contextualbandits/linreg/linreg_double.pyx"]:::perf
            LRFloat["contextualbandits/linreg/linreg_float.pyx"]:::perf
            LRUntyped["contextualbandits/linreg/linreg_untyped.pxi"]:::perf
        end

        subgraph "Cython/C++ Extensions"
            CYUTIL["contextualbandits/_cy_utils.pyx"]:::perf
            CPPHELP["contextualbandits/cy_cpp_helpers.cpp"]:::perf
        end
    end

    %% External Dependencies
    subgraph "External Dependencies"
        NumPy["NumPy/SciPy"]:::external
        SK["scikit-learn / XGBoost"]:::external
        Toolchain["C Compiler Toolchain"]:::external
        Pickle["cloudpickle / dill"]:::external
    end

    %% Data Flow
    Features["Feature Inputs"]:::external
    Action["Action Selection"]:::core
    Reward["Reward Feedback"]:::external
    Update["Model Update"]:::core
    EvalFlow["Evaluation Modules"]:::core

    Features -->|ingest| Online
    Online -->|"compute scores"| CYUTIL
    CYUTIL -->|"linear algebra ops"| CPPHELP
    Online -->|select action| Action
    Action --> Reward
    Reward -->|update| Online
    Reward -->|evaluate| Evaluation
    Evaluation --> EvalFlow

    %% Dependencies
    API --> Online
    API --> Offpolicy
    API --> Evaluation
    API --> Utils
    API --> LRDouble
    API --> LRFloat
    API --> LRUntyped
    API --> CYUTIL
    API --> CPPHELP
    API --> NumPy
    API --> SK
    Setup -->|"compiles"| CYUTIL
    Setup -->|"compiles"| LRDouble
    Setup -->|"compiles"| LRFloat
    Setup -->|"compiles"| LRUntyped
    Examples --> Online
    Examples --> Offpolicy
    Examples --> Evaluation
    Docs --> API

    %% Click Events
    click API "https://github.com/david-cortes/contextualbandits/blob/master/contextualbandits/__init__.py"
    click CYUTIL "https://github.com/david-cortes/contextualbandits/blob/master/contextualbandits/_cy_utils.pyx"
    click CPPHELP "https://github.com/david-cortes/contextualbandits/blob/master/contextualbandits/cy_cpp_helpers.cpp"
    click LRDouble "https://github.com/david-cortes/contextualbandits/blob/master/contextualbandits/linreg/linreg_double.pyx"
    click LRFloat "https://github.com/david-cortes/contextualbandits/blob/master/contextualbandits/linreg/linreg_float.pyx"
    click LRUntyped "https://github.com/david-cortes/contextualbandits/blob/master/contextualbandits/linreg/linreg_untyped.pxi"
    click Online "https://github.com/david-cortes/contextualbandits/blob/master/contextualbandits/online.py"
    click Offpolicy "https://github.com/david-cortes/contextualbandits/blob/master/contextualbandits/offpolicy.py"
    click Evaluation "https://github.com/david-cortes/contextualbandits/blob/master/contextualbandits/evaluation.py"
    click Utils "https://github.com/david-cortes/contextualbandits/blob/master/contextualbandits/utils.py"
    click Setup "https://github.com/david-cortes/contextualbandits/blob/master/setup.py"
    click Docs "https://github.com/david-cortes/contextualbandits/tree/master/docs/"
    click Ex1 "https://github.com/david-cortes/contextualbandits/blob/master/example/online_contextual_bandits.ipynb"
    click Ex2 "https://github.com/david-cortes/contextualbandits/blob/master/example/offpolicy_learning.ipynb"
    click Ex3 "https://github.com/david-cortes/contextualbandits/blob/master/example/policy_evaluation.ipynb"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:1px
    classDef perf fill:#bbf,stroke:#333,stroke-width:1px
    classDef external fill:#afa,stroke:#333,stroke-width:1px
    classDef build fill:#ffb,stroke:#333,stroke-width:1px
    classDef docs fill:#fbe,stroke:#333,stroke-width:1px
    classDef examples fill:#eef,stroke:#333,stroke-width:1px
    classDef api fill:#fcf,stroke:#333,stroke-width:1px
```
