mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
58555c5be0
## Description Follow-up to #2555. Documents the cold-prefix hook / reasoning-compaction / cache-TTL-learner flags (what to set for what, and whether each can be on by default), and makes two small safety fixes so the learning seam is production-ready and free when off. ## Type of Change - [x] Documentation update - [x] Performance improvement (learning seam is now free when disabled) ## Changes Made - **docs/content/docs/configuration.mdx** — env-var table rows for `HEADROOM_THINKING_COMPACT` (+`_KEEP_LAST`), `HEADROOM_COLD_RECOMPACT`, `HEADROOM_DEDUPE`, `HEADROOM_CACHE_TTL_LEARN`, `HEADROOM_KOMPRESS_ENDPOINT`, plus a **Cold-prefix hook & reasoning compaction** section: what to set for what, how cold detection reads the real TTL (CC config vs learned), and a per-flag "can this be on by default?" analysis. - **docs/content/docs/cache-optimization.mdx** — a cold-prefix recompaction section linking to the flags. - **headroom/cache/ttl_observations.py** — the observation log is now size-bounded (single-backup rotation) and respects `HEADROOM_STATELESS`. - **headroom/proxy/handlers/openai.py** — the extra `classify_cache_miss` attribution is gated behind `observations_enabled()` so it costs nothing when learning is off. Everything remains **off by default**. ## Testing - [x] Linting passes (`ruff check`) - [x] Type checking passes (`mypy`) - [x] Manual testing performed (module self-check) ### Test Output ```text $ ruff check headroom/cache/ttl_observations.py headroom/proxy/handlers/openai.py All checks passed! $ mypy headroom/cache/ttl_observations.py headroom/proxy/handlers/openai.py Success: no issues found in 2 source files $ python headroom/cache/ttl_observations.py ttl_observations self-check OK ``` ## Real Behavior Proof - Environment: local repo, Python 3.12 venv. - Exact command / steps: ran the module self-check (covers gated-off no-write, gated-on write, learned-table read with model→provider fallback) and ruff+mypy. - Observed result: self-check passes; when `HEADROOM_CACHE_TTL_LEARN` is unset no file is written; when `HEADROOM_STATELESS` is truthy no file is written; the observation log rotates to `.1` past the size cap. - Not tested: live multi-turn provider run (unchanged from #2555, which carried the live Kimi/CC proofs); docs render is Markdown/MDX only. ## 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 - [x] My changes generate no new warnings - [x] New and existing checks pass locally with my changes - [x] I did **not** edit `CHANGELOG.md` ## Additional Notes - Default-on stance (in the docs): `THINKING_COMPACT` stays opt-in (rewrites model inputs); `COLD_RECOMPACT` is a candidate to default for Claude Code once TTL detection is field-validated; `CACHE_TTL_LEARN` is the safest to default on (observation-only, bounded, stateless-aware) — kept opt-in for now. |
||
|---|---|---|
| .. | ||
| app | ||
| components | ||
| content/docs | ||
| lib | ||
| overrides | ||
| screenshots | ||
| .gitignore | ||
| bun.lock | ||
| claude-code-bedrock-headroom.md | ||
| next.config.mjs | ||
| observability.md | ||
| package-lock.json | ||
| package.json | ||
| platform-feature-matrix.json | ||
| platform-stabilization.md | ||
| postcss.config.mjs | ||
| proxy.ts | ||
| README.md | ||
| rtk-architecture.md | ||
| source.config.ts | ||
| tsconfig.json | ||
| vercel.json | ||
docs
This is a Next.js application generated with Create Fumadocs.
Run development server:
npm run dev
# or
pnpm dev
# or
yarn dev
Open http://localhost:3000 with your browser to see the result.
Explore
In the project, you can see:
lib/source.ts: Code for content source adapter,loader()provides the interface to access your content.lib/layout.shared.tsx: Shared options for layouts, optional but preferred to keep.
| Route | Description |
|---|---|
app/(home) |
The route group for your landing page and other pages. |
app/docs |
The documentation layout and pages. |
app/api/search/route.ts |
The Route Handler for search. |
Fumadocs MDX
A source.config.ts config file has been included, you can customise different options like frontmatter schema.
Read the Introduction for further details.
Learn More
To learn more about Next.js and Fumadocs, take a look at the following resources:
- Next.js Documentation - learn about Next.js features and API.
- Learn Next.js - an interactive Next.js tutorial.
- Fumadocs - learn about Fumadocs