forked from cleveragents/cleveragents-core
freemo
6519f140a9
Implement hot/warm/cold context tiers with ContextTier, ActorRole, TieredFragment, TierBudget, ActorContextView, TierMetrics, and ScopedBackendView models. ContextTierService provides store/get, promotion/demotion with cold-tier summarisation hook, LRU eviction, per-actor filtered views (strategist/executor/reviewer), and project-scoped isolation via ScopedBackendView. Settings: context_max_tokens_hot, context_max_decisions_warm, context_max_decisions_cold. DI-wired as singleton context_tier_service. Includes Behave BDD scenarios (30), Robot Framework integration tests (7), ASV benchmarks (5 suites), and docs/reference/context_tiers.md. Closes #208
110 lines
2.9 KiB
Markdown
110 lines
2.9 KiB
Markdown
# Context Tiers
|
|
|
|
The ACMS Context Tier system manages context fragments across three storage
|
|
tiers — **hot**, **warm**, and **cold** — with per-actor visibility, project
|
|
scoping, and LRU eviction.
|
|
|
|
## Overview
|
|
|
|
| Tier | Backend | Latency | Capacity |
|
|
|--------|-------------|---------|------------------|
|
|
| Hot | In-memory | Low | Token-budget |
|
|
| Warm | SQLite stub | Medium | Decision-count |
|
|
| Cold | File stub | High | Decision-count |
|
|
|
|
## Models
|
|
|
|
### ContextTier
|
|
|
|
```python
|
|
class ContextTier(StrEnum):
|
|
HOT = "hot"
|
|
WARM = "warm"
|
|
COLD = "cold"
|
|
```
|
|
|
|
### ActorRole
|
|
|
|
```python
|
|
class ActorRole(StrEnum):
|
|
STRATEGIST = "strategist" # sees hot + warm + cold
|
|
EXECUTOR = "executor" # sees hot + warm
|
|
REVIEWER = "reviewer" # sees hot only
|
|
```
|
|
|
|
### TieredFragment
|
|
|
|
Extends the CRP `ContextFragment` concept with tier placement and access
|
|
tracking metadata:
|
|
|
|
- `fragment_id` — stable unique identifier
|
|
- `content` — rendered text content
|
|
- `tier` — current storage tier
|
|
- `resource_id` — originating resource
|
|
- `project_name` — project scope for isolation
|
|
- `token_count` — token count of content
|
|
- `last_accessed` — timestamp for LRU eviction
|
|
- `access_count` — access frequency counter
|
|
- `created_at` — creation timestamp
|
|
|
|
### TierBudget
|
|
|
|
Controls capacity per tier:
|
|
|
|
- `max_tokens_hot` (default: 8000)
|
|
- `max_decisions_warm` (default: 500)
|
|
- `max_decisions_cold` (default: 5000)
|
|
|
|
### ActorContextView
|
|
|
|
Per-actor filtered view configuration with role-based default tiers.
|
|
|
|
### TierMetrics
|
|
|
|
Hit/miss counters: `hot_hit_count`, `hot_miss_count`, `warm_hit_count`,
|
|
`warm_miss_count`, plus population counts per tier.
|
|
|
|
### ScopedBackendView
|
|
|
|
Project-scoped filter that enforces resource isolation. Fragments with
|
|
empty `project_name` are excluded by default.
|
|
|
|
## Service
|
|
|
|
### ContextTierService
|
|
|
|
```python
|
|
from cleveragents.application.services.context_tiers import ContextTierService
|
|
|
|
svc = ContextTierService()
|
|
svc.store(fragment)
|
|
svc.get("fragment-id")
|
|
svc.promote("fragment-id") # cold→warm or warm→hot
|
|
svc.demote("fragment-id") # hot→warm or warm→cold (with summarisation)
|
|
svc.evict_lru(ContextTier.HOT, count=5)
|
|
svc.get_for_actor(ActorRole.STRATEGIST, project_names=["my-project"])
|
|
svc.get_scoped_view(["my-project"])
|
|
svc.get_metrics()
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Environment variables (via `Settings`):
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `CLEVERAGENTS_CONTEXT_MAX_TOKENS_HOT` | 8000 | Max tokens in hot tier |
|
|
| `CLEVERAGENTS_CONTEXT_MAX_DECISIONS_WARM` | 500 | Max fragments in warm tier |
|
|
| `CLEVERAGENTS_CONTEXT_MAX_DECISIONS_COLD` | 5000 | Max fragments in cold tier |
|
|
|
|
## DI Container
|
|
|
|
The `ContextTierService` is registered as a singleton in the DI container:
|
|
|
|
```python
|
|
from cleveragents.application.container import get_container
|
|
|
|
container = get_container()
|
|
svc = container.context_tier_service()
|
|
```
|