# plot2llm
> **Beta Notice:** This library is currently in beta. The API may change in future releases. Please report any issues or suggestions!
Convert Python figures (matplotlib, seaborn) to LLM-readable formats
---
## Introduction & Motivation
**Plot2LLM** is a Python library designed to bridge the gap between data visualization and AI. It analyzes and converts figures from matplotlib and seaborn into structured, LLM-friendly text or JSON. This enables:
- Automated documentation of plots
- Feeding plot information to Large Language Models (LLMs)
- Building explainable AI pipelines
- Generating technical summaries for reports
---
## Supported Features
- **Matplotlib support:**
- Line, scatter, bar, histogram, box, violin, and more
- Multi-axes and subplots
- Extraction of axes, labels, data, colors, statistics
- **Seaborn support:**
- Common plot types: scatter, line, box, violin, histogram, FacetGrid, PairPlot, etc.
- Automatic detection of seaborn-specific features
- **Output formats:**
- `'text'`: Human-readable technical summary
- `'json'`: Structured JSON/dict
- `'semantic'`: LLM-optimized dict with standard keys
- **Error handling:**
- Graceful handling of invalid figures or unsupported formats
- **Extensible:**
- Add your own formatters or analyzers
---
## Roadmap / Pending Features
- [ ] **Plotly, Bokeh, Altair support** (planned)
- [ ] **Interactive plot extraction**
- [ ] **Image-based plot analysis**
- [ ] **More advanced statistics and trend detection**
- [ ] **Better support for custom matplotlib artists**
- [ ] **Jupyter notebook integration**
- [ ] **Export to Markdown/HTML**
---
## Installation
```bash
pip install plot2llm
```
Or, for local development:
```bash
git clone <repo-url>
cd plot2llm
pip install -e .
```
---
## Quick Start
```python
import matplotlib.pyplot as plt
from plot2llm import FigureConverter
fig, ax = plt.subplots()
ax.plot([1, 2, 3], [2, 4, 6])
ax.set_title('Demo Plot')
converter = FigureConverter()
text_result = converter.convert(fig, 'text')
print(text_result)
```
---
## Detailed Usage
### Matplotlib Example
```python
import matplotlib.pyplot as plt
from plot2llm import FigureConverter
fig, ax = plt.subplots()
ax.bar(['A', 'B', 'C'], [10, 20, 15], color='skyblue')
ax.set_title('Bar Example')
ax.set_xlabel('Category')
ax.set_ylabel('Value')
converter = FigureConverter()
print(converter.convert(fig, 'text'))
```
### Seaborn Example
```python
import seaborn as sns
import matplotlib.pyplot as plt
from plot2llm import FigureConverter
iris = sns.load_dataset('iris')
fig, ax = plt.subplots()
sns.scatterplot(data=iris, x='sepal_length', y='sepal_width', hue='species', ax=ax)
ax.set_title('Iris Scatter')
converter = FigureConverter()
print(converter.convert(fig, 'text'))
```
### Using Different Formatters
```python
from plot2llm.formatters import TextFormatter, JSONFormatter, SemanticFormatter
formatter = TextFormatter()
result = converter.convert(fig, formatter)
print(result)
formatter = JSONFormatter()
result = converter.convert(fig, formatter)
print(result)
formatter = SemanticFormatter()
result = converter.convert(fig, formatter)
print(result)
```
---
## Example Outputs
**Text format:**
```
Plot types in figure: line
Figure type: matplotlib.Figure
Dimensions (inches): [8.0, 6.0]
Title: Demo Plot
Number of axes: 1
...
```
**JSON format:**
```json
{
"figure_type": "matplotlib",
"title": "Demo Plot",
"axes": [...],
...
}
```
**Semantic format:**
```json
{
"figure_type": "matplotlib",
"title": "Demo Plot",
"axes": [...],
"figure_info": {...},
"plot_description": "This is a matplotlib visualization titled 'Demo Plot'. It contains 1 subplot(s). Subplot 1 contains: line."
}
```
---
## API Reference (Summary)
### `FigureConverter`
- `convert(figure, output_format='text')`: Convert a figure to the specified format. `output_format` can be `'text'`, `'json'`, `'semantic'`, or a custom formatter object.
- `register_analyzer(name, analyzer)`: Add a custom analyzer.
- `register_formatter(name, formatter)`: Add a custom formatter.
### Formatters
- `TextFormatter`: Returns a technical, human-readable summary.
- `JSONFormatter`: Returns a structured dict (JSON-serializable).
- `SemanticFormatter`: Returns a dict optimized for LLMs, with standard keys.
---
## Changelog / Bugfixes
- Fixed: Output formats like `'text'` now return the full formatted result, not just the format name
- Improved: Seaborn analyzer supports all major plot types
- Consistent: Output structure for all formatters
---
## Contributing
Pull requests and issues are welcome! Please see the [docs/](docs/) folder for API reference and contribution guidelines.
---
## License
MIT License
---
## Contact & Links
- GitHub: [https://github.com/plot2llm/plot2llm](https://github.com/plot2llm/plot2llm)
- Issues: [https://github.com/plot2llm/plot2llm/issues](https://github.com/plot2llm/plot2llm/issues)
Raw data
{
"_id": null,
"home_page": "https://github.com/plot2llm/plot2llm",
"name": "plot2llm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Tu Nombre <tu-email@ejemplo.com>",
"keywords": "visualization, llm, matplotlib, seaborn, plotly, data-analysis, machine-learning",
"author": "Plot2LLM Team",
"author_email": "Tu Nombre <tu-email@ejemplo.com>",
"download_url": "https://files.pythonhosted.org/packages/60/8a/f3f21b1f0dc50ccb55e7844ff8068aa66c52628273bd8739dc7cc3f7794f/plot2llm-0.1.17.tar.gz",
"platform": null,
"description": "# plot2llm\r\n\r\n> **Beta Notice:** This library is currently in beta. The API may change in future releases. Please report any issues or suggestions!\r\n\r\nConvert Python figures (matplotlib, seaborn) to LLM-readable formats\r\n\r\n---\r\n\r\n## Introduction & Motivation\r\n\r\n**Plot2LLM** is a Python library designed to bridge the gap between data visualization and AI. It analyzes and converts figures from matplotlib and seaborn into structured, LLM-friendly text or JSON. This enables:\r\n- Automated documentation of plots\r\n- Feeding plot information to Large Language Models (LLMs)\r\n- Building explainable AI pipelines\r\n- Generating technical summaries for reports\r\n\r\n---\r\n\r\n## Supported Features\r\n\r\n- **Matplotlib support:**\r\n - Line, scatter, bar, histogram, box, violin, and more\r\n - Multi-axes and subplots\r\n - Extraction of axes, labels, data, colors, statistics\r\n- **Seaborn support:**\r\n - Common plot types: scatter, line, box, violin, histogram, FacetGrid, PairPlot, etc.\r\n - Automatic detection of seaborn-specific features\r\n- **Output formats:**\r\n - `'text'`: Human-readable technical summary\r\n - `'json'`: Structured JSON/dict\r\n - `'semantic'`: LLM-optimized dict with standard keys\r\n- **Error handling:**\r\n - Graceful handling of invalid figures or unsupported formats\r\n- **Extensible:**\r\n - Add your own formatters or analyzers\r\n\r\n---\r\n\r\n## Roadmap / Pending Features\r\n\r\n- [ ] **Plotly, Bokeh, Altair support** (planned)\r\n- [ ] **Interactive plot extraction**\r\n- [ ] **Image-based plot analysis**\r\n- [ ] **More advanced statistics and trend detection**\r\n- [ ] **Better support for custom matplotlib artists**\r\n- [ ] **Jupyter notebook integration**\r\n- [ ] **Export to Markdown/HTML**\r\n\r\n---\r\n\r\n## Installation\r\n\r\n```bash\r\npip install plot2llm\r\n```\r\n\r\nOr, for local development:\r\n\r\n```bash\r\ngit clone <repo-url>\r\ncd plot2llm\r\npip install -e .\r\n```\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n```python\r\nimport matplotlib.pyplot as plt\r\nfrom plot2llm import FigureConverter\r\n\r\nfig, ax = plt.subplots()\r\nax.plot([1, 2, 3], [2, 4, 6])\r\nax.set_title('Demo Plot')\r\n\r\nconverter = FigureConverter()\r\ntext_result = converter.convert(fig, 'text')\r\nprint(text_result)\r\n```\r\n\r\n---\r\n\r\n## Detailed Usage\r\n\r\n### Matplotlib Example\r\n\r\n```python\r\nimport matplotlib.pyplot as plt\r\nfrom plot2llm import FigureConverter\r\n\r\nfig, ax = plt.subplots()\r\nax.bar(['A', 'B', 'C'], [10, 20, 15], color='skyblue')\r\nax.set_title('Bar Example')\r\nax.set_xlabel('Category')\r\nax.set_ylabel('Value')\r\n\r\nconverter = FigureConverter()\r\nprint(converter.convert(fig, 'text'))\r\n```\r\n\r\n### Seaborn Example\r\n\r\n```python\r\nimport seaborn as sns\r\nimport matplotlib.pyplot as plt\r\nfrom plot2llm import FigureConverter\r\n\r\niris = sns.load_dataset('iris')\r\nfig, ax = plt.subplots()\r\nsns.scatterplot(data=iris, x='sepal_length', y='sepal_width', hue='species', ax=ax)\r\nax.set_title('Iris Scatter')\r\n\r\nconverter = FigureConverter()\r\nprint(converter.convert(fig, 'text'))\r\n```\r\n\r\n### Using Different Formatters\r\n\r\n```python\r\nfrom plot2llm.formatters import TextFormatter, JSONFormatter, SemanticFormatter\r\n\r\nformatter = TextFormatter()\r\nresult = converter.convert(fig, formatter)\r\nprint(result)\r\n\r\nformatter = JSONFormatter()\r\nresult = converter.convert(fig, formatter)\r\nprint(result)\r\n\r\nformatter = SemanticFormatter()\r\nresult = converter.convert(fig, formatter)\r\nprint(result)\r\n```\r\n\r\n---\r\n\r\n## Example Outputs\r\n\r\n**Text format:**\r\n```\r\nPlot types in figure: line\r\nFigure type: matplotlib.Figure\r\nDimensions (inches): [8.0, 6.0]\r\nTitle: Demo Plot\r\nNumber of axes: 1\r\n...\r\n```\r\n\r\n**JSON format:**\r\n```json\r\n{\r\n \"figure_type\": \"matplotlib\",\r\n \"title\": \"Demo Plot\",\r\n \"axes\": [...],\r\n ...\r\n}\r\n```\r\n\r\n**Semantic format:**\r\n```json\r\n{\r\n \"figure_type\": \"matplotlib\",\r\n \"title\": \"Demo Plot\",\r\n \"axes\": [...],\r\n \"figure_info\": {...},\r\n \"plot_description\": \"This is a matplotlib visualization titled 'Demo Plot'. It contains 1 subplot(s). Subplot 1 contains: line.\"\r\n}\r\n```\r\n\r\n---\r\n\r\n## API Reference (Summary)\r\n\r\n### `FigureConverter`\r\n- `convert(figure, output_format='text')`: Convert a figure to the specified format. `output_format` can be `'text'`, `'json'`, `'semantic'`, or a custom formatter object.\r\n- `register_analyzer(name, analyzer)`: Add a custom analyzer.\r\n- `register_formatter(name, formatter)`: Add a custom formatter.\r\n\r\n### Formatters\r\n- `TextFormatter`: Returns a technical, human-readable summary.\r\n- `JSONFormatter`: Returns a structured dict (JSON-serializable).\r\n- `SemanticFormatter`: Returns a dict optimized for LLMs, with standard keys.\r\n\r\n---\r\n\r\n## Changelog / Bugfixes\r\n\r\n- Fixed: Output formats like `'text'` now return the full formatted result, not just the format name\r\n- Improved: Seaborn analyzer supports all major plot types\r\n- Consistent: Output structure for all formatters\r\n\r\n---\r\n\r\n## Contributing\r\n\r\nPull requests and issues are welcome! Please see the [docs/](docs/) folder for API reference and contribution guidelines.\r\n\r\n---\r\n\r\n## License\r\n\r\nMIT License\r\n\r\n---\r\n\r\n## Contact & Links\r\n\r\n- GitHub: [https://github.com/plot2llm/plot2llm](https://github.com/plot2llm/plot2llm)\r\n- Issues: [https://github.com/plot2llm/plot2llm/issues](https://github.com/plot2llm/plot2llm/issues)\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Convert figures from visualization libraries into formats optimized for Large Language Models (LLMs)",
"version": "0.1.17",
"project_urls": {
"Bug Tracker": "https://github.com/tu-usuario/plot2llm/issues",
"Documentation": "https://plot2llm.readthedocs.io",
"Download": "https://pypi.org/project/plot2llm/#files",
"Homepage": "https://github.com/tu-usuario/plot2llm",
"Repository": "https://github.com/tu-usuario/plot2llm.git",
"Source Code": "https://github.com/tu-usuario/plot2llm"
},
"split_keywords": [
"visualization",
" llm",
" matplotlib",
" seaborn",
" plotly",
" data-analysis",
" machine-learning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b0ca56b6cba9b18c9115714f1bca6b954ad1e4a9f1ae1cb10339dae64bd4a06d",
"md5": "b57d636146e63bfa82f79c4b5c8872b3",
"sha256": "7cc8bfe5c3d916486c8d3fddf5f9abb9d5685b3d823d54950f1c6d119a1cdd73"
},
"downloads": -1,
"filename": "plot2llm-0.1.17-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b57d636146e63bfa82f79c4b5c8872b3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 31694,
"upload_time": "2025-07-17T14:43:55",
"upload_time_iso_8601": "2025-07-17T14:43:55.805100Z",
"url": "https://files.pythonhosted.org/packages/b0/ca/56b6cba9b18c9115714f1bca6b954ad1e4a9f1ae1cb10339dae64bd4a06d/plot2llm-0.1.17-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "608af3f21b1f0dc50ccb55e7844ff8068aa66c52628273bd8739dc7cc3f7794f",
"md5": "86fc55b5e12dcdb1ae44092fb96c4c40",
"sha256": "2a572de948995b92f50d81d6578a4db721e357c4455629e5baf14eea1fdaef84"
},
"downloads": -1,
"filename": "plot2llm-0.1.17.tar.gz",
"has_sig": false,
"md5_digest": "86fc55b5e12dcdb1ae44092fb96c4c40",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 32128,
"upload_time": "2025-07-17T14:43:56",
"upload_time_iso_8601": "2025-07-17T14:43:56.725677Z",
"url": "https://files.pythonhosted.org/packages/60/8a/f3f21b1f0dc50ccb55e7844ff8068aa66c52628273bd8739dc7cc3f7794f/plot2llm-0.1.17.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-17 14:43:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "plot2llm",
"github_project": "plot2llm",
"github_not_found": true,
"lcname": "plot2llm"
}
JSON
