forked from HAL9000/cleveragents-core
117 lines
4.0 KiB
Markdown
117 lines
4.0 KiB
Markdown
# Skeleton Compressor
|
|
|
|
## Overview
|
|
|
|
The **Skeleton Compressor** produces a compressed representation of a
|
|
plan's accumulated context for propagation to child plans as inherited
|
|
context. Compression is governed by the `skeleton_ratio` budget
|
|
parameter set on a project's context policy.
|
|
|
|
The compressor lives in
|
|
`cleveragents.application.services.skeleton_compressor.SkeletonCompressorService`
|
|
and is registered in the DI container as `skeleton_compressor_service`.
|
|
|
|
## Skeleton Ratio
|
|
|
|
| Ratio | Meaning | Behaviour |
|
|
|------:|:--------|:----------|
|
|
| `0.0` | No compression | All fragments pass through unchanged. |
|
|
| `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. |
|
|
|
|
The ratio is validated to the closed interval `[0.0, 1.0]`. Values
|
|
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.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
|
|
|
|
Fragments are sorted by **relevance descending** with a stable
|
|
secondary sort on **fragment_id ascending**. This guarantees
|
|
deterministic output: identical inputs always produce identical
|
|
compressed payloads regardless of the order in which fragments
|
|
arrive.
|
|
|
|
## Compression Algorithm
|
|
|
|
1. Validate all inputs (ratio, fragment fields).
|
|
2. Compute `original_tokens` — sum of `token_count` across all
|
|
fragments.
|
|
3. Sort fragments by `(-relevance, fragment_id)`.
|
|
4. Compute a token budget: `budget = original_tokens * (1 - ratio)`.
|
|
5. Iterate sorted fragments, accumulating tokens until the budget is
|
|
exhausted.
|
|
6. Return the kept fragments and a `SkeletonMetadata` record.
|
|
|
|
## Metadata
|
|
|
|
Every compression pass produces a frozen `SkeletonMetadata`:
|
|
|
|
| Field | Type | Description |
|
|
|:------|:-----|:------------|
|
|
| `ratio` | `float` | The ratio applied. |
|
|
| `original_tokens` | `int` | Tokens before compression. |
|
|
| `compressed_tokens` | `int` | Tokens after compression. |
|
|
| `source_decision_ids` | `tuple[str, ...]` | Decision ULIDs included. |
|
|
|
|
The metadata is persisted on the `Plan` model via the
|
|
`skeleton_metadata` field, making compression auditable.
|
|
|
|
### Compression Summary
|
|
|
|
The metadata doubles as a compression summary: compare
|
|
`original_tokens` to `compressed_tokens` to see how much context was
|
|
removed. The summary is included in `plan status` CLI output under
|
|
the `skeleton` key.
|
|
|
|
## Example: Multi-Decision Plan
|
|
|
|
Consider a plan with three decision context fragments:
|
|
|
|
```text
|
|
Fragment A (relevance=0.9, tokens=400, decision=01HX...)
|
|
Fragment B (relevance=0.6, tokens=300, decision=01HY...)
|
|
Fragment C (relevance=0.3, tokens=300, decision=01HZ...)
|
|
```
|
|
|
|
With `skeleton_ratio = 0.5` the token budget is
|
|
`1000 * (1 - 0.5) = 500` tokens:
|
|
|
|
- Fragment A (400 tokens, cumulative 400) — kept.
|
|
- Fragment B (300 tokens, cumulative 700) — exceeds budget; skipped.
|
|
|
|
**Result:**
|
|
|
|
```text
|
|
Compressed fragments: [A]
|
|
original_tokens: 1000
|
|
compressed_tokens: 400
|
|
source_decision_ids: (01HX...)
|
|
```
|
|
|
|
## Integration
|
|
|
|
The skeleton output feeds into the **subplan context inheritance**
|
|
pipeline. When a parent plan spawns a child, the strategy coordinator
|
|
calls the compressor on the parent's accumulated context, stores the
|
|
resulting `SkeletonMetadata` on the child plan, and passes the
|
|
compressed fragments as the child's inherited context budget.
|
|
|
|
## CLI
|
|
|
|
The `--skeleton-ratio` flag on `agents project context set` sets the
|
|
ratio for a project's context policy. The `plan status` command
|
|
displays the compression summary when `skeleton_metadata` is present.
|