Skip to content

CLAUDE.md

Latest commit

 

History

History
268 lines (205 loc) · 19.2 KB

CLAUDE.md

File metadata and controls

268 lines (205 loc) · 19.2 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Este projeto eh consumer + analise. A captura, parse e merge canonicos moram no projeto irmao em ~/Desktop/multi-ai-session-data-extractor/ (filho). Aqui:

  • data/processed/ e data/unified/ chegam via dvc import do filho (read-only, frozen: true). Atualizar com dvc update. NUNCA rodar dvc add nesses paths.
  • data/curated/ eh trabalho deste projeto (topics, enriched_*, entity_hierarchy, generated_titles). DVC tracked separado.
  • data/raw/ NAO atravessa a fronteira do filho por design. Filho versiona raw inteiro (4.8GB, #28 shipped 2026-05-04), pai consome so canonicos. Excecoes pontuais via dvc import de subpath quando uma analise precisa do bruto (ex: data/raw/Claude Code/_images/).
  • Notebooks .qmd em notebooks/ consomem unified + curated via DuckDB.

Memory: project_two_projects_split.md (decisao arquitetural), project_dvc_backup.md (estado DVC). DVC: docs/dvc-runbook.md.

Project Overview

Estudo longitudinal N=1 de interacao humano-AI (~294k mensagens, dez/2022-mai/2026). 12 fontes (Claude.ai, ChatGPT, Qwen, DeepSeek, Perplexity, Gemini, NotebookLM, Grok, Kimi, Claude Code, Codex, Gemini CLI) padronizadas em parquet e consultadas via DuckDB. Analises em Quarto (.qmd) no Positron. Fundamentacao teorica em Conversation Analysis, Human-AI Interaction e autoethnografia.

Commands

# Setup
python3 -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"

# Tests (17 testes — DuckDBManager + episode_id)
pytest                           # todos
pytest tests/test_db.py -v       # DuckDB
pytest tests/features/ -v        # episode_id

# Atualizar dados canonicos do filho
dvc update data/processed.dvc data/unified.dvc   # puxa nova versao via gdrive
python scripts/smoke_test_unified.py             # valida schema + nao-encolhimento (rodar APOS dvc update)

# Versionar dados curados (deste projeto)
dvc add data/curated && git add data/curated.dvc && dvc push

# Render notebooks
./scripts/render.sh notebooks/eda                                    # pasta inteira
./scripts/render.sh notebooks/eda/08-eda-unified.qmd                 # arquivo unico

# Enrichment local (episode_id em data/unified/)
python scripts/run_enrichment.py             # default offset 0
python scripts/run_enrichment.py --offset 3
python scripts/validate_episode_window.py    # valida janela 0-6h

# USP/MBA provas workflow
python scripts/generate_usp_provas_md.py     # processa chats claude_ai pra mds no vault externo

Architecture

Filho (~/Desktop/multi-ai-session-data-extractor/) ─DVC import (frozen)─→ data/processed/
                                                                       ─→ data/unified/

                               data/curated/  (deste projeto, DVC tracked)
                                     │
                                     ↓
            DuckDB (src/db.py) ←─ data/unified/ + data/curated/
                                     │
                                     ↓
                            Notebooks Quarto (.qmd)
  • DuckDB: src/db.py (DuckDBManager) registra parquets como views, queries retornam DataFrames.
  • Config visual: src/notebook_config.py — COLORS, LABELS, TYPES compartilhados pelos notebooks.
  • Enrichment: src/features/episode_id.py — clusteriza mensagens em "episodios" (mesmo prompt em multiplas plataformas).
  • Curated: parquets gerados por notebooks de enrichment em notebooks/enrichment/. Detalhe abaixo na secao "Parquets curados".

Data Sources (snapshot do unified)

12 fontes, ~294k msgs, dez/2022-mai/2026. Detalhes (excecoes, mapeamentos, ZIPs, recortes) em docs/research/inventario-fontes.md.

Fase Fontes Tipo
1 Claude.ai, ChatGPT, Qwen, DeepSeek, Perplexity, Gemini, NotebookLM, Grok, Kimi web (chat + RAG)
2 Claude Code, Codex, Gemini CLI CLI
3 Manual saves (clippings Obsidian, copypaste-web, terminal CC) filesystem

Subagents Claude Code: interaction_type=ai_ai e parent_session_id apontando pro parent. Filtrar com WHERE interaction_type = 'human_ai' pra analises sem distorcao.

Stubs orfas Claude Code: 352 sessoes (13/jan-28/fev/2026) tiveram JSONL raiz perdido upstream. Reconstruidos como stubs identificados por title LIKE '[orphan parent — % msgs originais, JSONL perdido]'. Filtrar em analises de conteudo.

Gemini CLI orphans: Conversas presentes em logs.json mas sem chats/session-*.json correspondente viram Conversations com is_preserved_missing=True, mode='cli', e Messages role=user (sem respostas do agente — logs.json so tem prompts). Filtrar com WHERE NOT (source = 'gemini_cli' AND is_preserved_missing) quando analise exigir resposta do agente.

agent_memories (tabela auxiliar nova, 2026-05-07): memorias geradas/lidas pelo agente entre sessoes (Claude Code per-project, Codex global). Conceito separado de messages — sao artefatos persistentes que o agente mantem como contexto, NAO mensagens de conversa. ~250 rows tipico (Claude Code), 0 hoje (Codex). Schema completo em docs/unified-schema.md. Joina com conversations.project = agent_memories.project_path (Claude Code per-project) ou trata como ambient memory por source (Codex global, project_path IS NULL). NAO incluir em queries de mensagens — kind ∈ {user, feedback, project, reference, index, other} reflete tipo de memoria, nao role de conversa.

Key Docs

  • Backlog: docs/backlog.md — o que esta feito, o que falta. Consultar antes de iniciar trabalho novo. Tabela "Mapa de ataque" no topo eh ponto de entrada unico.
  • Schema contract: docs/unified-schema.md — colunas esperadas das 4 tabelas canonicas (validadas pelo smoke) + auxiliares (agent_memories etc, fora do smoke) + dtypes + null policy. Mudanca de schema no filho deve virar PR aqui antes da quebra silenciosa em notebook. Smoke test: scripts/smoke_test_unified.py.
  • DVC runbook: docs/dvc-runbook.md — comandos, credenciais, troubleshooting OAuth.
  • DVC setup manual: docs/dvc-setup-manual.md — passo-a-passo pra montar DVC+Drive em outra maquina.
  • USP/MBA provas workflow: docs/usp-mba-provas-workflow.md — pipeline de chats claude_ai pra mds no vault externo (~/Desktop/Data Science & Analytics/).
  • Inventario fontes: docs/research/inventario-fontes.md — detalhes por fonte, excecoes.
  • Filesystem chat-inputs registry: docs/research/filesystem-chat-inputs-registry.md — registro continuo de arquivos do filesystem que sao conversas AI ou inputs. Atualizar ao achar novo.
  • Fundamentacao teorica: docs/research/fundamentacao-teorica.md
  • Framework analitico: docs/research/framework-analitico.md — Cattell × tecnicas × espelho/janela.
  • Serie canonica como dado: docs/research/serie-canonica-como-dado.md
  • Metodologia categorizacao: docs/research/metodologia-categorizacao-granularidade-assimetrica.md
  • Data profiling: docs/research/data-profiling-enrichment.md
  • Project enrichment: docs/research/project-enrichment-process.md
  • Timezone fix historico: docs/research/timezone-fix-historico.md
  • Specs: docs/superpowers/specs/ — design docs, gitignored.
  • Plan archive: docs/superpowers/archive/ — planos concluidos + runbooks historicos.

Serie canonica (notebooks/main/)

Notebooks que substituem progressivamente docs estaticos. Narrativa autoetnografica em 1a pessoa, validada frase a frase pelo Marlon. Ponto atual (14/abr/2026): 5 storylines completos.

  • 00-genese-storyline.md — gestacao conceitual + viabilidade da coleta (26-31/mar).
  • 01-padronizacao-storyline.md — schema base, refinamentos, fixes 2/10/13 abr.
  • 02-categorizacao-storyline.md — project_group, topic, granularidade assimetrica. 3.268 human_ai 100% categorizadas.
  • 03-metodologia-storyline.md — fundamentacao teorica + Mixed Analysis + matriz epistemologica.
  • 04-analise-storyline.md — framework Cattell × tecnicas × espelho/janela. 5 notebooks executores em notebooks/analysis/main-04/ (P/Q/R-mode, Sequential, Platform Signatures).

Drafts em _backup-* sao IA-gerados e NAO sao autoridade. Usar dados, nao vocabulario deles.

Proximo: 05-analise (opcional, aprofundamentos), nao iniciado.

Notebooks (notebooks/)

EDA (notebooks/eda/)

# Notebook Conteudo
08 eda-unified EDA cross-plataforma: streamgraph, temporal, 863 pares comparative prompting
09 eda-patterns 10 padroes analiticos
14 overview-streamgraph Streamgraph 12 fontes, human_ai vs ai_ai
15 projetos-cross-plataforma Cross-plataforma project_group
16 agent-memories EDA exploratorio das memorias persistentes do agente (claude_code, 253 rows, 19 projetos, 6 kinds)

Qualitizing (notebooks/qualitizing/)

# Notebook Conteudo
10 arqueologia-tematica 14 temas intelectuais, genealogia 24/mai-3/jun
11 grafo-genealogico Grafo de evolucao conceitual
12 timeline-entities Timeline por entity
14 timeline-narrativa-2025 Narrativa 2025

Data-profile (data-profile/)

20 notebooks com template padronizado (_template.qmd, 15 secoes). Tipos: web-chat, web-rag (NotebookLM), cli. Modulo compartilhado: src/notebook_config.py.

# Notebook Conteudo
00 consolidado-geral Profiling — todas as 12 fontes
01 consolidado-web-chat Profiling — 8 fontes web-chat
02 consolidado-web-rag Profiling — NotebookLM (3 contas)
03 consolidado-cli Profiling — 3 fontes CLI
04-15 por ferramenta Profiling individual + subcontas (Gemini 2, NotebookLM 3, Grok, Kimi)

Enrichment (notebooks/enrichment/)

Geram parquets em data/curated/. Notebooks chave:

  • 01-title-generation.qmd — generated_titles
  • 05-project-enrichment-v2.qmd — enriched_projects + topics_vocabulary + conversation_topics
  • 15-estrategia-orfas.qmd — entity_hierarchy
  • 16-consolidacao-single-pg.qmd — entity_hierarchy_consolidated
  • 17-chatgpt-voice-candidates.qmd — chatgpt_voice_candidates

Analysis (notebooks/analysis/)

Aplicacao do framework analitico (storyline 04). Subpasta main-04/ tem 5 executores: P-mode, Q-mode, R-mode, Sequential, Platform Signatures.

Archive (notebooks/archive/poc-exploration-data/)

Notebooks originais que liam JSON raw. Substituidos pelo data-profile. Preservados pra referencia.

ALERTA: dados curados NUNCA podem ser sobrescritos

data/curated/ eh o trabalho ativo deste projeto. NUNCA deve ser deletado ou sobrescrito por nada. dvc update em processed/unified nao toca em curated (paths separados), mas atencao a scripts que processem unified e cuspam output em curated — sempre LER de unified, MERGEAR no que ja existe em curated.

Itens pendentes de revisao (gitignored ate decisao)

Arquivos/pastas que entraram no working tree mas ainda nao foram triados. Estao no .gitignore pra manter o repo limpo. Nao deletar. Quando der tempo, decidir destino (committar, mover pra outro lugar, ou descartar).

Item Tipo Observacao
Claude files & resources/ pasta 5 subpastas: Claude Errors, Claude Insights, Claude Skills, IA user-profile (Me), yt-nblm-skill
plans/ pasta 61 arquivos .md (planos antigos jan-fev/2026), pode ser scratch ou material util
README_public.md arquivo 19KB, criado 25/abr/2026 — versao publica do README?
docs/research/Screen Recording 2026-04-27 at 22.36.55.mov arquivo 7.6MB, gravacao de tela 27/abr — provavelmente relacionada a algum achado de pesquisa
scripts/generate_usp_provas_md.py modified +25/-1 linhas nao commitadas — revisar diff antes de decidir

Conventions

  • Commits: conventional commits em portugues via ~/.claude/scripts/commit.sh.
  • Idioma do codigo: ingles. Comentarios e docs em portugues.
  • Quando o usuario pedir algo, fazer. Nao perguntar "quer que eu faca?". Nao propor alternativas quando a instrucao eh clara. Entregar no formato util (links clicaveis, nao terminal output).
  • Timestamps em BRT naive (America/Sao_Paulo) — parquets em unified vem normalizados pelo filho. Historico do fix: docs/research/timezone-fix-historico.md.
  • Codigo Python colapsado por default em notebooks. Regra global em notebooks/_quarto.yml (code-fold: true + code-tools: true). Leitor ve narrativa+tabelas+plots; codigo abre sob demanda bloco a bloco ou via "Show All Code" no topo. Front matter individual sobrescreve se precisar.
  • Dados em notebooks SEMPRE viram tabela Styler. Proibido print(df), df.to_string(), for row in df.iterrows(): print(...), df.to_markdown(), ou Markdown tables com pipes. Para preview de texto longo dentro de celula, usar <pre style="white-space:pre-wrap; max-width:560px; ...">...</pre> na coluna e renderizar com .style.format({...}, escape=None). Detalhe e exemplos na memory feedback_notebook_tables.md.
  • Render quirk: o python da .venv aponta pro python3.14 do homebrew sem isolamento. quarto render precisa da venv ativada (source .venv/bin/activate && quarto render ...) — QUARTO_PYTHON=.venv/bin/python sozinho NAO carrega os pacotes da venv.

Gestao de docs — atualizar JUNTO com o trabalho

Gatilho Atualizar O que muda
Completou item do backlog docs/backlog.md Marcar [x], atualizar numeros
Achado novo de pesquisa docs/research/<doc-relevante> Adicionar secao
Descobriu lacuna docs/backlog.md Adicionar em "Lacunas" ou "Fios soltos"
Decisao arquitetural MEMORY (tipo project) Registrar principio + por que
Feedback do usuario MEMORY (tipo feedback) Como trabalhar melhor
Mudanca em fonte upstream docs/research/inventario-fontes.md Secao da fonte

O que NAO duplicar: MEMORY nao repete o backlog. Backlog = estado/tarefas. MEMORY = contexto/decisoes/perfil.

Dissecacao das orfas — nb 15 (100% fechado, checklist preservado)

Notebook: notebooks/enrichment/15-estrategia-orfas.qmd. Estado: 938/938 classificadas (100%) + GT Lixo com 182 convs inaproveitaveis + 5 recuperadas do lixo. Fechado em 2026-04-09. Doc do metodo: docs/research/metodologia-categorizacao-granularidade-assimetrica.md. Historico + aprendizados em memory: project_nb15_state.md.

Regras criticas (aprendidas ao longo do nb 15, aplicaveis a trabalhos futuros de categorizacao):

  • SEMPRE render+open apos QUALQUER edicao no .qmd — sem perguntar, sem acumular.
  • NUNCA aplicar cluster sem ler conteudo real (titulos mentem — varios casos "Plotly Positron" era TQSA, "Obsidian plugin" era DataLab, etc).
  • NUNCA chutar conversation_ids truncados — sempre re-querar do DB (bug recorrente).
  • NUNCA adicionar em conv_topic_override sem adicionar em conv_pg_override — conversa fica invisivel.
  • SEMPRE que adicionar um topic value novo em conv_topic_override, registrar em topic_promote (2-tuple) ou topic_promote_subsub (3-tuple). Bug historico: 37+ convs caiam em "Empty" silenciosamente.
  • NUNCA adicionar no meio dos dicts — sempre no FINAL.
  • Mostrar dados antes de decidir — o ritmo "investigar → mostrar → decidir → aplicar → renderizar" eh inegociavel.
  • topic_promote = 2-tuple (entity, sub) / topic_promote_subsub = 3-tuple (entity, sub, sub_sub) — NAO confundir.
  • Voice mode chatgpt — colar conteudo no arquivo manual data/curated/chatgpt_voice_manual_content.md.
  • Sub_sub = episodio/artefato tematico do projeto, nao conceito metodologico.
  • Empty-title ≠ lixo automatico — sempre contar user msgs com LENGTH > 30 antes de descartar.
  • Ao finalizar sessao: atualizar docs (metodologia, backlog), memory, e committar.

Como consultar dados:

  • SEMPRE usar from src.db import DuckDBManager + db = DuckDBManager('data/unified') — registra todos os parquets como views automaticamente.
  • O parquet de enrichment esta em data/curated/enriched_projects.parquet — ler com pd.read_parquet(), NAO via DuckDB.
  • NUNCA usar duckdb.connect() direto ou read_parquet() no SQL — as views do DuckDBManager ja existem.
  • Fechar com db.close() no final.

Schema das views DuckDB (nomes exatos das colunas):

  • conversations: conversation_id, source, title, created_at, updated_at, message_count, model, account, mode, project, url, interaction_type, parent_session_id
  • messages: message_id, conversation_id, source, sequence, role, content, model, created_at, account, token_count, word_count, attachment_names, content_types, thinking, tool_results
  • conversation_projects: conversation_id, project_tag, tagged_by, confidence (NAO tem project_name — usar project_tag)
  • events: event_id, conversation_id, message_id, source, event_type, tool_name, file_path, command, duration_ms, success, metadata_json

Parquets curados em data/curated/ (pd.read_parquet, NAO via DuckDB):

Parquet Colunas Descricao
enriched_projects.parquet conversation_id, project_group, method Rodada 1 — 2.011 convs, 39 groups
topics_vocabulary.parquet topic, topic_type Rodada 2 — 152 topics, 16 topic_types
conversation_topics.parquet conversation_id, topic, role Rodada 2 — 3.535 registros (primary + secondary)
entity_hierarchy.parquet conversation_id, source, project_group, entity, sub_entity, sub_sub_entity Hierarquia 4 niveis — 3.292 rows, 3.067 convs, 16 entities, 123 subs, 187 sub_subs. Multi-membership preservado (convs transversais aparecem 2x)
entity_hierarchy_consolidated.parquet idem Versao single-PG do entity_hierarchy (1 row por conv). Gerado pelo nb 16. Usar pra contagens matematicas (Sankeys, P/Q/R-mode). Usar o original pra leitura etnografica
chatgpt_voice_candidates.parquet conversation_id, title, created_at, url, msg_count, placeholders, voice_score, classification, has_manual Classificacao de convs ChatGPT suspeitas de voice mode. 4 niveis (full_voice/mostly_voice/mixed/occasional). Gerado pelo nb 17
  • enriched_projects: project_group eh valor exato (ex: "DataLab GAS, Estapar, Eduzz NPS", nao "multi-membership"). Multi-memberships usam virgula no nome — filtrar com == exato, nao LIKE.
  • conversation_topics: role eh "primary" ou "secondary". Para ver TUDO de um topic: topics[topics['topic'] == 'MCA'] (sem filtrar role). Topics e secondaries usam o mesmo vocabulario controlado.
  • topics_vocabulary: vocabulario unificado. Todo valor em conversation_topics.topic existe aqui.
  • entity_hierarchy: hierarquia derivada do nb 15. sub_sub_entity e sub_entity podem ser None (atomicos puros pulam niveis). Multi-membership gera multiplas rows por conversation_id. PG eh scaffolding visual, entity/sub/sub_sub sao a classificacao real.
  • entity_hierarchy_consolidated: camada complementar gerada pelo nb 16. Mesma estrutura mas 1 row por conversation_id (multi-membership colapsado). Usar pra contagem honesta (Sankeys, P/Q/R-mode, correlacoes). Pra leitura etnografica (quais convs transversais entre projetos?), usar o original.

Dicas DuckDB (evitar erros comuns):

  • content pode ser NULL — usar COALESCE(content, '') antes de funcoes de string.
  • Truncar texto: content[:300] (slice Python-style) ou LEFT(COALESCE(content, ''), 300).
  • Strings: aspas simples 'texto', nao aspas duplas.