Skip to main content

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.

Metadata

Release files for MatplotLibAPI 4.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for MatplotLibAPI 4.2.0
File Size Uploaded Provenance Actions
matplotlibapi-4.2.0.tar.gz 97.2 kB Without provenance Details for matplotlibapi-4.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for MatplotLibAPI 4.2.0
File Interpreter ABI Platform Actions
matplotlibapi-4.2.0-py3-none-any.whl Python 3 none any Details for matplotlibapi-4.2.0-py3-none-any.whl

Total release size: 179.1 kB

Release files / matplotlibapi-4.2.0.tar.gz

Download URL matplotlibapi-4.2.0.tar.gz
Size 97.2 kB
Tags Source
SHA-256 checksum
How to use checksums
09794370586ae15a172236b6ae3b0632de7f6063fade7eeecd39ee1a6b5f8905
BLAKE2b-256 checksum
How to use checksums
f5cf054f2cee5c44a1982a699a50eeb90745db3858e9e6137a0f7a18994cd427
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Release files / matplotlibapi-4.2.0-py3-none-any.whl

Download URL matplotlibapi-4.2.0-py3-none-any.whl
Size 82.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
018eb7cbfc7c8fb9291d8a6b6a86f091fa17167f6d21417c1f8b4a9601a85300
BLAKE2b-256 checksum
How to use checksums
229f1cb8adbd67cef121898d9e77b0523b468036716fc32d9fe91cd7eab0b740
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.14

Security for MatplotLibAPI 4.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

4.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page