How ur-whitelab/bo-icl works
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/