Zaturn

Instructions

Implementation Reference

• zaturn/tools/visualizations.py:231-267 (handler)

  The bar_plot tool handler function. It takes source_id, SQL query, x and y column names, optional color and orientation parameters. Executes the query, creates a plotly bar plot, converts to image, or returns error.
  def bar_plot(self, source_id: Annotated[ str, Field(description='The data source to run the query on') ], query: Annotated[ str, Field(description='SQL query to run on the data source') ], x: Annotated[ str, Field(description='Column name from SQL result to use for x-axis') ], y: Annotated[ str, Field(description='Column name from SQL result to use for y-axis') ], color: Annotated[ str | None, Field(description='Optional column name from SQL result to use as a 3rd dimension by splitting each bar into colored sections') ] = None, orientation: Annotated[ str, Field(description="Orientation of the box plot, use 'v' for vertical (default) and 'h' for horizontal. Be mindful of choosing the correct X and Y columns as per orientation") ] = 'v', ) -> str | ImageContent: """ Run query against specified source and make a bar plot using result For both csv and parquet sources, use DuckDB SQL syntax Use 'CSV' as the table name in the SQL query for csv sources. Use 'PARQUET' as the table name in the SQL query for parquet sources. This will return an image of the plot """ try: df = self._get_df_from_source(source_id, query) fig = px.bar(df, x=x, y=y, color=color, orientation=orientation) fig.update_xaxes(autotickangles=[0, 45, 60, 90]) return _fig_to_image(fig) except Exception as e: return str(e)
• zaturn/tools/visualizations.py:27-40 (registration)

  Registration of the bar_plot tool (self.bar_plot) in the tools list of the Visualizations class.
  def __init__(self, data_sources): self.data_sources = data_sources self.tools = [ self.scatter_plot, self.line_plot, self.histogram, self.strip_plot, self.box_plot, self.bar_plot, self.density_heatmap, self.polar_scatter, self.polar_line, ]
• zaturn/tools/visualizations.py:13-22 (helper)

  Helper function to convert a Plotly figure to a base64-encoded PNG ImageContent object, used by bar_plot and other visualization tools.
  def _fig_to_image(fig): fig_encoded = b64encode(fig.to_image(format='png')).decode() img_b64 = "data:image/png;base64," + fig_encoded return ImageContent( type = 'image', data = fig_encoded, mimeType = 'image/png', annotations = None, )
• zaturn/tools/visualizations.py:43-49 (helper)

  Helper method to retrieve and query a dataframe from the specified data source, used by bar_plot.
  def _get_df_from_source(self, source_id, query): source = self.data_sources.get(source_id) if not source: raise Exception(f"Source {source_id} Not Found") return query_utils.execute_query(source, query)
• zaturn/mcp/__init__.py:89-95 (registration)

  Final registration of all ZaturnTools (including bar_plot) into the FastMCP server instance.
  def ZaturnMCP(sources): zaturn_tools = ZaturnTools(sources) zaturn_mcp = FastMCP() for tool_function in zaturn_tools.tools: zaturn_mcp.add_tool(Tool.from_function(tool_function)) return zaturn_mcp