sched-sim 0.2.0__tar.gz

sched_sim-0.2.0/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Prajwal Pujari
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

sched_sim-0.2.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: sched-sim
+Version: 0.2.0
+Summary: High-fidelity discrete-event simulator for LLM serving schedulers (FCFS, SJF, Chunked Prefill, Radix Prefix Caching, SLO-Aware, Disaggregated).
+Keywords: llm,inference,serving,scheduler,discrete-event-simulation,chunked-prefill,prefix-caching,radix-tree,paged-attention,queueing-theory,vllm,sglang,sarathi,distserve
+Author: Prajwal Pujari
+Author-email: Prajwal Pujari <prajwalpujari16@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Benchmark
+Classifier: Topic :: System :: Hardware
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/Prajwal7-2002/sched-sim
+Project-URL: Documentation, https://prajwal7-2002.github.io/sched-sim/
+Project-URL: Repository, https://github.com/Prajwal7-2002/sched-sim
+Project-URL: Issues, https://github.com/Prajwal7-2002/sched-sim/issues
+Description-Content-Type: text/markdown
+
+# sched-sim ⏱️
+
+[![CI](https://github.com/Prajwal7-2002/sched-sim/actions/workflows/ci.yml/badge.svg)](https://github.com/Prajwal7-2002/sched-sim/actions)
+[![Docs](https://github.com/Prajwal7-2002/sched-sim/actions/workflows/docs.yml/badge.svg)](https://prajwal7-2002.github.io/sched-sim/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![Hardware](https://img.shields.io/badge/CPU-100%25_Deterministic-green.svg)](#)
+[![Calibrated](https://img.shields.io/badge/Calibrated_With-servebench_%26_mini--infer-teal.svg)](#)
+
+A high-fidelity, CPU-first **discrete-event simulator (DES) for LLM serving schedulers**.
+
+In modern inference clusters (vLLM, TGI, TensorRT-LLM, SGLang, DistServe), **the scheduling policy is the single largest determinant of cluster throughput, latency, and hardware cost**. While continuous batching and Paged KV-caching provide the mechanism for dynamic execution, the scheduler determines:
+1. Which requests enter the next forward iteration.
+2. How large prompt prefills are chunked to prevent decode starvation.
+3. What happens when the physical KV-cache runs out of memory (swapping to CPU DRAM vs eviction and recomputation).
+4. When to disaggregate prefill and decode phases onto specialized GPU worker pools (Splitwise / DistServe architecture).
+
+Testing these policies on real GPU clusters (e.g. 8x H100 nodes) is **slow, noisy, and expensive ($20–$50/hr)**. `sched-sim` simulates hours of multi-GPU serving traffic in **seconds on any standard CPU**, using validated analytical performance models calibrated against empirical silicon measurements from **[servebench](https://github.com/Prajwal7-2002/servebench)** and **[mini-infer](https://github.com/Prajwal7-2002/mini-infer)**.
+
+---
+
+## ⚡ Core Architecture
+
+```
+                          ┌────────────────────────────────────────────────────────┐
+                          │                   Arrival Process                      │
+                          │   (Poisson, Bursty Gamma, LMSYS / ShareGPT Traces)    │
+                          └───────────────────────────┬────────────────────────────┘
+                                                      │ Request arrives (prompt_len, output_len)
+                                                      ▼
+                                       ┌─────────────────────────────┐
+                                       │       Waiting Queue         │
+                                       │  (FCFS, SJF, Priority, SLO) │
+                                       └──────────────┬──────────────┘
+                                                      │ Iteration Scheduler
+                                                      ▼
+                       ┌──────────────────────────────────────────────────────────────┐
+                       │               Continuous Batching Step (Iteration)           │
+                       │  ┌────────────────────────────┐ ┌──────────────────────────┐ │
+                       │  │   Prefill Tokens (Chunked) │ │ Decode Tokens (1/req)    │ │
+                       │  └────────────────────────────┘ └──────────────────────────┘ │
+                       │       ▲                                      ▲               │
+                       │       │ Paged KV Allocator                   │ Memory Check  │
+                       │       │                                      │               │
+                       │       ▼                                      ▼               │
+                       │  ┌──────────────────────────┐   ┌──────────────────────────┐ │
+                       │  │   Paged KV-Cache Pool    │   │   Preemption Subsystem   │ │
+                       │  │ (Physical 16-tok Blocks) │   │ (Recompute vs CPU Swap)  │ │
+                       │  └──────────────────────────┘   └──────────────────────────┘ │
+                       └──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ⏱️ Quickstart in 30 Seconds
+
+### Install
+```bash
+# Direct from source with uv (fastest)
+git clone https://github.com/Prajwal7-2002/sched-sim.git
+cd sched-sim
+uv sync
+
+# Or with standard pip
+pip install -e .
+```
+
+### 1. Run a Simulation Scenario
+Simulate **Chunked Prefill** serving a long-context RAG workload on an **NVIDIA A100 SXM4 (80GB)** cluster running Llama-3-8B:
+```bash
+sched-sim run --scheduler chunked --workload rag --hardware a100 --duration 10
+```
+
+> **Runs 100% on your CPU**: You do **not** need an A100 or any GPU to run `sched-sim`. It simulates hours of multi-GPU serving traffic in seconds on any standard CPU. The `--hardware` flag tells the discrete-event engine which cluster architecture to mathematically simulate (`a100`, `h100`, `t4`, `rtx3050`, or a custom JSON profile).
+
+### 2. Compare Schedulers Side-by-Side (Identical Trace)
+Benchmark all 5 scheduling policies on the exact same Poisson arrival trace:
+```bash
+sched-sim compare --schedulers fcfs,sjf,chunked,slo,disaggregated --workload rag --hardware a100
+```
+
+### 3. Replay Real-World Conversation Traces
+Replay Chatbot Arena conversation traces through the simulator:
+```bash
+sched-sim trace ./traces/lmsys_sample.json --scheduler chunked
+```
+
+### 4. Sweep Load to Discover Saturation Knees
+Discover the exact request rate where each scheduler hits its Goodput cliff:
+```bash
+sched-sim sweep --schedulers fcfs,chunked,slo,disaggregated --workload rag --min-rate 2 --max-rate 18 --step 4
+```
+
+### 5. Check Silicon Hardware Presets
+Inspect calibrated hardware profiles:
+```bash
+sched-sim info
+```
+
+---
+
+## 🔬 The 6 Core Schedulers
+
+| Scheduler | Architecture & Policy | Key Trade-Off |
+| :--- | :--- | :--- |
+| **`Cache-Aware`** | **Radix-Tree prefix caching** (SGLang / vLLM APC). Shares physical 16-token KV blocks with LRU eviction and prefix-affinity prioritization. | **Near-zero TTFT** for RAG, multi-turn chat, and shared system prompts. |
+| **`Chunked`** | Token budgeting (Sarathi-Serve / vLLM). Slices prompt prefills into 512-token chunks. | Eliminates TPOT latency spikes and ensures steady iteration times. |
+| **`SLO-Aware`** | Dynamic deadline scheduling (EDF) with selective dropping of unrecoverable requests. | Maximizes **Goodput** (% of requests meeting both TTFT and TPOT SLOs). |
+| **`Disaggregated`**| Splitwise / DistServe architecture: separates compute-bound Prefill workers from memory-bound Decode workers. | Zero decode interference; models KV-cache interconnect transfer delay. |
+| **`SJF`** | Shortest-Job-First (shortest prompt first). | Minimizes average waiting time and mean TTFT, but starves heavy RAG prompts. |
+| **`FCFS`** | First-Come First-Served continuous batching with atomic prefills. | Simple, but large prompts cause Head-of-Line blocking and decode starvation. |
+
+---
+
+## 🎨 Interactive Perfetto / Chromium Timeline Visualization
+
+Export native Chromium / Catapult Trace Event JSON files and inspect discrete forward-pass iteration slices and per-request lifecycles in **[ui.perfetto.dev](https://ui.perfetto.dev)**:
+
+```bash
+sched-sim run --scheduler cache_aware --workload rag --hardware a100 --trace-out trace.json
+```
+
+Drag and drop `trace.json` directly into **Perfetto** to visually analyze:
+- **Prefill vs. Decode vs. Mixed Slices**: Microsecond-accurate forward pass durations on the GPU accelerator.
+- **Request Streams**: Exact arrival, TTFT first-token timestamps, and completion times.
+- **Counter Tracks**: Real-time GPU KV-cache memory utilization (%) and concurrent batch stream counts.
+
+---
+
+## 🛠️ Hardware Calibration (Analytical Roofline Model)
+
+`sched-sim` avoids arbitrary delays. It computes exact step latencies from first-principles roofline mechanics calibrated with empirical silicon data:
+
+1. **Prefill Latency ($T_{\text{prefill}}$)**: Compute-bound matrix multiplication:
+   $$T_{\text{prefill}} = \max\left(\frac{2 \cdot P \cdot N}{\text{Effective TFLOPS}}, \frac{\text{Weights}}{\text{Bandwidth}}\right) + T_{\text{launch}}$$
+
+2. **Decode Latency ($T_{\text{decode}}$)**: Memory-bandwidth bound weight and KV-cache gather:
+   $$T_{\text{decode}} = \frac{P \cdot \text{dtype} + L_{\text{total}} \cdot \text{KV\_bytes\_per\_token}}{\text{DRAM Bandwidth (GB/s)}} + T_{\text{launch}}$$
+
+3. **Interconnect Transfer ($T_{\text{transfer}}$)**: Network serialization delay for PD Disaggregation:
+   $$T_{\text{transfer}} = \frac{L_{\text{prompt}} \cdot \text{KV\_bytes\_per\_token}}{\text{Network Bandwidth}} + T_{\text{net\_latency}}$$
+
+---
+
+## 🔬 Empirical Silicon Validation (AMD Ryzen 5 6600H + NVIDIA RTX 3050 6GB)
+
+`sched-sim` is validated against ground-truth benchmarks collected by **[servebench](https://github.com/Prajwal7-2002/servebench)** testing **Qwen 2.5 0.5B** on both C++/CUDA and Python runtimes on physical silicon:
+
+| Target Serving Engine | Model | Metric | Real Hardware (`servebench`) | `sched-sim` Predicted | Variance |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Ollama (C++/CUDA runtime)** | Qwen 2.5 0.5B | **TTFT** | 44.33 ms | 47.81 ms | **7.9%** |
+| | | **TPOT** | 4.96 ms | 5.33 ms | **7.5%** |
+| | | **E2E** | 627.50 ms | 666.73 ms | **6.3%** |
+| **mini-infer (PyTorch eager runtime)** | Qwen 2.5 0.5B | **TTFT** | 121.80 ms | 140.60 ms | **15.4%** |
+| | | **TPOT** | 103.24 ms | 106.67 ms | **3.3%** |
+| | | **E2E** | 3322.29 ms | 3447.26 ms | **3.8%** |
+
+Run the reproducible validation suite yourself:
+```bash
+uv run python benchmarks/validate_flagships.py
+```
+Full methodology and analysis available in [benchmarks/RESULTS.md](benchmarks/RESULTS.md).
+
+---
+
+## 📊 Telemetry & Reports
+
+Every run outputs comprehensive telemetry:
+* **Latency Percentiles**: TTFT (p50, p90, p99 ms), TPOT (p50, p90, p99 ms/tok), End-to-End latency.
+* **Goodput Ratio**: Exact percentage of requests meeting both TTFT and TPOT Service Level Objectives.
+* **Preemptions & Recomputations**: Total memory thrashing events and discarded tokens.
+* **Visual Gantt Timeline**: Live ASCII/Unicode GPU iteration breakdowns.
+* **Export**: JSON (`--output report.json`) and Markdown (`--output report.md`).
+
+---
+
+## 🧪 Testing
+
+Run the deterministic test suite:
+```bash
+uv run pytest
+```
+
+---
+
+## 📄 License
+
+Apache 2.0. See [LICENSE](LICENSE) for details.

sched_sim-0.2.0/README.md

@@ -0,0 +1,188 @@
+# sched-sim ⏱️
+
+[![CI](https://github.com/Prajwal7-2002/sched-sim/actions/workflows/ci.yml/badge.svg)](https://github.com/Prajwal7-2002/sched-sim/actions)
+[![Docs](https://github.com/Prajwal7-2002/sched-sim/actions/workflows/docs.yml/badge.svg)](https://prajwal7-2002.github.io/sched-sim/)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![Hardware](https://img.shields.io/badge/CPU-100%25_Deterministic-green.svg)](#)
+[![Calibrated](https://img.shields.io/badge/Calibrated_With-servebench_%26_mini--infer-teal.svg)](#)
+
+A high-fidelity, CPU-first **discrete-event simulator (DES) for LLM serving schedulers**.
+
+In modern inference clusters (vLLM, TGI, TensorRT-LLM, SGLang, DistServe), **the scheduling policy is the single largest determinant of cluster throughput, latency, and hardware cost**. While continuous batching and Paged KV-caching provide the mechanism for dynamic execution, the scheduler determines:
+1. Which requests enter the next forward iteration.
+2. How large prompt prefills are chunked to prevent decode starvation.
+3. What happens when the physical KV-cache runs out of memory (swapping to CPU DRAM vs eviction and recomputation).
+4. When to disaggregate prefill and decode phases onto specialized GPU worker pools (Splitwise / DistServe architecture).
+
+Testing these policies on real GPU clusters (e.g. 8x H100 nodes) is **slow, noisy, and expensive ($20–$50/hr)**. `sched-sim` simulates hours of multi-GPU serving traffic in **seconds on any standard CPU**, using validated analytical performance models calibrated against empirical silicon measurements from **[servebench](https://github.com/Prajwal7-2002/servebench)** and **[mini-infer](https://github.com/Prajwal7-2002/mini-infer)**.
+
+---
+
+## ⚡ Core Architecture
+
+```
+                          ┌────────────────────────────────────────────────────────┐
+                          │                   Arrival Process                      │
+                          │   (Poisson, Bursty Gamma, LMSYS / ShareGPT Traces)    │
+                          └───────────────────────────┬────────────────────────────┘
+                                                      │ Request arrives (prompt_len, output_len)
+                                                      ▼
+                                       ┌─────────────────────────────┐
+                                       │       Waiting Queue         │
+                                       │  (FCFS, SJF, Priority, SLO) │
+                                       └──────────────┬──────────────┘
+                                                      │ Iteration Scheduler
+                                                      ▼
+                       ┌──────────────────────────────────────────────────────────────┐
+                       │               Continuous Batching Step (Iteration)           │
+                       │  ┌────────────────────────────┐ ┌──────────────────────────┐ │
+                       │  │   Prefill Tokens (Chunked) │ │ Decode Tokens (1/req)    │ │
+                       │  └────────────────────────────┘ └──────────────────────────┘ │
+                       │       ▲                                      ▲               │
+                       │       │ Paged KV Allocator                   │ Memory Check  │
+                       │       │                                      │               │
+                       │       ▼                                      ▼               │
+                       │  ┌──────────────────────────┐   ┌──────────────────────────┐ │
+                       │  │   Paged KV-Cache Pool    │   │   Preemption Subsystem   │ │
+                       │  │ (Physical 16-tok Blocks) │   │ (Recompute vs CPU Swap)  │ │
+                       │  └──────────────────────────┘   └──────────────────────────┘ │
+                       └──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ⏱️ Quickstart in 30 Seconds
+
+### Install
+```bash
+# Direct from source with uv (fastest)
+git clone https://github.com/Prajwal7-2002/sched-sim.git
+cd sched-sim
+uv sync
+
+# Or with standard pip
+pip install -e .
+```
+
+### 1. Run a Simulation Scenario
+Simulate **Chunked Prefill** serving a long-context RAG workload on an **NVIDIA A100 SXM4 (80GB)** cluster running Llama-3-8B:
+```bash
+sched-sim run --scheduler chunked --workload rag --hardware a100 --duration 10
+```
+
+> **Runs 100% on your CPU**: You do **not** need an A100 or any GPU to run `sched-sim`. It simulates hours of multi-GPU serving traffic in seconds on any standard CPU. The `--hardware` flag tells the discrete-event engine which cluster architecture to mathematically simulate (`a100`, `h100`, `t4`, `rtx3050`, or a custom JSON profile).
+
+### 2. Compare Schedulers Side-by-Side (Identical Trace)
+Benchmark all 5 scheduling policies on the exact same Poisson arrival trace:
+```bash
+sched-sim compare --schedulers fcfs,sjf,chunked,slo,disaggregated --workload rag --hardware a100
+```
+
+### 3. Replay Real-World Conversation Traces
+Replay Chatbot Arena conversation traces through the simulator:
+```bash
+sched-sim trace ./traces/lmsys_sample.json --scheduler chunked
+```
+
+### 4. Sweep Load to Discover Saturation Knees
+Discover the exact request rate where each scheduler hits its Goodput cliff:
+```bash
+sched-sim sweep --schedulers fcfs,chunked,slo,disaggregated --workload rag --min-rate 2 --max-rate 18 --step 4
+```
+
+### 5. Check Silicon Hardware Presets
+Inspect calibrated hardware profiles:
+```bash
+sched-sim info
+```
+
+---
+
+## 🔬 The 6 Core Schedulers
+
+| Scheduler | Architecture & Policy | Key Trade-Off |
+| :--- | :--- | :--- |
+| **`Cache-Aware`** | **Radix-Tree prefix caching** (SGLang / vLLM APC). Shares physical 16-token KV blocks with LRU eviction and prefix-affinity prioritization. | **Near-zero TTFT** for RAG, multi-turn chat, and shared system prompts. |
+| **`Chunked`** | Token budgeting (Sarathi-Serve / vLLM). Slices prompt prefills into 512-token chunks. | Eliminates TPOT latency spikes and ensures steady iteration times. |
+| **`SLO-Aware`** | Dynamic deadline scheduling (EDF) with selective dropping of unrecoverable requests. | Maximizes **Goodput** (% of requests meeting both TTFT and TPOT SLOs). |
+| **`Disaggregated`**| Splitwise / DistServe architecture: separates compute-bound Prefill workers from memory-bound Decode workers. | Zero decode interference; models KV-cache interconnect transfer delay. |
+| **`SJF`** | Shortest-Job-First (shortest prompt first). | Minimizes average waiting time and mean TTFT, but starves heavy RAG prompts. |
+| **`FCFS`** | First-Come First-Served continuous batching with atomic prefills. | Simple, but large prompts cause Head-of-Line blocking and decode starvation. |
+
+---
+
+## 🎨 Interactive Perfetto / Chromium Timeline Visualization
+
+Export native Chromium / Catapult Trace Event JSON files and inspect discrete forward-pass iteration slices and per-request lifecycles in **[ui.perfetto.dev](https://ui.perfetto.dev)**:
+
+```bash
+sched-sim run --scheduler cache_aware --workload rag --hardware a100 --trace-out trace.json
+```
+
+Drag and drop `trace.json` directly into **Perfetto** to visually analyze:
+- **Prefill vs. Decode vs. Mixed Slices**: Microsecond-accurate forward pass durations on the GPU accelerator.
+- **Request Streams**: Exact arrival, TTFT first-token timestamps, and completion times.
+- **Counter Tracks**: Real-time GPU KV-cache memory utilization (%) and concurrent batch stream counts.
+
+---
+
+## 🛠️ Hardware Calibration (Analytical Roofline Model)
+
+`sched-sim` avoids arbitrary delays. It computes exact step latencies from first-principles roofline mechanics calibrated with empirical silicon data:
+
+1. **Prefill Latency ($T_{\text{prefill}}$)**: Compute-bound matrix multiplication:
+   $$T_{\text{prefill}} = \max\left(\frac{2 \cdot P \cdot N}{\text{Effective TFLOPS}}, \frac{\text{Weights}}{\text{Bandwidth}}\right) + T_{\text{launch}}$$
+
+2. **Decode Latency ($T_{\text{decode}}$)**: Memory-bandwidth bound weight and KV-cache gather:
+   $$T_{\text{decode}} = \frac{P \cdot \text{dtype} + L_{\text{total}} \cdot \text{KV\_bytes\_per\_token}}{\text{DRAM Bandwidth (GB/s)}} + T_{\text{launch}}$$
+
+3. **Interconnect Transfer ($T_{\text{transfer}}$)**: Network serialization delay for PD Disaggregation:
+   $$T_{\text{transfer}} = \frac{L_{\text{prompt}} \cdot \text{KV\_bytes\_per\_token}}{\text{Network Bandwidth}} + T_{\text{net\_latency}}$$
+
+---
+
+## 🔬 Empirical Silicon Validation (AMD Ryzen 5 6600H + NVIDIA RTX 3050 6GB)
+
+`sched-sim` is validated against ground-truth benchmarks collected by **[servebench](https://github.com/Prajwal7-2002/servebench)** testing **Qwen 2.5 0.5B** on both C++/CUDA and Python runtimes on physical silicon:
+
+| Target Serving Engine | Model | Metric | Real Hardware (`servebench`) | `sched-sim` Predicted | Variance |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Ollama (C++/CUDA runtime)** | Qwen 2.5 0.5B | **TTFT** | 44.33 ms | 47.81 ms | **7.9%** |
+| | | **TPOT** | 4.96 ms | 5.33 ms | **7.5%** |
+| | | **E2E** | 627.50 ms | 666.73 ms | **6.3%** |
+| **mini-infer (PyTorch eager runtime)** | Qwen 2.5 0.5B | **TTFT** | 121.80 ms | 140.60 ms | **15.4%** |
+| | | **TPOT** | 103.24 ms | 106.67 ms | **3.3%** |
+| | | **E2E** | 3322.29 ms | 3447.26 ms | **3.8%** |
+
+Run the reproducible validation suite yourself:
+```bash
+uv run python benchmarks/validate_flagships.py
+```
+Full methodology and analysis available in [benchmarks/RESULTS.md](benchmarks/RESULTS.md).
+
+---
+
+## 📊 Telemetry & Reports
+
+Every run outputs comprehensive telemetry:
+* **Latency Percentiles**: TTFT (p50, p90, p99 ms), TPOT (p50, p90, p99 ms/tok), End-to-End latency.
+* **Goodput Ratio**: Exact percentage of requests meeting both TTFT and TPOT Service Level Objectives.
+* **Preemptions & Recomputations**: Total memory thrashing events and discarded tokens.
+* **Visual Gantt Timeline**: Live ASCII/Unicode GPU iteration breakdowns.
+* **Export**: JSON (`--output report.json`) and Markdown (`--output report.md`).
+
+---
+
+## 🧪 Testing
+
+Run the deterministic test suite:
+```bash
+uv run pytest
+```
+
+---
+
+## 📄 License
+
+Apache 2.0. See [LICENSE](LICENSE) for details.

sched_sim-0.2.0/pyproject.toml

@@ -0,0 +1,69 @@
+[build-system]
+requires = ["uv_build>=0.12,<0.13"]
+build-backend = "uv_build"
+
+[project]
+name = "sched-sim"
+version = "0.2.0"
+description = "High-fidelity discrete-event simulator for LLM serving schedulers (FCFS, SJF, Chunked Prefill, Radix Prefix Caching, SLO-Aware, Disaggregated)."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+keywords = [
+    "llm",
+    "inference",
+    "serving",
+    "scheduler",
+    "discrete-event-simulation",
+    "chunked-prefill",
+    "prefix-caching",
+    "radix-tree",
+    "paged-attention",
+    "queueing-theory",
+    "vllm",
+    "sglang",
+    "sarathi",
+    "distserve",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: System :: Benchmark",
+    "Topic :: System :: Hardware",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13",
+    "pydantic>=2.6",
+    "pyyaml>=6.0",
+]
+
+[[project.authors]]
+name = "Prajwal Pujari"
+email = "prajwalpujari16@gmail.com"
+
+[project.scripts]
+sched-sim = "sched_sim.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/Prajwal7-2002/sched-sim"
+Documentation = "https://prajwal7-2002.github.io/sched-sim/"
+Repository = "https://github.com/Prajwal7-2002/sched-sim"
+Issues = "https://github.com/Prajwal7-2002/sched-sim/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5",
+    "ruff>=0.5",
+    "mkdocs-material>=9.5",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]