README.md

metadata

title: datum
app_file: app.py
sdk: gradio
sdk_version: 5.44.1

Datum - AI-Powered Data Analysis Agent

A simple yet powerful data analysis agent that uses AI to generate SQL queries, execute them against your data, and provide visualizations and insights through a web interface.

Features

• Natural Language Queries: Ask questions about your data in plain English
• Auto Routing (Chat vs SQL): Agent decides between a quick chat reply or full SQL/database analysis
• AI-Generated SQL: Automatically converts questions into SQL queries
• Data Visualization: Generates charts and graphs from query results
• Intelligent Insights: Provides narrative analysis and recommendations
• Web Interface: Clean, user-friendly Gradio interface
• DuckDB Integration: Fast, in-memory SQL database for data analysis
• LangSmith Tracing: Built-in observability and debugging with LangSmith integration

Project Structure

datum/
├── app.py                  # Main application with LangGraph workflow
├── builder/
│   ├── graph_builder.py    # Graph with router + conditional edges
│   ├── nodes.py            # Agent nodes (decider, chat, SQL, charting, narration)
│   ├── state.py            # Typed state definition for the agent
│   └── ui.py               # Gradio UI wiring
├── clients/
│   └── llm.py              # LLM configuration (Google Gemini)
├── datastore/
│   └── db.py               # DuckDB setup and data loading
├── utils/
│   ├── charts.py           # Chart generation utilities
│   ├── insight_utils.py    # Insight helpers
│   └── tracer_utils.py     # LangSmith tracing helpers
├── sample_data/            # Sample datasets
│   ├── sales.csv
│   ├── marketing_spend.csv
│   └── customers.csv
└── requirements.txt        # Python dependencies

Setup Instructions

Prerequisites

• Python 3.8 or higher
• Google API key for Gemini AI

Installation

1. Clone the repository

   git clone <repository-url>
   cd datum
   

2. Create a virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies

   pip install -r requirements.txt
   

4. Set up environment variables Create a .env file in the project root:

   GOOGLE_API_KEY=your_google_api_key_here
   LANGCHAIN_PROJECT=datum-analysis  # Optional: for LangSmith tracing
   LANGCHAIN_API_KEY=your_langsmith_api_key  # Optional: for LangSmith tracing
   LANGCHAIN_TRACING_V2=true  # Optional: enable LangSmith tracing
   

5. Run the application

   python app.py
   

6. Access the web interface Open your browser and navigate to the URL shown in the terminal (typically http://127.0.0.1:7860)

Usage

1. Ask a question: Type your data analysis question in natural language

   • Example: "What are the top 3 regions by revenue?"
   • Example: "Show me marketing spend by channel"
   • Example: "Which products have the highest unit sales?"

2. Agent chooses the path automatically

   • Chat route: Direct conversational answer when no database analysis is needed
   • SQL route: The agent generates SQL and provides:
     • Query Result (table)
     • Chart (visualization)
     • Insights (narrative + recommendation)
     • SQL (for transparency)

Routing at a Glance

The decider node analyzes your question and sets a route of chat or sql. The graph then either calls general_chat or runs the SQL flow (sql_generator → sql_executor → chart_generator + narrator).

Sample Data

The project includes sample datasets:

• Sales: Date, region, product, revenue, units sold
• Marketing Spend: Date, region, channel, spend amount
• Customers: Customer ID, region, age, income

Technology Stack

• LangGraph: Workflow orchestration
• Google Gemini: AI language model
• DuckDB: In-memory SQL database
• Gradio: Web interface
• Matplotlib: Chart generation
• Pandas: Data manipulation
• LangSmith: Observability and tracing platform

Customization

• Add your own data: Replace CSV files in the sample_data/ directory and update the schema in nodes.py
• Modify the LLM: Change the model or provider in llm.py
• Customize charts: Modify chart generation logic in charts.py
• Extend the workflow: Add new nodes to the LangGraph workflow in app.py

Observability & Debugging

The application includes built-in LangSmith tracing for monitoring and debugging:

• Trace Execution: All agent steps are automatically traced and logged
• Performance Monitoring: Track execution times and token usage
• Debug Information: View detailed logs of SQL generation, execution, and LLM calls
• Project Organization: Traces are organized by project name for easy filtering

To enable tracing, set the LangSmith environment variables in your .env file. Without these variables, the application will run normally but without tracing capabilities.

Troubleshooting

• API Key Error: Ensure your GOOGLE_API_KEY is set correctly in the .env file
• Import Errors: Make sure all dependencies are installed with pip install -r requirements.txt
• Data Issues: Verify your CSV files are in the correct format and location
• Tracing Issues: Check LangSmith credentials if you want to use the observability features

License

This project is open source and available under the MIT License.