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

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.