grahama1970/analytics

Skill de Analytics

Análise flexível de ciência de dados que funciona com qualquer conjunto de dados. Descobre automaticamente o esquema, recomenda visualizações e exporta no formato create-figure.

Início Rápido (Qualquer Conjunto de Dados)

cd .pi/skills/analytics

# Passo 1: Descubra o que está nos dados
./run.sh describe data.jsonl

# Passo 2: Veja recomendações e gere um gráfico
./run.sh chart data.jsonl --name distribution_channel -o chart.json

# Passo 3: Renderize com create-figure
cd .agent/skills/create-figure
./run.sh metrics -i /path/to/chart.json --type bar -o chart.pdf

O Pipeline Integrado

Qualquer Dado (JSONL/JSON/CSV)
         │
         ▼
┌─────────────────────────────────┐
│     analytics describe          │  ← Descobre esquema, recomenda gráficos
│  "5 colunas categóricas, 2 numéricas,	│
│   1 coluna temporal detectada"	│
│  Recomendações:               │
│   - distribution_channel (barras)  │
│   - trend_by_date (linha)        │
│   - heatmap_hour_x_day          │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│     analytics chart/group-by    │  ← Gera dados de gráfico no formato create-figure
│  --name distribution_channel    │
│  -o chart.json                  │
└─────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│     create-figure metrics       │  ← Renderiza PDF/PNG de qualidade de publicação
│  -i chart.json --type bar       │
│  -o channel_distribution.pdf    │
└─────────────────────────────────┘

Comandos

Descoberta (Comece Aqui)

Comando	Descrição
describe <arquivo>	Descobre esquema, detecta tipos de coluna, recomenda gráficos

./run.sh describe sales.jsonl
# Saída:
# Colunas: date (temporal), product (categórica), amount (numérica), region (categórica)
# Recomendações:
#   1. distribution_product - Distribuição de product
#   2. distribution_region - Distribuição de region
#   3. trend_by_date - Contagem ao longo de date
#   4. heatmap_product_x_region - product vs region

Análise Flexível

Comando	Descrição
group-by <arquivo>	Agrupa por qualquer coluna com agregação
stats <arquivo>	Estatísticas numéricas e correlações
chart <arquivo>	Gera especificação de gráfico para create-figure

# Agrupar por qualquer coluna
./run.sh group-by data.jsonl --by channel --for-figure -o by_channel.json
./run.sh group-by data.jsonl --by category --agg price --func sum

# Estatísticas numéricas
./run.sh stats data.jsonl --columns revenue,cost,profit

# Gerar gráfico a partir de recomendação
./run.sh chart data.jsonl --name distribution_channel -o chart.json

Dados com Timestamp (saídas ingest-*)

Comando	Descrição
insights <arquivo>	Resumo de análise completo (tendências, sessões, padrões)
trends <arquivo>	Tendências de visualização com médias móveis
sessions <arquivo>	Detecção de sessões e análise de maratona
time-patterns <arquivo>	Distribuição por hora/dia
evolution <arquivo>	Como as preferências mudam ao longo do tempo

Saída

Comando	Descrição
export <arquivo>	Exporta em lote todos os gráficos padrão
report <arquivo>	Relatório narrativo estilo Horus

Formatos Suportados

Formato	Extensão	Detecção Automática
JSONL	.jsonl	JSON delimitado por linha
JSON	.json	Array ou {data: [...]}
CSV	.csv	Separado por vírgulas

Detecção de Tipo de Coluna

O comando describe detecta automaticamente:

Tipo	Lógica de Detecção	Gráficos Recomendados
temporal	datetime64, strings com formato de data	linha, área, mapa de calor (eixo temporal)
numérico	int64, float64	histograma, dispersão, estatísticas
categórico	baixa cardinalidade (≤20 únicos)	barras, pizza, mapa de calor
booleano	dtype bool	pizza (verdadeiro/falso)
texto	strings de alta cardinalidade	nuvem de palavras, top-N

Recomendações de Gráfico

Com base nos tipos de coluna, o analytics recomenda:

Padrão de Dados	Tipo de Gráfico	Comando create-figure
1 categórica	barras, pizza	metrics --type bar
1 temporal	linha	training-curves
2 categóricas	mapa de calor	heatmap
temporal + categórica	mapa de calor	heatmap
2+ numéricas	matriz de correlação	heatmap
1 numérica	histograma	metrics --type bar

Fluxo de Trabalho do Agente

Para um agente de projeto analisar qualquer conjunto de dados e visualizar:

# 1. Descobrir esquema
resultado = executar("./run.sh describe data.jsonl --json")
recomendacoes = resultado["recommendations"]

# 2. Pegar a primeira recomendação
nome_grafico = recomendacoes[0]["name"]
cmd = recomendacoes[0]["create_figure_cmd"]

# 3. Gerar dados do gráfico
executar(f"./run.sh chart data.jsonl --name {nome_grafico} -o chart.json")

# 4. Renderizar
executar(f"cd .agent/skills/create-figure && ./run.sh {cmd} -i chart.json -o chart.pdf")

Exemplos

Dados de Vendas de E-commerce

# Dados: orders.jsonl com date, product, category, amount, region

./run.sh describe orders.jsonl
# → Recomenda: distribution_category, distribution_region, trend_by_date

./run.sh group-by orders.jsonl --by category --agg amount --func sum --for-figure -o revenue_by_category.json
# → {"metrics": {"Eletrônicos": 45000, "Roupas": 32000, ...}}

cd .agent/skills/create-figure
./run.sh metrics -i revenue_by_category.json --type bar -o revenue.pdf

Histórico do YouTube (ingest-yt-history)

# Use comandos especializados para dados com timestamp
./run.sh insights ~/.pi/ingest-yt-history/history.jsonl
./run.sh export ~/.pi/ingest-yt-history/history.jsonl -o ./charts --for-figure

cd .agent/skills/create-figure
./run.sh heatmap -i charts/heatmap.json -o viewing_heatmap.pdf

Dados de Resposta de API

# Dados: api_logs.json com endpoint, status_code, response_time, user_id

./run.sh describe api_logs.json
./run.sh stats api_logs.json --columns response_time
# → média=245.3ms, dp=89.2ms, p50=220ms, p99=450ms

./run.sh group-by api_logs.json --by endpoint --agg response_time --func mean --for-figure -o latency.json

Dependências

# pyproject.toml
dependencies = [
    "pandas>=2.0.0",
    "typer>=0.9.0",
    "rich>=13.0.0",
]

Integração com Horus

# Estilo narrativo Horus
./run.sh insights ~/.pi/ingest-yt-history/history.jsonl --horus

# Saída:
# "Seus padrões de visualização revelam uma tendência noturna para conteúdo melancólico.
#  O pico de atividade ocorre nas horas do crepúsculo, com o consumo de música se intensificando
#  durante sessões introspectivas noturnas..."

Erros Comuns

# ERRADO: Chamar stats diretamente em um conjunto desconhecido
./run.sh stats data.jsonl --columns revenue,cost
# → Falha em colunas não numéricas ("USD 1000" é texto, não número)
# CERTO: Sempre execute describe primeiro
./run.sh describe data.jsonl
# → Mostra tipos de coluna, recomenda comandos de gráfico corretos

# ERRADO: Escolher manualmente o tipo de gráfico sem recomendação do describe
./run.sh group-by data.jsonl --by date --agg views | ./run.sh metrics --type pie
# → Gráfico de pizza para dados de série temporal é inútil
# CERTO: Use o comando create-figure recomendado pelo describe

# ERRADO: Assumir que o esquema JSONL corresponde às expectativas
# → Campos renomeados, nulos presentes, tipos misturados
# CERTO: describe detecta tudo isso automaticamente