cts-contracts

Shared wire-contract datatypes for the Continuous Tracking platform, consumed by both the producer (continuous-tracking/tracking-orchestrator) and the consumer (cognitive-companion). Modelled on the existing triton-shared package pattern (a git-source-installed shared library), so there is no new infrastructure to learn.

Why this exists

The dementia-signal vocabulary and the protobuf wire types are currently duplicated across the two repos and kept in sync by discipline, not by construction:

• The canonical signal-kind strings are re-declared in tracking-orchestrator (app/domain/__init__.py Literal, app/transport/signal_publisher.py _KIND_TO_PROTO) and again in cognitive-companion (backend/services/cts/subscriber.py _PROTO_KIND_TO_STR).
• The generated protobuf Python bindings (continuoustracking/v1/*_pb2.py) are byte-for-byte committed into both repos and regenerated by a make proto-py target in continuous-tracking that writes into the sibling cognitive-companion checkout via a hard-coded relative path.

See cognitive-companion/SHARED-TYPES-PROPOSAL.md for the full analysis, the two-problem framing, and the phased migration plan.

Two layers, two problems

Layer	Problem	Solution	Status
Hand-written vocabulary (DementiaSignalKind, DementiaSignalSeverity)	Re-declared in 3+ places, can drift	This package (pure Python, no proto dep)	Scaffolded here
Generated protobuf bindings	Two committed copies + cross-repo Makefile path	buf-native versioned Python SDK (add a Python plugin to the existing buf.gen.yaml); ship as an optional extra of this package	Designed, deferred (lockstep migration)

Proto stays producer-owned (the source of truth lives with the service that emits the messages, in continuous-tracking/proto); this package generates and ships the Python SDK from it. The buf.yaml breaking: WIRE gate must be preserved.

Usage

from cts_contracts import DementiaSignalKind, DementiaSignalSeverity

kind = DementiaSignalKind.STILLNESS_ANOMALY
assert kind == "stillness_anomaly"          # StrEnum: equals its wire string
DementiaSignalKind.from_wire("absence")     # -> DementiaSignalKind.ABSENCE
DementiaSignalKind.from_wire("future_kind")  # -> None (render generically, never crash)

Consume from another repo (matching the triton-shared precedent) in pyproject.toml:

[project]
dependencies = ["cts-contracts>=0.1.0"]

[tool.uv.sources]
cts-contracts = { git = "https://github.com/SilverMind-Project/cts-contracts" }

Development

uv sync --extra dev
uv run pytest
uv run ruff check .
uv run mypy cts_contracts