refactor(core): remove unreferenced helpers, attributes and a shadowed module (#4091)

## Description

This PR removes code that nothing calls: one shadowed module, five
functions or classes, two attributes that are set but never read, and
two constants. About 140 lines go.

Evidence: for each name I ran a word-boundary search across `headroom`,
`crates`, `plugins`, `sdk`, `examples`, `benchmarks`, `scripts`, `e2e`,
`docs`, `wiki`, `.github`, `pyproject.toml`, `tests` and the org's
consumer repos. Each search found only the definition. None of the names
is in a lazy export map, an entry point or the docs.

`headroom/cli.py` was a January back-compat shim, `from headroom.cli
import main`. The `headroom/cli/` package has the same import name, and
a package directory wins over a module file in the same directory, so
the file can never be imported. I checked this in both install modes:
- In the published `headroom-ai==0.40.0` wheel, which ships both,
`import headroom.cli` resolves to `headroom/cli/__init__.py`.
- In the repo's editable install, it resolves to the same file.

The `headroom` console script points at `headroom.cli:main`, which is
the package.

Refs #4136

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)

## Changes Made

- Delete `headroom/cli.py`, and its entry in `[tool.coverage.run] omit`
in `pyproject.toml`.
- `headroom/client.py`: delete `HeadroomClient._call_openai` and
`_call_anthropic`. Since b17c6d81, `_create` calls
`call_client_transport(api_style, …)` directly.
- `headroom/copilot_auth.py`: delete `copilot_api_url()`, which only
forwarded to `_configured_api_url()`.
- `headroom/perf/analyzer.py`: delete `_litellm_cost()`, and update the
section comment. `_get_list_price` still uses the litellm import.
- `headroom/ccr/batch_processor.py`: delete the `APIClient` Protocol,
and the `Protocol` import it alone used.
- `headroom/ccr/batch_store.py`: delete
`BatchContextStore._cleanup_task`, which is set but never read.
- `headroom/ccr/mcp_server.py`: delete
`HeadroomMCPServer._compressor_initialized`, which is set but never
read.
- `headroom/telemetry/toin.py`: delete `DEFAULT_TOIN_DIR` and
`DEFAULT_TOIN_FILE`. The path comes from `HEADROOM_TOIN_PATH` and
`headroom.paths`.
- `headroom/telemetry/models.py`: delete
`FieldSemantics.is_value_important()`, part of the request-time hint API
that PR-B5 retired.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest -q -p no:cacheprovider tests/test_provider_registry_extended.py tests/test_copilot_auth.py tests/test_cli_perf_format.py tests/test_perf_per_port_logs.py tests/test_ccr_batch_store.py tests/test_ccr_batch_processor.py tests/test_ccr_mcp_http.py tests/test_ccr_mcp_server.py tests/test_toin.py tests/test_toin_integration.py tests/test_telemetry.py tests/test_package_init_lazy.py
334 passed, 6 skipped in 10.91s
$ pytest -q -p no:cacheprovider tests/test_cache/test_client_integration.py tests/test_canonical_pipeline.py tests/test_models.py
60 passed in 28.63s
$ uvx ruff@0.16.8 check <8 touched .py files>
All checks passed!
$ python -m mypy <8 touched .py files> --ignore-missing-imports
Success: no issues found in 8 source files
$ python -m headroom.cli --help
Usage: python -m headroom.cli [OPTIONS] COMMAND [ARGS]...
# published wheel, unpacked, with the editable path removed from sys.path:
$ python -I -c "import headroom.cli as c; print(c.__file__)"
.../wheel/x/headroom/cli/__init__.py
# editable install, run from outside the repo:
$ python -c "import headroom.cli as c; print(c.__file__)"
/Users/tejas/headroom/headroom/cli/__init__.py
```

## Real Behavior Proof

- Environment: macOS, Python 3.12.13, this branch checked out in a
worktree, repo .venv; temp HOME and HEADROOM_WORKSPACE_DIR, offline.
- Exact command / steps: (1) The shared smoke harness `smoke.sh
<worktree>`: it starts a real proxy from this checkout against a local
fake upstream and sends one Anthropic and one OpenAI request with a
compressible tool result. (2) A direct command on this PR's own path:
`cd $TMP && PYTHONPATH=<worktree> python -c 'import headroom.cli as c;
print(c.__file__)'; python -m headroom.cli --help | head -3;
GITHUB_COPILOT_API_URL=https://copilot.example.test python -c 'from
headroom import copilot_auth as c; print(c._configured_api_url())'`.
- Observed result: Both requests return 200 and `/stats` shows savings,
with only the expected offline-mode warnings in proxy.log. The direct
command's output is below.
- Not tested: Live proxy traffic through the Copilot and batch CCR
paths; none of the removed code was on them.

```text
$ bash smoke.sh <worktree>
branch: cleanup/core-misc-dead-helpers @ 221984e8
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines ($SMOKE_TMP/ws/logs/proxy-50464.log):
   2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you configured, operator-configured local endpoints, loopback health probes.
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.
(smoke dir: $SMOKE_TMP)

$ cd $TMP && PYTHONPATH=<worktree> python -c 'import headroom.cli as c; print(c.__file__)'; python -m headroom.cli --help | head -3; GITHUB_COPILOT_API_URL=https://copilot.example.test python -c 'from headroom import copilot_auth as c; print(c._configured_api_url())'
<worktree>/headroom/cli/__init__.py
Usage: python -m headroom.cli [OPTIONS] COMMAND [ARGS]...

  Headroom - The Context Optimization Layer for LLM Applications.
https://copilot.example.test
```

## Runtime Rollout Safety

- Rollout-managed feature(s): None.
- Minimum rollout channel: N/A; dead-code removal.
- Stable/default behavior changed: No. Nothing called the removed code.
- Kill switch / disable path: N/A.
- Unsafe override required: No.
- Qualification impact: None.
- Rollback path: Revert this commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review. This is a pure
deletion. No test referenced any removed name, and no doc mentions one.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
This commit is contained in:
Tejas Chopra
2026-10-10 08:58:09 -07:00
committed by GitHub
parent 85c35799ea
commit 08fce18310
10 changed files with 4 additions and 140 deletions
+1 -14
View File
@@ -23,7 +23,7 @@ from __future__ import annotations
import json
import logging
from dataclasses import dataclass
from typing import Any, Protocol
from typing import Any
import httpx
@@ -34,19 +34,6 @@ from .tool_injection import CCR_TOOL_NAME
logger = logging.getLogger(__name__)
class APIClient(Protocol):
"""Protocol for making API calls."""
async def post(
self,
url: str,
headers: dict[str, str],
json: dict[str, Any],
) -> httpx.Response:
"""Make a POST request."""
...
@dataclass
class BatchResultProcessorConfig:
"""Configuration for batch result processing."""
-1
View File
@@ -126,7 +126,6 @@ class BatchContextStore:
self._ttl = ttl
self._max_contexts = max_contexts
self._lock = asyncio.Lock()
self._cleanup_task: asyncio.Task | None = None
async def store(self, context: BatchContext) -> None:
"""Store a batch context.
-1
View File
@@ -388,7 +388,6 @@ class HeadroomMCPServer:
self._stats = SessionStats()
self._local_store: Any = None # Lazy-initialized CompressionStore
self._token_estimator: EstimatingTokenCounter | None = None
self._compressor_initialized = False
# File read cache: path → (content_hash, ccr_hash, line_count, token_count)
self._file_cache: dict[str, tuple[str, str, int, int]] = {}
-6
View File
@@ -1,6 +0,0 @@
"""Backwards compatibility - CLI moved to headroom.cli package."""
from headroom.cli import main
if __name__ == "__main__":
main()
-40
View File
@@ -642,46 +642,6 @@ class HeadroomClient:
self._storage.save(metrics)
raise
def _call_openai(
self,
*,
model: str,
messages: list[dict[str, Any]],
stream: bool,
metrics: RequestMetrics,
**kwargs: Any,
) -> Any:
"""Call OpenAI-style API."""
return call_client_transport(
"openai",
self,
model=model,
messages=messages,
stream=stream,
metrics=metrics,
**kwargs,
)
def _call_anthropic(
self,
*,
model: str,
messages: list[dict[str, Any]],
stream: bool,
metrics: RequestMetrics,
**kwargs: Any,
) -> Any:
"""Call Anthropic-style API."""
return call_client_transport(
"anthropic",
self,
model=model,
messages=messages,
stream=stream,
metrics=metrics,
**kwargs,
)
def _wrap_stream(
self,
stream: Iterator[Any],
-11
View File
@@ -281,17 +281,6 @@ def _configured_api_url() -> str:
return DEFAULT_API_URL
def copilot_api_url() -> str:
"""Return the configured Copilot API base URL without any network calls.
Resolves ``GITHUB_COPILOT_API_URL``, then the configured enterprise domain,
then ``api.githubcopilot.com``. Unlike :func:`resolve_copilot_api_url` this
performs no token exchange, so it is safe to call while routing a request.
"""
return _configured_api_url()
# GitHub's token exchange advertises the host that serves inline completions
# under ``endpoints.proxy``, alongside the ``endpoints.api`` chat host. It is
# recorded here when observed so completions routing uses GitHub's own answer
+3 -30
View File
@@ -67,12 +67,11 @@ _STAGE_TIMINGS_RE = re.compile(
# ---------------------------------------------------------------------------
# Cache-aware pricing via LiteLLM
# List pricing via LiteLLM
# ---------------------------------------------------------------------------
# LiteLLM already knows per-token costs for 100+ models including
# cache_read and cache_creation pricing. We call it directly instead
# of maintaining our own pricing tables.
# LiteLLM already knows per-token costs for 100+ models. We read it
# directly instead of maintaining our own pricing tables.
try:
import litellm as _litellm
@@ -82,32 +81,6 @@ except ImportError:
_LITELLM_AVAILABLE = False
def _litellm_cost(
model: str,
prompt_tokens: int,
cache_read_tokens: int = 0,
cache_write_tokens: int = 0,
) -> float | None:
"""Compute input cost via litellm.cost_per_token (cache-aware).
Returns total input cost in USD, or None if model not found.
"""
if not _LITELLM_AVAILABLE:
return None
resolved = resolve_litellm_model(model)
try:
input_cost, _ = _litellm.cost_per_token(
model=resolved,
prompt_tokens=prompt_tokens,
completion_tokens=0,
cache_read_input_tokens=cache_read_tokens,
cache_creation_input_tokens=cache_write_tokens,
)
return float(input_cost)
except Exception:
return None
def _get_list_price(model: str) -> float | None:
"""Get list input price per 1M tokens."""
if not _LITELLM_AVAILABLE:
-32
View File
@@ -633,38 +633,6 @@ class FieldSemantics:
self.inferred_type = inferred
self.confidence = confidence
def is_value_important(self, value_hash: str) -> bool:
"""Check if a specific value is considered important.
A value is important if:
1. It's in the important_value_hashes list (has been retrieved)
2. It's NOT the default value (for error_indicator type)
Args:
value_hash: SHA256[:8] hash of the value to check.
Returns:
True if this value should be preserved during compression.
"""
# If we don't have enough data, be conservative
if self.confidence < 0.3:
return False
# For error_indicator: non-default values are important
if self.inferred_type == "error_indicator":
if self.default_value_hash and value_hash != self.default_value_hash:
return True
# For any type: values that have been retrieved are important
if value_hash in self.important_value_hashes:
return True
# For status: check if this value has been retrieved
if self.inferred_type == "status":
return value_hash in self.value_retrieval_frequency
return False
@dataclass
class CompressionEvent:
-4
View File
@@ -78,10 +78,6 @@ logger = logging.getLogger(__name__)
# Environment variable for custom TOIN storage path
TOIN_PATH_ENV_VAR = "HEADROOM_TOIN_PATH"
# Default TOIN storage directory and file
DEFAULT_TOIN_DIR = ".headroom"
DEFAULT_TOIN_FILE = "toin.json"
# ── Aggregation-key defaults ────────────────────────────────────────────
# Used when callers haven't plumbed auth-mode / model-family detection
# (PR-F3 wires the real detectors). Shipping a real `"unknown"` slice is
-1
View File
@@ -541,7 +541,6 @@ markers = [
source = ["headroom"]
branch = true
omit = [
"headroom/cli.py",
"*/tests/*",
]