From da2e02a8f2cdab0d3f21fbf1f4f5baca6ddc2660 Mon Sep 17 00:00:00 2001 From: RickZ <121943721+rickisba@users.noreply.github.com> Date: Wed, 29 Jul 2026 15:15:14 +0800 Subject: [PATCH 1/2] docs(core): document runtime compatibility boundary --- core/README.md | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/core/README.md b/core/README.md index c12e739..9ea184d 100644 --- a/core/README.md +++ b/core/README.md @@ -8,10 +8,12 @@ It provides the common runtime interface that connects CacheRoute components tog ```text core/ +├── __init__.py # Stable public exports for shared runtime helpers ├── config.py # Default configuration for all CacheRoute components ├── request.py # Internal Request / Prompt / Service / Task data structures ├── fwd.py # HTTP forwarding utilities ├── model_calculation.py # Model-side cost and size estimation helpers +├── runtime_compat.py # Stable compatibility import surface for Runtime Profiles └── README.md ``` @@ -21,7 +23,14 @@ Main responsibilities: - define model, embedding, and knowledge retrieval configuration; - define the internal request object passed from Scheduler to Proxy; - normalize OpenAI-compatible requests into CacheRoute request metadata; -- provide common forwarding utilities for component communication. +- provide common forwarding utilities for component communication; +- expose stable Runtime Profile normalization imports shared by Legacy, v1, and test/mock paths. + +## Runtime compatibility boundary + +`core/runtime_compat.py` is the compatibility-facing import path used by existing CacheRoute modules. The dependency-light implementation lives in `cacheroute_compat/runtime.py`, which keeps Runtime Profile normalization available without importing the full application graph. + +Persisted and wire-level objects must use a resolved Runtime Profile (`legacy`, `v1`, or `test/mock`). The `auto` value is limited to startup resolution and must not become an operation-time fallback. The storage-neutral KDN representation of these profiles is documented in the [KDN domain vocabulary](../kdn_server/domain/README.md); serving-stack migration and startup details remain in [runtime compatibility documentation](../docs/runtime_compatibility_v1.md). ## Configuration From 1564b5575230ff8f27b90973dba10f5a69ea150b Mon Sep 17 00:00:00 2001 From: RickZ <121943721+rickisba@users.noreply.github.com> Date: Wed, 29 Jul 2026 15:16:35 +0800 Subject: [PATCH 2/2] docs(kdn): refresh directory map after v0.1.10 contracts --- kdn_server/README.md | 48 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 37 insertions(+), 11 deletions(-) diff --git a/kdn_server/README.md b/kdn_server/README.md index a755143..e7ca044 100644 --- a/kdn_server/README.md +++ b/kdn_server/README.md @@ -25,23 +25,49 @@ This allows the Scheduler and Proxy to make knowledge-aware routing and compute- kdn_server/ ├── KV_database/ │ └── / -│ ├── blocks/ # dumped KVCache blocks -│ ├── manifest.jsonl # KVCache block metadata -│ └── run_meta.json # build-time metadata +│ ├── blocks/ # dumped KVCache blocks +│ ├── manifest.jsonl # KVCache block metadata +│ └── run_meta.json # build-time metadata ├── text_database/ -│ ├── blocks/ # registered text blocks -│ ├── tmp/ # temporary files -│ └── index.sqlite3 # text knowledge index +│ ├── blocks/ # registered text blocks +│ ├── tmp/ # temporary files +│ └── index.sqlite3 # text knowledge index +├── contracts/ +│ ├── __init__.py # stable public service-contract exports +│ ├── common.py # versioned envelopes and shared wire types +│ ├── errors.py # structured outcomes and error details +│ ├── knowledge.py # Knowledge Service request/response contracts +│ ├── cache_service.py # Cache Service Facade contracts +│ └── README.md # contract reference +├── domain/ +│ ├── __init__.py # stable domain-model exports +│ ├── models.py # artifacts, observations, endpoints, tasks, queues +│ └── README.md # domain vocabulary and state semantics +├── gateway/ +│ ├── __init__.py # stable Gateway exports +│ ├── profiles.py # transport bindings and compatibility profiles +│ ├── capabilities.py # immutable capability snapshots +│ ├── protocol.py # LMCacheGateway Protocol +│ ├── base.py # shared negotiation and capability gates +│ ├── factory.py # explicit adapter construction boundary +│ ├── mock.py # deterministic CPU-only Mock Gateway +│ ├── legacy.py # explicit read-only Legacy adapter +│ └── README.md # Gateway architecture and extension guide +├── util/ +│ └── batch_register_kdn.py # batch knowledge registration helper ├── __init__.py -├── kdn_api.py # KDN HTTP service -├── kdn_register_cli.py # interactive KDN management CLI -├── kv_builder.py # KVCache construction -├── kv_injector.py # KVCache injection into Redis / LMCache backend -├── text_db.py # text knowledge database +├── kdn_api.py # KDN HTTP service +├── kdn_register_cli.py # interactive KDN management CLI +├── kv_builder.py # KVCache construction +├── kv_injector.py # KVCache injection into Redis / LMCache backend +├── text_db.py # text knowledge database └── README.md ``` + Each knowledge block is identified by a content-based hash ID. Text knowledge and KVCache blocks are stored separately, while the KDN metadata links them together. +The operational HTTP, CLI, database, build, and injection paths remain documented in this file. The new storage-neutral control-plane packages are documented progressively in [domain](domain/README.md), [contracts](contracts/README.md), [gateway](gateway/README.md), and the [CPU-only KDN workflow tests](../test/kdn/README.md). + --- ## API Routes