forked from HAL9000/cleveragents-core
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user