Visualizing QType Applications¶

QType includes a visualization feature that automatically generates Mermaid flowchart diagrams from your QType specifications. These visual diagrams help you understand the structure and flow of your AI applications at a glance.

The `qtype visualize` Command¶

The visualize command analyzes your QType YAML specification and generates a comprehensive Mermaid diagram showing:

Flows and their execution steps
Shared resources like models, indexes, authentication, and memory
Connections between components
Telemetry and observability configuration

Basic Usage¶

To generate a visualization of your QType application:

qtype visualize your_application.qtype.yaml

This will: 1. Load and validate your QType specification 2. Generate a Mermaid diagram 3. Open the diagram in your default browser for viewing

Output Formats¶

The visualize command supports multiple output formats:

Display in Browser (Default)¶

qtype visualize examples/chat_with_telemetry.qtype.yaml

Opens the diagram directly in your browser for immediate viewing.

Save as Mermaid Source¶

qtype visualize examples/chat_with_telemetry.qtype.yaml -o diagram.mmd

Saves the raw Mermaid markup to a .mmd or .mermaid file.

Export as SVG¶

qtype visualize examples/chat_with_telemetry.qtype.yaml -o diagram.svg

Generates a scalable vector graphics file perfect for documentation.

Export as PNG¶

qtype visualize examples/chat_with_telemetry.qtype.yaml -o diagram.png

Creates a raster image file for presentations or embedding.

Save Without Opening Browser¶

qtype visualize examples/chat_with_telemetry.qtype.yaml -o diagram.svg --no-display

Use the --no-display flag to save files without opening the browser.

Example: Chat with Telemetry¶

Let's look at a practical example using the chat_with_telemetry.qtype.yaml file:

id: hello_world
flows:
  - id: chat_example
    description: A simple chat flow with OpenAI
    mode: Chat
    steps:
      - id: llm_inference_step
        model: 
          id: gpt-4
          provider: openai
          auth: 
            id: openai_auth
            type: api_key
            api_key: ${OPENAI_KEY}
        system_message: |
          You are a helpful assistant.
        inputs:
          - id: user_message
            type: ChatMessage
        outputs:
          - id: response
            type: ChatMessage
telemetry:
  id: hello_world_telemetry
  endpoint: http://localhost:6006/v1/traces

Running the visualization command:

qtype visualize examples/chat_with_telemetry.qtype.yaml -o chat_with_telemetry.mermaid

Generates this Mermaid diagram:

flowchart TD
    subgraph APP ["📱 Application: hello_world"]
        direction TB

    subgraph FLOW_0 ["💬 Flow: chat_example"]
        direction LR
        FLOW_0_S0@{shape: rounded, label: "✨ llm_inference_step"}
    end

    subgraph RESOURCES ["🔧 Shared Resources"]
        direction LR
        AUTH_OPENAI_AUTH@{shape: hex, label: "🔐 openai_auth\nAPI_KEY"}
        MODEL_GPT_4@{shape: rounded, label: "✨ gpt-4 (openai)" }
        MODEL_GPT_4 -.->|uses| AUTH_OPENAI_AUTH
    end

    subgraph TELEMETRY ["📊 Observability"]
        direction TB
        TEL_SINK@{shape: curv-trap, label: "📡 hello_world_telemetry\nhttp&colon;//localhost:6006/v1/traces"}
    end

    end

    FLOW_0_S0 -.->|uses| MODEL_GPT_4
    FLOW_0_S0 -.->|traces| TEL_SINK

    %% Styling
    classDef appBox fill:none,stroke:#495057,stroke-width:3px
    classDef flowBox fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
    classDef llmNode fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    classDef modelNode fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px
    classDef authNode fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef telemetryNode fill:#fce4ec,stroke:#c2185b,stroke-width:2px
    classDef resourceBox fill:#f5f5f5,stroke:#616161,stroke-width:1px

    class APP appBox
    class FLOW_0 flowBox
    class RESOURCES resourceBox
    class TELEMETRY telemetryNode

Understanding the Diagram¶

The generated diagram uses intuitive icons and colors to represent different components:

Application Structure¶

📱 Application: The outermost container showing your application ID
💬 Chat Flows / 🔄 Flows: Individual flows with their descriptions
✨ Steps: Individual steps within flows (with different shapes for different step types)

Shared Resources¶

🔐 Authentication: API keys, OAuth, and other auth providers
✨ Models: LLM models with their providers (OpenAI, Bedrock, etc.)
🗂️ Indexes: Vector and document indexes for retrieval
🧠 Memory: Conversation memory stores
🔧 Tools: API tools, Python functions, and other capabilities

Observability¶

📊 Telemetry: OpenTelemetry tracing endpoints
📡 Telemetry Sink: Where traces and metrics are sent

Connections¶

Solid arrows (-->) show data flow between steps
Dotted arrows (-.->) show resource dependencies and relationships

Command Reference¶

qtype visualize [OPTIONS] SPEC_FILE

Arguments:
  SPEC_FILE    Path to the QType YAML file to visualize

Options:
  -o, --output PATH     Save diagram to file (.mmd, .mermaid, .svg, .png)
  -nd, --no-display     Don't open diagram in browser (default: False)
  -h, --help           Show help message

Tips for Better Visualizations¶

Use descriptive IDs: Clear, descriptive IDs for flows and steps make diagrams more readable
Add descriptions: Flow descriptions appear in the diagram and provide valuable context
Group related functionality: Organize steps logically within flows
Keep flows focused: Smaller, focused flows are easier to understand than large, complex ones