cleveragents-core/docs/reference/crp.md

# Context Request Protocol (CRP) Models

The CRP provides the structured vocabulary through which actors (via
skills) declare what information they need, at what level of detail,
and with what scope, while they are reasoning.

## Core Data Types

### DetailLevelMap

Maps named detail levels to integer depths for a UKO domain.
Inheritance allows child maps to include all entries from their parent
map and insert additional levels at any integer position.

| Field       | Type                    | Description                                     |
|-------------|-------------------------|-------------------------------------------------|
| `domain`    | `str`                   | UKO namespace (e.g., `"uko-code:"`, `"uko-py:"`)|
| `parent`    | `DetailLevelMap \| None`| Parent map to inherit from                      |
| `levels`    | `dict[str, int]`        | Named level -> integer depth mapping            |
| `max_depth` | `int`                   | Maximum meaningful depth for this domain (>= 0) |

**Methods:**

- `resolve(depth: int | str) -> int` -- Resolve a named level or integer to
  an integer depth.  Integer depths are clamped to `max_depth`.
- `register(name: str, value: int) -> None` -- Register a custom detail level.
- `effective_levels() -> dict[str, int]` -- Return the full merged level map
  including inherited entries.

### ContextRequest

A structured request for context, issued by an actor or skill via the
CRP.  Each request triggers a context assembly cycle in the ACMS
pipeline.

| Field                  | Type             | Default              | Description                                 |
|------------------------|------------------|----------------------|---------------------------------------------|
| `query`                | `str \| None`    | `None`               | Natural language query                      |
| `entities`             | `list[str]`      | `[]`                 | Named entities to focus on                  |
| `uko_types`            | `list[str]`      | `[]`                 | UKO types to filter                         |
| `focus`                | `list[str]`      | `[]`                 | URIs or identifiers to focus on             |
| `breadth`              | `int`            | `2`                  | Dependency hops outward (>= 0)              |
| `depth`                | `int \| str`     | `3`                  | Detail depth -- integer or named level      |
| `depth_gradient`       | `bool`           | `True`               | Items closer to focus get more detail       |
| `temporal`             | `TemporalScope`  | `CURRENT`            | Temporal scope for retrieval                |
| `max_tokens`           | `int \| None`    | `None`               | Maximum token budget (>= 0)                 |
| `preferred_strategies` | `list[str]`      | `[]`                 | Preferred context strategies                |
| `required_backends`    | `list[str]`      | `[]`                 | Required data backends                      |
| `priority`             | `float`          | `0.5`                | 0.0 = background, 1.0 = critical           |
| `purpose`              | `str`            | `""`                 | Why this context is needed                  |

### ContextFragment

The atomic unit of context returned by strategies and consumed by the
Context Assembly Pipeline.

| Field             | Type                 | Description                         |
|-------------------|----------------------|-------------------------------------|
| `uko_node`        | `str`                | UKO URI of the source node          |
| `content`         | `str`                | Rendered text content               |
| `detail_depth`    | `int`                | Resolved integer depth (>= 0)      |
| `token_count`     | `int`                | Token count of content (>= 0)      |
| `relevance_score` | `float`              | 0.0 -- 1.0 relevance to request    |
| `provenance`      | `FragmentProvenance` | Trace back to resource + location   |
| `metadata`        | `dict[str, Any]`     | Strategy-specific metadata          |

### FragmentProvenance

Links a fragment back to the originating resource and location.

| Field          | Type  | Default | Description                          |
|----------------|-------|---------|--------------------------------------|
| `resource_uri` | `str` | --      | URI of the originating resource      |
| `location`     | `str` | `""`    | Location within the resource         |
| `strategy`     | `str` | `""`    | Strategy that produced this fragment |

### ContextBudget

Token budget management with reservation support.

| Field             | Type  | Default | Description                            |
|-------------------|-------|---------|----------------------------------------|
| `max_tokens`      | `int` | --      | Maximum total token budget (>= 0)      |
| `reserved_tokens` | `int` | `0`     | Reserved tokens (<= `max_tokens`)      |

**Properties:**

- `available_tokens: int` -- `max_tokens - reserved_tokens`

### AssembledContext

The fused, budget-respecting context payload delivered to an actor.

| Field             | Type                   | Description                          |
|-------------------|------------------------|--------------------------------------|
| `fragments`       | `list[ContextFragment]`| Ordered context fragments            |
| `total_tokens`    | `int`                  | Total token count (>= 0)            |
| `budget_used`     | `float`                | Budget fraction consumed (0.0--1.0)  |
| `strategies_used` | `list[str]`            | Contributing strategies              |
| `context_hash`    | `str`                  | Cryptographic hash for snapshot      |
| `preamble`        | `str \| None`          | Optional structure summary           |
| `provenance_map`  | `dict[str, Any]`       | Fragment -> resource/location map    |

## Detail Level Table (Universal Layer 0)

| Depth | Question Answered              | What Gets Included                      |
|-------|--------------------------------|-----------------------------------------|
| 0     | *What exists?*                 | Name/identifier of the information unit |
| 1     | *How is it organized?*         | Names of immediate children             |
| 2     | *What are the key relationships?* | Children + dependency/reference edges|
| 3     | *What is each thing's purpose?* | + Short descriptions/summaries         |
| 4     | *What is the structural shape?* | + Type info, size/count metadata       |
| 5+    | *How does it work?*            | Progressively more content              |
| max   | *Everything.*                  | Complete content -- nothing omitted     |

## Example Usage

```python
from cleveragents.domain.models.acms.crp import (
    ContextBudget,
    ContextFragment,
    ContextRequest,
    DetailLevelMap,
    FragmentProvenance,
)

# Create a detail level map for source code
code_map = DetailLevelMap(
    domain="uko-code:",
    max_depth=9,
    levels={
        "MODULE_LISTING": 0,
        "SIGNATURES": 4,
        "FULL_SOURCE": 9,
    },
)

# Resolve a named level
depth = code_map.resolve("SIGNATURES")  # -> 4

# Create a context request
request = ContextRequest(
    query="How does authentication work?",
    focus=["uko-py:class/AuthManager"],
    breadth=2,
    depth="SIGNATURES",
    purpose="Understand the auth flow for refactoring",
)

# Create a budget
budget = ContextBudget(max_tokens=8000, reserved_tokens=1000)
print(budget.available_tokens)  # 7000

# Create a fragment
fragment = ContextFragment(
    uko_node="uko-py:class/AuthManager",
    content="class AuthManager: ...",
    detail_depth=4,
    token_count=120,
    relevance_score=0.95,
    provenance=FragmentProvenance(
        resource_uri="uko-py:module/auth",
        location="lines 1-50",
        strategy="breadth-depth-navigator",
    ),
)
```

## Built-in Context Skill

The `builtin/context` skill is automatically injected into every
actor's skill set.  It provides three tools:

| Tool                    | Description                                   |
|-------------------------|-----------------------------------------------|
| `request_context`       | Request specific context during reasoning     |
| `query_history`         | Query historical context about past decisions |
| `get_context_budget`    | Check remaining context token budget          |

These tools are currently stubbed (`NotImplementedError`) pending the
full ACMS Context Assembly Pipeline implementation.