🧠 pandatools – SƠN AI DataFrame Cleaner

Version 2.0. | Tác giả: Sơn Lê

pandatools là thư viện Python mở rộng Pandas DataFrame với accessor clean, cung cấp hơn 25 hàm phân tích, làm sạch, trực quan hóa, và tối ưu dữ liệu. Điểm nổi bật là SƠN AI Pipeline – cơ chế gọi AI (OpenAI GPT-4o, Gemini) để sinh code xử lý DataFrame theo ngữ cảnh thực tế, có cache thông minh và fallback khi API lỗi. Phiên bản 2.0 bổ sung Big Data mode (chunking, sampling), phân tích màu trên terminal, Unicode NFC cho tiếng Việt, memory optimization, và hệ thống task có thể mở rộng qua decorator @son_ai.

---

📦 Cài đặt

pip install pandas numpy openai google-generativeai matplotlib seaborn openpyxl

Yêu cầu tối thiểu: pandas, numpy. Các gói còn lại tùy chọn theo tính năng sử dụng (AI, vẽ biểu đồ, xuất Excel).

---

🚀 Khởi tạo nhanh

import pandas as pd
import pandatools  # Kích hoạt accessor df.clean

df = pd.read_csv('data.csv')
df.clean.intoo()           # Phân tích màu + gợi ý code
df = df.clean.auto()       # Làm sạch tự động, không cần API
df.clean.csv('output.csv') # Lưu kết quả

---

🤖 SƠN AI Pipeline

SƠN AI là hệ thống gọi mô hình ngôn ngữ lớn (OpenAI/Gemini) để sinh code Python xử lý DataFrame dựa trên prompt mô tả từng task. Mỗi task có fallback là hàm Python thuần, đảm bảo pipeline luôn hoạt động ngay cả khi không có API key hoặc API lỗi.

Khởi tạo (phải gọi trước khi dùng son)

# Key trực tiếp
df.clean.ai_son(model="gpt-4o", key="sk-abc123...")

# Key từ env (1=OPENAI_API_KEY, 2=SON_AI_KEY, 3=AI_API_KEY)
df.clean.ai_son(model="gpt-4o", key=1)

# Gemini
df.clean.ai_son(model="gemini-1.5-pro", provider="gemini", key="...")

Sau khi khởi tạo, SonConfig.is_ready = True, có thể gọi pipeline.

Chạy pipeline

df = df.clean.son([1, 2, 4, 7])                 # Custom tasks
df = df.clean.son([1, 2, 3, 4, 5, 6])           # Basic pipeline
df = df.clean.son([1,2,3,4,5,7,8,6,10])         # Advanced
df = df.clean.son([1,2,3,4,5,7,8,6,9,10])       # ML Ready

Cơ chế hoạt động

1. Với mỗi task_id, lấy prompt từ registry TASKS.
2. Gửi prompt + context DataFrame (columns, dtypes, shape, sample) lên AI.
3. AI trả về hàm def clean(df): ..., được cache ra ~/.son_cache/.
4. exec() code AI sinh, gọi clean(result).
5. Nếu AI lỗi hoặc không khả dụng, chạy fallback task['fn'](df) – hàm Python đã đăng ký sẵn.

---

📋 Danh sách Task

ID	Mô tả	Prompt AI (rút gọn)
1	🗑️ Xóa duplicate rows	Xóa tất cả hàng trùng lặp dựa trên tất cả columns
2	📝 Chuẩn hóa tên cột	lowercase, space→_, bỏ ký tự đặc biệt, giới hạn 50 ký tự
3	✂️ Strip text columns	Strip khoảng trắng, chuỗi rỗng/'nan'/'None'→NaN
4	🚫 Xóa cột vô nghĩa	Cột >70% missing hoặc chỉ có 1 giá trị duy nhất
5	🔧 Auto-fix dtypes	Object→numeric/datetime/category, float→Int64, 0/1→bool
6	💉 Fill missing values	Numeric→median, datetime→ffill, string→mode/'Unknown'
7	📊 Xử lý outliers (IQR)	Q1, Q3, IQR, clip ngoài [Q1-1.5×IQR, Q3+1.5×IQR]
8	🔤 Chuẩn hóa text Unicode	NFC normalization, thay multiple spaces, strip
9	📅 Feature engineering datetime	Tạo year, month, day, dayofweek, quarter, is_weekend
10	💾 Memory optimization	Downcast int64→int nhỏ hơn, float64→float32

---

🔧 Hàm làm sạch thủ công (Không cần API)

Tất cả đều có tham số inplace=False. Trả về DataFrame mới, nếu inplace=True thì ghi đè lên DataFrame gốc.

Hàm	Chức năng	Tham số chính
auto()	Gộp task 1→6, chạy tuần tự	inplace
drop_dupes()	Xóa hàng trùng	subset, keep='first'/'last'/False
strip_strings()	Strip khoảng trắng string cols	lowercase=True/False
fix_dtypes()	Tự sửa object→numeric/datetime/category	—
fill_missing()	Điền missing thông minh	numeric_strategy='median'/'mean', cat_fill='Unknown', datetime_strategy='ffill'/'bfill', add_indicator=True
remove_uninformative()	Xóa cột >70% missing/constant	missing_threshold=0.7
normalize_text()	Unicode NFC (tiếng Việt)	columns=['col1','col2']
clip_outliers()	Clip outliers IQR	strategy='iqr', multiplier=1.5
normalize_column_names()	Chuẩn hóa tên cột	—
optimize_memory()	Downcast int/float	—

---

📊 Phân tích & Trực quan hóa

Phân tích dữ liệu

# Bảng màu terminal + gợi ý code từng cột
df.clean.intoo()

# JSON output
df.clean.intoo(as_json=True, max_rows=20)

# Thống kê nâng cao
df.clean.summary()
df.clean.summary(as_json=True)

# Memory usage
df.clean.info_memory()

Bảng intoo() hiển thị mỗi cột với: Non-Null count, % thiếu (đỏ nếu >50%, vàng nếu >0%), dtype, gợi ý xử lý, và code snippet tương ứng. Màu sắc trực quan giúp phát hiện vấn đề ngay trên terminal.

Biểu đồ

Hàm	Mô tả
bd('col')	Tự chọn biểu đồ phù hợp (histogram/boxplot/pie/bar)
bd('x','y')	Tự detect loại 2 cột (scatter/line/bar)
bd_bar(x, y)	Bar chart, hỗ trợ group by z
bd_line(x, y)	Line chart, hỗ trợ group by z
bd_pie(col)	Pie chart (top 10)
bd_scatter(x, y, z)	Scatter plot với hue
bd_hist(col, bins=30)	Histogram + KDE
bd_box(x, y)	Boxplot
bd_heatmap()	Correlation heatmap (numeric cols)

Tất cả hàm biểu đồ hỗ trợ save='file.png', title='...', figsize=(w,h).

---

🐘 Big Data Mode

Kích hoạt khi DataFrame quá lớn, tự động giảm tải bộ nhớ:

df.clean.bigdata(start=True, chunk_size=100_000, sample_size=10_000)

Khi bật:

• intoo() và auto() tự động lấy mẫu sample_size dòng để phân tích/ làm sạch.
• optimize_memory() được gọi tự động trong auto().
• Cảnh báo khi shape thay đổi do sampling.

---

💾 Lưu file

df.clean.csv('output.csv')              # UTF-8 BOM (tương thích Excel tiếng Việt)
df.clean.excel('output.xlsx')           # Excel
df.clean.to_parquet('output.parquet')   # Parquet (nhanh hơn CSV ~10x)

---

🛠️ Tự định nghĩa Task

Dùng decorator @son_ai để đăng ký task mới vào registry toàn cục TASKS:

from pandatools import son_ai

@son_ai(11, "Prompt mô tả cho AI biết cần làm gì", "📛 Mô tả ngắn")
def my_custom_task(df):
    # Code fallback khi AI không khả dụng
    df['new_col'] = df['old_col'] * 2
    return df

# Sử dụng ngay
df.clean.son([1, 2, 11])

Task mới sẽ xuất hiện trong df.clean.list() và có thể dùng trong mọi pipeline.

---

📚 Hàm tiện ích

Hàm	Mô tả
df.clean.hd()	In hướng dẫn đầy đủ 12 mục ra terminal
df.clean.list()	In danh sách 10 task mặc định + pipeline gợi ý

---

🎯 Ví dụ đầy đủ

import pandas as pd
import pandatools

# Đọc dữ liệu
df = pd.read_csv('raw_data.csv')

# Xem hướng dẫn
df.clean.hd()

# Phân tích tổng quan
df.clean.intoo()

# Làm sạch tự động
df = df.clean.auto()

# Hoặc dùng Big Data mode
df.clean.bigdata(start=True)
df = df.clean.auto()

# SƠN AI nâng cao
df.clean.ai_son(model="gpt-4o", key=1)
df = df.clean.son([1, 2, 4, 7, 8])

# Trực quan hóa
df.clean.bd('age')
df.clean.bd_scatter('age', 'income', z='gender', save='scatter.png')

# Lưu kết quả
df.clean.csv('clean_data.csv')
df.clean.to_parquet('clean_data.parquet')

---

📁 Cache

Code do AI sinh được cache tại ~/.son_cache/ dưới dạng file .py, keyed bằng MD5 của (model + prompt + columns). Lần chạy sau với cùng input sẽ dùng cache, không gọi API.

---

🔑 Biến môi trường

Vị trí	Tên biến	Dùng với key=
1	OPENAI_API_KEY	key=1
2	SON_AI_KEY	key=2
3	AI_API_KEY	key=3

Khi không truyền key, hệ thống tự động thử lần lượt 3 biến trên.

---

License: MIT Author: Sơn Lê