pcdlint (Prompt-Cache Determinism Linter)

A static taint analysis linter that detects code patterns silently invalidating LLM Prompt Caching (OpenAI & Anthropic SDKs).

The $10,000 Bug Explained

LLM prompt caching works by storing the prefix of a prompt in a fast cache. When the prefix matches a cached version, the model skips re-processing the prefix — delivering a 10x read discount versus the full write cost.

The catch? The cache key is computed from the exact byte sequence of the prompt prefix. A single non-deterministic character at position 0 — like datetime.now() — changes every single byte, making the cache completely useless.

Full Write Cost:  ██████████  ($0.030 / 1K tokens)
Cache Read Cost:  █          ($0.003 / 1K tokens)  ← 10x cheaper

One datetime.now() at character 0 silently destroys cache hits, wasting money on every request.

❌ Bad Code (0% Cache Hit)

from datetime import datetime

system = f"Time: {datetime.now()}\n{STATIC_RULES}"
#                                    ^^^^^^^^^^^^ PREFIX TAINTED — every request has a unique prefix

client.chat.completions.create(
    model="gpt-4",
    system=system,  # Cache MISS every time!
)

✅ Good Code (90% Cost Reduction)

from datetime import datetime

system = f"{STATIC_RULES}\nTime: {datetime.now()}"
#       ^^^^^^^^^^^^^^ Static prefix first, dynamic value at the end — cache prefix preserved

client.chat.completions.create(
    model="gpt-4",
    system=system,  # Cache HIT — prefix bytes match across requests!
)

Rule Reference

Installation

pip install pcdlint

Or install from source with dev dependencies:

pip install -e ".[dev]"

CLI Usage

# Check a single file
pcdlint check src/my_app.py

# Check multiple paths
pcdlint check src/ tests/

# Output as JSON
pcdlint check src/ --format json

# Fail on warnings (useful for CI)
pcdlint check src/ --fail-on-warn

GitHub Actions CI Integration

name: pcdlint
on: [push, pull_request]
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install pcdlint
      - run: pcdlint check src/ --fail-on-warn

How It Works

1. AST Parsing: Uses Python's built-in ast module to parse source files — no external compilers needed.
2. Taint Tracking: Identifies non-deterministic sources (datetime.now(), uuid.uuid4(), os.urandom(), etc.) and tracks their propagation through f-strings, concatenation, and .format().
3. Prefix Analysis: Precisely determines if a tainted expression appears before a static prefix solid in the prompt string.
4. Rule Matching: Checks tainted prompts against LLM API sink calls (chat.completions.create, messages.create, etc.) and reports violations.