Render an HTML summary report from a set of pre-generated charts.

    Call this after all chart tools have been run and you have collected
    their output paths.

    Args:
        report_title:      Title shown on the cover page.
        datasets:          List of dataset names included in the report.
        chart_paths:       List of relative paths to chart PNG files.
        chart_titles:      List of titles — one per chart, same order as chart_paths.
        chart_captions:    List of caption strings, same order as chart_paths.
        executive_summary: Optional paragraph summarising the key findings.
        output_filename:   HTML filename to write (auto-generated if empty).

    Returns:
        Relative path to the saved HTML file.
    

    Filter a dataset by categorical, numeric, and datetime criteria, then save the result.

    All filter types are applied independently and intersected to produce the final subset.

    Args:
        source_dataset_name: Name of the registered source dataset.
        categorical_filters: List of (column, value) tuples for exact value matching.
                            E.g. [("region", "South"), ("region", "North"), ("category", "Hardware")]
        numeric_filters: List of (column, value, operator) tuples for numeric comparison.
                        E.g. [("age", 30, ">="), ("salary", 50000, ">")]
        datetime_column: Column name to filter by date range. Leave empty to skip.
        datetime_from: Start of date range (inclusive). Leave empty for no lower bound.
        datetime_to: End of date range (inclusive). Leave empty for no upper bound.
        output_dataset_name: Name for the output subset. Auto-generated if empty.
        output_dataset_desc: Description of the subset. Auto-generated if empty.

    Returns:
        A JSON str with {"dataset_name":"...","dataset_path":"...","dataset_schema":"..."}
    

    List the available datasets and get their schemas : 
    column names, dtypes, sample values,
    and a categorised column list (numeric / categorical / datetime).
    

    Convert an HTML report to PDF and POST it to the (fake) API.

    Args:
        html_path:   Path to the HTML file (output of build_html_report).
        report_name: Logical name for the report used in the API call.

    Returns:
        A JSON str with {"pdf_path":"...","report_id":"...","message":"..."}
    

    Generate a bar chart from a dataset column.

    Args:
        dataset:   Name of the dataset (e.g. "sales", "users").
        x_column:  Column to use for the X axis (categorical or date).
        y_column:  Numeric column to aggregate on the Y axis (sum by default).
        title:     Chart title shown at the top.
        group_by:  Optional column to group bars by colour (e.g. "category").
        filename:  Output filename (auto-generated if empty).

    Returns:
        A JSON str with {"chart_path":"...","chart_data":"..."}.
    

    Generate a histogram showing the distribution of a numeric column.

    Args:
        dataset:  Name of the dataset.
        column:   Numeric column to plot.
        title:    Chart title.
        bins:     Number of bins (default 20).
        filename: Output filename (auto-generated if empty).

    Returns:
        A JSON str with {"chart_path":"...","chart_data":"..."}.
    

    Generate a line chart — great for time series or trends.

    Args:
        dataset:   Name of the dataset.
        x_column:  Column for the X axis, ideally a date or ordered category.
        y_column:  Numeric column for the Y axis (summed per X value).
        title:     Chart title.
        group_by:  Optional column to draw one line per group.
        filename:  Output filename (auto-generated if empty).

    Returns:
        A JSON str with {"chart_path":"...","chart_data":"..."}.
    

    Generate a pie chart showing the composition of a categorical column.

    Args:
        dataset:          Name of the dataset.
        category_column:  Categorical column whose values form the slices.
        value_column:     Numeric column to sum per category.
        title:            Chart title.
        filename:         Output filename (auto-generated if empty).

    Returns:
        A JSON str with {"chart_path":"...","chart_data":"..."}.
    

    Generate a scatter plot comparing two numeric columns.

    Best used when get_summary_statistics reveals a notable correlation
    between two columns worth visualising.

    Args:
        dataset:   Name of the dataset.
        x_column:  Numeric column for the X axis.
        y_column:  Numeric column for the Y axis.
        title:     Chart title.
        color_by:  Optional categorical column to colour points by group.
        filename:  Output filename (auto-generated if empty).

    Returns:
        A JSON str with {"chart_path":"...","chart_data":"..."}.
    

    Return descriptive statistics and a correlation matrix for a dataset.

    Call this before generating charts to understand distributions,
    spot outliers, and find which numeric columns correlate strongly
    (good candidates for scatter plots).

    Args:
        dataset: Name of the dataset.

    Returns:
        JSON string with two keys:
          - "describe": per-column stats (count, mean, std, min/max, quartiles)
          - "correlation": Pearson correlation matrix for numeric columns