| Name | pgeon-xai JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | |
| Summary | pgeon (or pgeon-xai) is a Python package that produces explanations for opaque agents using Policy Graphs (PGs) |
| upload_time | 2024-02-25 22:09:30 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | Copyright (c) 2023, 2024 Adrian Tormos, Victor Gimenez-Abalos, Dmitry Gnatyshak, Sergio Alvarez-Napagao, Barcelona Supercomputing Center Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
agents
artificial intelligence
explainability
policy graphs
reinforcement learning
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# pgeon / pgeon-xai
> Tormos, A., Abalos, V., Gnatyshak, D., & Alvarez-Napagao, S. (2023, October). [Policy graphs in action: explaining single- and multi-agent behaviour using predicates](https://openreview.net/forum?id=QPqL9xsYOf). In _XAI in Action: Past, Present, and Future Applications_.
**_pgeon_** (**_pgeon-xai_**) is a Python package that produces explanations for opaque agents using **Policy Graphs** (PGs).
A Policy Graph is a means to obtain a representation of the behavior of an opaque agent, in the form of a directed graph. Discrete states are mapped to nodes and actions to edges.
## Getting started
* Install **pgeon** with pip: `pip install pgeon-xai`
or:
1. Download the `pgeon/` folder and move it into the root directory of your project.
2. Install **pgeon**'s requirements with `pip install -r PATH_TO_PGEON_REQUIREMENTS`.
## Example usage
### Generating a Policy Graph
Given a Gymnasium `environment` and a `discretizer`, you can generate a PG to describe an opaque agent's behavior with `fit()`.
```python
from pgeon import PolicyGraph
pg = PolicyGraph(environment, discretizer)
pg = pg.fit(agent, num_episodes=1000)
```
### Creating and using a PG-based policy
There exist two PG-based policies. You can select one or the other with `PGBasedPolicyMode`.
```python
from pgeon import PGBasedPolicy, PGBasedPolicyMode
greedy_policy = PGBasedPolicy(pg, mode=PGBasedPolicyMode.GREEDY)
stochastic_policy = PGBasedPolicy(pg, mode=PGBasedPolicyMode.STOCHASTIC)
# Passing the policy an observation to get an action
obs, _ = environment.reset()
action = greedy_policy.act(obs)
```
### More examples
You can check [`examples/cartpole/demo.ipynb`](https://github.com/HPAI-BSC/pgeon/blob/main/example/cartpole/demo.ipynb) for a complete breakdown of **pgeon**'s features.
To run the notebook yourself:
1. Download the entire repository.
2. Install **pgeon**'s requirements with `pip install -r requirements.txt`.
3. Install an extra dependency, rllib, with `pip install "ray[rllib]"`.
4. Open and execute `examples/cartpole/demo.ipynb`.
## Citation
If you use the **pgeon** library, please cite:
```
@inproceedings{tormos2023policy,
title={Policy graphs in action: explaining single-and multi-agent behaviour using predicates},
author={Tormos, Adrian and Abalos, Victor and Gnatyshak, Dmitry and Alvarez-Napagao, Sergio},
booktitle={XAI in Action: Past, Present, and Future Applications},
year={2023},
url={https://openreview.net/forum?id=QPqL9xsYOf}
}
```
Raw data
{
"_id": null,
"home_page": "",
"name": "pgeon-xai",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Adrian Tormos <hpai@bsc.es>, Sergio Alvarez-Napagao <hpai@bsc.es>",
"keywords": "agents,artificial intelligence,explainability,policy graphs,reinforcement learning",
"author": "",
"author_email": "Adrian Tormos <hpai@bsc.es>, Victor Gimenez-Abalos <hpai@bsc.es>, Dmitry Gnatyshak <hpai@bsc.es>, Sergio Alvarez-Napagao <hpai@bsc.es>",
"download_url": "https://files.pythonhosted.org/packages/3c/ba/b0b5cd960494d91396fe711bab4b4447b21733526f3ffcaa7849a8be81a6/pgeon_xai-1.0.1.tar.gz",
"platform": null,
"description": "# pgeon / pgeon-xai\n\n> Tormos, A., Abalos, V., Gnatyshak, D., & Alvarez-Napagao, S. (2023, October). [Policy graphs in action: explaining single- and multi-agent behaviour using predicates](https://openreview.net/forum?id=QPqL9xsYOf). In _XAI in Action: Past, Present, and Future Applications_.\n\n**_pgeon_** (**_pgeon-xai_**) is a Python package that produces explanations for opaque agents using **Policy Graphs** (PGs).\n\nA Policy Graph is a means to obtain a representation of the behavior of an opaque agent, in the form of a directed graph. Discrete states are mapped to nodes and actions to edges.\n\n## Getting started\n\n* Install **pgeon** with pip: `pip install pgeon-xai`\n\nor:\n\n1. Download the `pgeon/` folder and move it into the root directory of your project.\n2. Install **pgeon**'s requirements with `pip install -r PATH_TO_PGEON_REQUIREMENTS`.\n\n\n## Example usage\n\n### Generating a Policy Graph\n\nGiven a Gymnasium `environment` and a `discretizer`, you can generate a PG to describe an opaque agent's behavior with `fit()`.\n\n```python\nfrom pgeon import PolicyGraph\n\npg = PolicyGraph(environment, discretizer)\npg = pg.fit(agent, num_episodes=1000)\n```\n\n### Creating and using a PG-based policy\n\nThere exist two PG-based policies. You can select one or the other with `PGBasedPolicyMode`.\n\n```python\nfrom pgeon import PGBasedPolicy, PGBasedPolicyMode\n\ngreedy_policy = PGBasedPolicy(pg, mode=PGBasedPolicyMode.GREEDY)\nstochastic_policy = PGBasedPolicy(pg, mode=PGBasedPolicyMode.STOCHASTIC)\n\n# Passing the policy an observation to get an action\nobs, _ = environment.reset()\naction = greedy_policy.act(obs)\n```\n\n### More examples\n\nYou can check [`examples/cartpole/demo.ipynb`](https://github.com/HPAI-BSC/pgeon/blob/main/example/cartpole/demo.ipynb) for a complete breakdown of **pgeon**'s features.\n\nTo run the notebook yourself:\n\n1. Download the entire repository.\n2. Install **pgeon**'s requirements with `pip install -r requirements.txt`.\n3. Install an extra dependency, rllib, with `pip install \"ray[rllib]\"`.\n4. Open and execute `examples/cartpole/demo.ipynb`.\n\n## Citation\n\nIf you use the **pgeon** library, please cite:\n\n```\n@inproceedings{tormos2023policy,\n title={Policy graphs in action: explaining single-and multi-agent behaviour using predicates},\n author={Tormos, Adrian and Abalos, Victor and Gnatyshak, Dmitry and Alvarez-Napagao, Sergio},\n booktitle={XAI in Action: Past, Present, and Future Applications},\n year={2023},\n url={https://openreview.net/forum?id=QPqL9xsYOf}\n}\n```\n",
"bugtrack_url": null,
"license": "Copyright (c) 2023, 2024 Adrian Tormos, Victor Gimenez-Abalos, Dmitry Gnatyshak, Sergio Alvarez-Napagao, Barcelona Supercomputing Center Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "pgeon (or pgeon-xai) is a Python package that produces explanations for opaque agents using Policy Graphs (PGs)",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/HPAI-BSC/pgeon/issues",
"Homepage": "https://github.com/HPAI-BSC/pgeon",
"Repository": "https://github.com/HPAI-BSC/pgeon"
},
"split_keywords": [
"agents",
"artificial intelligence",
"explainability",
"policy graphs",
"reinforcement learning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e51f7bd9c95163b1edca1fb61ec8d3d3db334daf70ad5e889deb6fa044b682d6",
"md5": "9042bf39e8b7743262c12b023d60b752",
"sha256": "3c8bfdb12920ef26a76fa20a622a697b1f393170db851cfafb611b7e27b69a46"
},
"downloads": -1,
"filename": "pgeon_xai-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9042bf39e8b7743262c12b023d60b752",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 11711,
"upload_time": "2024-02-25T22:09:28",
"upload_time_iso_8601": "2024-02-25T22:09:28.129871Z",
"url": "https://files.pythonhosted.org/packages/e5/1f/7bd9c95163b1edca1fb61ec8d3d3db334daf70ad5e889deb6fa044b682d6/pgeon_xai-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3cbab0b5cd960494d91396fe711bab4b4447b21733526f3ffcaa7849a8be81a6",
"md5": "de7350c84f11f4c50749bc0a1b6a6a84",
"sha256": "7c8d675f0ee264143740a434ea6c0e072ad1b4f607e6fd51f02ceab6442dd3c9"
},
"downloads": -1,
"filename": "pgeon_xai-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "de7350c84f11f4c50749bc0a1b6a6a84",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3470116,
"upload_time": "2024-02-25T22:09:30",
"upload_time_iso_8601": "2024-02-25T22:09:30.717587Z",
"url": "https://files.pythonhosted.org/packages/3c/ba/b0b5cd960494d91396fe711bab4b4447b21733526f3ffcaa7849a8be81a6/pgeon_xai-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-25 22:09:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HPAI-BSC",
"github_project": "pgeon",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "pgeon-xai"
}
