feat(acms): implement depth/breadth projection system and skeleton context propagation #544

Closed
opened 2026-03-04 01:01:02 +00:00 by freemo · 1 comment
Owner

Metadata

  • Commit Message: feat(acms): implement depth/breadth projection system
  • Branch: feature/m5-depth-breadth-projection
Field Value
Type Feature
Priority High
MoSCoW Should Have
Points 8
Milestone v3.4.0
Assignee freemo
Parent Epic #396 (Epic: ACMS Context Pipeline)
Depends On #538 (ContextFragment model), #189 (UKO ontology scaffolding), #194 (skeleton compressor)

Background

This issue covers two related spec features:

Depth/Breadth Projection System (§ Core Concepts > Depth/Breadth Projection, lines 25265-25300)

The spec defines a formal projection system over the UKO graph:

  • Breadth (0-N hops): how many relationship hops from the focal entity to include.
  • Depth (integer or named level): how much detail to include per entity.
  • DetailLevelMap: maps named depth levels to domain-specific semantics.
    • Code domain: MODULE_LISTINGCLASS_SIGNATURESMETHOD_BODIESFULL_SOURCE
    • Docs domain: TABLE_OF_CONTENTSSECTION_SUMMARIESFULL_CONTENT
    • Database domain: TABLE_LISTINGSCHEMA_DETAILSFULL_PROCEDURES

No implementation of the projection system or DetailLevelMap exists in the codebase.

Skeleton Context Propagation (§ Core Concepts > Hierarchical Plan Context, lines 25235-25263; § Architecture > ACMS, lines 43057-43110)

The SkeletonCompressor (#194) is implemented (226 lines), but the propagation workflow is missing: when a child plan is spawned, the parent's assembled context should be compressed into a skeleton and injected into the child's context budget. This involves:

  1. Calling the pipeline's SkeletonCompressor during subplan spawn
  2. Injecting the skeleton as inherited context with a configurable skeleton_ratio budget allocation
  3. Child plans start with parent context skeleton + their own fresh context

Acceptance Criteria

  1. DetailLevelMap enum/class defines named depth levels per domain (code, docs, database).
  2. ProjectionSpec dataclass captures (breadth: int, depth: int | str, domain: str).
  3. Projection logic retrieves UKO entities at the specified breadth/depth, returning ContextFragment results at the requested detail level.
  4. When a subplan is spawned, the parent plan's assembled context is compressed via SkeletonCompressor and injected into the child's initial context budget.
  5. skeleton_ratio config parameter controls what fraction of child's budget is reserved for inherited skeleton (default: 0.2 per spec).
  6. Child plan's context assembly starts with the skeleton as pre-populated fragments.

Subtasks

1. Design

  • Design DetailLevelMap and ProjectionSpec data models
  • Design integration point between subplan spawn and skeleton injection
  • Define skeleton_ratio config schema

2. Implementation

  • Implement DetailLevelMap with domain-specific depth semantics
  • Implement ProjectionSpec and projection logic
  • Wire projection into strategy implementations (strategies use ProjectionSpec to control retrieval depth)
  • Implement skeleton propagation in subplan spawn workflow
  • Honor skeleton_ratio budget parameter

3. Testing

  • Unit tests for DetailLevelMap resolution
  • Unit tests for projection at various breadth/depth combinations
  • Unit test: skeleton injection during subplan spawn
  • Test skeleton_ratio budget allocation
  • Integration test: parent plan → skeleton → child plan context

4. Documentation

  • Docstrings for projection system
  • Config documentation for skeleton_ratio

5. Integration

  • Wire projection into ACMS pipeline strategies
  • Wire skeleton propagation into SubplanActor (#198)

6. Observability

  • Log skeleton compression ratio and injected token count
  • Log projection parameters per strategy invocation

7. Security

  • Skeleton propagation must not leak context across plan isolation boundaries beyond what the parent explicitly shares

Definition of Done

  • All acceptance criteria met
  • All subtask checkboxes checked
  • Tests pass in CI
  • Code reviewed and approved
## Metadata - **Commit Message**: `feat(acms): implement depth/breadth projection system` - **Branch**: `feature/m5-depth-breadth-projection` | Field | Value | |-------|-------| | **Type** | Feature | | **Priority** | High | | **MoSCoW** | Should Have | | **Points** | 8 | | **Milestone** | v3.4.0 | | **Assignee** | freemo | | **Parent Epic** | #396 (Epic: ACMS Context Pipeline) | | **Depends On** | #538 (ContextFragment model), #189 (UKO ontology scaffolding), #194 (skeleton compressor) | ## Background This issue covers two related spec features: ### Depth/Breadth Projection System (§ Core Concepts > Depth/Breadth Projection, lines 25265-25300) The spec defines a formal projection system over the UKO graph: - **Breadth** (0-N hops): how many relationship hops from the focal entity to include. - **Depth** (integer or named level): how much detail to include per entity. - **DetailLevelMap**: maps named depth levels to domain-specific semantics. - Code domain: `MODULE_LISTING` → `CLASS_SIGNATURES` → `METHOD_BODIES` → `FULL_SOURCE` - Docs domain: `TABLE_OF_CONTENTS` → `SECTION_SUMMARIES` → `FULL_CONTENT` - Database domain: `TABLE_LISTING` → `SCHEMA_DETAILS` → `FULL_PROCEDURES` No implementation of the projection system or `DetailLevelMap` exists in the codebase. ### Skeleton Context Propagation (§ Core Concepts > Hierarchical Plan Context, lines 25235-25263; § Architecture > ACMS, lines 43057-43110) The SkeletonCompressor (#194) is implemented (226 lines), but the **propagation workflow** is missing: when a child plan is spawned, the parent's assembled context should be compressed into a skeleton and injected into the child's context budget. This involves: 1. Calling the pipeline's SkeletonCompressor during subplan spawn 2. Injecting the skeleton as inherited context with a configurable `skeleton_ratio` budget allocation 3. Child plans start with parent context skeleton + their own fresh context ## Acceptance Criteria 1. `DetailLevelMap` enum/class defines named depth levels per domain (code, docs, database). 2. `ProjectionSpec` dataclass captures `(breadth: int, depth: int | str, domain: str)`. 3. Projection logic retrieves UKO entities at the specified breadth/depth, returning `ContextFragment` results at the requested detail level. 4. When a subplan is spawned, the parent plan's assembled context is compressed via SkeletonCompressor and injected into the child's initial context budget. 5. `skeleton_ratio` config parameter controls what fraction of child's budget is reserved for inherited skeleton (default: 0.2 per spec). 6. Child plan's context assembly starts with the skeleton as pre-populated fragments. ## Subtasks ### 1. Design - [ ] Design `DetailLevelMap` and `ProjectionSpec` data models - [ ] Design integration point between subplan spawn and skeleton injection - [ ] Define `skeleton_ratio` config schema ### 2. Implementation - [ ] Implement `DetailLevelMap` with domain-specific depth semantics - [ ] Implement `ProjectionSpec` and projection logic - [ ] Wire projection into strategy implementations (strategies use ProjectionSpec to control retrieval depth) - [ ] Implement skeleton propagation in subplan spawn workflow - [ ] Honor `skeleton_ratio` budget parameter ### 3. Testing - [ ] Unit tests for DetailLevelMap resolution - [ ] Unit tests for projection at various breadth/depth combinations - [ ] Unit test: skeleton injection during subplan spawn - [ ] Test skeleton_ratio budget allocation - [ ] Integration test: parent plan → skeleton → child plan context ### 4. Documentation - [ ] Docstrings for projection system - [ ] Config documentation for skeleton_ratio ### 5. Integration - [ ] Wire projection into ACMS pipeline strategies - [ ] Wire skeleton propagation into SubplanActor (#198) ### 6. Observability - [ ] Log skeleton compression ratio and injected token count - [ ] Log projection parameters per strategy invocation ### 7. Security - [ ] Skeleton propagation must not leak context across plan isolation boundaries beyond what the parent explicitly shares ## Definition of Done - [ ] All acceptance criteria met - [ ] All subtask checkboxes checked - [ ] Tests pass in CI - [ ] Code reviewed and approved
freemo added this to the v3.2.0 milestone 2026-03-04 01:01:15 +00:00
freemo modified the milestone from v3.2.0 to v3.4.0 2026-03-04 01:09:35 +00:00
freemo self-assigned this 2026-03-04 01:41:12 +00:00
Author
Owner

Implementation Notes

PR: #603
Branch: feature/m5-depth-breadth-projection
Commit: 6a4529eafeat(acms): implement depth/breadth projection system

Source: src/cleveragents/application/services/depth_breadth_projection.py (530 lines)

Seven components implemented per spec §25265-25340 and §43057-43128:

  1. ProjectionSpec — Frozen Pydantic model capturing a projection request. Fields: focus (tuple of URIs, min 1), breadth (int ≥ 0, default 2), depth (int or named string, default 3), depth_gradient (bool, default True), domain (str, default "uko-code:"). Validates non-negative depth.

  2. ProjectedNode — Frozen Pydantic model for a materialized UKO node with uri, distance from focus, resolved_depth after gradient, and label.

  3. DepthBreadthProjector — Stateless BFS projector. Maintains a registry of DetailLevelMap instances per domain. project() does BFS from focus URIs over an adjacency list, computing resolved_depth = base - floor(base * distance / breadth) for each node. project_to_fragments() converts to ContextFragment with relevance inversely proportional to distance. Handles multiple focus items.

  4. PlanContextInheritance — Service implementing compute_child_context(). Computes child detail = parent avg + delta * max_detail_increase (capped at 9), child breadth = max(1, parent - delta), skeleton budget = child_budget * skeleton_ratio. Injects skeleton via duck-typed compressor. Returns ChildContextResult.

  5. ChildContextResult — Frozen model with request: ContextRequest, skeleton_fragments: tuple[ContextFragment, ...], parent_context_hash, skeleton_budget, depth_delta. Separates the request from skeleton data since ContextRequest has no metadata field.

  6. InheritanceConfig — Frozen config: skeleton_ratio=0.2, min_skeleton_tokens=32, max_detail_increase=3.

  7. Built-in presets: code_detail_map() (MODULE_LISTING=0 through FULL_SOURCE=9), docs_detail_map() (TITLE_ONLY=0 through FULL_CONTENT=10), database_detail_map() (TABLE_LISTING=0 through FULL_CATALOG=11).

Design Decisions

  • Used duck-typing (_SkeletonCompressorLike = Any) for the skeleton compressor to avoid circular imports between this module and acms_service.py
  • ChildContextResult wraps both request and skeleton data — the spec shows metadata being passed on ContextRequest but the model doesn't have a metadata field, so we return a richer result instead
  • Gradient formula: base - floor(base * distance / breadth) — at distance 0 gives full depth, at max distance gives 0, matching spec examples exactly
  • Relevance score: 1.0 - distance / (breadth + 1) — smooth decay from 1.0 at focus to near-0 at edge
  • Existing DetailLevelMap in crp.py is reused (not duplicated)

Test Coverage

  • 27 Behave scenarios (features/depth_breadth_projection.feature): model creation/validation, BFS traversal at breadth 0/1/2, gradient vs uniform depth, named depth resolution, multi-focus, fragment conversion, preset maps, inheritance computation, skeleton injection/skip, error cases
  • 9 Robot Framework tests (robot/depth_breadth_projection.robot): end-to-end component verification
  • ASV benchmarks (benchmarks/depth_breadth_projection_bench.py): latency for spec creation, node creation, small/medium graph projection, fragment conversion, inheritance

Verification

Check Result
nox -s lint 0 issues
nox -s typecheck 0 errors (pyright strict)
nox -s unit_tests 8551 scenarios, 0 failures
nox -s integration_tests 1212 tests, 0 failures
nox -s coverage_report 97.0% (≥97% threshold)
## Implementation Notes **PR**: #603 **Branch**: `feature/m5-depth-breadth-projection` **Commit**: `6a4529ea` — `feat(acms): implement depth/breadth projection system` ### Source: `src/cleveragents/application/services/depth_breadth_projection.py` (530 lines) Seven components implemented per spec §25265-25340 and §43057-43128: 1. **`ProjectionSpec`** — Frozen Pydantic model capturing a projection request. Fields: `focus` (tuple of URIs, min 1), `breadth` (int ≥ 0, default 2), `depth` (int or named string, default 3), `depth_gradient` (bool, default True), `domain` (str, default "uko-code:"). Validates non-negative depth. 2. **`ProjectedNode`** — Frozen Pydantic model for a materialized UKO node with `uri`, `distance` from focus, `resolved_depth` after gradient, and `label`. 3. **`DepthBreadthProjector`** — Stateless BFS projector. Maintains a registry of `DetailLevelMap` instances per domain. `project()` does BFS from focus URIs over an adjacency list, computing `resolved_depth = base - floor(base * distance / breadth)` for each node. `project_to_fragments()` converts to `ContextFragment` with relevance inversely proportional to distance. Handles multiple focus items. 4. **`PlanContextInheritance`** — Service implementing `compute_child_context()`. Computes child detail = parent avg + delta * max_detail_increase (capped at 9), child breadth = max(1, parent - delta), skeleton budget = child_budget * skeleton_ratio. Injects skeleton via duck-typed compressor. Returns `ChildContextResult`. 5. **`ChildContextResult`** — Frozen model with `request: ContextRequest`, `skeleton_fragments: tuple[ContextFragment, ...]`, `parent_context_hash`, `skeleton_budget`, `depth_delta`. Separates the request from skeleton data since `ContextRequest` has no `metadata` field. 6. **`InheritanceConfig`** — Frozen config: `skeleton_ratio=0.2`, `min_skeleton_tokens=32`, `max_detail_increase=3`. 7. **Built-in presets**: `code_detail_map()` (MODULE_LISTING=0 through FULL_SOURCE=9), `docs_detail_map()` (TITLE_ONLY=0 through FULL_CONTENT=10), `database_detail_map()` (TABLE_LISTING=0 through FULL_CATALOG=11). ### Design Decisions - Used duck-typing (`_SkeletonCompressorLike = Any`) for the skeleton compressor to avoid circular imports between this module and `acms_service.py` - `ChildContextResult` wraps both request and skeleton data — the spec shows metadata being passed on `ContextRequest` but the model doesn't have a metadata field, so we return a richer result instead - Gradient formula: `base - floor(base * distance / breadth)` — at distance 0 gives full depth, at max distance gives 0, matching spec examples exactly - Relevance score: `1.0 - distance / (breadth + 1)` — smooth decay from 1.0 at focus to near-0 at edge - Existing `DetailLevelMap` in `crp.py` is reused (not duplicated) ### Test Coverage - **27 Behave scenarios** (`features/depth_breadth_projection.feature`): model creation/validation, BFS traversal at breadth 0/1/2, gradient vs uniform depth, named depth resolution, multi-focus, fragment conversion, preset maps, inheritance computation, skeleton injection/skip, error cases - **9 Robot Framework tests** (`robot/depth_breadth_projection.robot`): end-to-end component verification - **ASV benchmarks** (`benchmarks/depth_breadth_projection_bench.py`): latency for spec creation, node creation, small/medium graph projection, fragment conversion, inheritance ### Verification | Check | Result | |-------|--------| | `nox -s lint` | ✅ 0 issues | | `nox -s typecheck` | ✅ 0 errors (pyright strict) | | `nox -s unit_tests` | ✅ 8551 scenarios, 0 failures | | `nox -s integration_tests` | ✅ 1212 tests, 0 failures | | `nox -s coverage_report` | ✅ 97.0% (≥97% threshold) |
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#396 Epic: ACMS Context Pipeline
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#544
No description provided.