docs: session-4 documentation updates — CHANGELOG, Module Guides nav, ACMS skeleton context #4578
+2068
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,209 @@
|
||||
# ACMS Skeleton Context Inheritance
|
||||
|
||||
## Overview
|
||||
|
||||
When a parent plan spawns a child plan, the child plan starts with no
|
||||
accumulated context. Without inherited context, the child's actor must
|
||||
re-discover information the parent already gathered, wasting tokens and
|
||||
execution time.
|
||||
|
||||
**Skeleton context inheritance** solves this by compressing the parent
|
||||
plan's accumulated context fragments into a budget-bounded **skeleton**
|
||||
that is passed to the child plan's context assembly pipeline.
|
||||
|
||||
This feature was introduced in v3.8.1 (issue #3563).
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
Parent Plan
|
||||
├── ContextFragment (relevance=0.9, tokens=800)
|
||||
├── ContextFragment (relevance=0.7, tokens=600)
|
||||
└── ContextFragment (relevance=0.3, tokens=400)
|
||||
│
|
||||
│ 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
|
||||
└── skeleton_fragments — inherited from parent (compressed)
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
### `ContextAssemblyPipeline.assemble()`
|
||||
|
||||
```python
|
||||
from cleveragents.application.services.acms_pipeline import ContextAssemblyPipeline
|
||||
from cleveragents.domain.models.core.context_fragment import ContextFragment
|
||||
|
||||
pipeline = ContextAssemblyPipeline()
|
||||
payload = pipeline.assemble(
|
||||
plan_id="child-plan-id",
|
||||
fragments=child_fragments,
|
||||
budget=budget,
|
||||
strategy="relevance",
|
||||
# Skeleton inheritance parameters:
|
||||
skeleton_ratio=0.15, # fraction of budget for skeleton
|
||||
parent_fragments=parent_frags, # parent's accumulated fragments
|
||||
)
|
||||
|
||||
# Access inherited skeleton
|
||||
for frag in payload.skeleton_fragments:
|
||||
print(frag.uko_node, frag.token_count)
|
||||
```
|
||||
|
||||
**New parameters (v3.8.1+):**
|
||||
|
||||
| Parameter | Type | Default | Description |
|
||||
|-----------|------|---------|-------------|
|
||||
| `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.
|
||||
|
||||
> **Tip:** `skeleton_ratio=0.0` means `skeleton_budget = 0` (no inherited
|
||||
> skeleton). `skeleton_ratio=1.0` reserves the entire available budget
|
||||
> for inherited context.
|
||||
|
||||
### `ACMSPipeline.assemble()`
|
||||
|
||||
```python
|
||||
from cleveragents.application.services.acms_service import ACMSPipeline
|
||||
from cleveragents.application.services.acms_skeleton_compressor import (
|
||||
resolve_configured_skeleton_compressor,
|
||||
)
|
||||
from cleveragents.domain.models.core.context_fragment import ContextBudget
|
||||
|
||||
pipeline = ACMSPipeline(
|
||||
skeleton_compressor=resolve_configured_skeleton_compressor(),
|
||||
)
|
||||
|
||||
payload = pipeline.assemble(
|
||||
plan_id="child-plan-id",
|
||||
fragments=child_fragments,
|
||||
budget=ContextBudget(max_tokens=2048),
|
||||
strategy="relevance",
|
||||
skeleton_ratio=0.15,
|
||||
parent_fragments=parent_frags,
|
||||
)
|
||||
```
|
||||
|
||||
`ACMSPipeline` exposes the same parameters as `ContextAssemblyPipeline`, but it
|
||||
does not wire production defaults. Use it when you need to supply custom
|
||||
strategy selectors, budget allocators, or compressors (for example in tests or
|
||||
specialized automation). When invoking it directly, pass a skeleton compressor
|
||||
so the inheritance parameters behave the same way as the higher-level
|
||||
`ContextAssemblyPipeline`.
|
||||
|
||||
> **When to choose:** Prefer `ContextAssemblyPipeline` for production and CLI
|
||||
> usage. Reach for `ACMSPipeline` only when you need fine-grained control over
|
||||
> its dependencies — for example when you are composing a minimal pipeline in a
|
||||
> unit test or swapping in alternative strategy implementations.
|
||||
|
||||
### `ContextPayload.skeleton_fragments`
|
||||
|
||||
```python
|
||||
@dataclass(frozen=True)
|
||||
class ContextPayload:
|
||||
...
|
||||
skeleton_fragments: tuple[ContextFragment, ...] = ()
|
||||
```
|
||||
|
||||
Immutable tuple of compressed parent context fragments. Empty when no
|
||||
parent context was provided.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Default skeleton ratio
|
||||
|
||||
The default `skeleton_ratio` of `0.15` means the skeleton budget is 15%
|
||||
of the child plan's available token budget. For a 4096-token budget with
|
||||
512 reserved tokens, the skeleton budget is:
|
||||
|
||||
```
|
||||
skeleton_budget = (4096 - 512) * 0.15 = 537 tokens
|
||||
```
|
||||
|
||||
### Per-project override
|
||||
|
||||
Set a custom skeleton ratio for a project's context policy:
|
||||
|
||||
```bash
|
||||
agents project context set --skeleton-ratio 0.20
|
||||
```
|
||||
|
||||
This overrides the default for all child plans spawned within that project.
|
||||
|
||||
---
|
||||
|
||||
## Relationship to `SkeletonCompressorService`
|
||||
|
||||
The `SkeletonCompressorService` (registered in the DI container as
|
||||
`skeleton_compressor_service`) is the underlying service that performs
|
||||
the compression. The ACMS pipeline calls it internally during Phase 3
|
||||
(Context Finalization).
|
||||
|
||||
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
|
||||
|
||||
The `SubplanService.spawn()` method passes the parent plan's accumulated
|
||||
context as `parent_fragments` when assembling the child plan's initial
|
||||
context. This is the primary production path for skeleton inheritance.
|
||||
|
||||
```python
|
||||
# Conceptual — internal to SubplanService
|
||||
child_payload = pipeline.assemble(
|
||||
plan_id=child_plan_id,
|
||||
fragments=child_fragments,
|
||||
budget=child_budget,
|
||||
parent_fragments=parent_plan.accumulated_fragments,
|
||||
skeleton_ratio=project_context_policy.skeleton_ratio,
|
||||
)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **`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
|
||||
assembled fragments. If the same resource appears in both, it will be
|
||||
present twice. A deduplication pass is planned for a future milestone.
|
||||
@@ -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
|
||||
|
||||
|
||||
+16
-15
@@ -23,22 +23,23 @@ nav:
|
||||
- Configuration: api/config.md
|
||||
- AI Providers: api/providers.md
|
||||
- TUI: api/tui.md
|
||||
- Modules:
|
||||
- Shell Safety: modules/shell-safety.md
|
||||
- UKO Provenance Tracking: modules/uko-provenance.md
|
||||
- Invariant Reconciliation: modules/invariant-reconciliation.md
|
||||
- Development:
|
||||
- Agent System Specification: development/agent-system-specification.md
|
||||
- CI/CD Pipeline: development/ci-cd.md
|
||||
- Quality Automation: development/quality-automation.md
|
||||
- Testing Guide: development/testing.md
|
||||
- Review Playbook: development/review_playbook.md
|
||||
- Scale Testing: development/scale_testing.md
|
||||
- Ops Runbook: development/ops-runbook.md
|
||||
- System Watchdog: development/system-watchdog.md
|
||||
- Automation Tracking: development/automation-tracking.md
|
||||
- Custom Sandbox Strategy: development/custom_sandbox_strategy.md
|
||||
- Documentation Writer: development/docs-writer.md
|
||||
- Agent System Specification: development/agent-system-specification.md
|
||||
- CI/CD Pipeline: development/ci-cd.md
|
||||
- Quality Automation: development/quality-automation.md
|
||||
- Testing Guide: development/testing.md
|
||||
- Review Playbook: development/review_playbook.md
|
||||
- Scale Testing: development/scale_testing.md
|
||||
- Ops Runbook: development/ops-runbook.md
|
||||
- System Watchdog: development/system-watchdog.md
|
||||
- Automation Tracking: development/automation-tracking.md
|
||||
- Custom Sandbox Strategy: development/custom_sandbox_strategy.md
|
||||
- Documentation Writer: development/docs-writer.md
|
||||
- Module Guides:
|
||||
- Shell Safety: modules/shell-safety.md
|
||||
- UKO Provenance Tracking: modules/uko-provenance.md
|
||||
- Invariant Reconciliation: modules/invariant-reconciliation.md
|
||||
- ACMS Skeleton Context: modules/acms-skeleton-context.md
|
||||
- Implementation Timeline: timeline.md
|
||||
- FAQ: faq.md
|
||||
- Reference: reference/
|
||||
|
||||
Reference in New Issue
Block a user