telemetry-client-py/CLAUDE.md

mosaicstack-telemetry (Python Client SDK)

Python client SDK for Mosaic Stack Telemetry. Reports AI coding task-completion telemetry and queries crowd-sourced predictions.

Development

# Install dependencies (including dev)
uv sync --all-extras

# Run tests (85%+ coverage required)
uv run pytest

# Lint
uv run ruff check src/ tests/

# Format check
uv run ruff format --check src/ tests/

# Type check
uv run mypy src/

Architecture

• src/mosaicstack_telemetry/client.py — Main TelemetryClient (public API)
• src/mosaicstack_telemetry/config.py — TelemetryConfig dataclass with env var support
• src/mosaicstack_telemetry/queue.py — Thread-safe bounded event queue
• src/mosaicstack_telemetry/submitter.py — Batch submission with retry/backoff
• src/mosaicstack_telemetry/_sync.py — Threading-based periodic submitter
• src/mosaicstack_telemetry/_async.py — Asyncio-based periodic submitter
• src/mosaicstack_telemetry/event_builder.py — Fluent event builder
• src/mosaicstack_telemetry/prediction_cache.py — TTL-based prediction cache
• src/mosaicstack_telemetry/types/ — All Pydantic models and enums

Key Rules

• track() must NEVER throw or block the caller
• All logging uses logging.getLogger("mosaicstack_telemetry")
• Runtime deps: httpx + pydantic only
• Python 3.10+ compatible (uses str, Enum mixin instead of StrEnum)