<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/7.2-display-system -->

# Display System

- src/praisonai-agents/praisonaiagents/main.py
- src/praisonai-agents/test_callback_enhancement.py
- src/praisonai-agents/test_callback_fix.py
- src/praisonai-agents/test_callback_fix_verification.py
- src/praisonai-agents/test_callback_simple.py
- src/praisonai-agents/test_duplicate_callback_fix.py
- src/praisonai/praisonai/inc/models.py

## Purpose and Scope

The Display System provides a unified interface for rendering agent execution information to the console using the Rich library. It implements a callback-based architecture that allows external systems to intercept and process display events without coupling to the console output implementation. This system handles formatted output for task interactions, tool calls, errors, reasoning steps, and status indicators with a consistent color palette and visual design language.

For information about the CLI interface that uses this system, see [CLI Interface](/MervinPraison/PraisonAI/7.1-cli-interface). For web-based UIs, see [Web UI (Chainlit)](/MervinPraison/PraisonAI/7.3-web-ui-(chainlit)).

## Architecture Overview

The Display System consists of three primary layers: the color and design system defining visual semantics, the callback registry enabling event interception, and the display functions producing formatted console output.

### System Component Architecture

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/main.py1-105](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L1-L105) [src/praisonai-agents/praisonaiagents/main.py106-132](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L106-L132)

## Color Palette and Design System

The Display System uses `PRAISON_COLORS`, a semantic color palette that creates a visual narrative flow from agent identity through task execution to response completion.

### Color Palette Structure

The palette emphasizes scannable differentiation with soft, professional colors. Each semantic role has a primary color for borders/accents and a lighter text variant for readability.

### Animation Frames

The system includes predefined animation sequences for status indicators:

- WORKING_FRAMES : ["*oo", "o*o", "oo*", "o*o"] - Pulsing dot animation
- WORKING_PHASES : Four-stage processing descriptions from "Analyzing query..." to "Finalizing output..."

**Sources:** [src/praisonai-agents/praisonaiagents/main.py34-79](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L34-L79)

## Callback System

The callback system enables external consumers to intercept display events without modifying the display logic. It maintains separate registries for synchronous and asynchronous callbacks.

### Callback Registration Flow

```

```

### Callback Execution Flow

The system provides two execution mechanisms: `execute_sync_callback()` for immediate synchronous execution and `execute_callback()` for async-compatible execution that can handle both sync and async callbacks.

```

```

**Key implementation details:**

1. Parameter filtering : The system inspects callback signatures to maintain backward compatibility. If a callback accepts **kwargs , all parameters are passed. Otherwise, only parameters in the callback signature are included. src/praisonai-agents/praisonaiagents/main.py 149-156
2. Always-execute policy : Callbacks execute regardless of the output mode setting (verbose/silent). This ensures external systems receive events even when console output is suppressed. src/praisonai-agents/praisonaiagents/main.py 134-157
3. Dual-mode support : Synchronous callbacks are wrapped in loop.run_in_executor() when called from async contexts to prevent blocking. src/praisonai-agents/praisonaiagents/main.py 180-181

**Sources:** [src/praisonai-agents/praisonaiagents/main.py106-197](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L106-L197)

## Display Functions

The Display System provides eight primary display functions, each serving a specific purpose in the agent execution visualization.

### Function-to-UI Mapping

```

```

### display_interaction()

The primary display function for task execution and agent responses. It accepts comprehensive context parameters for both the task and the agent.

**Function signature:**

```

```

**Visual output:**

- Task : Inline format with  prefix in warm coral ( #FF9B9B )
- Response : Panel with ocean blue border ( #4A90D9 ), optional timing in title
- Metrics footer : Compact line showing tokens in/out, cost, and model

**Implementation details:**

1. Empty response handling : Skips display if response is empty, common with tool-only calls. src/praisonai-agents/praisonaiagents/main.py 238-240
2. Metrics formatting : Adds dashed separator and compact metrics line when metrics dict is provided with tokens_in , tokens_out , cost , and model fields. src/praisonai-agents/praisonaiagents/main.py 264-277
3. Content cleaning : Truncates base64 content and long strings to prevent console overflow. src/praisonai-agents/praisonaiagents/main.py 198-217

**Sources:** [src/praisonai-agents/praisonaiagents/main.py219-288](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L219-L288)

### display_tool_call()

Displays tool execution in an inline timeline format with structured information about tool invocation.

**Function signature:**

```

```

**Visual format:**

```
> tool_name(arg1=value1, arg2=value2) -> result [1.2s] ok
```

**Key features:**

- Inline prefix : Uses > character in soft sage green ( #86A789 )
- Status icons : ok for success, x for failure
- Compact display : Truncates long arguments (>50 chars) and outputs (>80 chars)
- Timing : Displays elapsed time in brackets when available
- Arrow notation : Uses -> to separate input from output

**Callback execution**: Always triggers callbacks even when `console=None`, ensuring external systems receive tool execution events regardless of verbose mode. [src/praisonai-agents/praisonaiagents/main.py348-349](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L348-L349)

**Sources:** [src/praisonai-agents/praisonaiagents/main.py325-385](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L325-L385)

### display_reasoning_steps()

Shows the agent's thought process using distinctive numbered circles ((1)(2)(3)).

**Function signature:**

```

```

**Circle numbers**: Supports up to 20 steps using Unicode circled numbers `(1)(2)(3)(4)(5)(6)(7)(8)(9)(10)(11)(12)(13)(14)(15)(16)(17)(18)(19)(20)`. For steps beyond 20, falls back to `(21)` format. [src/praisonai-agents/praisonaiagents/main.py438-443](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L438-L443)

**Sources:** [src/praisonai-agents/praisonaiagents/main.py422-455](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L422-L455)

### display_working_status()

Creates an animated working indicator with pulsing dots showing processing phases.

**Function signature:**

```

```

**Animation cycle**:

- Frame 0: *oo - "Analyzing query..."
- Frame 1: o*o - "Processing context..."
- Frame 2: oo* - "Generating response..."
- Frame 3: o*o - "Finalizing output..."

**Usage pattern**: Typically used with `Rich.Live` for real-time status updates during long operations.

**Sources:** [src/praisonai-agents/praisonaiagents/main.py457-485](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L457-L485)

### display_error()

Displays error messages with semantic error styling and appends to the global `error_logs` list.

**Function signature:**

```

```

**Error persistence**: Appends to `error_logs` list for later retrieval and analysis. [src/praisonai-agents/praisonaiagents/main.py402](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L402-L402)

**Sources:** [src/praisonai-agents/praisonaiagents/main.py386-402](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L386-L402)

### display_instruction()

Displays agent instructions and context information. Only outputs the instruction panel when log level is `DEBUG`.

**Function signature:**

```

```

**Agent info panel**: Displays when `agent_name` is provided, showing:

- Agent name : With Agent emoji prefix
- Role : If provided
- Tools : Formatted as italic list

**Debug-only instruction**: The instruction message itself only displays when `logging.getLogger().getEffectiveLevel() == logging.DEBUG`. [src/praisonai-agents/praisonaiagents/main.py322-323](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L322-L323)

**Sources:** [src/praisonai-agents/praisonaiagents/main.py301-324](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L301-L324)

## Content Processing and Cleanup

The system includes a centralized `_clean_display_content()` helper function that preprocesses all display content.

### Cleaning Pipeline

```

```

**Base64 handling**: Removes lines containing "base64" to prevent console pollution with binary data. [src/praisonai-agents/praisonaiagents/main.py206-211](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L206-L211)

**Truncation**: Defaults to 20,000 characters with "..." appended for longer content. [src/praisonai-agents/praisonaiagents/main.py214-215](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L214-L215)

**Empty content logging**: Logs debug messages when empty content is received to aid troubleshooting. [src/praisonai-agents/praisonaiagents/main.py200-202](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L200-L202)

**Sources:** [src/praisonai-agents/praisonaiagents/main.py198-217](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L198-L217)

## Async Display Functions

All display functions have async equivalents with an `a` prefix: `adisplay_interaction()`, `adisplay_tool_call()`, etc. These functions mirror their synchronous counterparts but use `await execute_callback()` for proper async callback execution.

### Async Function Mapping

**Implementation note**: Async functions call `await execute_callback()` which properly handles both sync and async callbacks by running sync callbacks in an executor and directly awaiting async callbacks. [src/praisonai-agents/praisonaiagents/main.py158-196](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L158-L196)

**Sources:** [src/praisonai-agents/praisonaiagents/main.py487-610](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L487-L610)

## TaskOutput Model

The system defines a `TaskOutput` model for structured task execution results.

**Class definition:**

```

```

**Methods:**

- json() : Returns JSON string if output_format == "JSON"
- to_dict() : Merges json_dict and pydantic.model_dump() into unified dict
- __str__() : Returns pydantic representation, then json_dict, finally raw

**Token metrics integration**: Includes optional `token_metrics` field for tracking token usage and costs. [src/praisonai-agents/praisonaiagents/main.py637](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L637-L637)

**Sources:** [src/praisonai-agents/praisonaiagents/main.py628-658](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L628-L658)

## Usage Examples

### Registering Display Callbacks

```

```

### Registering Approval Callbacks

```

```

**Sources:** [src/praisonai-agents/test_callback_fix_verification.py1-112](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/test_callback_fix_verification.py#L1-L112) [src/praisonai-agents/test_callback_simple.py1-43](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/test_callback_simple.py#L1-L43)

## Integration with Agent System

The Display System integrates with the core agent system through callback invocation at key execution points. The LLM class and Agent class call display functions during:

1. Response generation : display_interaction() after LLM completes response
2. Tool execution : display_tool_call() during tool invocation
3. Error handling : display_error() when exceptions occur
4. Reflection : display_self_reflection() during self-reflection loops
5. Streaming : display_generating() during streaming responses

**Output mode control**: Display functions check the `output` parameter (verbose/silent) to determine whether to render to console, but always execute callbacks. This allows UI frameworks to receive events without console pollution. [src/praisonai-agents/praisonaiagents/main.py350-351](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L350-L351)

**Sources:** [src/praisonai-agents/praisonaiagents/main.py81-104](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/main.py#L81-L104)

## Testing Infrastructure

The system includes comprehensive test coverage for callback functionality:

- test_duplicate_callback_fix.py : Verifies callbacks execute exactly once per event, addressing issue #878
- test_callback_fix_verification.py : Tests basic callback registration and execution
- test_callback_enhancement.py : Validates enhanced context parameters (agent_name, task_name, etc.)
- test_callback_simple.py : Simple smoke test for callback system
- test_callback_fix.py : Tests callbacks work with output="silent" mode

**Key test scenario**: Ensures `display_interaction()` is called only once per LLM response, even with features like reasoning, reflection, and tool calls. [src/praisonai-agents/test_duplicate_callback_fix.py29-61](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/test_duplicate_callback_fix.py#L29-L61)

**Sources:** [src/praisonai-agents/test_duplicate_callback_fix.py1-230](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/test_duplicate_callback_fix.py#L1-L230) [src/praisonai-agents/test_callback_fix_verification.py1-112](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/test_callback_fix_verification.py#L1-L112) [src/praisonai-agents/test_callback_enhancement.py1-82](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/test_callback_enhancement.py#L1-L82) [src/praisonai-agents/test_callback_simple.py1-43](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/test_callback_simple.py#L1-L43) [src/praisonai-agents/test_callback_fix.py1-71](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/test_callback_fix.py#L1-L71)
