# 
CoBaIR is a python library for **Co**ntext **Ba**sed **I**ntention **R**ecognition.
It provides the means to infer an intention from given context.
An intention is a binary value e.g. `repair pipe` that can either be present or not. Only one intention can be present at a time.
Context on the otherhand can have multiple discrete instantiations e.g. `weather:sunny|cloudy|raining`.
If context values are continuous, discretizer functions can be used to create discrete values.
From the inferred intention in a HRI scenario the robot can perform corresponding actions to help the human with a specific task.
## Publications
For a more in-depth explanation consult the following papers:
- [Concept Paper](https://www.dfki.de/fileadmin/user_upload/import/12351_lubitz_kimmi_cobabir_2022_-_Adrian_Lubitz.pdf)
- [Full Paper for IEEE RO-MAN Conference](https://arxiv.org/abs/2308.05627)
## Install
```bash
pip install CoBaIR
```
You can install the library from your local copy after cloning this repo with pip using `pip install .`
or install the newest experimental features from the `develop` branch with `pip install git+https://github.com/dfki-ric/CoBaIR.git@develop`
### Known Issues
On some Linux Distros there seems to be a problem with a shared library. [This Solutions](https://stackoverflow.com/questions/71010343/cannot-load-swrast-and-iris-drivers-in-fedora-35/72200748#72200748) suggests to `export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6
` which works on Ubuntu 22.04.
## Graphical User Interface
To make the configuration of a scenario easier we provide a Graphical User Interface(GUI). The GUI can be started with
```bash
python start_configurator.py
```
if you want to start the GUI with a loaded config use
```bash
python start_configurator.py -f config.yml
```
## Tutorial
For a step-by-step guide on how to use CoBaIR, check out our [Tutorial](docs/Tutorial.md).
## Documentation
The Documentation can be accessed on https://dfki-ric.github.io/CoBaIR/
## Bayesian Approach
In the bayesian approach CoBaIR uses a two-layer Bayesian Net of the following structure.
## Config Format
Configs will be saved in yml files. For convenience the is a configurator which can be started with
```bash
python start_configurator.py
```
### Bayesian Approach
The configuration file for a two layer bayesian net for context based intention recognition follows the given format:
```yaml
# List of contexts. Contexts can have different discrete instantiations.
# Number of instantiations must be larger than 1.
# For all discrete instantiations a prior probability must be given(sum for one context must be 1)
contexts:
context 1:
instantiation 1 : float
.
instantiation m_1 : float
context n:
instantiation 1 : float
.
instantiation m_n : float
# List of intentions. Intentions are always binary(either present or not)
# For every intention the context variables and their influence on the intention is given
# [very high, high, medium, low, very low, no] => [5, 4, 3, 2, 1, 0]
intentions:
intention 1:
context 1:
instantiation 1: int # one out of [5, 4, 3, 2, 1, 0]
.
instantiation m_1: int # one out of [5, 4, 3, 2, 1, 0]
context n:
instantiation 1: int # one out of [5, 4, 3, 2, 1, 0]
.
instantiation m_n: int # one out of [5, 4, 3, 2, 1, 0]
intention p:
context 1:
instantiation 1: int # one out of [5, 4, 3, 2, 1, 0]
.
instantiation m_1: int # one out of [5, 4, 3, 2, 1, 0]
context n:
instantiation 1: int # one out of [5, 4, 3, 2, 1, 0]
.
instantiation m_n: int # one out of [5, 4, 3, 2, 1, 0]
# decision_threshold is a float value between 0 and 1 which decides
# when an intention should be considered in inference.
# Probability must be greater than decision_threshold.
decision_threshold: float
```
# How to contribute
If you find any Bugs or want to contribute/suggest a new feature you can create a Merge Request / Pull Request or contact me directly via adrian.lubitz@dfki.de
## Run tests
Tests are implemented with [pytest](https://docs.pytest.org/en/7.1.x/).
To install test dependencies you need to run
```bash
pip install -r requirements/test_requirements.txt
```
Then you can run
```bash
python -m pytest tests/
```
You can as well see the test report for a specific commit in gitlab under [pipeline->Tests](hhttps://git.hb.dfki.de/kimmi_sf/implementation/CoBaIR/-/pipelines/39889/test_report)
### Coverage
If you want to see coverage for the tests you can run
```bash
coverage run -m pytest tests/
```
Use
```bash
coverage report
```
or
```bash
coverage html
```
You can as well see the coverage for a specific job in gitlab under [jobs](https://git.hb.dfki.de/kimmi_sf/implementation/CoBaIR/-/jobs)
To show results of the coverage analysis.
## Build docu
Documentation is implemented with the [material theme](https://squidfunk.github.io/mkdocs-material/) for [mkdocs](https://www.mkdocs.org/).
### Dependencies
Install all dependencies for building the docu with
```bash
pip install -r requirements/doc_requirements.txt
```
### Build
Build the docu with
```bash
mkdocs build
```
The documentation will be in the `site` folder.
# Authors
Adrian Lubitz & Arunima Gopikrishnan
## Funding
CoBaIR is currently developed in the [Robotics Group](https://robotik.dfki-bremen.de/de/ueber-uns/universitaet-bremen-arbeitsgruppe-robotik.html) of the [University of Bremen](https://www.uni-bremen.de/), together with the [Robotics Innovation Center](https://robotik.dfki-bremen.de/en/startpage.html) of the **German Research Center for Artificial Intelligence** (DFKI) in **Bremen**.
CoBaIR has been funded by the German Federal Ministry for Economic Affairs and Energy and the [German Aerospace Center](https://www.dlr.de/DE/Home/home_node.html) (DLR).
CoBaIR been used and/or developed in the [KiMMI-SF](https://robotik.dfki-bremen.de/en/research/projects/kimmi-sf/) project.
<p align="center">
<img src="https://raw.githubusercontent.com/oarriaga/altamira-data/master/images/funding_partners.png" width="1200">
</p>
Raw data
{
"_id": null,
"home_page": "https://github.com/dfki-ric/CoBaIR",
"name": "CoBaIR",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "intention recognition context human machine interaction robot bayesian",
"author": "Adrian Lubitz",
"author_email": "Adrian.Lubitz@dfki.de",
"download_url": "https://files.pythonhosted.org/packages/b1/c5/dbcbde7930c69e81b05929549969ad577beb89440b632b821f6bcc50b91a/CoBaIR-4.0.3.tar.gz",
"platform": null,
"description": "# \n\nCoBaIR is a python library for **Co**ntext **Ba**sed **I**ntention **R**ecognition. \nIt provides the means to infer an intention from given context. \nAn intention is a binary value e.g. `repair pipe` that can either be present or not. Only one intention can be present at a time.\nContext on the otherhand can have multiple discrete instantiations e.g. `weather:sunny|cloudy|raining`.\nIf context values are continuous, discretizer functions can be used to create discrete values.\nFrom the inferred intention in a HRI scenario the robot can perform corresponding actions to help the human with a specific task.\n\n## Publications\nFor a more in-depth explanation consult the following papers:\n\n- [Concept Paper](https://www.dfki.de/fileadmin/user_upload/import/12351_lubitz_kimmi_cobabir_2022_-_Adrian_Lubitz.pdf)\n- [Full Paper for IEEE RO-MAN Conference](https://arxiv.org/abs/2308.05627)\n\n\n\n## Install \n```bash\npip install CoBaIR\n```\nYou can install the library from your local copy after cloning this repo with pip using `pip install .` \nor install the newest experimental features from the `develop` branch with `pip install git+https://github.com/dfki-ric/CoBaIR.git@develop`\n\n### Known Issues\nOn some Linux Distros there seems to be a problem with a shared library. [This Solutions](https://stackoverflow.com/questions/71010343/cannot-load-swrast-and-iris-drivers-in-fedora-35/72200748#72200748) suggests to `export LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libstdc++.so.6\n` which works on Ubuntu 22.04.\n\n## Graphical User Interface\n![GUI](docs/images/simpleConfig.gif \"A simple configuration in the GUI\")\n\nTo make the configuration of a scenario easier we provide a Graphical User Interface(GUI). The GUI can be started with\n```bash\npython start_configurator.py\n```\nif you want to start the GUI with a loaded config use\n```bash\npython start_configurator.py -f config.yml\n```\n## Tutorial\nFor a step-by-step guide on how to use CoBaIR, check out our [Tutorial](docs/Tutorial.md).\n\n## Documentation\nThe Documentation can be accessed on https://dfki-ric.github.io/CoBaIR/\n\n\n## Bayesian Approach\nIn the bayesian approach CoBaIR uses a two-layer Bayesian Net of the following structure.\n\n\n## Config Format\nConfigs will be saved in yml files. For convenience the is a configurator which can be started with\n\n```bash\npython start_configurator.py\n```\n\n### Bayesian Approach\nThe configuration file for a two layer bayesian net for context based intention recognition follows the given format:\n\n```yaml\n# List of contexts. Contexts can have different discrete instantiations. \n# Number of instantiations must be larger than 1.\n# For all discrete instantiations a prior probability must be given(sum for one context must be 1)\ncontexts:\n context 1:\n instantiation 1 : float\n .\n instantiation m_1 : float\n context n:\n instantiation 1 : float\n .\n instantiation m_n : float\n# List of intentions. Intentions are always binary(either present or not)\n# For every intention the context variables and their influence on the intention is given\n# [very high, high, medium, low, very low, no] => [5, 4, 3, 2, 1, 0]\nintentions: \n intention 1:\n context 1:\n instantiation 1: int # one out of [5, 4, 3, 2, 1, 0]\n .\n instantiation m_1: int # one out of [5, 4, 3, 2, 1, 0]\n context n:\n instantiation 1: int # one out of [5, 4, 3, 2, 1, 0]\n .\n instantiation m_n: int # one out of [5, 4, 3, 2, 1, 0]\n intention p:\n context 1:\n instantiation 1: int # one out of [5, 4, 3, 2, 1, 0]\n .\n instantiation m_1: int # one out of [5, 4, 3, 2, 1, 0]\n context n:\n instantiation 1: int # one out of [5, 4, 3, 2, 1, 0]\n .\n instantiation m_n: int # one out of [5, 4, 3, 2, 1, 0]\n# decision_threshold is a float value between 0 and 1 which decides \n# when an intention should be considered in inference.\n# Probability must be greater than decision_threshold.\ndecision_threshold: float\n\n```\n# How to contribute\nIf you find any Bugs or want to contribute/suggest a new feature you can create a Merge Request / Pull Request or contact me directly via adrian.lubitz@dfki.de\n\n## Run tests\nTests are implemented with [pytest](https://docs.pytest.org/en/7.1.x/).\nTo install test dependencies you need to run \n\n```bash\npip install -r requirements/test_requirements.txt\n```\nThen you can run \n```bash\npython -m pytest tests/\n```\nYou can as well see the test report for a specific commit in gitlab under [pipeline->Tests](hhttps://git.hb.dfki.de/kimmi_sf/implementation/CoBaIR/-/pipelines/39889/test_report)\n\n### Coverage\nIf you want to see coverage for the tests you can run\n\n```bash\ncoverage run -m pytest tests/\n```\n\nUse \n\n```bash\ncoverage report\n```\nor \n\n\n```bash\ncoverage html\n```\n\nYou can as well see the coverage for a specific job in gitlab under [jobs](https://git.hb.dfki.de/kimmi_sf/implementation/CoBaIR/-/jobs)\n\nTo show results of the coverage analysis.\n## Build docu\nDocumentation is implemented with the [material theme](https://squidfunk.github.io/mkdocs-material/) for [mkdocs](https://www.mkdocs.org/).\n\n### Dependencies\nInstall all dependencies for building the docu with \n```bash\npip install -r requirements/doc_requirements.txt\n```\n### Build\nBuild the docu with \n```bash\nmkdocs build\n```\nThe documentation will be in the `site` folder.\n\n# Authors\nAdrian Lubitz & Arunima Gopikrishnan\n\n## Funding\nCoBaIR is currently developed in the [Robotics Group](https://robotik.dfki-bremen.de/de/ueber-uns/universitaet-bremen-arbeitsgruppe-robotik.html) of the [University of Bremen](https://www.uni-bremen.de/), together with the [Robotics Innovation Center](https://robotik.dfki-bremen.de/en/startpage.html) of the **German Research Center for Artificial Intelligence** (DFKI) in **Bremen**.\nCoBaIR has been funded by the German Federal Ministry for Economic Affairs and Energy and the [German Aerospace Center](https://www.dlr.de/DE/Home/home_node.html) (DLR).\nCoBaIR been used and/or developed in the [KiMMI-SF](https://robotik.dfki-bremen.de/en/research/projects/kimmi-sf/) project.\n\n<p align=\"center\">\n<img src=\"https://raw.githubusercontent.com/oarriaga/altamira-data/master/images/funding_partners.png\" width=\"1200\">\n</p>\n\n\n",
"bugtrack_url": null,
"license": "BSD 3-Clause",
"summary": "CoBaIR is a Python library for Context Based Intention Recognition",
"version": "4.0.3",
"project_urls": {
"Homepage": "https://github.com/dfki-ric/CoBaIR"
},
"split_keywords": [
"intention",
"recognition",
"context",
"human",
"machine",
"interaction",
"robot",
"bayesian"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1e65e426f7135d4fa637f0144681631e0c2af656de3286ca9e754172058e86d4",
"md5": "585df807f0e11070752455d1384d3f48",
"sha256": "b35ae15742d8014d290cdfb97b46725682d99a96c26123ccfe02f2b79ee8e3ea"
},
"downloads": -1,
"filename": "CoBaIR-4.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "585df807f0e11070752455d1384d3f48",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 38007,
"upload_time": "2023-12-20T09:17:40",
"upload_time_iso_8601": "2023-12-20T09:17:40.165243Z",
"url": "https://files.pythonhosted.org/packages/1e/65/e426f7135d4fa637f0144681631e0c2af656de3286ca9e754172058e86d4/CoBaIR-4.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b1c5dbcbde7930c69e81b05929549969ad577beb89440b632b821f6bcc50b91a",
"md5": "d52292fbf8e8e0eb5895edc357b146e1",
"sha256": "cb8404852f92a8bc7322fdf177317238b74ff1e3d6c1922175b7b53ae5e0b561"
},
"downloads": -1,
"filename": "CoBaIR-4.0.3.tar.gz",
"has_sig": false,
"md5_digest": "d52292fbf8e8e0eb5895edc357b146e1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 31012,
"upload_time": "2023-12-20T09:18:17",
"upload_time_iso_8601": "2023-12-20T09:18:17.779799Z",
"url": "https://files.pythonhosted.org/packages/b1/c5/dbcbde7930c69e81b05929549969ad577beb89440b632b821f6bcc50b91a/CoBaIR-4.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-20 09:18:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dfki-ric",
"github_project": "CoBaIR",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cobair"
}
JSON
