MatplotLibAPI

MatplotLibAPI is a typed, local-first plotting engine for pandas users, Python applications, plugins, CLIs, and AI agents. It provides a small stable plotting API plus one schema-driven execution contract that can be discovered and used without credentials or hosted services.

Installation

pip install MatplotLibAPI

Install optional MCP support with:

pip install "MatplotLibAPI[mcp]"

Python quick start

import pandas as pd
from MatplotLibAPI import fplot_bar

sales = pd.DataFrame(
    {
        "product": ["A", "A", "B", "B"],
        "region": ["North", "South", "North", "South"],
        "revenue": [12, 9, 15, 11],
    }
)

figure = fplot_bar(
    sales,
    category="product",
    value="revenue",
    group="region",
    stacked=True,
)

Canonical plot specification

PlotSpec is the portable contract shared by Python, plugins, the CLI, MCP, Codex, and generated OpenAI tool definitions.

import pandas as pd
from MatplotLibAPI import PlotSpec, execute_plot

sales = pd.DataFrame(
    {
        "product": ["A", "B"],
        "revenue": [12, 15],
    }
)

spec = PlotSpec.from_dict(
    {
        "chart": "bar",
        "encoding": {
            "category": "product",
            "value": "revenue",
        },
        "options": {"stacked": False},
        "output": {"format": "png", "path": "charts/revenue.png"},
    }
)

result = execute_plot(spec, sales)
print(result.to_dict())

The executor validates chart names, parameters, referenced columns, local paths, input dimensions, and output size before returning a RenderResult.

Discovery and plugins

from MatplotLibAPI import create_registry, openai_tool_definitions

registry = create_registry()
print(registry.context.list_plots())
print(registry.context.describe_plot("bar"))
print(openai_tool_definitions(registry=registry))

Each registered plot has one PlotDescriptor containing its callable, parameter schema, backend, capabilities, aliases, examples, and supported output formats. Legacy plugin API version 1 remains accepted; new plugins use version 2.

Command line

matplotlibapi plots list
matplotlibapi plots describe bar
matplotlibapi schema plot-spec
matplotlibapi schema openai-tools
matplotlibapi inspect data.csv
matplotlibapi recommend data.csv
matplotlibapi validate plot.json
matplotlibapi render plot.json --data data.csv --output chart.png
matplotlibapi doctor
matplotlibapi test
matplotlibapi eval
matplotlibapi benchmark

All file operations are constrained to --workspace by default. Absolute paths and workspace traversal are rejected unless an embedding application explicitly uses a more permissive RenderPolicy.

MCP

Start the optional stdio server with:

matplotlibapi-mcp

The MCP generic renderer and dedicated tools use the same canonical executor and registry metadata. describe_plot_modules also returns plot descriptors and OpenAI-compatible tool schemas.

Stable package-root API

Contracts and execution

PLOT_SPEC_SCHEMA_VERSION
DataSource
OutputSpec
PlotSpec
PlotValidationError
ValidationIssue
RenderPolicy
RenderResult
execute_plot
validate_plot_request
inspect_dataframe
recommend_plot
migrate_plot_spec
openai_tool_definitions

Plugin surface

PLUGIN_API_VERSION
Plugin
PluginContext
PluginRegistry
PlotDescriptor
CorePlotsPlugin
create_registry
infer_plot_descriptor

Plotting helpers

fplot_area
fplot_bar
fplot_box_violin
fplot_correlation_matrix
fplot_heatmap
fplot_histogram_kde
fplot_pie_donut
fplot_sankey
fplot_sunburst
fplot_table
fplot_timeserie
fplot_timeseries
fplot_treemap
fplot_waffle
fplot_wordcloud

Other types

CorrelationMethod
DataFrameAccessor

Specialized object APIs remain available from their modules:

from MatplotLibAPI.bubble import Bubble
from MatplotLibAPI.network import NetworkGraph
from MatplotLibAPI.Pivot import plot_pivoted_bars

Deterministic evaluations

The agent evaluation baseline requires no LLM, network access, API keys, or credentials:

matplotlibapi eval
python scripts/benchmark_agent_plotting.py

It covers chart recommendations, invalid specification rejection, profiling, schema discovery, and local performance budgets.

Development

black --check src tests scripts
pydocstyle src scripts
pyright
pytest --cov=MatplotLibAPI --cov-report=term-missing
python -m build
python -m twine check dist/*

See docs/PLOT_SPEC.md, docs/API_REFERENCE.md, docs/AGENT_EVALS.md, and CONTRIBUTING.md for the complete contracts.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

matplotlibapi-4.2.0.tar.gz (97.2 kB view details)

Uploaded Aug 6, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

matplotlibapi-4.2.0-py3-none-any.whl (82.0 kB view details)

Uploaded Aug 6, 2026 Python 3

File details

Details for the file matplotlibapi-4.2.0.tar.gz.

File metadata

Download URL: matplotlibapi-4.2.0.tar.gz
Upload date: Aug 6, 2026
Size: 97.2 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for matplotlibapi-4.2.0.tar.gz
Algorithm	Hash digest
SHA256	`09794370586ae15a172236b6ae3b0632de7f6063fade7eeecd39ee1a6b5f8905`
MD5	`c911edff0f44eb34ec85e09108ad6001`
BLAKE2b-256	`f5cf054f2cee5c44a1982a699a50eeb90745db3858e9e6137a0f7a18994cd427`

See more details on using hashes here.

File details

Details for the file matplotlibapi-4.2.0-py3-none-any.whl.

File metadata

Download URL: matplotlibapi-4.2.0-py3-none-any.whl
Upload date: Aug 6, 2026
Size: 82.0 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for matplotlibapi-4.2.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`018eb7cbfc7c8fb9291d8a6b6a86f091fa17167f6d21417c1f8b4a9601a85300`
MD5	`e5779269e6f31c4f40d20f4aa8498a8e`
BLAKE2b-256	`229f1cb8adbd67cef121898d9e77b0523b468036716fc32d9fe91cd7eab0b740`