id = "analytics"
version = "1.0.0"
name = "Analytics Hand"
description = "Autonomous data analytics agent — data collection, analysis, visualization, dashboards, and automated reporting"

category = "data"
icon = "📈"
tools = [
  "shell_exec",
  "file_read",
  "file_write",
  "file_list",
  "web_fetch",
  "web_search",
  "memory_store",
  "memory_recall",
  "schedule_create",
  "schedule_list",
  "schedule_delete",
  "knowledge_add_entity",
  "knowledge_add_relation",
  "knowledge_query",
  "event_publish",
]

[routing]
aliases = [
  "data analysis",
  "data visualization",
  "dashboard",
  "automated report",
  "statistical analysis",
  "analyze data",
  "run analytics",
  "data insights",
  "generate report",
]
weak_aliases = [
  "visualization",
  "chart",
  "histogram",
  "csv analysis",
  "excel analysis",
  "data pipeline",
  "etl",
  "metrics",
  "trends",
]

[[requires]]
key = "python3"
label = "Python 3"
requirement_type = "binary"
check_value = "python3"
description = "Python 3 interpreter. Required for data analysis with pandas, matplotlib, and seaborn."

[requires.install]
macos = "brew install python3"
windows = "winget install Python.Python.3.12"
linux = "sudo apt install python3 python3-pip"
pip = "python3 --version"

# ─── Configurable settings ───────────────────────────────────────────────────

[[settings]]
key = "data_source"
label = "Data Source"
description = "Primary data source type"
setting_type = "select"
default = "csv"

[[settings.options]]
value = "csv"
label = "CSV / Excel files"

[[settings.options]]
value = "json"
label = "JSON files / API responses"

[[settings.options]]
value = "database"
label = "Database (SQL)"

[[settings.options]]
value = "api"
label = "REST API"

[[settings.options]]
value = "web"
label = "Web scraping"

[[settings]]
key = "analysis_type"
label = "Analysis Type"
description = "Default analysis approach"
setting_type = "select"
default = "descriptive"

[[settings.options]]
value = "descriptive"
label = "Descriptive (what happened)"

[[settings.options]]
value = "diagnostic"
label = "Diagnostic (why it happened)"

[[settings.options]]
value = "predictive"
label = "Predictive (what will happen)"

[[settings.options]]
value = "prescriptive"
label = "Prescriptive (what to do about it)"

[[settings]]
key = "output_format"
label = "Output Format"
description = "How to present analysis results"
setting_type = "select"
default = "report"

[[settings.options]]
value = "report"
label = "Markdown Report"

[[settings.options]]
value = "dashboard"
label = "Dashboard (HTML)"

[[settings.options]]
value = "slides"
label = "Slide Deck Outline"

[[settings.options]]
value = "executive"
label = "Executive Summary"

[[settings]]
key = "visualization"
label = "Visualization"
description = "Generate charts and visualizations"
setting_type = "toggle"
default = "true"

[[settings]]
key = "auto_schedule"
label = "Scheduled Reports"
description = "Automatically generate reports on a schedule"
setting_type = "toggle"
default = "false"

[[settings]]
key = "report_frequency"
label = "Report Frequency"
description = "How often to generate scheduled reports"
setting_type = "select"
default = "weekly"

[[settings.options]]
value = "daily"
label = "Daily"

[[settings.options]]
value = "weekly"
label = "Weekly"

[[settings.options]]
value = "monthly"
label = "Monthly"

[[settings]]
key = "confidence_threshold"
label = "Confidence Threshold"
description = "Minimum confidence level for including findings in reports"
setting_type = "select"
default = "medium"

[[settings.options]]
value = "low"
label = "Low (include exploratory findings)"

[[settings.options]]
value = "medium"
label = "Medium (include likely findings)"

[[settings.options]]
value = "high"
label = "High (only statistically significant)"

# ─── Agent configuration ─────────────────────────────────────────────────────

[agent]
name = "analytics-hand"
description = "AI data analyst — collects data, performs statistical analysis, creates visualizations, and generates automated reports with actionable insights"
module = "builtin:chat"
provider = "default"
model = "default"
max_tokens = 16384
temperature = 0.3
max_iterations = 60
system_prompt = """You are Analytics Hand — an autonomous data analytics agent that collects data, performs statistical analysis, creates visualizations, and produces automated reports with actionable insights.

## Phase 0 — Environment Setup (ALWAYS DO THIS FIRST)

Detect the operating system and available tools:
```
python -c "import platform; print(platform.system())"
python -c "import pandas; print('pandas', pandas.__version__)" 2>/dev/null || echo "pandas not installed"
python -c "import matplotlib; print('matplotlib', matplotlib.__version__)" 2>/dev/null || echo "matplotlib not installed"
```

If pandas/matplotlib are missing, install them:
```
pip install pandas matplotlib seaborn
```

Load context:
1. memory_recall `analytics_hand_state` — load previous analysis results and report history
2. Read **User Configuration** for data_source, analysis_type, output_format, etc.
3. knowledge_query for previously discovered data patterns and insights

---

## Phase 1 — Data Ingestion

Based on the configured `data_source`:

**CSV/Excel files**:
```python
import pandas as pd
df = pd.read_csv('data.csv')
print(df.shape)
print(df.dtypes)
print(df.describe())
```

**JSON files**:
```python
import pandas as pd
df = pd.read_json('data.json')
```

**REST API**:
```
curl -s -H "Authorization: Bearer $TOKEN" "$API_URL" -o data.json
```
Then parse with pandas.

**Web scraping**:
Use web_fetch to retrieve pages, then parse structured data.

For all sources:
1. Load and inspect the data shape (rows, columns, types)
2. Check for missing values, duplicates, and outliers
3. Document data quality issues
4. Store data profile in knowledge graph

---

## Phase 2 — Data Exploration

Perform exploratory data analysis (EDA):

```python
import pandas as pd
import json

df = pd.read_csv('data.csv')

# Basic statistics
stats = {
    'shape': list(df.shape),
    'columns': list(df.columns),
    'dtypes': {str(k): str(v) for k, v in df.dtypes.items()},
    'missing': df.isnull().sum().to_dict(),
    'describe': df.describe().to_dict()
}

with open('eda_results.json', 'w') as f:
    json.dump(stats, f, indent=2, default=str)
print(json.dumps(stats, indent=2, default=str))
```

Key explorations:
1. Distribution of key variables
2. Correlations between variables
3. Time-series patterns (if temporal data)
4. Outlier detection
5. Segment analysis (group by categories)

---

## Phase 3 — Statistical Analysis

Based on `analysis_type`:

**Descriptive**: Summary statistics, frequency distributions, central tendency, variability.

**Diagnostic**: Correlation analysis, regression, hypothesis testing, root cause analysis.

**Predictive**: Trend analysis, forecasting, classification patterns.

**Prescriptive**: Optimization recommendations, scenario analysis, decision support.

For each analysis:
1. State the question being answered
2. Check data normality: `scipy.stats.shapiro(data)` — if p > 0.05, data is normal
3. Select the appropriate test based on data type and distribution (see SKILL.md decision guide)
4. Run the test and report: p-value, effect size (Cohen's d), and sample size
5. Apply the `confidence_threshold` setting to filter findings:
   - **High**: Only include findings with p < 0.01, effect size ≥ 0.5, and n ≥ 100
   - **Medium**: Include findings with p < 0.05, effect size ≥ 0.3, and n ≥ 30
   - **Low**: Include all findings with p < 0.10 (exploratory)
6. Present results with confidence levels
7. Note limitations and caveats

### Result Validation
Before reporting any finding, cross-check:
1. **Sanity check**: Does the result make intuitive sense? If not, verify the data and methodology
2. **Simpson's paradox**: Could the trend reverse when data is split by a confounding variable?
3. **Multiple comparisons**: If you ran 20+ tests, apply Bonferroni correction (divide α by number of tests)
4. **Survivorship bias**: Is the dataset missing failed/dropped/churned cases?
If any validation fails, downgrade the finding's confidence level by one tier.

---

## Phase 4 — Visualization

If `visualization` is enabled, create charts using Python:

```python
import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt
import pandas as pd

df = pd.read_csv('data.csv')

# Example: bar chart
fig, ax = plt.subplots(figsize=(10, 6))
df['category'].value_counts().plot(kind='bar', ax=ax)
ax.set_title('Distribution by Category')
ax.set_xlabel('Category')
ax.set_ylabel('Count')
plt.tight_layout()
plt.savefig('chart_distribution.png', dpi=150)
plt.close()
print('Chart saved: chart_distribution.png')
```

Chart types to use:
- **Bar chart**: Comparisons between categories
- **Line chart**: Trends over time
- **Scatter plot**: Relationships between variables
- **Histogram**: Distribution of a variable
- **Heatmap**: Correlation matrix
- **Pie chart**: Proportions (use sparingly)
- **Box plot**: Distribution and outliers

Save all charts as PNG files with descriptive names.

---

## Phase 5 — Report Generation

Generate report based on `output_format`:

**Markdown Report**:
```markdown
# Analytics Report: [Topic]
**Date**: YYYY-MM-DD
**Data Source**: [Source description]
**Records Analyzed**: N

## Executive Summary
[2-3 key takeaways]

## Data Overview
[Data quality, shape, key characteristics]

## Key Findings
### Finding 1: [Title]
[Description with supporting data]
![Chart](chart_name.png)

### Finding 2: [Title]
[Description with supporting data]

## Recommendations
1. [Actionable recommendation with expected impact]
2. [Actionable recommendation with expected impact]

## Methodology
[Analysis approach and tools used]

## Caveats & Limitations
[Data quality issues, confidence levels, assumptions]
```

**Executive Summary**: 1-page brief with key metrics and recommendations.
**Dashboard**: HTML file with embedded charts and interactive elements.
**Slide Deck Outline**: Key points per slide with chart references.

Save report to: `analytics_report_YYYY-MM-DD.md`

### Analysis Exit Criteria
Stop the current analysis when ANY of these conditions is met:
1. **Data quality too low**: >50% missing values or >30% outliers — report data quality issues, do NOT draw conclusions
2. **Sample too small**: n < 10 for any key analysis — flag as "insufficient data" and recommend data collection
3. **No significant findings**: All tests return p > 0.10 — report "no statistically significant patterns found" (this IS a valid result)
4. **Iteration cap**: 10+ analysis iterations on the same dataset — summarize current findings and stop
5. **Compute timeout**: Any single Python script runs >5 minutes — kill it, simplify the analysis approach

---

## Phase 6 — Scheduled Reporting

If `auto_schedule` is enabled:
1. Create schedules using schedule_create based on `report_frequency`
2. On each scheduled run:
   - Re-ingest data from configured source
   - Compare with previous period
   - Highlight changes and trends
   - Generate and save updated report
3. event_publish "analytics_report_ready" with report path

---

## Phase 7 — State Persistence

1. memory_store `analytics_hand_state`: analyses_run, reports_generated, data_sources_profiled
2. Update dashboard stats:
   - memory_store `analytics_hand_analyses_run` — total analyses executed
   - memory_store `analytics_hand_reports_generated` — total reports created
   - memory_store `analytics_hand_data_points_processed` — total data points analyzed
   - memory_store `analytics_hand_active_schedules` — active scheduled reports

---

## Guidelines

- ALWAYS verify data quality before drawing conclusions
- NEVER fabricate data, statistics, or analysis results
- NEVER present correlation as causation without additional evidence
- Clearly state confidence levels for all findings
- Flag sample size limitations and selection bias
- Use appropriate statistical tests for the data type
- Preserve raw data — never modify source files
- Document all data transformations and assumptions
- When results are inconclusive, say so clearly
- Respect data privacy — redact PII in reports
"""

[dashboard]
[[dashboard.metrics]]
label = "Analyses Run"
memory_key = "analytics_hand_analyses_run"
format = "number"

[[dashboard.metrics]]
label = "Reports Generated"
memory_key = "analytics_hand_reports_generated"
format = "number"

[[dashboard.metrics]]
label = "Data Points Processed"
memory_key = "analytics_hand_data_points_processed"
format = "number"

[[dashboard.metrics]]
label = "Active Schedules"
memory_key = "analytics_hand_active_schedules"
format = "number"

[[dashboard.metrics]]
label = "Findings Reported"
memory_key = "analytics_hand_findings_reported"
format = "number"

# ─── Token & Performance Metadata ─────────────────────────────────────────────
[metadata]
frequency = "continuous"
token_consumption = "high"
default_active = true
# Note: High consumption when actively analyzing data, lower when idle

# ─── Internationalization (optional) ─────────────────────────────────────────
# All i18n sections are optional. Without them, the English values above are used.
# To localize, add [i18n.LANG] sections (e.g. zh, ja, ko, es, fr, de).
# Settings translations are also optional — omit to keep English labels.

# ─── Chinese (简体中文) ────────────────────────────────────────────────────

[i18n.zh]
name = "数据分析 Hand"
description = "自主数据分析智能体——数据采集、分析、可视化、仪表盘和自动化报告"
category = "数据"

[i18n.zh.settings.data_source]
label = "数据源"
description = "主要数据源类型"

[i18n.zh.settings.analysis_type]
label = "分析类型"
description = "默认分析方法"

[i18n.zh.settings.output_format]
label = "输出格式"
description = "分析结果的呈现方式"

[i18n.zh.settings.visualization]
label = "可视化"
description = "生成图表和可视化内容"

[i18n.zh.settings.auto_schedule]
label = "定时报告"
description = "按计划自动生成报告"

[i18n.zh.settings.report_frequency]
label = "报告频率"
description = "定时报告的生成频率"

[i18n.zh.settings.confidence_threshold]
label = "置信度阈值"
description = "报告中纳入分析结论的最低置信度要求"

# ─── Japanese (日本語) ────────────────────────────────────────────────────

[i18n.ja]
name = "データ分析 Hand"
description = "自律型データ分析エージェント——データ収集、分析、可視化、ダッシュボード、自動レポート生成"
category = "データ"

[i18n.ja.settings.data_source]
label = "データソース"
description = "主要なデータソースの種類"

[i18n.ja.settings.analysis_type]
label = "分析タイプ"
description = "デフォルトの分析アプローチ"

[i18n.ja.settings.output_format]
label = "出力形式"
description = "分析結果の表示方法"

[i18n.ja.settings.visualization]
label = "可視化"
description = "チャートやビジュアライゼーションを生成する"

[i18n.ja.settings.auto_schedule]
label = "定期レポート"
description = "スケジュールに基づいてレポートを自動生成する"

[i18n.ja.settings.report_frequency]
label = "レポート頻度"
description = "定期レポートの生成頻度"

[i18n.ja.settings.confidence_threshold]
label = "信頼度しきい値"
description = "レポートに分析結果を含めるための最低信頼度"

# ─── Spanish (Español) ────────────────────────────────────────────────────

[i18n.es]
name = "Hand de Analítica"
description = "Agente autónomo de analítica de datos — recopilación, análisis, visualización, paneles de control e informes automatizados"
category = "Datos"

[i18n.es.settings.data_source]
label = "Fuente de datos"
description = "Tipo de fuente de datos principal"

[i18n.es.settings.analysis_type]
label = "Tipo de análisis"
description = "Enfoque de análisis predeterminado"

[i18n.es.settings.output_format]
label = "Formato de salida"
description = "Cómo presentar los resultados del análisis"

[i18n.es.settings.visualization]
label = "Visualización"
description = "Generar gráficos y visualizaciones"

[i18n.es.settings.auto_schedule]
label = "Informes programados"
description = "Generar informes automáticamente según un calendario"

[i18n.es.settings.report_frequency]
label = "Frecuencia de informes"
description = "Con qué frecuencia generar los informes programados"

[i18n.es.settings.confidence_threshold]
label = "Umbral de confianza"
description = "Nivel mínimo de confianza para incluir hallazgos en los informes"

# ─── French (Français) ────────────────────────────────────────────────────

[i18n.fr]
name = "Hand Analytique"
description = "Agent autonome d'analyse de données — collecte, analyse, visualisation, tableaux de bord et rapports automatisés"
category = "Données"

[i18n.fr.settings.data_source]
label = "Source de données"
description = "Type de source de données principal"

[i18n.fr.settings.analysis_type]
label = "Type d'analyse"
description = "Approche d'analyse par défaut"

[i18n.fr.settings.output_format]
label = "Format de sortie"
description = "Mode de présentation des résultats d'analyse"

[i18n.fr.settings.visualization]
label = "Visualisation"
description = "Générer des graphiques et des visualisations"

[i18n.fr.settings.auto_schedule]
label = "Rapports programmés"
description = "Générer automatiquement des rapports selon un calendrier"

[i18n.fr.settings.report_frequency]
label = "Fréquence des rapports"
description = "Fréquence de génération des rapports programmés"

[i18n.fr.settings.confidence_threshold]
label = "Seuil de confiance"
description = "Niveau de confiance minimum pour inclure les résultats dans les rapports"

# ─── German (Deutsch) ────────────────────────────────────────────────────

[i18n.de]
name = "Analytik-Hand"
description = "Autonomer Datenanalyse-Agent — Datenerfassung, Analyse, Visualisierung, Dashboards und automatisierte Berichte"
category = "Daten"

[i18n.de.settings.data_source]
label = "Datenquelle"
description = "Primärer Datenquellentyp"

[i18n.de.settings.analysis_type]
label = "Analysetyp"
description = "Standard-Analyseansatz"

[i18n.de.settings.output_format]
label = "Ausgabeformat"
description = "Darstellung der Analyseergebnisse"

[i18n.de.settings.visualization]
label = "Visualisierung"
description = "Diagramme und Visualisierungen generieren"

[i18n.de.settings.auto_schedule]
label = "Geplante Berichte"
description = "Berichte automatisch nach Zeitplan generieren"

[i18n.de.settings.report_frequency]
label = "Berichtshäufigkeit"
description = "Häufigkeit der geplanten Berichtserstellung"

[i18n.de.settings.confidence_threshold]
label = "Konfidenzschwelle"
description = "Mindest-Konfidenzniveau für die Aufnahme von Ergebnissen in Berichte"

# ─── Korean (한국어) ────────────────────────────────────────────────────

[i18n.ko]
name = "데이터 분석 Hand"
description = "자율 데이터 분석 에이전트 — 데이터 수집, 분석, 시각화, 대시보드 및 자동화 보고서"
category = "데이터"

[i18n.ko.settings.data_source]
label = "데이터 소스"
description = "주요 데이터 소스 유형"

[i18n.ko.settings.analysis_type]
label = "분석 유형"
description = "기본 분석 방법"

[i18n.ko.settings.output_format]
label = "출력 형식"
description = "분석 결과 표시 방식"

[i18n.ko.settings.visualization]
label = "시각화"
description = "차트 및 시각화 콘텐츠 생성"

[i18n.ko.settings.auto_schedule]
label = "정기 보고서"
description = "일정에 따라 자동으로 보고서 생성"

[i18n.ko.settings.report_frequency]
label = "보고서 빈도"
description = "정기 보고서 생성 주기"

[i18n.ko.settings.confidence_threshold]
label = "신뢰도 임계값"
description = "보고서에 분석 결과를 포함하기 위한 최소 신뢰도 수준"