Files
headroom/pyproject.toml
d379efe90c test: skip tests marked live by default (#4786)
## Description

`pyproject.toml` declares a `live` marker ("opt-in multi-turn tests that
hit real upstream APIs; require provider keys"), and two test files
carry it: `tests/test_thinking_signature_scope_live.py` ("Opt-in:
requires a real key and is gated behind `pytest.mark.live`. Run with
`pytest -m live ...`") and `tests/test_realignment_live_multi_turn.py`
(which describes a "default `pytest -m "not live"` run that never
touches the network"). `addopts` was `-v --tb=short` with no `-m`
filter, so a plain `pytest` run on a machine with `ANTHROPIC_API_KEY` in
the environment, or in the project's `.env` (loaded by
`tests/_dotenv.py`), collected these tests and called the real API.

This PR adds `-m 'not live'` to `addopts`, so the default run deselects
them. `pytest -m live <file>` still selects them (a later `-m` replaces
this one).

Part of #4783

## Type of Change

- [x] 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
- [ ] Code refactoring (no functional changes)

## Changes Made

- `pyproject.toml`: `addopts = "-v --tb=short -m 'not live'"`, with a
three-line comment saying why and how to opt in.
- `tests/test_realignment_live_multi_turn.py`: the module-wide `live`
marker is replaced by `@pytest.mark.live` on the eight tests that need a
provider key, so the offline
`test_classify_auth_mode_routes_payg_vs_oauth` keeps running by default.
- `tests/test_live_marker_default_deselect.py`: collection-only test
that the default run deselects live tests, keeps the offline one, and
that `-m live` selects them again (fails against the old `addopts`).

## Testing

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

This changes pytest configuration only, so no new test is added; the
proof is the collection result below (`--collect-only`, with a dummy
`ANTHROPIC_API_KEY`, nothing contacted).

### Test Output

```text
Before (origin/main pyproject.toml):
pytest tests/test_thinking_signature_scope_live.py tests/test_realignment_live_multi_turn.py --collect-only -q
15 tests collected

After (this branch):
same command                           -> 1 test collected (the offline test_classify_auth_mode_routes_payg_vs_oauth), 14 deselected
same command with -m live              -> 14 tests collected
```

## Real Behavior Proof

- Environment: Windows 11, Python 3.12, pytest 9.2.0,
`ANTHROPIC_API_KEY=sk-ant-dummy-collect-only` in the environment.
- Exact command / steps: `python -m pytest
tests/test_thinking_signature_scope_live.py
tests/test_realignment_live_multi_turn.py --collect-only -q`, with the
pyproject from `origin/main` and with this branch's, and once more with
`-m live`.
- Observed result: before, 15 tests collected (they would run and call
the API when a key is present); after, the 14 provider-calling tests are
deselected and the offline one is still collected; with `-m live`, 14
collected.
- Not tested: an actual live run (no provider key was used), and CI (the
CI workflows I read do not export a provider key to pytest, so this PR
is aimed at developer machines).

## Runtime Rollout Safety

- Rollout-managed feature(s): none; test configuration only.
- Minimum rollout channel: n/a
- Stable/default behavior changed: no for the library and proxy. The
default `pytest` run no longer collects tests marked `live`.
- Kill switch / disable path: run `pytest -m live ...` (or pass any `-m`
expression).
- 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
- [x] 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
- [ ] New and existing unit tests pass locally with my changes (the
whole suite was not run; see Testing)
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

- If a CI job runs `pytest -m live` deliberately it keeps working,
because the later `-m` wins. I did not find such a job.

AI assistance: this change and the runs above were done with Claude
(Sonnet 5.5), operated by me (HetCreep).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4786"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-authored-by: JerrettDavis <mxjerrett@gmail.com>
2026-11-16 19:48:28 -06:00

644 lines
28 KiB
TOML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
[build-system]
requires = ["maturin>=1.5,<2.0"]
build-backend = "maturin"
[project]
name = "headroom-ai"
version = "0.44.0"
description = "Compress tool outputs, logs, JSON and chat history before each LLM call. Fewer input tokens, same answers; in-process, no API key. Library, proxy and MCP server."
# PyPI renders this file; GitHub renders README.md. Keep the two in step on the
# install commands and the savings claim (README.md "Proof" is the source).
readme = "README-pypi.md"
license = "Apache-2.0"
requires-python = ">=3.11"
authors = [
{ name = "Headroom Contributors" }
]
maintainers = [
{ name = "Headroom Contributors" }
]
keywords = [
"llm",
"openai",
"anthropic",
"claude",
"gpt",
"gemini",
"token-cost",
"reduce-tokens",
"input-tokens",
"context-window",
"token-budget",
"tool-output",
"tool-results",
"chat-history",
"trim-messages",
"context-compression",
"prompt-compression",
"context-engineering",
"agents",
"coding-agents",
"mcp",
"proxy",
"fastapi",
"langchain",
"litellm",
]
classifiers = [
"Development Status :: 4 - Beta",
"Intended Audience :: Developers",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Programming Language :: Python :: 3.13",
"Programming Language :: Python :: 3.14",
"Topic :: Scientific/Engineering :: Artificial Intelligence",
"Topic :: Software Development :: Libraries :: Python Modules",
"Typing :: Typed",
]
dependencies = [
# Core: lightweight compression (SmartCrusher, ContentRouter, CCR, TOIN)
"tiktoken>=0.5.0", # Tokenizer for all compressors
"pydantic>=2.0.0", # Config and data models
# Model registry, pricing and non-core providers; all lazily imported and
# ImportError-guarded. 1.96.2 is the first litellm with prebuilt wheels for
# Python 3.11-3.14 on Linux, macOS and Windows: older releases either reject
# Python 3.14 (GH #956) or fall back to a Rust source build.
"litellm>=1.96.2,<2.0",
"click>=8.5.0", # CLI framework; PYSEC-2026-2132 fix (command injection in click.edit())
"rich>=13.0.0", # Rich terminal output
"opentelemetry-api>=1.45.2", # CVE-2026-114603 tracestate parsing; CVE-2026-126360 traceparent ReDoS
# AST-aware code slicing (CodeCompressor); binary wheel. 0.44.1 is excluded:
# that PyPI release was a compromised supply-chain build shipping an
# info-stealer `sg.exe` (Trojan:Win64/Lazy!MTB) alongside the real binary
# (GH #2332). The `!=` keeps every other release installable, including a
# future patched one.
"ast-grep-cli>=0.30.0,!=0.44.1",
"pyyaml>=6.0", # omp wrap: parse/merge omp's models.yml registry
"tomlkit>=0.15.2,<1.0", # Loss-minimizing Codex config recovery
# Verify upstream TLS through the OS trust store (macOS Keychain, Windows
# cert store), where IT installs corporate TLS-inspection roots (Zscaler,
# Netskope). Pure Python, no deps; the same library pip uses by default.
"truststore>=0.10.0",
# Not imported directly: huggingface-hub (via litellm -> tokenizers, so in
# every install) uses it for Hub downloads. Before 1.6.0 its worker threads
# could re-initialize or re-enter Python while the interpreter shut down
# after a download, crashing the process at exit (SIGSEGV in
# Py_InitializeEx, or a fatal TstateNULL error). Declared here rather than
# as a uv constraint so the floor reaches the published wheel's metadata
# and pip upgrades an older copy. Same platform marker as huggingface-hub's
# own hf-xet requirement, so it never installs where hf-xet would not.
"hf-xet>=1.6.0; platform_machine == 'AMD64' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'",
# Not imported directly: litellm, huggingface-hub and torch use it.
# CVE-2026-112907/112913/112940 are fixed in 4.2.1, but litellm 1.106 caps
# filelock <4, so without this floor pip picks that litellm and 3.32.7;
# with it pip takes litellm 1.103.7 (uv.lock has 1.101.0). Declared here so
# the floor reaches pip installs.
"filelock>=4.2.1",
]
[project.optional-dependencies]
# Proxy server (most common install: pip install headroom-ai[proxy])
proxy = [
"fastapi>=0.100.0",
"uvicorn>=0.23.0,<1.0",
# LiteLLM provider backends (e.g. openrouter) expect orjson at runtime but
# litellm only declares it under its own [proxy] extra (GH #2056).
"orjson>=3.9.14; platform_python_implementation != 'PyPy'",
"httpx[http2]>=0.24.0",
"openai>=2.14.0", # OpenAI API format support
# SDK 2 constructor-callback API (GH #2658). 2.2.0 fixes CVE-2026-59951
# and CVE-2026-116684/116685/116686, which affect 2.0.0-2.1.x.
"mcp>=2.2.0,<3.0.0", # MCP server (headroom_compress, retrieve, stats)
"magika>=0.6.0; python_version<'3.14' or sys_platform != 'darwin' or platform_machine != 'x86_64'", # ML detection needs ORT wheels
"zstandard>=0.20.0", # Decompress zstd request bodies (Codex, etc.)
"websockets>=13.0", # WebSocket proxy for /v1/responses (Codex gpt-5.4+)
"python-socks[asyncio]>=2.7.1", # SOCKS support when websockets discovers a system proxy
# ORT <1.24 deadlocks in Rust fastembed instead of returning an init error.
# Python 3.10 keeps Python-only ORT and bypasses native detection. Intel
# macOS also needs older ORT because newer releases have no x86_64 wheels.
# No ORT wheel exists for Intel macOS Python 3.14+; optional ML detection
# falls back to heuristics there. Transitive ORT backends use the same gate.
"onnxruntime>=1.24.0; python_version>='3.11' and (sys_platform != 'darwin' or platform_machine != 'x86_64')",
"onnxruntime>=1.16.0,<1.24.0; python_version<'3.11' or (python_version<'3.14' and sys_platform == 'darwin' and platform_machine == 'x86_64')",
"transformers>=5.5.0,<6.0", # Tokenizer only (for Kompress)
# File watcher for live code graph reindexing (--code-graph). watchdog 6.0.0
# publishes no macOS wheel for Python 3.14, so installing it there needs a C
# compiler. The watcher is optional and skips itself when watchdog is absent.
"watchdog>=4.0.0; sys_platform != 'darwin' or python_version < '3.14'",
"sqlite-vec>=0.1.9", # Vector index for memory (--memory). Lightweight, no torch.
]
# Production ASGI/WSGI server — Unix-only (gunicorn does not support Windows).
# Kept separate from [proxy] so that dev, CI, and Windows users are not forced
# to install a non-functional package. Production deployments should use:
# pip install headroom-ai[proxy,proxy-prod]
proxy-prod = [
"headroom-ai[proxy]",
"gunicorn>=21.0.0; sys_platform != 'win32'",
]
# Google Vertex through the LiteLLM translation backend
# (`--backend vertex` / `vertex_ai` / `litellm-vertex`), which imports `vertexai`.
# Kept separate from [proxy] for the same reason as proxy-prod: this pulls
# google-cloud-aiplatform and its transitive tree (~175MB installed), and the
# proxy's *native* Vertex passthrough routes
# (/v1/projects/.../locations/.../publishers/...) do not need it at all. Only
# the LiteLLM backend does. Install with:
# pip install headroom-ai[proxy,vertex]
vertex = [
"google-cloud-aiplatform>=1.38",
]
# AST-based code compression (tree-sitter)
# tree-sitter-language-pack >=1.0 removed the bundled tree-sitter package and
# switched to an incompatible internal node API (.kind vs .type, callable
# root_node, etc.). Pin to <1.0.0 so that tree-sitter>=0.25.2 is pulled in
# as a transitive dependency and the existing code_compressor.py node-walk
# logic continues to work. See issue #1216.
code = [
"tree-sitter-language-pack>=0.10.0,<1.0",
"tree-sitter>=0.26.0,<0.27",
]
# ML-based compression with Kompress (ModernBERT).
# (The legacy [llmlingua] extra was removed in 0.9.x — no live code path used it.
# Use [ml] for the supported ML compression dependencies.)
ml = [
# PyTorch does not publish wheels for macOS 15 x86_64 at this floor, which
# makes `headroom-ai[all]` unsatisfiable on Intel Macs (#1931).
"torch>=2.12.1; sys_platform != 'darwin' or platform_machine != 'x86_64'",
"transformers>=5.5.0,<6.0",
# transformers >= 5.x requires huggingface-hub >= 1.5.0,< 3.0; pinning
# the floor here prevents Kompress from silently falling back to
# "unavailable" when a sibling install (e.g. `pip install
# strands-agents`) drags huggingface-hub backwards.
"huggingface-hub>=1.5.0,<3.0",
]
# Memory system (hierarchical memory with vector search).
# Uses the pure-Python sqlite-vec backend by default (VectorBackend.AUTO ->
# SQLITE_VEC), so no C++ toolchain is required. The optional HNSW backend lives
# in the [vector] extra below; installing it here would make `[all]` (which pulls
# [memory]) fail on any machine without a compiler — see #1368.
memory = [
"sqlite-vec>=0.1.9",
"sentence-transformers>=2.2.0,<7.0; sys_platform != 'darwin' or platform_machine != 'x86_64'",
]
# Optional HNSW vector backend. Needs a C++ toolchain to build hnswlib, so it is
# kept out of [memory] and [all]; opt in with `pip install headroom-ai[vector]`
# and select it via MemoryConfig(vector_backend=VectorBackend.HNSW). The default
# sqlite-vec backend needs no compiler.
vector = [
"hnswlib>=0.8.0",
]
# Qdrant + Neo4j memory backend helpers
memory-stack = [
"mem0ai>=2.0.18,<3.0",
"qdrant-client>=1.9.0,<2.0",
"neo4j>=5.20.0,<7.0",
]
# Apple-Silicon GPU (MPS) offload for the memory embedder. Opt in at runtime with
# HEADROOM_EMBEDDER_RUNTIME=pytorch_mps. macOS-only; intentionally excluded from [all].
pytorch-mps = [
"torch>=2.12.1; sys_platform == 'darwin'",
"sentence-transformers>=2.2.0; sys_platform == 'darwin'",
]
# Semantic relevance scoring with embeddings.
# Uses `fastembed` (BAAI/bge-small-en-v1.5 by default — 33M params,
# 384 dims, ~67 MB quantized ONNX). The Rust scorer (`fastembed` crate)
# loads the same pinned Qdrant/bge-small-en-v1.5-onnx-Q snapshot, so both
# languages run the same ONNX file; tests/parity/fixtures/embedding/
# bounds the remaining ONNX Runtime drift. Replaced sentence-transformers in
# Stage 3c.1 — fastembed is faster (~2-3x), smaller (no torch
# dependency), and outranks all-MiniLM-L6-v2 on MTEB by ~6 points.
# >=0.6.0 for `specific_model_path`, which the pinned-snapshot load needs.
relevance = [
"fastembed>=0.6.0; python_version<'3.14' or sys_platform != 'darwin' or platform_machine != 'x86_64'",
"numpy>=1.24.0",
]
# Image compression (ML-based routing + OCR)
#
# OCR backend uses ONNX Runtime regardless of Python version. The
# rapidocr ecosystem split into two flavors after 1.4.x:
# * rapidocr-onnxruntime 1.4.x — bundled-ORT package, capped at
# Python <3.13 by its requires-python metadata. Drop-in for our
# existing v1 tuple-shaped API call.
# * rapidocr 3.x — engine-agnostic core, supports Python 3.13+.
# Returns a RapidOCROutput dataclass (txts, scores, boxes, ...).
# Needs `onnxruntime` installed separately to use the ORT backend.
#
# `headroom/image/compressor.py` adapts both API shapes at runtime via
# a try/except cascade. See issue #372 for context.
image = [
"pillow>=12.3.0", # PYSEC-2026-2253..2257; uv.lock takes 13.0.0 (see override-dependencies)
"sentencepiece>=0.1.99", # Required by SigLIP tokenizer (SiglipTokenizer)
# Python 3.6–3.12: keep the proven ORT-bundled package directly.
# ~15 MB ONNX models auto-downloaded on first use.
"rapidocr-onnxruntime>=1.4.0,<2; python_version<'3.13'",
# Python 3.13+: rapidocr-onnxruntime is unavailable (its wheels
# declare requires-python<3.13). Use the successor `rapidocr` 3.x
# core + `onnxruntime` engine; same ORT backend, just split into
# two packages. Total install size and inference speed unchanged.
"rapidocr>=3.0,<4; python_version>='3.13' and (python_version<'3.14' or sys_platform != 'darwin' or platform_machine != 'x86_64')",
"onnxruntime>=1.7,<2; python_version>='3.13' and (python_version<'3.14' or sys_platform != 'darwin' or platform_machine != 'x86_64')",
]
# Report generation
reports = [
"jinja2>=3.0.0",
]
# Binary spreadsheet ingestion (.xlsx / .xls -> tabular text)
spreadsheet = [
"openpyxl>=3.1.0", # .xlsx
"xlrd>=2.0.1", # legacy .xls
]
# OpenTelemetry metrics export
otel = [
"opentelemetry-sdk>=1.24.0",
"opentelemetry-exporter-otlp-proto-http>=1.24.0",
]
# any-llm multi-provider backend (requires Python 3.11+)
anyllm = [
"any-llm-sdk>=1.0.0; python_version >= '3.11'",
]
# LangChain integration
langchain = [
"langchain-core>=1.3.3,<4.0",
"langchain-openai>=1.1.14,<2.0",
]
# LangGraph integration (headroom.integrations.langchain.langgraph)
# LangGraph ships its own langchain-core pin, so this only adds langgraph itself
# on top of the langchain extra.
langgraph = [
"langchain-core>=1.3.3,<4.0",
"langchain-openai>=1.1.14,<2.0",
"langgraph>=1.2.14,<2.0",
]
# Agno agent framework integration
agno = [
"agno>=1.0.0",
]
# AWS Strands Agents SDK integration
strands = [
"strands-agents>=0.1.0",
]
# CrewAI: no extra on purpose. The integration only wraps CrewAI tools, so it
# uses whatever CrewAI the user already has (`pip install headroom-ai crewai`).
# An extra here would put CrewAI's own dependency tree (including chromadb,
# which has unpatched server-side CVEs) into our lockfile and security alerts.
# AutoGen agent framework integration
autogen = [
"autogen-agentchat>=0.7",
]
# MCP server for Claude Code integration
mcp = [
"mcp>=2.2.0,<3.0.0",
"httpx>=0.24.0",
"starlette>=0.27.0",
"uvicorn>=0.23.0,<1.0",
]
# Voice filler detection
voice = [
"onnxruntime>=1.24.0; python_version>='3.11' and (sys_platform != 'darwin' or platform_machine != 'x86_64')",
"onnxruntime>=1.16.0,<1.24.0; python_version<'3.11' or (python_version<'3.14' and sys_platform == 'darwin' and platform_machine == 'x86_64')",
"transformers>=5.5.0,<6.0",
"torch>=2.12.1; sys_platform != 'darwin' or platform_machine != 'x86_64'",
]
# Voice training (includes voice deps + training extras)
voice-train = [
"headroom-ai[voice]",
"datasets>=5.0.1",
"accelerate>=0.20.0",
]
# Evaluation framework
evals = [
"datasets>=5.0.1",
"sentence-transformers>=2.2.0,<7.0; sys_platform != 'darwin' or platform_machine != 'x86_64'",
"numpy>=1.24.0",
"scikit-learn>=1.3.0",
"anthropic>=0.18.0",
"openai>=1.0.0",
]
# AWS Bedrock backend
bedrock = [
# `aws login` (IAM Identity Provider / console-login, DPoP) requires
# boto3 >= 1.41.0 AND the AWS Common Runtime (CRT) per AWS docs
# ("Boto3 1.41.0 or later with CRT"). CRT is a separate install — pull it
# via the botocore [crt] extra (awscrt). Without it, resolving `aws login`
# credentials raises botocore's MissingDependencyException.
"boto3>=1.41.0",
"botocore[crt]>=1.41.0",
]
# State shared across replicas: CCR store (HEADROOM_CCR_BACKEND=redis) and
# session-aware /v1/compress (HEADROOM_COMPRESS_SESSION_STORE=redis://...).
redis = [
"redis>=5.0.0",
]
# System tray icon (opt-in: `headroom proxy --tray` / `headroom tray`; Windows first)
tray = [
"pystray>=0.19.5",
"pillow>=12.3.0",
]
# HTML content extraction
html = [
"trafilatura>=1.6.0",
]
# Development dependencies
dev = [
"pytest>=7.0.0",
"pytest-cov>=4.0.0",
"pytest-asyncio>=0.21.0",
"ruff==0.17.4",
"mypy>=1.0.0",
"pre-commit>=3.0.0",
"openai>=1.0.0",
"anthropic>=0.18.0",
"litellm>=1.96.2,<2.0", # see core deps note
"fastapi>=0.100.0",
"uvicorn>=0.23.0,<1.0",
# socks: test_upstream_guard proves a guarded upstream is refused on EVERY
# supported proxy transport. Without the extra, httpcore substitutes a stub
# AsyncSOCKSProxy that cannot be constructed, and the SOCKS case degrades to
# asserting on a type rather than a real pool.
"httpx[http2,socks]>=0.24.0",
"websockets>=13.0",
"opentelemetry-sdk>=1.24.0",
"opentelemetry-exporter-otlp-proto-http>=1.24.0",
"ollama>=0.4.0",
"langchain-ollama>=0.2.0",
"hnswlib>=0.8.0",
"sqlite-vec>=0.1.9",
"sentence-transformers>=2.2.0,<7.0",
"numpy>=1.24.0",
"openpyxl>=3.1.0", # exercises spreadsheet_ingest (.xlsx) in the test suite
"fakeredis[lua]>=2.20.0", # Redis-backed shared state, without a Redis server
"xlrd>=2.0.1", # exercises spreadsheet_ingest (.xls) in the test suite
"xlwt>=1.3.0", # writes the legacy .xls fixtures for spreadsheet_ingest tests
# test_upstream_guard builds a self-signed cert to prove the pinned connection
# still presents the original hostname for SNI and still verifies the cert.
# The floor in the security-pins block below is a *version* constraint on a
# transitive dep, not a guarantee it is installed -- CI had neither.
"cryptography>=50.0.0",
"respx>=0.20.0", # HTTP mock transport for passthrough handler tests
]
# All optional dependencies for the default CLI/proxy feature set.
# PyTorch-backed features stay opt-in because Linux PyPI wheels include CUDA
# runtime packages and dependency metadata cannot detect installed hardware.
#
# The EleutherAI lm-evaluation-harness is intentionally not exposed as a
# project extra. Headroom invokes it as an external subprocess
# (`python -m lm_eval`), and the harness currently pulls sqlitedict
# CVE-2024-35515 with no upstream fix. Keeping it out of locked project extras
# prevents repository scanners from flagging production installs; researchers
# who need standard accuracy benchmarks can install `lm-eval[api]` in their
# benchmark environment separately.
all = [
"headroom-ai[proxy,code,relevance,image,reports,otel,html,mcp,spreadsheet]",
]
# Lean: a proxy with ALL torch-free capability — for running Headroom in a
# constrained or low-resource environment and offloading heavy ML elsewhere.
#
# This is a DEPENDENCY PROFILE. It provides no isolation, no confinement and
# no privilege reduction of any kind. It was previously named `sandbox`, which
# invited exactly that assumption; `sandbox` is retained below as a
# deprecated alias for one release so existing installs keep resolving.
#
# = [all] MINUS:
# - image (SigLIP/OCR — excluded by request)
# - ml (torch — the PyTorch Kompress backend; ONNX path in [proxy] still
# runs Kompress locally with no torch, or offload it entirely via
# HEADROOM_KOMPRESS_ENDPOINT)
# - voice (excluded by request)
# - memory + evals (both pull sentence-transformers -> torch, i.e. the very
# ML weight a sandbox avoids; evals is a dev/test harness, not a
# runtime feature). Opt back in explicitly if you accept torch:
# pip install headroom-ai[lean,memory]
#
# Everything kept here is torch-free: code-aware compression (tree-sitter),
# embedding relevance (fastembed), HTML/spreadsheet ingestion, reports, OTel.
lean = [
"headroom-ai[proxy,code,relevance,reports,otel,html,mcp,spreadsheet]",
]
# Deprecated alias for `lean`, kept for one release. The name implied an
# isolation guarantee the extra never provided. Remove after 0.39.x.
sandbox = [
"headroom-ai[lean]",
]
[project.scripts]
headroom = "headroom.cli.main:main"
headroom-cache-ttl = "headroom.cache.ttl_estimator:main"
[project.urls]
Homepage = "https://docs.headroomlabs.ai"
Documentation = "https://docs.headroomlabs.ai/docs"
Repository = "https://github.com/headroomlabs-ai/headroom"
Issues = "https://github.com/headroomlabs-ai/headroom/issues"
Changelog = "https://github.com/headroomlabs-ai/headroom/blob/main/CHANGELOG.md"
# llms.txt convention (llmstxt.org) — point AI agents / LLM crawlers
# at the auto-generated docs index so they can resolve install paths
# and entry points without a follow-up fetch.
"AI / LLM Index" = "https://docs.headroomlabs.ai/llms.txt"
# Maturin builds a single wheel containing both the Python source under
# `headroom/` AND the compiled Rust extension `headroom/_core.so` (cdylib
# from `crates/headroom-py`). One `pip install headroom-ai` ships everything
# atomically — no separate `headroom-core-py` package, no chicken-and-egg,
# no PIP_FIND_LINKS plumbing. Phase A0's runtime fail-loud check still
# exists but only fires if someone forces an sdist install on a platform
# without a wheel and the rust toolchain isn't available to compile it.
# Constrain transitive dependencies that have CVEs requiring minimum versions.
# These packages don't appear as direct headroom deps but are pulled in
# transitively; the floor pins below ensure uv resolves to patched versions.
[tool.uv]
constraint-dependencies = [
# PYSEC-2026-4320 — remove distrusted root certificates from the CA bundle.
"certifi>=2026.10.19",
# GHSA-5239-wwwm-4pmq (Low) — transitive via rich; fix at 2.20.0
"pygments>=2.20.0",
# GHSA-4xgf-cpjx-pc3j (Medium) — transitive via mcp; fix at 2.14.2
"pydantic-settings>=2.14.2",
# GHSA-hmq2-w58f-27jc, GHSA-jm78-9fvv-mhgr, GHSA-wvpp-8hx9-p66j (High),
# GHSA-hh9p-6wh2-4mfc (Medium) + earlier ones — transitive via agno.
# 3.1.58 clears every GitPython advisory published to date; the previous
# 3.1.50 floor resolved to 3.1.54, which nine open advisories still cover.
"gitpython>=3.1.58",
# GHSA-f4xh-w4cj-qxq8 (High) — transitive via langchain-core; fix at 0.8.18
"langsmith>=0.9.0",
# CVE-2026-49825 (High, XSS) — transitive via lxml[html-clean]; fix at 0.4.5
"lxml-html-clean>=0.4.5",
# CVE-2026-5241 (High) — direct optional dep for proxy/ml/voice; fix at 5.5.0
"transformers>=5.5.0",
# GHSA-xmj3-9gf7-h52w — Windows wheel namespace path traversal.
"setuptools>=84.1.0",
# CVE-2026-112940/112913/112907. The patched series requires Python 3.11;
# Python 3.10 retains the legacy locked version; it is not remediated by this marker.
"filelock>=4.2.1; python_version >= '3.11'",
# PYSEC-2026-3545/3546/3547 — transitive HTTP/WebSocket parser fixes;
# CVE-2026-111063/111064, GHSA-2g87-pp6c-29x5; fix at 3.14.4
"aiohttp>=3.14.4",
# PYSEC-2026-3552/3553/3554 — PKCS#7 and certificate verification fixes
"cryptography>=50.0.0",
]
# Pin the project's package index to public PyPI. Without this, `uv lock`
# inherits the developer's user-level `~/.config/uv/uv.toml` index
# setting — including private/internal mirrors like
# `pypi.netflix.net/simple` — and bakes those URLs into uv.lock, which
# then breaks CI on every public runner that can't reach the mirror.
# Declaring the index in pyproject.toml makes the project authoritative
# regardless of who runs `uv lock`.
# fastembed (0.9.0, latest) caps pillow <13, but Pillow 13.0.0 is the only fix
# for ten decoder CVEs on untrusted images (CVE-2026-112395, -112895 and
# others), which headroom.image opens. fastembed imports PIL only for its image models;
# Headroom uses its text models. Checked: fastembed text embedding and
# Headroom's image tests pass on Pillow 13. This applies to uv.lock (CI,
# release images, uv installs); the package metadata keeps pillow>=12.3.0 so
# `pip install headroom-ai[all]` still resolves against fastembed's cap; on
# that Pillow, headroom/image/decoder_guard.py forwards images undecoded.
# Drop this override once fastembed allows Pillow 13.
override-dependencies = [
"pillow>=13.0.0",
]
[[tool.uv.index]]
name = "pypi"
url = "https://pypi.org/simple/"
default = true
[tool.maturin]
# Where the Python package lives. With `python-source = "."` and the
# package directory `headroom/` at repo root, maturin includes every file
# under `headroom/` in the wheel — that picks up the dashboard HTML
# templates and bundled YAML configs. `LICENSE` and `NOTICE` are listed
# explicitly because maturin sdists do not get the package-directory
# treatment wheels do, and PEP 639 auto-discovery emits both files into
# `License-File:` metadata — PyPI rejects sdists whose declared license
# files are missing from the tarball with `400 License-File X does not
# exist in distribution file`.
include = [
{ path = "LICENSE", format = "sdist" },
{ path = "NOTICE", format = "sdist" },
]
python-source = "."
module-name = "headroom._core"
# The cdylib source lives under `crates/headroom-py`. Maturin invokes
# `cargo build` with this manifest to produce `_core.cdylib`, then injects
# the resulting `.so` into the wheel at `headroom/_core.so`.
manifest-path = "crates/headroom-py/Cargo.toml"
features = ["extension-module"]
# Forbid building without the cdylib feature — bare `cargo build` won't
# produce a usable Python extension. Maturin's default `bindings` is "pyo3"
# which is correct here (see `crates/headroom-py/src/`).
bindings = "pyo3"
[tool.ruff]
# Kept at py310 until the py311 idiom migration lands (UP017/UP036/UP041/UP042
# touch ~200 sites); requires-python is 3.11.
target-version = "py310"
line-length = 100
[tool.ruff.lint]
select = [
"E", # pycodestyle errors
"W", # pycodestyle warnings
"F", # pyflakes
"I", # isort
"B", # flake8-bugbear
"C4", # flake8-comprehensions
"UP", # pyupgrade
]
ignore = [
"E501", # line too long (handled by formatter)
"B008", # do not perform function calls in argument defaults
"B905", # zip without strict parameter
]
[tool.ruff.lint.isort]
known-first-party = ["headroom"]
[tool.ruff.format]
quote-style = "double"
indent-style = "space"
[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
ignore_missing_imports = true
# Per-module overrides for modules with dynamic typing patterns
[[tool.mypy.overrides]]
module = [
"headroom.proxy.server",
"headroom.proxy.cost",
"headroom.proxy.prometheus_metrics",
"headroom.proxy.semantic_cache",
"headroom.proxy.rate_limiter",
"headroom.proxy.request_logger",
"headroom.proxy.helpers",
"headroom.integrations.langchain",
"headroom.integrations.mcp",
"headroom.ccr.mcp_server",
"headroom.relevance.embedding",
"headroom.reporting.generator",
]
disallow_untyped_defs = false
[[tool.mypy.overrides]]
module = [
"headroom.tokenizers.*",
"headroom.providers.litellm",
"headroom.providers.google",
]
disallow_untyped_defs = false
warn_return_any = false
# Handler mixins use self.* from HeadroomProxy via duck typing — mypy can't resolve these
[[tool.mypy.overrides]]
module = ["headroom.proxy.handlers.*"]
disallow_untyped_defs = false
ignore_errors = true
# Ignore third-party stubs with syntax errors
[[tool.mypy.overrides]]
module = ["mlx.*"]
ignore_errors = true
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_functions = ["test_*"]
# "-m 'not live'": tests marked live call real provider APIs with the developer's
# keys, so they never run by default. Opt in with `pytest -m live <file>` (a later
# -m replaces this one).
addopts = "-v --tb=short -m 'not live'"
asyncio_mode = "auto"
filterwarnings = [
# pyo3 Unsendable parsers emit an unraisable warning when GC drops them on a
# test-teardown thread; this is a test-harness artifact, not a production issue
# (production threads are long-lived and drop their parsers on themselves).
"ignore::pytest.PytestUnraisableExceptionWarning",
]
markers = [
"slow: slow tests (model loads, large fixtures)",
"real_llm: tests that hit real LLM APIs; skipped unless explicitly enabled",
"live: opt-in multi-turn tests that hit real upstream APIs; require provider keys",
"proxy_dependency_gate: exercises ensure_proxy_dependencies() without mocking",
"proxy_port_preflight: exercises the proxy busy-port check against real sockets",
"windows_newline: newline-contract tests (#3698); also run on windows-latest in CI",
]
[tool.coverage.run]
source = ["headroom"]
branch = true
omit = [
"*/tests/*",
]
[tool.coverage.report]
exclude_lines = [
"pragma: no cover",
"def __repr__",
"raise NotImplementedError",
"if TYPE_CHECKING:",
"if __name__ == .__main__.:",
]