feat: add sample status client, conversions, and query filtering

[craigmcchesney]

Adds a client interface to the MLDP Sample Status API (new in dp-grpc 1.16.0, added by dp-grpc#139).

Closes #8

What's here

Commit
cbe9631	Raise grpcio/protobuf floors to match the regenerated stubs
e783775	SampleStatusClient — the four live RPCs
053c149	Bucket conversions — per-sample expansion
6c5b292	SampleStatusSelector support in QueryClient
0f937ff	Cookbook recipe, CLAUDE.md, integration tests
7fa3368	Record end-to-end verification

Scope follows the agreed plan: the four live RPCs, the query-selector integration, bucket conversions, and the cookbook recipe. The deferred domain-registry RPCs (saveSampleStatusDomain / querySampleStatusDomains) are not wrapped — they are reserved placeholders returning "not implemented".

Two model properties drove the design

Both are easy to violate silently, so each is pinned by tests.

Absence means "no assertion." There is no implicit default status; labeling three samples says nothing about the rest. So absent confidence/reasons surface as None — never 0.0/"". 0.0 is a legitimate confidence value, so a fabricated default would be indistinguishable from a real "I am certain this is fine."

Matching is by exact timestamp at nanosecond precision. No nearest-sample search, no tolerance window. expand_data_timestamps() therefore computes SamplingClock positions as startTime + i * periodNanos in integer nanoseconds. Present-day epoch nanos need ~61 bits against float64's 53 mantissa bits, so a float-seconds round-trip would produce timestamps matching nothing.

New patterns

Where the PV-metadata and machine-config patterns carried over they were followed; four places needed something new:

• Structured frame construction — sampling_clock() / timestamp_list() axis builders, with per-timestamp length rules validated client-side so a mistake names the offending PV instead of bouncing the whole batch. timestamp_list() compares nanoseconds, not just seconds, when enforcing strict increase.
• No criterion-builder class — deliberately. The request takes plain repeated string filters (ANDed across, ORed within), so plain lists are the honest representation rather than ceremony imitating PvMetadataQuery.
• Explicit wildcard opt-in — delete_sample_statuses() requires pv_names or all_pvs=True, raising on neither or both, so the destructive every-PV delete is never reached by omitting an argument.
• SampleStatusFilter.include()/.exclude() as the only constructors, making the server-rejected MODE_UNSPECIFIED zero value unreachable.

A note at a shared seam

_build_query_spec() is shared with the future bucket-oriented client (#16), where the server rejects sampleStatusSelector — a bucket is a stored unit that cannot be partially filtered without rewriting it. A comment at the seam records that a bucket request builder must refuse sample_status_filter rather than copy it through into a request the server would reject.

Verification

• 418 tests pass against a live 1.16.0 stack (401 on CI's unit-only path); ruff lint/format clean; all 78 cookbook snippets type-check.
• Integration tests confirm the exact-timestamp contract end to end — including a dense case labeling 100 samples at 1 kHz and checking every expanded position. That is the assertion unit tests over hand-built objects fundamentally cannot make.
• Mutation-tested rather than trusting green tests. This caught a real gap: the first limit=0 test asserted request.limit == 0, which passes even with the PvMetadataClient query ignores limit=0 (truthiness bug) #13 truthiness bug, because a proto3 scalar set to 0 is indistinguishable from unset — both serialize to zero bytes and report empty ListFields(). Patching the protobuf property raises AttributeError, so the test now spies on the assignment. That test carries more machinery than a unit test usually wants; it's the one spot worth a close look in review.

Worth knowing

• The floor fix is in this PR by choice. It's three lines in pyproject.toml and the only commit touching that file, but it belongs here substantively: the bug was reachable only because the same stub regen that added these RPCs raised the stubs' import-time grpcio requirement above the declared floor. Without it, pip install can produce a package that fails at import.
• Integration tests probe for the API before running. A pre-1.16.0 Annotation Service accepts the connection and then answers every sample status call with UNIMPLEMENTED — reachability alone is not a sufficient skip check, and without the probe this surfaces as seven assertion failures instead of a skip.
• One caveat remains: status filtering of query results is unit-tested only. The integration tests write statuses and read them back, but with no Python ingestion path (Add ingestion API client (full surface: ingestData + streaming) #17) those statuses have no underlying samples to attach to, so "this PV minus what the model flagged" hasn't been watched to actually drop rows. Flagged in the recipe and CLAUDE.md, with Add ingestion API client (full surface: ingestData + streaming) #17 as the trigger to re-verify.

🤖 Generated with Claude Code

https://claude.ai/code/session_017CvckaDwdLbD29hd23ur2a

[Copilot]

Pull request overview

This PR adds first-class support for MLDP’s Sample Status API to dp-python-lib, including a new SampleStatusClient, per-sample “bucket → rows” conversions, and optional sample-status-based filtering for v2 sample queries.

Changes:

• Introduces SampleStatusClient under the annotation facade (client.annotation.sample_status) with params/types and three-tier error handling.
• Adds sample_status_conversions utilities to expand SampleStatusBucket results into flat per-sample SampleStatusRow objects with nanosecond-exact timestamp expansion.
• Extends QueryClient/QueryParams with SampleStatusFilter → QuerySpec.sampleStatusSelector support, and documents/tests the new behavior.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/dp_python_lib/client/sample_status_client.py	New Sample Status feature client + axis builders + request/response wrappers.
src/dp_python_lib/client/sample_status_conversions.py	New conversion layer: expand sample-status buckets into per-sample rows with exact-nanos timestamps.
src/dp_python_lib/client/query_client.py	Adds SampleStatusFilter helper + wires sampleStatusSelector into _build_query_spec().
src/dp_python_lib/client/query_conversions.py	Documentation update noting valueStatus deprecation in favor of sample status.
src/dp_python_lib/client/annotation_client.py	Mounts the new SampleStatusClient on the annotation facade.
src/dp_python_lib/client/__init__.py	Exposes sample status client/types/helpers from dp_python_lib.client.
tests/unit/test_sample_status_client.py	Unit tests for request building, validation, paging/streaming behavior, and error handling.
tests/unit/test_sample_status_conversions.py	Unit tests for exact timestamp expansion and bucket→row conversion semantics.
tests/unit/test_query_client.py	Unit tests for SampleStatusFilter and request building with sampleStatusSelector.
tests/integration/test_sample_status_client_integration.py	Live-service integration tests for save/query/delete, axis round-trip, and upsert semantics.
tests/integration/conftest.py	Minor docstring clarification for integration-test prerequisites.
doc/cookbook/sample-status.md	New cookbook recipe documenting labeling, reading back, and query filtering usage.
doc/cookbook/README.md	Adds cookbook index entry for sample status recipe.
doc/cookbook/query.md	Adds cross-reference to sample status as the replacement for valueStatus.
CLAUDE.md	Adds sample status client/conversions overview and usage notes.
.dev/tools/check-cookbook-snippets.py	Extends snippet-checker preamble imports to include new sample status symbols.
pyproject.toml	Raises grpcio/protobuf (and grpcio-tools) minimum versions to match regenerated stubs.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[craigmcchesney]

Review fixes — bbb0caa

All four Copilot findings addressed, plus one rename from review. Replies are in each thread; summary here.

#	Finding	Outcome
1	_timestamp_count() allows empty axes	Fixed — guard added, both arms
2	QueryParams does not validate the selector	Fixed — the substantive one
3	Cookbook None wording	Fixed in all three annotation pages
4	Float arithmetic in integration test	Changed — valid in principle, not actually flaky
—	test_streaming_request_carries_the_selector_too	Renamed

The rename (not from Copilot)

That test called _build_query_samples_request() — the unary builder — so its name promised something it did not do. Coverage was not missing: iter_query_samples_stream() uses that same builder (query_client.py:709), so exercising it does cover the streaming path. Renamed to test_selector_reaches_the_streaming_path_via_the_shared_builder, with a comment recording why, so a future split into two builders fails loudly rather than silently leaving the streaming path unfiltered.

Two claims in the PR description that were verified, not assumed

• Integer-nanosecond expansion is genuinely necessary. datetime.timestamp() has a ULP of ~238ns at present-day epochs — it cannot represent nanoseconds at all. The design reasoning holds.
• The limit=0 spy test earns its machinery. Confirmed a proto3 scalar set to 0 is indistinguishable from unset via reflection, so watching the assignment really is the only way to catch the PvMetadataClient query ignores limit=0 (truthiness bug) #13 truthiness bug.

Docs corrected beyond the code

Finding #2 exposed a docs overstatement: CLAUDE.md and the cookbook both said include()/exclude() were "the only ways" to build a selector, making MODE_UNSPECIFIED unreachable. That was the intent, but the parameter accepts any SampleStatusSelector, so it was never actually unreachable. Both now describe what the code enforces.

Verification

• 423 passed, 1 skipped (401 unit → 406 unit, +5 pinning the new guards). Integration tests ran against a live 1.16.0 server, so the _exact_nanos change is confirmed end to end
• ruff lint + format clean; 78/78 cookbook snippets type-check
• Each new validation manually confirmed to raise with its intended message

The remaining caveat is unchanged and still flagged in the recipe and CLAUDE.md: status filtering of query results is unit-tested only, pending a Python ingestion path (#17) to attach statuses to real samples.