From 4b3d16a124aeaa08df75f793357c5de00d1ed38a Mon Sep 17 00:00:00 2001 From: Fona <62028332+FonaTech@users.noreply.github.com> Date: Sat, 14 Nov 2026 02:59:28 +0800 Subject: [PATCH] docs(readme): add architecture hero image and full docs TOC MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Place the Chronos forward-stack diagram (docs/assets/arch/chronos_forward_stack.png) at the top of README.md and README_zh.md, right under the badge block. - Add a 'Documentation' / '文档索引' section with every chapter under docs/ (OVERVIEW, KERNEL_ARCHITECTURE, SYMBOLS, THEORY, ATTENTION, MOE_ROUTING, CLUSTER_LOCALITY, LOOKAHEAD, LOOP_DEPTH, LAZY_EXPERTS, RESIDENCY, SPEC_DECODE, LONG_CONTEXT, REPRODUCIBILITY, vllm_integration, READING_GUIDE_ZH), grouped by area and with a one-line 'what it answers' column. The section points readers to docs/README.md as the full index. The image file was already shipped with 0.3.3 under docs/assets/arch/, so this is a docs-only addition; no code paths, wheel contents or version string change. Co-Authored-By: Claude Opus 5.5 --- README.md | 29 +++++++++++++++++++++++++++++ README_zh.md | 29 +++++++++++++++++++++++++++++ 2 files changed, 58 insertions(+) diff --git a/README.md b/README.md index 82fc1f0..350b440 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,35 @@ [中文文档](README_zh.md) +![Chronos forward stack: embedding, prelude, recurrent region and coda, with separate input and output lanes](docs/assets/arch/chronos_forward_stack.png) + +*Chronos forward stack. The embedding lookup feeds a prelude of $P$ blocks, a recurrent region of $G$ blocks run $R$ times with conditioning, and a coda of $C$ blocks, then a tied LM head. Prefetch, lookahead and expert residency hang off the recurrent region.* + +--- + +## Documentation + +**Start here:** [docs/README.md](docs/README.md) is the full index with reading routes and figures. + +| Area | Chapter | What it answers | +|---|---|---| +| Entry point | [OVERVIEW.md](docs/OVERVIEW.md) | How do computation, routing and residency connect? | +| Entry point | [KERNEL_ARCHITECTURE.md](docs/KERNEL_ARCHITECTURE.md) | What is the implementation-exact end-to-end graph? | +| Reference | [SYMBOLS.md](docs/SYMBOLS.md) | Axes, units and configuration fields. | +| Reference | [THEORY.md](docs/THEORY.md) | Stability, information and resource derivations with assumptions. | +| Model | [ATTENTION.md](docs/ATTENTION.md) | MLA/SWA projection, caching, reconstruction and masking. | +| Model | [MOE_ROUTING.md](docs/MOE_ROUTING.md) | Dispatch, shared averaging, fallback and regularizers. | +| Model | [CLUSTER_LOCALITY.md](docs/CLUSTER_LOCALITY.md) | Fixed-partition mutual-information objective. | +| Model | [LOOKAHEAD.md](docs/LOOKAHEAD.md) | Future-token expert-distribution prediction and training. | +| Model | [LOOP_DEPTH.md](docs/LOOP_DEPTH.md) | Matched-step and matched-time recurrent-depth experiments. | +| Runtime | [LAZY_EXPERTS.md](docs/LAZY_EXPERTS.md) | Expert-page loading, admission and materialization. | +| Runtime | [RESIDENCY.md](docs/RESIDENCY.md) | Eviction policies and residency counters. | +| Runtime | [SPEC_DECODE.md](docs/SPEC_DECODE.md) | Draft/verify sampling correctness and cost. | +| Runtime | [LONG_CONTEXT.md](docs/LONG_CONTEXT.md) | Chunked loss, blockwise attention and recomputation. | +| Evidence | [REPRODUCIBILITY.md](docs/REPRODUCIBILITY.md) | Evidence and controls required for a claim. | +| Serving | [vllm_integration.md](docs/vllm_integration.md) | Serving interfaces and integration scaffold. | +| 中文 | [READING_GUIDE_ZH.md](docs/READING_GUIDE_ZH.md) | 中文阅读路线、核心机制与符号导引。 | + --- ## Why reactive MoE offload breaks down diff --git a/README_zh.md b/README_zh.md index dcb5f85..ea3d3a3 100644 --- a/README_zh.md +++ b/README_zh.md @@ -8,6 +8,35 @@ [English](README.md) +![Chronos 前向栈：嵌入、prelude、recurrent 区（迭代执行）、coda，与独立的输入 / 输出通道](docs/assets/arch/chronos_forward_stack.png) + +*Chronos 前向栈。Embedding 查表之后是 $P$ 层 prelude、$G$ 层 recurrent 区（以条件化方式迭代 $R$ 次）、$C$ 层 coda，最后接 tied LM head。Prefetch、lookahead 与专家驻留均挂接在 recurrent 区。* + +--- + +## 文档索引 + +**入口：** [docs/README.md](docs/README.md) 是带阅读路线与配图的完整索引。 + +| 分区 | 章节 | 回答的问题 | +|---|---|---| +| 入口 | [OVERVIEW.md](docs/OVERVIEW.md) | 计算、路由与驻留如何相互衔接？ | +| 入口 | [KERNEL_ARCHITECTURE.md](docs/KERNEL_ARCHITECTURE.md) | 端到端执行图的实现级描述。 | +| 参考 | [SYMBOLS.md](docs/SYMBOLS.md) | 轴、单位与配置字段。 | +| 参考 | [THEORY.md](docs/THEORY.md) | 稳定性、信息与资源推导（含假设）。 | +| 模型 | [ATTENTION.md](docs/ATTENTION.md) | MLA/SWA 的投影、缓存、重构与掩码。 | +| 模型 | [MOE_ROUTING.md](docs/MOE_ROUTING.md) | 路由分发、共享平均、回退与正则项。 | +| 模型 | [CLUSTER_LOCALITY.md](docs/CLUSTER_LOCALITY.md) | 固定划分下的互信息目标。 | +| 模型 | [LOOKAHEAD.md](docs/LOOKAHEAD.md) | 未来 token 的专家分布预测与训练。 | +| 模型 | [LOOP_DEPTH.md](docs/LOOP_DEPTH.md) | 匹配步数与匹配时间的递归深度实验。 | +| 运行时 | [LAZY_EXPERTS.md](docs/LAZY_EXPERTS.md) | 专家页的加载、准入与物化。 | +| 运行时 | [RESIDENCY.md](docs/RESIDENCY.md) | 驱逐策略与驻留计数器。 | +| 运行时 | [SPEC_DECODE.md](docs/SPEC_DECODE.md) | 草稿/校验采样的正确性与代价。 | +| 运行时 | [LONG_CONTEXT.md](docs/LONG_CONTEXT.md) | 分块损失、分块注意力与重计算。 | +| 证据 | [REPRODUCIBILITY.md](docs/REPRODUCIBILITY.md) | 性能/质量结论所需的证据与控制。 | +| 服务 | [vllm_integration.md](docs/vllm_integration.md) | 已实现的服务接口与集成骨架。 | +| 中文 | [READING_GUIDE_ZH.md](docs/READING_GUIDE_ZH.md) | 中文阅读路线、核心机制与符号导引。 | + --- ## 现有方案的根本性缺陷