headroom/mkdocs.yml

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

137 lines
3.6 KiB
YAML
Raw Normal View History

site_name: Headroom
docs_dir: wiki
site_description: "The Context Optimization Layer for LLM Applications — compress everything your AI agent reads."
site_url: https://chopratejas.github.io/headroom
repo_url: https://github.com/chopratejas/headroom
repo_name: chopratejas/headroom
edit_uri: edit/main/docs/
theme:
name: material
custom_dir: docs/overrides
palette:
- media: "(prefers-color-scheme: light)"
scheme: default
primary: deep purple
accent: amber
toggle:
icon: material/brightness-7
name: Switch to dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: deep purple
accent: amber
toggle:
icon: material/brightness-4
name: Switch to light mode
font:
text: Inter
code: JetBrains Mono
features:
- content.code.copy
- content.code.annotate
- content.tabs.link
- navigation.instant
- navigation.instant.progress
- navigation.tabs
- navigation.tabs.sticky
- navigation.sections
- navigation.expand
- navigation.top
- navigation.indexes
- search.highlight
- search.suggest
- search.share
- toc.follow
- header.autohide
icon:
repo: fontawesome/brands/github
logo: material/layers-outline
plugins:
- search
extra_css:
- stylesheets/extra.css
markdown_extensions:
- admonition
- attr_list
- def_list
- md_in_html
- tables
- toc:
permalink: true
- pymdownx.highlight:
anchor_linenums: true
line_spans: __span
pygments_lang_class: true
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tabbed:
alternate_style: true
- pymdownx.details
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
- pymdownx.tasklist:
custom_checkbox: true
nav:
- Home: index.md
- Getting Started:
- Quickstart: quickstart.md
- Installation: getting-started.md
- Docker-Native Install: docker-install.md
- Persistent Installs: persistent-installs.md
- Configuration: configuration.md
- User Guide:
- Proxy Server: proxy.md
- Compression Pipeline: compression.md
- CCR (Lossless Retrieval): ccr.md
- Image Compression: image-compression.md
- Memory System: memory.md
- Shared Context: shared-context.md
- Failure Learning: learn.md
- Integrations:
- Overview: integration-guide.md
feat: add Vertex AI proxy routing (#793) ## Description Adds first-class GCP Vertex AI proxy routing for publisher REST endpoints so Vertex requests are forwarded to a configurable regional Vertex host instead of falling through to the generic OpenAI/Anthropic/Gemini passthrough selection. Fixes #792 ## Type of Change - [x] New feature (non-breaking change that adds functionality) - [x] Documentation update ## Changes Made - Added a `vertex` provider target with `VERTEX_TARGET_API_URL` and `--vertex-api-url` support. - Registered explicit Vertex publisher routes for Google `generateContent`, `streamGenerateContent`, `countTokens` and Anthropic publisher `rawPredict`, `streamRawPredict` passthrough. - Added startup banner/routing output for Vertex AI. - Added focused tests for provider target resolution, CLI/env config, banner output, and route delegation. - Added `wiki/vertex.md` with usage examples and Google Cloud source links. ## Sources - Vertex AI Gemini inference reference: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference - Google Cloud REST authentication: https://docs.cloud.google.com/docs/authentication/rest - Google Application Default Credentials: https://docs.cloud.google.com/docs/authentication/application-default-credentials ## Testing - [x] Linting passes (`python -m ruff check .`) - [x] New tests added for new functionality - [x] Focused unit tests pass - [ ] Full unit suite completed locally - [ ] Rust tests completed locally - [ ] Type checking passes locally ## Test Output ```text $ python -m ruff check . All checks passed! $ python -m pytest tests/test_provider_registry.py tests/test_provider_proxy_routes.py tests/test_cli_proxy_env.py tests/test_banner_upstream_targets.py -q 57 passed, 1 warning in 13.75s ``` Local limitations: - `python -m pytest tests scripts/tests -q` timed out after 1 hour on this Windows machine before completing. - `cargo test -p headroom-proxy --test integration_vertex_raw_predict` could not run because `cargo` is not installed on PATH in this environment. - The commit hook's `mypy` step fails locally on an existing Windows `fcntl` typing issue in `headroom/subscription/tracker.py`; `ruff`, `ruff-format`, and plugin-version hooks passed, and the commit was made with only `mypy` skipped. ## Checklist - [x] My code follows the project's style guidelines - [x] I have performed a self-review of my code - [x] I have made corresponding changes to the documentation - [x] I have added tests that prove the feature works - [ ] New and existing unit tests pass locally with my changes - [ ] I have updated the CHANGELOG.md if applicable
2026-06-10 01:05:30 -05:00
- Vertex AI: vertex.md
- LangChain: langchain.md
- Agno: agno.md
- Strands: strands.md
- MCP Tools: mcp.md
- How It Works:
- Architecture: ARCHITECTURE.md
- Transforms Pipeline: transforms.md
- Text Compression: text-compression.md
- LLMLingua: llmlingua.md
- Benchmarks:
- Accuracy: benchmarks.md
- Latency: LATENCY_BENCHMARKS.md
- Limitations: LIMITATIONS.md
- Reference:
- CLI: cli.md
- API: api.md
- SDK: sdk.md
feat: add differential network capture harness (#761) ## Summary - add a containerized differential network capture harness for Claude Code direct vs Claude Code routed through Headroom - capture both Headroom client-side traffic and Headroom upstream traffic with sanitized mitmproxy JSONL output - add `headroom capture network-diff` to compare captures and produce Markdown/JSON reports, including Anthropic tool-count/tool-byte deltas for deferred-tool investigations - add an on-demand GitHub Actions workflow for the harness; it only runs via `workflow_dispatch`, with live Claude Code/Anthropic capture gated on `ANTHROPIC_API_KEY` - document the workflow and ignore generated capture artifacts ## Validation - `C:\git\headroom\.venv\Scripts\python.exe -m pytest tests/test_network_diff_capture.py` - `ruff check headroom/capture headroom/cli/capture.py tests/test_network_diff_capture.py` - `ruff format --check headroom/capture headroom/cli/capture.py tests/test_network_diff_capture.py` - `C:\git\headroom\.venv\Scripts\python.exe -m mypy headroom/capture/network_diff.py headroom/cli/capture.py` - `docker compose -f docker/differential-network-capture/docker-compose.yml --profile run config` - `docker compose -f docker/differential-network-capture/docker-compose.yml --profile run build claude-direct` - `docker run --rm -e CLAUDE_COMMAND="claude --version" headroom-network-diff-claude-direct:latest` - parsed `.github/workflows/network-diff-capture.yml` with PyYAML and confirmed manual-only trigger Live Claude API capture was not run locally because `ANTHROPIC_API_KEY` is not set in this environment. The workflow can run it manually in GitHub Actions when that secret is present; otherwise it emits a visible skip warning and uploads a skipped artifact. ## Notes - Full pre-commit mypy still fails on unrelated Windows `fcntl` attributes in `headroom/subscription/tracker.py`; the feature commit skipped only that hook after narrow mypy passed for the new modules. - `tests/test_release_workflows.py` has two Windows-local failures because it shells out to a missing Unix/Rust command; unrelated workflow checks in that file passed before those failures. - Motivated by https://github.com/chopratejas/headroom/issues/746#issuecomment-4651276818 / Issue #746.
2026-06-09 00:18:31 -05:00
- Differential Network Capture: network-diff-capture.md
- Metrics & Observability: metrics.md
- Error Codes: errors.md
- Troubleshooting: troubleshooting.md
- Deployment:
- macOS LaunchAgent: macos-deployment.md
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/chopratejas/headroom
- icon: fontawesome/brands/python
link: https://pypi.org/project/headroom-ai/
- icon: fontawesome/brands/discord
link: https://discord.gg/yRmaUNpsPJ
generator: false