Module: context

from adk_fluent import C

Context engineering namespace. Each method returns a frozen CTransform descriptor.

Quick Reference

Method	Returns	Description
C.none()	CTransform	Suppress all conversation history
C.default()	CTransform	Keep default conversation history (pass-through)
C.user_only()	CUserOnly	Include only user messages
C.from_agents(*names)	CFromAgents	Include user messages + outputs from named agents
C.exclude_agents(*names)	CExcludeAgents	Exclude outputs from named agents
C.window(n=5)	CWindow	Include last N turn-pairs from conversation history
C.last_n_turns(n)	CWindow	Alias for C.window(n=n)
C.from_state(*keys)	CFromState	Read named keys from session state as context
C.template(text)	CTemplate	Render a template string with {key} and {key?} state placeholders
C.when(predicate, block)	CWhen	Include block only if predicate is truthy at runtime
C.select(author=None, type=None, tag=None)	CSelect	Filter events by metadata: author, type, and/or tag
C.recent(decay='exponential', half_life=10, min_weight=0.1)	CRecent	Importance-weighted selection based on recency with exponential decay
C.compact(strategy='tool_calls')	CCompact	Structural compaction — merge sequential same-author messages or tool calls
C.dedup(strategy='exact', model='gemini-2.5-flash')	CDedup	Remove duplicate or redundant events.
C.truncate(max_turns=None, max_tokens=None, strategy='tail')	CTruncate	Hard limit on context by turn count or estimated tokens
C.project(*fields)	CProject	Keep only specified fields from event content
C.budget(max_tokens=8000, overflow='truncate_oldest')	CBudget	Set token budget constraint for context
C.priority(tier=2)	CPriority	Set priority tier for context ordering
C.fit(max_tokens=4000, strategy='strict', model='gemini-2.5-flash')	CFit	Aggressive pruning to fit a hard token limit.
C.fresh(max_age=3600.0, stale_action='drop')	CFresh	Prune stale context based on event timestamp
C.redact(*patterns, replacement='[REDACTED]')	CRedact	Remove PII or sensitive patterns from context via regex
C.summarize(scope='all', model='gemini-2.5-flash', prompt=None, schema=None)	CSummarize	Summarize context via LLM.
C.relevant(query_key=None, query=None, top_k=5, model='gemini-2.5-flash')	CRelevant	Select events by semantic relevance to a query via LLM scoring
C.extract(schema=None, key='extracted', model='gemini-2.5-flash')	CExtract	Extract structured data from conversation via LLM
C.distill(key='facts', model='gemini-2.5-flash')	CDistill	Extract atomic facts from conversation via LLM
C.validate(*checks, model='gemini-2.5-flash')	CValidate	Validate context quality.
C.notes(key='default', format='plain')	CNotes	Read structured notes from scratchpad at state["_notes_{key}"]
C.write_notes(key='default', strategy='append', source_key=None)	CWriteNotes	Write to scratchpad after agent execution
C.rolling(n=5, summarize=False, model='gemini-2.5-flash')	CRolling	Rolling window with optional summarization of older turns
C.from_agents_windowed(**agent_windows)	CFromAgentsWindowed	Per-agent selective windowing
C.user(strategy='all')	CUser	Select user messages with a strategy
C.manus_cascade(budget=8000, model='gemini-2.5-flash')	CManusCascade	Manus-inspired progressive compression cascade
C.pipeline_aware(*keys)	CPipelineAware	Topology-aware context: user messages + named state keys
C.shared_thread()	CSharedThread	Shared conversational context for multi-agent loops
C.with_ui(surface_id=None)	CTransform	Include current UI surface state in agent context

Methods

C.none() -> CTransform

Suppress all conversation history.

C.default() -> CTransform

Keep default conversation history (pass-through).

C.user_only() -> CUserOnly

Include only user messages.

C.from_agents(*names: str) -> CFromAgents

Include user messages + outputs from named agents.

Parameters:

• *names (str)

C.exclude_agents(*names: str) -> CExcludeAgents

Exclude outputs from named agents.

Parameters:

• *names (str)

C.window(*, n: int = 5) -> CWindow

Include last N turn-pairs from conversation history.

Parameters:

• n (int) — default: 5

C.last_n_turns(n: int) -> CWindow

Alias for C.window(n=n).

Parameters:

• n (int)

C.from_state(*keys: str) -> CFromState

Read named keys from session state as context.

Parameters:

• *keys (str)

C.template(text: str) -> CTemplate

Render a template string with {key} and {key?} state placeholders.

Parameters:

• text (str)

C.when(predicate: Callable | str, block: CTransform) -> CWhen

Include block only if predicate is truthy at runtime.

String predicate is a shortcut for state key check: C.when(“has_history”, C.rolling(“conversation”)) C.when(lambda s: s.get(“debug”), C.notes(“debug_scratchpad”))

Parameters:

• predicate (Callable | str)

• block (CTransform)

C.select(*, author: str | tuple[str, ...] | None = None, type: str | tuple[str, ...] | None = None, tag: str | tuple[str, ...] | None = None) -> CSelect

Filter events by metadata: author, type, and/or tag.

Parameters:

• author (str | tuple[str, …] | None) — default: None

• type (str | tuple[str, …] | None) — default: None

• tag (str | tuple[str, …] | None) — default: None

C.recent(*, decay: str = exponential, half_life: int = 10, min_weight: float = 0.1) -> CRecent

Importance-weighted selection based on recency with exponential decay.

Parameters:

• decay (str) — default: 'exponential'

• half_life (int) — default: 10

• min_weight (float) — default: 0.1

C.compact(*, strategy: str = tool_calls) -> CCompact

Structural compaction — merge sequential same-author messages or tool calls.

Parameters:

• strategy (str) — default: 'tool_calls'

C.dedup(*, strategy: str = exact, model: str = gemini-2.5-flash) -> CDedup

Remove duplicate or redundant events. strategy=’semantic’ uses LLM.

Parameters:

• strategy (str) — default: 'exact'

• model (str) — default: 'gemini-2.5-flash'

C.truncate(*, max_turns: int | None = None, max_tokens: int | None = None, strategy: str = tail) -> CTruncate

Hard limit on context by turn count or estimated tokens.

Parameters:

• max_turns (int | None) — default: None

• max_tokens (int | None) — default: None

• strategy (str) — default: 'tail'

C.project(*fields: str) -> CProject

Keep only specified fields from event content.

Parameters:

• *fields (str)

C.budget(*, max_tokens: int = 8000, overflow: str = truncate_oldest) -> CBudget

Set token budget constraint for context.

Parameters:

• max_tokens (int) — default: 8000

• overflow (str) — default: 'truncate_oldest'

C.priority(*, tier: int = 2) -> CPriority

Set priority tier for context ordering.

Parameters:

• tier (int) — default: 2

C.fit(*, max_tokens: int = 4000, strategy: str = strict, model: str = gemini-2.5-flash) -> CFit

Aggressive pruning to fit a hard token limit. strategy=’cascade’ uses LLM.

Parameters:

• max_tokens (int) — default: 4000

• strategy (str) — default: 'strict'

• model (str) — default: 'gemini-2.5-flash'

C.fresh(*, max_age: float = 3600.0, stale_action: str = drop) -> CFresh

Prune stale context based on event timestamp.

Parameters:

• max_age (float) — default: 3600.0

• stale_action (str) — default: 'drop'

C.redact(*patterns: str, replacement: str = [REDACTED]) -> CRedact

Remove PII or sensitive patterns from context via regex.

Parameters:

• *patterns (str)

• replacement (str) — default: '[REDACTED]'

LLM-powered methods

C.summarize(*, scope: str = all, model: str = gemini-2.5-flash, prompt: str | None = None, schema: dict | None = None) -> CSummarize

Summarize context via LLM. Scope: ‘all’, ‘before_window’, ‘tool_results’.

Parameters:

• scope (str) — default: 'all'

• model (str) — default: 'gemini-2.5-flash'

• prompt (str | None) — default: None

• schema (dict | None) — default: None

C.relevant(*, query_key: str | None = None, query: str | None = None, top_k: int = 5, model: str = gemini-2.5-flash) -> CRelevant

Select events by semantic relevance to a query via LLM scoring.

Parameters:

• query_key (str | None) — default: None

• query (str | None) — default: None

• top_k (int) — default: 5

• model (str) — default: 'gemini-2.5-flash'

C.extract(*, schema: dict | None = None, key: str = extracted, model: str = gemini-2.5-flash) -> CExtract

Extract structured data from conversation via LLM.

Parameters:

• schema (dict | None) — default: None

• key (str) — default: 'extracted'

• model (str) — default: 'gemini-2.5-flash'

C.distill(*, key: str = facts, model: str = gemini-2.5-flash) -> CDistill

Extract atomic facts from conversation via LLM.

Parameters:

• key (str) — default: 'facts'

• model (str) — default: 'gemini-2.5-flash'

C.validate(*checks: str, model: str = gemini-2.5-flash) -> CValidate

Validate context quality. Checks: ‘contradictions’, ‘completeness’, ‘freshness’, ‘token_efficiency’.

Parameters:

• *checks (str)

• model (str) — default: 'gemini-2.5-flash'

Scratchpads + Sugar

C.notes(key: str = default, *, format: str = plain) -> CNotes

Read structured notes from scratchpad at state["_notes_{key}"].

Parameters:

• key (str) — default: 'default'

• format (str) — default: 'plain'

C.write_notes(key: str = default, *, strategy: str = append, source_key: str | None = None) -> CWriteNotes

Write to scratchpad after agent execution.

Strategies: ‘append’, ‘replace’, ‘merge’, ‘prepend’.

Parameters:

• key (str) — default: 'default'

• strategy (str) — default: 'append'

• source_key (str | None) — default: None

C.rolling(n: int = 5, *, summarize: bool = False, model: str = gemini-2.5-flash) -> CRolling

Rolling window with optional summarization of older turns.

When summarize=True, events before the window are summarized via LLM.

Parameters:

• n (int) — default: 5

• summarize (bool) — default: False

• model (str) — default: 'gemini-2.5-flash'

C.from_agents_windowed(**agent_windows: int) -> CFromAgentsWindowed

Per-agent selective windowing.

Example: C.from_agents_windowed(researcher=1, critic=3)

Parameters:

• **agent_windows (int)

C.user(*, strategy: str = all) -> CUser

Select user messages with a strategy.

Strategies: ‘all’, ‘first’, ‘last’, ‘bookend’.

Parameters:

• strategy (str) — default: 'all'

C.manus_cascade(*, budget: int = 8000, model: str = gemini-2.5-flash) -> CManusCascade

Manus-inspired progressive compression cascade.

Applies: compact → dedup → summarize → truncate.

Parameters:

• budget (int) — default: 8000

• model (str) — default: 'gemini-2.5-flash'

C.pipeline_aware(*keys: str) -> CPipelineAware

Topology-aware context: user messages + named state keys.

Designed for pipeline agents that need the user’s original message plus structured data from upstream agents, but should NOT see raw intermediate agent conversation history.

Equivalent to C.user_only() + C.from_state(*keys) but with clearer intent and better contract checker support.

Example: # classifier writes intent, handler sees user msg + intent classifier = Agent(“classify”).writes(“intent”) handler = Agent(“handle”).context(C.pipeline_aware(“intent”)) pipeline = classifier >> handler

Args:

*keys: State key names to include alongside user messages.

Parameters:

• *keys (str)

C.shared_thread() -> CSharedThread

Shared conversational context for multi-agent loops.

Every agent sees the full transcript of what all other agents said. Like a group chat — no explicit state wiring needed.

Usage: loop = ( (researcher >> writer >> critic) * until(lambda s: s.get(“approved”), max=4) ).context(C.shared_thread())

C.with_ui(surface_id: str | None = None) -> CTransform

Include current UI surface state in agent context.

Injects the A2UI data model for the given surface (or all surfaces) into the agent’s context as a <ui_state> block.

Args:

• surface_id: Optional surface to include. If None, includes all.

Usage: Agent(“renderer”).context(C.with_ui(“dashboard”)) Agent(“updater”).context(C.from_state(“total”) + C.with_ui())

Parameters:

• surface_id (str | None) — default: None

Composition Operators

+ (union (CComposite))

Combine context transforms

| (pipe (CPipe))

Chain context processing

Types

Type	Description
CTransform	Base context transform descriptor
CComposite	Union of multiple context blocks (via + operator)
CPipe	Pipe transform: source feeds into transform (via
CFromState	Read named keys from session state and format as context
CWindow	Include only the last N turn-pairs from conversation history
CUserOnly	Include only user messages from conversation history
CFromAgents	Include user messages + outputs from named agents
CExcludeAgents	Exclude outputs from named agents
CTemplate	Render a template string with {key} and {key?} placeholders from state
CSelect	Filter events by metadata: author, type, and/or tag
CRecent	Importance-weighted selection based on recency with exponential decay
CCompact	Structural compaction — merge sequential same-author messages or tool calls
CDedup	Remove duplicate or redundant events
CTruncate	Hard limit on context size by turn count or estimated tokens
CProject	Keep only specific fields from event content
CBudget	Token budget constraint for context
CPriority	Priority tier for context ordering (lower = higher priority)
CFit	Aggressive pruning to fit a hard token limit
CFresh	Prune stale context based on event timestamp
CRedact	Remove PII or sensitive patterns from context via regex
CSummarize	Lossy compression via LLM summarization
CRelevant	Semantic relevance selection via LLM scoring
CExtract	Structured extraction from conversation via LLM
CDistill	Fact distillation from conversation via LLM
CValidate	Context quality validation
CNotes	Read from an agent’s structured scratchpad stored in session state
CWriteNotes	Write to an agent’s structured scratchpad after agent execution
CRolling	Rolling window with optional summarization of older turns
CFromAgentsWindowed	Per-agent selective windowing
CUser	User message strategies
CManusCascade	Manus-inspired progressive compression cascade
CWhen	Conditional context inclusion
CPipelineAware	Topology-aware context for pipeline agents
CSharedThread	Shared conversational thread for multi-agent loops