🚀 Talking Data

Talking Data is a lightweight, multi-provider AI Data Analysis library that performs SQL-based reasoning directly on your pandas.DataFrame using OpenAI, Groq, or Google Gemini models.

• 🧩 Generates SQL queries from plain English questions
• 🚀 Executes them locally using DuckDB
• 🧠 Summarizes results as insightful text or HTML
• ⚙ Installs missing dependencies automatically

Installation

Copypip install talking_data

Once installed, import it in your Python project:

Copyfrom talking_data import open_analysis

⚡ Quickstart Example

Copyfrom talking_data import open_analysis
import pandas as pd

df = pd.DataFrame({
    "region": ["East", "West", "North", "South"],
    "sales": [1200, 800, 950, 1100],
    "profit": [200, 100, 150, 180]
})

result = open_analysis(
    df=df,
    model_provider="openai",
    api_key="YOUR_API_KEY",
    question="Which region performs best by profit margin?",
    query_context="Profit margin = profit / sales * 100",
    log_level="detailed"
)

print("SQL Query:", result["sql_query"])
print(result["query_result"])
print("Insights:", result["plain_text_output"])

🧠 Examples by Provider

1️⃣ OpenAI Example

Copyresult = open_analysis(
    df=df,
    model_provider="openai",
    api_key="YOUR_OPENAI_API_KEY",
    question="Which region has the highest total sales?",
)
print(result["plain_text_output"])

2️⃣ Groq Example

Copyresult = open_analysis(
    df=df,
    model_provider="groq",
    api_key="YOUR_GROQ_API_KEY",
    question="Compare profit and sales correlation by region."
)
print(result["plain_text_output"])

3️⃣ Gemini Example

Copyresult = open_analysis(
    df=df,
    model_provider="gemini",
    api_key="YOUR_GEMINI_API_KEY",
    question="Find the top 2 regions by total sales."
)
print(result["plain_text_output"])

🧠 Example Output

Here’s what a typical open_analysis() call returns — a mix of plain text insights, SQL, and HTML output that you can render anywhere:

Plain Text Output

CopyRegion East has the highest profit margin of 16.7%, followed by South at 16.3%.

Generated SQL

CopySELECT region, SUM(profit)/SUM(sales)*100 AS margin 
            FROM df 
            GROUP BY region 
            ORDER BY margin DESC;

HTML Output

Copy<section>
    <h3>Regional Profit Margin Insights</h3>
    <ul>
        <li>East region leads with a 16.7% margin</li>
        <li>South follows closely at 16.3%</li>
    </ul>
    </section>

🧩 Supported Providers

The library detects and loads each SDK lazily at runtime — missing packages are installed automatically.

🧩 Function Reference

Copyopen_analysis(
    df: pd.DataFrame,
    model_provider: str = "openai",
    model: str = None,
    api_key: str = None,
    question: str = "Do a data analysis on the dataframe and give me insights?",
    temperature_one: float = 0.2,
    temperature_two: float = 0.7,
    max_completion_tokens: int = 1024,
    output_layer_context: str = None,
    query_context: str = None,
    log_level: str = "basic"
) -> dict

This function performs a two-stage process:

1. SQL Generation — Converts your natural-language question into an executable SQL query.
2. Insight Summarization — Executes the query on DuckDB and summarizes the result in both HTML and text formats.

🧾 Parameters

📤 Return Structure

Copy{
  "provider": "openai",
  "model": "gpt-4o",
  "sql_query": "SELECT region, SUM(profit)/SUM(sales)*100 AS margin FROM df GROUP BY region ORDER BY margin DESC",
  "query_result": "",
  "html_output": "
...
",
  "plain_text_output": "East region has the highest profit margin (16.7%)",
  "logs": [...]
}

🪵 Logging Levels

• none — No logs returned.
• basic — Shows only essential steps.
• detailed — Includes SQL and phase transitions.
• debug — Includes tracebacks and full prompt data.

Logs are stored in result["logs"] as a list of messages.

🧩 FAQ

Q: Does it modify my DataFrame?
A: No, it registers it temporarily in DuckDB for querying.

Q: Can it work offline?
A: Not yet — all providers are cloud APIs.

Q: Do I need to install dependencies manually?
A: No, Talking Data installs them automatically when needed.

Q: Can I get HTML output?
A: Yes, via result["html_output"].

🔁 Version History

🪪 License

CopyMIT License

Copyright (2025)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...

Made with ❤️ by Mohammad Abdullah · Talking Data v0.9.0 · MIT License