<p align="center">
<img src="https://raw.githubusercontent.com/Osc2405/plot2llm/refs/heads/main/assets/logo.png" width="200" alt="plot2llm logo">
</p>
# plot2llm
[](https://pypi.org/project/plot2llm/)
[](LICENSE)
[](https://pypi.org/project/plot2llm/)
> **Convert your Python plots into LLM-ready structured outputs — from matplotlib and seaborn.**
**Plot2LLM** bridges the gap between data visualization and AI. Instantly extract technical summaries, JSON, or LLM-optimized context from your figures for explainable AI, documentation, or RAG pipelines.
> 🧠 **Use the `'semantic'` format to generate structured context optimized for GPT, Claude or any RAG pipeline.**
**Latest Updates (v0.2.1):**
- ✅ **Complete Statistical Insights**: Full distribution analysis, correlations, outliers, and central tendency for all plot types
- ✅ **Enhanced Plot Type Detection**: Improved histogram vs bar vs line detection with proper prioritization
- ✅ **Rich Pattern Analysis**: Detailed shape characteristics and pattern recognition for all visualization types
- ✅ **Comprehensive Test Suite**: 172/174 tests passing (98.9% success rate) with 24s execution time
- ✅ **Production Ready**: All core features validated with extensive error handling and edge case coverage
- ✅ **Code Quality**: All linting issues resolved with ruff and black formatting
---
## Features
| Feature | Status |
|--------------------------------|------------------|
| Matplotlib plots | ✅ Full support |
| Seaborn plots | ✅ Full support |
| JSON/Text/Semantic output | ✅ |
| Custom formatters/analyzers | ✅ |
| Multi-axes/subplots | ✅ |
| Level of detail control | ✅ |
| Error handling | ✅ |
| Extensible API | ✅ |
| Statistical Analysis | ✅ Complete |
| Pattern Analysis | ✅ Rich insights |
| Axis Type Detection | ✅ Smart detection |
| Unicode Support | ✅ Full support |
| Distribution Analysis | ✅ Skewness/Kurtosis |
| Correlation Analysis | ✅ Pearson/Spearman |
| Outlier Detection | ✅ IQR method |
| Plot Type Detection | ✅ Histogram/Bar/Line |
| Plotly/Bokeh/Altair detection | 🚧 Planned |
| Jupyter plugin | 🚧 Planned |
| Export to Markdown/HTML | 🚧 Planned |
| Image-based plot analysis | 🚧 Planned |
---
## Who is this for?
- Data Scientists who want to document or explain their plots automatically
- AI engineers building RAG or explainable pipelines
- Jupyter Notebook users creating technical visualizations
- Developers generating automated reports with AI
- Researchers needing statistical analysis of visualizations
---
## Installation
```bash
pip install plot2llm
```
For full functionality with matplotlib and seaborn:
```bash
pip install plot2llm[all]
```
**Note:** Version 0.2.2 includes all required dependencies (scipy, jsonschema) for complete functionality.
Or, for local development:
```bash
git clone https://github.com/Osc2405/plot2llm.git
cd plot2llm
pip install -e .
```
---
## Quick Start
```python
import matplotlib.pyplot as plt
import numpy as np
from plot2llm import FigureConverter
x = np.linspace(0, 2 * np.pi, 100)
fig, ax = plt.subplots()
ax.plot(x, np.sin(x), label="sin(x)", color="royalblue")
ax.plot(x, np.cos(x), label="cos(x)", color="orange")
ax.set_title('Sine and Cosine Waves')
ax.set_xlabel('Angle [radians]')
ax.set_ylabel('Value')
ax.legend()
converter = FigureConverter()
text_result = converter.convert(fig, 'text')
print(text_result)
```
---
## Examples
### Basic Usage
```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')
converter = FigureConverter()
print(converter.convert(fig, 'text'))
```
### Advanced Statistical Analysis
```python
import seaborn as sns
import matplotlib.pyplot as plt
from plot2llm import FigureConverter
# Create a scatter plot with correlation
fig, ax = plt.subplots()
x = np.random.randn(100)
y = 2 * x + np.random.randn(100) * 0.5
ax.scatter(x, y)
ax.set_title('Correlation Analysis')
converter = FigureConverter()
semantic_result = converter.convert(fig, 'semantic')
# Access statistical insights
stats = semantic_result['statistical_insights']
print(f"Correlation: {stats['correlations'][0]['value']:.3f}")
print(f"Strength: {stats['correlations'][0]['strength']}")
```
### Real-World Examples
The `examples/` directory contains comprehensive examples:
- **`minimal_matplotlib.py`**: Basic matplotlib usage
- **`minimal_seaborn.py`**: Basic seaborn usage
- **`real_world_analysis.py`**: Financial, marketing, and customer segmentation analysis
- **`llm_integration_demo.py`**: LLM integration and format comparison
- **`semantic_output_*.py`**: Complete semantic output examples
Run any example with:
```bash
python examples/minimal_matplotlib.py
```
---
## Output Formats
### 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 (LLM-Optimized)
```json
{
"metadata": {
"figure_type": "matplotlib",
"detail_level": "medium"
},
"axes": [
{
"title": "Demo Plot",
"plot_types": [{"type": "line"}],
"x_type": "numeric",
"y_type": "numeric"
}
],
"statistical_insights": {
"central_tendency": {"mean": 0.5, "median": 0.4},
"correlations": [{"type": "pearson", "value": 0.95, "strength": "strong"}]
},
"pattern_analysis": {
"pattern_type": "trend",
"shape_characteristics": {
"monotonicity": "increasing",
"smoothness": "smooth"
}
}
}
```
---
## Advanced Features
### Statistical Analysis
- **Central Tendency**: Mean, median, mode calculations
- **Variability**: Standard deviation, variance, range analysis
- **Correlations**: Pearson correlation coefficients with strength and direction
- **Data Quality**: Total points, missing values detection
- **Distribution Analysis**: Skewness and kurtosis for histograms
### Pattern Analysis
- **Monotonicity**: Increasing, decreasing, or mixed trends
- **Smoothness**: Smooth, piecewise, or discrete patterns
- **Symmetry**: Symmetric or asymmetric distributions
- **Continuity**: Continuous or discontinuous data patterns
### Smart Axis Detection
- **Numeric Detection**: Handles Unicode minus signs and various numeric formats
- **Categorical Detection**: Identifies discrete categories vs continuous ranges
- **Mixed Support**: Works with both Matplotlib and Seaborn plots
---
## API Reference
See the full [API Reference](docs/API_REFERENCE.md) for details on all classes and methods.
---
## Project Status
This project is in **stable beta**. Core functionalities are production-ready with comprehensive test coverage.
- [x] Matplotlib support (Full)
- [x] Seaborn support (Full)
- [x] Extensible formatters/analyzers
- [x] Multi-format output (text, json, semantic)
- [x] Statistical analysis with correlations
- [x] Pattern analysis with shape characteristics
- [x] Smart axis type detection
- [x] Unicode support for numeric labels
- [x] Comprehensive error handling
- [ ] Plotly/Bokeh/Altair integration
- [ ] Jupyter plugin
- [ ] Export to Markdown/HTML
- [ ] Image-based plot analysis
---
## Changelog
### v0.2.1 (Latest)
- ✅ **Enhanced Statistical Analysis**: Complete statistical insights for all plot types
- ✅ **Improved Plot Type Detection**: Better histogram vs bar vs line detection
- ✅ **Rich Pattern Analysis**: Detailed shape characteristics for all visualization types
- ✅ **Comprehensive Test Suite**: 172/174 tests passing (98.9% success rate)
### v0.2.1
- ✅ **Enhanced Statistical Analysis**: Complete statistical insights for all plot types
- ✅ **Improved Plot Type Detection**: Better histogram vs bar vs line detection
- ✅ **Rich Pattern Analysis**: Detailed shape characteristics for all visualization types
- ✅ **Comprehensive Test Suite**: 172/174 tests passing (98.9% success rate)
---
## 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 repo](https://github.com/Osc2405/plot2llm)
- [Issues](https://github.com/Osc2405/plot2llm/issues)
---
*Try it, give feedback, or suggest a formatter you'd like to see!*
Raw data
{
"_id": null,
"home_page": null,
"name": "plot2llm",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Osc2405 <orosero2405@gmail.com>",
"keywords": "data-analysis, llm, machine-learning, matplotlib, plotly, seaborn, visualization",
"author": null,
"author_email": "Osc2405 <orosero2405@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/8c/02/f6f9f19baf2d322317613895a5e34c12d94102a6781fdc7c97f4b2c96887/plot2llm-0.2.2.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/Osc2405/plot2llm/refs/heads/main/assets/logo.png\" width=\"200\" alt=\"plot2llm logo\">\n</p>\n\n# plot2llm\n\n[](https://pypi.org/project/plot2llm/)\n[](LICENSE)\n[](https://pypi.org/project/plot2llm/)\n\n> **Convert your Python plots into LLM-ready structured outputs \u2014 from matplotlib and seaborn.**\n\n**Plot2LLM** bridges the gap between data visualization and AI. Instantly extract technical summaries, JSON, or LLM-optimized context from your figures for explainable AI, documentation, or RAG pipelines.\n\n> \ud83e\udde0 **Use the `'semantic'` format to generate structured context optimized for GPT, Claude or any RAG pipeline.**\n\n**Latest Updates (v0.2.1):**\n- \u2705 **Complete Statistical Insights**: Full distribution analysis, correlations, outliers, and central tendency for all plot types\n- \u2705 **Enhanced Plot Type Detection**: Improved histogram vs bar vs line detection with proper prioritization\n- \u2705 **Rich Pattern Analysis**: Detailed shape characteristics and pattern recognition for all visualization types\n- \u2705 **Comprehensive Test Suite**: 172/174 tests passing (98.9% success rate) with 24s execution time\n- \u2705 **Production Ready**: All core features validated with extensive error handling and edge case coverage\n- \u2705 **Code Quality**: All linting issues resolved with ruff and black formatting\n\n---\n\n## Features\n\n| Feature | Status |\n|--------------------------------|------------------|\n| Matplotlib plots | \u2705 Full support |\n| Seaborn plots | \u2705 Full support |\n| JSON/Text/Semantic output | \u2705 |\n| Custom formatters/analyzers | \u2705 |\n| Multi-axes/subplots | \u2705 |\n| Level of detail control | \u2705 |\n| Error handling | \u2705 |\n| Extensible API | \u2705 |\n| Statistical Analysis | \u2705 Complete |\n| Pattern Analysis | \u2705 Rich insights |\n| Axis Type Detection | \u2705 Smart detection |\n| Unicode Support | \u2705 Full support |\n| Distribution Analysis | \u2705 Skewness/Kurtosis |\n| Correlation Analysis | \u2705 Pearson/Spearman |\n| Outlier Detection | \u2705 IQR method |\n| Plot Type Detection | \u2705 Histogram/Bar/Line |\n| Plotly/Bokeh/Altair detection | \ud83d\udea7 Planned |\n| Jupyter plugin | \ud83d\udea7 Planned |\n| Export to Markdown/HTML | \ud83d\udea7 Planned |\n| Image-based plot analysis | \ud83d\udea7 Planned |\n\n---\n\n## Who is this for?\n\n- Data Scientists who want to document or explain their plots automatically\n- AI engineers building RAG or explainable pipelines\n- Jupyter Notebook users creating technical visualizations\n- Developers generating automated reports with AI\n- Researchers needing statistical analysis of visualizations\n\n---\n\n## Installation\n\n```bash\npip install plot2llm\n```\n\nFor full functionality with matplotlib and seaborn:\n```bash\npip install plot2llm[all]\n```\n\n**Note:** Version 0.2.2 includes all required dependencies (scipy, jsonschema) for complete functionality.\n\nOr, for local development:\n```bash\ngit clone https://github.com/Osc2405/plot2llm.git\ncd plot2llm\npip install -e .\n```\n\n---\n\n## Quick Start\n\n```python\nimport matplotlib.pyplot as plt\nimport numpy as np\nfrom plot2llm import FigureConverter\n\nx = np.linspace(0, 2 * np.pi, 100)\nfig, ax = plt.subplots()\nax.plot(x, np.sin(x), label=\"sin(x)\", color=\"royalblue\")\nax.plot(x, np.cos(x), label=\"cos(x)\", color=\"orange\")\nax.set_title('Sine and Cosine Waves')\nax.set_xlabel('Angle [radians]')\nax.set_ylabel('Value')\nax.legend()\n\nconverter = FigureConverter()\ntext_result = converter.convert(fig, 'text')\nprint(text_result)\n```\n\n---\n\n## Examples\n\n### Basic Usage\n```python\nimport matplotlib.pyplot as plt\nfrom plot2llm import FigureConverter\n\nfig, ax = plt.subplots()\nax.bar(['A', 'B', 'C'], [10, 20, 15], color='skyblue')\nax.set_title('Bar Example')\n\nconverter = FigureConverter()\nprint(converter.convert(fig, 'text'))\n```\n\n### Advanced Statistical Analysis\n```python\nimport seaborn as sns\nimport matplotlib.pyplot as plt\nfrom plot2llm import FigureConverter\n\n# Create a scatter plot with correlation\nfig, ax = plt.subplots()\nx = np.random.randn(100)\ny = 2 * x + np.random.randn(100) * 0.5\nax.scatter(x, y)\nax.set_title('Correlation Analysis')\n\nconverter = FigureConverter()\nsemantic_result = converter.convert(fig, 'semantic')\n\n# Access statistical insights\nstats = semantic_result['statistical_insights']\nprint(f\"Correlation: {stats['correlations'][0]['value']:.3f}\")\nprint(f\"Strength: {stats['correlations'][0]['strength']}\")\n```\n\n### Real-World Examples\nThe `examples/` directory contains comprehensive examples:\n\n- **`minimal_matplotlib.py`**: Basic matplotlib usage\n- **`minimal_seaborn.py`**: Basic seaborn usage \n- **`real_world_analysis.py`**: Financial, marketing, and customer segmentation analysis\n- **`llm_integration_demo.py`**: LLM integration and format comparison\n- **`semantic_output_*.py`**: Complete semantic output examples\n\nRun any example with:\n```bash\npython examples/minimal_matplotlib.py\n```\n\n---\n\n## Output Formats\n\n### Text Format\n```\nPlot types in figure: line\nFigure type: matplotlib.Figure\nDimensions (inches): [8.0, 6.0]\nTitle: Demo Plot\nNumber of axes: 1\n...\n```\n\n### JSON Format\n```json\n{\n \"figure_type\": \"matplotlib\",\n \"title\": \"Demo Plot\",\n \"axes\": [...],\n ...\n}\n```\n\n### Semantic Format (LLM-Optimized)\n```json\n{\n \"metadata\": {\n \"figure_type\": \"matplotlib\",\n \"detail_level\": \"medium\"\n },\n \"axes\": [\n {\n \"title\": \"Demo Plot\",\n \"plot_types\": [{\"type\": \"line\"}],\n \"x_type\": \"numeric\",\n \"y_type\": \"numeric\"\n }\n ],\n \"statistical_insights\": {\n \"central_tendency\": {\"mean\": 0.5, \"median\": 0.4},\n \"correlations\": [{\"type\": \"pearson\", \"value\": 0.95, \"strength\": \"strong\"}]\n },\n \"pattern_analysis\": {\n \"pattern_type\": \"trend\",\n \"shape_characteristics\": {\n \"monotonicity\": \"increasing\",\n \"smoothness\": \"smooth\"\n }\n }\n}\n```\n\n---\n\n## Advanced Features\n\n### Statistical Analysis\n- **Central Tendency**: Mean, median, mode calculations\n- **Variability**: Standard deviation, variance, range analysis\n- **Correlations**: Pearson correlation coefficients with strength and direction\n- **Data Quality**: Total points, missing values detection\n- **Distribution Analysis**: Skewness and kurtosis for histograms\n\n### Pattern Analysis\n- **Monotonicity**: Increasing, decreasing, or mixed trends\n- **Smoothness**: Smooth, piecewise, or discrete patterns\n- **Symmetry**: Symmetric or asymmetric distributions\n- **Continuity**: Continuous or discontinuous data patterns\n\n### Smart Axis Detection\n- **Numeric Detection**: Handles Unicode minus signs and various numeric formats\n- **Categorical Detection**: Identifies discrete categories vs continuous ranges\n- **Mixed Support**: Works with both Matplotlib and Seaborn plots\n\n---\n\n## API Reference\n\nSee the full [API Reference](docs/API_REFERENCE.md) for details on all classes and methods.\n\n---\n\n## Project Status\n\nThis project is in **stable beta**. Core functionalities are production-ready with comprehensive test coverage.\n\n- [x] Matplotlib support (Full)\n- [x] Seaborn support (Full)\n- [x] Extensible formatters/analyzers\n- [x] Multi-format output (text, json, semantic)\n- [x] Statistical analysis with correlations\n- [x] Pattern analysis with shape characteristics\n- [x] Smart axis type detection\n- [x] Unicode support for numeric labels\n- [x] Comprehensive error handling\n- [ ] Plotly/Bokeh/Altair integration\n- [ ] Jupyter plugin\n- [ ] Export to Markdown/HTML\n- [ ] Image-based plot analysis\n\n---\n\n## Changelog\n\n### v0.2.1 (Latest)\n- \u2705 **Enhanced Statistical Analysis**: Complete statistical insights for all plot types\n- \u2705 **Improved Plot Type Detection**: Better histogram vs bar vs line detection\n- \u2705 **Rich Pattern Analysis**: Detailed shape characteristics for all visualization types\n- \u2705 **Comprehensive Test Suite**: 172/174 tests passing (98.9% success rate)\n\n### v0.2.1\n- \u2705 **Enhanced Statistical Analysis**: Complete statistical insights for all plot types\n- \u2705 **Improved Plot Type Detection**: Better histogram vs bar vs line detection\n- \u2705 **Rich Pattern Analysis**: Detailed shape characteristics for all visualization types\n- \u2705 **Comprehensive Test Suite**: 172/174 tests passing (98.9% success rate)\n\n---\n\n## Contributing\n\nPull requests and issues are welcome! Please see the [docs/](docs/) folder for API reference and contribution guidelines.\n\n---\n\n## License\n\nMIT License\n\n---\n\n## Contact & Links\n\n- [GitHub repo](https://github.com/Osc2405/plot2llm)\n- [Issues](https://github.com/Osc2405/plot2llm/issues)\n\n---\n\n*Try it, give feedback, or suggest a formatter you'd like to see!*\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Convert figures from visualization libraries into formats optimized for Large Language Models (LLMs)",
"version": "0.2.2",
"project_urls": {
"Bug Tracker": "https://github.com/Osc2405/plot2llm/issues",
"Documentation": "https://plot2llm.readthedocs.io",
"Download": "https://pypi.org/project/plot2llm/#files",
"Homepage": "https://github.com/Osc2405/plot2llm",
"Repository": "https://github.com/Osc2405/plot2llm.git",
"Source Code": "https://github.com/Osc2405/plot2llm"
},
"split_keywords": [
"data-analysis",
" llm",
" machine-learning",
" matplotlib",
" plotly",
" seaborn",
" visualization"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8582fa01391edb3393fbc8023196fd117497b26a786fe30d1c157ef2e6cb508d",
"md5": "3547fc4f46d0b18217e6de9f5c27c45c",
"sha256": "aa2b8dbf1db01fdf2698d183bda46d755d61c5ce35a1d868a3cac8013835452a"
},
"downloads": -1,
"filename": "plot2llm-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3547fc4f46d0b18217e6de9f5c27c45c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 76041,
"upload_time": "2025-08-08T19:57:46",
"upload_time_iso_8601": "2025-08-08T19:57:46.533366Z",
"url": "https://files.pythonhosted.org/packages/85/82/fa01391edb3393fbc8023196fd117497b26a786fe30d1c157ef2e6cb508d/plot2llm-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8c02f6f9f19baf2d322317613895a5e34c12d94102a6781fdc7c97f4b2c96887",
"md5": "2bfce086eaab4f6f5aa339b8aeb7f53e",
"sha256": "4313754b822d978083c9b7ad1dbf7597aff7222ad63f6bb7f099e07d302c011c"
},
"downloads": -1,
"filename": "plot2llm-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "2bfce086eaab4f6f5aa339b8aeb7f53e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 1413073,
"upload_time": "2025-08-08T19:57:48",
"upload_time_iso_8601": "2025-08-08T19:57:48.446651Z",
"url": "https://files.pythonhosted.org/packages/8c/02/f6f9f19baf2d322317613895a5e34c12d94102a6781fdc7c97f4b2c96887/plot2llm-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-08 19:57:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Osc2405",
"github_project": "plot2llm",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "matplotlib",
"specs": [
[
">=",
"3.5.0"
]
]
},
{
"name": "numpy",
"specs": [
[
">=",
"1.21.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.3.0"
]
]
},
{
"name": "scipy",
"specs": [
[
">=",
"1.7.0"
]
]
},
{
"name": "seaborn",
"specs": [
[
">=",
"0.11.0"
]
]
},
{
"name": "webcolors",
"specs": [
[
">=",
"1.11.0"
]
]
},
{
"name": "jsonschema",
"specs": [
[
">=",
"4.0.0"
]
]
}
],
"tox": true,
"lcname": "plot2llm"
}
JSON
