# ur-whitelab/bo-icl architecture

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

- Interactive diagram: https://gitdiagram.com/ur-whitelab/bo-icl
- Repository: https://github.com/ur-whitelab/bo-icl

## Overview

##### Project type and purpose
- BO-ICL is a Python library (installable via pip) that wraps LLM calls (OpenAI API) to perform regression with uncertainty estimates and Bayesian optimization.
- It exposes a simple “AskTell” interface for users to feed data points, query predictions, run acquisition (“ask”), and perform inverse design.

##### File structure
Top–level:
- boicl/            ← core package modules
– asktell*.py     ← multiple strategy implementations (FewShotTopk, Finetuning, GPR, Ridge, NearestNeighbor)
– llm_model.py    ← adapter for LLM calls (handles prompt building, sending to OpenAI, reading token probabilities)
– pool.py         ← manages candidate sets for acquisition
– tool.py         ← helper routines (formatting, prompt templates)
- tests/            ← pytest suite (unit tests for each component)
- paper/            ← Jupyter notebooks & datasets (for experiments, not part of runtime)
- .github/          ← CI pipelines for build & tests
- setup.py, dev-requirements.txt

##### Main components
A. Client layer (User script / Notebook)
– “asktell = boicl.AskTell…”
– Calls tell(), predict(), ask(), inv_predict()
B. AskTell Strategy modules (Strategy Pattern)
– AskTellFewShotTopk, AskTellFinetuning, AskTellGPR, AskTellRidgeRegression, AskTellNearestNeighbor
– Each implements a common interface: tell(), predict(), ask(), inv_predict()
C. Pool manager
– Maintains candidate points, computes acquisition values, selects next query
D. LLM adapter (llm_model.py)
– Builds prompts (prefix, examples, suffix) using tool.py
– Calls OpenAI API (via openai-python client)
– Parses token probabilities → returns mean, uncertainty
E. Underlying libraries & external services
– OpenAI API (cloud service)
– scikit-learn (for GPR, Ridge, NearestNeighbor backends)
F. CI/Test pipeline
– GitHub Actions workflows trigger pytest against tests/
G. Distribution & Packaging
– setup.py / PyPI publication

##### Relationships and data flows
1. Client → AskTell Strategy:
- tell(x, y) updates internal dataset
- predict(x_new) → uses current strategy to form prompt
- ask(pool) → uses Pool manager + acquisition function
- inv_predict(target_y) → inverse design prompt
2. AskTell → Pool manager (for ask)
3. AskTell → LLM adapter
- Passes prompt → OpenAI API → receives token probs → returns distribution
4. AskTell (GPR/Ridge/NN variants) → scikit-learn modules for closed-form / kernel regression
5. CI pipeline → runs tests against boicl modules

##### Architectural patterns and design principles
- Strategy Pattern: many AskTell* classes share interface, swappable at runtime.
- Adapter Pattern: llm_model.py abstracts away OpenAI API specifics.
- Separation of Concerns: prompt formatting (tool.py) vs. model logic vs. acquisition logic.
- Extensibility: new AskTell* strategies can be added under boicl/

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        CL1["BO Experiments Notebook"]:::frontend
        CL2["Regression Experiments Notebook"]:::frontend
    end

    %% Library Core
    subgraph "BO-ICL Library" 
        direction TB
        AskTellBase["AskTell Base Interface"]:::frontend
        subgraph "AskTell Strategies" 
            direction TB
            FS["FewShotTopk"]:::frontend
            FT["Finetuning"]:::frontend
            GPR["GPR"]:::frontend
            RR["RidgeRegression"]:::frontend
            NN["NearestNeighbor"]:::frontend
        end
        Pool["Pool Manager"]:::core
        AQ["Acquisition Functions"]:::core
        LLM["LLM Adapter"]:::core
        Tool["Prompt Tools"]:::core
        Version["Version Info"]:::core
    end

    %% External Dependencies
    subgraph "External Dependencies" 
        direction TB
        OA["OpenAI API"]:::external
        SK["scikit-learn"]:::external
    end

    %% CI/CD & Testing
    subgraph "CI / CD & Tests" 
        direction TB
        Build["GitHub Actions Build"]:::ci
        TestWF["GitHub Actions Tests"]:::ci
        T1["Test AskTell"]:::ci
        T2["Test LLM Adapter"]:::ci
        T3["Test Prompt Tools"]:::ci
    end

    %% Distribution
    subgraph "Packaging & Distribution"
        direction TB
        Setup["setup.py"]:::ci
        DevReq["dev-requirements.txt"]:::ci
    end

    %% Data Flows
    CL1 -->|"invoke tell(), predict(), ask(), inv_predict()"| AskTellBase
    CL2 --> AskTellBase

    AskTellBase --> FS
    AskTellBase --> FT
    AskTellBase --> GPR
    AskTellBase --> RR
    AskTellBase --> NN

    AskTellBase -->|"ask() uses"| Pool
    Pool --> AQ

    AskTellBase -->|"build prompt"| Tool
    AskTellBase -->|"call adapter"| LLM
    LLM -->|"send prompt"| OA
    OA -->|"token probabilities"| LLM
    LLM -->|"returns distribution"| AskTellBase

    GPR -->|"uses"| SK
    RR --> SK
    NN --> SK

    Build --> TestWF
    TestWF --> T1
    TestWF --> T2
    TestWF --> T3

    %% Click Events
    click CL1 "https://github.com/ur-whitelab/bo-icl/blob/main/paper/BO_experiments.ipynb"
    click CL2 "https://github.com/ur-whitelab/bo-icl/blob/main/paper/Regression_experiments.ipynb"
    click AskTellBase "https://github.com/ur-whitelab/bo-icl/blob/main/boicl/asktell.py"
    click FS "https://github.com/ur-whitelab/bo-icl/blob/main/boicl/asktell.py"
    click FT "https://github.com/ur-whitelab/bo-icl/blob/main/boicl/asktellFinetuning.py"
    click GPR "https://github.com/ur-whitelab/bo-icl/blob/main/boicl/asktellGPR.py"
    click RR "https://github.com/ur-whitelab/bo-icl/blob/main/boicl/asktellRidgeRegression.py"
    click NN "https://github.com/ur-whitelab/bo-icl/blob/main/boicl/asktellNearestNeighbor.py"
    click Pool "https://github.com/ur-whitelab/bo-icl/blob/main/boicl/pool.py"
    click AQ "https://github.com/ur-whitelab/bo-icl/blob/main/boicl/aqfxns.py"
    click LLM "https://github.com/ur-whitelab/bo-icl/blob/main/boicl/llm_model.py"
    click Tool "https://github.com/ur-whitelab/bo-icl/blob/main/boicl/tool.py"
    click Version "https://github.com/ur-whitelab/bo-icl/blob/main/boicl/version.py"
    click T1 "https://github.com/ur-whitelab/bo-icl/blob/main/tests/test_AskTell.py"
    click T2 "https://github.com/ur-whitelab/bo-icl/blob/main/tests/test_LLM.py"
    click T3 "https://github.com/ur-whitelab/bo-icl/blob/main/tests/test_tool.py"
    click Build "https://github.com/ur-whitelab/bo-icl/blob/main/.github/workflows/build.yml"
    click TestWF "https://github.com/ur-whitelab/bo-icl/blob/main/.github/workflows/tests.yml"
    click Setup "https://github.com/ur-whitelab/bo-icl/blob/main/setup.py"
    click DevReq "https://github.com/ur-whitelab/bo-icl/blob/main/dev-requirements.txt"

    %% Styles
    classDef frontend fill:#CCE5FF,stroke:#004085,color:#004085;
    classDef core fill:#D4EDDA,stroke:#155724,color:#155724;
    classDef external fill:#FFF3CD,stroke:#856404,color:#856404;
    classDef ci fill:#E2E3E5,stroke:#6C757D,color:#6C757D;
```
