Skip to content

Chart Utilities

cortex_agents.chart_utils.plot_charts 

plot_charts(charts: list[dict[str, Any]], interactive: bool = True, max_width: int = 900, max_height: int = 450, display_now: bool = True) -> list | None

Plot charts from agent response using Altair.

Parameters:

Name Type Description Default
charts list[dict[str, Any]]

List of chart dicts from response.get_charts()

 required
interactive bool

Enable interactive Altair features (default: True)

 True
max_width int

Maximum chart width in pixels (default: 900)

 900
max_height int

Maximum chart height in pixels (default: 600)

 450
display_now bool

Auto-display in Jupyter (default: True)

 True

Returns:

Type Description
list | None

List of Altair Chart objects (or None if Altair not installed)

Raises:

Type Description
ImportError

If Altair is not installed
ValueError

If charts list is empty or malformed

Examples: 

response = agent.run("Show dual eligible trend", agent_name="MY_AGENT", database="MY_DB", schema="MY_SCHEMA")
charts = response.get_charts()

if charts:
    plot_charts(charts)

Source code in cortex_agents/chart_utils.py 
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def plot_charts(
    charts: list[dict[str, Any]],
    interactive: bool = True,
    max_width: int = 900,
    max_height: int = 450,
    display_now: bool = True,
) -> list | None:
    """Plot charts from agent response using Altair.

    Args:
        charts: List of chart dicts from response.get_charts()
        interactive: Enable interactive Altair features (default: True)
        max_width: Maximum chart width in pixels (default: 900)
        max_height: Maximum chart height in pixels (default: 600)
        display_now: Auto-display in Jupyter (default: True)

    Returns:
        List of Altair Chart objects (or None if Altair not installed)

    Raises:
        ImportError: If Altair is not installed
        ValueError: If charts list is empty or malformed

    Examples:
    ```python
    response = agent.run("Show dual eligible trend", agent_name="MY_AGENT", database="MY_DB", schema="MY_SCHEMA")
    charts = response.get_charts()

    if charts:
        plot_charts(charts)
    ```
    """
    try:
        import altair as alt
    except ImportError as e:
        raise ImportError("Altair is required for chart plotting. Install it with: pip install altair pandas") from e

    if not charts:
        raise ValueError("No charts provided")

    chart_objects = []

    for i, chart_dict in enumerate(charts):
        try:
            # Extract Vega-Lite spec
            spec_str = chart_dict.get("chart_spec")
            if not spec_str:
                logger.warning(f"Chart {i + 1}: No chart_spec found")
                continue

            # Parse JSON spec
            spec = json.loads(spec_str)

            # Create Altair chart from Vega-Lite spec
            chart = alt.Chart.from_dict(spec)

            # Configure size
            chart = chart.properties(width=max_width, height=max_height)

            # Enable interactivity if requested
            if interactive:
                chart = chart.interactive()

            chart_objects.append(chart)

            logger.info(f"Chart {i + 1}: {spec.get('title', 'Untitled')} (rendered)")

            # Auto-display in Jupyter if requested
            if display_now:
                try:
                    from IPython.display import display

                    display(chart)
                except ImportError:
                    pass  # Not in Jupyter

        except json.JSONDecodeError as e:
            logger.error(f"Chart {i + 1}: Failed to parse chart_spec JSON: {e}")
        except Exception as e:
            logger.error(f"Chart {i + 1}: Error rendering chart: {e}")

    return chart_objects if chart_objects else None

cortex_agents.chart_utils.plot_chart_dict 

plot_chart_dict(chart_spec: dict[str, Any], interactive: bool = True, max_width: int = 900, max_height: int = 600) -> alt.Chart

Plot a single chart from a Vega-Lite specification dict.

Parameters:

Name Type Description Default
chart_spec dict[str, Any]

Vega-Lite specification dict

 required
interactive bool

Enable interactive features (default: True)

 True
max_width int

Maximum chart width in pixels

 900
max_height int

Maximum chart height in pixels

 600

Returns:

Type Description
Chart

Altair Chart object

Raises:

Type Description
ImportError

If Altair is not installed

Examples: 

        spec = {
            "mark": "line",
            "encoding": {
                "x": {"field": "month", "type": "temporal"},
                "y": {"field": "value", "type": "quantitative"}
            },
            "data": {"values": [...]}
        }
        plot_chart_dict(spec)
        To use it in Streamlit:
        ::

        chart_objects = plot_charts(charts, interactive=True)
            for i, chart in enumerate(chart_objects):
                st.vega_lite_chart(json.loads(chart.to_json()), width='stretch')

Source code in cortex_agents/chart_utils.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
def plot_chart_dict(
    chart_spec: dict[str, Any],
    interactive: bool = True,
    max_width: int = 900,
    max_height: int = 600,
) -> "alt.Chart":
    """Plot a single chart from a Vega-Lite specification dict.

    Args:
        chart_spec: Vega-Lite specification dict
        interactive: Enable interactive features (default: True)
        max_width: Maximum chart width in pixels
        max_height: Maximum chart height in pixels

    Returns:
        Altair Chart object

    Raises:
        ImportError: If Altair is not installed

    Examples:
    ```python

            spec = {
                "mark": "line",
                "encoding": {
                    "x": {"field": "month", "type": "temporal"},
                    "y": {"field": "value", "type": "quantitative"}
                },
                "data": {"values": [...]}
            }
            plot_chart_dict(spec)
            To use it in Streamlit:
            ::

            chart_objects = plot_charts(charts, interactive=True)
                for i, chart in enumerate(chart_objects):
                    st.vega_lite_chart(json.loads(chart.to_json()), width='stretch')
    ```
    """
    try:
        import altair as alt
    except ImportError as e:
        raise ImportError("Altair is required for chart plotting. Install it with: pip install altair pandas") from e

    chart = alt.Chart.from_dict(chart_spec)

    chart = chart.properties(width=max_width, height=max_height)

    if interactive:
        chart = chart.interactive()

    return chart

cortex_agents.chart_utils.extract_chart_specs 

extract_chart_specs(charts: list[dict[str, Any]]) -> list[dict]

Extract parsed Vega-Lite specs from chart dicts.

Parameters:

Name Type Description Default
charts list[dict[str, Any]]

List of chart dicts from response.get_charts()

 required

Returns:

Type Description
list[dict]

List of parsed Vega-Lite specification dicts

Examples: 

        charts = response.get_charts()
        specs = extract_chart_specs(charts)
        for spec in specs:
            print(spec["title"])

Source code in cortex_agents/chart_utils.py 
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
def extract_chart_specs(charts: list[dict[str, Any]]) -> list[dict]:
    """Extract parsed Vega-Lite specs from chart dicts.

    Args:
        charts: List of chart dicts from response.get_charts()

    Returns:
        List of parsed Vega-Lite specification dicts

    Examples:
    ```python

            charts = response.get_charts()
            specs = extract_chart_specs(charts)
            for spec in specs:
                print(spec["title"])
    ```
    """
    specs = []

    for chart in charts:
        try:
            spec_str = chart.get("chart_spec")
            if spec_str:
                spec = json.loads(spec_str)
                specs.append(spec)
        except json.JSONDecodeError:
            pass

    return specs

cortex_agents.chart_utils.get_chart_info 

get_chart_info(charts: list[dict[str, Any]]) -> list[dict[str, str]]

Get metadata about charts without rendering.

Parameters:

Name Type Description Default
charts list[dict[str, Any]]

List of chart dicts from response.get_charts()

 required

Returns:

Type Description
list[dict[str, str]]

List of dicts with chart info (title, mark, fields)

Examples: 

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

        for chart_info in info:
            print(f"Title: {chart_info['title']}")
            print(f"Type: {chart_info['mark']}")
            print(f"Fields: {chart_info['fields']}")

Source code in cortex_agents/chart_utils.py 
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
def get_chart_info(charts: list[dict[str, Any]]) -> list[dict[str, str]]:
    """Get metadata about charts without rendering.

    Args:
        charts: List of chart dicts from response.get_charts()

    Returns:
        List of dicts with chart info (title, mark, fields)

    Examples:
    ```python

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

            for chart_info in info:
                print(f"Title: {chart_info['title']}")
                print(f"Type: {chart_info['mark']}")
                print(f"Fields: {chart_info['fields']}")
    ```
    """
    info_list = []

    for i, chart in enumerate(charts):
        try:
            spec_str = chart.get("chart_spec")
            if not spec_str:
                continue

            spec = json.loads(spec_str)

            # Extract fields from encoding
            fields = set()
            if "encoding" in spec:
                for _encoding, config in spec["encoding"].items():
                    if "field" in config:
                        fields.add(config["field"])

            info = {
                "index": i,
                "title": spec.get("title", "Untitled"),
                "mark": spec.get("mark", "unknown"),
                "fields": sorted(fields),
                "num_data_points": len(spec.get("data", {}).get("values", [])),
            }
            info_list.append(info)

        except (json.JSONDecodeError, KeyError):
            pass

    return info_list

cortex_agents.chart_utils.chart_to_json 

chart_to_json(chart_spec: dict[str, Any], pretty: bool = True) -> str

Convert chart spec to JSON string.

Parameters:

Name Type Description Default
chart_spec dict[str, Any]

Vega-Lite specification dict

 required
pretty bool

Pretty-print JSON (default: True)

 True

Returns:

Type Description
str

JSON string
Source code in cortex_agents/chart_utils.py 
243
244
245
246
247
248
249
250
251
252
253
254
255
256
def chart_to_json(chart_spec: dict[str, Any], pretty: bool = True) -> str:
    """Convert chart spec to JSON string.

    Args:
        chart_spec: Vega-Lite specification dict
        pretty: Pretty-print JSON (default: True)

    Returns:
        JSON string
    """
    if pretty:
        return json.dumps(chart_spec, indent=2)
    else:
        return json.dumps(chart_spec)