Skip to main content

Phantom: deterministic testing for LLM-serving KV caches

Phantom finds cross-request data leaks and KV-cache corruption in LLM inference engines, exactly, on a laptop CPU, with no GPU and no model weights. It has been tested on vLLM and LMCache.

Phantom is a model with no weights. To the serving engine it looks like a real LLM: it is scheduled, batched, preempted, prefix-cached and offloaded. But instead of K/V vectors it writes a provenance tag (writer, position, prefix chain hash) into every KV slot, and checks every slot it reads. Two slots are interchangeable exactly when their chain hashes match, which is the rule prefix caching is allowed to exploit, so correct sharing never raises an alarm. One seed replays a whole run event for event, and failures shrink automatically to a handful of events.

Install and try

pip install phantom-kv

# A correct engine: expect "no violations found"
phantomkv fuzz --seeds 1000

# A planted bug (free blocks on abort while KV writes are in flight): caught
phantomkv fuzz --seeds 1000 --plant abort-free-race

# Shrink a failing run to a minimal reproduction (53 events -> 6)
phantomkv shrink --seed 0 --plant abort-free-race

The simulator needs nothing but Python 3.10+. Running Phantom inside real vLLM and LMCache uses the scripts in the repository.

Results

  • Real bugs: 2 in LMCache, found independently (a fast server restart is never noticed by vLLM; aborted requests leak read locks for 300 s). Both were already reported upstream; Phantom's A/B tests show both open fixes work.
  • Planted bugs: caught in every class tried, in vLLM's block pool, between two vLLM engines, and in LMCache's own code.
  • False alarms: 0 on unmodified vLLM and LMCache; every seed replays identically.
  • Unplanted code: no bugs found in vLLM's two CPU offloading systems.

MIT licensed.

Metadata

Release files for phantom-kv 0.7.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for phantom-kv 0.7.0
File Size Uploaded Provenance Actions
phantom_kv-0.7.0.tar.gz 66.5 kB With provenance Details for phantom_kv-0.7.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for phantom-kv 0.7.0
File Interpreter ABI Platform Actions
phantom_kv-0.7.0-py3-none-any.whl Python 3 none any Details for phantom_kv-0.7.0-py3-none-any.whl

Total release size: 123.7 kB

Release files / phantom_kv-0.7.0.tar.gz

Download URL phantom_kv-0.7.0.tar.gz
Size 66.5 kB
Tags Source
SHA-256 checksum
How to use checksums
455d168ab9c75da4dfa485fdfdf542fb31f25d1fd76c8c1fc0dec732ab9a654a
BLAKE2b-256 checksum
How to use checksums
3d5484689e42300f27f1ad074f2fba3bdd9f03cc0ab354c02c4a1910b49beb0b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / phantom_kv-0.7.0-py3-none-any.whl

Download URL phantom_kv-0.7.0-py3-none-any.whl
Size 57.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8008e5ecfe8df26f68c8d623fe739e92832632cde58acd24f8f15f64f2543be0
BLAKE2b-256 checksum
How to use checksums
370d15ec60ee68fd8a6b522ef35002bf1158df8453bf5ceb3ca1af087e1764b9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for phantom-kv 0.7.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for phantom_kv-0.7.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.7.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page