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_VERSIONDataSourceOutputSpecPlotSpecPlotValidationErrorValidationIssueRenderPolicyRenderResultexecute_plotvalidate_plot_requestinspect_dataframerecommend_plotmigrate_plot_specopenai_tool_definitions
Plugin surface
PLUGIN_API_VERSIONPluginPluginContextPluginRegistryPlotDescriptorCorePlotsPlugincreate_registryinfer_plot_descriptor
Plotting helpers
fplot_areafplot_barfplot_box_violinfplot_correlation_matrixfplot_heatmapfplot_histogram_kdefplot_pie_donutfplot_sankeyfplot_sunburstfplot_tablefplot_timeseriefplot_timeseriesfplot_treemapfplot_wafflefplot_wordcloud
Other types
CorrelationMethodDataFrameAccessor
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.