Ondewo CSI Client Python Library

This library facilitates the interaction between a user and a CAI server. It achieves this by providing a higher-level interface mediator.

This higher-level interface mediator is structured around a series of python files generated from protobuf files. These protobuf files specify the details of the interface, and can be used to generate code in 10+ high-level languages. They are found in the ONDEWO CSI API along with the older Google protobufs from Dialogueflow that were used at the start. The ONDEWO PROTO-COMPILER will generate the needed files directly in this library.

Python Installation

You can install the library by installing it directly from the PyPi:

pip install ondewo-csi-client

Or, you could clone it and install the requirements:

git clone git@github.com:ondewo/ondewo-csi-client-python.git
cd ondewo-csi-client-python
make setup_developer_environment_locally

Repository Structure

.
├── examples                                  <----- Helpful for implementation of code
│   ├── audiofiles
│   │   ├── config_basic_en_LJ_female_en.wav
│   │   ├── config_basic_kerstin_itsupport.wav
│   │   ├── config_basic_thorsten_german_medical.wav
│   │   └── pizza_de.wav
│   ├── convert_files.py
│   ├── healthcheck_example.py
│   ├── multi_client_example.py
│   ├── s2s_pipelines_example.py
│   ├── s2s_streaming_example.py
│   ├── speech2speech_example.py
│   ├── speech2speech_with_hangup_example.py
│   └── streamer.py
├── ondewo
│   ├── csi
│   │   ├── client
│   │   │   ├── services
│   │   │   │   ├── conversations.py
│   │   │   │   └── __init__.py
│   │   │   ├── client_config.py
│   │   │   ├── client.py
│   │   │   ├── __init__.py
│   │   │   └── services_container.py
│   │   ├── conversation_pb2_grpc.py
│   │   ├── conversation_pb2.py
│   │   ├── conversation_pb2.pyi
│   │   └── __init__.py
│   └── __init__.py
├── ondewo-csi-api                           <----- @ https://github.com/ondewo/ondewo-csi-api
├── ondewo-proto-compiler                    <----- @ https://github.com/ondewo/ondewo-proto-compiler
├── tutorials                                <----- Helpful for implementation of code
│   ├── s2t_examples
│   │   └── audiofiles
│   │       ├── sample_1.wav
│   │       └── sample_2.wav
│   ├── Jupyter_demo_helper.ipynb
│   └── Jupyter_demo.ipynb
├── CONTRIBUTING.md
├── Dockerfile.utils
├── LICENSE
├── Makefile
├── MANIFEST.in
├── mypy.ini
├── README.md
├── RELEASE.md
├── requirements-dev.txt
├── requirements.txt
├── setup.cfg
└── setup.py

Build

The make build command is dependent on 2 repositories and their speciefied version:

• ondewo-csi-api -- CSI_API_GIT_BRANCH in Makefile
• ondewo-proto-compiler -- ONDEWO_PROTO_COMPILER_GIT_BRANCH in Makefile

It will generate a _pb2.py, _pb2.pyi and _pb2_grpc.py file for every .proto in the api submodule.

⚠️ All Files in the ondewo folder that dont have pb2 in their name are handwritten, and therefor need to be manually adjusted to any changes in the proto-code.

Examples

The /examples folder provides a possible implementation of this library. To run an example, simply execute it like any other python file. Most examples load a JSON ClientConfig (see examples/configs/); keycloak_auth_example.py instead builds the config inline from environment variables. Authentication uses the Keycloak headless offline-token flow: the client logs in once and sends the auto-refreshed access token as Authorization: Bearer <jwt> on every RPC (the legacy http_token / cai-token HTTP-Basic login has been removed). The config fields are:

• host // The hostname of the Server - e.g. 127.0.0.1
• port // Port of the Server - e.g. 6600
• grpc_cert // gRPC Certificate of the server (optional; omit for an insecure channel)
• keycloak_url // Base URL of the Keycloak server - e.g. https://keycloak.ondewo.com/auth
• realm // Keycloak realm that owns the SDK client and the user
• client_id // Public Keycloak client id used for the ROPC grant (no client secret)
• username // Username (email) of the 2FA-exempt technical user; user_name is accepted as a legacy alias
• password // Password of the technical user
• token_expiration_in_s // Optional upper bound (seconds) on how long auto-refresh keeps renewing the token

Automatic Release Process

The entire process is automated to make development easier. The actual steps are simple:

TODO after Pull Request was merged in:

• Checkout master:

  git checkout master
  

• Pull the new stuff:

  git pull
  

• (If not already, run the setup_developer_environment_locally command):

  make setup_developer_environment_locally
  

• Update the ONDEWO_CSI_VERSION in the Makefile

• Add the new Release Notes in RELEASE.md in the format:

  ## Release ONDEWO CSI Python Client X.X.X       <---- Beginning of Notes
  
     ...<NOTES>...
  
  *****************                      <---- End of Notes
  

• Release:

  make ondewo_release
  

The release process can be divided into 6 Steps:

1. build specified version of the ondewo-csi-api
2. commit and push all changes in code resulting from the build
3. Create and push the release branch e.g. release/1.3.20
4. Create and push the release tag e.g. 1.3.20
5. Create a new Release on GitHub
6. Publish the built dist folder to pypi.org

⚠️ The Release Automation checks if the build has created all the proto-code files, but it does not check the code-integrity. Please build and test the generated code prior to starting the release process.