llm-sketchkit v0.4.0

llm-sketchkit 0.4.0

0.4.0 adds opt-in per-model input, output, cache-read and cache-write token
totals, reported and missing coverage, and a four-bin input-tier histogram to
summary exchange in Go and Python.

Go 1.26 or newer and Python 3.11 or newer remain required.

What's New

• Track token totals and reported/missing counts for each field, alongside
  invalid/conflicting usage, cache-partition violations and token provenance.
  Missing usage remains distinct from a reported zero.
• Group attempts by input-token tier, separating reported-input coverage from
  jointly complete input/output/cache splits, with token totals and input extrema
  for complete splits.
• Collect, validate and combine model-usage blocks through Go's modelusage
  package and Python's model_usage module. Leaving model_usage unset keeps
  the existing summary shape and base accounting.

See the integration contract for APIs, model/byte
budgets and update ordering.

Limits And Upgrade

Model Usage v1 records aggregates, not raw telemetry or prices. Combination
rejects mixed extension presence and incompatible contracts; applications must
also check their expected contract ID. Use summary combination for cumulative
snapshots rather than adding them as disjoint attempts.

Component/version	Model Usage v1
sketchkit Go/Python 0.2.3 and 0.3.0 readers	Reject enabled summaries, including enabled-empty blocks
sketchkit Go/Python 0.4.0 readers	Support enabled summaries and existing summaries without the extension
fleetdiff	Upcoming reader support; version unassigned
collector	Upcoming opt-in producer support; version unassigned

Upgrade all readers before enabling producers at a new observation-window
boundary. Retain capable readers for stored enabled windows: disabling new
emission does not make those windows readable by older readers.

This release updates golang.org/x/text from v0.42.0 to v0.43.0 without
changing its normalization implementation. For upgrades from 0.2.x, follow
the 0.3.0 identity migration.

llm-sketchkit v0.2.4

llm-sketchkit 0.2.4

Release date: 2026-10-16.

Identity-preserving maintenance backport, based on v0.2.3.

Model Usage

The optional model_usage extension adds bounded,
per-model token accounting to summary envelopes. Go and Python expose matching
validation, collection, contract identifiers, checked merging, and cumulative
snapshot replacement/replay behavior. Pricing examples are test-only; there is
no production price table or pricing API.

The shared corpus contains 112 named scenarios plus two separate contract
fixtures. Malformed Unicode/JSON, overflow, input-batch bounds, privacy, and
failure atomicity have dedicated regressions. No contract or frozen vector is
changed by this maintenance release.

Identity Boundary

This line retains v0.2.3 canonicalization, hash domains and framing, sketch
algorithms, and dependencies: Go 1.25.0 minimum, golang.org/x/text v0.41.0, and
google.golang.org/protobuf v1.36.12. The newer minor line is not substituted.

In particular, x/text v0.43.0 corrects supplementary-plane recomposition.
Those corrections can change Go text_v1 bytes and downstream hashes compared
with v0.2.3. For example, U+11F41 U+0301 yields hex e1bd85 on this maintenance
line and f091bd81cc81 with the newer dependency. The legacy behavior is retained
deliberately for identity continuity, not endorsed as corrected normalization.

Go minimum-version selection can select a newer x/text through another
dependency. Verify the consumer's resolved module graph and run its identity
fixtures; a direct sketchkit pin alone does not guarantee the older normalizer.
Python retains its historical runtime-dependent normalization and trim behavior.
Preservation means the same runtime and normalization dependency as v0.2.3, not
cross-language equivalence or an implicit migration of existing identities.

Reader-First Rollout

1. Upgrade readers to an extension-aware release. Use this maintenance line when
   v0.2.3 identity continuity is required. Evaluate a newer minor line separately
   when an identity migration is acceptable.
2. Confirm legacy summaries still round-trip byte-for-byte and enabled summaries
   pass validation. v0.2.3 and older readers reject enabled model_usage, including
   an empty block. A reader must not silently discard enabled accounting.
3. Enable producer output only after downstream readers are upgraded. Absence of
   model_usage preserves existing canonical summary bytes and means unavailable
   model accounting, not zero usage.

Existing summary and sketch formats remain unchanged when the extension is
absent. Structural preflight now rejects malformed JSON constants, invalid UTF-8,
and unpaired surrogate escapes consistently with full parsing. These malformed
inputs are not part of the preserved valid-wire contract.

Maintenance Release

Release from the v0.2.3-based maintenance branch with package version 0.2.4 and
tag v0.2.4; do not merge this branch into main. Main already has the extension
and its own normalization contract. Publication, signing, and consumer pinning
are separate release operations.

llm-sketchkit v0.3.0

llm-sketchkit 0.3.0

0.3.0 corrects text normalization and tightens summary validation. Some identities
change when upgrading from 0.2.2, in Go as well as Python.

Go Normalization

Updating golang.org/x/text from 0.41.0 to 0.42.0 fixes a composition-key bug.
For example, U+11F41 followed by certain combining marks could incorrectly become
Greek text, changing the resulting hash.

The Python alignment adds no Go identity change relative to current main, which
already uses 0.42.0. That statement does not apply to published 0.2.2.

Python Text Identities

The text_v1 profile trims exactly Unicode 15 White_Space and applies stream-safe
NFC normalization. Python output changes for these inputs:

• U+001C through U+001F at text edges are preserved instead of stripped.
• Runs exceeding 30 non-starters receive U+034F COMBINING GRAPHEME JOINER before
  the character that exceeds the limit. Counting includes compatibility
  decompositions and backward-combining characters, so fewer than 31 original
  characters can reach the limit.
• On Python 3.11, normalization involving Unicode 15 combining marks uses their
  correct classes: U+10EFD..U+10EFF, U+11F41..U+11F42, U+1E08F, and U+1E4EC..U+1E4EF.

The cross-language guarantee covers Unicode 15.0 assigned scalars, including
private-use values. It excludes unassigned values, noncharacters, and later
additions. Invalid UTF-8 remains an error.

Retained State

Profile names and wire formats are unchanged, so merge checks cannot identify a
mixture of old and corrected identities. Existing hashes or sketches alone cannot
be repaired.

Identify affected Go and Python producers, record their versions, and upgrade at
a new observation-window boundary. Keep affected old and new windows separate in
comparisons and merges. Rebuild only with legitimately available original inputs
and the original hash key; otherwise retain a separate historical series. Run
identity checks before resuming cross-language comparisons. Go-only deployments
using the older dependency also need this assessment. See the
migration guide for details.

Estimates And Validation

Python HLL++ bias sums use left-to-right addition. On Python 3.12 and later,
estimates may differ in their last bits. Stored registers, sketch bytes, and hash
identities are unchanged; recomputing the estimate is sufficient.

Both languages reject zero-length observation intervals containing nonzero
counters or nonempty sketch state. Empty intervals may contain zero counters
and configured empty sketches, including all-zero dense HLL++ state. Retained
totals, counts and register/bit content determine emptiness, not the presence of
serialized payloads. Tied epoch starts sort by end time, then epoch identifier.
Protobuf groups are rejected before decoding at every known message level; the
schema defines none.

Go 1.26 or newer is required. Test retained summaries and external encodings before
upgrading, including in Go-only systems.

llm-sketchkit v0.2.3

llm-sketchkit 0.2.3

0.2.3 focuses on limiting memory use when reading untrusted data, reducing repeated
work when combining summaries, and keeping secrets out of diagnostic output.

Bounded Parsing

Sketch readers check resource limits before protobuf decoding. Inputs are limited
to 64 KiB for HLL++ and frequent-items, 4 KiB for MinHash, and 2.5 MiB for Bloom,
within the existing global limit. Checks also cover discarded bodies and repeated
messages, so extra data cannot bypass the allocation limits.

Summary JSON readers check counter and sketch entry counts before building their
maps. Malformed protobuf is reported through the documented parser error types;
Go callers can continue to use errors.Is. Encodings that exceed the limits are
rejected even if a protobuf decoder could otherwise read them.

Less Repeated Work

Combining summaries validates each input once and bounds how much decoded state
remains in memory. Go accumulates completed groups; Python decodes selected
payloads again in merge order instead of retaining every decoded sketch. Inputs
remain unchanged. Python frequent-items also avoids repeated full-map scans when
choosing the smallest retained count, while preserving deterministic ties.

Safer Diagnostics And Packaging

Errors omit untrusted profile and domain text, and Python tracebacks suppress raw
inner messages at public boundaries. Go formatting redacts hash secrets,
including when a secret appears inside another value. Python preserves environment
key bytes without exposing them through Unicode conversion errors.

Release packaging resolves existing version tags to exact commits, generates the
software bill of materials separately from distributions, and refuses to overwrite
existing release assets.

Compatibility

This release backports the hardening changes onto 0.2.2 and retains Go 1.25
support and golang.org/x/text v0.41.0. It does not include the newer dependency's
normalization changes. Previously published 0.2.2 artifacts are unaffected.

Compatibility comparisons confirm unchanged text identities and HLL++ results
against 0.2.2 on the tested corpus, separately for Go, Python 3.11, and Python
3.14. Existing conformance-vector outputs also match exactly. Public APIs, profile
names, wire formats, and keyed hashing remain unchanged. Test representative retained
data against the resource limits before upgrading.

These comparisons use the release's dependency graph. Check your application's
resolved x/text version: another dependency can select a newer version and
change normalization behavior.

Go dependency-related and Python identity corrections, HLL++ estimate arithmetic
changes, and the new interval and protobuf-group acceptance rules belong in 0.3.0.

v0.2.2

Metadata-only maintenance release based on v0.2.1.

• Use Vijay consistently in package author metadata and source headers.
• Add a regression test for package author display names.
• Preserve Go 1.25/1.26 support, Python 3.11-3.14 support, dependencies, public APIs, sketch algorithms, and wire formats.

The Go 1.26 minimum on main remains reserved for the next minor release. This patch was built from the release/0.2 maintenance branch.

Install: python -m pip install --upgrade llm-sketchkit==0.2.2

Validation: Go race tests; 46 Python tests; supported-runtime, differential, notebook, protobuf, and package checks. PyPI publication, release assets, and public-install verification run automatically after publication.

v0.2.1

This patch hardens frequent-items decoding in Go and Python. Serialized states are rejected when retained item bounds contradict the declared total weight, including exact states with unaccounted weight. Shared validation vectors cover exact, lossy, empty, and integer-limit cases.

Valid encodings, sketch algorithms, hash domains, and public APIs are unchanged.

Install Python: python -m pip install --upgrade llm-sketchkit==0.2.1

Go module: github.com/llm-measurement/llm-sketchkit@v0.2.1

The release workflow publishes the Python package to PyPI and attaches distributions, checksums, and an SPDX dependency inventory here.

llm-sketchkit v0.2.0

Summary exchange across independent systems

Go and Python can now combine compatible window summaries from independently operated producers without pooling their raw telemetry.

• Versioned summary envelope carrying complete sketch state, counters, measurement scope, accounting rules and key version.
• Snapshot replay handling, restart epochs, and explicit missing-producer and partial-window reporting.
• Shared canonical fixtures and a local file-combination example.
• Existing sketch algorithms, hash domains and protobuf encodings are unchanged.

Install Python with python -m pip install llm-sketchkit==0.2.0, or use Go module tag v0.2.0. PyPI publication follows this release automatically.

Producers must observe disjoint input streams and use compatible configurations. Snapshot replay protection does not deduplicate underlying events. The envelope does not authenticate producers; summaries remain pseudonymous, not anonymous.

This release also includes expanded runtime and fuzz coverage, operational and supply-chain documentation, release SBOMs and checksums, and published-artifact installation checks. The previous 0.1.x line receives high/critical security fixes through 2026-12-04 under the support policy.

See the example, format contract, and changelog.

llm-sketchkit v0.1.0

The first supported 0.1.x release of llm-sketchkit.

Highlights:

• deterministic Go and Python implementations with shared conformance vectors
• mergeable HLL++, weighted frequent-items, Bloom filter, and MinHash summaries
• documented wire formats and named hash domains preserved across 0.1.x patch releases
• clean wheel and source-distribution verification
• runnable Go-to-Python notebook and Apache DataSketches oracle

Install from PyPI:

python -m pip install llm-sketchkit

No sketch semantics, profiles, hash domains, or wire encodings changed from v0.1.0-alpha.4.

llm-sketchkit v0.1.0-alpha.4

This alpha improves adoption guidance and source licensing metadata.

• Added task-oriented guidance and answers to common integration, capacity, privacy, and compatibility questions.
• Added Apache-2.0 SPDX identifiers to source files and an automated consistency check.

No sketch semantics, profiles, hash domains, or wire encodings changed in this release.

llm-sketchkit v0.1.0-alpha.3

Alpha.3 improves evidence, distribution quality, and release reproducibility without changing sketch semantics or wire encoding.

Highlights

• Adds a reproducible scorecard covering Linux performance, HLL++ error, Bloom false-positive rates, MinHash error, and the Apache DataSketches frequent-items oracle.
• Records a fresh five-run Linux benchmark on Go 1.26.5. The least favorable runs sustained 1,652,619 64-byte hashes/s/core and 850,340 1 KiB hashes/s/core; HLL++ and frequent-items updates remained at or below 10.58 ns/op and 145.6 ns/op with zero allocations.
• Builds and clean-installs both Python wheel and source distributions in CI.
• Keeps the generated protobuf module inside the llm_sketchkit package namespace.
• Updates GitHub Actions to current commit-pinned releases and adds tag-restricted PyPI trusted-publishing automation for use when the repository is public.

Verification

The tag and checksum manifest are signed by Vijay Erramilli with key 670D249E72D570B836D6F7589272956FD1758DDC.

git verify-tag v0.1.0-alpha.3
gpg --verify SHA256SUMS.asc SHA256SUMS
shasum -a 256 -c SHA256SUMS
python -m pip install ./llm_sketchkit-0.1.0a3-py3-none-any.whl

Reproduce

git clone https://github.com/llm-measurement/llm-sketchkit.git
cd llm-sketchkit
git checkout v0.1.0-alpha.3
go test ./... -race
python -m pip install -e ".[dev,oracle]"
python -m pytest -q
python scripts/datasketches_oracle.py --check
python scripts/render_scorecard.py --check

The Python artifacts are attached here. PyPI publication remains disabled while the repository is private.