DEV Community: Alexandre Caramaschi

RAG and Query Fan-Out: How the AI Assembles the Answer That Cites You

Alexandre Caramaschi — Sun, 31 May 2026 16:54:46 +0000

When you ask ChatGPT, Gemini, or Perplexity a question and get back a tidy paragraph with two or three sources cited, it is tempting to believe the machine "found the right page." It did not. The answer was assembled from fragments of several pages, retrieved in parallel, reordered by relevance, and stitched together by the model. If your content made it into that process, you got cited. If it did not, you simply do not exist for that question, no matter how good your article is.

I treat this as the central engineering problem of GEO (Generative Engine Optimization). Optimizing for generative AI is not "writing for a robot." It is understanding two concrete mechanics, RAG and query fan-out, and shaping your content's structure to survive them. The counterintuitive thesis is simple: what decides the citation is not your whole page, it is the isolated passage inside it. Most sites optimize the page and never the passage.

What RAG actually is

RAG stands for Retrieval-Augmented Generation. The idea is direct: the language model does not answer only from what it memorized during training. Before writing, it retrieves relevant documents from the web (or from an index), injects the retrieved snippets into its own context, and only then generates the answer, grounded in those snippets. That is why the system can cite a source: the sentence it wrote is, ideally, backed by a chunk of text it just read.

This pattern is now the common denominator of search-enabled assistants. ChatGPT in search mode runs primarily on the Bing index; Google AI Mode runs on Google's own index; Perplexity behaves as an online information-retrieval system on top of an LLM where every answer ships with inline citations. Different backends, same underlying architecture: retrieve, then generate.

The detail that changes everything for content producers: the model does not retrieve your site. It retrieves chunks, separately delimited and indexed pieces of text. The unit of competition is not the URL, it is the block. If your strongest argument is spread across three paragraphs that only make sense together, no single chunk wins the retrieval ranking.

Query fan-out: one question becomes many

The second mechanism is query fan-out. Instead of searching for exactly what you typed, the system decomposes your question into several subqueries and fires them all in parallel. A question like "best ERP for fashion e-commerce in Brazil" does not become one search. It becomes a fan: "ERP for e-commerce," "ERP marketplace integration," "ERP tax/invoice management," "ERP retail comparison Brazil," "ERP user reviews," and so on.

Each subquery retrieves its own set of passages. The system then merges everything, re-ranks, and synthesizes. This multi-step behavior is what the market calls "Deep Research" in ChatGPT and "Pro Search" in Perplexity: break the question into subtasks, fetch multiple sources for each, synthesize into a report. Google's AI Mode, rolled out broadly in early 2026, turns this into an interactive space where new queries are fired internally to refine the answer.

The strategic implication is strong and almost nobody acts on it: you do not need to rank for the main question, you need to rank for the subqueries. A page that covers only the umbrella term loses to a page that clearly answers each derived intent. Subtopic coverage stopped being a long-tail SEO tactic and became a retrieval requirement. This is why I reorganize content by intents, not by keywords.

The full flow, from question to citation

It helps to see the whole path in order. The diagram below traces a query through a RAG + fan-out engine and marks the three points where your content is included or discarded.

USER QUESTION
   "best ERP for fashion e-commerce in Brazil?"
        |
        v
[1] QUERY FAN-OUT  (decomposition)
        |
        +--> subquery A: "ERP fashion e-commerce"
        +--> subquery B: "ERP marketplace integration"
        +--> subquery C: "ERP tax / e-invoice"
        +--> subquery D: "ERP retail comparison BR"
        |    (fired in PARALLEL)
        v
[2] RETRIEVAL  (per-chunk recall)
        |   index: Bing / Google / proprietary
        |   each subquery pulls N passages
        v
   POOL OF CANDIDATE PASSAGES
        |   <-- POINT 1: your chunk enters here or not
        v
[3] RE-RANKING  (reordered by relevance)
        |   relevance + authority + freshness + schema
        v
   TOP-K SELECTED PASSAGES
        |   <-- POINT 2: your chunk rises or drops
        v
[4] GENERATION  (LLM synthesis)
        |   model writes the answer grounded
        |   in the selected passages
        v
   ANSWER + CITATIONS
        |   <-- POINT 3: you become a cited source or not
        v
   USER READS THE ANSWER

Note the three decision points. At Point 1, your chunk must be retrieved by at least one subquery, which depends on textual relevance and on the content being crawlable and indexed. At Point 2, it must survive re-ranking, which weighs relevance, source authority, freshness, and structured signals. At Point 3, the model must actually use your passage in the synthesis and attribute the citation. Every optimization below targets one of these three bottlenecks, never "the site as a whole."

Self-contained passages and semantic chunking

Because the engine indexes and retrieves by piece, your number-one task is to make each piece stand on its own. I call this a self-contained passage: a block of text that answers a specific question without depending on the previous paragraph to make sense. If a passage opens with "as we saw above," it already lost, because "above" does not travel with the chunk when it is extracted.

In practice, write blocks that carry their own context. Repeat the subject instead of using a dangling pronoun. Open the section with the direct statement, then explain. Semantic chunking, from the content side, means helping the engine cut in the right places: one subtopic per section, headings that describe exactly what follows, and paragraphs that do not blend two ideas. The cleaner the semantic boundary, the better the retrieved chunk.

Rules I apply and enforce on teams:

One intent per block. Do not answer "what is it" and "how much does it cost" in the same paragraph. Those are two chunks, two subqueries, two citation chances.
Answer before explanation. The first sentence of the section delivers the conclusion. Detail comes after, for those who want depth.
Embedded context. Each passage names the entity, the number, and the relevant date instead of assuming the reader (or the extractor) already knows.
No orphan pronoun at the start. "This," "it," "that process" at the beginning of a block break self-containment.

Direct answers up top and intent coverage

Re-ranking favors passages that answer directly and densely. A 2026 GEO study based on 145 real fashion and e-commerce queries found that assistants prioritize content with tables, FAQs, direct answers, and proprietary data, because that makes extraction and synthesis easier. The same study quantifies how many brands each engine shows per answer: Perplexity typically surfaces 3 to 6 brands with sources, Google AI Overviews 3 to 5, ChatGPT or Claude 2 to 4. Few slots. Whoever does not answer directly does not compete.

Intent coverage is the complement. Because fan-out decomposes the question, content that covers the entire fan of sub-intents is retrieved by more subqueries and therefore appears at more points in the synthesis. Do not confuse this with stuffing keywords. It means covering, with real depth, the adjacent questions a user would ask in sequence: definition, comparison, price, common mistake, next step. Each becomes a different entry door.

I build this from the subquery map, not from search volume. Take the main question, list the 8 to 12 likely fan-out sub-intents, and guarantee at least one self-contained passage for each. It is laborious, and it is what separates a cited article from an invisible one.

Structured data: the layer re-ranking reads

Schema.org is not "old SEO" in this context. It is the layer that helps the engine understand what each thing is before ranking the passage. Fabrice Canel, on Microsoft's Bing team, has stated that schema markup helps Microsoft's LLMs understand content and serves as an essential data source for AI-based search features. When ChatGPT's backend is Bing, that stops being theory.

What matters for RAG and fan-out specifically:

Organization and Person with sameAs anchor your brand to a disambiguated entity, reducing the risk of the engine attributing the passage to the wrong company.
FAQPage and Article make the question-answer pair explicit, which is exactly the format fan-out looks to retrieve per subquery.
Stable @id and about/mentions references create a coherent internal graph, associated with fewer wrong citations and better eligibility for AI Overviews.

An honest caveat, because schema gets sold as a silver bullet: structured data is a disambiguation and eligibility signal, not a guaranteed citation trigger. It improves Point 1 and Point 2 of the flow and helps the engine trust the source, but it does not replace having the best passage.

Example: same information, two outcomes

To close the concept, compare two ways of writing the same thing. The first is how most people publish. The second is optimized for retrieval.

Version that is not retrieved (context locked to the previous paragraph, diluted answer):

As mentioned, it depends a lot on the size of the
operation. In their case, many factors come into
play and the ideal is always to analyze case by case
before deciding anything about tax integration.

This block answers no subquery. It names no entity, brings no number, gives no answer. Extracted alone, it is noise.

Retrievable version (self-contained, answer up top, data embedded):

A fashion e-commerce ERP in Brazil must issue NF-e
and NFC-e natively. In 2026, with the first phase of
split payment from the tax reform, automatic tax
integration stopped being optional: without it, the
merchant remits tax manually on every sale. Platforms
with a native tax module eliminate that work.

The second block names the entity (fashion e-commerce ERP), answers directly (must issue NF-e and NFC-e), carries a dated milestone (split payment in 2026), and ends with an actionable criterion. It is retrievable by the tax-management subquery, the integration subquery, and the comparison subquery. Same information, three entry doors instead of zero.

RAG-readiness checklist for engineers

I close any content audit with this checklist. It is not exhaustive, but it targets the three decision points of the flow.

Crawlable and indexable. Confirm the engine can read the rendered page, with no critical content hidden behind JavaScript the crawler does not execute. Without this, Point 1 never happens.
One subtopic per section, descriptive heading. Each heading should let you guess the passage from the title alone. This guides the semantic chunk cut.
Direct answer in the first sentence of each section. Conclusion before explanation.
Sub-intent map covered. List the 8 to 12 likely fan-out subqueries and verify a passage exists for each.
Self-contained passages. No block starts with an orphan pronoun or a reference to "above."
Entity and FAQ schema. Organization/Person with sameAs, and FAQPage wherever a question-answer pair exists.
Proprietary, dated data. At least one number, experiment, or date that does not exist identically elsewhere. Originality increases the odds the model prefers your passage in the synthesis.
Visible freshness. Explicit publish and update dates. Perplexity in particular values freshness and rewards visible updates.

This work is not glamorous and does not produce a pretty screenshot. But it is what puts your passage inside the candidate pool, at the top of the re-ranking, and finally into the sentence the user reads. The rest is consequence.

The practical next step

Google stopped treating this as an experiment. In May 2026 it published an official resource on optimizing for generative AI in Search, signaling the topic became product guidance, not community guesswork. At the same I/O 2026, the company declared Search had entered the "agentic era," with AI Mode and information agents running 24/7. Agents that assemble answers from retrieved passages. Same mechanic as this guide, now on Search's primary surface.

Start small and measurable: take your most important article, run the RAG-readiness checklist, and rewrite three sections as self-contained passages with the answer up top. Then test the subqueries in Perplexity and AI Mode and see whether your passage shows up. The rule I never give up: optimize the passage, not the page. That is where the AI decides whether to cite you.

Written by Alexandre Caramaschi, CEO of Brasil GEO, ex-CMO of Semantix (Nasdaq), co-founder of AI Brasil. This is an English adaptation of the original Portuguese article: RAG e query fan-out: como a IA monta a resposta que cita você.

Why I added a 6th LLM to my orchestrator (and why Grok with K is not Groq with Q)

Alexandre Caramaschi — Sun, 17 May 2026 17:37:17 +0000

TL;DR: I built geo-orchestrator, an open-source multi-LLM pipeline in Python that routes tasks across 6 providers. Yesterday's real production run: 10 tasks, 5 waves, \$0.1967 total cost, 5/6 providers used, zero failures.

Repo (MIT): https://github.com/alexandrebrt14-sys/geo-orchestrator

The premise

No single frontier model wins by itself anymore. Not Claude Opus 4.7. Not GPT-4o. Not Gemini 2.5 Pro. Not Grok 4.3. What wins is orchestration between them.

I didn't reach this thesis by opinion. I reached it by running 1,189 calls with unified tracking. The spreadsheet doesn't lie: concentrating 96.7% of cost in Claude Opus gave me high quality at corporate-subscription bill. Distributing across 6 providers with complexity-based routing gave me equivalent or superior quality at 1/30th the price.

Why 6 providers (and why Grok is not Groq)

Most common confusion in vendor calls this month:

Groq Inc (with Q) — LPU chip company. Serves open-source models like Llama 4 Scout and gpt-oss-120b at sub-second latency. Bills \$0.11/\$0.34 per 1M tokens. API at api.groq.com/openai/v1.

xAI Grok (with K) — Elon Musk's lab. Owns proprietary models grok-4.3 and grok-4.20 with live X/Twitter search via search_parameters (nobody else has this). Bills \$1.25/\$2.50 per 1M. API at api.x.ai/v1.

Two completely different companies. Two different roles in the stack. The catalog uses long labels to prevent runtime errors.

The architecture, in 3 layers

Layer 1 — Provider enum with 6 entries

class Provider(str, Enum):
    ANTHROPIC = "anthropic"
    OPENAI = "openai"
    GOOGLE = "google"
    PERPLEXITY = "perplexity"
    GROQ = "groq"
    XAI = "xai"  # added 2026-05-17 — grok-4.3 with live X search

Layer 2 — Tier routing by complexity

Tasks classified complexity 1–2 go economy tier (Haiku, Llama Scout, sonar). Complexity 3 goes balanced (Sonnet, GPT-4o). Complexity 4–5 wakes up premium (Opus, Pro, sonar-deep-research). Before tier routing I ran everything in Opus. Today Opus is 8% of calls and audited quality is the same.

Layer 3 — Provider concentration cap at 80%

If any vendor crosses 80% of session calls, the router rebalances to next viable provider. Inspired by Mixture of Agents (Wang 2024, arXiv:2406.04692) and DAAO (arXiv:2509.11079).

This isn't just FinOps. It's epistemic diversity: 6 models failing at different points give me more robust consensus than 1 model failing consistently.

What I learned in 14 months

Inference cost dropped 50x in 2 years. Whoever still pays \$5 per execution is paying routing inefficiency, not intelligence. The right question is not "which LLM is best" — it's "what's the optimal sequence of LLMs for this specific demand."

Provider diversity is the new redundancy. In April, Anthropic hit 102% of daily budget mid-run. The fallback chain redirected all Claude tasks to Sonnet → Groq with zero visible failure. Single-provider is single-point-of-failure.

The literature is cheaper than Stack Overflow. Three papers most influenced my last 6 months: Mixture of Agents (Wang 2024), RouteLLM (Ong 2024, arXiv:2406.18665), DAAO (2025). All open on arXiv, all with code.

Want to try?

Repo: https://github.com/alexandrebrt14-sys/geo-orchestrator (MIT, 140 tests passing, 12,500 lines).

Long-form article (PT-BR Bloomberg longform, 9 sections, 6 FAQs): https://alexandrecaramaschi.com/artigos/orquestrador-6-llms-padrao-stack-geo-2026

Coletei 8.571 queries em sete dias e descobri que ser citado por IA é uma métrica que não existe

Alexandre Caramaschi — Wed, 29 Apr 2026 13:20:18 +0000

Há sete dias eu liguei o cronômetro de uma janela de 90 dias. Pré-registrei a metodologia no OSF, travei a versão 2 do pipeline, e deixei a coleta rodar no automático em cinco LLMs (ChatGPT, Claude, Gemini, Groq e Perplexity), 69 entidades brasileiras (61 reais e 8 fictícias plantadas como controle), quatro verticais (Fintech, Varejo, Saúde e Tecnologia). Hoje, dia 7 de 90, já temos 8.571 queries empíricas e 1.785 citações no banco. E os primeiros sinais já desmontam uma premissa que circula em quase todo deck de marketing brasileiro.

O dado mais importante deste post é uma frase. Não existe uma métrica única chamada "ser citado por IA". Existem cinco mercados completamente diferentes acontecendo ao mesmo tempo, e a maior parte das marcas está otimizando para o errado.

Cinco mercados, 75 vezes de diferença

A taxa de citação global, sobre 8.571 queries, é de 20,8% (intervalo de confiança de 95%: 20,0%–21,7%). Esse número, sozinho, é inútil. Quando se decompõe por LLM:

Perplexity: 82,5% de citação
Claude: 26,0%
ChatGPT: 17,2%
Groq: 8,2%
Gemini: 1,1%

Setenta e cinco vezes de diferença entre o melhor e o pior. Não é ruído. São 8.571 queries pareadas, com a mesma cohort, na mesma janela, com o mesmo prompt-set. O modelo com RAG ativo (Perplexity) e o modelo paramétrico puro (Gemini) são, do ponto de vista de visibilidade de marca, dois universos. Quando uma marca declara "fui citada pela IA", precisa terminar a frase: por qual.

Reportar "presença em IA" como métrica única é esconder duas ordens de grandeza atrás de uma média ponderada. Cada engine opera com pipeline diferente — recuperação ao vivo, augmentação seletiva, inferência paramétrica pura — e a barra de entrada para cada uma é radicalmente distinta.

Três achados que estão me tirando o sono

Além do gap entre engines, três sinais preliminares já mostram que a leitura ingênua do mercado está errada em pelo menos três frentes.

1. Vertical importa duas vezes mais do que eu esperava. Fintech tem 28,6% de taxa de citação. Saúde tem 14,0%. Mesma metodologia, mesma janela, mesma cohort. O recall setorial dos LLMs é profundamente desigual, e o setor de saúde está órfão.

2. Inglês cita mais do que português. Queries em inglês geram 23,0% de citações. As mesmas queries em português, sobre as mesmas marcas, geram 18,7%. Eu esperava o oposto. O sinal prático: hoje, perguntar "best Brazilian fintechs" devolve mais marcas brasileiras do que perguntar "melhores fintechs brasileiras". Provavelmente envolve o volume de corpus de treinamento em inglês citando marcas brasileiras, mais do que a presença em conteúdo nativo em português.

3. Quase ninguém fala mal. De 3.841 contextos com sentimento classificado, 0,2% são negativos. Os LLMs raramente criticam quem citam. Qualquer dashboard tipo "share of voice em IA" mede presença, não reputação. Reputação exige outro experimento.

E ainda: 97% das menções identificadas usam o nome próprio da marca (167 em 172 contextos auditados). Os modelos preferem citar pelo nome a inserir um link. A unidade competitiva no GEO é a entidade nomeada, não a URL.

Por que confio nesses números aos sete dias

Resultado parcial do dia 7 que talvez seja o mais importante: especificidade de 100,0%. As oito entidades fictícias plantadas na cohort — nomes plausíveis em português que correspondem a empresas que não existem — receberam zero falsos positivos em 8.571 queries. A instrumentação está calibrada.

Para chegar aqui, eu tive que jogar fora a versão 1 desse pipeline. Em fevereiro publiquei um paper chamado Null-Triad: Three Ways to Fail to Conclude no Zenodo (DOI 10.5281/zenodo.19712217) admitindo que a primeira metodologia tinha três falhas estruturais simultâneas: poder estatístico insuficiente em H1, design que não testava o que media em H2, e um casamento de string que inflava H3. A migração para a v2 derrubou 45% das "citações" que estávamos contando, porque eram falsos positivos do tipo "Inter" sendo capturado dentro de "international", ou "Stone" dentro de "cornerstone".

Foi humilhante e foi necessário. Publicar o Null-Triad antes de iniciar a v2 foi a forma mais honesta que encontrei de declarar publicamente: o que eu disse antes estava errado, e aqui está exatamente como.

O que muda no pipeline v2

A versão 2 está formalizada em METHODOLOGY_V2.md e aberta sob licença MIT em github.com/alexandrebrt14-sys/papers:

NER com word-boundary rigoroso e normalização Unicode dupla (NFC + NFKD).
Dicionário canônico de aliases (BTG ↔ BTG Pactual, XP ↔ XP Investimentos, C6 ↔ C6 Bank, Magalu ↔ Magazine Luiza).
Oito decoys fictícios plantados como canários de especificidade.
Estimador sanduíche cluster-robust (CR1) respeitando a estrutura de cluster diário.
Simulação Monte Carlo substituindo thresholds arbitrários por percentis empíricos.
Correção BH-FDR para múltiplas comparações.
Regra de decisão pré-registrada: rejeito H₀ apenas se o p-valor ajustado for menor que 0,05 e o intervalo de 95% excluir o valor nulo.
Reprodutibilidade container-level: Dockerfile com PYTHONHASHSEED pinado, requirements-lock.txt imutável, manifest SHA-256 dos outputs.

A janela vai até 21 de julho de 2026. No dia 25 o estudo atinge poder estatístico para H1, no dia 38 para H2. Só vou bater no peito sobre conclusões definitivas em outubro, quando o paper for submetido à Information Sciences (Elsevier, fator de impacto 8,1). Até lá, prometo o que prometi no OSF: vou publicar também os resultados nulos, se aparecerem.

O que já dá para usar na prática (com cautela)

Pare de tratar "presença em IA" como métrica única. Reporte por modelo. Idealmente por modelo e por idioma.
Se você é fintech ou varejo, o jogo está aberto. Barra de entrada estruturalmente menor — Fintech 28,6%, Varejo 25,5%.
Se você é saúde, o trabalho é estrutural. Com 14,0% de taxa, ganhar visibilidade exige construção de autoridade externa em ciclo longo.
Se você está investindo em conteúdo só em português, está deixando dinheiro na mesa. Conteúdo bilíngue, com base inglesa sólida, é hoje uma alavanca subestimada.
Não confie em dashboards que prometem "share of voice em IA" sem mostrar intervalo de confiança, tamanho de amostra e metodologia de extração. A v1 deste mesmo estudo cometeu o erro de contar "international" como "Inter" durante meses.

Sete dias. Mais oitenta e três pela frente

Dataset e dashboard atualizados em tempo real:

alexandrecaramaschi.com/research — números do dia, intervalos de confiança, distribuição por vertical, LLM e idioma.
alexandrecaramaschi.com/papers-roadmap — fases, hipóteses, venues alvo, ondas entregues.
github.com/alexandrebrt14-sys/papers — código completo, pipeline, testes, migrations, Dockerfile.

A próxima vez que alguém te disser que "a IA está citando" a sua marca, a resposta correta tem quatro componentes: qual IA, em que idioma, em que vertical e com que intervalo de confiança. Se faltar qualquer um dos quatro, o que está sendo medido não é visibilidade — é folclore.

Alexandre Caramaschi — CEO da Brasil GEO, ex-CMO da Semantix (Nasdaq), cofundador da AI Brasil.

YouTube as a GEO Engine: 10 Field Rules for Getting Cited by ChatGPT, Gemini and Perplexity

Alexandre Caramaschi — Fri, 24 Apr 2026 16:11:20 +0000

Last quarter I helped scale a B2B channel to 1,200+ subs, 179K total views, and two videos past 30K views each. Great numbers. Wrong lens.

In the same period, that channel generated zero attributed leads in the CRM. Zero. The paid campaigns bought 11,765 views at R$0.13 average CPV. Every single one landed on the YouTube channel page — not the website. Subs went up. Pipeline stayed flat.

The problem wasn't the channel. It was the strategy. YouTube in 2026 is not a conversion funnel — it is structured authority storage for generative engines. Treat it as the first and you waste money. Treat it as the second and you buy something your competitor cannot: citation inside ChatGPT, Gemini, Perplexity and Claude answers.

Ten field rules follow. None are theoretical. All came from auditing a real channel (@acaramaschi) that averages a GEO score of 75/100 with 12 videos below threshold — meaning, lots of room to grow, probably like yours.

Read full 10 rules + Portuguese version: https://alexandrecaramaschi.com/artigos/youtube-para-geo-o-canal-como-prova-de-autoridade-algoritmica

10 rules in bullets (short version for dev.to)

Metadata GEO-first before thumbnail — Title ≤ 60 chars with keyword in first 35; description ≥ 300 chars + CTA; 5+ tags; chapters for 2min+; 3 hashtags. 82% of audited videos had zero tags.
Shorts open, long-form converts authority — Shorts = 30-60s hook trailer. Long-form 7-20min = pillar. One long-form yields 10x the indexable transcript of 10 Shorts.
Treat transcript as a blog post — Download auto-transcript, rewrite, upload as manual caption, republish as site article with Schema VideoObject + Article. One video → three indexable sources.
Wikidata + Schema VideoObject on the site — Create Wikidata item, add P2397 (YouTube channel ID). Site articles embed with full VideoObject markup. Attribution triad: channel ↔ Wikidata ↔ site.
Demand Gen with site destination, not just subscribe — Run two parallel campaigns: Subs (final_url=channel) and Leads (final_url=site). Same asset, different CTA, different conversion goals. 70/30 budget split.
Canonical UTM and ≤ 20% dark attribution — utm_source=youtube&utm_medium=demandgen&utm_campaign={snake}. Persist first-touch cookie 90d. Measure CPL per video, not per channel.
Weekly cadence beats daily volume — 3-7 day upload interval. Retention ≥ 50%. If 21 days without posting, pause ads (CTR drops 40-60%).
Pick 3 pillar topics, rotate format — 60% / 25% / 15% split. LLMs associate channels with topics. Topical authority comes from density, not variety.
Crosslink channel ↔ site ↔ platforms — Every video: 3 outbound + 3 inbound links. Description → site article. dev.to, LinkedIn, Medium, Hashnode repost. 3-5 crosslinks = average delta between cited vs uncited.
Measure GEO score, not views — 0-100 formula based on title + desc + tags + chapters + hashtags + manual transcript + site link + retention. Target ≥ 85 for every 2026 video.

Full 2000-word article with detailed examples, formulas and 5 FAQs:
→ alexandrecaramaschi.com/artigos/youtube-para-geo-o-canal-como-prova-de-autoridade-algoritmica

Other articles in the Generative Engine Optimization series:

Alexandre Caramaschi is CEO of Brasil GEO, former CMO of Semantix (Nasdaq: STIX), co-founder of AI Brasil. Pioneer in Generative Engine Optimization and Business-to-Agent (B2A) in Brazil. Watch the channel: @acaramaschi.

Por que o Brasil deveria estar pesquisando GEO antes do resto do mundo — e o que encontrei em 1.004 consultas a LLMs

Alexandre Caramaschi — Thu, 16 Apr 2026 19:33:49 +0000

Por que o Brasil deveria estar pesquisando GEO antes do resto do mundo

Na semana passada, colei dois prompts idênticos no ChatGPT, Claude, Gemini e Perplexity. A única diferença: um estava em português, outro em inglês. A pergunta era a mesma — "quais os melhores bancos digitais do Brasil?". A resposta em português citou Nubank, Inter, C6 Bank nove vezes em dez. A versão em inglês citou os mesmos nomes em cinco de dez respostas, e nas outras cinco apareceram Revolut, N26, Monzo — marcas europeias que nem operam aqui.

A diferença não foi opinião. Foi +29 pontos percentuais de visibilidade — 79,4% de citação em português contra 50,4% em inglês, medido sobre um dataset empírico de 1.004 consultas estruturadas rodando há 24 dias em paralelo nos quatro principais motores generativos.

Esse número sozinho inverte a lógica que domina agências brasileiras: não faz sentido escrever conteúdo em inglês para "ampliar alcance" quando o motor que decide quem aparece na resposta já aprendeu a citar marcas brasileiras em português melhor do que em inglês. E esse é apenas um dos achados.

A tese central: quem não aparece em IA nos próximos 18 meses vai desaparecer

O Brasil tem uma janela curta para fazer Generative Engine Optimization virar disciplina antes do resto do mundo. Esta não é uma afirmação de marketing — é uma observação empírica ancorada em três assimetrias raramente discutidas em conjunto:

A primeira é linguística. Os LLMs citam marcas brasileiras em português com densidade 29pp maior que em inglês. Isso cria um domínio onde o conteúdo publicado em pt-BR tem valor específico no treinamento e no grounding retrieval desses modelos — algo que concorrentes em espanhol, alemão ou francês não desfrutam na mesma intensidade.

A segunda é institucional. Não existe hoje, no Brasil, um framework empírico público medindo continuamente como LLMs tratam marcas locais em série temporal longitudinal. Nenhuma ABRADi, ABComm, Endeavor ou universidade pública publicou um dataset aberto comparável a CC-GSEO-Bench (China) ou SAGEO Arena (EUA) para o mercado brasileiro. Quem medir primeiro define a metodologia.

A terceira é comercial. O agentic commerce — agentes de IA fazendo compras em nome de humanos — vai chegar no varejo brasileiro nos próximos 18 meses. Quem aparecer nas recomendações desses agentes vende. Quem não aparecer, não existe.

Eu sou Alexandre Caramaschi, CEO da Brasil GEO, ex-CMO da Semantix (Nasdaq), cofundador da AI Brasil. Há seis meses larguei consultorias pontuais para construir a primeira infraestrutura científica de GEO no Brasil. O que segue é o relato técnico do que estamos medindo, por que estamos medindo, e o que os primeiros resultados sugerem.

A arquitetura da pesquisa: quatro verticais, cinco LLMs, 69 entidades

O protocolo tem quatro componentes metodológicos. Cada um responde a uma objeção que um revisor rigoroso levantaria.

Quatro verticais independentes. Fintech, saúde, tecnologia e varejo. Cada vertical tem sua coorte de entidades monitoradas: 21 em fintech, 16 em saúde, 16 em tecnologia, 16 em varejo. A escolha de verticais diferentes testa se os achados são generalizáveis ou específicos de um setor (Proposal 8 do design doc de concorrentes internacionais incluídos para cross-market comparison).

Cinco LLMs consultados em paralelo. ChatGPT 4o-mini, Claude Haiku 4.5, Gemini 2.5 Pro, Perplexity Sonar e, desde hoje, Groq Llama 3.3 70B. A diversidade é intencional: três modelos comerciais fechados e dois open-weight. Isso isola o efeito "modelo da OpenAI" do efeito "LLM em geral" quando uma marca aparece em todos.

Oito entidades fictícias para calibração. Aqui mora a contribuição metodológica que considero mais forte. Inserimos oito marcas inventadas — Banco Floresta Digital, FinPay Solutions, MegaStore Brasil, ShopNova Digital, HealthTech Brasil, Clínica Horizonte Digital, TechNova Solutions, DataBridge Brasil — distribuídas uma por vertical. Se qualquer LLM citar uma dessas, sabemos que está alucinando. Zero tolerância.

1.004 consultas empíricas em 24 dias. Cada query é estruturada, tem categoria (descoberta, comparativo, confiança, produto, B2B, investimento, alternativas), idioma (PT ou EN) e é executada contra todos os LLMs simultaneamente. O banco SQLite (papers.db) fica versionado no git, público, auditável. Qualquer pesquisador pode baixar o dataset e reproduzir nossos números em trinta minutos.

O achado publicável: specificity = 100%

Se eu pudesse escolher um único resultado para entrar no abstract do paper que estamos escrevendo para submissão em julho de 2026, seria este:

Zero menções às oito entidades fictícias em 1.004 respostas. False positive rate = 0,00%. Specificity = 100%.

Isso significa duas coisas. Primeiro, que o denominador da nossa pesquisa é confiável — quando contamos citações, estamos contando citações reais, não alucinações do modelo. Segundo, que os LLMs que testamos não inventam marcas brasileiras sob prompts de descoberta, comparação e confiança. Esse é um achado não-trivial. Existem setores e idiomas onde LLMs alucinam empresas em volume — nossa calibração mostra que, em português sobre marcas brasileiras reais, a alucinação é residual.

Essa validação sustenta todos os outros números que vou citar.

Os números que estão vivos agora em alexandrecaramaschi.com/research

A página de research é dinâmica: puxa o snapshot consolidado do repositório de coleta a cada hora. Conforme o dataset cresce, os números atualizam. No momento em que escrevo, este é o estado:

Taxa global de citação: 62,4% (IC 95% de Wilson: 59,3% — 65,3%). Em outras palavras, quando uma query relevante é feita a um LLM, existe uma em três chances de uma marca brasileira aparecer na resposta. Isso é alto — mais alto do que os 15-30% que benchmarks internacionais reportam para marcas em outros mercados emergentes.

Ranking de LLMs por taxa de citação:

LLM	Taxa	IC 95%	n
Claude Haiku 4.5	67,8%	62,2% — 72,9%	298
Perplexity Sonar	65,3%	58,6% — 71,4%	213
ChatGPT 4o-mini	63,0%	57,5% — 68,2%	316
Gemini 2.5 Pro	48,6%	41,3% — 56,0%	177

Claude lidera. Gemini fica atrás por uma combinação de dois fatores: respostas mais curtas (média de 300 tokens contra 800 dos outros) e latência 13 vezes maior que Claude, o que sugere que o modelo está pensando mais antes de responder — paradoxalmente, citando menos.

Taxa por vertical:

Vertical	Taxa	n
Fintech	68,5%	336
Tecnologia	65,5%	252
Varejo	63,4%	191
Saúde	48,9%	225

Fintech brasileira é o setor mais citado. Saúde é o menos. A diferença sugere que marcas com histórico digital forte — fintechs que nasceram online — têm presença desproporcional no corpus de treinamento. Marcas de saúde, mesmo as grandes como Dasa, Fleury e Rede D'Or, competem com terminologia técnica genérica ("hospital em São Paulo") que dissolve o sinal de marca.

Taxa por categoria de prompt:

Descobrimos que a categoria da pergunta importa mais do que o modelo escolhido. Perguntas de confiança (Nubank é seguro?) geram 100% de citação porque o nome já está embutido. Perguntas de descoberta (quais os melhores bancos?) geram 87% — alta densidade, mas com variância entre LLMs. Perguntas abertas de reputação (quais as marcas mais inovadoras do Brasil?) caem para 61%.

A implicação prática é direta: prompt engineering de marca é responsável por mais variância do que a escolha de LLM. Uma marca que aparece em 80% das queries de descoberta em português mas em 30% das queries em inglês tem um problema de presença de idioma, não de SEO tradicional.

O mecanismo técnico: por que português funciona

A diferença de 29 pontos percentuais entre português e inglês merece explicação técnica, porque pode soar mágica.

Três hipóteses sustentam o achado. A primeira é densidade de corpus. LLMs treinados em grandes volumes de texto em português brasileiro — sites, notícias, redes sociais, documentação fiscal — têm embeddings densos para marcas locais. Quando o prompt está em pt-BR, o retrieval puxa exatamente esses embeddings, com alta cosine similarity para as marcas monitoradas.

A segunda é efeito de contexto. Uma query em inglês aciona um espaço latente global. "Best digital banks" tem Revolut, Monzo, N26, Chime como vizinhos fortes no embedding — a marca brasileira compete contra um pool internacional. Uma query em português aciona o espaço latente brasileiro, onde Nubank e Inter são os vizinhos fortes.

A terceira é grounding retrieval. Perplexity e as versões recentes de ChatGPT consultam a web em tempo real. Quando a query está em português, o retrieval traz sites brasileiros. Em inglês, traz Forbes, Bloomberg, The Economist — veículos que raramente escrevem sobre bancos digitais brasileiros fora do hype Nubank.

O mecanismo é compatível com o que Karpathy chamou de "LLM as a compression of the internet". A internet brasileira, em português, tem densidade de marca local. A internet em inglês, não.

O que decidimos medir a seguir

Este dataset tem 24 dias de idade. A meta é atingir 10.000 consultas em 7 dias (com a expansão aplicada hoje: 35 queries por vertical, duas coletas diárias às 6h e 18h BRT, cinco LLMs em paralelo). Daqui até 15 de julho de 2026, temos 90 dias de coleta contínua para submeter à primeira publicação acadêmica peer-reviewed sobre GEO no mercado brasileiro.

As próximas perguntas já estão na fila:

Sensibilidade ao prompt (Proposal 6). Vamos rodar 30 paráfrases da mesma query. Uma marca que aparece em 80% das variações é forte. Uma que aparece em 20% depende de formulações específicas — fragilidade que um agente de IA autônomo vai expor quando parafrasear a pergunta do usuário.

Efeito de intervenção (Módulo 4). Quando a marca publica uma peça de conteúdo específica — por exemplo, um llms.txt estruturado, um post com schema.org ItemList — a taxa de citação muda em 7 dias? 14? 30? Medir isso com grupo de controle e teste-t de Welch pareado nos dá causalidade, não correlação.

Cross-LLM agreement. Quando Claude, ChatGPT e Perplexity concordam em citar a mesma marca para a mesma query, a probabilidade de um quarto LLM também citar é 91%. Quando apenas um LLM cita, a probabilidade de um segundo concordar é 23%. Isso cria um sinal de robustez: marcas que aparecem em múltiplos LLMs têm presença estrutural no corpus. Marcas que aparecem em apenas um podem estar num viés idiossincrático.

Temporal stability. Com 90 dias de série, conseguiremos rodar Mann-Kendall para detectar tendências e decomposição sazonal para isolar efeitos de ciclo. A hipótese que quero testar é que a taxa de citação de marcas médias oscila mais do que a de marcas grandes — sinal de que LLMs estão aprendendo e esquecendo em janelas curtas.

Por que isso importa para o Brasil antes do que para qualquer outro país

A oportunidade é específica e tem data de validade.

No Ocidente, GEO já virou departamento em agências enterprise. Na China, universidades publicaram CC-GSEO-Bench. No Brasil, apenas cases dispersos sem framework comparável. Isso cria uma janela de 18 meses — até o final de 2027 — onde quem medir com rigor científico define a literatura, os padrões e os casos canônicos.

Três movimentos aceleram essa janela:

Primeiro, o agentic commerce vai chegar no Brasil em 2027, talvez antes. Agentes de IA comprando em nome de consumidores. O OpenAI Operator, o Google Mariner, o Anthropic Claude computer use estão em beta pública. Quando esses agentes escolherem onde comprar seu Pix, seu cartão, seu plano de saúde, a resposta vai depender do ranking no modelo — não do ranking no Google. Marcas que só fizeram SEO tradicional estão cegas para o que decide a venda.

Segundo, o custo de coleta é trivial. Toda a infraestrutura que mantém essa pesquisa — cinco LLMs, quatro verticais, dois runs diários, 70 observações por célula por dia, pipeline automatizado em GitHub Actions — custa 27 dólares por mês. Isso está dentro do budget de cinco dias de tráfego pago de qualquer empresa média. O gargalo não é capital, é convicção.

Terceiro, o Brasil tem ativos únicos. Português é o quinto idioma mais falado no mundo e o terceiro mais presente em LLMs. Temos marcas que venceram na era mobile (Nubank), na era social (iFood) e agora precisam vencer na era agentic. E temos pesquisadores, engenheiros e operadores com track record em AI — da AI Brasil à Semantix, passando por dezenas de startups.

O que falta é alguém colocando a infraestrutura no chão. Estamos colocando.

O que estou oferecendo

Ao longo dos próximos 90 dias, o dataset de pesquisa vai triplicar de tamanho. Vou publicar o preprint em ArXiv até 24 de maio. A submissão a um journal peer-reviewed — CSCW, CHI ou ACL — está agendada para 15 de julho. Todos os dados ficam abertos em alexandrecaramaschi.com/research.

Paralelamente, rodo Sprints GEO de 20 horas para marcas que querem entrar no dataset como cases tratados: medição de baseline, diagnóstico estrutural, intervenção de conteúdo, medição pós-intervenção com grupo de controle. Cinco marcas por ciclo. A próxima leva abre em maio.

Se você dirige marketing ou produto em uma marca que ainda não tem auditoria de visibilidade em IA, dois caminhos:

O primeiro é rodar o diagnóstico gratuito que mantenho em brasilgeo.ai. Ele usa a mesma metodologia do paper, aplicada a uma marca específica, em menos de 10 minutos.

O segundo é enviar email direto para agendar conversa sobre onde sua marca cai no corpus atual — quais LLMs te citam, em qual idioma, em qual categoria de query — antes que o agentic commerce torne essa conversa tarde demais.

O Brasil pode ser potência em GEO e em agentic commerce antes do resto do mundo. Não porque somos melhores que os outros mercados. Porque a janela está aberta, o idioma trabalha a nosso favor e ninguém ainda ocupou o lugar de referência científica. Quem ocupar agora vai definir o resto da década.

Alexandre Caramaschi é CEO da Brasil GEO, ex-CMO da Semantix (Nasdaq), cofundador da AI Brasil. Escreve sobre pesquisa empírica em Generative Engine Optimization em alexandrecaramaschi.com. O dataset completo desta pesquisa está em alexandrecaramaschi.com/research.

I Built a Deterministic Crosslink Engine for 117 Pages Using Jaccard Similarity

Alexandre Caramaschi — Fri, 10 Apr 2026 02:30:11 +0000

A content site with 117 pages and zero internal linking strategy is a site where visitors bounce after reading one page. That was my site two weeks ago.

Today, every page on alexandrecaramaschi.com has 6 contextual crosslinks generated by a deterministic engine that runs in 200ms, costs nothing, and lives in a single Node.js script — no embeddings, no vector databases, no API calls.

Here is exactly how I built it.

The Problem: 117 Pages, Manual Linking

The site has 41 long-form articles, 38 courses (388 modules), 26 strategic insights, and 14 service/tool pages. All built with Next.js 16 App Router.

The existing relatedArticles field in my CMS was manually curated — and covered maybe 15% of pages. Course pages had zero outbound links to articles. Articles never pointed to courses. The result: visitors arrived via search, consumed one page, and left.

The Architecture: Faceted Taxonomy + Weighted Scoring

Instead of reaching for OpenAI embeddings, I designed a controlled vocabulary with 4 semantic facets:

1. Topics — 26 canonical terms with synonym normalization:

export const TOPICS = {
  geo: ["geo", "generative engine optimization", "motor generativo"],
  seo: ["seo", "search engine optimization"],
  "ia-generativa": ["ia generativa", "llm", "chatgpt", "claude", "gemini"],
  vscode: ["vscode", "vs code", "visual studio code", "editor", "ide"],
  // ... 22 more
};

Each piece of content is annotated by scanning its title, description, and keywords against this vocabulary. Normalization strips accents and lowercases before matching (critical for Portuguese content).

2. Audience — 7 profiles (beginner, dev, marketing-pro, executive, etc.)

3. Intent — 4 journey stages: discover → learn → apply → decide

4. Vertical — 12 industry sectors (healthcare, legal, tourism, etc.)

The Scoring Function

For each pair of content items (A, B), the score is a weighted sum across facets:

score(A, B) = 1.0 * jaccard(topics_A, topics_B)
            + 0.5 * audienceOverlap(A, B)
            + 0.8 * intentFlow(A, B)
            + 1.2 * verticalBridge(A, B)
            + 1.3 * crossDomainBonus(A, B)
            + 0.6 * trackAffinity(A, B)

Jaccard similarity handles topic matching. Two items sharing 3 of 5 topics score 0.6 — high enough to be relevant, low enough to avoid duplicates.

Intent flow rewards linking from discovery content (articles) to learning content (courses) to action pages (tools) — guiding visitors deeper.

Cross-domain bonus is the key retention driver: an article about "zero-click economy" linking to the "SEO + GEO Fundamentals" course is more valuable than linking to another article about zero-click. Different content types with shared topics get a 1.3x boost.

Track affinity ensures courses in the same learning path (e.g., Python → Data Science → Deploy) link to each other even without keyword overlap.

Anti-Bubble Mixing

Raw scoring produces homogeneous results — a course page would only suggest other courses. The mixer enforces quotas:

content (articles + insights): min 1
learning (courses):             min 1
action (guides + tools):        min 1
any single group:               max 50%

Three phases:

Fill mandatory quotas from each group
Complete by score, respecting group caps
Fallback by supercategory for edge cases

Injection Without Editing 63 Static Pages

The site has 38 static course pages and 26 static insight pages — all individual page.tsx files. Editing each one was not viable.

Solution: middleware + headers + layout injection.

The middleware sets an x-pathname header:

// middleware.ts
const requestHeaders = new Headers(request.headers);
requestHeaders.set('x-pathname', pathname);
const response = NextResponse.next({ request: { headers: requestHeaders } });

A server component reads it:

// SmartRelated.tsx
const h = await headers();
const path = h.get("x-pathname");
const items = getCrosslinksFor(path, 6);

Injected via educacao/layout.tsx and insights/layout.tsx, it automatically appears below every course and insight page. For articles (dynamic [slug] route), the pathname is passed explicitly as a prop.

Results

Metric	Before	After
Pages with crosslinks	~15%	100%
Total crosslinks	~40 manual	700 generated
Cross-type links	0	116 of 117 pages
Badge types per page	1	2.3 average
Build time delta	—	+200ms
API costs	—	$0

The generator runs as part of prebuild and outputs a static JSON map consumed at render time.

Why Not Embeddings?

At 117 pages, embeddings are overkill. The controlled vocabulary approach is:

Deterministic — same input, same output, every time
Auditable — grep the vocabulary file to understand any link
Free — no API calls, no vector DB
Fast — 200ms to generate the entire map
Versionable — the JSON map is committed to git

When the site crosses ~500 pages, I will migrate to pgvector. The architecture was designed for this: consumers only read crosslink-map.json — they do not care how it was generated.

Try It

The full source is at alexandrecaramaschi.com. Navigate any course, scroll to the bottom, and you will see the crosslinks in action.

Alexandre Caramaschi — CEO at Brasil GEO, former CMO at Semantix (Nasdaq), co-founder of AI Brasil. Building the practice of Generative Engine Optimization in Latin America.

12 dias de 'success' coletando zero dados — o bug silencioso que matou minha pesquisa de 90 dias

Alexandre Caramaschi — Wed, 08 Apr 2026 00:24:00 +0000

8 dias. 0 observações. 12 workflows GitHub Actions marcados como verde. Foi isso que descobri há seis horas, em 7 de abril de 2026, ao olhar meu dashboard de pesquisa em alexandrecaramaschi.com/research e ver overall_rate: 0, total_observations: 0, days_collecting: 0 em todas as quatro verticais.

O GitHub Actions me dizia que tinha rodado com sucesso desde 30 de março. Os commits estavam lá, datados, com mensagens automáticas perfeitas: data: daily collection 4 verticals 2026-04-07.

Eu tinha um workflow chamando python -m src.cli collect citation para 4 verticais (fintech, varejo, saúde, tecnologia), 4 LLMs (ChatGPT, Claude, Gemini, Perplexity), todo dia às 06:00 BRT.

A pasta output/ tinha checkpoints atualizados. O dashboard estava no ar. E não havia uma única linha de dado real desde 30 de março.

A tese contraintuitiva

Workflows verdes em CI mentem. Especialmente quando o seu código tem continue-on-error: true espalhado por todo lado e o seu único critério de sucesso é "o processo não exceptioned".

O caso que eu vou contar é uma combinação de três falhas que se reforçam: API keys rotacionadas externamente sem propagação ao repositório, retorno HTTP 401 silencioso porque o coletor capturava a exceção e seguia, e um workflow YAML que considerava "completou sem crash" como "rodou bem". O resultado é o pior tipo de bug de pipeline: o que mantém todos os indicadores verdes enquanto a base de dados envelhece.

O contexto: pesquisa empírica de 90 dias

Estou rodando um estudo longitudinal sobre como LLMs citam empresas brasileiras. O design tem 4 verticais, 69 entidades (61 reais + 8 fictícias para calibração de falso positivo), 4 modelos com versão pinada (gpt-4o-mini-2024-07-18, claude-haiku-4-5-20251001, sonar, gemini-2.5-pro) e ~288 observações por dia. O alvo eram 90 dias contínuos, ~25.920 observações, três papers planejados para ArXiv + SIGIR/WWW + Information Sciences Q1.

A coleta começou em 24 de março. Tudo funcionou no dia 1. Em 25 e 26, um SyntaxError em Python 3.11 do CI (válido em 3.12 do meu local) matou a coleta — incidente já documentado, fixado, post-mortem escrito.

Em 29 de março, tudo funcionando de novo: 256 observações reais, distribuição saudável entre os 4 LLMs.

Em 30 de março, alguma coisa quebrou.

A causa raiz

Em algum momento entre 29 e 30 de março, eu rotacionei as 5 chaves de API do meu workspace local — provavelmente durante uma auditoria FinOps que estava fazendo no orquestrador multi-LLM. Atualizei o .env do repositório principal. Fiz smoke test, validei que tudo respondia HTTP 200. Segui em frente.

O que eu não fiz: propagar as chaves novas para os GitHub Secrets do repositório papers. As keys lá ficaram datadas de 24 de março, ainda apontando para o conjunto antigo, agora inválido.

A partir de 30 de março, todo dia às 06:00 BRT, o workflow rodava. Cada chamada a OpenAI retornava HTTP 401 invalid_api_key. Cada chamada a Anthropic retornava HTTP 401 invalid x-api-key. Cada chamada a Perplexity, mesma coisa. O Gemini retornava HTTP 400 por outro motivo (estrutura de resposta do 2.5 Pro com thinking mode incompatível com o parser que eu tinha — outro bug que vou cobrir abaixo).

E o coletor continuava. Porque a função collect() capturava as exceções, logava no stderr, e retornava uma lista vazia. A função do CLI verificava if results: antes de inserir no banco — lista vazia significava simplesmente "nada para inserir, ok, próxima vertical". Sem exit code não-zero. Sem raise. Sem alerta.

O job finalize baixava o artifact papers-db-latest do dia anterior, rodava o sync_to_supabase.py que agregava (zero linhas → todos os KPIs zerados), atualizava o snapshot da tabela papers_dashboard_data no Supabase com total_observations: 0, overall_rate: 0, days_collecting: 0, fazia upload do mesmo artifact inalterado, commitava data/daily_*.csv (vazio), data/finops_checkpoint.json e docs/. E saía com exit code 0.

12 dias assim. Workflow status: completed/success. Banco real: 186 observações estagnadas em 24 de março. Dashboard live: zeros em todas as verticais.

Como descobri

Não foi um alerta. Era para ser. Não havia.

Foi uma pergunta. "A coleta está funcionando consistentemente para termos massa crítica em 90 dias?"

Cinco minutos depois, baixando os logs do último run via gh run view --log e filtrando por ERROR:

ERROR: [ChatGPT] HTTP 401: invalid_api_key
ERROR: [Claude] HTTP 401: invalid x-api-key
ERROR: [Gemini] HTTP 400: ...
ERROR: [Perplexity] HTTP 401: Invalid API key provided

Repetido em loop por todas as 18 queries de cada uma das 4 verticais. Mais de 200 linhas de erro. E o workflow no topo da página dizia success em verde.

A decisão de regredir

Eu tinha uma escolha: fazer backfill manual com data alterada para preservar a sequência (mas com timestamps todos do dia atual, contaminando análises temporais), ou aceitar que perdi 8 dias e reiniciar o contador.

Reiniciei. A integridade temporal de um estudo longitudinal vale mais que a vaidade de um número de "dias contínuos". 90 dias com timestamps reais é evidência. 90 dias com 8 deles inventados é fraude metodológica.

O dia 1 da nova janela é 8 de abril. Dia 90 será 6 de julho de 2026. ~256 observações por dia × 90 dias ≈ 23.000 observações totais com integridade temporal preservada.

Os 5 fixes que vão garantir que isso nunca mais aconteça

1. Fail-loud no comando de coleta

src/cli.py::collect_citation agora soma o total de citações coletadas em todas as verticais. Se for zero quando pelo menos uma vertical foi tentada, o comando levanta SystemExit(1):

if total_attempted > 0 and total_collected == 0:
    console.print(
        f"FAIL-LOUD: 0 citacoes em {total_attempted} verticais. "
        f"Provavel causa: API keys invalidas/expiradas, rate limiting, "
        f"ou erro de configuracao."
    )
    raise SystemExit(1)

Isso garante que o workflow falha de verdade quando 100% das chamadas dão erro. Sem || true por cima. Sem continue-on-error. O job termina vermelho.

2. Retry policy granular no coletor

src/collectors/base.py antes só tratava HTTP 429. Agora trata cinco categorias diferentes:

Erro	Comportamento
`HTTP 401/403`	Circuit break imediato. Não retenta. Loga "rotacionar key no GitHub Secrets".
`HTTP 429`	Retry com backoff exponencial. Após max retries, circuit break.
`HTTP 5xx`	Retry com backoff exponencial.
`ConnectError`, `ReadTimeout`, `WriteTimeout`	Retry com backoff.
`HTTP 4xx fatais` (400, 404, 422)	Log e segue para a próxima query.

A separação importa: 401 não é transient, é configuração. Retry não resolve. O fix é rotacionar a chave. Logar isso explicitamente faz a falha aparecer no diagnóstico em vez de ficar enterrada em retries inúteis.

3. Health check de 14 dimensões com alerta WhatsApp + email

Criei scripts/health_check.py no estilo do geo-finops/health_check.py que já existe no meu ecossistema. O script roda 14 checks ponta a ponta:

papers.db existe
Schema com 21 tabelas obrigatórias
As 4 API keys estão carregadas no ambiente
Smoke test real das 4 keys (faz uma chamada mínima a cada provider)
Pelo menos 200 observações nas últimas 24h
Todas as 4 verticais coletaram nas últimas 24h
Todos os 4 LLMs responderam nas últimas 24h
Sem gap maior que 1 dia entre coletas (warning)
papers_dashboard_data no Supabase com total_observations > 0
FinOps gasto < 90% do budget mensal
Endpoint /research retornando HTTP 200
Modelos pinados no banco (versões específicas)
raw_text preservado para reprocessamento
Entidades fictícias presentes no coorte (calibração de falso positivo)

Exit code 1 se qualquer check crítico falha. Quando falha, send_alert() dispara dois canais em paralelo: WhatsApp Business API para +5562998141505 e email via Resend para caramaschiai@caramaschiai.io. O conteúdo da mensagem inclui o sumário das falhas, métricas relevantes e um runbook básico de recovery.

Smoke test rodado: whatsapp: OK. Mensagem real chegou no celular.

4. Health check como gating no daily-collect

O daily-collect.yml ganhou um step novo no fim do job finalize:

- name: Health check (gating)
  run: python scripts/health_check.py --min-obs-per-day 200

Sem continue-on-error. Se o health check falha, o workflow falha. Se o workflow falha, o daily-collect-alert.yml (workflow separado que escuta workflow_run.failure) dispara WhatsApp + email.

Mais um workflow agendado (health-check-daily.yml) roda 4 horas depois — 13:00 UTC, camada redundante caso o daily-collect tenha falhado em algum aspecto que o gating não pegou. Defesa em profundidade.

5. FinOps tighter

Os budgets default eram folgados demais ($35/mês global) para o custo real observado (~$1/mês). Se algum bug fizesse queries explodirem por horas antes de eu notar, o estrago poderia ser de duas ordens de grandeza acima do que faria sentido pagar.

Apertei tudo com 5x de margem sobre o custo médio observado:

Provider	Antes	Depois	Hard stop
openai	$10/mês	$3/mês	95%
anthropic	$10/mês	$3/mês	95%
google	$5/mês	$2/mês	100%
perplexity	$10/mês	$3/mês	95%
groq	$5/mês	$1/mês	100%
global	$35/mês	$10/mês	95%

Hard stop em 95% por provider significa que quando o gasto chega lá, o tracker bloqueia novas chamadas para aquele provider até o reset diário/mensal. Bill shock previne-se com cap, não com confiança.

Os bugs que descobri por acidente no caminho

Gemini 2.5 Pro thinking mode

Enquanto debugava a coleta, descobri que mesmo com keys novas o Gemini estava retornando dados vazios. O modelo gemini-2.5-pro usa thinking tokens internos antes de gerar output. Com max_output_tokens = 300, o thinking budget esgotava os tokens e a resposta voltava com candidates[0].content sem campo parts. O parser fazia data["candidates"][0]["content"]["parts"][0]["text"] e dava KeyError: 'parts'. Mas o KeyError virava um log warning e a função retornava None — outro erro silencioso.

Fix: 4x o max_output_tokens para modelos *-pro (compensa o thinking budget) + tratamento gracioso de respostas sem parts (trata como string vazia em vez de exceção).

Idempotência exige normalização determinística do schema chave

Esse vem de um bug irmão no meu pacote geo-finops (tracking unificado de LLMs do meu ecossistema). Quando dois callers gravavam a mesma call lógica em formatos diferentes — Python local com microsegundos, Next.js server com milissegundos — eles passavam pelo dedup como "linhas diferentes". A constraint UNIQUE bate na string literal do timestamp, não no instante semântico.

Fix: _normalize_timestamp() que faz datetime.fromisoformat(...).astimezone(timezone.utc).isoformat() antes de qualquer INSERT. Se você expõe um schema chave que inclui timestamp, normalize obrigatoriamente. A documentação do PostgreSQL não vai te lembrar disso.

O que eu aprendi (e estou levando para todos os outros pipelines)

Workflows verdes mentem. Reescrevendo: workflows verdes não significam pipelines saudáveis. Eles significam que o processo terminou. A diferença entre os dois custou-me 8 dias de coleta e quase comprometeu um estudo de 90 dias.

continue-on-error: true é dívida técnica disfarçada de resiliência. Use com extrema parcimônia, e nunca em steps que produzem dados. Steps de cleanup, sim. Steps de coleta, jamais.

Smoke test de keys ≠ check de "key existe no env". Verificar que OPENAI_API_KEY está setada não diz nada sobre se ela é válida. O check 4 do meu health check faz uma chamada mínima a cada provider — custo total ~$0.0001, valor inestimável.

Defesa em profundidade > checagem única. Health check no daily-collect (camada 1) + workflow separado 4h depois (camada 2) + alerta WhatsApp em qualquer falha (camada 3) + retry granular no coletor (camada 4) + budget tight com hard stop (camada 5). Se uma camada falha, a próxima pega.

Double check exige dados reais, não mocks. O bug do 409 Conflict no geo-finops (e o do timestamp não-normalizado) só apareceram quando rodei testes reais de fim a fim. Mocks teriam passado todos os checks. O caminho certo é: executar caller real, validar cada estágio do pipeline, re-executar para validar idempotência, cleanup pós-teste, adicionar regressão automatizada.

Backfill com timestamp alterado é fraude. Se você está construindo evidência longitudinal, prefira o reset honesto à sequência inflada. Nove dias perdidos doem. Nove dias inventados invalidam o paper inteiro.

Onde isso vai

A nova janela começa amanhã, 8 de abril. Daqui a 90 dias eu deveria ter ~23.000 observações reais, com integridade temporal, todas com raw_text preservado para reprocessamento, modelos pinados para reprodutibilidade, e calibração de falso positivo embutida via 8 entidades fictícias.

O dashboard ao vivo está em https://alexandrecaramaschi.com/research. O código (incluindo todos os fixes desta noite) está em https://github.com/alexandrebrt14-sys/papers. O health check é executável e auditável em scripts/health_check.py — qualquer pessoa que queira replicar a metodologia consegue rodar os 14 checks no próprio fork.

Se você está construindo um pipeline de coleta longitudinal e ainda não tem fail-loud em nenhum step, faça isso hoje. Não amanhã. A diferença entre descobrir o bug em uma hora e descobrir em 12 dias é a diferença entre um post como este e um paper morto.

Estou contando para chegar a 6 de julho com massa crítica. Aceito relatos de bugs parecidos — o meu post-mortem é seu também.

Alexandre Caramaschi — CEO da Brasil GEO, ex-CMO da Semantix (Nasdaq), cofundador da AI Brasil. Escreve sobre Generative Engine Optimization, pesquisa empírica em LLMs e infraestrutura de pipelines em https://alexandrecaramaschi.com.

847 commits em 3 semanas: como vibe coding transformou um executivo de marketing em builder

Alexandre Caramaschi — Sat, 04 Apr 2026 20:11:25 +0000

Ha 3 semanas eu nao tinha uma unica linha de codigo publicada. Zero.

Eu era um executivo de marketing com 20 anos de mercado — ex-CMO da Semantix na Nasdaq, cofundador da AI Brasil — mas nunca tinha escrito codigo de producao.

Hoje tenho:

13 repositorios no GitHub com 847 commits
2 sites em producao com uptime 100%
40 cursos educacionais gratuitos publicados
Pipeline que orquestra 5 IAs simultaneamente
29.400 linhas de Python num sistema de governanca pessoal
653 citacoes academicas monitoradas
Auditoria OWASP com 34 findings e 11 correcoes

Custo mensal: zero dolares.

O que e vibe coding na pratica

Nao e pedir para uma IA fazer um site. E uma conversa tecnica continua. Voce traz visao de negocio e decisoes estrategicas. A IA traz execucao em velocidade impossivel para times tradicionais.

Meu fluxo:

Definir o que precisa existir e por que
Claude Code escreve, testa e faz deploy
Validar, ajustar, corrigir rumo
Proximo passo

Cada iteracao levava minutos, nao dias.

Os numeros

Site pessoal (alexandrecaramaschi.com):

429 commits, 124 paginas, 27 rotas de API
Gamificacao completa (XP, streaks, badges, certificados)
Busca semantica com pgvector
29 tipos de Schema.org JSON-LD

Governanca pessoal (29.400 linhas Python):

WhatsApp responde 85% sem IA (deterministico, custo zero)
Parser Itau PDF classifica 711 transacoes em 30 categorias
6 calendarios sincronizados com detector de gaps
Briefing matinal automatico as 7h

Pipeline academico:

7.010 linhas, coleta diaria em 4 verticais
653 citacoes sobre LLMs e empresas brasileiras

5 licoes

Comece com problema real, nao com tecnologia
Documente tudo desde o dia 1
Seguranca nao e opcional
O custo de errar caiu drasticamente
O mercado nao vai esperar voce ficar pronto

847 commits. 3 semanas. Sem equipe. Custo zero. E estamos so no comeco.

Alexandre Caramaschi — CEO da Brasil GEO, ex-CMO da Semantix (Nasdaq), cofundador da AI Brasil

De 60 Issues para 14: Como Refatorei 194K Linhas com 5 IAs via Vibecoding

Alexandre Caramaschi — Sat, 04 Apr 2026 19:00:08 +0000

Uma sessao de trabalho. 70 commits. 10 repositorios. 194 mil linhas de codigo auditadas. 5 modelos de linguagem orquestrados. Custo total: US$60.

Esse e o relato tecnico de como usei Vibecoding para transformar um ecossistema de automacoes pessoais em uma plataforma de governanca digital pronta para escalar com Google Ads.

O Ponto de Partida

Meu projeto comecou com 21 mil linhas de Python, 6 sub-calendarios sincronizados, um webhook WhatsApp Business e um banco SQLite com 1.831 registros. O sistema dizia NAO TENHO ACESSO quando os dados estavam a um SELECT de distancia.

Tirar a IA do Caminho

Para dados deterministicos, a IA generativa e o problema. Implementei pipeline de tres camadas: keywords sem LLM em menos de 100ms, classificacao LLM como fallback, geracao LLM como ultimo recurso. 85 porcento das queries nunca tocam num LLM.

70 Commits em 10 Repos

Issues GitHub: de 60 para 14. Testes: de 7 para 13. Resposta WhatsApp: de 3-8s para menos de 100ms. Tabelas documentadas: de 0 para 64.

5 LLMs Orquestrados

Perplexity pesquisa. GPT-4o redige. Gemini analisa. Groq classifica. Claude arquiteta. 10 execucoes, 5 RFCs, US$60 total.

7 Licoes

Para dados deterministicos, tire o LLM do caminho
Nunca confie no prompt para proibir comportamentos
Deploy nao e commit
Documente os dados antes de escalar
Orquestre LLMs em vez de depender de um so
Prepare tracking antes dos anuncios
Use Vibecoding para acelerar, nao para substituir pensamento

Alexandre Caramaschi - CEO da Brasil GEO, ex-CMO da Semantix (Nasdaq), cofundador da AI Brasil.

Como Implementei 30 Tipos de Schema JSON-LD e llms.txt Para Ser Citado por ChatGPT, Gemini e Claude

Alexandre Caramaschi — Tue, 31 Mar 2026 08:54:17 +0000

Como Implementei 30 Tipos de Schema JSON-LD e llms.txt Para Ser Citado por ChatGPT, Gemini e Claude

Quando decidi que meu site precisava ser entendido por IAs, não apenas por humanos, percebi que estava diante de um problema que quase ninguém estava resolvendo. A maioria dos desenvolvedores ainda otimiza exclusivamente para o Google. Mas o tráfego de respostas geradas por IA — ChatGPT, Gemini, Perplexity, Claude — já é uma realidade. E essas engines não leem seu site da mesma forma que o Googlebot.

Eu precisava de duas coisas: uma carteira de identidade estruturada que qualquer máquina pudesse interpretar (Schema JSON-LD) e um currículo legível que eu entregaria diretamente para os LLMs (llms.txt). Este artigo documenta exatamente como implementei ambos nos projetos alexandrecaramaschi.com e brasilgeo.ai, com código real e resultados verificáveis.

O Que é Schema JSON-LD (e Por Que IAs Precisam Disso)

Pense no Schema JSON-LD como a carteira de identidade da sua página na web. Quando você conhece alguém, a pessoa diz o nome, onde trabalha, o que faz. O JSON-LD faz exatamente isso, só que para máquinas.

É um bloco de dados estruturados em formato JSON que você insere no <head> da sua página. Ele não aparece visualmente para o usuário — é invisível. Mas para crawlers de busca e pipelines RAG (Retrieval-Augmented Generation) que alimentam LLMs, é ouro puro.

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "name": "Brasil GEO",
      "url": "https://brasilgeo.ai",
      "founder": {
        "@type": "Person",
        "name": "Alexandre Caramaschi",
        "jobTitle": "CEO"
      }
    },
    {
      "@type": "WebSite",
      "name": "Alexandre Caramaschi",
      "url": "https://alexandrecaramaschi.com"
    }
  ]
}

O segredo está no @graph: em vez de ter múltiplos scripts JSON-LD espalhados pela página, eu consolido tudo em um grafo único. Isso facilita a interpretação tanto por motores de busca tradicionais quanto por sistemas de IA que montam contexto para geração de respostas.

Os 30 Tipos de Schema Que Implementei

No alexandrecaramaschi.com — construído com Next.js 16 + React 19, com 41 artigos publicados — implementei 30 tipos de Schema.org organizados em um único @graph. Aqui está a lista completa com a função de cada um:

Identidade e Entidade Principal

Organization — Define a Brasil GEO como entidade com sameAs para Wikidata (Q138755989)
Person — Alexandre Caramaschi com credenciais, vínculos e Wikidata (Q138755507)
WebSite — Metadados do site, SearchAction para busca interna
ProfilePage — Página "Sobre" como perfil canônico da entidade

Conteúdo Editorial

Article — Cada um dos 41 artigos com autor, data, imagem
BlogPosting — Posts do blog com datePublished e dateModified
TechArticle — Artigos técnicos com proficiencyLevel
NewsArticle — Conteúdo com caráter noticioso
HowTo — Guias passo a passo com steps estruturados
FAQPage — Perguntas frequentes com mainEntity em array

Educação e Cursos

Course — Cursos sobre GEO com provider e hasCourseInstance
CourseInstance — Instâncias específicas com datas e modalidade
EducationalOrganization — Brasil GEO como provedora educacional
LearningResource — Recursos educacionais complementares

Mídia

VideoObject — Vídeos com thumbnailUrl, duration, uploadDate
ImageObject — Imagens estruturadas com contentUrl e caption
MediaObject — Objetos de mídia genéricos

Navegação e Estrutura

BreadcrumbList — Trilha de navegação hierárquica em cada página
SiteNavigationElement — Menu principal estruturado
ItemList — Listas ordenadas de conteúdo (ex: top artigos)
CollectionPage — Páginas de coleção (categorias, tags)

Eventos e Interação

Event — Webinars, palestras e workshops
Review — Avaliações estruturadas de serviços
ContactPoint — Canais de contato com tipo e idioma

SEO Avançado e IA

Service — Serviços oferecidos pela Brasil GEO
Offer — Ofertas vinculadas a cursos e serviços
AggregateRating — Avaliação agregada de serviços
SpeakableSpecification — Trechos otimizados para leitura por voz
ClaimReview — Verificação de afirmações (fact-checking)
DefinedTerm — Termos do glossário GEO com definição formal

O Que é llms.txt (O Currículo Para IAs)

Se o Schema JSON-LD é a carteira de identidade, o llms.txt é o currículo que você entrega diretamente para a IA. É um arquivo em texto simples, hospedado na raiz do seu domínio (/llms.txt), que resume toda a estrutura do seu site em formato que LLMs conseguem consumir eficientemente.

Enquanto o robots.txt diz ao crawler o que ele pode acessar, o llms.txt diz ao LLM o que ele deveria ler e como seu conteúdo está organizado.

No brasilgeo.ai — construído com Cloudflare Workers e 28 artigos HTML — mantenho dois arquivos:

llms.txt — 258 linhas, 23KB — mapa conciso com links e descrições
llms-full.txt — 42KB — conteúdo expandido para LLMs com janela de contexto grande

A estrutura segue um formato markdown simplificado:

# Brasil GEO

> Consultoria especializada em Generative Engine Optimization (GEO).
> Ajudamos empresas a ganhar visibilidade em ChatGPT, Gemini,
> Perplexity e outros motores de IA generativa.

## Artigos

- [O Guia Completo de GEO](https://brasilgeo.ai/artigos/guia-completo-geo): Estratégias para otimizar conteúdo para motores de IA generativa.
- [Schema JSON-LD para IA](https://brasilgeo.ai/artigos/schema-jsonld-ia): Como estruturar dados para visibilidade em LLMs.

## Cursos

- [Fundamentos de GEO](https://brasilgeo.ai/cursos/fundamentos-geo): Curso introdutório sobre Generative Engine Optimization.

## Repositórios Open-Source

- [geo-checklist](https://github.com/alexandrebrt14-sys/geo-checklist): Checklist completo de GEO com 80+ itens verificáveis.
- [llms-txt-templates](https://github.com/alexandrebrt14-sys/llms-txt-templates): Templates reutilizáveis para llms.txt.
- [entity-consistency-playbook](https://github.com/alexandrebrt14-sys/entity-consistency-playbook): Playbook para consistência de entidades em GEO.

Implementação Prática no Next.js

No alexandrecaramaschi.com, criei um componente JsonLd.tsx que renderiza o grafo completo no <head> via layout.tsx. Aqui está a versão simplificada:

// components/JsonLd.tsx
interface JsonLdProps {
  graph: Record<string, unknown>[];
}

export function JsonLd({ graph }: JsonLdProps) {
  const jsonLd = {
    "@context": "https://schema.org",
    "@graph": graph,
  };

  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
    />
  );
}

No layout.tsx, o componente recebe o grafo montado dinamicamente com base na rota:

// app/layout.tsx
import { JsonLd } from "@/components/JsonLd";
import { buildGraph } from "@/lib/schema";

export default function RootLayout({ children }) {
  const graph = buildGraph(); // monta Organization, Person, WebSite

  return (
    <html lang="pt-BR">
      <head>
        <JsonLd graph={graph} />
      </head>
      <body>{children}</body>
    </html>
  );
}

Cada página de artigo adiciona seus próprios tipos ao grafo (Article, BreadcrumbList, FAQPage), e o componente consolida tudo em um único <script type="application/ld+json">.

Implementação no Cloudflare Workers

No brasilgeo.ai, o llms.txt e o llms-full.txt são servidos diretamente pelo Cloudflare Worker. A lógica é simples:

// worker.js
async function handleRequest(request) {
  const url = new URL(request.url);

  if (url.pathname === "/llms.txt") {
    return new Response(LLMS_TXT_CONTENT, {
      headers: {
        "Content-Type": "text/plain; charset=utf-8",
        "Cache-Control": "public, max-age=86400",
      },
    });
  }

  if (url.pathname === "/llms-full.txt") {
    return new Response(LLMS_FULL_TXT_CONTENT, {
      headers: {
        "Content-Type": "text/plain; charset=utf-8",
        "Cache-Control": "public, max-age=86400",
      },
    });
  }

  // ... demais rotas
}

O cache de 24 horas (max-age=86400) garante performance sem sacrificar a atualização do conteúdo.

Resultados Verificáveis

Implementar Schema JSON-LD e llms.txt não é um exercício teórico. Aqui estão os resultados concretos:

Entity consistency score validado automaticamente pelo lint-content.js com 44+ checks por execução — verifica se nomes, credenciais e vínculos estão consistentes em todo o conteúdo
Presença no Wikidata — Person (Q138755507) e Organization (Q138755989) vinculados via sameAs no Schema, criando uma âncora de entidade que LLMs reconhecem
6 repositórios open-source no GitHub referenciados no llms.txt, criando sinais de autoridade distribuídos: geo-checklist, llms-txt-templates, entity-consistency-playbook, geo-taxonomy, geo-orchestrator e landing-page-geo
Pipeline multi-LLM com o geo-orchestrator usando 5 LLMs (Perplexity para pesquisa, GPT-4o para redação, Gemini para análise, Groq para classificação, Claude para revisão) — garantindo que o conteúdo produzido já nasce otimizado para múltiplos motores
Crosslinks estruturados entre os 41 artigos do alexandrecaramaschi.com e os 28 do brasilgeo.ai, com referências mútuas que reforçam a topical authority

Guia Passo a Passo Para Começar Hoje

Se você quer implementar Schema JSON-LD e llms.txt no seu projeto, siga estes 5 passos:

1. Defina sua entidade principal

Crie um Schema Organization ou Person com name, url, description e sameAs (LinkedIn, GitHub, Wikidata). Essa é a fundação de tudo.

2. Implemente o @graph único

Em vez de múltiplos <script type="application/ld+json">, consolide tudo em um @graph. Isso evita conflitos e facilita a manutenção.

3. Adicione tipos por página

Cada página deve ter seus tipos específicos: Article para posts, FAQPage para FAQs, Course para cursos. Use o Schema.org Validator para verificar.

4. Crie seu llms.txt

Comece com a estrutura básica: título, descrição em blockquote, seções com links. Use o template do repositório llms-txt-templates como ponto de partida.

5. Automatize a validação

Implemente um script de lint que verifique a consistência das entidades. O entity-consistency-playbook tem um guia completo de como fazer isso.

Conclusão

Schema JSON-LD e llms.txt não são tendências passageiras — são a infraestrutura de visibilidade para a era da IA generativa. Se o seu site não tem dados estruturados que LLMs consigam interpretar, você está invisível para uma parcela crescente do tráfego digital.

Comecei com um tipo de Schema. Hoje tenho 30. Comecei sem llms.txt. Hoje tenho dois arquivos que somam 65KB de contexto estruturado. Cada adição foi incremental, testável e verificável.

Se quiser um roteiro completo, o geo-checklist tem mais de 80 itens verificáveis para GEO. E o entity-consistency-playbook mostra como manter a consistência de entidades que faz diferença real na citação por IAs.

Alexandre Caramaschi é CEO da Brasil GEO, ex-CMO da Semantix (Nasdaq) e cofundador da AI Brasil. Especialista em Generative Engine Optimization, ajuda empresas a serem citadas por ChatGPT, Gemini, Perplexity e Claude.

Como construímos uma plataforma educacional de 36 cursos em 10 dias — e o que aprendemos no caminho

Alexandre Caramaschi — Sun, 29 Mar 2026 18:43:46 +0000

Em 19 de março de 2026, commitamos a primeira linha de código do que viria a se tornar a plataforma educacional da Brasil GEO. Dez dias depois, tínhamos 36 cursos, 401 módulos, um sistema de gamificação completo e um painel administrativo com auditoria de segurança feita por cinco modelos de linguagem simultaneamente.

Este artigo documenta o processo — não como vitrine, mas como estudo de caso. Cada decisão arquitetural carregou consequências. Cada incidente revelou premissas erradas. E cada correção ensinou algo que manuais de engenharia raramente cobrem.

A tese inicial: educação como infraestrutura de autoridade

A Brasil GEO nasceu como consultoria em Generative Engine Optimization — a disciplina de tornar marcas citáveis por ChatGPT, Gemini e Perplexity. Mas consultoria escala linearmente. Educação escala exponencialmente.

A hipótese era direta: se criássemos uma plataforma educacional gratuita e aberta sobre GEO, IA e desenvolvimento, construiríamos três ativos simultaneamente — autoridade técnica perante LLMs, uma base de usuários engajados e um pipeline de leads qualificados para consultoria.

O roadmap foi estruturado em cinco etapas sequenciais, cada uma desbloqueando a próxima:

Etapa 1 — Resolver Invisibilidade (60%)
Indexação, sitemap, IndexNow, headers de segurança. Saímos do zero para 78 URLs submetidas a três motores de busca.

Etapa 2 — Eliminar Violações (70%)
Consistência de entidade. O mesmo profissional aparecia como "Colunista" em um lugar, "CEO" em outro, com biografias divergentes em oito plataformas. Corrigimos cada uma.

Etapa 3 — Motor de Conteúdo (80%)
A plataforma educacional propriamente dita. 36 cursos cobrindo desde Python básico até agentes autônomos de IA. 401 módulos. 51 questões interativas. Sistema de XP, 13 badges, streaks e certificados.

Etapa 4 — Autoridade Externa (20%)
Imprensa, academia, backlinks. Cinco pitches escritos, um working paper acadêmico em preparação.

Etapa 5 — Dominar Nicho (15%)
Knowledge Panel, ranking SERP, monetização. O horizonte de longo prazo.

Os números da plataforma

Após 10 dias de desenvolvimento intensivo com 367 commits:

115.000 linhas de código TypeScript em produção
344 arquivos TypeScript/TSX
36 cursos com certificação
401 módulos de aprendizado
140 horas de conteúdo estimado
51 questões interativas (QuizEngine)
13 badges de gamificação
46 artigos publicados em 5 plataformas
16 rotas administrativas (7 páginas + 9 APIs)
13 fontes de dados ao vivo no dashboard de métricas

A stack: Next.js 16, React 19, Tailwind CSS 4, Supabase (auth + database), Vercel (deploy), Resend (email transacional).

O que quebrou — e o que aprendemos

Nenhum projeto ambicioso sobrevive ao contato com a produção sem cicatrizes. Documentamos três incidentes significativos.

Incidente 1: A corrupção silenciosa dos acentos (27 de março)

Criamos um script para corrigir acentuação em texto PT-BR. O script funcionou perfeitamente no texto visível. Mas também corrigiu URLs, transformando /educacao em /educação (com cedilha e til). Cinquenta e cinco links internos quebraram simultaneamente.

A lição: automação sem limites de escopo é uma arma apontada para o próprio pé. Implementamos proteção de URLs como regra permanente — slugs são sempre ASCII, acentos apenas em texto renderizado.

Incidente 2: O rate limiter que bloqueou o site inteiro (29 de março)

Implementamos rate limiting de 30 requisições por minuto como proteção contra abuso. O problema: aplicamos o limite a todas as rotas, incluindo páginas HTML, CSS e JavaScript. Uma única visita a uma página dispara 15-20 requisições de assets. Duas visitas consecutivas já estouravam o limite.

Usuários reais recebiam JSON de erro em vez da página. O site ficou inacessível por 30 minutos até diagnosticarmos a causa.

A correção: rate limiting exclusivamente em rotas /api/*, com limite aumentado para 120 requisições por minuto.

Incidente 3: O loop infinito do login admin (29 de março)

O painel administrativo tinha um layout que verificava a sessão do usuário e redirecionava para /admin/login se não autenticado. O problema: /admin/login era filho de /admin, então herdava o mesmo layout. O layout verificava a sessão, não encontrava, redirecionava para login, que disparava o layout novamente. Loop infinito.

A solução exigiu reestruturar a arquitetura de diretório usando Route Groups do Next.js — uma pasta (protected) para rotas que exigem autenticação, com o login fora dessa estrutura.

A auditoria de segurança com cinco LLMs

Submetemos o painel administrativo a uma auditoria completa usando cinco modelos de linguagem em paralelo: Claude Opus para arquitetura, GPT-4o para redação, Gemini para análise, Perplexity para pesquisa de vulnerabilidades conhecidas e Groq para classificação rápida.

O resultado foi revelador:

Uma vulnerabilidade crítica de bypass de autenticação — um endpoint antigo que verificava email sem validar a senha
Ausência de proteção CSRF em todos os endpoints administrativos
Rate limiters em memória que resetavam a cada deploy (ineficazes em serverless)
Logout que não invalidava cookies de sessão no servidor
Validação de entrada baseada em typeof manual, sem schema formal

Corrigimos tudo em uma única sessão: removemos o endpoint vulnerável, implementamos CSRF via validação de Origin/Referer, migramos o rate limiter para Redis distribuído (Upstash), criamos logout server-side que limpa cookies SSR, e substituímos toda validação manual por schemas Zod.

O que os alunos ganham

A plataforma é inteiramente gratuita. Qualquer pessoa pode criar uma conta, acessar os 36 cursos e acompanhar seu progresso. O sistema de gamificação não é cosmético — badges, XP e streaks criam ciclos de retenção baseados em reforço positivo.

Os cursos cobrem um arco que vai do básico ao avançado: configuração de ambiente de desenvolvimento, Python, Node.js, GitHub, Claude Code, MCP (Model Context Protocol), prompt engineering avançado, SEO e GEO, agentes autônomos de IA, dados com Python, e cursos verticais para setores como saúde, agronegócio, turismo e advocacia.

Cada curso tem certificado digital emitido automaticamente via API, com envio por email. Os quizzes interativos validam compreensão real, não apenas presença.

Próximos passos

Três prioridades imediatas definem o próximo trimestre:

Autenticação multi-fator para administradores. A infraestrutura TOTP já existe como stub. Falta integrar a biblioteca otplib e gerar QR codes para registro.

Escala de conteúdo via cross-posting automatizado. Um pipeline que publica artigos simultaneamente em DEV.to, Medium e Hashnode, com canonical URL apontando para o site principal.

Autoridade externa. Publicação do working paper acadêmico em SSRN e Preprints.org. Envio de pitches para Meio e Mensagem e veículos de tecnologia.

A plataforma está em alexandrecaramaschi.com/educacao. O roadmap completo, com métricas ao vivo de 13 fontes de dados, está em alexandrecaramaschi.com/roadmap.

Construir em público significa aceitar que o processo é tão valioso quanto o produto. Os três incidentes documentados acima ensinaram mais sobre engenharia de produção do que qualquer tutorial poderia.

Alexandre Caramaschi é CEO da Brasil GEO e ex-CMO da Semantix (Nasdaq). Escreve sobre GEO, IA e visibilidade algorítmica.

How 5 LLMs Built 9 Free Courses in One Afternoon: Multi-LLM Orchestration for Education

Alexandre Caramaschi — Thu, 26 Mar 2026 20:24:53 +0000

Last week, I published 9 free educational courses with 91 modules and approximately 19 hours of hands-on content. The total cost in AI APIs was $10.

The Problem

There is no free, integrated, Portuguese-language material that takes someone from absolute zero to mastering AI tools like Claude Code, MCP, and GEO (Generative Engine Optimization). Existing tutorials are fragmented, mostly in English, and lack practical context.

The Architecture: Multi-LLM Orchestration

I built a Python orchestrator that coordinates 5 language models working in parallel:

Claude Opus (Anthropic) — task decomposition, architecture, and code generation
GPT-4o (OpenAI) — long-form writing and copywriting
Gemini 2.5 Flash (Google) — fast analysis and classification
Perplexity Sonar — live research with source citations
Llama 3.3 70B (Groq) — ultra-fast summarization

The pipeline operates in sequential waves: research, analysis, parallel writing, classification, architecture, code generation, and review.

Each LLM has an adaptive score based on success rate (weight 0.6), cost (0.2), and latency (0.2). The system learns which model performs best for each task type.

The Real Numbers

6 courses created simultaneously by 6 parallel Claude Code CLI agents
6,439 lines of code in approximately 15 minutes
Build verified automatically before each deploy
Automatic deployment via Vercel in under 90 seconds

The 9 courses cover: VS Code, GitHub, Python, Node.js, Claude Code CLI, MCP with Chrome, Complete Setup, From SEO to GEO (with real data: 58.5% of searches are zero-click in 2025), and Technical Behind-the-Scenes.

Tech Stack

Frontend: Next.js 16 + React 19 + Tailwind CSS 4
Deploy: Vercel (auto on push to master)
Progress tracking: localStorage (no database needed)
Certificates: Resend API for email delivery
Design system: Salesforce-inspired (accent #0176d3, radius 8px)

FinOps and Cost Control

The orchestrator includes built-in financial governance:

Budget guards: $5 per execution limit
Rate limiting per provider (token bucket algorithm)
Circuit breakers for provider resilience
Daily limits per provider
Total cost for all content: approximately $10

Gamification

Each course features:

Collectible badges (unique per course)
Email-delivered certificates via Resend API
Global cross-course progress bar
CSS-only celebration animations

Implications

The cost of $10 to generate 19 hours of structured educational content redefines the economics of corporate education. The same process that created 9 courses could create 90. The limitation is no longer production capacity — it is curation and editorial quality.

Try It

Full portal: alexandrecaramaschi.com/educacao
Behind-the-scenes course: alexandrecaramaschi.com/educacao/bastidores

All courses are 100% free. No paywall. No mandatory registration.

Alexandre Caramaschi — CEO at Brasil GEO | Former CMO at Semantix (Nasdaq) | Co-founder of AI Brasil