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 and Plotly static-export support with:

pip install "MatplotLibAPI[mcp]"
pip install "MatplotLibAPI[plotly-export]"

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},
        "presentation": {
            "accessibility": "colorblind",
            "number_format": "currency",
            "currency": "EUR",
            "alt_text": "Revenue by product.",
        },
        "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. Plugin API version 2 is canonical; version 1 remains accepted during the documented 4.x compatibility window.

Create and validate a third-party plugin with:

matplotlibapi plugins scaffold example-plugin ./example-plugin
matplotlibapi plugins conform

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 repair plot.json --data data.csv
matplotlibapi presets list
matplotlibapi migrate plot.json
matplotlibapi compatibility
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. MCP also exposes bounded profiling, ranked recommendations, repair suggestions, and compatibility status. describe_plot_modules returns plot descriptors and OpenAI-compatible tool schemas.

Data-aware intelligence

import pandas as pd
from MatplotLibAPI import PlotSpec, profile_dataframe, recommend_plots

frame = pd.DataFrame(
    {
        "date": pd.to_datetime(["2026-01-01", "2026-02-01"]),
        "revenue": [100, 125],
    }
)
profile = profile_dataframe(frame)
recommendations = recommend_plots(profile)
spec = PlotSpec.from_dict(
    {
        "chart": recommendations[0].chart,
        "encoding": recommendations[0].encoding,
    }
)

Profiles are bounded and deterministic. Recommendations include scores, reasons, and warnings. Repair suggestions are opt-in and never mutate the source spec.

Canonical time-series API and 5.0 preparation

timeseries and fplot_timeseries are canonical. The historic timeserie spelling remains available until the executable compatibility gate permits a 5.0 removal after 2027-02-06. Use matplotlibapi migrate before that boundary.

Stable package-root API

Contracts and execution

  • PLOT_SPEC_SCHEMA_VERSION
  • DataSource
  • OutputSpec
  • PresentationSpec
  • PlotSpec
  • PlotValidationError
  • ValidationIssue
  • RenderPolicy
  • RenderResult
  • execute_plot
  • validate_plot_request
  • inspect_dataframe
  • recommend_plot
  • profile_dataframe
  • recommend_plots
  • suggest_plot_spec_repairs
  • apply_repair_suggestions
  • migrate_plot_spec
  • migrate_plot_spec_for_v5
  • v5_compatibility_status
  • openai_tool_definitions

Plugin surface

  • PLUGIN_API_VERSION
  • Plugin
  • PluginContext
  • PluginRegistry
  • PlotDescriptor
  • CorePlotsPlugin
  • create_registry
  • infer_plot_descriptor
  • validate_plugin_conformance
  • validate_registry_conformance
  • write_plugin_scaffold

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_timeseries (canonical)
  • fplot_timeserie (compatibility alias)
  • 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 explained chart recommendations, invalid specification rejection, bounded profiling, opt-in repair suggestions, plugin conformance, 5.0 migration gates, 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/DATA_INTELLIGENCE.md, docs/PLUGIN_ECOSYSTEM.md, docs/MIGRATING_TO_5.md, docs/API_REFERENCE.md, and CONTRIBUTING.md for the complete contracts.

Metadata

Release files for MatplotLibAPI 4.4.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.4.0
File Size Uploaded Provenance Actions
matplotlibapi-4.4.0.tar.gz 116.3 kB Without provenance Details for matplotlibapi-4.4.0.tar.gz

Built distribution (wheel)

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

Total release size: 212.4 kB

Release files / matplotlibapi-4.4.0.tar.gz

Download URL matplotlibapi-4.4.0.tar.gz
Size 116.3 kB
Tags Source
SHA-256 checksum
How to use checksums
d298d5975575ade5cab90aff7d0fe3eaaff897aaf1fd42992c00a9de15dafb57
BLAKE2b-256 checksum
How to use checksums
5b361766fcc195b23528f5cf7af1feae33e381cf88ff1947d806d8c3f89a55f8
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.4.0-py3-none-any.whl

Download URL matplotlibapi-4.4.0-py3-none-any.whl
Size 96.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fc788dd11a2090ac97bda7772251bd5baa0ca67886926da70e7755ff0954f6d8
BLAKE2b-256 checksum
How to use checksums
bfb71e942443a2496edb2fed3241b43c72409649174e06979c5307299ad25d79
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.4.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.4.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