mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-11-22 15:10:00 +08:00
## 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>
644 lines
28 KiB
TOML
644 lines
28 KiB
TOML
[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__.:",
|
||
]
|