forked from cleveragents/cleveragents-core
Luis Mendes
34c2acc354
Implement the missing runtime logic for the ACMS context tier service. Previously only data models and manual promote()/demote()/evict_lru() methods existed. This commit adds: - Auto-promotion on access: get() now promotes fragments one tier up when access_count reaches the configurable promotion_threshold (default: 5 accesses). The access counter resets after each successful promotion so fragments must accumulate fresh accesses before the next tier transition. - Staleness enforcement: new enforce_staleness() method demotes hot fragments older than hot_ttl (default: 24h) to warm, and warm fragments older than warm_ttl to cold. A snapshot of existing warm-tier IDs prevents double-demotion in a single pass. - Budget enforcement on store and promote: store() and promote() now enforce TierBudget.max_tokens_hot by evicting LRU hot-tier fragments until the token budget is met. The eviction loop uses incremental token tracking to avoid recomputing the sum. - Event emission: Added TIER_PROMOTED, TIER_DEMOTED, TIER_EVICTED event types to EventType enum. All tier transitions emit DomainEvent instances through the optional EventBus. - Configuration: Added context_tier_promotion_threshold, context_tier_hot_ttl_hours, context_tier_warm_ttl_hours settings. The warm TTL setting also accepts the spec-defined env var CLEVERAGENTS_CTX_WARM_HOURS as an alias. - DI wiring: container.py now injects event_bus into context_tier_service. Review fixes applied (code review on PR #1150): - C1: Reset access_count to 0 after each auto-promotion to prevent chain promotion that bypassed the warm tier. - C2: Call _enforce_hot_budget() inside promote() warm-to-hot path so auto-promoted fragments respect the token budget. - H1: Corrected _enforce_hot_budget() docstring: actual complexity is O(n + n*k) not O(n), since min() scans remaining entries on each eviction. - M1: Added CLEVERAGENTS_CTX_WARM_HOURS as an additional env var alias for context_tier_warm_ttl_hours per specification line 30555. Review fixes applied (second code review on PR #1150): - B-CRIT-1: Fixed data loss in promote() warm-to-hot: emit TIER_PROMOTED before _enforce_hot_budget(), and if the promoted fragment is evicted by budget, restore it to the warm tier instead of silently losing it. - B-HIGH-1: Fixed self-eviction on store(): fragments whose token_count exceeds the entire hot-tier budget are now redirected to the warm tier with a warning log. - B-MED-1: Wrapped _emit_tier_event() in try/except so a failing event bus does not break tier operations (best-effort emission). - B-MED-2: Fixed event ordering so TIER_PROMOTED fires before any budget-triggered TIER_EVICTED events. - D-LOW-1: Fixed type hint in Robot helper (dict[str, Callable]). - D-LOW-2: Added __all__ export to context_tiers.py. - S-LOW-1: Added thread-safety docstring note to ContextTierService. Review fixes applied (third code review on PR #1150): - B-MED-1: Added TIER_DEMOTED event emission for oversized fragment redirect in store(), closing the observability gap where the only tier transition without event emission was the hot-to-warm redirect for fragments exceeding the entire hot-tier budget. - S-LOW-1: Added CLEVERAGENTS_CTX_HOT_HOURS as an additional env var alias for context_tier_hot_ttl_hours, for consistency with the warm-tier alias CLEVERAGENTS_CTX_WARM_HOURS. - S-LOW-2: Added docstring note to enforce_staleness() reconciling the hot-tier TTL with the specification statement that hot-tier retention is "Until resource removed" (TTL controls tier placement, not data retention). Review fixes applied (fourth code review on PR #1150): - B-HIGH-1: Reset access_count to 0 on demotion so that demoted fragments must accumulate fresh accesses before re-promotion. Without this reset, a previously popular fragment whose access_count already exceeded the promotion threshold would be re-promoted on the very next get() call, making staleness enforcement ineffective. Review fixes applied (freemo APPROVED review on PR #1150): - #1: Removed all # type: ignore annotations from test files. Fixed _EventCollector, _FailingBus, and _NullBus subscribe() signatures to use Callable[[DomainEvent], None] matching the EventBus protocol. Replaced dict-spread TieredFragment construction with explicit keyword arguments and post-construction assignment. - #2: Extracted runtime policy logic (enforce_staleness, _maybe_auto_promote, _re_fetch_after_promotion, _enforce_hot_budget, _emit_tier_event) into TierRuntimeMixin in tier_runtime.py to reduce context_tiers.py toward the 500-line guideline. - #3: Added fragment_id non-empty validation guard to promote() and demote() per CONTRIBUTING.md argument validation policy. - #8: Renamed _resolve to _re_fetch_after_promotion for clarity. Removed @tdd_expected_fail from TDD tests (Behave + Robot) as the bug is now fixed. All 3 TDD scenarios pass normally. Tests: 27 Behave scenarios (24 feature + 3 TDD), 4 Robot integration tests, 4 ASV benchmark suites. ISSUES CLOSED: #821
40 lines
2.0 KiB
Gherkin
40 lines
2.0 KiB
Gherkin
@tdd_bug @tdd_bug_821 @mock_only
|
|
Feature: TDD Bug #821 — context tier service has data models but no runtime logic
|
|
As a developer
|
|
I want to verify that ContextTierService automatically promotes, demotes,
|
|
and evicts fragments based on access patterns, staleness, and budget limits
|
|
So that the bug is captured and will be caught by a regression test
|
|
|
|
ContextTierService has well-defined data models for hot/warm/cold tiers
|
|
(ContextTier, TieredFragment, TierBudget) and manual promote()/demote()/
|
|
evict_lru() methods, but NO automatic runtime logic:
|
|
|
|
- get() touches access metadata but never auto-promotes a frequently
|
|
accessed cold/warm fragment to a higher tier.
|
|
- There is no staleness enforcement: no method checks last_accessed
|
|
timestamps and demotes stale hot fragments to warm/cold.
|
|
- store() does not enforce budget limits: storing beyond
|
|
max_tokens_hot does not trigger automatic eviction.
|
|
|
|
These tests assert the expected runtime behaviour and will FAIL until
|
|
the bug is fixed. The @tdd_expected_fail tag inverts the result so
|
|
CI passes.
|
|
|
|
Scenario: Promotion on repeated access moves fragment to a higher tier
|
|
Given a context tier service with default budget
|
|
And a fragment stored in the cold tier
|
|
When I access the fragment 5 times via get
|
|
Then the fragment should have been promoted to warm or hot tier
|
|
|
|
Scenario: Demotion on staleness moves fragment to a lower tier
|
|
Given a context tier service with default budget
|
|
And a fragment stored in the hot tier with a stale last_accessed timestamp
|
|
When I invoke the staleness enforcement runtime
|
|
Then the fragment should have been demoted to warm or cold tier
|
|
|
|
Scenario: Eviction on hot tier budget overflow removes oldest fragment
|
|
Given a context tier service with a small hot tier budget of 100 tokens
|
|
And the hot tier is filled to its token budget limit
|
|
When I store one more fragment in the hot tier
|
|
Then the oldest fragment should have been evicted from the hot tier
|