[![PyPI - License](https://img.shields.io/pypi/l/autotwin_pmswsgi)](https://github.com/AutotwinEU/proc-mining-serv/blob/main/LICENSE)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/autotwin_pmswsgi)](https://www.python.org/downloads/)
[![PyPI - Version](https://img.shields.io/pypi/v/autotwin_pmswsgi)](https://pypi.org/project/autotwin_pmswsgi/)
# Processing Mining Service (PMS) WSGI for Auto-Twin
The processing mining service (PMS) WSGI implements a RESTful API that invokes
different system discovery modules to automatically create, update and delete
graph models, Petri nets and automata in a system knowledge graph (SKG).
## Installation
To facilitate installation, the PMS WSGI is released as a Python module,
`autotwin_pmswsgi`, in the PyPI repository. `autotwin_pmswsgi` implicitly
depends on `pygraphviz`. This dependency however cannot be resolved
automatically by `pip`. As a preparation, you need to install `pygraphviz`
manually, following instructions provided
[here](https://pygraphviz.github.io/documentation/stable/install.html).
Whenever `pygraphviz` is available, the latest version of `autotwin_pmswsgi`
can be easily installed with `pip`.
pip install autotwin_pmswsgi
## Deployment
The PMS WSGI is almost ready to be deployed for production use once
`autotwin_pmswsgi` is installed successfully. Four environment variables are
additionally required to specify the [Neo4j](https://github.com/neo4j/neo4j)
instance that holds the SKG of the system under consideration.
| Name | Description |
|------------------|----------------------------------------------------------|
| `NEO4J_URI` | URI of the Neo4j instance, e.g. `neo4j://localhost:7687` |
| `NEO4J_USERNAME` | Username for the Neo4j instance, e.g. `neo4j` |
| `NEO4J_PASSWORD` | Password for the Neo4j instance, e.g. `12345678` |
| `NEO4J_DATABASE` | Database where the SKG is stored, e.g. `neo4j` |
After setting the above environment variables, you can start up the PMS WSGI on
a [Waitress](https://github.com/Pylons/waitress) server by executing
waitress-serve autotwin_pmswsgi:wsgi
## Containerization
To enable containerization, the PMS WSGI is also released as a Docker image,
`ghcr.io/autotwineu/proc-mining-serv`, in the GHCR registry. Suppose that a
Docker engine is running on your machine. Deploying the PMS WSGI on a Docker
container named `proc-mining-serv` can be done via a single command.
docker run --detach --env NEO4J_URI=<NEO4J_URI> --env NEO4J_USERNAME=<NEO4J_USERNAME> --env NEO4J_PASSWORD=<NEO4J_PASSWORD> --env NEO4J_DATABASE=<NEO4J_DATABASE> --name proc-mining-serv --pull always ghcr.io/autotwineu/proc-mining-serv
`<NEO4J_URI>`, `<NEO4J_USERNAME>`, `<NEO4J_PASSWORD>` and `<NEO4J_DATABASE>`
correspond to the values of the four environment variables required by the PMS
WSGI (see [Deployment](#deployment)).
## RESTful API
The PMS WSGI listens HTTP requests on port `8080` and is accessible through a
RESTful API that exposes the following endpoints for different types of models.
The content types of the request and response for each API endpoint are both
`application/json`.
--------------------------------------------------------------------------------
### API Endpoints for Graph Models
<details>
<summary>
<code>POST</code>
<code><b>/graph-model</b></code>
<code>(create a graph model in the SKG)</code>
</summary>
<br/>
**Parameters**
> None
**Body**
> Definition
>
> | Name | Type | Default | Description |
> |------------------------|-------------------------|--------------|-----------------------------------------------|
> | `name` | `string` | `"System"` | Name of the system to be discovered |
> | `version` | `string` | `""` | Version of the system to be discovered |
> | `neo4j:interval` | `array[number\|string]` | `[0.0, 0.0]` | Interval of the event log to be used |
> | `model:formula:ratio` | `number` | `0.0` | Minimum ratio of a formula to the primary one |
> | `model:delays:seize` | `number\|string` | `0.0` | Delay in seizing a queued part |
> | `model:delays:release` | `number\|string` | `0.0` | Delay in releasing a blocked part |
> | `model:cdf:points` | `number` | `100` | Maximum number of points in a CDF |
> Example
> ```json
> {
> "name": "Pizza Line",
> "version": "V4",
> "neo4j": {
> "interval": [0, 500000000]
> },
> "model": {
> "formula": {
> "ratio": 0.06
> },
> "delays": {
> "seize": 30000,
> "release": 0
> },
> "cdf": {
> "points": 100
> }
> }
> }
> ```
**Response**
> Code: 201
> Definition
>
> | Name | Type | Description |
> |------------|----------|---------------------------------|
> | `model_id` | `string` | ID of the generated graph model |
> Example
> ```json
> {
> "model_id": "4:d44864fe-b050-4f74-8157-60d999e3580b:273316"
> }
> ```
</details>
--------------------------------------------------------------------------------
### API Endpoints for Petri Nets
<details>
<summary>
<code>POST</code>
<code><b>/petri-net</b></code>
<code>(create a Petri net in the SKG)</code>
</summary>
<br/>
**Parameters**
> None
**Body**
> None
**Response**
> Code: 501
> Definition
>
> | Name | Type | Description |
> |---------------|----------|-------------------------------|
> | `code` | `string` | Code of the HTTP error |
> | `name` | `string` | Name of the HTTP error |
> | `description` | `string` | Description of the HTTP error |
> Example
> ```json
> {
> "code": 501,
> "name": "Not Implemented",
> "description": "The server does not support the action requested by the browser."
> }
> ```
</details>
--------------------------------------------------------------------------------
### API Endpoints for Automata
<details>
<summary>
<code>POST</code>
<code><b>/automaton</b></code>
<code>(create an automaton in the SKG)</code>
</summary>
<br/>
**Parameters**
> None
**Body**
> None
**Response**
> Code: 501
> Definition
>
> | Name | Type | Description |
> |---------------|----------|-------------------------------|
> | `code` | `string` | Code of the HTTP error |
> | `name` | `string` | Name of the HTTP error |
> | `description` | `string` | Description of the HTTP error |
> Example
> ```json
> {
> "code": 501,
> "name": "Not Implemented",
> "description": "The server does not support the action requested by the browser."
> }
> ```
</details>
--------------------------------------------------------------------------------
Raw data
{
"_id": null,
"home_page": "https://github.com/AutotwinEU/proc-mining-serv",
"name": "autotwin_pmswsgi",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "auto-twin, system discovery, restful service",
"author": "Lulai Zhu",
"author_email": "lulai.zhu@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e5/4a/8b387b1057fd1109e6f841bbd3679aa08e469260fa4d0c64c99b7f075100/autotwin_pmswsgi-0.1.2.tar.gz",
"platform": null,
"description": "[![PyPI - License](https://img.shields.io/pypi/l/autotwin_pmswsgi)](https://github.com/AutotwinEU/proc-mining-serv/blob/main/LICENSE)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/autotwin_pmswsgi)](https://www.python.org/downloads/)\n[![PyPI - Version](https://img.shields.io/pypi/v/autotwin_pmswsgi)](https://pypi.org/project/autotwin_pmswsgi/)\n\n# Processing Mining Service (PMS) WSGI for Auto-Twin\n\nThe processing mining service (PMS) WSGI implements a RESTful API that invokes\ndifferent system discovery modules to automatically create, update and delete\ngraph models, Petri nets and automata in a system knowledge graph (SKG).\n\n## Installation\nTo facilitate installation, the PMS WSGI is released as a Python module,\n`autotwin_pmswsgi`, in the PyPI repository. `autotwin_pmswsgi` implicitly\ndepends on `pygraphviz`. This dependency however cannot be resolved\nautomatically by `pip`. As a preparation, you need to install `pygraphviz`\nmanually, following instructions provided\n[here](https://pygraphviz.github.io/documentation/stable/install.html).\nWhenever `pygraphviz` is available, the latest version of `autotwin_pmswsgi`\ncan be easily installed with `pip`.\n\n pip install autotwin_pmswsgi\n\n## Deployment\nThe PMS WSGI is almost ready to be deployed for production use once\n`autotwin_pmswsgi` is installed successfully. Four environment variables are\nadditionally required to specify the [Neo4j](https://github.com/neo4j/neo4j)\ninstance that holds the SKG of the system under consideration.\n\n| Name | Description |\n|------------------|----------------------------------------------------------|\n| `NEO4J_URI` | URI of the Neo4j instance, e.g. `neo4j://localhost:7687` |\n| `NEO4J_USERNAME` | Username for the Neo4j instance, e.g. `neo4j` |\n| `NEO4J_PASSWORD` | Password for the Neo4j instance, e.g. `12345678` |\n| `NEO4J_DATABASE` | Database where the SKG is stored, e.g. `neo4j` |\n\nAfter setting the above environment variables, you can start up the PMS WSGI on\na [Waitress](https://github.com/Pylons/waitress) server by executing\n\n waitress-serve autotwin_pmswsgi:wsgi\n\n## Containerization\nTo enable containerization, the PMS WSGI is also released as a Docker image,\n`ghcr.io/autotwineu/proc-mining-serv`, in the GHCR registry. Suppose that a\nDocker engine is running on your machine. Deploying the PMS WSGI on a Docker\ncontainer named `proc-mining-serv` can be done via a single command.\n\n docker run --detach --env NEO4J_URI=<NEO4J_URI> --env NEO4J_USERNAME=<NEO4J_USERNAME> --env NEO4J_PASSWORD=<NEO4J_PASSWORD> --env NEO4J_DATABASE=<NEO4J_DATABASE> --name proc-mining-serv --pull always ghcr.io/autotwineu/proc-mining-serv\n\n`<NEO4J_URI>`, `<NEO4J_USERNAME>`, `<NEO4J_PASSWORD>` and `<NEO4J_DATABASE>`\ncorrespond to the values of the four environment variables required by the PMS\nWSGI (see [Deployment](#deployment)).\n\n## RESTful API\nThe PMS WSGI listens HTTP requests on port `8080` and is accessible through a\nRESTful API that exposes the following endpoints for different types of models.\nThe content types of the request and response for each API endpoint are both\n`application/json`.\n\n--------------------------------------------------------------------------------\n\n### API Endpoints for Graph Models\n\n<details>\n <summary>\n <code>POST</code>\n <code><b>/graph-model</b></code>\n <code>(create a graph model in the SKG)</code>\n </summary>\n <br/>\n\n**Parameters**\n> None\n\n**Body**\n> Definition\n>\n> | Name | Type | Default | Description |\n> |------------------------|-------------------------|--------------|-----------------------------------------------|\n> | `name` | `string` | `\"System\"` | Name of the system to be discovered |\n> | `version` | `string` | `\"\"` | Version of the system to be discovered |\n> | `neo4j:interval` | `array[number\\|string]` | `[0.0, 0.0]` | Interval of the event log to be used |\n> | `model:formula:ratio` | `number` | `0.0` | Minimum ratio of a formula to the primary one |\n> | `model:delays:seize` | `number\\|string` | `0.0` | Delay in seizing a queued part |\n> | `model:delays:release` | `number\\|string` | `0.0` | Delay in releasing a blocked part |\n> | `model:cdf:points` | `number` | `100` | Maximum number of points in a CDF |\n\n> Example\n> ```json\n> {\n> \"name\": \"Pizza Line\",\n> \"version\": \"V4\",\n> \"neo4j\": {\n> \"interval\": [0, 500000000]\n> },\n> \"model\": {\n> \"formula\": {\n> \"ratio\": 0.06\n> },\n> \"delays\": {\n> \"seize\": 30000,\n> \"release\": 0\n> },\n> \"cdf\": {\n> \"points\": 100\n> }\n> }\n> }\n> ```\n\n**Response**\n> Code: 201\n\n> Definition\n> \n> | Name | Type | Description |\n> |------------|----------|---------------------------------|\n> | `model_id` | `string` | ID of the generated graph model |\n\n> Example\n> ```json\n> {\n> \"model_id\": \"4:d44864fe-b050-4f74-8157-60d999e3580b:273316\"\n> }\n> ```\n\n</details>\n\n--------------------------------------------------------------------------------\n\n### API Endpoints for Petri Nets\n\n<details>\n <summary>\n <code>POST</code>\n <code><b>/petri-net</b></code>\n <code>(create a Petri net in the SKG)</code>\n </summary>\n <br/>\n\n**Parameters**\n> None\n\n**Body**\n> None\n\n**Response**\n> Code: 501\n\n> Definition\n> \n> | Name | Type | Description |\n> |---------------|----------|-------------------------------|\n> | `code` | `string` | Code of the HTTP error |\n> | `name` | `string` | Name of the HTTP error |\n> | `description` | `string` | Description of the HTTP error |\n\n> Example\n> ```json\n> {\n> \"code\": 501,\n> \"name\": \"Not Implemented\",\n> \"description\": \"The server does not support the action requested by the browser.\"\n> }\n> ```\n\n</details>\n\n--------------------------------------------------------------------------------\n\n### API Endpoints for Automata\n\n<details>\n <summary>\n <code>POST</code>\n <code><b>/automaton</b></code>\n <code>(create an automaton in the SKG)</code>\n </summary>\n <br/>\n\n**Parameters**\n> None\n\n**Body**\n> None\n\n**Response**\n> Code: 501\n\n> Definition\n> \n> | Name | Type | Description |\n> |---------------|----------|-------------------------------|\n> | `code` | `string` | Code of the HTTP error |\n> | `name` | `string` | Name of the HTTP error |\n> | `description` | `string` | Description of the HTTP error |\n\n> Example\n> ```json\n> {\n> \"code\": 501,\n> \"name\": \"Not Implemented\",\n> \"description\": \"The server does not support the action requested by the browser.\"\n> }\n> ```\n\n</details>\n\n--------------------------------------------------------------------------------\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Process Mining Service WSGI for Auto-Twin",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/AutotwinEU/proc-mining-serv"
},
"split_keywords": [
"auto-twin",
" system discovery",
" restful service"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "480821432e85c48f55adacb36361363a44a5fbf4b00c4afeffeb36c42672fd1d",
"md5": "2f65a5275d38676b5e746f95397e9759",
"sha256": "e5fba62b1e0b63793cee001a1a1fa36625ff988050f98dbfc346487a884c7b31"
},
"downloads": -1,
"filename": "autotwin_pmswsgi-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2f65a5275d38676b5e746f95397e9759",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 5547,
"upload_time": "2024-06-10T22:46:21",
"upload_time_iso_8601": "2024-06-10T22:46:21.719727Z",
"url": "https://files.pythonhosted.org/packages/48/08/21432e85c48f55adacb36361363a44a5fbf4b00c4afeffeb36c42672fd1d/autotwin_pmswsgi-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e54a8b387b1057fd1109e6f841bbd3679aa08e469260fa4d0c64c99b7f075100",
"md5": "394b1704643aaaaf2ba784d511d79d0e",
"sha256": "d6a383bfd4e8a6ee47c1ff5d13c5e067003e0404b0149102b31fb255e3b1df9c"
},
"downloads": -1,
"filename": "autotwin_pmswsgi-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "394b1704643aaaaf2ba784d511d79d0e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 5474,
"upload_time": "2024-06-10T22:46:22",
"upload_time_iso_8601": "2024-06-10T22:46:22.681733Z",
"url": "https://files.pythonhosted.org/packages/e5/4a/8b387b1057fd1109e6f841bbd3679aa08e469260fa4d0c64c99b7f075100/autotwin_pmswsgi-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-10 22:46:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AutotwinEU",
"github_project": "proc-mining-serv",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "autotwin_pmswsgi"
}