Chart Plotting¶

The SDK includes built-in utilities for plotting charts generated by Cortex Agents using Altair (Python wrapper for Vega-Lite).

Installation¶

Install the optional chart dependencies:

pip install snowflake-cortex-agents[charts]

Or directly:

pip install altair pandas

Quick Start¶

Simple Plot¶

from cortex_agents import CortexAgent
from cortex_agents.chart_utils import plot_charts

agent = CortexAgent()
response = agent.run("Show trend over time", agent_name="MY_AGENT", database="DB", schema="SCHEMA")

charts = response.get_charts()  # wait for streaming to complete
if charts:
    plot_charts(charts)  # renders all charts

Get Chart Metadata (Without Rendering)¶

from cortex_agents.chart_utils import get_chart_info

charts = response.get_charts()
info = get_chart_info(charts)

for chart_data in info:
    print(f"Title: {chart_data['title']}")
    print(f"Type: {chart_data['mark']}")  # "line", "bar", "scatter", etc.
    print(f"Fields: {chart_data['fields']}")
    print(f"Data Points: {chart_data['num_data_points']}")

Extract Raw Vega-Lite Specs¶

from cortex_agents.chart_utils import extract_chart_specs
import json

charts = response.get_charts()
specs = extract_chart_specs(charts)

for spec in specs:
    print(json.dumps(spec, indent=2))

Custom Chart Modifications¶

from cortex_agents.chart_utils import extract_chart_specs, plot_chart_dict

charts = response.get_charts()
specs = extract_chart_specs(charts)

for spec in specs:
    # Modify the spec
    spec['title'] = "My Custom Title"
    spec['config'] = {'background': '#f0f0f0'}

    # Plot the modified chart
    chart = plot_chart_dict(spec, interactive=True)
    display(chart)  # In Jupyter

Save Charts¶

import altair as alt
from cortex_agents.chart_utils import extract_chart_specs

specs = extract_chart_specs(response.get_charts())

for i, spec in enumerate(specs, 1):
    chart = alt.Chart.from_dict(spec)

    # Save as HTML
    chart.save(f"chart_{i}.html")

    # Save as JSON spec
    import json
    with open(f"chart_{i}.json", "w") as f:
        json.dump(spec, f, indent=2)

Chart Types¶

The agent can generate various Vega-Lite chart types:

Type	Use Case
`line`	Time series, trends
`bar`	Categorical comparisons
`scatter`	Correlations
`area`	Stacked values over time
`boxplot`	Distributions
`histogram`	Frequency distributions

Jupyter Integration¶

For best results in Jupyter notebooks:

import altair as alt
from IPython.display import display
from cortex_agents.chart_utils import plot_charts

# Allow large datasets
alt.data_transformers.enable('default', max_rows=None)

charts = response.get_charts()
chart_objects = plot_charts(charts)

for chart in chart_objects:
    display(chart)

Streamlit Integration¶

import json
from cortex_agents.chart_utils import plot_charts

chart_objects = plot_charts(charts, interactive=True, display_now=False)
for chart in chart_objects:
    st.vega_lite_chart(json.loads(chart.to_json()), use_container_width=True)

Troubleshooting¶

"Altair is required" error¶

pip install altair pandas

Charts not displaying in Jupyter¶

Try enabling a renderer explicitly:

import altair as alt
alt.renderers.enable('default')  # or 'colab', 'notebook', etc.

"No charts found"¶

Not all agent responses include charts. Charts are generated when:

Agent queries return tabular data suitable for visualization
Agent response indicates visualization is helpful
Query asks for trends, comparisons, or distributions

Try prompts like "Show me trends over time" or "Compare these values".

Custom Vega-Lite modifications¶

Common spec customizations:

spec['config'] = {
    'background': '#ffffff',
    'font': 'Arial'
}

spec['mark'] = {'type': 'line', 'point': True, 'color': 'darkblue'}

spec['encoding']['color'] = {
    'field': 'category',
    'type': 'nominal',
    'scale': {'scheme': 'category10'}
}

Full Vega-Lite documentation: https://vega.github.io/vega-lite/

Examples¶

See examples/example_streamlit_streaming.py and examples/example_streamlit_streaming_async.py for complete chart rendering examples.