Add read-only observability snapshots

[shipiyouniao]

Summary

Adds a small read-only observability surface for kvcached runtime integrations and KV cache pools.

This PR intentionally keeps the surface policy-free: it exposes structured snapshots that external monitoring systems or control-plane layers can consume without depending on private patch details.

What is included

• kvcached.observability dataclasses for:
  • runtime integration state
  • KV cache pool state
  • capability discovery
• KVCacheManager.observability_snapshot() and observability_snapshot_dict()
• vLLM and SGLang integration runtime snapshot helpers
• unit tests using a fake allocator, with no CUDA/GPU dependency

Notes

• This is read-only and does not change allocation, admission, GC, or scheduling behavior.
• Related to Discussion: stable extension points for production kvcached integrations #375, but this is only a small observability/accounting surface and does not close that broader discussion.

Validation

Ran on a Linux host without GPU workload:

pytest tests/test_observability.py -q
# 3 passed

GOPROXY=https://goproxy.cn,direct pre-commit run --all-files
# passed

pre-commit run --all-files --hook-stage manual mypy-3.9
pre-commit run --all-files --hook-stage manual mypy-3.10
pre-commit run --all-files --hook-stage manual mypy-3.11
pre-commit run --all-files --hook-stage manual mypy-3.12
pre-commit run --all-files --hook-stage manual mypy-3.13
# all passed

[Copilot]

Pull request overview

This PR introduces a small, read-only observability surface for kvcached integrations and KV cache pools, exposing structured “snapshot” dataclasses and helper methods so external monitoring/control-plane systems can introspect state without relying on private patch details.

Changes:

• Added kvcached.observability module with RuntimeSnapshot / KVCachePoolSnapshot, plus capability discovery and snapshot builders.
• Added KVCacheManager.observability_snapshot() / observability_snapshot_dict() for pool-level snapshot export.
• Added vLLM/SGLang integration runtime snapshot helpers and a new unit test covering JSON-serializability and snapshot field values.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_observability.py	Adds unit tests for capability discovery and snapshot serialization/field correctness.
kvcached/observability.py	Introduces stable schema/versioned snapshot dataclasses and snapshot builder helpers.
kvcached/kv_cache_manager.py	Exposes synchronized pool snapshot helper methods on KVCacheManager.
kvcached/integration/vllm/interfaces.py	Adds vLLM runtime integration snapshot + dict helper.
kvcached/integration/sglang/interfaces.py	Adds SGLang runtime integration snapshot + dict helper.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.