Examples
Copy-paste snippets you can run right away. All examples work with the built-in word tokenizer, no extras required.
Python API
From quick profiling to waste detection and prompt diffs.
from prompt_flamegraph import profile_prompt
prompt = {
"system_prompt": "You are a helpful coding assistant.",
"tools": [
{"name": "read_file", "description": "Read a file."},
{"name": "run_command", "description": "Run a shell command."},
],
"rag_context": {
"doc_1.py": "def helper():\n return 'value'\n",
"doc_2.py": "def other():\n return 'other'\n",
},
"chat_history": [
{"role": "user", "content": "Help me debug."},
{"role": "assistant", "content": "What error do you see?"},
],
}
profile_prompt(prompt, output="context.html", cost_per_token=1.5e-6)
from prompt_flamegraph import build_tree, detect_waste
tree = build_tree(prompt)
report = detect_waste(tree)
print(f"Total tokens: {report.total_tokens}")
print(f"Wasted: {report.wasted_tokens} ({report.waste_ratio:.1%})")
for finding in report.findings:
print(f"- {finding.kind}: {finding.message}")
from prompt_flamegraph import diff_prompts
v1 = {
"system_prompt": "You are a helpful coding assistant.",
"tools": ["read_file", "run_command"],
}
v2 = {
"system_prompt": "You are a helpful coding assistant. Be concise.",
"tools": ["read_file", "run_command", "search_web"],
}
diff_prompts(v1, v2, output="diff.html")
from prompt_flamegraph import (
normalize, # raw OpenAI/Anthropic payload -> dict
from_messages, # [{"role": ..., "content": ...}] -> dict
from_langchain, # LangChain-style objects (never imported)
from_litellm_messages, # LiteLLM message lists -> dict
profile_any, # auto-detects the input shape
)
profile_any(openai_payload, output="context.html", model="gpt-4o")
Command line
Same features, without writing a single line of Python.
terminal
$ prompt-flamegraph prompt.json -o context.html --cost 1.5e-6 $ prompt-flamegraph prompt.json --terminal $ prompt-flamegraph v1.json --diff v2.json -o diff.html $ prompt-flamegraph prompt.json --format svg -o context.svg $ prompt-flamegraph prompt.json --format md -o context.md $ prompt-flamegraph prompt.json --model gpt-4o $ prompt-flamegraph prompt.json --budget 100000 --format json -o report.json $ prompt-flamegraph --list-models $ cat openai_request.json | prompt-flamegraph - $ prompt-flamegraph --demo --cost 1.5e-6
Read JSON from a file
The CLI accepts a JSON file, a raw JSON string or an OpenAI/Anthropic payload — and reads stdin with -.
cat openai_request.json | prompt-flamegraph - -o report.html
Estimate cost
Pass --cost in dollars per token and the report shows estimated spend per category.
prompt-flamegraph prompt.json --cost 1.5e-6 -o cost.html
Model-aware pricing
Pass --model gpt-4o and the tokenizer, per-token price and context window come from the model preset.
prompt-flamegraph prompt.json --model gpt-4o -o report.html
CI budget gate
Fail a pipeline when a prompt outgrows its budget — --budget exits with code 3, after the report is written.
prompt-flamegraph prompt.json --budget 100000 --format json -o report.json
With OpenAI-style token counts
Install the tiktoken extra to match OpenAI models.
Install the extra
pip install prompt-flamegraph[tiktoken]
Use it in code
from prompt_flamegraph import profile_prompt
profile_prompt(
prompt,
output="context.html",
tokenizer="tiktoken",
)
Keep exploring
Read the API docs or check the feature list.