# Code Review Graph Token Savings Estimation Methodology: Implementation Guide

> Learn how Code Review Graph estimates token savings using a simple 4 characters to 1 token ratio. Discover the methodology for calculating absolute and percentage savings in this implementation guide.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: technical-article
- Published: 2026-07-25

---

**Code Review Graph estimates token savings by assuming 4 characters equal 1 token, calculating the difference between original and graph-compressed contexts, and returning both absolute and percentage savings.**

The `tirth8205/code-review-graph` repository implements a lightweight **token savings estimation methodology** that helps developers quantify how much LLM context is reduced when converting raw source code into graph-based representations. This approach uses a conservative 4-character-to-token heuristic to provide fast, order-of-magnitude estimates without requiring heavy tokenizer dependencies for every analysis run.

## The Three-Stage Estimation Pipeline

The methodology operates through a deterministic three-stage pipeline implemented in [`code_review_graph/context_savings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/context_savings.py).

### Stage 1: Character-Based Token Approximation

The foundation of the estimation is the `estimate_tokens` function (lines 16-32 in [`code_review_graph/context_savings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/context_savings.py)). This helper converts any value—whether a string, JSON-serializable object, or file representation—into a rough token count using the constant `CHARS_PER_TOKEN = 4`.

For non-string values, the function first serializes the object to JSON using compact separators (`","` and `":"`) with sorted keys, then divides the character length by 4 and rounds up, with a minimum return value of 1 token. This empirical ratio matches the average character-per-token density of most OpenAI models, providing a deliberately conservative upper bound that works across programming languages and payload types.

### Stage 2: Baseline vs. Returned Context Comparison

The `estimate_context_savings` function (lines 54-82) accepts both an `original_context` (the full source code or text you would send to an LLM) and a `returned_context` (the graph-derived payload). Each context passes through `estimate_tokens` to establish token counts.

For efficiency, callers who already know their token counts can bypass the estimation step by supplying `original_tokens` and `returned_tokens` parameters directly.

### Stage 3: Savings Calculation and Output

The final stage computes two metrics:

- **Saved tokens**: `baseline - returned`, clamped to never be negative
- **Saved percent**: `round((saved / baseline) * 100)`, returning 0% when baseline is zero

The function returns a dictionary with the structure `{"estimated": True, "saved_tokens": <int>, "saved_percent": <int>}`. If no valid baseline can be derived (when `original_tokens` ≤ 0), the function returns `None`.

## Optional Calibration with tiktoken

When the optional `tiktoken` library is available, the `verify_with_tiktoken` function (lines 51-98 in [`code_review_graph/context_savings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/context_savings.py)) provides model-specific verification. This utility reads actual file contents and runs the real `cl100k_base` tokenizer (by default) to produce verified baseline and returned token counts.

This allows developers to compare the conservative 4-character estimate against ground-truth tokenization, ensuring the heuristic remains accurate for their specific use case while keeping the default path lightweight.

## Practical Implementation Examples

Estimate tokens for arbitrary Python objects:

```python
from code_review_graph.context_savings import estimate_tokens

obj = {"name": "Alice", "age": 30, "tags": ["engineer", "python"]}
tokens = estimate_tokens(obj)  # → 9 tokens

```

Calculate savings between original and compressed contexts:

```python
from pathlib import Path
from code_review_graph.context_savings import estimate_context_savings

original = Path("big_script.py").read_text()
returned = '{"functions":2,"flows":1}'

savings = estimate_context_savings(
    original_context=original,
    returned_context=returned
)

# → {'estimated': True, 'saved_tokens': 850, 'saved_percent': 45}

```

Attach savings metadata to result dictionaries:

```python
from code_review_graph.context_savings import attach_context_savings

result = {"status": "ok"}
result = attach_context_savings(
    result,
    original_context=original,
    returned_context=returned
)
print(result["context_savings"])

```

Verify estimates using the actual tokenizer:

```python
from code_review_graph.context_savings import verify_with_tiktoken

verification = verify_with_tiktoken(
    repo_root=Path("."),
    changed_files=["big_script.py"],
    response=result,
)

# → {'verified_baseline': 1200, 'verified_returned': 340, 

#    'verified_saved': 860, 'verified_percent': 72}

```

## Core Architecture and Key Files

The token savings estimation methodology spans several files in the repository:

- **[`code_review_graph/context_savings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/context_savings.py)** – Contains the core implementation including `estimate_tokens`, `estimate_context_savings`, `attach_context_savings`, and `verify_with_tiktoken`

- **[`code_review_graph/token_benchmark.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/token_benchmark.py)** – Benchmark utilities that reuse the estimation logic for large-scale evaluations and performance reporting

- **[`code_review_graph/eval/benchmarks/token_efficiency.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/eval/benchmarks/token_efficiency.py)** – Example benchmark showcasing token-efficiency reporting using the estimation functions

- **[`code_review_graph/prompts.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/prompts.py)** – Inserts token-efficiency preambles into LLM prompts, surfacing the savings estimates directly to users

## Summary

- **Conservative heuristic**: The 4-character-per-token rule provides a fast, lightweight upper bound that avoids heavy tokenizer dependencies in production pipelines

- **Three-stage pipeline**: Token estimation (`estimate_tokens`), context comparison (`estimate_context_savings`), and percentage calculation deliver clear metrics for CI dashboards and CLI output

- **Optional verification**: The `verify_with_tiktoken` function enables calibration against real `cl100k_base` tokenization when accuracy validation is required

- **Flexible API**: Support for both automatic character-based estimation and explicit token count passing accommodates diverse integration scenarios

## Frequently Asked Questions

### Why does the methodology use 4 characters per token?

The 4-character rule represents an empirical average across OpenAI models and most modern transformers. This conservative ratio deliberately over-estimates token counts slightly, ensuring that reported savings represent a minimum guaranteed reduction while keeping calculations fast enough for real-time CI dashboards without importing heavyweight tokenizer libraries.

### What happens when the baseline token count is zero or negative?

When `original_tokens` is less than or equal to zero, `estimate_context_savings` returns `None` rather than a savings dictionary. This prevents division-by-zero errors in percentage calculations and signals that no meaningful baseline exists for comparison.

### Can I bypass the character-based estimation with exact token counts?

Yes. The `estimate_context_savings` function accepts optional `original_tokens` and `returned_tokens` parameters. When provided, these values skip the `estimate_tokens` logic entirely, allowing you to supply pre-calculated counts from your own tokenization pipeline or external tools.

### Where does the methodology surface in the user interface?

According to the source code in [`code_review_graph/prompts.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/prompts.py), the token savings estimates are inserted into LLM prompt preambles to demonstrate efficiency. Additionally, `format_context_savings` provides human-readable strings like "Estimated context saved: ~850 tokens (~45%)" for terminal UIs and logging output.