cleveragents/cleveragents-core

Fork 3

refactor(acms): unify duplicate ContextFragment / ContextBudget / FragmentProvenance model hierarchies #569

New issue

Closed

opened 2026-03-04 22:10:28 +00:00 by hamza.khyari · 2 comments

hamza.khyari commented

2026-03-04 22:10:28 +00:00

Member

Metadata

Commit Message: refactor(acms): unify ContextFragment model hierarchies by extending CRP base types
Branch: refactor/unify-context-fragment-models

Problem

The codebase has two parallel definitions of ContextFragment, ContextBudget, and FragmentProvenance that were created independently on different branches and merged without reconciliation:

Type	Core (`domain/models/core/context_fragment.py`)	CRP (`domain/models/acms/crp.py`)
`ContextFragment`	`frozen=True`, has `fragment_id`, `tier`, `created_at`, `max_length=1M`, `metadata: dict[str, str]`	Mutable, no `fragment_id`/`tier`/`created_at`, `metadata: dict[str, Any]`, no size limits
`ContextBudget`	`frozen=True`, defaults `max_tokens=4096`, `reserved < max` (strict)	Mutable, `max_tokens` required, `reserved <= max`
`FragmentProvenance`	`frozen=True`, has `resource_type`	Mutable, has `strategy` instead

Both core/__init__.py and acms/__init__.py export identically-named but incompatible classes, creating a type-safety hazard.

Current usage

Pipeline (acms_service.py): imports core types exclusively
CLI simulation (project_context.py): imports CRP types exclusively, builds AssembledContext with CRP ContextFragment
No cross-contamination yet — but project_context.py:287 explicitly says "When the full ACMS pipeline is wired, this will delegate to the live pipeline instead", at which point the type mismatch becomes a runtime bug

Additional duplication

Core has ContextPayload; CRP has AssembledContext — same concept, different names and field sets
ContextRequest, AssembledContext, DetailLevelMap exist only in CRP and are spec-mandated types the pipeline needs

Impact on protocol signatures

The ACMS pipeline has 16 documented Known Limitations, roughly half of which exist because the pipeline uses dict[str, Any] instead of ContextRequest, and tuple[ContextFragment, ...] instead of AssembledContext. These divergences are a direct consequence of the model split.

Proposed Approach: Extend CRP Types

Core types extend CRP types via Pydantic v2 inheritance. No file merging, no re-exports.

# core/context_fragment.py
from cleveragents.domain.models.acms.crp import (
    ContextFragment as CRPContextFragment,
    FragmentProvenance as CRPFragmentProvenance,
)

class FragmentProvenance(CRPFragmentProvenance, frozen=True):
    resource_type: str = "unknown"

class ContextFragment(CRPContextFragment, frozen=True):
    fragment_id: str = Field(default_factory=lambda: str(ULID()))
    tier: Literal["hot", "warm", "cold"] = "warm"
    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
    provenance: FragmentProvenance  # override with extended type

Why extend instead of refactor

No breakage — CRP types stay untouched, existing consumers keep working
isinstance compatibility — isinstance(core_fragment, CRPContextFragment) returns True, so the CLI can pass fragments to the pipeline without conversion
Smaller diff — only core/context_fragment.py changes its base classes
Clean ownership — CRP owns the spec shape, core owns the operational extensions
Pydantic v2 supports this — frozen=True child of mutable parent is a verified, supported pattern

Caveat

Core will import from acms.crp (inverted dependency direction). This is defensible since ContextFragment is an ACMS spec concept. If needed later, the CRP base types can be moved to a shared location without changing the inheritance.

Acceptance Criteria

Core ContextFragment extends CRP ContextFragment — isinstance check passes for both
Core FragmentProvenance extends CRP FragmentProvenance — adds resource_type, keeps strategy
Core ContextBudget extends CRP ContextBudget with frozen=True and operational defaults
ContextPayload extends CRP AssembledContext with payload_id, plan_id, assembled_at
Pipeline protocol signatures updated to use ContextRequest (from CRP) where dict[str, Any] is currently used
project_context.py can pass CRP fragments to pipeline without conversion
All existing tests pass (pipeline BDD, CRP model BDD, Robot, ASV)
Known Limitations table in acms.md updated — rows eliminated where divergences are resolved

Subtasks

Refactor core/context_fragment.py to extend CRP base types
Update acms_service.py protocol signatures to use ContextRequest
Verify isinstance compatibility across both hierarchies
Update acms.md Known Limitations table
Coordinate with #538 (ScoredFragment can extend ContextFragment)
Run full nox validation

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line of the commit message
matches the Commit Message in Metadata exactly, followed by a blank line,
then additional lines providing relevant details about the implementation.
The commit is pushed to the remote on the branch matching the Branch in
Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and
merged before this issue is marked done.

Notes

Ticket #538 (assigned to @freemo) says "the codebase has no ContextFragment" — that is outdated; there are now two. This ticket should be completed before or coordinated with #538.
CRP types in acms/crp.py remain the spec-aligned canonical base; core types are frozen operational extensions.

## Metadata - **Commit Message**: `refactor(acms): unify ContextFragment model hierarchies by extending CRP base types` - **Branch**: `refactor/unify-context-fragment-models` ## Problem The codebase has **two parallel definitions** of `ContextFragment`, `ContextBudget`, and `FragmentProvenance` that were created independently on different branches and merged without reconciliation: | Type | Core (`domain/models/core/context_fragment.py`) | CRP (`domain/models/acms/crp.py`) | |------|------|------| | `ContextFragment` | `frozen=True`, has `fragment_id`, `tier`, `created_at`, `max_length=1M`, `metadata: dict[str, str]` | Mutable, no `fragment_id`/`tier`/`created_at`, `metadata: dict[str, Any]`, no size limits | | `ContextBudget` | `frozen=True`, defaults `max_tokens=4096`, `reserved < max` (strict) | Mutable, `max_tokens` required, `reserved <= max` | | `FragmentProvenance` | `frozen=True`, has `resource_type` | Mutable, has `strategy` instead | Both `core/__init__.py` and `acms/__init__.py` export identically-named but **incompatible** classes, creating a type-safety hazard. ### Current usage - **Pipeline** (`acms_service.py`): imports core types exclusively - **CLI simulation** (`project_context.py`): imports CRP types exclusively, builds `AssembledContext` with CRP `ContextFragment` - **No cross-contamination yet** — but `project_context.py:287` explicitly says "When the full ACMS pipeline is wired, this will delegate to the live pipeline instead", at which point the type mismatch becomes a runtime bug ### Additional duplication - Core has `ContextPayload`; CRP has `AssembledContext` — same concept, different names and field sets - `ContextRequest`, `AssembledContext`, `DetailLevelMap` exist only in CRP and are spec-mandated types the pipeline needs ### Impact on protocol signatures The ACMS pipeline has 16 documented Known Limitations, roughly half of which exist because the pipeline uses `dict[str, Any]` instead of `ContextRequest`, and `tuple[ContextFragment, ...]` instead of `AssembledContext`. These divergences are a direct consequence of the model split. ## Proposed Approach: Extend CRP Types Core types extend CRP types via Pydantic v2 inheritance. No file merging, no re-exports. ```python # core/context_fragment.py from cleveragents.domain.models.acms.crp import ( ContextFragment as CRPContextFragment, FragmentProvenance as CRPFragmentProvenance, ) class FragmentProvenance(CRPFragmentProvenance, frozen=True): resource_type: str = "unknown" class ContextFragment(CRPContextFragment, frozen=True): fragment_id: str = Field(default_factory=lambda: str(ULID())) tier: Literal["hot", "warm", "cold"] = "warm" created_at: datetime = Field(default_factory=lambda: datetime.now(UTC)) provenance: FragmentProvenance # override with extended type ``` ### Why extend instead of refactor - **No breakage** — CRP types stay untouched, existing consumers keep working - **`isinstance` compatibility** — `isinstance(core_fragment, CRPContextFragment)` returns `True`, so the CLI can pass fragments to the pipeline without conversion - **Smaller diff** — only `core/context_fragment.py` changes its base classes - **Clean ownership** — CRP owns the spec shape, core owns the operational extensions - **Pydantic v2 supports this** — `frozen=True` child of mutable parent is a verified, supported pattern ### Caveat Core will import from `acms.crp` (inverted dependency direction). This is defensible since `ContextFragment` is an ACMS spec concept. If needed later, the CRP base types can be moved to a shared location without changing the inheritance. ## Acceptance Criteria 1. Core `ContextFragment` extends CRP `ContextFragment` — `isinstance` check passes for both 2. Core `FragmentProvenance` extends CRP `FragmentProvenance` — adds `resource_type`, keeps `strategy` 3. Core `ContextBudget` extends CRP `ContextBudget` with `frozen=True` and operational defaults 4. `ContextPayload` extends CRP `AssembledContext` with `payload_id`, `plan_id`, `assembled_at` 5. Pipeline protocol signatures updated to use `ContextRequest` (from CRP) where `dict[str, Any]` is currently used 6. `project_context.py` can pass CRP fragments to pipeline without conversion 7. All existing tests pass (pipeline BDD, CRP model BDD, Robot, ASV) 8. Known Limitations table in `acms.md` updated — rows eliminated where divergences are resolved ## Subtasks - [ ] Refactor `core/context_fragment.py` to extend CRP base types - [ ] Update `acms_service.py` protocol signatures to use `ContextRequest` - [ ] Verify `isinstance` compatibility across both hierarchies - [ ] Update `acms.md` Known Limitations table - [ ] Coordinate with #538 (`ScoredFragment` can extend `ContextFragment`) - [ ] Run full `nox` validation ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the **first line** of the commit message matches the Commit Message in Metadata exactly, followed by a blank line, then additional lines providing relevant details about the implementation. - The commit is pushed to the remote on the branch matching the **Branch** in Metadata exactly. - The commit is submitted as a **pull request** to `master`, reviewed, and **merged** before this issue is marked done. ## Notes - Ticket #538 (assigned to @freemo) says "the codebase has no ContextFragment" — that is outdated; there are now two. This ticket should be completed before or coordinated with #538. - CRP types in `acms/crp.py` remain the spec-aligned canonical base; core types are frozen operational extensions.

hamza.khyari added this to the v3.4.0 milestone