ractogateway.pipelines.sql_analyst._viz

Chart specification and deterministic Plotly figure builder.

No LLM calls — chart type is either specified by the user or inferred from DataFrame column dtypes using simple heuristics.

Requires: pip install ractogateway[pipelines-sql-viz]

class ractogateway.pipelines.sql_analyst._viz.ChartSpec(**data)

Bases: BaseModel

Specification for a Plotly chart.

Pass to SQLAnalystPipeline as chart=ChartSpec(...) or as a plain dict (e.g. chart={"chart_type": "bar", "x": "customer", "y": "revenue"}). Use chart="auto" to let the pipeline infer the best chart type from the DataFrame’s column dtypes with no extra LLM call.

Supported chart types

bar · line · scatter · pie · histogram · box · area · heatmap · violin · funnel

Example:

from ractogateway.pipelines import SQLAnalystPipeline, ChartSpec

result = pipeline.run(
    user_query="Top 5 customers by revenue?",
    ...,
    chart=ChartSpec(chart_type="bar", x="customer_name", y="revenue",
                    title="Top 5 Customers"),
)
result.plotly_figure.show()

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

chart_type: str

x: str | None

y: str | list[str] | None

color: str | None

title: str

x_label: str | None

y_label: str | None

orientation: Literal['v', 'h'] | None

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

ractogateway.pipelines.sql_analyst._viz.build_figure(df, spec)

Build a Plotly Figure from df using the deterministic spec.

Parameters:

• df (Any) – A pandas DataFrame to visualise.

• spec (ChartSpec) – A ChartSpec describing chart type, axes, title, etc.

Return type:

Any

Returns:

plotly.graph_objects.Figure

Raises:

• ImportError – If plotly is not installed.

• ValueError – If spec.chart_type is not in _CHART_MAP.

ractogateway.pipelines.sql_analyst._viz.infer_spec(df, pd_module)

Infer the best ChartSpec from df column dtypes — no LLM needed.

Heuristic decision tree:

1. datetime + numeric → line chart (trend over time)

2. categorical + numeric, ≤6 unique values → pie chart

3. categorical + numeric, >6 unique values → bar chart

4. 2+ numeric columns → scatter plot

5. 1 numeric column → histogram

6. Otherwise → None

Parameters:

• df (Any) – A pandas DataFrame (may be the raw SQL result or the pandas analysis output).

• pd_module (Any) – The pandas module (passed in to avoid re-importing).

Return type:

ChartSpec | None

Returns:

ChartSpec | None