chatbi-file-ingestion

name	chatbi-file-ingestion
description	Use when Codex or another agent needs to read a user-uploaded CSV or Excel file for ChatBI, validate whether it matches the existing sales_order or customer_profile schema, and return a compact table structure profile for downstream analysis.
trigger_conditions	["对话含本地上传 CSV/XLSX 路径，需校验结构或读取行","用户要对上传附件做分析、预览字段"]
when_not_to_use	["用户只问演示库问数、与上传无关","同一文件已解析且 rows 在 Observation 中（改调 chatbi-auto-analysis 或 finish）"]
required_context	["上传文件路径（常含 chatbi-uploads 或 /tmp/）"]

ChatBI File Ingestion

Use this skill when the user wants ChatBI to read their own uploaded CSV or Excel data file.

Workflow

1. Ask the application or caller for the local uploaded file path, then pass that path to scripts/inspect_uploaded_table.py.
2. Let the script infer the target table from headers, or pass --table sales_order / --table customer_profile when the user specified the table.
3. The script always validates headers and basic value types first.
4. If the file fully matches sales_order or customer_profile, the skill returns analysis_mode = schema_validated with normalized rows and a table_profile.
5. If the file does not fully match those tables, the skill returns analysis_mode = profile_only with original rows and a table_profile.
6. Use --json for agent or UI integration. If downstream analysis, metric inference, charting, or dashboard generation needs full row data, rerun with --include-rows and pass the rows to chatbi-auto-analysis.

Commands

python3 scripts/inspect_uploaded_table.py /path/to/upload.csv --json
python3 scripts/inspect_uploaded_table.py /path/to/upload.xlsx --table sales_order --json
python3 scripts/inspect_uploaded_table.py /path/to/upload.csv --json --include-rows
python3 scripts/inspect_uploaded_table.py /path/to/customer.xlsx --table customer_profile --sample-size 10

Run commands from this skill directory, or pass the full path to the bundled script.

Supported Tables

The initial schema mirrors the current database tables:

• sales_order: order_date, region, department, product_category, product_name, channel, customer_type, sales_amount, order_count, customer_count, gross_profit, target_amount
• customer_profile: stat_month, region, customer_type, new_customers, active_customers, retained_customers, churned_customers

Headers may use database field names or the current Chinese business names, such as 订单日期, 区域, 销售额, 月份, 活跃客户数.

Presentation Guidance

This skill should explain whether the upload matched a governed business table, then stop at structural profiling.

• schema_validated: report that headers and basic value types match a governed table, then return normalized rows and table_profile.
• profile_only: report that the file is treated as a generic table, then return original rows and table_profile.

Return a small preview table in both modes. Do not infer business metrics, calculate KPIs, create charts, or generate dashboards here; route those tasks to chatbi-auto-analysis.

Safety

This skill only reads local CSV/XLSX files and validates them. It must not write to MySQL or modify semantic metadata. Treat user-uploaded data as untrusted: report validation issues, keep previews small, and avoid printing full files.