Add CacheRoute strategy: per-KDN index, topology-aware proxy selection, and demo flags

[zhy1658858023]

Motivation

• Provide an incremental, research-friendly CacheRoute scheduler strategy that chooses KDNs by text completeness and KV-ready coverage and selects proxies by topology + safe-load + knowledge-affinity without opaque weight parameters.
• Keep changes minimal and backward-compatible so experiments can run when optional topology/heartbeat data are absent.
• Enable easy demo/validation hooks so the strategy behavior is observable and reproducible during experiments.

Description

• Introduced a new strategy scheduler/strategy/cacheroute.py implementing lexicographic, non-weighted decision rules for KDN selection (text_full -> not_overloaded -> kv_cover_len -> load/tie-break) and a topology-aware proxy selection flow (best topology group -> load-safe filter -> affinity -> tie-break rotation), with environment-configurable thresholds and affinity decay/top-k retention.
• Extended the strategy interface in scheduler/strategy/base.py to accept an optional lightweight request_ctx (contains knowledge_list, kdn_knowledge_index, etc.) and updated round_robin to keep compatibility with the new signature.
• Built a scheduler-side per-KDN knowledge index in scheduler/knowledge/kdn_sync.py (method refresh_kdn_knowledge_index) and integrated it with the existing KDN refresh flow so strategies can compute per-KDN coverage without re-running retrieval/embedding.
• Plumbed the index into the request path: core/request.py now builds a compact request_ctx and scheduler/scheduler.py passes kdn_knowledge_index into _handle_client -> strategy select call; /debug/strategy exposes the last decision snapshot when available.
• Added optional static KDN→Proxy topology metadata support by sending meta.kdn_links during proxy registration; proxy side reads PROXY_KDN_LINKS_JSON (or demo --kdn-links-json) in proxy/proxy.py and test/demo_proxy.py to populate that field without changing wire schemas.
• Added demo convenience: test/demo_scheduler.py accepts --cacheroute (shortcut for --strategy cacheroute) and test/demo_proxy.py accepts --kdn-links-json for quick experiments.

Testing

• Ran Python syntax checks for modified modules: python3 -m py_compile scheduler/strategy/cacheroute.py proxy/proxy.py test/demo_proxy.py (succeeded).
• Executed focused strategy unit checks by loading the cacheroute module via file import (avoiding full package imports) and ran selection scenarios validating: topology-first proxy group selection, deterministic tie rotation, and affinity updates (succeeded).
• Attempted a full package import test but it failed due to an environment dependency (uvicorn missing) when importing top-level scheduler (this is an environment issue, not strategy logic); as a workaround we used direct module loading for strategy tests (documented and succeeded).
• No changes to public wire formats were introduced and the strategy gracefully degrades to prior behavior when optional topology or heartbeat fields are not provided.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 31c2292c86

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Isolate KDN snapshot errors during index refresh

refresh_kdn_knowledge_index now performs a blocking snapshot call for every alive KDN, but a single fetch_kdn_snapshot failure aborts the whole function and propagates out of kdn_refresh_once. In practice, one stale/unreachable KDN in the alive set causes all refresh cycles to fail, so knowledge_table and kdn_knowledge_index stop updating for healthy nodes as well. This should degrade gracefully per KDN (skip/log failed node) instead of failing the full refresh pass.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Validate topology tier values before int conversion

The strategy casts bandwidth_tier/latency_tier directly with int(...) from proxy-provided meta.kdn_links. If one proxy advertises a non-numeric value (e.g., from misconfigured PROXY_KDN_LINKS_JSON), this raises ValueError inside routing, which bubbles out of strategy selection and leaves the request without a selected route (ultimately returning a routing failure). Tier parsing should be defensive and fall back to defaults for invalid values.

Useful? React with 👍 / 👎.