# 📈 Chat2Plot - interactive & safe text-to-visualization with LLM
This library uses LLMs to generate:
1. Visualization
2. High-level chart specifications in json (You can choose between a simple or vega-lite format)
3. Explanation
from natural language requests for given data.
Chat2Plot does not generate executable code or SQL from the LLM,
so you can safely generate visualizations.
demo: https://chat2plot-sample.streamlit.app/
## Quick Start
```shell
pip install chat2plot
```
```Python
import os
import pandas as pd
from chat2plot import chat2plot
# 1. Set api-key
os.environ["OPENAI_API_KEY"] = "..."
df = pd.read_csv(...)
# 2. Pass a dataframe to draw
c2p = chat2plot(df)
# 3. Make a question about the data
result = c2p("average target over countries")
result.figure.show() # draw a plot
print(result.config) # get a config (json / dataclass)
print(result.explanation) # see the explanation generated by LLM
# you can make follow-up request to refine the chart
result = c2p("change to horizontal-bar chart")
result.figure.show()
```
## Why Chat2Plot?
Inside Chat2Plot, LLM does not generate Python code,
but generates plot specifications in json.
The declarative visualization specification in json is transformed into actual charts in
Chat2Plot using plotly or altair, but users can also use json directly in their own applications.
This design limits the visualization expression compared to Python code generation
(such as ChatGPT's Code Interpreter Plugin), but has the following practical advantages:
- Secure
- More secure execution, as LLM does not directly generate code.
- Language-independent
- Declarative data structures are language-agnostic, making it easy to plot in non-Python environments.
- Interactive
- Declarative data can be modified by the user to improve plots through collaborative work between the user and LLM.
By default, chat2plot uses [function calling API](https://openai.com/blog/function-calling-and-other-api-updates).
## Examples
### Custom language models
`gpt-3.5-turbo-0613` is used by default, but you can use other language models.
```python
import pandas as pd
from langchain.chat_models import AzureChatOpenAI
from chat2plot import chat2plot
plot = chat2plot(pd.DataFrame(), chat=AzureChatOpenAI())
ret = plot.query("<your query>")
```
### Vega-lite format
```python
import pandas as pd
from chat2plot import chat2plot
plot = chat2plot(pd.DataFrame(), schema_definition="vega")
ret = plot.query("<your query>")
assert isinstance(ret.config, dict) # vega-lite format
print(ret.config)
```
### Custom chart definition
```python
import pydantic
import pandas as pd
from chat2plot import chat2plot
class CustomChartConfig(pydantic.BaseModel):
chart_type: str
x_axis_name: str
y_axis_name: str
y_axis_aggregate: str
plot = chat2plot(pd.DataFrame(), schema_definition=CustomChartConfig)
ret = plot.query("<your query>")
# chat2plot treats the data type you pass as a chart setting
assert isinstance(ret.config, CustomChartConfig)
```
### Specifying output language
You can specify in which language the chart explanations should be output.
If not specified, it will return as much as possible in the same language as the user's question,
but this option is often useful if you always want output in a specific language.
```python
import pandas as pd
from chat2plot import chat2plot
plot = chat2plot(pd.DataFrame(), language="Chinese")
ret = plot.query("<your query>")
print(ret.explanation) # explanation
```
### Privacy preserving
When `description_strategy="dtypes"` is specified, chat2plot will not send the data
content (but just column names) to LLM.
```python
import pandas as pd
from langchain.chat_models import AzureChatOpenAI
from chat2plot import chat2plot
plot = chat2plot(pd.DataFrame(), description_strategy="dtypes")
ret = plot.query("<your query>")
```
## API
A `Chat2Plot` instance can be created using the `chat2plot` function.
```Python
def chat2plot(
df: pd.DataFrame,
schema_definition: Literal["simple", "vega"] | Type[pydantic.BaseModel] = "simple",
chat: BaseChatModel | None = None,
function_call: bool | Literal["auto"] = "auto",
language: str | None = None,
description_strategy: str = "head",
custom_deserializer: ModelDeserializer | None = None,
verbose: bool = False,
) -> Chat2PlotBase:
```
- **df** - Data source for visualization.
- **schema_definition** (optional) - Type of json format.
- `vega` - A vega-lite compliant format
- `simple` - chat2plot's built-in format, parsed as `chat2plot.PlotConfig`
If you want chat2plot to generate chart definitions according to your own defined schema,
you can pass any type that extends pydantic.BaseModel instead of these two options.
- **chat** (optional) - The chat instance for interaction with LLMs.
If omitted, `ChatOpenAI(temperature=0, model_name="gpt-3.5-turbo-0613")` will be used.
- **function_call** (optional) - Specifies whether to use the [function calling API](https://openai.com/blog/function-calling-and-other-api-updates).
If omitted, it is automatically determined based on the underlying model type.
- **language** (optional) - Language of explanations. If not specified, it will be automatically inferred from user prompts.
- **description_strategy** (optional) - Type of how the information in the dataset is embedded in the prompt.
- `head` - send `df.head(5)` to LLMs.
- `dtypes` - send `df.dtypes` to LLMs. This can be used when you do not want to send contents of `df` to LLMs.
- **custom_deserializer** (optional) - Specifies a custom deserializer to convert json returned from the LLM into a chart configuration.
- **verbose** (optional) - If `True`, chat2plot will output logs.
Once an instance is created, a graph generation request can be made
by calling `query` method, or simply passing the same arguments to the instance (`__call__`).
```Python
def query(self, q: str, config_only: bool = False, show_plot: bool = False) -> Plot:
```
- **q** - A query string.
- **config_only** - If `True`, skip generating figure.
- **show_plot** - If `True`, showing the generated figure is also performed inside chat2plot.
The default behavior is `config_only=False` and `show_plot=False`,
i.e. Chat2Plot generates a figure as well as configuration, but does not draw it.
The `query` method returns `Plot` object, and this has the following properties:
```Python
@dataclass(frozen=True)
class Plot:
figure: alt.Chart | Figure | None
config: PlotConfig | dict[str, Any] | None
response_type: ResponseType
explanation: str
conversation_history: list[langchain.schema.BaseMessage] | None
```
- **figure** - The generated figure (chart).
- **config** - The chart specification. Returns dict for `vega` mode and `PlotConfig` for `simple` mode.
- **response_type** - The result code of the response.
- **explanation** - Reason for the chart setup, generated by LLMs.
- **conversation_history** - Full history of conversation (including retry prompt).
Raw data
{
"_id": null,
"home_page": "https://github.com/nyanp/chat2plot",
"name": "chat2plot",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "llm visualization chart gpt",
"author": "nyanp",
"author_email": "Noumi.Taiga@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/8c/89/66dbfd7545345d00a67be323ebb8529554677eab6fea189f941cb219a950/chat2plot-0.0.11.tar.gz",
"platform": null,
"description": "# \ud83d\udcc8 Chat2Plot - interactive & safe text-to-visualization with LLM\n\nThis library uses LLMs to generate:\n\n1. Visualization \n2. High-level chart specifications in json (You can choose between a simple or vega-lite format)\n3. Explanation\n\nfrom natural language requests for given data.\n\nChat2Plot does not generate executable code or SQL from the LLM, \nso you can safely generate visualizations.\n\ndemo: https://chat2plot-sample.streamlit.app/\n\n\n\n## Quick Start\n\n```shell\npip install chat2plot\n```\n\n```Python\nimport os\nimport pandas as pd\nfrom chat2plot import chat2plot\n\n# 1. Set api-key\nos.environ[\"OPENAI_API_KEY\"] = \"...\"\n\ndf = pd.read_csv(...)\n\n# 2. Pass a dataframe to draw\nc2p = chat2plot(df)\n\n# 3. Make a question about the data\nresult = c2p(\"average target over countries\")\nresult.figure.show() # draw a plot\nprint(result.config) # get a config (json / dataclass)\nprint(result.explanation) # see the explanation generated by LLM\n\n# you can make follow-up request to refine the chart\nresult = c2p(\"change to horizontal-bar chart\")\nresult.figure.show()\n```\n\n## Why Chat2Plot?\n\nInside Chat2Plot, LLM does not generate Python code,\nbut generates plot specifications in json.\n\nThe declarative visualization specification in json is transformed into actual charts in \nChat2Plot using plotly or altair, but users can also use json directly in their own applications.\n\nThis design limits the visualization expression compared to Python code generation \n(such as ChatGPT's Code Interpreter Plugin), but has the following practical advantages:\n\n- Secure\n - More secure execution, as LLM does not directly generate code.\n\n- Language-independent\n - Declarative data structures are language-agnostic, making it easy to plot in non-Python environments.\n\n- Interactive\n - Declarative data can be modified by the user to improve plots through collaborative work between the user and LLM.\n\nBy default, chat2plot uses [function calling API](https://openai.com/blog/function-calling-and-other-api-updates).\n\n## Examples\n\n### Custom language models\n`gpt-3.5-turbo-0613` is used by default, but you can use other language models.\n\n```python\nimport pandas as pd\nfrom langchain.chat_models import AzureChatOpenAI\nfrom chat2plot import chat2plot\n\nplot = chat2plot(pd.DataFrame(), chat=AzureChatOpenAI())\nret = plot.query(\"<your query>\")\n```\n\n### Vega-lite format\n\n```python\nimport pandas as pd\nfrom chat2plot import chat2plot\n\nplot = chat2plot(pd.DataFrame(), schema_definition=\"vega\")\nret = plot.query(\"<your query>\")\n\nassert isinstance(ret.config, dict) # vega-lite format\nprint(ret.config)\n```\n\n### Custom chart definition\n\n```python\nimport pydantic\nimport pandas as pd\nfrom chat2plot import chat2plot\n\nclass CustomChartConfig(pydantic.BaseModel):\n chart_type: str\n x_axis_name: str\n y_axis_name: str\n y_axis_aggregate: str\n\nplot = chat2plot(pd.DataFrame(), schema_definition=CustomChartConfig)\nret = plot.query(\"<your query>\")\n\n# chat2plot treats the data type you pass as a chart setting\nassert isinstance(ret.config, CustomChartConfig)\n```\n\n### Specifying output language\nYou can specify in which language the chart explanations should be output. \nIf not specified, it will return as much as possible in the same language as the user's question, \nbut this option is often useful if you always want output in a specific language.\n\n```python\nimport pandas as pd\nfrom chat2plot import chat2plot\n\nplot = chat2plot(pd.DataFrame(), language=\"Chinese\")\nret = plot.query(\"<your query>\")\n\nprint(ret.explanation) # explanation \n```\n\n### Privacy preserving\nWhen `description_strategy=\"dtypes\"` is specified, chat2plot will not send the data \ncontent (but just column names) to LLM.\n\n```python\nimport pandas as pd\nfrom langchain.chat_models import AzureChatOpenAI\nfrom chat2plot import chat2plot\n\nplot = chat2plot(pd.DataFrame(), description_strategy=\"dtypes\")\nret = plot.query(\"<your query>\")\n```\n\n\n## API\n\nA `Chat2Plot` instance can be created using the `chat2plot` function.\n\n```Python\ndef chat2plot(\n df: pd.DataFrame,\n schema_definition: Literal[\"simple\", \"vega\"] | Type[pydantic.BaseModel] = \"simple\",\n chat: BaseChatModel | None = None,\n function_call: bool | Literal[\"auto\"] = \"auto\",\n language: str | None = None,\n description_strategy: str = \"head\",\n custom_deserializer: ModelDeserializer | None = None,\n verbose: bool = False,\n) -> Chat2PlotBase:\n```\n\n- **df** - Data source for visualization.\n- **schema_definition** (optional) - Type of json format.\n - `vega` - A vega-lite compliant format\n - `simple` - chat2plot's built-in format, parsed as `chat2plot.PlotConfig`\n\n If you want chat2plot to generate chart definitions according to your own defined schema, \n you can pass any type that extends pydantic.BaseModel instead of these two options.\n- **chat** (optional) - The chat instance for interaction with LLMs.\n If omitted, `ChatOpenAI(temperature=0, model_name=\"gpt-3.5-turbo-0613\")` will be used.\n- **function_call** (optional) - Specifies whether to use the [function calling API](https://openai.com/blog/function-calling-and-other-api-updates).\n If omitted, it is automatically determined based on the underlying model type. \n- **language** (optional) - Language of explanations. If not specified, it will be automatically inferred from user prompts.\n- **description_strategy** (optional) - Type of how the information in the dataset is embedded in the prompt.\n - `head` - send `df.head(5)` to LLMs.\n - `dtypes` - send `df.dtypes` to LLMs. This can be used when you do not want to send contents of `df` to LLMs.\n- **custom_deserializer** (optional) - Specifies a custom deserializer to convert json returned from the LLM into a chart configuration.\n- **verbose** (optional) - If `True`, chat2plot will output logs.\n\n\nOnce an instance is created, a graph generation request can be made \nby calling `query` method, or simply passing the same arguments to the instance (`__call__`).\n\n```Python\ndef query(self, q: str, config_only: bool = False, show_plot: bool = False) -> Plot:\n```\n- **q** - A query string.\n- **config_only** - If `True`, skip generating figure.\n- **show_plot** - If `True`, showing the generated figure is also performed inside chat2plot.\n\nThe default behavior is `config_only=False` and `show_plot=False`, \ni.e. Chat2Plot generates a figure as well as configuration, but does not draw it.\n\nThe `query` method returns `Plot` object, and this has the following properties:\n\n```Python\n@dataclass(frozen=True)\nclass Plot:\n figure: alt.Chart | Figure | None\n config: PlotConfig | dict[str, Any] | None\n response_type: ResponseType\n explanation: str\n conversation_history: list[langchain.schema.BaseMessage] | None\n```\n\n- **figure** - The generated figure (chart).\n- **config** - The chart specification. Returns dict for `vega` mode and `PlotConfig` for `simple` mode.\n- **response_type** - The result code of the response.\n- **explanation** - Reason for the chart setup, generated by LLMs.\n- **conversation_history** - Full history of conversation (including retry prompt).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "chat to visualization with LLM",
"version": "0.0.11",
"project_urls": {
"Homepage": "https://github.com/nyanp/chat2plot"
},
"split_keywords": [
"llm",
"visualization",
"chart",
"gpt"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "74d7b57ae9d095beb62bdbe2c62ba5a7a30bf0d2fb740799e457a8978ebc63a7",
"md5": "34ad5cb54198cb23cc6b34647c682d9c",
"sha256": "68b5292600e2a12be6524c4856e02997cb4e64f7f76fce3d6d3cbbbc3345c477"
},
"downloads": -1,
"filename": "chat2plot-0.0.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "34ad5cb54198cb23cc6b34647c682d9c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 19388,
"upload_time": "2023-06-24T14:59:16",
"upload_time_iso_8601": "2023-06-24T14:59:16.026668Z",
"url": "https://files.pythonhosted.org/packages/74/d7/b57ae9d095beb62bdbe2c62ba5a7a30bf0d2fb740799e457a8978ebc63a7/chat2plot-0.0.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8c8966dbfd7545345d00a67be323ebb8529554677eab6fea189f941cb219a950",
"md5": "e2530097ab32db21bc1206e78c51cb31",
"sha256": "8ad8d599b41e99bfdd10fb54749f1da0b8eb2c5a7952a3b26ce6cc2abc29d280"
},
"downloads": -1,
"filename": "chat2plot-0.0.11.tar.gz",
"has_sig": false,
"md5_digest": "e2530097ab32db21bc1206e78c51cb31",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18971,
"upload_time": "2023-06-24T14:59:17",
"upload_time_iso_8601": "2023-06-24T14:59:17.562099Z",
"url": "https://files.pythonhosted.org/packages/8c/89/66dbfd7545345d00a67be323ebb8529554677eab6fea189f941cb219a950/chat2plot-0.0.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-06-24 14:59:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nyanp",
"github_project": "chat2plot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "chat2plot"
}
JSON
