Metadata-Version: 2.4
Name: aas-thing
Version: 0.9.8.dev0
Summary: A Python toolkit for building Industry 4.0-compliant Things as Asset Administration Shells (AAS), with seamless integration into the Smart Systems Service Infrastructure (S³I).
Author-email: The S3I Development Team <s3i@kwh40.de>
License-Expression: LGPL-3.0-only
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pytest>=7.0
Requires-Dist: pytest-asyncio
Requires-Dist: pika==1.3.2
Requires-Dist: python-keycloak
Requires-Dist: basyx-python-sdk==1.2.0
Requires-Dist: pyyaml
Requires-Dist: jsonschema
Requires-Dist: aas-python-http-client==1.0.3
Requires-Dist: pydantic
Provides-Extra: docs
Requires-Dist: Sphinx==5.0.2; extra == "docs"
Requires-Dist: recommonmark==0.6.0; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Requires-Dist: sphinx-tabs; extra == "docs"
Requires-Dist: sphinxcontrib-images; extra == "docs"
Dynamic: license-file

# Asset Administration Shell (AAS) Thing Python SDK  

[![PyPI Release](https://img.shields.io/badge/pypi-v1.0.0_-orange)](https://pypi.org/project/fml40-reference-implementation/)  [![License: LGPL v3](https://img.shields.io/badge/License-LGPLv3%20-blue.svg)](https://www.gnu.org/licenses/lgpl-3.0.html)

A Python toolkit for building **Industry 4.0**-compliant Things using Asset Administration Shell (AAS), with seamless integration into the Smart Systems Service Infrastructure (S³I). 
Please refer to the whitepaper for details:

> Hoppen M., Chen, J., Roßmann, J. (2025) Smart Systems Service Infrastructure (S3I) — Design and deployment of the Smart Systems Service Infrastructure (S3I) for decentralized networking in Forestry 4.0. KWH4.0 Position Paper. DOI: [10.18154/RWTH-2025-03168](https://doi.org/10.18154/RWTH-2025-03168) 

---

## Table of Contents

- [Overview](#overview)  
- [Features](#features)  
  - [Core Functionality](#core-functionality)  
  - [Roadmap](#roadmap) 
- [Technical Structure](#technical-structure)  
- [Installation](#installation)  
- [Documentation](#documentation)  
- [Contributing](#contributing)  
- [License](#license)  

---

## Overview

The AAS Thing Python SDK helps you:

- Instantiate and manipulate AAS and submodels using the Eclipse [BaSyx Python SDK](https://github.com/eclipse-basyx/basyx-python-sdk)
- Exchange standardized I4.0 messages ([VDI 2193-1](https://www.vdi.de/fileadmin/pages/vdi_de/redakteure/richtlinien/inhaltsverzeichnisse/3134409.pdf)) over AMQP (store-and-forward) or (in future) HTTP  
- Authenticate, manage and discover services, exchange information via the S³I core (IdentityProvider, Directory, Repository, Broker)  

By following the AAS specification, your Things become members in Industry 4.0 ecosystems, interoperating securely and reliably.

---

## Features

### Core Functionality

- **AAS management**  
  Load and parse `.json`, `.xml`, or `.aasx` AAS on disk using [BaSyx Python SDK](https://github.com/eclipse-basyx/basyx-python-sdk).

- **Message-based communication**  
  Create, send and receive I4.0 messages (`I40Message`) combined with the AAS API specification defined in [Specification of the Asset Administration Shell Part 2](https://industrialdigitaltwin.org/en/content-hub/aasspecifications/specification-of-the-asset-administration-shell-part-2-application-programming-interfaces-idta-number-01002-3-0-4), over AMQP (store-and-forward) or (in future) HTTP.


- **S³I integration**  
  - **IdentityProvider**: OpenID Connect authentication via Keycloak  
  - **Broker**: AMQP 0.9 messaging with RabbitMQ  
  - **Directory & Repository**: Endpoint discovery and cloud storage  

### Global instance of S³I
  We provide a global instance of the S³I, which runs in a server located at [MMI](https://www.mmi.rwth-aachen.de/), RWTH Aachen University and can be used for testing. It includes:

| Name                        | Endpoint                                                                                                 |
|-----------------------------|---------------------------------------------------------------------------------------------------------|
| `S³I IdentityProvider`      | https://idp.mmi-0.s3i.mmi-services.de/                                                                  |
| `S³I Broker`                | https://broker.mmi-0.s3i.mmi-services.de/                                                                |
| `S³I Directory`             | [https://dir.mmi-0.s3i.mmi-services.de/](https://dir.mmi-0.s3i.mmi-services.de/swagger-ui/index.html)   | 
| `S³I Repository`            | [https://repo.mmi-0.s3i.mmi-services.de/](https://repo.mmi-0.s3i.mmi-services.de/swagger-ui/index.html) |
| `S³I Config`                | [https://config.mmi-0.s3i.mmi-services.de/](https://config.mmi-0.s3i.mmi-services.de/apidoc)            |
| `S³I Postbox API`           | [https://postbox.mmi-0.s3i.mmi-services.de/](http://postbox.mmi-0.s3i.mmi-services.de/apidoc)           |	
| `S³I Manager (coming soon)` | http://manager.mmi-0.s3i.mmi-services.de/                                                               |	

### Roadmap of the SDK
In the near future, we will provide the supports to: 
- **Postbox API**: REST-based alternative to AMQP for sending and receiving I4.0 messages
- **Discovery Service**: Endpoint discovery using query parameters
- **Authorization**: XACML-based access control framework 
- **Events**: Support for AAS- and AMQP-based events
- **Server Infrastructure**: The open-source server infrastructure for the Smart Systems Service Infrastructure (S³I) and its configuration for docker and kubernetes

---

## Technical Structure

| Module                               | Purpose                                                                              |
|--------------------------------------|--------------------------------------------------------------------------------------|
| `aas_thing/core.py`                  | `BaseAASThing`: lifecycle, configuration, event loop                                 |
| `aas_thing/aas_connection.py`        | `AASConnector`: load/sync AAS & submodels                                            |
| `aas_thing/s3i_connection.py`        | `S3IConnector`: interface to S³I IdentityProvider, Broker                            | 
| `aas_thing/message_handler.py`       | `I40SemanticProtocolHandler`: handle_request, handle_reply of incoming I4.0 messages |
| `aas_thing/s3i.identity_provider.py` | `S3IIdentityProviderClient`: create connection to S³I IdP                            |
| `aas_thing/s3i.broker.py`            | `S3IBrokerAMQPClient`: create connection to S³I Broker                               |
| `aas_thing/s3i.directory.py`         | `S3IDirectoryClient`: create connection with S³I Directory                           |
| `aas_thing/s3i.repository.py`        | `S3IRepositoryClient`: create connection with S³I Repository                         |

---

## Installation

Install from PyPI:

```bash
$ python -m pip install aas-thing
```

Or build & install from source:

```bash
$ git clone git@git.rwth-aachen.de:co2for-it/s3i/aas-thing-python-sdk.git
$ cd aas-thing-python-sdk
$ python -m pip install .
```

### Thing lifecycle

Constructing a `BaseAASThing` is local-only: it loads configuration and stores
handler registrations, but does not contact the Identity Provider, AAS
Repository, or AMQP Broker. Network resources are acquired by `open()` and
released by `close()`.

```python
thing = DemoHarvester("config.yaml")
thing.register_operation_handler(
    submodel_id=f"{thing.thing_id}/JobManagement",
    operation_id="AcceptJob",
    handler=thing.acceptJob,
)
thing.start()  # synchronous wrapper around asyncio.run(thing.serve_forever())
```

Async applications can manage the same lifecycle explicitly:

```python
async with thing:
    await thing.wait_until_stopped()
```

`open()` authenticates and loads the AAS first, validates and binds queued
handlers next, and only then opens Broker channels. Startup failures trigger
automatic rollback of resources that were already acquired.

The supported public integration surface is:

```python
thing.register_operation_handler(submodel_id, operation_id, operation_handler)
thing.register_event_handler("factory/jobs", event_handler)
thing.register_reply_handler(correlation_id, reply_handler)

thing.on_idp_ready(on_idp)
thing.on_repository_ready(on_repository)
thing.on_message_broker_ready(on_messages)
thing.on_event_broker_ready(on_events)

thing.subscribe("factory/jobs")
reply = await thing.send_request(request, timeout=10)
thing.stop()
```

Synchronous handlers are run in worker threads so that they do not block the
event loop; coroutine handlers are awaited directly. During shutdown, consumers
are stopped first, active handlers are drained, maintenance tasks and pending
requests are cancelled, Broker connections are awaited, and the IdP is closed
last.

### Configuration

`s3i_connector.identity_provider` and exactly one `aas_connector` backend
(`http` or `file`) are required. Message Broker, Event Broker, Authorization,
and Directory sections are optional. The whole configuration is validated when
the Thing is constructed.

Relative paths passed as the configuration filename are resolved against the
current working directory. A relative `aas_connector.file.path` is resolved
against the directory containing that configuration file.

Secrets can be supplied without committing them to YAML:

```yaml
client_id: "${S3I_CLIENT_ID}"
client_secret: "${S3I_CLIENT_SECRET}"
request_timeout: 30
broker_connect_timeout: 30
```

Values use the process environment by default. Applications with a secret
provider can inject its resolved mapping through
`BaseAASThing(..., config_values=secret_values)`. `${NAME:-default}` supplies an
optional fallback.

## Documentation
Full API reference, tutorials, and demos are available in the [documentation](https://co2for-it.pages.rwth-aachen.de/s3i/aas-thing-python-sdk/).

## Contributing
Contributions, bug reports, and feature requests are welcome! 

Please:

- Fork the repository
- Create a feature branch (``git checkout -b feature/XYZ``)
- Commit your changes (``git commit -m "Add XYZ"``)
- Push to your fork (``git push origin feature/XYZ``)
- Open a Merge Request

See ``CONTRIBUTING.md`` for detailed guidelines.

## License
This project is licensed under the LGPL v3 License. See the ``LICENSE`` file for details.
