From 58f75675186b8a4b562aead34b2b46da39b2d4cb Mon Sep 17 00:00:00 2001 From: "CleverThis hal9000@cleverthis.com" Date: Wed, 8 Apr 2026 19:55:23 +0000 Subject: [PATCH] docs: clarify skeleton ratio inheritance semantics Refs: #4578 --- docs/modules/acms-skeleton-context.md | 60 +++++++++++++++++---------- docs/reference/skeleton_compressor.md | 11 ++++- 2 files changed, 47 insertions(+), 24 deletions(-) diff --git a/docs/modules/acms-skeleton-context.md b/docs/modules/acms-skeleton-context.md index 5281e7e251..9d85ab0070 100644 --- a/docs/modules/acms-skeleton-context.md +++ b/docs/modules/acms-skeleton-context.md @@ -23,32 +23,35 @@ Parent Plan ├── ContextFragment (relevance=0.7, tokens=600) └── ContextFragment (relevance=0.3, tokens=400) │ - ▼ SkeletonCompressor - │ skeleton_ratio=0.15 - │ skeleton_budget = available_tokens * 0.15 - │ - ▼ Compressed skeleton (top-relevance, budget-bounded) + │ ContextAssemblyPipeline (default skeleton_ratio = 0.15) + │ skeleton_budget = int(budget.available_tokens * 0.15) + ▼ + SkeletonCompressor (DepthReductionCompressor) + │ receives parent_fragments + skeleton_budget tokens + ▼ + Compressed skeleton (top-relevance, budget-bounded) │ Child Plan ContextPayload - ├── fragments — child's own assembled context + ├── fragments — child's own assembled context └── skeleton_fragments — inherited from parent (compressed) ``` -The `SkeletonCompressor` sorts parent fragments by relevance descending -and greedily packs them into the skeleton budget. The compressed result -is returned in `ContextPayload.skeleton_fragments`. +The pipeline computes the skeleton budget from the child plan's +available tokens, then invokes the configured `SkeletonCompressor` to +fit the parent fragments within that budget. The resulting tuple is +returned in `ContextPayload.skeleton_fragments`. --- ## API -### `ACMSPipeline.assemble()` +### `ContextAssemblyPipeline.assemble()` ```python -from cleveragents.application.services.acms_service import ACMSPipeline +from cleveragents.application.services.acms_pipeline import ContextAssemblyPipeline from cleveragents.domain.models.core.context_fragment import ContextFragment -pipeline = ACMSPipeline() +pipeline = ContextAssemblyPipeline() payload = pipeline.assemble( plan_id="child-plan-id", fragments=child_fragments, @@ -68,17 +71,20 @@ for frag in payload.skeleton_fragments: | Parameter | Type | Default | Description | |-----------|------|---------|-------------| -| `skeleton_ratio` | `float` | `0.15` | Fraction of `budget.available_tokens` allocated to the skeleton | +| `skeleton_ratio` | `float` | `0.15` | Fraction of `budget.available_tokens` reserved for inheritance | | `parent_fragments` | `tuple[ContextFragment, ...] \| None` | `None` | Parent plan's accumulated fragments; `None` disables skeleton compression | When `parent_fragments` is `None`, `ContextPayload.skeleton_fragments` is an empty tuple and no compression is performed. -### `ContextAssemblyPipeline.assemble()` +> **Tip:** `skeleton_ratio=0.0` means `skeleton_budget = 0` (no inherited +> skeleton). `skeleton_ratio=1.0` reserves the entire available budget +> for inherited context. -The same `skeleton_ratio` and `parent_fragments` parameters are available -on `ContextAssemblyPipeline.assemble()` for consistency across the two -pipeline entry points. +### `ACMSPipeline.assemble()` + +The lower-level `ACMSPipeline` shares the same signature for callers who +work directly with the baseline pipeline implementation. ### `ContextPayload.skeleton_fragments` @@ -128,6 +134,16 @@ the compression. The ACMS pipeline calls it internally during Phase 3 For direct use of the compressor outside the pipeline, see [`docs/reference/skeleton_compressor.md`](../reference/skeleton_compressor.md). +> **Pipeline vs compressor semantics:** The pipeline's +> `skeleton_ratio` controls how much of the child plan's *available +> tokens* are earmarked for inheritance. The configured +> `SkeletonCompressor` then fits (or re-renders) the parent fragments to +> stay within that integer token budget. When you call +> `SkeletonCompressorService` directly, its own `skeleton_ratio` +> parameter instead controls how aggressively fragments are pruned +> relative to the parent's original token total. Both defaults are +> `0.15`, but they operate at different abstraction layers. + --- ## Subplan Spawning Integration @@ -151,11 +167,11 @@ child_payload = pipeline.assemble( ## Gotchas -- **`skeleton_ratio=0.0`** disables compression entirely — all parent - fragments pass through unchanged. Use this only when you want the full - parent context in the child (rare; usually exceeds budget). -- **`skeleton_ratio=1.0`** keeps only the single highest-relevance fragment. - Useful for very tight token budgets. +- **`skeleton_ratio=0.0`** reserves zero tokens for inheritance, so no + skeleton fragments are passed to the child. +- **`skeleton_ratio=1.0`** reserves the entire available budget for the + skeleton; the compressor still enforces the budget so child-specific + fragments may have limited space. - The skeleton budget is computed from `budget.available_tokens`, not `budget.max_tokens`. Reserved tokens are already excluded. - Skeleton fragments are **not** deduplicated against the child's own diff --git a/docs/reference/skeleton_compressor.md b/docs/reference/skeleton_compressor.md index 55120d4eaf..60e79a2b39 100644 --- a/docs/reference/skeleton_compressor.md +++ b/docs/reference/skeleton_compressor.md @@ -16,7 +16,7 @@ and is registered in the DI container as `skeleton_compressor_service`. | Ratio | Meaning | Behaviour | |------:|:--------|:----------| | `0.0` | No compression | All fragments pass through unchanged. | -| `0.3` | Default | ~70 % of tokens retained (top-relevance first). | +| `0.15` | Default | ~85 % of tokens retained (top-relevance first). | | `0.5` | Moderate | ~50 % of tokens retained. | | `0.8` | Heavy | ~20 % of tokens retained. | | `1.0` | Maximum | Only the single highest-relevance fragment is kept. | @@ -27,7 +27,14 @@ outside this range raise `ValueError`. ### Default Handling When a plan or project context policy does not set `skeleton_ratio`, -the service applies the constant `DEFAULT_SKELETON_RATIO = 0.3`. +the service applies the constant `DEFAULT_SKELETON_RATIO = 0.15`. + +> **Adapter note:** When invoked through `ContextAssemblyPipeline`, the +> pipeline converts its own `skeleton_ratio` into an integer +> `skeleton_budget` (token allotment) before calling the configured +> compressor. When you use `SkeletonCompressorService` directly, pass a +> ratio in `[0.0, 1.0]` to control how aggressively fragments are +> pruned relative to the original token total. ## Fragment Ordering