| Name | sibyl-api JSON |
| Version |
0.1.2
JSON |
| download |
| home_page | https://github.com/DAI-Lab/sibyl-api |
| Summary | Explanation tool for machine learning |
| upload_time | 2024-06-12 14:51:13 |
| maintainer | None |
| docs_url | None |
| author | MIT Data To AI Lab |
| requires_python | !=2.7.*,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,!=3.7.*,!=3.8.*,>=3.9 |
| license | MIT |
| keywords |
sibyl-api
sibyl
api
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="left">
<img width=15% src="https://dai.lids.mit.edu/wp-content/uploads/2018/06/Logo_DAI_highres.png" alt=“DAI-Lab” />
<i>An open source project from Data to AI Lab at MIT.</i>
</p>
[](https://pypi.org/project/sibyl-api/)
[](https://pypi.org/project/sibyl-api/)
[](https://pypi.org/project/sibyl-api/)
[](https://github.com/sibyl-dev/sibyl-api/actions/workflows/python-test.yml)
[](https://join.slack.com/t/sibyl-ml/shared_invite/zt-2dyfwbgo7-2ALinuT2KDZpsVJ4rntJuA)
# Sibyl-API
REST-API endpoints for understanding and interacting with ML models.
| Important Links | |
| --------------------------------------------- | -------------------------------------------------------------------- |
| :book: **[Documentation]** | Quickstart and user guides |
| :memo: **[API Reference]** | Endpoint usage and details |
| :scroll: **[License]** | The repository is published under the MIT License. |
| :computer: **[Website]** | Check out the Sibyl Project Website for more information. |
[Website]: https://sibyl-ml.dev/
[Documentation]: https://dtail.gitbook.io/sibyl/
[License]: https://github.com/sibyl-dev/sibyl-api/blob/dev/LICENSE
[Community]: https://join.slack.com/t/sibyl-ml/shared_invite/zt-2dyfwbgo7-2ALinuT2KDZpsVJ4rntJuA
[API Reference]: https://sibyl-ml.dev/sibyl-api/
# Overview
Sibyl-API offers API endpoints for easy-to-understand ML model explanations and smooth interactions.
To get started with Sibyl-API, follow the instructions below or in our documentation to setup your Sibyl database. From there,
you can easily make model predictions, get and modify information about model features, and get a variety of explanations
about your models and their predictions.
# Install
## Requirements
**Sibyl-API** requires [MongoDB version 6 or 7](https://www.mongodb.com/try/download/community).
To install MongoDB, follow the instructions
[here](https://www.mongodb.com/docs/manual/administration/install-community/).
## Install from PyPi
Sibyl-API can be installed from pypi:
```bash
pip install sibyl-api
```
## Install from source
Sibyl-API uses **Poetry** for dependency management. If you do not have *Poetry* installed, please head to [poetry installation guide](https://python-poetry.org/docs/#installation)
and install poetry according to the instructions.
Run the following command to make sure poetry is activated. You may need to close and reopen the terminal.
```bash
poetry --version
```
Then, you can clone this repository and install it from
source by running `poetry install`:
```bash
git clone https://github.com/sibyl-dev/sibyl-api.git
cd sibyl-api
poetry install
```
# Quickstart
Follow these steps to get started with the built-in Ames Housing dataset example.
You can prepare and load the Ames Housing dataset by running
```bash
sibyl prepare-sample-db
```
> ⚠️ This function will overwrite any
existing database on localhost:27017 with the name **housing**):
You can now run Sibyl-API with the sample dataset with:
```bash
poetry run sibyl run -D housing -v
```
Once Sibyl-API is running, you can access and test your APIs manually at `localhost:3000/apidocs`
# Preparing database
Sibyl-API uses a MongoDB-based database system. We offer several methods to setup your database.
## Preparing data
### Required inputs
At minimum, sibyl-API requires the following inputs (either as a DataFrame or csv, see creation options below):
**entities**: A table with the entities to be explained. Each row should correspond to a single observation.
Columns:
- `eid` (*required*): unique identifier specifying which entity this observation corresponds to
- `row_id`: unique identifier specifying the observation ID. Together, `eid` and `row_id` should uniquely identify each observation.
- `label`: the ground-truth label for this observation
- `[FEATURES]`: additional columns for each feature used to make predictions. These columns should be named the same as the features used in the model.
Sample table:
| `eid` | `row_id` | `label` | `feature1` | `feature2` | `feature3` |
|---------|----------|---------|------------|------------|------------|
| entity1 | 101 | 0 | 0.1 | 0.2 | 0.3 |
| entity1 | 102 | 1 | 0.2 | 0.3 | 0.4 |
| entity2 | 204 | 1 | 0.3 | 0.4 | 0.5 |
**features**: A table with the features used to make predictions. Each row should correspond to a single feature.
Columns:
- `feature` (*required*): the name of the feature
- `type` (*required*): the type of the feature. This can be `categorical`, `numerical`, or `boolean`
- `description`: a description of the feature
- `negative_description`: a description of the feature when it is not present. Only for boolean features
- `values`: a list of possible values for the feature. Only for categorical features.
Sample table:
| `feature` | `type` | `description` | `negative_description` | `values` |
|-----------|--------|----------------------|--------------------------------|-----------------------------|
| size | numerical | size in square feet | | |
| has_ac | boolean | has air conditioning | does not have air conditioning | |
| nghbrh | categorical | neighborhood | | [Oceanview, Ridge, Oakvale] |
**realapp**: A pickled `pyreal.RealApp` object. This object is used to generate explanations for the model.
See [the pyreal documentation](https://dtail.gitbook.io/pyreal/) for details on setting this up.
### Optional inputs
Additionally, you can configure APIs futher with:
**config**: a configuration file (YAML or python dictionary) specifying
additional settings. See our [config documentation](https://dtail.gitbook.io/sibyl/user-guides/preparing-the-database/configuring-applications) for details.
**categories**: a table with the categories used to make predictions. Each row should correspond to a single category.
Columns:
- `category` (*required*): the name of the category
- `description`: a description of the category
- `color`: color to use for the category
- `abbreviation`: abbreviation to use for the category
## Creating the Mongo database
### With the prepare-db script
Be sure to `start` your mongodb service before preparing the database
Copy `sibyl/db/config_template.yml` and fill it in with your configurations. Place required data
in a common directory.
Next, run the preprocessing script with:
```bash
sibyl run prepare-db [CONFIG_NAME].yml [DIRECTORY]
```
where `[CONFIG_NAME].yml` is the path to your configuration file and `[DIRECTORY]` is
the directory containing your data.
### With the Setup Wizard
Currently, the setup wizard is only available when installing from source.
First, install the optional setup dependencies with
```bash
poetry install --with setup
```
Then, run the setup wizard with
```bash
poetry run streamlit run setup-wizard/main.py
```
# Running APIs
Once the library has been installed, you can run the APIs locally with:
```bash
poetry run sibyl run -v -D [DATABASE_NAME]
```
Or, to run in development mode:
```bash
poetry shell
sibyl run -E development -v -D [DATABASE_NAME]
```
You can then access your APIs locally at http://localhost:3000/apidocs
# Contributing Guide
We appreciate contributions of all kinds! See [our contributing guide](https://dtail.gitbook.io/sibyl/developer-guides/contributing-to-sibyl) for instructions.
Raw data
{
"_id": null,
"home_page": "https://github.com/DAI-Lab/sibyl-api",
"name": "sibyl-api",
"maintainer": null,
"docs_url": null,
"requires_python": "!=2.7.*,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,!=3.7.*,!=3.8.*,>=3.9",
"maintainer_email": null,
"keywords": "sibyl-api, sibyl, api",
"author": "MIT Data To AI Lab",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/50/6e/6f51c6cae5f49268f91247cda979189fdef1cc03d4fae345ec49ef811ded/sibyl_api-0.1.2.tar.gz",
"platform": null,
"description": "<p align=\"left\">\n<img width=15% src=\"https://dai.lids.mit.edu/wp-content/uploads/2018/06/Logo_DAI_highres.png\" alt=\u201cDAI-Lab\u201d />\n<i>An open source project from Data to AI Lab at MIT.</i>\n</p>\n\n[](https://pypi.org/project/sibyl-api/)\n[](https://pypi.org/project/sibyl-api/)\n[](https://pypi.org/project/sibyl-api/)\n[](https://github.com/sibyl-dev/sibyl-api/actions/workflows/python-test.yml)\n[](https://join.slack.com/t/sibyl-ml/shared_invite/zt-2dyfwbgo7-2ALinuT2KDZpsVJ4rntJuA)\n\n# Sibyl-API\n\nREST-API endpoints for understanding and interacting with ML models. \n\n| Important Links | |\n| --------------------------------------------- | -------------------------------------------------------------------- |\n| :book: **[Documentation]** | Quickstart and user guides |\n| :memo: **[API Reference]** | Endpoint usage and details |\n| :scroll: **[License]** | The repository is published under the MIT License. |\n| :computer: **[Website]** | Check out the Sibyl Project Website for more information. |\n\n[Website]: https://sibyl-ml.dev/\n[Documentation]: https://dtail.gitbook.io/sibyl/\n[License]: https://github.com/sibyl-dev/sibyl-api/blob/dev/LICENSE\n[Community]: https://join.slack.com/t/sibyl-ml/shared_invite/zt-2dyfwbgo7-2ALinuT2KDZpsVJ4rntJuA\n[API Reference]: https://sibyl-ml.dev/sibyl-api/\n\n# Overview\n\nSibyl-API offers API endpoints for easy-to-understand ML model explanations and smooth interactions. \n\nTo get started with Sibyl-API, follow the instructions below or in our documentation to setup your Sibyl database. From there, \nyou can easily make model predictions, get and modify information about model features, and get a variety of explanations\nabout your models and their predictions.\n\n# Install\n\n## Requirements\n\n**Sibyl-API** requires [MongoDB version 6 or 7](https://www.mongodb.com/try/download/community).\n\nTo install MongoDB, follow the instructions\n[here](https://www.mongodb.com/docs/manual/administration/install-community/).\n\n## Install from PyPi\n\nSibyl-API can be installed from pypi:\n```bash\npip install sibyl-api\n```\n\n## Install from source\n\nSibyl-API uses **Poetry** for dependency management. If you do not have *Poetry* installed, please head to [poetry installation guide](https://python-poetry.org/docs/#installation)\nand install poetry according to the instructions.\nRun the following command to make sure poetry is activated. You may need to close and reopen the terminal.\n\n```bash\npoetry --version\n```\n\nThen, you can clone this repository and install it from\nsource by running `poetry install`:\n\n```bash\ngit clone https://github.com/sibyl-dev/sibyl-api.git\ncd sibyl-api\npoetry install\n```\n\n# Quickstart\nFollow these steps to get started with the built-in Ames Housing dataset example.\nYou can prepare and load the Ames Housing dataset by running\n```bash\nsibyl prepare-sample-db\n```\n> \u26a0\ufe0f This function will overwrite any\nexisting database on localhost:27017 with the name **housing**):\n\n\nYou can now run Sibyl-API with the sample dataset with:\n```bash\npoetry run sibyl run -D housing -v\n```\n\nOnce Sibyl-API is running, you can access and test your APIs manually at `localhost:3000/apidocs`\n\n# Preparing database\nSibyl-API uses a MongoDB-based database system. We offer several methods to setup your database.\n\n## Preparing data\n### Required inputs\nAt minimum, sibyl-API requires the following inputs (either as a DataFrame or csv, see creation options below):\n\n**entities**: A table with the entities to be explained. Each row should correspond to a single observation.\n\nColumns:\n - `eid` (*required*): unique identifier specifying which entity this observation corresponds to\n - `row_id`: unique identifier specifying the observation ID. Together, `eid` and `row_id` should uniquely identify each observation.\n - `label`: the ground-truth label for this observation\n - `[FEATURES]`: additional columns for each feature used to make predictions. These columns should be named the same as the features used in the model.\n\nSample table:\n\n| `eid` | `row_id` | `label` | `feature1` | `feature2` | `feature3` |\n|---------|----------|---------|------------|------------|------------|\n| entity1 | 101 | 0 | 0.1 | 0.2 | 0.3 |\n| entity1 | 102 | 1 | 0.2 | 0.3 | 0.4 |\n| entity2 | 204 | 1 | 0.3 | 0.4 | 0.5 |\n\n**features**: A table with the features used to make predictions. Each row should correspond to a single feature.\n\nColumns:\n - `feature` (*required*): the name of the feature\n - `type` (*required*): the type of the feature. This can be `categorical`, `numerical`, or `boolean`\n - `description`: a description of the feature\n - `negative_description`: a description of the feature when it is not present. Only for boolean features\n - `values`: a list of possible values for the feature. Only for categorical features.\n\nSample table:\n\n| `feature` | `type` | `description` | `negative_description` | `values` |\n|-----------|--------|----------------------|--------------------------------|-----------------------------|\n| size | numerical | size in square feet | | |\n| has_ac | boolean | has air conditioning | does not have air conditioning | |\n| nghbrh | categorical | neighborhood | | [Oceanview, Ridge, Oakvale] |\n\n**realapp**: A pickled `pyreal.RealApp` object. This object is used to generate explanations for the model. \nSee [the pyreal documentation](https://dtail.gitbook.io/pyreal/) for details on setting this up.\n\n### Optional inputs\nAdditionally, you can configure APIs futher with:\n\n**config**: a configuration file (YAML or python dictionary) specifying\nadditional settings. See our [config documentation](https://dtail.gitbook.io/sibyl/user-guides/preparing-the-database/configuring-applications) for details.\n\n**categories**: a table with the categories used to make predictions. Each row should correspond to a single category.\n\nColumns:\n - `category` (*required*): the name of the category\n - `description`: a description of the category\n - `color`: color to use for the category\n - `abbreviation`: abbreviation to use for the category\n\n## Creating the Mongo database\n\n### With the prepare-db script\nBe sure to `start` your mongodb service before preparing the database\n\nCopy `sibyl/db/config_template.yml` and fill it in with your configurations. Place required data\nin a common directory.\n\nNext, run the preprocessing script with:\n```bash\nsibyl run prepare-db [CONFIG_NAME].yml [DIRECTORY]\n```\nwhere `[CONFIG_NAME].yml` is the path to your configuration file and `[DIRECTORY]` is\nthe directory containing your data.\n\n### With the Setup Wizard\nCurrently, the setup wizard is only available when installing from source.\nFirst, install the optional setup dependencies with\n```bash\npoetry install --with setup\n```\nThen, run the setup wizard with\n```bash\npoetry run streamlit run setup-wizard/main.py\n```\n\n# Running APIs\n\nOnce the library has been installed, you can run the APIs locally with:\n\n```bash\npoetry run sibyl run -v -D [DATABASE_NAME]\n```\n\nOr, to run in development mode:\n```bash\npoetry shell\n\nsibyl run -E development -v -D [DATABASE_NAME]\n```\n\nYou can then access your APIs locally at http://localhost:3000/apidocs\n\n# Contributing Guide\nWe appreciate contributions of all kinds! See [our contributing guide](https://dtail.gitbook.io/sibyl/developer-guides/contributing-to-sibyl) for instructions.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Explanation tool for machine learning",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/DAI-Lab/sibyl-api",
"Repository": "https://github.com/DAI-Lab/sibyl-api"
},
"split_keywords": [
"sibyl-api",
" sibyl",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "37b7aec8886eadc6ac64fdf1d3885e2e30f3fd340f1900d9c422729bfdd5e3e7",
"md5": "c3ed77d25a912e2f3fb4d232f4361212",
"sha256": "2d4e6c0d4ac4bb6b53d177224cceb5ac35ef4ed709ecef22dc1f8d2defb3be79"
},
"downloads": -1,
"filename": "sibyl_api-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c3ed77d25a912e2f3fb4d232f4361212",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "!=2.7.*,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,!=3.7.*,!=3.8.*,>=3.9",
"size": 52625,
"upload_time": "2024-06-12T14:51:11",
"upload_time_iso_8601": "2024-06-12T14:51:11.658959Z",
"url": "https://files.pythonhosted.org/packages/37/b7/aec8886eadc6ac64fdf1d3885e2e30f3fd340f1900d9c422729bfdd5e3e7/sibyl_api-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "506e6f51c6cae5f49268f91247cda979189fdef1cc03d4fae345ec49ef811ded",
"md5": "4c5d41513a4bd567491a5830780d6b0f",
"sha256": "566f961714ae2dbaba84773f2555c9fd6bdb5875993231a23c0cbf3c2e6a118a"
},
"downloads": -1,
"filename": "sibyl_api-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "4c5d41513a4bd567491a5830780d6b0f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "!=2.7.*,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,!=3.7.*,!=3.8.*,>=3.9",
"size": 44027,
"upload_time": "2024-06-12T14:51:13",
"upload_time_iso_8601": "2024-06-12T14:51:13.305809Z",
"url": "https://files.pythonhosted.org/packages/50/6e/6f51c6cae5f49268f91247cda979189fdef1cc03d4fae345ec49ef811ded/sibyl_api-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-12 14:51:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DAI-Lab",
"github_project": "sibyl-api",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sibyl-api"
}
