Context Blocks API

Context blocks are named sections of the system prompt. They come from multiple sources (framework, strategy, skills, developer) and are managed through a single unified interface.

Core Concept

Every context block entry is a dict mapping {key: value}:

from nooa import Context

context = {
    "role": "You are a security expert",                       # str: literal text, volatile suffix
    "shell": Context(expr="doc(self.shell)", prefix=True),     # evaluated each turn, cacheable prefix
    "config": Context("stable config text", prefix=True),      # literal, cacheable prefix
    "status": Context(expr="f'{self.done}/{self.total}'"),     # evaluated each turn, volatile suffix
    "self": None,                                              # suppress block from prompt
}

Value Types

Entry Points (same dict shape everywhere)

# 1. Class-level
class MyAgent(Agent, llm=llm, context={
    "role": Context("Security expert", prefix=True),
    "self": None,  # suppress doc(self) block
}):
    pass

# 2. Instance-level
agent = MyAgent(context={"focus": "performance analysis"})

# 3. @strategy decorator (agent methods)
@strategy(CodeActStrategy(), context={
    "focus": "Write comprehensive tests",
    "state": None,
})
async def write_tests(self, code: str) -> str: ...

# 4. @strategy decorator (standalone functions)
@strategy(CodeActStrategy(), context={
    "role": "expert summarizer",
    "execution_context": None,
}, llm=llm)
async def summarise(text: str) -> str:
    """Summarise the text in one sentence."""
    ...

# 5. Scoped (with-block, temporary)
with ScopedContext(context={"urgency": "high", "state": None}):
    result = await agent.analyze(data)

# 6. Runtime (inside agent code or constructors) — SAME TYPES
self.context["role"] = "You are an expert"
self.context["shell"] = Context(expr="doc(self.shell)", prefix=True)
self.context["status"] = Context(expr="f'{self.done}/{self.total}'")
self.context["self"] = None  # suppress

Well-Known Block Keys

Suppress any of these with context={"key": None} or self.context["key"] = None.

Prefix vs Suffix

• Prefix = cacheable across turns. Forms a stable shared prefix that LLM providers can cache. Use for blocks that rarely change (agent identity, tool docs, stable config).
• Suffix = volatile. Default. Changes between turns.

Rule of thumb:

• Set at class/instance init time → usually prefix-worthy
• Set per method/turn → usually suffix
• Use prefix=True explicitly when you swap something at runtime but know it's stable across multiple subsequent turns (e.g. hot-swapping shell tool docs)

Inspecting Your Prompt

# In agent code:
self.context.all_keys()      # All block keys (framework + strategy + user)
self.context.disabled()      # Currently suppressed keys
self.context.is_enabled("k") # Check if a specific key renders

# From outside:
agent.context_manager.keys()            # All registered keys
agent.context_manager.protected_keys    # Framework-protected keys
agent.context_manager.disabled_keys     # Suppressed set

Context Class Reference

class Context:
    def __init__(
        self,
        value: str | None = None,   # Literal text (mutually exclusive with expr)
        *,
        expr: str | None = None,    # Python expression re-evaluated each turn
        prefix: bool = False,       # Place in cacheable prefix if True
    ): ...

• value and expr are mutually exclusive (TypeError if both given)
• expr is validated at creation time (must be compilable Python)
• prefix=False is the default (volatile suffix)

Legacy API (deprecated)

These still work but emit DeprecationWarning: