Ondewo S2T 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 S2T 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-s2t-client

Or, you could clone it and install the requirements:

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

Repository Structure

.
├── examples                           <----- Helpful for implementation of code
│   ├── audiofiles
│   │   ├── sample_1.wav
│   │   └── sample_2.wav
│   ├── configs
│   │   ├── insecure_grpc.json
│   │   └── secure_grpc_placeholder.json
│   ├── lm_data
│   │   └── shakespeare.zip
│   ├── file_transcription_example.py
│   ├── ondewo-s2t-with-certificate.ipynb
│   └── streaming_example.py
├── ondewo
│   ├── s2t
│   │   ├── client
│   │   │   ├── services
│   │   │   │   ├── __init__.py
│   │   │   │   ├── async_speech_to_text.py
│   │   │   │   └── speech_to_text.py
│   │   │   ├── utils
│   │   │   │   ├── __init__.py
│   │   │   │   └── keycloak.py        <----- D18 Keycloak headless offline-token provider
│   │   │   ├── __init__.py
│   │   │   ├── async_client.py
│   │   │   ├── async_services_container.py
│   │   │   ├── async_services_interface.py
│   │   │   ├── client.py
│   │   │   ├── client_config.py
│   │   │   ├── services_container.py
│   │   │   └── services_interface.py
│   │   ├── scripts
│   │   │   └── generate_services.py   <----- Generates the files marked auto-generated above
│   │   ├── __init__.py
│   │   ├── py.typed                   <----- PEP 561 marker; makes the shipped .pyi stubs usable
│   │   ├── speech_to_text_pb2_grpc.py
│   │   ├── speech_to_text_pb2.py
│   │   └── speech_to_text_pb2.pyi
│   └── __init__.py
├── test
│   └── unit                           <----- Hermetic unit tests; no S2T server required
├── ondewo-proto-compiler              <----- @ https://github.com/ondewo/ondewo-proto-compiler
├── ondewo-s2t-api                     <----- @ https://github.com/ondewo/ondewo-s2t-api
├── CLAUDE.md
├── CONTRIBUTING.md
├── Dockerfile.utils
├── LICENSE
├── Makefile
├── MANIFEST.in
├── README.md
├── RELEASE.md
├── pyproject.toml                     <----- Dependencies + ruff / mypy / coverage config
└── uv.lock                            <----- Committed lockfile; CI installs with --frozen

Build

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

• ondewo-s2t-api -- ONDEWO_S2T_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.

Development

The project is managed with uv; uv.lock is committed and CI installs frozen, so every dependency edit must be followed by uv lock.

make setup_developer_environment_locally   # installs uv, syncs .venv, installs the pre-commit hooks
uv run --frozen ruff check .               # lint
uv run --frozen mypy ondewo                # type check
make test                                  # unit tests + the 100% coverage gate

make test and the tests GitHub Actions workflow run the same gate: coverage scope lives in pyproject.toml under [tool.coverage.run] source = ["ondewo"], which coverage resolves by scanning the filesystem, so a new file with no tests fails --cov-fail-under=100 instead of being skipped. Only the generated *_pb2.py / *_pb2_grpc.py stubs are omitted.

Run the hooks over the whole tree with make precommit_hooks_run_all_files (or uv run --extra dev pre-commit run --all-files, or a bare uvx pre-commit run --all-files). The mypy hook is declared language: system so it can see the types-* stubs, and its entry is pinned to uv run --frozen --extra dev mypy so it finds them from any environment.

Examples

The /examples folder provides a possible implementation of this library. To run an example, simply execute it like any other python file and point it at a JSON config with --config (see examples/configs/). The config is parsed into ondewo.s2t.client.client_config.ClientConfig and supports the following fields:

• 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 (required for a secure channel)
• keycloak_url // Base URL of the Keycloak server (optional headless-auth parameter)
• realm // Keycloak realm (optional headless-auth parameter)
• client_id // Public Keycloak client id, no secret (optional headless-auth parameter)
• username // Technical-user email/username for the Keycloak ROPC grant (optional)
• password // Technical-user password (optional)

user_name is still accepted as a backward-compatible alias for username; when both are set, username wins.

A bare {"host": ..., "port": ...} config (as in examples/configs/insecure_grpc.json) stays valid for an unauthenticated / ingress-injected-auth server; the Keycloak fields are only required together when any one of them is set.

Authentication (Keycloak bearer)

When the config carries the Keycloak fields, the SDK authenticates headlessly against a public Keycloak client (no client secret — D18/Q1) using the offline-token flow: a one-time Resource Owner Password Credentials login (grant_type=password with scope=offline_access) yields a long-lived offline refresh token, and the client then auto-refreshes a short-lived access token in the background before it expires. The technical user is 2FA-exempt (D14), so ROPC bypasses the browser flow.

Client and AsyncClient forward this token automatically: every RPC issued through the service wrappers travels with the canonical gRPC metadata Authorization: Bearer <jwt>, so application code never has to build or refresh the header itself. A config without the Keycloak fields sends no such header and calls travel unauthenticated (e.g. against a plaintext server or an Envoy ingress that injects auth).

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_S2T_VERSION in the Makefile

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

  ## Release ONDEWO S2T 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-s2t-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.