Presets & Functions

Display presets control detail level, and standalone functions render analytics data.

Quick Example

from mamba_agents.agent.display import print_stats, get_preset

# Use a named preset
output = print_stats(stats, preset="compact")

# Customize a preset
preset = get_preset("detailed", show_tokens=False)
output = print_stats(stats, preset="detailed", show_tokens=False)

# Use different output formats
print_stats(stats, format="rich")   # Rich terminal tables
print_stats(stats, format="plain")  # ASCII text
print_stats(stats, format="html")   # HTML for Jupyter

Preset Comparison

Setting	Compact	Detailed	Verbose
show_tokens	False	True	True
max_content_length	100	300	None (unlimited)
expand	False	False	True
show_tool_details	False	False	True
max_tool_arg_length	50	200	500
limit	None	None	None

Named Preset Instances

from mamba_agents.agent.display import COMPACT, DETAILED, VERBOSE

• COMPACT — Minimal output: counts only, short truncation, no tool details.
• DETAILED — Balanced output: full tables, moderate truncation, no tool details. (default)
• VERBOSE — Maximum output: expanded content, no truncation, full tool args/results.

API Reference

DisplayPreset

DisplayPreset dataclass

DisplayPreset(
    show_tokens: bool = True,
    max_content_length: int | None = 300,
    expand: bool = False,
    show_tool_details: bool = False,
    max_tool_arg_length: int = 200,
    limit: int | None = None,
)

Configuration controlling how much detail renderers include.

ATTRIBUTE	DESCRIPTION
show_tokens	Whether to show token counts in stats output. TYPE: bool
max_content_length	Content truncation length in characters. None disables truncation, showing full content. TYPE: int | None
expand	Whether to show full content (overrides truncation). TYPE: bool
show_tool_details	Whether to show tool arguments and results. TYPE: bool
max_tool_arg_length	Truncation length for tool argument strings. TYPE: int
limit	Maximum items to display (e.g., turns in timeline). None means no limit. TYPE: int | None

get_preset

get_preset

get_preset(
    name: str = "detailed", **overrides: Any
) -> DisplayPreset

Retrieve a named preset, optionally overriding individual fields.

PARAMETER	DESCRIPTION
name	Preset name. Must be one of "compact", "detailed", or "verbose". TYPE: str DEFAULT: 'detailed'
**overrides	Keyword arguments matching DisplayPreset fields. These take precedence over the preset's default values. TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
DisplayPreset	A DisplayPreset instance with the requested configuration.

RAISES	DESCRIPTION
ValueError	If name is not a recognised preset name. The error message includes the list of valid preset names.

Examples:

Get the default preset::

preset = get_preset()  # returns 'detailed'

Get compact with token display enabled::

preset = get_preset("compact", show_tokens=True)

Source code in src/mamba_agents/agent/display/presets.py

def get_preset(name: str = "detailed", **overrides: Any) -> DisplayPreset:
    """Retrieve a named preset, optionally overriding individual fields.

    Args:
        name: Preset name. Must be one of ``"compact"``, ``"detailed"``,
            or ``"verbose"``.
        **overrides: Keyword arguments matching ``DisplayPreset`` fields.
            These take precedence over the preset's default values.

    Returns:
        A ``DisplayPreset`` instance with the requested configuration.

    Raises:
        ValueError: If *name* is not a recognised preset name. The error
            message includes the list of valid preset names.

    Examples:
        Get the default preset::

            preset = get_preset()  # returns 'detailed'

        Get compact with token display enabled::

            preset = get_preset("compact", show_tokens=True)
    """
    base = _PRESETS.get(name)
    if base is None:
        valid = ", ".join(sorted(_PRESETS))
        raise ValueError(f"Unknown preset name: {name!r}. Valid presets: {valid}")

    if not overrides:
        return base

    return replace(base, **overrides)

print_stats

print_stats

print_stats(
    stats: MessageStats,
    *,
    preset: str = "detailed",
    format: str = "rich",
    console: Console | None = None,
    **options: Any,
) -> str

Render message statistics in the chosen format.

Resolves the named preset, applies any keyword options as overrides, selects the renderer matching format, and delegates to its render_stats method.

PARAMETER	DESCRIPTION
stats	Token and message count statistics to render. TYPE: MessageStats
preset	Named preset ("compact", "detailed", or "verbose"). TYPE: str DEFAULT: 'detailed'
format	Output format ("rich", "plain", or "html"). TYPE: str DEFAULT: 'rich'
console	Optional Rich Console instance. Only used when format is "rich". TYPE: Console | None DEFAULT: None
**options	Keyword overrides applied to the resolved preset (e.g., show_tokens=False). TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
str	The rendered string.

RAISES	DESCRIPTION
ValueError	If preset or format is not recognised.

Example::

from mamba_agents.agent.display import print_stats

output = print_stats(stats)  # Rich table to terminal
output = print_stats(stats, format="plain")  # ASCII table
output = print_stats(stats, preset="compact", show_tokens=True)

Source code in src/mamba_agents/agent/display/functions.py

def print_stats(
    stats: MessageStats,
    *,
    preset: str = "detailed",
    format: str = "rich",
    console: Console | None = None,
    **options: Any,
) -> str:
    """Render message statistics in the chosen format.

    Resolves the named *preset*, applies any keyword *options* as
    overrides, selects the renderer matching *format*, and delegates
    to its ``render_stats`` method.

    Args:
        stats: Token and message count statistics to render.
        preset: Named preset (``"compact"``, ``"detailed"``, or
            ``"verbose"``).
        format: Output format (``"rich"``, ``"plain"``, or ``"html"``).
        console: Optional Rich ``Console`` instance. Only used when
            *format* is ``"rich"``.
        **options: Keyword overrides applied to the resolved preset
            (e.g., ``show_tokens=False``).

    Returns:
        The rendered string.

    Raises:
        ValueError: If *preset* or *format* is not recognised.

    Example::

        from mamba_agents.agent.display import print_stats

        output = print_stats(stats)  # Rich table to terminal
        output = print_stats(stats, format="plain")  # ASCII table
        output = print_stats(stats, preset="compact", show_tokens=True)
    """
    resolved_preset = get_preset(preset, **options)
    renderer = _resolve_renderer(format)

    if isinstance(renderer, RichRenderer):
        return renderer.render_stats(stats, resolved_preset, console=console)
    return renderer.render_stats(stats, resolved_preset)

print_timeline

print_timeline

print_timeline(
    turns: list[Turn],
    *,
    preset: str = "detailed",
    format: str = "rich",
    console: Console | None = None,
    **options: Any,
) -> str

Render a conversation timeline in the chosen format.

Resolves the named preset, applies any keyword options as overrides, selects the renderer matching format, and delegates to its render_timeline method.

PARAMETER	DESCRIPTION
turns	List of conversation turns to render. TYPE: list[Turn]
preset	Named preset ("compact", "detailed", or "verbose"). TYPE: str DEFAULT: 'detailed'
format	Output format ("rich", "plain", or "html"). TYPE: str DEFAULT: 'rich'
console	Optional Rich Console instance. Only used when format is "rich". TYPE: Console | None DEFAULT: None
**options	Keyword overrides applied to the resolved preset (e.g., limit=10). TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
str	The rendered string.

RAISES	DESCRIPTION
ValueError	If preset or format is not recognised.

Example::

from mamba_agents.agent.display import print_timeline

output = print_timeline(turns)  # Rich panels to terminal
output = print_timeline(turns, format="html")  # HTML sections
output = print_timeline(turns, preset="verbose", limit=5)

Source code in src/mamba_agents/agent/display/functions.py

def print_timeline(
    turns: list[Turn],
    *,
    preset: str = "detailed",
    format: str = "rich",
    console: Console | None = None,
    **options: Any,
) -> str:
    """Render a conversation timeline in the chosen format.

    Resolves the named *preset*, applies any keyword *options* as
    overrides, selects the renderer matching *format*, and delegates
    to its ``render_timeline`` method.

    Args:
        turns: List of conversation turns to render.
        preset: Named preset (``"compact"``, ``"detailed"``, or
            ``"verbose"``).
        format: Output format (``"rich"``, ``"plain"``, or ``"html"``).
        console: Optional Rich ``Console`` instance. Only used when
            *format* is ``"rich"``.
        **options: Keyword overrides applied to the resolved preset
            (e.g., ``limit=10``).

    Returns:
        The rendered string.

    Raises:
        ValueError: If *preset* or *format* is not recognised.

    Example::

        from mamba_agents.agent.display import print_timeline

        output = print_timeline(turns)  # Rich panels to terminal
        output = print_timeline(turns, format="html")  # HTML sections
        output = print_timeline(turns, preset="verbose", limit=5)
    """
    resolved_preset = get_preset(preset, **options)
    renderer = _resolve_renderer(format)

    if isinstance(renderer, RichRenderer):
        return renderer.render_timeline(turns, resolved_preset, console=console)
    return renderer.render_timeline(turns, resolved_preset)

print_tools

print_tools

print_tools(
    tools: list[ToolCallInfo],
    *,
    preset: str = "detailed",
    format: str = "rich",
    console: Console | None = None,
    **options: Any,
) -> str

Render a tool usage summary in the chosen format.

Resolves the named preset, applies any keyword options as overrides, selects the renderer matching format, and delegates to its render_tools method.

PARAMETER	DESCRIPTION
tools	List of tool call summaries to render. TYPE: list[ToolCallInfo]
preset	Named preset ("compact", "detailed", or "verbose"). TYPE: str DEFAULT: 'detailed'
format	Output format ("rich", "plain", or "html"). TYPE: str DEFAULT: 'rich'
console	Optional Rich Console instance. Only used when format is "rich". TYPE: Console | None DEFAULT: None
**options	Keyword overrides applied to the resolved preset (e.g., show_tool_details=True). TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
str	The rendered string.

RAISES	DESCRIPTION
ValueError	If preset or format is not recognised.

Example::

from mamba_agents.agent.display import print_tools

output = print_tools(tools)  # Rich table to terminal
output = print_tools(tools, format="plain")  # ASCII table
output = print_tools(tools, preset="verbose")

Source code in src/mamba_agents/agent/display/functions.py

def print_tools(
    tools: list[ToolCallInfo],
    *,
    preset: str = "detailed",
    format: str = "rich",
    console: Console | None = None,
    **options: Any,
) -> str:
    """Render a tool usage summary in the chosen format.

    Resolves the named *preset*, applies any keyword *options* as
    overrides, selects the renderer matching *format*, and delegates
    to its ``render_tools`` method.

    Args:
        tools: List of tool call summaries to render.
        preset: Named preset (``"compact"``, ``"detailed"``, or
            ``"verbose"``).
        format: Output format (``"rich"``, ``"plain"``, or ``"html"``).
        console: Optional Rich ``Console`` instance. Only used when
            *format* is ``"rich"``.
        **options: Keyword overrides applied to the resolved preset
            (e.g., ``show_tool_details=True``).

    Returns:
        The rendered string.

    Raises:
        ValueError: If *preset* or *format* is not recognised.

    Example::

        from mamba_agents.agent.display import print_tools

        output = print_tools(tools)  # Rich table to terminal
        output = print_tools(tools, format="plain")  # ASCII table
        output = print_tools(tools, preset="verbose")
    """
    resolved_preset = get_preset(preset, **options)
    renderer = _resolve_renderer(format)

    if isinstance(renderer, RichRenderer):
        return renderer.render_tools(tools, resolved_preset, console=console)
    return renderer.render_tools(tools, resolved_preset)