forked from cleveragents/cleveragents-core
eugen.thaci
f66fb5a19a
Align Unicode box-drawing blocks and related tables in specification.md, ADR-044/045/046, and reference pages for consistent MkDocs rendering. ISSUES CLOSED: #1171
131 lines
4.9 KiB
Markdown
131 lines
4.9 KiB
Markdown
# Context Strategy Registry
|
|
|
|
The Context Strategy Registry manages pluggable retrieval strategies for the
|
|
ACMS Context Assembly Pipeline. Strategies implement the `ContextStrategy`
|
|
protocol and are registered via TOML configuration or programmatic API.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
ContextRequest
|
|
┌─── StrategySelector ────┐
|
|
│ can_handle() polling │
|
|
└──────────┬──────────────┘
|
|
v
|
|
┌─── BudgetAllocator ─────┐
|
|
│ proportional alloc │
|
|
└──────────┬──────────────┘
|
|
v
|
|
┌─── StrategyExecutor ────┐
|
|
│ parallel w/ timeout │
|
|
│ circuit breaker │
|
|
└──────────┬──────────────┘
|
|
v
|
|
ContextFragment[]
|
|
```
|
|
|
|
## ContextStrategy Protocol
|
|
|
|
Every strategy implements:
|
|
|
|
| Member | Type | Description |
|
|
|--------|------|-------------|
|
|
| `name` | `property -> str` | Unique strategy name |
|
|
| `capabilities` | `property -> StrategyCapabilities` | Backend requirements and quality score |
|
|
| `can_handle(request, backends)` | `-> float` | 0.0-1.0 confidence for this request |
|
|
| `assemble(request, backends, budget, plan_context)` | `-> list[ContextFragment]` | Execute and return fragments; must respect budget |
|
|
| `explain()` | `-> str` | Human-readable description |
|
|
|
|
## StrategyCapabilities
|
|
|
|
| Field | Type | Default | Description |
|
|
|-------|------|---------|-------------|
|
|
| `uses_text` | `bool` | `False` | Requires TextBackend |
|
|
| `uses_vector` | `bool` | `False` | Requires VectorBackend |
|
|
| `uses_graph` | `bool` | `False` | Requires GraphBackend |
|
|
| `uses_temporal` | `bool` | `False` | Requires temporal/cold-tier data |
|
|
| `resource_types` | `tuple[str, ...]` | `()` | Supported resource types (empty = all) |
|
|
| `quality_score` | `float` | `0.5` | Intrinsic quality score (0.0-1.0) |
|
|
| `supports_depth_breadth` | `bool` | `False` | Supports depth/breadth projection |
|
|
| `supports_plan_hierarchy` | `bool` | `False` | Supports plan hierarchy traversal |
|
|
| `supports_temporal` | `bool` | `False` | Supports temporal archaeology queries |
|
|
|
|
## Built-in Strategies
|
|
|
|
| Strategy | Quality | Backends | Description |
|
|
|----------|---------|----------|-------------|
|
|
| `simple-keyword` | 0.3 | Text | Basic keyword/regex text search. Universal fallback. |
|
|
| `semantic-embedding` | 0.6 | Vector | Vector similarity search. |
|
|
| `breadth-depth-navigator` | 0.85 | Graph | Graph-aware UKO traversal. Primary code-aware strategy. |
|
|
| `arce` | 0.95 | All | Multi-modal ARCE pipeline. Highest quality. |
|
|
| `temporal-archaeology` | 0.5 | Graph + Cold | Historical pattern discovery. |
|
|
| `plan-decision-context` | 0.7 | Warm/Cold | Parent/ancestor plan context retrieval. |
|
|
|
|
Default enabled (spec `context.strategies.enabled`):
|
|
`["simple-keyword", "semantic-embedding", "breadth-depth-navigator"]`
|
|
|
|
## Configuration
|
|
|
|
### Global (config.toml)
|
|
|
|
```toml
|
|
[context.strategies]
|
|
enabled = ["simple-keyword", "semantic-embedding", "breadth-depth-navigator"]
|
|
|
|
[context.strategies.custom]
|
|
"my-strategy" = "my_package.strategies:MyStrategy"
|
|
```
|
|
|
|
### Per-strategy settings
|
|
|
|
| Key | Type | Default | Description |
|
|
|-----|------|---------|-------------|
|
|
| `timeout_seconds` | int | 30 | Per-strategy assembly timeout |
|
|
| `max_fragments` | int | 100 | Maximum fragments per call |
|
|
| `max_workers` | int | 4 | Parallel workers for executor |
|
|
| `circuit_breaker_threshold` | int | 3 | Failures before circuit opens |
|
|
| `enabled` | bool | `true` | Whether the strategy is active |
|
|
|
|
### Per-project overrides
|
|
|
|
Projects can override the global enabled list using:
|
|
|
|
```
|
|
agents project context set --strategy simple-keyword --strategy semantic-embedding
|
|
```
|
|
|
|
This replaces the global `context.strategies.enabled` list for that project.
|
|
|
|
## ContextStrategyResult
|
|
|
|
Output of a single strategy execution:
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `strategy_name` | `str` | Name of the producing strategy |
|
|
| `fragments` | `tuple[ContextFragment, ...]` | Deterministically ordered fragments |
|
|
| `total_fragments` | `int` | Total fragments before limits |
|
|
| `tokens_used` | `int` | Total tokens across fragments |
|
|
| `execution_time_ms` | `float` | Execution wall-clock time (ms) |
|
|
| `errors` | `tuple[str, ...]` | Error messages |
|
|
| `stats` | `dict[str, Any]` | Strategy-specific statistics |
|
|
|
|
Fragment ordering: `(relevance_score DESC, uko_node ASC)`.
|
|
|
|
## Registry Validation
|
|
|
|
The registry validates that:
|
|
|
|
1. Every enabled strategy is actually registered.
|
|
2. Every strategy declares at least one backend capability.
|
|
3. Every strategy declares supported resource types.
|
|
|
|
## Fallback Degradation Path
|
|
|
|
When backends are unavailable, the system degrades gracefully:
|
|
|
|
1. `arce` (requires all) → 2. `breadth-depth-navigator` (graph) →
|
|
3. `semantic-embedding` (vector) → 4. `simple-keyword` (text only)
|
|
|
|
This ensures context is always produced.
|