{"id":46765488,"url":"https://github.com/fidelity/boolxai","last_synced_at":"2026-03-09T22:30:07.975Z","repository":{"id":246549875,"uuid":"818339619","full_name":"fidelity/boolxai","owner":"fidelity","description":"BoolXAI is a research library for machine learning for Explainable AI (XAI) based on expressive Boolean formulas.","archived":false,"fork":false,"pushed_at":"2025-10-10T19:27:49.000Z","size":5952,"stargazers_count":20,"open_issues_count":0,"forks_count":4,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-02-23T20:34:22.879Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://fidelity.github.io/boolxai/","language":"Jupyter Notebook","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fidelity.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.txt","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-21T16:18:04.000Z","updated_at":"2025-12-16T11:42:14.000Z","dependencies_parsed_at":"2024-10-28T16:46:15.090Z","dependency_job_id":"6ae440b3-913a-42ca-a3a0-a44e09ca8cf9","html_url":"https://github.com/fidelity/boolxai","commit_stats":null,"previous_names":["fidelity/boolxai"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fidelity/boolxai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidelity%2Fboolxai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidelity%2Fboolxai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidelity%2Fboolxai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidelity%2Fboolxai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fidelity","download_url":"https://codeload.github.com/fidelity/boolxai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fidelity%2Fboolxai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30314624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T20:05:46.299Z","status":"ssl_error","status_checked_at":"2026-03-09T19:57:04.425Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-09T22:30:07.080Z","updated_at":"2026-03-09T22:30:07.933Z","avatar_url":"https://github.com/fidelity.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BoolXAI: Explainable AI using expressive Boolean formulas\n\n*This repo is being made available as a static archive. It has been released by Fidelity Investments under the Apache 2.0 license, and will not receive updates.*\n*If you have questions, please contact \u003copensource@fidelity.com\u003e*.\n\n[![ci](https://github.com/fidelity/boolxai/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fidelity/boolxai/actions/workflows/ci.yml)\n[![PyPI version fury.io](https://badge.fury.io/py/boolxai.svg)](https://pypi.python.org/pypi/boolxai/)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10-blue)](https://www.python.org/downloads/release/python-3100/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)\n[![Downloads](https://static.pepy.tech/personalized-badge/boolxai?period=total\u0026units=international_system\u0026left_color=grey\u0026right_color=orange\u0026left_text=Downloads)](https://pepy.tech/project/boolxai)\n\nBoolXAI ([AAAI'25](https://ojs.aaai.org/index.php/AAAI/article/view/35157), [MAKE'23](https://www.mdpi.com/2504-4990/5/4/86), [ArXiv'23](https://arxiv.org/pdf/2306.03976)) is a research library for Explainable AI (XAI) based\non expressive Boolean formulas that allow And, Or, Choose(k), AtMost(k), and AtLeast(k) operators.\n\nThe Boolean formula defines a rule with tunable\ncomplexity (or interpretability), according to which input data are classified. Such a\nformula can include any operator that can be applied to one or more Boolean variables,\nthus providing higher expressiveness compared to more rigid rule-based and tree-based\napproaches. The classifier is trained using native local optimization techniques,\nefficiently searching the space of feasible formulas. For a high-level introduction, see the [AAAI'25 presentation](https://nbviewer.org/github/skadio/skadio.github.io/blob/master/files/2025_IAAI_BoolXAI_Kadioglu.pdf) and the [Fidelity blogpost](https://fcatalyst.com/blog/june2023/explainable-ai-using-expressive-boolean-formulas), and for a technical introduction, see the [Amazon AWS blogpost](https://aws.amazon.com/blogs/quantum-computing/explainable-ai-using-expressive-boolean-formulas/). \n\nBoolXAI is developed by Amazon Quantum Solutions Lab, the FCAT Quantum and Future Computing Incubator, and the AI Center of Excellence at Fidelity Investments. Documentation is available at [fidelity.github.io/boolxai](https://fidelity.github.io/boolxai).\n\n## Quick Start\n\nThe heart of BoolXAI is the rule classifier (`BoolXAI.RuleClassifier`), which can be\nused as an interpretable ML model for binary classification. Note that the input data\nmust be binarized. Here's a simple example showing the basic usage. For additional\nexamples, including advanced usage, see the Usage Examples.\n\n\u003c!--- When updating the below, please update tests/test_quick_start.py as well ---\u003e\n\n```python\nimport numpy as np\nfrom sklearn.metrics import balanced_accuracy_score\n\nfrom boolxai import BoolXAI, Operator\n\n# Create random toy data for binary classification. X and y must be binary! \nrng = np.random.default_rng(seed=42)\nX = rng.choice([0, 1], size=(100, 10))\ny = rng.choice([0, 1], size=100)\n\n# Rule classifier with maximum depth, complexity, possible operators\nrule_classifier = BoolXAI.RuleClassifier(max_depth=3,\n                                         max_complexity=6, \n                                         operators=[Operator.And, Operator.Or, Operator.Choose, Operator.AtMost, Operator.AtLeast],\n                                         random_state=42)\n\n# Learn the best rule\nrule_classifier.fit(X, y)\n\n# Best rule and best score\nbest_rule = rule_classifier.best_rule_\nbest_score = rule_classifier.best_score_\nprint(f\"{best_rule=} {best_score=:.2f}\")\n\n# The depth of a rule is the number of edges in the longest path from the root to any leaf/literal.\n# The complexity of a rule is the total number of operators and literals.\nprint(f\"depth={best_rule.depth()} complexity={best_rule.complexity()}\")\n\n# Predict and score\ny_pred = rule_classifier.predict(X)\nscore = balanced_accuracy_score(y, y_pred)\nprint(f\"{score=:.2f}\")\n\n# It is also possible to plot the best rule --requires installing plot dependencies\nbest_rule.plot()\n\n# or get a networkx.DiGraph representation of the rule --requires installing plot dependencies\nG = best_rule.to_graph()\nprint(G)\n```\n\n## Usage Examples\n\n- [Training a rule classifier](http://fidelity.github.io/boolxai/_examples/basic_usage.html#Training-a-rule-classifier)\n- [Interpreting and visualizing the rules](http://fidelity.github.io/boolxai/_examples/basic_usage.html#Making-sense-of-the-rules)\n- [Number of starts (num_starts)](http://fidelity.github.io/boolxai/_examples/advanced_usage.html#Number-of-starts)\n- [Bagging (max_samples)](http://fidelity.github.io/boolxai/_examples/advanced_usage.html#Bagging)\n- [Parallelization (num_jobs)](http://fidelity.github.io/boolxai/_examples/advanced_usage.html#Parallelization)\n- [Cross-Validation](http://fidelity.github.io/boolxai/_examples/advanced_usage.html#Cross-validation)\n- [Pareto frontier (max_complexity)](http://fidelity.github.io/boolxai/_examples/advanced_usage.html#Pareto-frontier)\n- [Boolean operators](http://fidelity.github.io/boolxai/_examples/advanced_usage.html#Changing-the-allowed-operators)\n- [Custom operators](http://fidelity.github.io/boolxai/_examples/advanced_usage.html#Adding-custom-operators)\n- [Partial optimization (base_rule)](http://fidelity.github.io/boolxai/_examples/advanced_usage.html#Optimizing-part-of-a-rule)\n- [Boosting](http://fidelity.github.io/boolxai/_examples/upstream_usage.html#Boosting)\n- [Multi-label classification](http://fidelity.github.io/boolxai/_examples/upstream_usage.html#Multilabel-classification)\n- [Multi-class classification](http://fidelity.github.io/boolxai/_examples/upstream_usage.html#Multiclass-classification)\n\n## Installation\n\nWe recommend installing BoolXAI in a virtual environment.\n\nIt can be installed from PyPI using:\n\n```pip install boolxai```\n\nAlternatively, clone this repo and use:\n\n```pip install -e .```\n\nIn order to plot the best rule and get its networkx graph, additional dependencies are required, which can be installed using:\n\n```pip install boolxai[plot]```\n\nIn order to run the [Notebook Usage Examples](https://github.com/fidelity/boolxai/tree/master/notebooks/), additional\ndependencies are required, which can be installed using:\n\n```pip install -r notebooks/requirements.txt```\n\nNote that it's recommended to create a Jupyter notebook kernel for this repository and\nrun the notebooks using it, for example:\n\n```python3 -m ipykernel install --user --name boolxai```\n\n### Requirements\n\nThis library requires **Python 3.11++**.\nSee [requirements.txt](requirements.txt) for dependencies. For plotting, see [requirements_plot.txt](requirements_plot.txt) and `graphviz` must be installed separately (see [instructions](https://graphviz.org/download)) - it cannot be installed using `pip`.\n\n## Citation\n\nIf you use BoolXAI in a publication, please cite it as:\n\n```bibtex\n@inproceedings{DBLP:conf/aaai/KadiogluZRBSSZK25,\n  author       = {Serdar Kadioglu and Elton Yechao Zhu and Gili Rosenberg and John Kyle Brubaker and Martin J. A. Schuetz and Grant Salton and Zhihuai Zhu and Helmut G. Katzgraber},\n  editor       = {Toby Walsh and Julie Shah and Zico Kolter},\n  title        = {BoolXAI: Explainable {AI} Using Expressive Boolean Formulas},\n  booktitle    = {AAAI-25, Sponsored by the Association for the Advancement of Artificial\n                  Intelligence, February 25 - March 4, 2025, Philadelphia, PA, {USA}},\n  pages        = {28900--28906},\n  publisher    = {{AAAI} Press},\n  doi          = {10.1609/AAAI.V39I28.35157},\n  year         = {2025}\n}\n\n@article{DBLP:journals/make/RosenbergBSSZZKBK23,\n  author       = {Gili Rosenberg and John Kyle Brubaker and Martin J. A. Schuetz and Grant Salton and Zhihuai Zhu and Elton Yechao Zhu and Serdar Kadioglu and Sima E. Borujeni and Helmut G. Katzgraber},\n  title        = {Explainable Artificial Intelligence Using Expressive Boolean Formulas},\n  journal      = {Mach. Learn. Knowl. Extr.},\n  volume       = {5},\n  number       = {4},\n  pages        = {1760--1795},\n  doi          = {10.3390/MAKE5040086},\n  year         = {2023}\n}\n```\n\n## Support\n\nPlease submit bug reports, questions, and feature requests as\n[GitHub Issues](https://github.com/fidelity/boolxai/issues).\n\n## License\n\nBoolXAI is licensed under the [Apache License 2.0](LICENSE).\n\n\u003cbr\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffidelity%2Fboolxai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffidelity%2Fboolxai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffidelity%2Fboolxai/lists"}