cleveragents-core/docs/modules/depth-reduction-compressor.md

Depth Reduction Compressor

Package: cleveragents.application.services.depth_reduction_compressor Introduced: v3.8.0 (issue #919)

The DepthReductionCompressor is the production ACMS skeleton compression stage. It compresses inherited parent context fragments by re-rendering them at lower UKO detail depths (overview levels 0–1), reducing token usage while preserving structural information for child plans.

---

Purpose

When a parent plan spawns a child plan, the parent's accumulated context fragments are passed as inherited context. Without compression, large parent contexts can exhaust the child plan's token budget before any new context is added.

The DepthReductionCompressor solves this by re-rendering inherited fragments at shallower detail depths (overview levels 0–1 in the UKO detail-level map), producing a compact structural summary rather than full source content.

---

How It Works

The compressor uses the UKO detail-level map chain to determine the appropriate overview depth for each fragment:

1. For each input fragment, look up the UKO node's detail-level map.
2. Re-render the fragment at depth 0 (module listing) or depth 1 (type signatures), whichever fits within the skeleton budget.
3. Return the re-rendered fragments as the compressed skeleton.

This is distinct from the SkeletonCompressorService (which drops lower-relevance fragments entirely) — DepthReductionCompressor keeps all fragments but reduces their verbosity.

---

Key Classes

DepthReductionCompressor

from cleveragents.application.services.depth_reduction_compressor import (
    DepthReductionCompressor,
)

compressor = DepthReductionCompressor(
    uko_detail_map=container.uko_detail_map(),
)

Constructor parameters:

Parameter	Type	Default	Description
uko_detail_map	UKODetailLevelMap	required	UKO detail-level map for depth resolution
target_depths	tuple[int, ...]	(1, 0)	Depth levels to try, in order (highest first)

Methods:

Method	Returns	Description
compress(fragments, skeleton_budget)	tuple[ContextFragment, ...]	Re-render fragments at overview depths to fit within skeleton_budget tokens

---

DepthReductionResult

Frozen dataclass returned by compress():

Field	Type	Description
fragments	tuple[ContextFragment, ...]	Re-rendered fragments
original_tokens	int	Total tokens before compression
compressed_tokens	int	Total tokens after compression
depth_reductions	dict[str, int]	Fragment ID → new depth for each reduced fragment

---

Usage Example

from cleveragents.application.services.depth_reduction_compressor import (
    DepthReductionCompressor,
)
from cleveragents.domain.models.core.context_fragment import (
    ContextBudget,
    ContextFragment,
    FragmentProvenance,
)

# Create compressor (typically obtained from DI container)
compressor = DepthReductionCompressor(uko_detail_map=uko_detail_map)

# Compress parent context for child plan inheritance
result = compressor.compress(
    fragments=parent_context.fragments,
    skeleton_budget=512,  # tokens available for inherited context
)

print(f"Compressed {result.original_tokens} → {result.compressed_tokens} tokens")
print(f"Depth reductions: {result.depth_reductions}")

# Use compressed fragments as child plan's inherited context
child_context = ContextPayload(
    plan_id=child_plan_id,
    fragments=result.fragments,
    ...
)

---

Pipeline Integration

The DepthReductionCompressor is registered as the builtin SkeletonCompressor in the ACMS pipeline (Phase 3 — Context Finalization). It replaces the previous identity-compression stub.

ACMSPipeline
  └── Phase 3: Context Finalization
        ├── PreambleGenerator (no-op stub)
        └── SkeletonCompressor ← DepthReductionCompressor (v3.8.0+)

The pipeline invokes compress() automatically when assembling context for child plans. You do not need to call it directly in most cases.

---

DI Container Registration

The compressor is registered as a singleton in the DI container:

from cleveragents.application.container import Container

container = Container()
compressor = container.skeleton_compressor()
# Returns the configured DepthReductionCompressor instance

---

Relationship to SkeletonCompressorService

	SkeletonCompressorService	DepthReductionCompressor
Strategy	Drop low-relevance fragments	Re-render all fragments at lower depth
Output	Subset of original fragments	All fragments, re-rendered
Token reduction	By fragment count	By content verbosity
Use case	Skeleton ratio budget enforcement	Child plan context inheritance
Introduced	v3.7.0	v3.8.0

Both components are part of the ACMS pipeline's Phase 3 skeleton compression stage. SkeletonCompressorService applies the skeleton_ratio budget policy; DepthReductionCompressor handles the actual re-rendering.

---

BDD Coverage

The depth reduction compressor is covered by BDD scenarios in features/acms_skeleton_compression.feature:

• Compressor output at depth 0 and depth 1
• Default pipeline wiring (compressor is the configured builtin)
• Token budget enforcement (compressed output fits within skeleton_budget)
• Depth reduction metadata (depth_reductions dict)

---

Related Documentation

• Skeleton Compressor — SkeletonCompressorService and skeleton ratio
• ACMS Pipeline — 10-component pipeline architecture
• ACMS Strategy Coordinator & Fusion Engine — Phase 1 and Phase 2
• UKO Runtime — UKO detail-level map