# DataBrief AI

DataBrief AI is an AI-assisted CSV data quality profiling tool built with Python, Pandas, and Streamlit. It detects common data quality issues, generates an explainable quality score, creates charts and downloadable reports, and can optionally turn aggregated profile statistics into a short executive summary with Gemini.

## Why DataBrief AI?

Raw tabular data often contains missing values, duplicate rows, constant columns, or suspicious outliers before it reaches reporting and decision-making workflows. DataBrief AI provides a fast first-pass quality check without requiring users to write analysis code.

The core analysis is deterministic and testable. Gemini is used only as an optional summarization layer over aggregated statistics; raw CSV rows are not sent to the model.

## Features

- Automatic CSV delimiter and common Turkish encoding detection
- 0–100 explainable data quality score
- Missing-value and duplicate-row analysis
- Constant-column detection
- IQR-based outlier candidate detection
- Numeric and categorical summaries
- Automatic charts in a Streamlit interface
- Downloadable rule-based Markdown report
- Optional Gemini executive summary
- MCP tools for exposing the analysis engine to other AI workflows
- Unit tests for the analysis engine and a Streamlit smoke test

## Tech Stack

- Python
- Pandas
- Streamlit
- Google Gen AI SDK (Gemini)
- Model Context Protocol (MCP) Python SDK
- `unittest`

## Architecture

```mermaid
flowchart LR
    A[CSV Upload] --> B[CSV Parser]
    B --> C[Pandas Analysis Engine]
    C --> D[Quality Score]
    C --> E[Data Profile]
    C --> F[Charts]
    C --> G[Rule-based Report]
    E --> H[Optional Gemini Summary]
    C --> I[MCP Tools]
```

## Privacy Approach

The Gemini integration does **not** send raw CSV rows to the model. `analyzer.py` first computes an aggregated `DataProfile`, and only that profile is used for the optional AI-generated summary.

API keys are not stored in the repository. Use a local `.env` file or enter the key in the password field inside the app.

## Project Structure

```text
databrief-ai/
├── sample_data/
│   └── musteri_verisi.csv
├── tests/
│   ├── test_analyzer.py
│   └── test_app_smoke.py
├── .env.example
├── .gitignore
├── ai_report.py
├── analyzer.py
├── app.py
├── mcp_server.py
├── README.md
└── requirements.txt
```

## Run Locally

Python 3.11 or newer is recommended.

Create and activate a virtual environment:

```bash
python -m venv .venv
source .venv/bin/activate
```

On Windows:

```powershell
.venv\Scripts\activate
```

Install dependencies:

```bash
pip install -r requirements.txt
```

Start the Streamlit app:

```bash
streamlit run app.py
```

You can upload your own CSV file or use the included sample dataset.

## Optional Gemini Summary

Copy the example environment file:

```bash
cp .env.example .env
```

Then add your API key to `.env`:

```text
GEMINI_API_KEY=your_api_key_here
GEMINI_MODEL=gemini-3.6-flash
```

The API key can also be entered directly in the Streamlit interface and is not written to disk by the application.

## MCP Server

Start the MCP server with:

```bash
python mcp_server.py
```

Available tools:

- `analyze_csv_text` — returns the data profile as JSON
- `create_quality_report` — returns the rule-based quality report

For safety, each MCP call accepts CSV text up to 2 MB.

## Tests

Run the test suite with:

```bash
python -m unittest discover -s tests -v
```

## Quality Score

The current quality score starts at 100 and applies weighted penalties for:

- missing-cell ratio
- duplicate-row ratio
- constant-column ratio

Outliers are reported separately because an outlier can be a valid observation and should not automatically reduce the quality score.

## Disclaimer

DataBrief AI is designed as a first-pass data quality and decision-support tool. Its outputs should not replace domain-specific validation or expert review.