Adds lmcache/tools/cache_simulator/ with four modules:

- lru_cache.py      — LRUCacheFast (O(1)) and LRUCache (O(log n) with
                      position tracking) backed by OrderedDict / SortedList
- simulator.py      — load_lookup_events(), simulate(), print_statistics(),
                      plot_statistics(), and a CLI
- plot_hit_rate.py  — capacity sweep over log-spaced GiB range + matplotlib
                      plot
- README.md         — user and developer documentation

The primary metric is *token* cache hit rate:

    hit_tokens / total_tokens

where hit_tokens = hit_prefix_chunks × chunk_size and tail tokens
(seq_len mod chunk_size) are always counted as misses, matching the
LMCache server's semantics. Cache capacity is expressed in bytes; the
CLI accepts GiB and auto-computes bytes-per-chunk from shapes/dtypes in
the first event.

Running simulator.py prints a full text report and saves a 7-panel
statistics PNG (per-request hit rate, hit prefix length, chunk reuse
count, rolling hit rate, input length, global span, cache position).

Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: crclq2018 <crclq2018@gmail.com>
Signed-off-by: rigginschen <rigginschen@tencent.com>

Integrates the cache simulator into the lmcache CLI so users can run:

  lmcache tool cache-simulator simulate -i <logs> --cache-capacity-gib 64
  lmcache tool cache-simulator sweep    -i <logs> --min-capacity-gib 1 --max-capacity-gib 512

`simulate` replays lookup-hash JSONL logs at a fixed cache capacity,
prints a text report, and saves a 7-panel statistics PNG.
`sweep` scans a log-spaced range of capacities and saves a hit-rate
vs capacity PNG.

The python -m lmcache.tools.cache_simulator.{simulator,plot_hit_rate}
entry points continue to work unchanged.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: crclq2018 <crclq2018@gmail.com>
Signed-off-by: kumaneko <crclq2018@gmail.com>

…cation

Adds four public functions that serve as the single source of truth for
CLI flag definitions and execution logic:

  simulator.py:       add_simulate_arguments(parser), run_simulate(args)
  plot_hit_rate.py:   add_sweep_arguments(parser),    run_sweep(args)

ToolCommand now calls these instead of duplicating the flags itself.
Adding or removing a flag in the simulator modules automatically takes
effect in both `python -m ...` and `lmcache tool cache-simulator ...`.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: crclq2018 <crclq2018@gmail.com>
Signed-off-by: kumaneko <crclq2018@gmail.com>

ToolCommand in __init__.py is now a thin dispatcher (~60 lines).
Cache-simulator wiring moves to tool/cache_simulator.py.

Adding a future tool requires only:
  1. Create tool/<new_tool>.py with a register() function
  2. Import it in __init__.py and call new_tool.register(inner)

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: crclq2018 <crclq2018@gmail.com>
Signed-off-by: kumaneko <crclq2018@gmail.com>

Adds a "CLI integration" subsection under "For Developers" that:
- shows the tool/ package layout alongside the simulator package
- explains that add_*_arguments/run_* are the single source of truth
- tells developers where to edit when adding a flag vs a new action

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: crclq2018 <crclq2018@gmail.com>
Signed-off-by: kumaneko <crclq2018@gmail.com>

The cache simulator tool (lmcache tool cache-simulator) uses
matplotlib for generating PNG charts. Declaring it in cli.txt
ensures it is always available when the lmcache CLI is installed,
avoiding ImportError on any lmcache invocation.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: crclq2018 <crclq2018@gmail.com>
Signed-off-by: kumaneko <crclq2018@gmail.com>

…serve dataset

Add gen_bench_dataset.py which converts LMCache lookup-hash JSONL logs
into a vllm bench serve custom dataset (JSONL with "prompt" and
"output_tokens" fields).  The conversion preserves prefix-sharing
structure: requests that shared a chunk hash in the original logs will
share the same token prefix in the synthetic prompts, so LMCache prefix
caching sees the same hit/miss pattern during replay.

Algorithm: build a stable safe vocabulary from the tokenizer (tokens
that round-trip through encode/decode cleanly), then deterministically
map each chunk hash to chunk_size token IDs via SHA-256 seeded RNG.

Also wire "gen-dataset" as a new sub-action of
`lmcache tool cache-simulator` and update the README with Step 4.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Signed-off-by: kumaneko <crclq2018@gmail.com>