Skip to content

Add privacy-conscious generation analytics#136

Draft
dewana-sl wants to merge 8 commits into
KittenML:mainfrom
dewana-sl:implement-analytics
Draft

Add privacy-conscious generation analytics#136
dewana-sl wants to merge 8 commits into
KittenML:mainfrom
dewana-sl:implement-analytics

Conversation

@dewana-sl
Copy link
Copy Markdown

@dewana-sl dewana-sl commented May 21, 2026

Summary

Adds lightweight generation analytics to the Python SDK so maintainers can understand basic usage patterns without adding an analytics SDK dependency or collecting user text/audio.

How analytics is handled

  • Sends one anonymous event for each generate, generate_to_file, or generate_stream invocation.
  • Uses a local anonymous UUID persisted under the KittenTTS analytics home, not account identity.
  • Captures SDK version, SDK type, platform, Python runtime, selected model, model version, selected voice, generation type, asset source, and SDK error code when a call fails.
  • Does not send prompt text, generated audio, stack traces, file paths, hostnames, usernames, or project names.
  • Supports opt-out with analytics=False at model construction or KITTENTTS_ANALYTICS=0.
  • Sends in a daemon background thread with a short timeout and swallows analytics failures so TTS generation and process shutdown remain unaffected.

Why this is better

This keeps the SDK dependency-free for analytics. It avoids pulling in a vendor client, avoids blocking inference on network calls, and documents the event contract clearly in docs/analytics.md. Streaming is tracked once per stream invocation instead of once per chunk, which keeps event volume proportional to user actions rather than text chunking internals.

Validation

  • python3 -m unittest -q
  • Editable install in a fresh virtualenv with declared package dependencies.
  • Import smoke for kittentts, KittenTTS, and normalize_text.
  • Real inference smoke with KittenML/kitten-tts-nano-0.8-int8 and KITTENTTS_ANALYTICS=0.
  • Real inference smoke with default analytics enabled, confirming generation succeeds and the process exits cleanly.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants