Scholarly Infrastructure · 大师荟萃之楼

A batteries-included Python toolkit that helps ML/AI researchers run reproducible experiments, tune hyperparameters, and log results without rewriting boilerplate.

“所谓大学者，非谓有大楼之谓也，有大师之谓也。” ——梅贻琦

“A first-class university is not top for its grand infrastructures, but by its great scholars.” —— Mei Yiqi

Scholarly Infrastructure turns Mei Yiqi’s insight into engineering practice: great research is built on great infrastructure, not just one-off scripts. It is an open-source Python library that lets any ML/AI researcher manage experiment arguments, hyperparameter optimization, logging, and LLM access in a reproducible, composable way.

Introduction

Scholarly Infrastructure is a modular Python toolkit for machine-learning and AI research. Instead of re-implementing argument parsing, hyperparameter search, logging, and config loading for every project, you compose a small set of well-tested building blocks:

• declare experiment arguments once and reuse them as configs, command-line flags, and Optuna search spaces;
• turn an ordinary config-driven training script into a distributed hyperparameter study with a single command;
• log rich, ML-aware output — including PyTorch model structure and parameter summaries;
• call LLMs through one unified interface.

It is built with nbdev, so the documentation is the source code and every API ships with runnable notebooks.

Key Features

• rv_args — Arguments as Random Variables. Define hyperparameters and configs as typed dataclass fields and automatically derive an Optuna search space (get_optuna_search_space) and an argparse interface (argparse_parser_add_arguments). Reproducible, Bayesian-ready configuration with zero boilerplate.
• experiment.auto_optuna — Zero-code-change HPO. Wrap any config-driven research script into an Optuna study with tune (CMA-ES + Hyperband pruning) and ablation (grid search, fully reproducible) modes — no need to rewrite your training loop.
• logging — Rich, ML-aware logging. richuru-powered console output plus a torch helper that inspects model structure and parameter counts at a glance.
• llm_api — Unified LLM access. A single interface for calling LLMs inside research and data-processing pipelines.
• nbscholar — nbdev workflow helpers. separate / export / check commands that keep notebook-as-source development clean and reviewable.

Modules at a Glance

• rv_args — Declare experiment arguments and hyperparameters as typed dataclass fields (“random variables”); automatically derive Optuna search spaces (get_optuna_search_space) and argparse interfaces (argparse_parser_add_arguments). See 01_rv_args.ipynb.
• experiment — auto_optuna wraps any config-driven research script into an Optuna study, with tune (CMA-ES + Hyperband pruning) and ablation (grid search, reproducible) modes. See 01_experiment.ipynb.
• logging — richuru-based rich logging; the torch helper inspects model structure and parameter counts at a glance. See 02_logging.ipynb and 02a_torch.ipynb.
• llm_api — A single interface for calling LLMs inside research and data pipelines. See 04_llm_api.ipynb.
• nbscholar — nbdev workflow helpers (separate / export / check) that keep notebook-as-source development clean. See 03_nbscholar.ipynb.
• nucleus / help — Core infrastructure and the library overview. See 00_help.ipynb.

Installation

Install from the GitHub repository:

$ pip install git+https://github.com/THU-CVML/ScholarlyInfrastructure.git

or from pypi (published on PyPI):

$ pip install scholarly_infrastructure

Requires Python >= 3.7.

📖 Usage

Documentation

Full, runnable documentation lives in the src/notebooks/ directory (rendered with nbdev). Start with 00_help.ipynb for the library overview, then 01_rv_args.ipynb (arguments as random variables) and 01_experiment.ipynb (auto Optuna).

Quick Start

import scholarly_infrastructure as si

# The library is organized into composable, lazily-imported submodules:
si.rv_args     # arguments as random variables + Optuna / argparse bridges
si.experiment  # auto_optuna: turn config-driven runs into Optuna studies
si.logging     # rich, ML-aware logging (incl. PyTorch model inspection)
si.llm_api     # unified LLM access
si.nbscholar   # nbdev workflow helpers

Turn a config-driven training script into an Optuna study:

si.experiment.auto_optuna(mode="tune")      # CMA-ES + Hyperband
si.experiment.auto_optuna(mode="ablation")  # grid search, reproducible

See src/notebooks/01_rv_args.ipynb and 01_experiment.ipynb for complete, runnable examples.

🤝 Contributing

Contributions are welcome! Here’s how you can quickly get involved. Please review our contribution guidelines for more details.

git guide

1. Fork the repository and then git clone it to your local machine: git clone https://github.com/your-username/ScholarlyInfrastructure.git.\
2. Create a new branch for your feature or bug fix: git checkout -b feature-name.\
3. Commit your changes: git commit -m "Add feature-name".\
4. Push your branch: git push origin feature-name.\
5. Open a pull request and describe your changes.

---

nbdev framework guide

Our project utilizes nbdev to manage our codes, tests and documentation. If you are new to using nbdev here are some quick points to get you started.

1. Install this libary in Development mode

After you have cloned the repository, and before you start working on it, you need to pip install this library in development mode. This can be done using the following command:

# make sure NamableClassify package is installed in development mode
$ pip install -e .[dev]

2. make changes under notebooks/ directory

use #| export for exported codes.

3. check and synchronize before git commit

# compile to have changes apply to the python module
$ nbdev_prepare

License

This project is licensed under the Apache 2.0 License. You are free to use, modify, and distribute this software under the terms, provided you comply with the license’s conditions, including giving credit to the original authors and not using their trademarks.

Scholarly Infrastructure aims to be the quiet foundation beneath your next experiment — so you can spend less time wiring plumbing and more time on the science.