fix(startup): suppress proxy startup log noise (#619)

* docs: add enterprise.md

* docs: add link to enterprisemd in README

* fix(copilot): restore generic endpoint for non-subscription OAuth (#610) (#612)

* fix(copilot): restore generic endpoint for non-subscription OAuth (#610)

0.23.0 re-pointed the shared Copilot OAuth branch from the generic
api.githubcopilot.com host to the account-specific endpoints.api host
returned by /copilot_internal/user, and made resolve_copilot_api_url
ignore the GITHUB_COPILOT_API_URL override whenever a token resolved.

That change was meant to add --subscription, but it also altered the
pre-existing non-subscription OAuth flow that worked on 0.22.4. The
account host does not serve newer models (e.g. gpt-5.4) on the responses
API, so wrapped requests began failing with unsupported-model errors
while plain Copilot and 0.22.4 kept working.

Restore 0.22.4 routing for non-subscription OAuth (generic host, still
overridable) and keep account resolution only for --subscription.
resolve_copilot_api_url now honors GITHUB_COPILOT_API_URL first, so the
override escape hatch works for every path. BYOK is unaffected.

Add a regression suite that mocks a successful user-info response, the
real-world path the prior test never exercised (it relied on the network
call failing in CI and falling back to the generic host).

* fix(copilot): route subscription + OAuth through the generic host (#610)

The 0.23.0 endpoint resolution derived the Copilot API host from
/copilot_internal/user (endpoints.api), which returns a segmented host
(e.g. api.individual.githubcopilot.com) that does not serve newer models
on the responses API and is not the host the official Copilot client
routes with (that comes from the token-exchange endpoint). --subscription
used the identical resolution, so it carried the same latent regression
as the non-subscription OAuth path.

Make Copilot host resolution override -> generic for BOTH --subscription
and the implicit OAuth path, and stop using user-info to route. Accounts
that require a dedicated host (enterprise / data residency) pin it via
GITHUB_COPILOT_API_URL. resolve_copilot_api_url no longer makes a network
call; _fetch_copilot_user_info is retained for token validation.

Update the subscription smoke tests that encoded the old account-host
assumption, and add wrap-level + unit coverage that --subscription routes
to the generic host even when user-info advertises an account host, and
that the GITHUB_COPILOT_API_URL override flows through both paths.

* docs(copilot): document generic-host routing + enterprise override (#610)

Spell out the routing contract introduced by the #610 fix so enterprise
users have a supported path. Headroom routes wrapped Copilot hosted
traffic (--subscription and OAuth) to the generic api.githubcopilot.com,
and accounts on a dedicated host (Enterprise Cloud data residency, egress
proxy) pin it via GITHUB_COPILOT_API_URL.

- copilot --help: note the generic host + GITHUB_COPILOT_API_URL override.
- TESTING-copilot-subscription.md: add "API host & Enterprise / data
  residency" section; correct the stale api.*.githubcopilot.com claim; and
  invite enterprise tenants who want token-exchange-based auto-detection to
  open an issue.
- integration-guide.md: short hosted-host + override note in the Copilot
  section.

* fix(wrap): report unbindable proxy ports (#602)

* fix(proxy): fail-open on corrupt golden bytes instead of RuntimeError (#603)

* fix(proxy): fail-open on corrupt golden bytes instead of RuntimeError

Permanent session corruption: once golden bytes become unreadable
(UnicodeDecodeError / JSONDecodeError), every subsequent request for
the session raised RuntimeError, returning 500 until proxy restart.

Fix: log at ERROR level and recover — skip the corrupt memory tool,
or regenerate a fresh CCR definition — rather than propagating
RuntimeError and permanently breaking the session.

Also change proxy_inbound_request_aborted from logger.info to
logger.error with exc_info=True so tracebacks appear in logs.

Closes: proxy silent-500 sessions in the wild (observed 2026-06-04)

* fix(tests): re-enable headroom log propagation in corrupt-bytes tests

configure_proxy_logging() sets headroom_logger.propagate = False to prevent
duplicate writes when the proxy redirects stderr to a log file. In CI the
proxy initialises its logging stack before the test suite, leaving propagation
disabled. pytest's caplog handler attaches to the root logger, so records that
stop at the headroom logger are never captured.

Added _enable_headroom_log_propagation autouse fixture that temporarily
re-enables propagation for the duration of each test, making caplog capture
work regardless of the surrounding logging configuration.

* fix(tests): remove unused imports from corrupt-bytes regression tests

Remove json, SessionCcrTracker, and SessionToolTracker imports that were
imported but never referenced in the test body. Fixes ruff F401 and I001
lint errors reported by CI.

---------

Co-authored-by: Patrick Ancillotti <patrick.ancillotti@people.inc>

* fix(startup): suppress log noise from litellm, trafilatura, HF hub, and tiktoken warning

* fix(startup): suppress httpx INFO logs from sentence_transformers HEAD checks

* docs(changelog): add entry for startup log noise suppression fixes

* refactor(startup): extract hf_hub_download_local_first into onnx_runtime

The three _hub_download/_hub_dl helpers in embedders.py, onnx_router.py, and
kompress_compressor.py are identical -- try local cache first, fall back to
network download. Extract into a single hf_hub_download_local_first() function
in onnx_runtime.py (the natural home for shared ORT/HF utilities) and update
all three callers to use it.

* fix(lint): sort imports and remove unused _FALLBACK_WARNING_SHOWN import

* fix(lint): cast hf_hub_download return to str for mypy no-any-return

---------

Co-authored-by: Patrick Ancillotti <patrick.ancillotti@people.inc>
This commit is contained in:
Patrick A 2026-06-05 18:44:40 -04:00 committed by GitHub
parent 53d2342291
commit 45559011b1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
10 changed files with 262 additions and 22 deletions

View file

@ -6,6 +6,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Bug Fixes
* **startup:** suppress proxy startup log noise — litellm banner, trafilatura parse errors, HuggingFace Hub unauthenticated warnings, tiktoken fallback warning, and httpx INFO lines from sentence_transformers HEAD checks. Affected files: `headroom/providers/litellm.py`, `headroom/transforms/html_extractor.py`, `headroom/memory/adapters/embedders.py`, `headroom/providers/anthropic.py`, `headroom/providers/registry.py`, `headroom/image/onnx_router.py`, `headroom/transforms/kompress_compressor.py`.
## [0.23.0](https://github.com/chopratejas/headroom/compare/v0.22.4...v0.23.0) (2026-06-04)
### Features

View file

@ -20,7 +20,7 @@ from typing import Any
import numpy as np
from headroom.image.trained_router import ImageSignals, RouteDecision, Technique
from headroom.onnx_runtime import create_cpu_session_options
from headroom.onnx_runtime import create_cpu_session_options, hf_hub_download_local_first
logger = logging.getLogger(__name__)
@ -57,19 +57,18 @@ class OnnxTechniqueRouter:
return
import onnxruntime as ort
from huggingface_hub import hf_hub_download
from tokenizers import Tokenizer
logger.info("Loading technique-router ONNX INT8...")
model_path = hf_hub_download(_TECHNIQUE_ROUTER_REPO, "model_quantized.onnx")
model_path = hf_hub_download_local_first(_TECHNIQUE_ROUTER_REPO, "model_quantized.onnx")
self._classifier_session = ort.InferenceSession(
model_path,
create_cpu_session_options(ort),
providers=["CPUExecutionProvider"],
)
tokenizer_path = hf_hub_download(_TECHNIQUE_ROUTER_REPO, "tokenizer.json")
tokenizer_path = hf_hub_download_local_first(_TECHNIQUE_ROUTER_REPO, "tokenizer.json")
self._tokenizer = Tokenizer.from_file(tokenizer_path)
self._tokenizer.enable_truncation(max_length=64)
self._tokenizer.enable_padding(length=64)
@ -77,7 +76,7 @@ class OnnxTechniqueRouter:
# Load label mapping
import json
config_path = hf_hub_download(_TECHNIQUE_ROUTER_REPO, "config.json")
config_path = hf_hub_download_local_first(_TECHNIQUE_ROUTER_REPO, "config.json")
with open(config_path) as f:
config = json.load(f)
self._id2label = {int(k): v for k, v in config.get("id2label", {}).items()}
@ -93,18 +92,17 @@ class OnnxTechniqueRouter:
return
import onnxruntime as ort
from huggingface_hub import hf_hub_download
logger.info("Loading SigLIP ONNX INT8 image encoder...")
model_path = hf_hub_download(_SIGLIP_ENCODER_REPO, "image_encoder_int8.onnx")
model_path = hf_hub_download_local_first(_SIGLIP_ENCODER_REPO, "image_encoder_int8.onnx")
self._siglip_session = ort.InferenceSession(
model_path,
create_cpu_session_options(ort),
providers=["CPUExecutionProvider"],
)
embeddings_path = hf_hub_download(_SIGLIP_ENCODER_REPO, "text_embeddings.npz")
embeddings_path = hf_hub_download_local_first(_SIGLIP_ENCODER_REPO, "text_embeddings.npz")
loaded = np.load(embeddings_path)
self._text_embeddings = {k: loaded[k] for k in loaded.files}

View file

@ -13,17 +13,30 @@ from __future__ import annotations
import asyncio
import logging
import os
import warnings
from functools import cached_property
from typing import TYPE_CHECKING, Any, cast
import numpy as np
from headroom.models.config import ML_MODEL_DEFAULTS
from headroom.onnx_runtime import create_cpu_session_options
from headroom.onnx_runtime import create_cpu_session_options, hf_hub_download_local_first
if TYPE_CHECKING:
from sentence_transformers import SentenceTransformer
# Suppress HuggingFace Hub warnings about missing tokens and rate limits.
# These appear whenever hf_hub_download is called without HF_TOKEN set.
# We operate in an authenticated-optional mode; warnings are not actionable.
os.environ.setdefault("HF_HUB_DISABLE_PROGRESS_BARS", "1")
os.environ.setdefault("HF_HUB_DISABLE_IMPLICIT_TOKEN", "1")
warnings.filterwarnings("ignore", category=UserWarning, module="huggingface_hub")
# Also silence the huggingface_hub logger which emits rate-limit advisory messages.
logging.getLogger("huggingface_hub").setLevel(logging.ERROR)
# sentence_transformers uses httpx to check model file manifests on every startup.
# These HEAD/GET requests generate INFO lines per worker; suppress to WARNING.
logging.getLogger("httpx").setLevel(logging.WARNING)
logger = logging.getLogger(__name__)
@ -305,13 +318,13 @@ class OnnxLocalEmbedder:
return
import onnxruntime as ort
from huggingface_hub import hf_hub_download
from tokenizers import Tokenizer
logger.info("Loading ONNX embedding model (all-MiniLM-L6-v2, ~86MB)...")
model_path = hf_hub_download(self.ONNX_REPO, "model.onnx")
tok_path = hf_hub_download(self.ONNX_REPO, "tokenizer.json")
# Prefer local cache to avoid a redundant network HEAD on warm starts.
model_path = hf_hub_download_local_first(self.ONNX_REPO, "model.onnx")
tok_path = hf_hub_download_local_first(self.ONNX_REPO, "tokenizer.json")
# Keep a small thread pool for Docker compatibility and disable ORT's
# CPU memory arena/pattern caches so long-running proxy workers do not

View file

@ -7,6 +7,32 @@ import sys
from typing import Any
def hf_hub_download_local_first(repo_id: str, filename: str) -> str:
"""Download a file from HuggingFace Hub, preferring the local cache.
Tries ``local_files_only=True`` first to avoid a network HEAD request when
the model is already cached. Falls back to a normal (network-allowed)
download on the first cold start.
Args:
repo_id: HuggingFace Hub repository identifier (e.g. ``"org/model"``).
filename: Filename within the repository.
Returns:
Absolute path to the local cached file.
Raises:
Any exception raised by ``hf_hub_download`` on a genuine download failure.
"""
from huggingface_hub import hf_hub_download
from huggingface_hub.errors import EntryNotFoundError, LocalEntryNotFoundError
try:
return str(hf_hub_download(repo_id, filename, local_files_only=True))
except (LocalEntryNotFoundError, EntryNotFoundError, OSError):
return str(hf_hub_download(repo_id, filename))
def create_cpu_session_options(
ort: Any,
*,

View file

@ -36,6 +36,9 @@ def _get_litellm_clients() -> tuple[Any | None, Any | None]:
try:
import litellm
litellm.suppress_debug_info = True
litellm.set_verbose = False
from litellm import get_model_info as litellm_get_model_info
except ImportError:
return None, None
@ -223,13 +226,15 @@ class AnthropicTokenCounter(TokenCounter):
Falls back to tiktoken approximation only when no client is available.
"""
def __init__(self, model: str, client: Any = None):
def __init__(self, model: str, client: Any = None, warn: bool = True):
"""Initialize token counter.
Args:
model: Anthropic model name.
client: Optional anthropic.Anthropic client for API-based counting.
If not provided, falls back to tiktoken approximation.
warn: If False, suppresses the no-client UserWarning (useful for
internal proxy usage where approximation is intentional).
"""
global _FALLBACK_WARNING_SHOWN
@ -238,7 +243,7 @@ class AnthropicTokenCounter(TokenCounter):
self._encoding: Any = None
self._use_api = client is not None
if not self._use_api and not _FALLBACK_WARNING_SHOWN:
if not self._use_api and warn and not _FALLBACK_WARNING_SHOWN:
warnings.warn(
"AnthropicProvider: No client provided, using tiktoken approximation. "
"For accurate counting, pass an Anthropic client: "
@ -446,6 +451,7 @@ class AnthropicProvider(Provider):
self,
client: Any = None,
context_limits: dict[str, int] | None = None,
warn: bool = True,
):
"""Initialize Anthropic provider.
@ -453,12 +459,16 @@ class AnthropicProvider(Provider):
client: Optional anthropic.Anthropic client for accurate token counting.
If not provided, uses tiktoken approximation.
context_limits: Optional override for model context limits.
warn: If False, suppresses the no-client UserWarning. Set to False
in contexts where tiktoken approximation is intentional (e.g.
the internal proxy pipeline provider).
Example:
from anthropic import Anthropic
provider = AnthropicProvider(client=Anthropic())
"""
self._client = client
self._warn = warn
self._token_counters: dict[str, AnthropicTokenCounter] = {}
# Build context limits: defaults -> config file -> env var -> explicit
@ -488,6 +498,7 @@ class AnthropicProvider(Provider):
self._token_counters[model] = AnthropicTokenCounter(
model=model,
client=self._client,
warn=self._warn,
)
return self._token_counters[model]

View file

@ -33,6 +33,12 @@ logger = logging.getLogger(__name__)
# Check if litellm is available
try:
import litellm
# Suppress litellm's startup banner ("Provider List: https://...") and
# verbose debug output that spams stdout on every worker import.
litellm.suppress_debug_info = True
litellm.set_verbose = False
from litellm import get_model_info as litellm_get_model_info
from litellm import model_cost as litellm_model_cost
from litellm import token_counter as litellm_token_counter

View file

@ -126,7 +126,9 @@ def build_proxy_provider_runtime(config: Any) -> ProxyProviderRuntime:
return ProxyProviderRuntime(
api_targets=api_targets,
pipeline_providers={
"anthropic": AnthropicProvider(),
# warn=False: the proxy pipeline provider intentionally uses tiktoken
# approximation (no Anthropic client available at this layer).
"anthropic": AnthropicProvider(warn=False),
"openai": OpenAIProvider(),
},
)

View file

@ -23,6 +23,11 @@ from typing import Any
import trafilatura
from trafilatura.settings import use_config
# Suppress trafilatura's internal parse-error noise (e.g. "parsed tree length: 0")
# which appears at WARNING level on every document that fails to extract content.
# These are expected failures for non-article pages; log them only at CRITICAL.
logging.getLogger("trafilatura").setLevel(logging.CRITICAL)
logger = logging.getLogger(__name__)

View file

@ -25,7 +25,11 @@ from dataclasses import dataclass
from typing import Any, Literal
from ..config import TransformResult
from ..onnx_runtime import create_cpu_session_options, trim_process_heap
from ..onnx_runtime import (
create_cpu_session_options,
hf_hub_download_local_first,
trim_process_heap,
)
from ..tokenizer import Tokenizer
from .base import Transform
@ -329,10 +333,9 @@ def _load_kompress_onnx(
if model_id in _kompress_cache:
return _kompress_cache[model_id]
from huggingface_hub import hf_hub_download
logger.info("Downloading Kompress ONNX model from %s ...", model_id)
onnx_path = hf_hub_download(model_id, "onnx/kompress-int8.onnx")
onnx_path = hf_hub_download_local_first(model_id, "onnx/kompress-int8.onnx")
backend = "onnx_coreml" if use_coreml else "onnx"
providers: list[Any]
@ -383,10 +386,9 @@ def _load_kompress_pytorch(model_id: str, device: str = "auto") -> tuple[Any, An
if model_id in _kompress_cache:
return _kompress_cache[model_id]
from huggingface_hub import hf_hub_download
logger.info("Downloading Kompress PyTorch model from %s ...", model_id)
weights_path = hf_hub_download(model_id, "model.safetensors")
weights_path = hf_hub_download_local_first(model_id, "model.safetensors")
HeadroomCompressorModel = _get_model_class()
model = HeadroomCompressorModel()

View file

@ -0,0 +1,170 @@
"""Tests for startup log noise suppression.
Covers the fixes in:
- headroom/memory/adapters/embedders.py (HF env vars, httpx logger)
- headroom/providers/anthropic.py (warn=False suppresses tiktoken warning)
- headroom/providers/litellm.py (suppress_debug_info, set_verbose)
- headroom/transforms/html_extractor.py (trafilatura logger CRITICAL)
"""
from __future__ import annotations
import logging
import warnings
class TestAnthropicWarnParameter:
"""AnthropicProvider.warn=False suppresses the no-client tiktoken warning."""
def test_warn_true_emits_warning_without_client(self):
"""Default warn=True should emit UserWarning when no client is given."""
import headroom.providers.anthropic as _mod
from headroom.providers.anthropic import AnthropicProvider
# Only runs if the module-level dedup flag hasn't fired yet in this process;
# we reset it to guarantee the warning fires.
original = _mod._FALLBACK_WARNING_SHOWN
_mod._FALLBACK_WARNING_SHOWN = False
try:
with warnings.catch_warnings(record=True) as w:
warnings.simplefilter("always")
provider = AnthropicProvider(warn=True)
# Trigger token-counter creation which is where warning fires
try:
provider.get_token_counter("claude-3-5-sonnet-20241022")
except Exception:
pass
user_warnings = [x for x in w if issubclass(x.category, UserWarning)]
assert any("tiktoken" in str(warning.message) for warning in user_warnings)
finally:
_mod._FALLBACK_WARNING_SHOWN = original
def test_warn_false_suppresses_warning(self):
"""warn=False must produce zero UserWarnings about tiktoken fallback."""
import headroom.providers.anthropic as _mod
from headroom.providers.anthropic import AnthropicProvider
original = _mod._FALLBACK_WARNING_SHOWN
_mod._FALLBACK_WARNING_SHOWN = False
try:
with warnings.catch_warnings(record=True) as w:
warnings.simplefilter("always")
provider = AnthropicProvider(warn=False)
try:
provider.get_token_counter("claude-3-5-sonnet-20241022")
except Exception:
pass
tiktoken_warnings = [
x for x in w if issubclass(x.category, UserWarning) and "tiktoken" in str(x.message)
]
assert tiktoken_warnings == [], (
f"Expected no tiktoken warnings with warn=False, got: {tiktoken_warnings}"
)
finally:
_mod._FALLBACK_WARNING_SHOWN = original
def test_registry_uses_warn_false(self):
"""The internal proxy provider registry must pass warn=False to AnthropicProvider."""
import inspect
from headroom.providers import registry as _registry_mod
source = inspect.getsource(_registry_mod)
assert "AnthropicProvider(warn=False)" in source, (
"registry.py must instantiate AnthropicProvider with warn=False"
)
class TestEmbedderLogLevels:
"""headroom.memory.adapters.embedders must set specific logger levels at import time."""
def test_huggingface_hub_logger_is_error_or_higher(self):
"""huggingface_hub logger must be silenced to ERROR or above."""
import headroom.memory.adapters.embedders # noqa: F401
level = logging.getLogger("huggingface_hub").level
assert level >= logging.ERROR, (
f"Expected huggingface_hub logger level >= ERROR ({logging.ERROR}), got {level}"
)
def test_httpx_logger_is_warning_or_higher(self):
"""httpx logger must be set to WARNING or above to suppress HEAD request INFO lines."""
import headroom.memory.adapters.embedders # noqa: F401
level = logging.getLogger("httpx").level
assert level >= logging.WARNING, (
f"Expected httpx logger level >= WARNING ({logging.WARNING}), got {level}"
)
def test_hf_hub_env_vars_are_set(self):
"""HF Hub env vars to disable progress bars and implicit tokens must be set."""
import os
import headroom.memory.adapters.embedders # noqa: F401
assert os.environ.get("HF_HUB_DISABLE_PROGRESS_BARS") == "1"
assert os.environ.get("HF_HUB_DISABLE_IMPLICIT_TOKEN") == "1"
class TestLiteLLMLogSuppression:
"""litellm startup banner suppression must be applied at import time."""
def test_litellm_suppress_debug_info_is_set(self):
"""litellm.suppress_debug_info must be True after importing the litellm provider."""
litellm = pytest_importorskip_litellm()
if litellm is None:
return # litellm not installed — skip gracefully
import headroom.providers.litellm # noqa: F401
assert litellm.suppress_debug_info is True, (
"litellm.suppress_debug_info must be True to silence startup banner"
)
def test_litellm_set_verbose_is_false(self):
"""litellm.set_verbose must be False after importing the litellm provider."""
litellm = pytest_importorskip_litellm()
if litellm is None:
return
import headroom.providers.litellm # noqa: F401
assert litellm.set_verbose is False, (
"litellm.set_verbose must be False to suppress verbose debug output"
)
def pytest_importorskip_litellm():
"""Return litellm if installed, else None (for graceful skip in optional-dep tests)."""
try:
import litellm
return litellm
except ImportError:
return None
class TestTrafilaturaLogLevel:
"""trafilatura logger must be raised to CRITICAL to suppress parse-error noise."""
def test_trafilatura_logger_is_critical(self):
"""trafilatura logger must be CRITICAL or above after importing html_extractor."""
pytest_importorskip_trafilatura()
import headroom.transforms.html_extractor # noqa: F401
level = logging.getLogger("trafilatura").level
assert level >= logging.CRITICAL, (
f"Expected trafilatura logger level >= CRITICAL ({logging.CRITICAL}), got {level}"
)
def pytest_importorskip_trafilatura():
"""Skip test if trafilatura is not installed."""
try:
import trafilatura # noqa: F401
except ImportError:
import pytest
pytest.skip("trafilatura not installed")