Gyovana Santos do Prado

Construído em FastAPI com Pydantic AI para parsing. Pipeline central: extração de fatos → atomização multi-pass → geração de documentos (padrão H3). Guardrail de grounding rejeita qualquer afirmação sem proveniência direta de registro. Arquitetura multi-provider (OpenAI e Anthropic validados de forma intercambiável via model-as-config). Sequenciamento de build ciente de DAG: cards em paralelo onde dependências permitiam, sequencial onde schemas precisavam estabilizar primeiro. Fechou empiricamente uma questão arquitetural — cálculo de fatos sob demanda foi descartado após zero ocorrências em runs com dados reais, evitando abstração prematura. Seis PRs empilhados estruturados para sequência de merge limpa.

Spike comparando três fluxos de extração LLM para dados qualitativos (respostas abertas de pesquisa de satisfação) usando Pydantic AI e prompts Jinja via ai-prompter:

• H3 (dois estágios: fatos → claims atômicos → síntese): $0,0216/doc, 0 violações de altitude, 100% de grounding
• H1+doc_separado: $0,0296/doc, 1 violação, 71% de cobertura de famílias de fatos
• H3+predraft (H3 + rascunho prévio): $0,0348/doc, 3 violações, 60% mais claims mas com mais ruído

Trade-off central: H3+predraft gerou 60% mais claims que H3, mas introduziu 3 'violações de altitude' (generalizações sem suporte nos dados). H1 teve maior cobertura de fatos (71% vs 57% de famílias) mas custo maior e uma violação. H3 venceu em todos os critérios ponderados.

O pipeline inclui um guard determinístico de PII (emails, telefones, CPF, handles) rodando antes de qualquer chamada LLM — 20% das respostas reais continham PII, tornando esse passo obrigatório. Um validador quote_grounding confirma que cada claim gerado rastreia até uma citação verbatim, tornando o pipeline auditável. O fact index cobre 67 fatos em 7 famílias (boolean, categorical, cooccurrence, cross_tab, matrix, multi_select, persona).

O parser usa Pydantic AI com output_type=PersonaSpec, e PersonaSpec contém objetos PersonaVariable com campos opcionais order e scale. A escolha de design: ambos os campos usam Optional[list] = None em vez de list[str] = []. Razão: a fábrica downstream chama model_dump(exclude_none=True) e depois verifica 'order' in var — uma lista vazia [] seria falsy em checagem booleana mas truthy para in, quebrando silenciosamente o tratamento de variáveis ordinais. Com defaults None, exclude_none=True remove as chaves completamente, e 'order' in var retorna corretamente False para variáveis categóricas. A suíte de testes usa TestModel(custom_output_args={...}) do Pydantic AI para substituir o LLM por output estruturado determinístico — sem chamadas de API no CI. Um teste (test_parse_persona_spec_model_dump_exclui_nulos) documenta explicitamente o invariante de ausência de chave. Stack: Pydantic AI, FastAPI, Pydantic v2, pytest.

SurrealDB v3, Python, uv. A migration cria novas tabelas SCHEMAFULL e re-tipa campos existentes. O ponto crítico: re-tipar um campo em uma tabela SCHEMAFULL pré-existente exige DEFINE FIELD OVERWRITE — um DEFINE FIELD simples pode não fazer nada ou lançar erro dependendo da versão do SurrealDB. O down migration reverte na ordem inversa de dependências e remove explicitamente sub-campos de array para evitar campos fantasma residuais.

Bug de ambiente: dois projetos compartilhando o mesmo namespace/database no SurrealDB faziam suas tabelas de tracking de migrations colidirem. O runner do outro projeto havia inserido linhas na tabela compartilhada; ao tentar rollback, o runner não encontrava os arquivos de migration correspondentes no diretório do projeto atual e abortava. Correção imediata: deleção manual dos registros contaminantes. Solução definitiva: cada projeto usa seu próprio par namespace/database em dev local.

Sessão de design arquitetural para um serviço FastAPI async (Python / Pydantic AI / SurrealDB) que processa dados de pesquisa survey em insights estruturados e auditáveis — substituindo um pipeline legado baseado em claude -p no shell.

Medir antes de decidir: Antes de comprometer com um pipeline de retrieval/seleção, escrevemos um script para consultar o SurrealDB local e medir o fact space persistido. Resultado: 12–14 k tokens (6% da janela de contexto). Nenhum pipeline se justificava até esse sintoma aparecer em produção — um número concreto fechou um debate que seria puramente especulativo.

Regime híbrido determinístico/LLM: O núcleo de insights foi dividido em dois regimes com invariantes distintos:

• Questões fechadas (Likert, NPS, múltipla escolha): Python puro, completamente determinístico, testável com golden files — LLM nunca toca esse caminho.
• Questões abertas/qualitativas: LLM identifica temas e padrões de frequência; um guardrail de quote-grounding (substring match verbatim contra o CSV fonte) valida cada afirmação antes da persistência. Alucinação capturada sem embeddings — custo zero, 100% auditável. O invariante: todo fato qualitativo precisa citar um fragmento rastreável da fonte.

Falha de guardrail como sinal de avaliação: O output validator do Pydantic AI faz 1 retry em falha; falhas persistentes são gravadas com flag guardrail_failed em vez de descartadas. Justificativa: nas primeiras runs em produção, a taxa de falha é o sinal de qualidade mais valioso — descartar silenciosamente os outputs que falham esconde exatamente o que se precisa aprender.

Fact space recomputado por run: Cada run reconstrói seu próprio fact space a partir dos specs da fonte e o persiste de forma independente. Trade-off: computação redundante vs. reprodutibilidade total — qualquer run pode ser reauditada em isolamento, independente de mudanças futuras no schema ou nos dados.

Três componentes: um site estático em Astro (i18n EN/PT, feed/projetos/CV renderizados de JSON no build), um servidor MCP em Python expondo cinco tools (log_activity, review_and_publish, add_project, update_now, get_portfolio_state) que escrevem pela API de Contents do GitHub, e um hook de Stop que embute o rubric verbatim — mudar critérios não exige mudar código. A validação tem três camadas: JSON Schema, completude bilíngue (tradução faltando quebra o build, de propósito) e uma denylist local como retaguarda determinística atrás da sanitização por categoria do LLM.

animation-timeline: view() mapeia o progresso de uma animação à posição do elemento no viewport — a borda da linha do tempo escala de 0 à altura total conforme cada entrada a cruza. Embrulhado em @supports para que navegadores sem suporte vejam só a borda estática, e desligado sob prefers-reduced-motion. O resto do sistema de movimento é um IntersectionObserver inline de ~30 linhas (reveal escalonado) atrás de uma classe html.js, então uma falha de JavaScript nunca deixa conteúdo escondido.

• Stack: Python + subprocess, Claude Code CLI (claude -p --output-format json)
• Adicionado provider ROTAS_LLM_PROVIDER=claude-code ao lado do caminho baseado em API existente, para coexistência
• Causa raiz: hooks globais de Stop (usados para avaliação de sessão do portfólio) eram herdados pelo processo filho do CLI headless, acrescentando a saída de avaliação ao campo result e quebrando o parsing JSON
• Correção: --settings '{"disableAllHooks": true}' passado na chamada do subprocess
• Parser JSON tornado tolerante a prosa markdown ao redor, como medida defensiva contra deriva de prompt
• Trade-off aceito: ~95s por consulta vs 5-10s com chave de API real — custo zero supera a latência para um protótipo pessoal; UX exibe aviso de 'IA lenta'
• Critérios de aceite cumpridos: 6/6 IDs de itinerário corretos, justificativas ≤280 chars, reranqueamento contextual inverteu corretamente a ordem de prioridade e sinalizou uma baldeação noturna como eliminatória

Um par competente poderia razoavelmente ter escolhido um CMS headless ou uma API pequena. Git-como-banco-de-dados venceu em três frentes: histórico completo e rollback de graça, custo de infraestrutura zero, e um pipeline de deploy (push → rebuild) que hosts estáticos oferecem de fábrica. A branch drafts existe por confidencialidade, não relevância — trabalho de cliente nunca pode auto-publicar sem um olhar humano. Trade-off aceito: sem atualizações em tempo real, que um portfólio não precisa.