diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 0f95027c..d4dad0bb 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -130,6 +130,7 @@ Any function or method parameter typed `bool` (or with a boolean default) must b # BAD def estimate(self, y_true: NDArray, y_proxy: NDArray, power_tuning: bool = True) -> ...: ... + # GOOD def estimate(self, y_true: NDArray, y_proxy: NDArray, *, power_tuning: bool = True) -> ...: ... ``` @@ -181,10 +182,18 @@ Strings, comments and docstrings (including notebook code cells) must not contai These three document types have distinct purposes and must not bleed into each other. -- **Tutorials** show how to use the public API. They must not expose private attributes or methods, must not be math-heavy (that belongs in the user guide), and must tell a coherent end-to-end story. If a tutorial section feels like it is documenting the implementation rather than teaching usage, move it or cut it. +- **Tutorials** show how to use the public API. They must not expose private attributes or methods, must not be math-heavy (that belongs in the user guide), and must tell a coherent end-to-end story. If a tutorial section feels like it is documenting the implementation rather than teaching usage, move it or cut it. Tutorials must also stay lean: no Monte Carlo loops, no coverage sweeps, no helper machinery for validation-style analyses (those belong in deep dives, which the tutorial links to at the end). Mirror the closest sibling tutorial section by section: same summary table, at most 3 key takeaways (each adding something the others do not), and the same closing "Want to go further?" line linking to the scientific validation notebook. - **Deep dives / validation notebooks** are for scientific validation. They test the statistical validity of one or more workflows, where each workflow covers a full pipeline: data generation, annotation, then estimation. Results are stochastic and depend on a random seed. Monte Carlo simulations must use a single external loop over seeds, calling each workflow once per iteration. Note that workflows do not fully isolate from each other: data generation is typically shared across them. Figures must appear at the right point in the narrative. - **User guides** document the mathematical foundations of each implemented method (sampling or estimation). For each method, lay out the mathematical setting: expected inputs, computed quantities, and their main properties, taking inspiration from pre-existing sections in the guide. When a reference paper exists, formulas must be consistent with it; notation may diverge from the paper when needed to preserve consistency across the guide as a whole. Never reference the implementation directly: no pseudocode, no mentions of class or method names. +#### Tutorial baselines + +A comparison is only informative if each baseline differs from the featured method by exactly one ingredient. A baseline that differs on two confounds the conclusion. + +- Before writing a tutorial, list the ingredients of the featured method (proxy labels, data structure such as strata, clusters or several proxies, sampling design, anytime validity). Each baseline in the comparison table must remove exactly one of them and keep all the others. +- A takeaway may only attribute a gain to the ingredient the comparison isolates. Do not credit the proxy labels or the structure for a speed-up that the chosen baselines cannot separate. +- If the matching baseline does not exist in the library, stop. Do not write the tutorial against a substitute. Report the missing estimator or monitor to the user, so a ticket can be opened and the tutorial put on hold. + #### Scientific consistency in notebooks Figures, printed values, and inline text must be mutually consistent — if the text says one number and the figure or table shows another, all occurrences must be corrected together. Sampling rules and notation must match the paper (e.g., πᵢ ∈ (0,1), not [0,1], in theory sections). Statistical framing must be precise: never say "removes bias" without specifying which bias. Avoid stating explicit variable or experimental numerical values (rates, delays, batch counts, percentages) directly in prose; describe results qualitatively instead (e.g., "detects faster", "stays within budget") and let the figures, tables, and printed cell outputs carry the precise numbers, so nothing in the text needs to be hand-updated when the notebook is re-run or its parameters change. @@ -214,4 +223,4 @@ Use Conventional Commits prefixes: ### Consistency and Propagation -Before adding a new class, function, or module, find the nearest equivalent already in the codebase and verify that the new code mirrors it in structure, naming, and block ordering. When a good pattern appears in new code that the existing code lacks, propagate it to the existing code in the same PR. When a rename or refactor touches one site, grep for all other sites that use the old name and update them before considering the work done. +Before adding a new class, function, or module, find the nearest equivalent already in the codebase and verify that the new code mirrors it in structure, naming, and block ordering. When a good pattern appears in new code that the existing code lacks, propagate it to the existing code in the same PR. When a rename or refactor touches one site, grep for all other sites that use the old name and update them before considering the work done. When adding an estimator or monitor for a new data structure or information source (strata, clusters, several proxies, active sampling), check that its label-only counterpart for the same structure exists. If it does not, it is part of the same deliverable, or a blocking dependency listed in the ticket. diff --git a/.github/workflows/draft_paper.yml b/.github/workflows/draft_paper.yml new file mode 100644 index 00000000..375f0b2a --- /dev/null +++ b/.github/workflows/draft_paper.yml @@ -0,0 +1,41 @@ +name: Draft paper PDF + +on: + push: + branches: [main] + paths: + - "JOSS/**" + - ".github/workflows/draft_paper.yml" + pull_request: + branches: [main] + paths: + - "JOSS/**" + - ".github/workflows/draft_paper.yml" + workflow_dispatch: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + paper: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7.0.1 + with: + persist-credentials: false + + - name: Build draft PDF + uses: openjournals/openjournals-draft-action@v1.0 + with: + journal: joss + paper-path: JOSS/paper.md + + - name: Upload draft PDF + uses: actions/upload-artifact@v7.0.1 + with: + name: joss-paper + path: JOSS/paper.pdf diff --git a/JOSS/glide-workflow.png b/JOSS/glide-workflow.png new file mode 100644 index 00000000..9483e03d Binary files /dev/null and b/JOSS/glide-workflow.png differ diff --git a/JOSS/paper.bib b/JOSS/paper.bib new file mode 100644 index 00000000..012a7d9d --- /dev/null +++ b/JOSS/paper.bib @@ -0,0 +1,354 @@ +@article{waudbysmith2024time, + title={Time-uniform central limit theory and asymptotic confidence sequences}, + author={Waudby-Smith, Ian and Arbour, David and Sinha, Ritwik and Kennedy, Edward H and Ramdas, Aaditya}, + journal={The Annals of Statistics}, + volume={52}, + number={6}, + pages={2613--2640}, + year={2024}, + publisher={Institute of Mathematical Statistics}, + doi={10.1214/24-AOS2408}, + url={https://doi.org/10.1214/24-AOS2408} +} + +@article{zhang2026prediction, + title={Prediction-Powered Risk Monitoring of Deployed Models for Detecting Harmful Distribution Shifts}, + author={Zhang, Guangyi and Cai, Yunlong and Yu, Guanding and Simeone, Osvaldo}, + journal={arXiv preprint arXiv:2602.02229}, + doi={10.48550/arXiv.2602.02229}, + url={https://arxiv.org/abs/2602.02229}, + year={2026} +} + +@article{podkopaev2021tracking, + title={Tracking the risk of a deployed model and detecting harmful distribution shifts}, + author={Podkopaev, Aleksandr and Ramdas, Aaditya}, + journal={arXiv preprint arXiv:2110.06177}, + doi={10.48550/arXiv.2110.06177}, + url={https://arxiv.org/abs/2110.06177}, + year={2021} +} + +@article{angelopoulos2023prediction, + title={Prediction-powered inference}, + author={Angelopoulos, Anastasios N and Bates, Stephen and Fannjiang, Clara and Jordan, Michael I and Zrnic, Tijana}, + journal={Science}, + volume={382}, + number={6671}, + pages={669--674}, + year={2023}, + publisher={American Association for the Advancement of Science}, + doi={10.1126/science.adi6000}, + url={https://doi.org/10.1126/science.adi6000} +} + +@article{angelopoulos2023ppiplusplus, + title={Ppi++: Efficient prediction-powered inference}, + author={Angelopoulos, Anastasios N and Duchi, John C and Zrnic, Tijana}, + journal={arXiv preprint arXiv:2311.01453}, + doi={10.48550/arXiv.2311.01453}, + url={https://arxiv.org/abs/2311.01453}, + year={2023} +} + +@article{song2026demystifying, + title={Demystifying Prediction Powered Inference}, + author={Song, Yilin and Kluger, Dan M and Parikh, Harsh and Gu, Tian}, + journal={arXiv preprint arXiv:2601.20819}, + doi={10.48550/arXiv.2601.20819}, + url={https://arxiv.org/abs/2601.20819}, + year={2026} +} + +@inproceedings{NEURIPS2024_c9fcd02e, + author = {Fisch, Adam and Maynez, Joshua and Hofer, R. Alex and Dhingra, Bhuwan and Globerson, Amir and Cohen, William W.}, + booktitle = {Advances in Neural Information Processing Systems}, + doi = {10.52202/079017-3541}, + editor = {A. Globerson and L. Mackey and D. Belgrave and A. Fan and U. Paquet and J. Tomczak and C. Zhang}, + pages = {111489--111514}, + publisher = {Curran Associates, Inc.}, + title = {Stratified Prediction-Powered Inference for Effective Hybrid Evaluation of Language Models}, + url = {https://proceedings.neurips.cc/paper_files/paper/2024/file/c9fcd02e6445c7dfbad6986abee53d0d-Paper-Conference.pdf}, + volume = {37}, + year = {2024} +} + +@inproceedings{fogliato2024framework, + title={A framework for efficient model evaluation through stratification, sampling, and estimation}, + author={Fogliato, Riccardo and Patil, Pratik and Monfort, Mathew and Perona, Pietro}, + booktitle={European Conference on Computer Vision}, + pages={140--158}, + year={2024}, + organization={Springer}, + doi={10.1007/978-3-031-73223-2_9}, + url={https://doi.org/10.1007/978-3-031-73223-2_9} +} + +@InProceedings{pmlr-v235-zrnic24a, + title = {Active Statistical Inference}, + author = {Zrnic, Tijana and Candes, Emmanuel}, + booktitle = {Proceedings of the 41st International Conference on Machine Learning}, + pages = {62993--63010}, + year = {2024}, + editor = {Salakhutdinov, Ruslan and Kolter, Zico and Heller, Katherine and Weller, Adrian and Oliver, Nuria and Scarlett, Jonathan and Berkenkamp, Felix}, + volume = {235}, + series = {Proceedings of Machine Learning Research}, + month = {21--27 Jul}, + publisher = {PMLR}, + pdf = {https://raw.githubusercontent.com/mlresearch/v235/main/assets/zrnic24a/zrnic24a.pdf}, + url = {https://proceedings.mlr.press/v235/zrnic24a.html}, + abstract = {Inspired by the concept of active learning, we propose active inference—a methodology for statistical inference with machine-learning-assisted data collection. Assuming a budget on the number of labels that can be collected, the methodology uses a machine learning model to identify which data points would be most beneficial to label, thus effectively utilizing the budget. It operates on a simple yet powerful intuition: prioritize the collection of labels for data points where the model exhibits uncertainty, and rely on the model’s predictions where it is confident. Active inference constructs valid confidence intervals and hypothesis tests while leveraging any black-box machine learning model and handling any data distribution. The key point is that it achieves the same level of accuracy with far fewer samples than existing baselines relying on non-adaptively-collected data. This means that for the same number of collected samples, active inference enables smaller confidence intervals and more powerful tests. We evaluate active inference on datasets from public opinion research, census analysis, and proteomics.} +} + +@inproceedings{gligoric2025can, + title={Can unconfident llm annotations be used for confident conclusions?}, + author={Gligori{\'c}, Kristina and Zrnic, Tijana and Lee, Cinoo and Candes, Emmanuel and Jurafsky, Dan}, + booktitle={Proceedings of the 2025 Conference of the Nations of the Americas Chapter of the Association for Computational Linguistics: Human Language Technologies (Volume 1: Long Papers)}, + pages={3514--3533}, + year={2025}, + doi={10.18653/v1/2025.naacl-long.179}, + url={https://doi.org/10.18653/v1/2025.naacl-long.179} +} + +@article{angelopoulos2025cost, + title={Cost-optimal active ai model evaluation}, + author={Angelopoulos, Anastasios N and Eisenstein, Jacob and Berant, Jonathan and Agarwal, Alekh and Fisch, Adam}, + journal={arXiv preprint arXiv:2506.07949}, + doi={10.48550/arXiv.2506.07949}, + url={https://arxiv.org/abs/2506.07949}, + year={2025} +} + +@article{kluger2025prediction, + title={Prediction-powered inference with imputed covariates and nonuniform sampling}, + author={Kluger, Dan M and Lu, Kerri and Zrnic, Tijana and Wang, Sherrie and Bates, Stephen}, + journal={arXiv preprint arXiv:2501.18577}, + doi={10.48550/arXiv.2501.18577}, + url={https://arxiv.org/abs/2501.18577}, + year={2025} +} + +@article{cowen2026multiple, + title={Multiple-Prediction-Powered Inference}, + author={Cowen-Breen, Charlie and Agarwal, Alekh and Bates, Stephen and Cohen, William W and Eisenstein, Jacob and Globerson, Amir and Fisch, Adam}, + journal={arXiv preprint arXiv:2603.27414}, + doi={10.48550/arXiv.2603.27414}, + url={https://arxiv.org/abs/2603.27414}, + year={2026} +} + +@article{shan2025sada, + title={SADA: Safe and Adaptive Aggregation of Multiple Black-Box Predictions in Semi-Supervised Learning}, + author={Shan, Jiawei and Chen, Zhifeng and Dong, Yiming and Wang, Yazhen and Zhao, Jiwei}, + journal={arXiv preprint arXiv:2509.21707}, + doi={10.48550/arXiv.2509.21707}, + url={https://arxiv.org/abs/2509.21707}, + year={2025} +} + +@inproceedings{yuan-etal-2024-r, + title = "{R}-Judge: Benchmarking Safety Risk Awareness for {LLM} Agents", + author = "Yuan, Tongxin and + He, Zhiwei and + Dong, Lingzhong and + Wang, Yiming and + Zhao, Ruijie and + Xia, Tian and + Xu, Lizhen and + Zhou, Binglin and + Li, Fangqi and + Zhang, Zhuosheng and + Wang, Rui and + Liu, Gongshen", + editor = "Al-Onaizan, Yaser and + Bansal, Mohit and + Chen, Yun-Nung", + booktitle = "Findings of the Association for Computational Linguistics: EMNLP 2024", + month = nov, + year = "2024", + address = "Miami, Florida, USA", + publisher = "Association for Computational Linguistics", + url = "https://aclanthology.org/2024.findings-emnlp.79/", + doi = "10.18653/v1/2024.findings-emnlp.79", + pages = "1467--1490", + abstract = "Large language models (LLMs) have exhibited great potential in autonomously completing tasks across real-world applications. Despite this, these LLM agents introduce unexpected safety risks when operating in interactive environments. Instead of centering on the harmlessness of LLM-generated content in most prior studies, this work addresses the imperative need for benchmarking the behavioral safety of LLM agents within diverse environments. We introduce R-Judge, a benchmark crafted to evaluate the proficiency of LLMs in judging and identifying safety risks given agent interaction records. R-Judge comprises 569 records of multi-turn agent interaction, encompassing 27 key risk scenarios among 5 application categories and 10 risk types. It is of high-quality curation with annotated safety labels and risk descriptions. Evaluation of 11 LLMs on R-Judge shows considerable room for enhancing the risk awareness of LLMs: The best-performing model, GPT-4o, achieves 74.42{\%} while no other models significantly exceed the random. Moreover, we reveal that risk awareness in open agent scenarios is a multi-dimensional capability involving knowledge and reasoning, thus challenging for LLMs. With further experiments, we find that fine-tuning on safety judgment significantly improve model performance while straightforward prompting mechanisms fail. R-Judge is publicly available at Annoymous." +} + +@article{martinon2026industrializing, + title={Industrializing Prediction-Powered Inference: The GLIDE Library for Reliable GenAI and Agentic Systems Evaluation}, + author={Martinon, Gr{\'e}goire and Merad, Ibrahim and Raki, Mohammed}, + journal={arXiv preprint arXiv:2605.31278}, + doi={10.48550/arXiv.2605.31278}, + url={https://arxiv.org/abs/2605.31278}, + year={2026} +} + +@inproceedings{yu-etal-2018-spider, + title = "{S}pider: A Large-Scale Human-Labeled Dataset for Complex and Cross-Domain Semantic Parsing and Text-to-{SQL} Task", + author = "Yu, Tao and + Zhang, Rui and + Yang, Kai and + Yasunaga, Michihiro and + Wang, Dongxu and + Li, Zifan and + Ma, James and + Li, Irene and + Yao, Qingning and + Roman, Shanelle and + Zhang, Zilin and + Radev, Dragomir", + editor = "Riloff, Ellen and + Chiang, David and + Hockenmaier, Julia and + Tsujii, Jun{'}ichi", + booktitle = "Proceedings of the 2018 Conference on Empirical Methods in Natural Language Processing", + month = oct # "-" # nov, + year = "2018", + address = "Brussels, Belgium", + publisher = "Association for Computational Linguistics", + url = "https://aclanthology.org/D18-1425/", + doi = "10.18653/v1/D18-1425", + pages = "3911--3921", + abstract = "We present \textit{Spider}, a large-scale complex and cross-domain semantic parsing and text-to-SQL dataset annotated by 11 college students. It consists of 10,181 questions and 5,693 unique complex SQL queries on 200 databases with multiple tables covering 138 different domains. We define a new complex and cross-domain semantic parsing and text-to-SQL task so that different complicated SQL queries and databases appear in train and test sets. In this way, the task requires the model to generalize well to both new SQL queries and new database schemas. Therefore, Spider is distinct from most of the previous semantic parsing tasks because they all use a single database and have the exact same program in the train set and the test set. We experiment with various state-of-the-art models and the best model achieves only 9.7{\%} exact matching accuracy on a database split setting. This shows that Spider presents a strong challenge for future research. Our dataset and task with the most recent updates are publicly available at \url{https://yale-lily.github.io/seq2sql/spider}." +} + +@inproceedings{cruz-blandon-etal-2025-memerag, + title = "{MEMERAG}: A Multilingual End-to-End Meta-Evaluation Benchmark for Retrieval Augmented Generation", + author = "Cruz Bland{\'o}n, Mar{\'i}a Andrea and + Talur, Jayasimha and + Charron, Bruno and + Liu, Dong and + Mansour, Saab and + Federico, Marcello", + editor = "Che, Wanxiang and + Nabende, Joyce and + Shutova, Ekaterina and + Pilehvar, Mohammad Taher", + booktitle = "Proceedings of the 63rd Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers)", + month = jul, + year = "2025", + address = "Vienna, Austria", + publisher = "Association for Computational Linguistics", + url = "https://aclanthology.org/2025.acl-long.1101/", + doi = "10.18653/v1/2025.acl-long.1101", + pages = "22577--22595", + ISBN = "979-8-89176-251-0", + abstract = "Automatic evaluation of retrieval augmented generation (RAG) systems relies on fine-grained dimensions like faithfulness and relevance, as judged by expert human annotators. Meta-evaluation benchmarks support the development of automatic evaluators that correlate well with human judgement. However, existing benchmarks predominantly focus on English or use translated data, which fails to capture cultural nuances. A native approach provides a better representation of the end user experience.In this work, we develop a Multilingual End-to-end Meta-Evaluation RAG benchmark MEMERAG. Our benchmark builds on the popular MIRACL dataset, using native-language questions and generating responses with diverse large language models (LLMs), which are then assessed by expert annotators for faithfulness and relevance. We describe our annotation process and show that it achieves high inter-annotator agreement. We then analyse the performance of the answer-generating LLMs across languages as per the human evaluators. Finally we apply the dataset to our main use-case which is to benchmark multilingual automatic evaluators (LLM-as-a-judge). We show that our benchmark can reliably identify improvements offered by advanced prompting techniques and LLMs. We release our benchmark to support the community developing accurate evaluation methods for multilingual RAG systems." +} + +@ARTICLE{2020SciPy-NMeth, + author = {Virtanen, Pauli and Gommers, Ralf and Oliphant, Travis E. and + Haberland, Matt and Reddy, Tyler and Cournapeau, David and + Burovski, Evgeni and Peterson, Pearu and Weckesser, Warren and + Bright, Jonathan and {van der Walt}, St{\'e}fan J. and + Brett, Matthew and Wilson, Joshua and Millman, K. Jarrod and + Mayorov, Nikolay and Nelson, Andrew R. J. and Jones, Eric and + Kern, Robert and Larson, Eric and Carey, C J and + Polat, {\.I}lhan and Feng, Yu and Moore, Eric W. and + {VanderPlas}, Jake and Laxalde, Denis and Perktold, Josef and + Cimrman, Robert and Henriksen, Ian and Quintero, E. A. and + Harris, Charles R. and Archibald, Anne M. and + Ribeiro, Ant{\^o}nio H. and Pedregosa, Fabian and + {van Mulbregt}, Paul and {SciPy 1.0 Contributors}}, + title = {{{SciPy} 1.0: Fundamental Algorithms for Scientific + Computing in Python}}, + journal = {Nature Methods}, + year = {2020}, + volume = {17}, + pages = {261--272}, + adsurl = {https://rdcu.be/b08Wh}, + doi = {10.1038/s41592-019-0686-2}, +} + +@inproceedings{es-etal-2024-ragas, + title = "{RAGA}s: Automated Evaluation of Retrieval Augmented Generation", + author = "Es, Shahul and + James, Jithin and + Espinosa Anke, Luis and + Schockaert, Steven", + editor = "Aletras, Nikolaos and + De Clercq, Orphee", + booktitle = "Proceedings of the 18th Conference of the European Chapter of the Association for Computational Linguistics: System Demonstrations", + month = mar, + year = "2024", + address = "St. Julians, Malta", + publisher = "Association for Computational Linguistics", + url = "https://aclanthology.org/2024.eacl-demo.16/", + doi = "10.18653/v1/2024.eacl-demo.16", + pages = "150--158", + abstract = "We introduce RAGAs (Retrieval Augmented Generation Assessment), a framework for reference-free evaluation of Retrieval Augmented Generation (RAG) pipelines. RAGAs is available at [\url{https://github.com/explodinggradients/ragas}]. RAG systems are composed of a retrieval and an LLM based generation module. They provide LLMs with knowledge from a reference textual database, enabling them to act as a natural language layer between a user and textual databases, thus reducing the risk of hallucinations. Evaluating RAG architectures is challenging due to several dimensions to consider: the ability of the retrieval system to identify relevant and focused context passages, the ability of the LLM to exploit such passages faithfully, and the quality of the generation itself. With RAGAs, we introduce a suite of metrics that can evaluate these different dimensions without relying on ground truth human annotations. We posit that such a framework can contribute crucially to faster evaluation cycles of RAG architectures, which is especially important given the fast adoption of LLMs." +} + +@software{Ip_deepeval_2026, +author = {Ip, Jeffrey and Vongthongsri, Kritin}, +license = {Apache-2.0}, +month = sep, +title = {{deepeval}}, +url = {https://github.com/confident-ai/deepeval}, +version = {4.2.1}, +year = {2026} +} + +@inproceedings{NEURIPS2023_91f18a12, + author = {Zheng, Lianmin and Chiang, Wei-Lin and Sheng, Ying and Zhuang, Siyuan and Wu, Zhanghao and Zhuang, Yonghao and Lin, Zi and Li, Zhuohan and Li, Dacheng and Xing, Eric and Zhang, Hao and Gonzalez, Joseph and Stoica, Ion}, + booktitle = {Advances in Neural Information Processing Systems}, + doi = {10.52202/075280-2020}, + editor = {A. Oh and T. Naumann and A. Globerson and K. Saenko and M. Hardt and S. Levine}, + pages = {46595--46623}, + publisher = {Curran Associates, Inc.}, + title = {Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena}, + url = {https://proceedings.neurips.cc/paper_files/paper/2023/file/91f18a1287b398d378ef22505bf41832-Paper-Datasets_and_Benchmarks.pdf}, + volume = {36}, + year = {2023} +} + +@software{UK_AI_Security_Institute_Inspect_AI_Framework_2024, +author = {{UK AI Security Institute}}, +license = {MIT}, +month = may, +title = {{Inspect AI: Framework for Large Language Model Evaluations}}, +url = {https://github.com/UKGovernmentBEIS/inspect_ai}, +year = {2024} +} + +@misc{trulens, + title={{TruLens}: Evaluation and Tracking for {LLM} Experiments and {AI} Agents}, + author={{TruEra}}, + year={2026}, + note={Version 2.14.0, MIT License}, + howpublished={\url{https://github.com/truera/trulens}} +} + +@article{Pedregosa_Scikit-learn_Machine_Learning_2011, +author = {Pedregosa, Fabian and Varoquaux, Gaël and Gramfort, Alexandre and Michel, Vincent and Thirion, Bertrand and Grisel, Olivier and Blondel, Mathieu and Prettenhofer, Peter and Weiss, Ron and Dubourg, Vincent and Vanderplas, Jake and Passos, Alexandre and Cournapeau, David and Brucher, Matthieu and Perrot, Matthieu and Duchesnay, Édouard}, +journal = {Journal of Machine Learning Research}, +pages = {2825--2830}, +title = {{Scikit-learn: Machine Learning in Python}}, +url = {https://jmlr.csail.mit.edu/papers/v12/pedregosa11a.html}, +volume = {12}, +year = {2011} +} +@misc{martinon2026pydata, + title={Beyond {LLM}-as-Judge: Using {GLIDE} for Reliable, Scalable Evaluation of {GenAI} Systems}, + author={Martinon, Gr{\'e}goire}, + year={2026}, + note={Tutorial, PyData Amsterdam 2026, 12 September 2026}, + howpublished={\url{https://pretalx.com/pydata-amsterdam2026/talk/ZSYGEC/}} +} + +@misc{martinon2026compute, + title={Stop Guessing, Start Measuring. Rigorous Evaluation of Agentic Systems with Prediction-Powered Inference}, + author={Martinon, Gr{\'e}goire}, + year={2026}, + note={Talk, Compute! Paris 2026, 25 November 2026}, + howpublished={\url{https://pretalx.com/compute-paris-2026/talk/ZMVL9B/}} +} + +@inproceedings{ + merad2026industrializing, + title={Industrializing Prediction-Powered Inference: The {GLIDE} Library for Reliable Gen{AI} Evaluation}, + author={Ibrahim Merad and Gr{\'e}goire Martinon}, + booktitle={Trustworthy AI for Good (AI4GOOD) Workshop @ NeurIPS 2026}, + year={2026}, + url={https://openreview.net/forum?id=Z51G2eCNIA} +} \ No newline at end of file diff --git a/JOSS/paper.md b/JOSS/paper.md new file mode 100644 index 00000000..d082dc39 --- /dev/null +++ b/JOSS/paper.md @@ -0,0 +1,104 @@ +--- +title: 'GLIDE: A Python library for prediction-powered evaluation of GenAI systems' +tags: + - Python + - prediction-powered inference + - statistical inference + - AI evaluation + - LLM-as-judge + - confidence intervals + - anytime-valid inference +authors: + - name: Grégoire Martinon + orcid: 0009-0000-6035-460X + corresponding: true + affiliation: 1 + - name: Ibrahim Merad + orcid: 0000-0003-0907-9096 + affiliation: 1 +affiliations: + - name: Emerton Data, France + index: 1 +date: 23 October 2026 +bibliography: paper.bib +--- + +# Summary + +Deciding whether a generative AI (GenAI) system behaves acceptably is a measurement problem: what fraction of answers contain hallucinations, or what fraction of an agent's trajectories are unsafe? Human expert annotation answers such questions reliably but slowly and at high cost, while the popular LLM-as-judge paradigm is cheap but yields biased proxy annotations [@NEURIPS2023_91f18a12]. Prediction-powered inference (PPI) dissolves that trade-off: it combines a small human-labeled sample (taken as ground truth) with a large pool of proxy-labeled observations into a debiased metric, whose confidence interval remains valid however poor the proxy is [@angelopoulos2023prediction; @angelopoulos2023ppiplusplus]. + +`GLIDE` (Generated Label Inference & Debiasing Engine) brings that literature into a unified library, specialized in risk and performance estimation of complex AI systems that produce large amounts of unstructured data, such as AI agents. Most such metrics, be they accuracy, hallucination rate or unsafe-trajectory rate, are population means estimated on samples of generated outputs. Since human annotation is scarce, their estimation borrows from survey theory, where a small sample estimates a population statistic: it requires both choosing which observations humans should label and combining the resulting ground-truth labels with proxy labels. + +`GLIDE` addresses both needs and exposes multiple sampling designs and performance estimators behind a scikit-learn-style API. Every estimator returns a result object carrying the point estimate, the confidence interval, and the effective sample size, i.e., the number of human labels a classical survey estimator would have needed to reach the same precision. Whenever the LLM-as-judge correlates with human annotators, the effective sample size translates into direct savings in human annotations. + +`GLIDE` also addresses monitoring, which consists of repeated evaluations on a stream of batches, each carrying a few human labels and many proxy labels. Naively repeating an evaluation inflates the false alarm rate, so monitoring requires dedicated statistical control of multiple testing. `GLIDE` monitors return the running metric together with an anytime-valid bound (upper for a risk metric, lower for a performance metric). + +The library is documented through runnable tutorials, a mathematical user guide, a scientific validation notebook for every estimator and monitor, and several end-to-end case studies on public benchmarks. + +![The evaluation workflow `GLIDE` implements. Left: prediction-powered inference debiases a cheap proxy metric using a small human-annotated control sample. Right: the resulting three-step decomposition around which the API is organized.\label{fig:workflow}](glide-workflow.png) + +# Statement of need + +Evaluating a deployed GenAI system under a fixed annotation budget raises several complications, each addressed by a separate strand of the literature. + +- **Heterogeneous strata.** LLM-as-judge quality varies across axes known in advance: domain, language, query type. Stratified sampling tunes evaluation per stratum [@NEURIPS2024_c9fcd02e; @fogliato2024framework]. +- **Small labeled sets.** Below a few dozen labels per stratum, the central-limit approximation degrades. Bootstrap intervals stay valid [@kluger2025prediction]. +- **Correlated units.** For granular metrics (e.g., the proportion of hallucinated sentences), evaluation units may not be independent (think of sentences within a paragraph). Treating them as independent understates the variance, so clustered inference, which works on group means, is needed. +- **Multiple judges.** Modern evaluation stacks accumulate LLM judges of differing cost and skill. Multi-proxy aggregation weights them optimally, so an extra judge can only narrow the interval [@shan2025sada; @cowen2026multiple]. +- **Judge uncertainty.** LLM judges can expose per-observation uncertainty scores that reveal where a human label pays off. Active sampling concentrates the budget there [@pmlr-v235-zrnic24a; @gligoric2025can]. +- **Cost asymmetry.** Expert review costs dollars per unit, an LLM-as-judge call cents. Cost-aware sampling targets human annotations at the most promising observations under a monetary budget [@angelopoulos2025cost]. +- **Continuous monitoring.** Re-estimating a metric batch after batch inevitably produces false alarms. Anytime-valid confidence sequences make peeking safe under a single budget [@podkopaev2021tracking; @waudbysmith2024time; @zhang2026prediction]. + +These methods share one template: a few reliable annotations combined with a large set of proxy annotations. However, they and their extensions are scattered across papers with heterogeneous notation and partial reference implementations [@song2026demystifying], some in R and some in Python, none covering more than a slice of the design space. + +`GLIDE` closes that gap by treating sampling, estimation and monitoring as one consistent family. + +# State of the field + +`ppi_py` [@angelopoulos2023prediction] has long been the reference implementation of the PPI family. This open-source Python package covers means, generalized linear models and M-estimators. The remaining methods above live in single-paper repositories: `ssepy` for stratified sampling and estimation [@fogliato2024framework], `active-inference` and `confidence-driven-inference` for active designs [@pmlr-v235-zrnic24a; @gligoric2025can], `PTDBoot` for the bootstrap variants [@kluger2025prediction], and `sada` for multi-proxy aggregation [@shan2025sada]. Each repository is self-consistent, but has its own data conventions, no shared sampling layer and no monitoring counterpart. + +Evaluation orchestration frameworks such as RAGAS [@es-etal-2024-ragas], DeepEval [@Ip_deepeval_2026], TruLens [@trulens] and Inspect [@UK_AI_Security_Institute_Inspect_AI_Framework_2024] solve the engineering problem of running an LLM-as-judge evaluation. `GLIDE` can thus consume the outputs of such pipelines, combine them with ground-truth labels, and supply the downstream rigorous statistical estimation layer. + +We built a new library rather than contributing these methods upstream for two reasons. + +The first is audience and scope. `ppi_py` is the reference implementation of the seminal PPI work and remains the right tool for inference on general estimands (e.g., quantiles, regression coefficients). It starts from an already-labeled set, so sampling design falls outside its scope. `GLIDE` addresses the broader community of engineers and evaluation teams, and buys that accessibility by narrowing the estimand to the mean, the workhorse of system evaluation. The narrowing also buys breadth: `ppi_py` predates most of the extensions listed above, whereas `GLIDE` brings cost-aware and active designs, stratified and clustered variants, multi-proxy aggregation, bootstrap intervals and anytime-valid monitoring into one consistent framework, several of them in their first public implementation. + +The first is audience and scope. `ppi_py` is the reference implementation of the seminal PPI work and remains the right tool for inference on general estimands (e.g., quantiles, regression coefficients). It starts from an already-labeled set, so sampling design falls outside its scope. `GLIDE` addresses the broader community of engineers and evaluation teams, and buys that accessibility by narrowing the estimand to the mean, the workhorse of system evaluation. The narrowing also buys breadth: `ppi_py` predates most of the extensions listed above into one consistent framework, several of them in their first public implementation. + +The second reason follows from the first. Serving that audience requires an API that reconciles sampling, estimation and monitoring in one modular architecture. `GLIDE` provides a unified API that lets users switch easily between methods, and lets contributors add a new estimator, sampler or monitor without having to understand or modify the rest of the code base. + +# Software design + +`GLIDE` organizes evaluation around three sequential steps inherited from survey theory (\autoref{fig:workflow}): sampling, which selects which observations deserve a human label; annotation, which only domain experts can perform; and estimation, which combines the labels and the proxy predictions into a debiased estimate with a confidence interval. Monitoring is a fourth component that wraps per-batch estimates in an anytime-valid bound. + +Two design decisions carry most of the library's behavior. + +The first is the data contract: each class method take as inputs one aligned array per collection of labels, following the conventions scikit-learn established across the data science community [@Pedregosa_Scikit-learn_Machine_Learning_2011]. + +The second is a middle layer of abstraction: each estimator family factors its computation into a `MeanEstimationEngine`, which an estimator calls once over the whole dataset and a monitor calls once per batch. Because estimators and monitors share this middle layer, contributors can readily extend any estimator into its anytime-valid monitor counterpart, without reimplementing its statistics. + +In terms of quality gates, every new component passes three lines of defense, all run in continuous integration: unit tests with 100% code coverage and executed docstring examples, functional tests of statistical properties (e.g., a stratified estimator on a single stratum must equal the uniform one), and Monte Carlo validation notebooks assessing statistical coverage, interval width, false-alarm and miscoverage rates. + +Regarding maintenance philosophy, `scipy` [@2020SciPy-NMeth] is the single runtime dependency, our dependency support windows follow SPEC 0, and releases follow semantic versioning. + +# Research impact statement + +The statistical framework behind the library is described in a companion methods paper presented at the ICML 2026 workshop on statistical frameworks for uncertainty in agentic systems [@martinon2026industrializing]. Three reproducible case studies in the documentation run full workflows on public benchmarks, whose proxy-labeled versions we release as documented datasets: agentic safety evaluation on R-Judge [@yuan-etal-2024-r], text-to-SQL accuracy on Spider [@yu-etal-2018-spider], and multilingual retrieval-augmented generation faithfulness on MEMERAG [@cruz-blandon-etal-2025-memerag]. + +`GLIDE` has reached practitioner and research audiences alike. It was the subject of a tutorial at PyData Amsterdam 2026 [@martinon2026pydata], will be presented at Compute! Paris 2026 [@martinon2026compute] and at the AI4Good workshop at NeurIPS 2026 in Paris [@merad2026industrializing]. + +`GLIDE` has been developed in public since its first commit in March 2026, with roughly two releases per month and a dozen contributors. It has attracted more than a hundred stars and is disseminated through a monthly newsletter. Beyond the open-source community, the package has already been used in several missions delivered by Emerton Data, a consulting firm, to evaluate industrialized GenAI systems with limited human annotation budgets. + +# Code availability + +The package can be installed from PyPI with `pip install glide-py`. The source is on GitHub (https://github.com/EmertonData/glide). + +# AI usage disclosure + +Generative AI was used both to develop the software and to prepare this manuscript. Development tasks are co-designed by the tech lead with Claude Code. Developers co-implement with Claude Code. Each pull request is co-reviewed: Claude's code-review first, then a tech lead's review. For the manuscript, Claude was used to brainstorm, format, and audit the draft against the journal's guidelines. The authors take full responsibility of the result. + +# Acknowledgements + +We thank Anastasios Angelopoulos, Stephen Bates, Dan Kluger and Adam Fisch for useful discussions and guidance at the beginning of the project, and for their encouragement at ICML 2026. We are grateful to Pravallika Mavilla, Mohammed Raki, Guillaume D'Hérouville, Victor Woelffel and all contributors to the repository, and to Emerton Data for its financial support of the library as an open-source project. Finally, we thank the authors of the methods and reference implementations `GLIDE` builds upon. + +# References \ No newline at end of file diff --git a/Makefile b/Makefile index 44923bb9..79a3ae8b 100644 --- a/Makefile +++ b/Makefile @@ -78,6 +78,9 @@ build: rm -rf dist uv build +paper: + docker run --rm -v $(PWD):/data -u $(shell id -u):$(shell id -g) openjournals/inara:latest -o pdf JOSS/paper.md + bump-major: uv run bump-my-version bump major