Chart Builder

Generate charts from tabular data via the bundled scripts/charts.py toolkit. Each function takes a DataFrame or a file path plus the columns to plot, and saves a PNG (returning the path). It handles theming, figure sizing, label rotation, NaN dropping, legend placement, and saving.

Instructions

1. Provide the data source: a pandas DataFrame, or a path to a .csv / .tsv / .json file.
2. Call the function for the chart you need, passing the column names:
   • bar(data, x, y) — one value per category (horizontal=True for barh)
   • grouped_bar(data, x, y, group) — value per category split by group (stacked=True to stack)
   • line(data, x, y, group=None) — value over an ordered axis, one line per group
   • scatter(data, x, y, group=None, size=None) — two numeric columns
   • histogram(data, y, bins=20, group=None) — distribution of one column
   • pie(data, x, y, donut=False) — share of y per category x
3. Optional keyword args on every chart: title, xlabel, ylabel (derived from column names if omitted), out (default "chart.png"; pass None to skip saving), dpi (default 150), figsize, palette.
4. The function returns the saved image path. See references/cheatsheet.md for full signatures and a chart-selection table.

Usage

Import:

from charts import bar, line, pie
bar("sales.csv", x="region", y="revenue", title="Revenue by region",
    out="revenue.png")

CLI:

python scripts/charts.py grouped_bar sales.csv \
    --x region --y revenue --group quarter --stacked --out by_quarter.png

Bundled files

• scripts/charts.py — the toolkit: load_data, apply_theme, save_fig, and six chart functions (bar, grouped_bar, line, scatter, histogram, pie), plus a CLI. Depends on matplotlib and pandas; runs headless.
• references/cheatsheet.md — chart-selection table, full signatures, and copy-paste CLI examples.
• assets/sample_sales.csv — a small demo dataset that exercises every chart.

Defaults

• Colorblind-friendly palette and a shared theme across charts.
• Figure size, x-label rotation, and legend placement adapt to the data.
• Rows with missing values in the plotted columns are dropped before drawing.
• Output is a saved PNG at 150 DPI by default (override out and dpi).

Run this — do not improvise

This capability's deterministic implementation is a RAPP single-file agent, linked beside this file as chart_builder_agent.py and embedded as the fenced Python below (sha256 f0e78a1c34b818da…; a byte-exact copy is also vaulted in the capsule comment at the end of this file). On a host with sandbox execution, run the linked file directly — if it is missing, write the fence contents verbatim to chart_builder_agent.py first:

python3 chart_builder_agent.py '{"key": "value"}'      # arguments as one JSON object
echo '{"key": "value"}' | python3 chart_builder_agent.py   # or on stdin
python3 chart_builder_agent.py --tool                      # emit the JSON tool contract

Treat stdout as a tool result. If it reports missing or unresolved inputs, stop and collect them. If it returns steps, execute those steps in order exactly as returned; if it returns instructions, follow them with the supplied inputs. Otherwise use the result verbatim. Do not invent behavior beyond that output. On a host without code execution, treat the Parameters schema and the code below as the exact specification and never paraphrase a step. Never edit inside the generated markers; a converter-equipped host can instead restore the original file checksum-verified with the installed rapp-agent-converter/scripts/toast.py convert SKILL.md --to agent.

"""ChartBuilder -- Use this skill whenever the user asks to visualize, chart, plot, or graph data (bar, line, scatter, histogram, pie) from a CSV, table, or DataFrame. It gives the agent prebuilt, parameterized matplotlib functions so charts are produced faster and more reliably — with consistent styling and sane defaults — instead of hand-writing matplotlib each time.

Generated by the rapp skill from chart-builder. The RCI capsule at the bottom of this file carries the full original; `toast.py convert` restores it byte-exact."""

import json
import re
import sys

try:
    from agents.basic_agent import BasicAgent
except ImportError:  # running OUTSIDE a brainstem -- stay executable anyway.
    class BasicAgent:  # noqa: D101 - minimal stand-in, same contract
        def __init__(self, name=None, metadata=None):
            if name:
                self.name = name
            if metadata:
                self.metadata = metadata

        def perform(self, **kwargs):
            return "Not implemented."

        def system_context(self):
            return None

        def to_tool(self):
            return {"type": "function", "function": {
                "name": self.name,
                "description": self.metadata.get("description", ""),
                "parameters": self.metadata.get("parameters", {})}}

# The procedural layer, verbatim from the source capability.
INSTRUCTIONS = 'Generate charts from tabular data via the bundled `scripts/charts.py` toolkit.\nEach function takes a DataFrame or a file path plus the columns to plot, and\nsaves a PNG (returning the path). It handles theming, figure sizing, label\nrotation, NaN dropping, legend placement, and saving.\n\n## Instructions\n1. Provide the data source: a pandas DataFrame, or a path to a `.csv` / `.tsv` /\n   `.json` file.\n2. Call the function for the chart you need, passing the column names:\n   - `bar(data, x, y)` — one value per category (`horizontal=True` for barh)\n   - `grouped_bar(data, x, y, group)` — value per category split by `group`\n     (`stacked=True` to stack)\n   - `line(data, x, y, group=None)` — value over an ordered axis, one line per\n     `group`\n   - `scatter(data, x, y, group=None, size=None)` — two numeric columns\n   - `histogram(data, y, bins=20, group=None)` — distribution of one column\n   - `pie(data, x, y, donut=False)` — share of `y` per category `x`\n3. Optional keyword args on every chart: `title`, `xlabel`, `ylabel` (derived\n   from column names if omitted), `out` (default `"chart.png"`; pass `None` to\n   skip saving), `dpi` (default `150`), `figsize`, `palette`.\n4. The function returns the saved image path. See `references/cheatsheet.md` for\n   full signatures and a chart-selection table.\n\n## Usage\nImport:\n```python\nfrom charts import bar, line, pie\nbar("sales.csv", x="region", y="revenue", title="Revenue by region",\n    out="revenue.png")\n```\n\nCLI:\n```bash\npython scripts/charts.py grouped_bar sales.csv \\\n    --x region --y revenue --group quarter --stacked --out by_quarter.png\n```\n\n## Bundled files\n- `scripts/charts.py` — the toolkit: `load_data`, `apply_theme`, `save_fig`, and\n  six chart functions (`bar`, `grouped_bar`, `line`, `scatter`, `histogram`,\n  `pie`), plus a CLI. Depends on `matplotlib` and `pandas`; runs headless.\n- `references/cheatsheet.md` — chart-selection table, full signatures, and\n  copy-paste CLI examples.\n- `assets/sample_sales.csv` — a small demo dataset that exercises every chart.\n\n## Defaults\n- Colorblind-friendly palette and a shared theme across charts.\n- Figure size, x-label rotation, and legend placement adapt to the data.\n- Rows with missing values in the plotted columns are dropped before drawing.\n- Output is a saved PNG at 150 DPI by default (override `out` and `dpi`).'

# Ordered commands lifted verbatim from the capability's own documentation.
STEPS = []


class ChartBuilderAgent(BasicAgent):
    def __init__(self):
        self.name = 'ChartBuilder'
        self.metadata = {
          "name": "ChartBuilder",
          "description": "Use this skill whenever the user asks to visualize, chart, plot, or graph data (bar, line, scatter, histogram, pie) from a CSV, table, or DataFrame. It gives the agent prebuilt, parameterized matplotlib functions so charts are produced faster and more reliably \u2014 with consistent styling and sane defaults \u2014 instead of hand-writing matplotlib each time.",
          "parameters": {
            "type": "object",
            "properties": {},
            "required": []
          }
        }
        super().__init__(name=self.name, metadata=self.metadata)

    def perform(self, **kwargs):  # toaster:generated-perform
        return json.dumps({"status": "ok", "instructions": INSTRUCTIONS,
                           "inputs": kwargs,
                           "note": "Prose-only capability: follow INSTRUCTIONS "
                                   "with the given inputs."}, indent=2)

if __name__ == "__main__":
    #     echo '{"arg": "value"}' | python3 chart_builder_agent.py
    #     python3 chart_builder_agent.py '{"arg": "value"}'
    #     python3 chart_builder_agent.py --tool          # emit the JSON tool contract
    _a = sys.argv[1:]
    if _a and _a[0] == "--tool":
        print(json.dumps(ChartBuilderAgent().to_tool(), indent=2))
    else:
        _raw = _a[0] if _a else (sys.stdin.read().strip() or "{}")
        print(ChartBuilderAgent().perform(**json.loads(_raw)))

# rci-capsule:v1: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