hannah-proto
Protobuf/gRPC schema definitions for the Hannah voice assistant ecosystem (Core, satellites, WebUI, ioBroker adapter, Telegram bot, and other consumers). This repo is the single source of truth for the wire protocol shared across all of them.
The .proto files live under hannah/, one per functional area — satellite control, event streaming, the ioBroker agent bridge, user registry, timers, automations, and so on. Nothing here is application code, just schema.
Distribution
Three independent, tag-triggered publish targets — pick whichever matches your language. Each contains only generated gRPC stubs/types for the current tagged release.
| Language | Package | Install |
|---|---|---|
| Python | PyPI hannah-proto |
pip install hannah-proto |
| TypeScript | npm @m1kad0/hannah-proto |
npm install @m1kad0/hannah-proto |
| Go | github.com/NurPech/hannah-proto-go | go get github.com/NurPech/hannah-proto-go |
Go has no separate package registry, so that tagged GitHub repo is the package — go get resolves it directly.
Versioning: PROTO_VERSION
Alongside the semver package/tag version, every release carries a single-integer PROTO_VERSION (see the PROTO_VERSION file). Hannah Core and its clients exchange this value on every call and reject a mismatch at runtime — that's the actual compatibility gate, not the semver tag. A breaking schema change requires bumping PROTO_VERSION; CI enforces this on every merge request via buf breaking.
Per-message compatibility: compat_version
PROTO_VERSION is repo-wide — any breaking change anywhere bumps it, forcing every consumer to reject, even ones that never call the affected RPC. compat_version (options.proto) is a finer-grained, independent counter set on an individual message:
message Foo {
option (compat_version) = 2;
...
}
Bump a message's compat_version only when that specific message has an actual breaking change. A message with no compat_version option carries an implicit value of 1 — don't backfill the option onto messages that have never had a breaking change. This lets a consumer-side interceptor check only the messages a given RPC call actually uses instead of rejecting on any unrelated proto change.
Deprecating fields and RPCs
Don't remove a field or RPC the moment it's unused — that forces every consumer to bump immediately, even ones that never touched it (see the SetGroupRooms incident that forced 9 unrelated components to bump, hannah-proto#9). Instead:
- Mark it
deprecated = true(protobuf's built-in field/method option) and note why + what replaces it in a comment. - Leave it in place until the next planned major cleanup, not the next release.
- Actually remove it (a breaking change,
PROTO_VERSIONbump) only during that cleanup, batched with other accumulated deprecations rather than one at a time.
Go/TypeScript/Python codegen surface deprecated = true automatically (Go doc comment, TS @deprecated JSDoc) — no extra tooling or config needed.
Compatibility checks
CI runs buf lint and buf breaking (against origin/master) on every MR. To check a local branch against a specific released version:
buf breaking --against '.git#tag=vX.Y.Z'
Changelog
See CHANGELOG.md for what changed release to release, including breaking changes and the consumers they affect.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file hannah_proto-3.7.1.tar.gz.
File metadata
- Download URL: hannah_proto-3.7.1.tar.gz
- Upload date:
- Size: 34.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
33e9f317c2706d9a64e5527d29076843833bf527b0edca6408d0f6216a65470f
|
|
| MD5 |
8b949ebe1adcda096841e5bd7f0a159c
|
|
| BLAKE2b-256 |
652928a11194a1f2f9df3b4e2833948c75c54df40966b2c2d0f4bf97e0cbcb2e
|
File details
Details for the file hannah_proto-3.7.1-py3-none-any.whl.
File metadata
- Download URL: hannah_proto-3.7.1-py3-none-any.whl
- Upload date:
- Size: 58.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/7.0.0 CPython/3.14.6
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8e35b1e3d6da2ef9da301c7fdae328d8ab0a3dccf2ea09ef1932d17ffd27d5d3
|
|
| MD5 |
5a418c82d3ddf3f8b746ddf27dced353
|
|
| BLAKE2b-256 |
8676513b8e67525eacf784cdd6978fbd98f0c837d819967733357616c6a66921
|
