🔵 Usando a Ferramenta a Fundo

O que é

O CLI (linha de comando) é o mesmo motor da web, mas operado por texto. Ele brilha quando você quer rodar várias empresas em sequência, automatizar tarefas, usar num servidor sem tela ou repetir uma análise com precisão.

Por que aprender

Quem só usa a web fica limitado a uma empresa por vez, no clique. O CLI desbloqueia escala e repetibilidade — é o que separa o uso casual do profissional.

Conceitos-chave

• Lotes: várias empresas em sequência
• Automação e uso em servidor
• Precisão: o mesmo comando, o mesmo resultado

O que é

O comando central é python -m strategy_factory.main run "Stripe". Ele dispara as 3 fases e cria a pasta output/stripe com tudo: documentos, apresentações, Word e diagramas.

Por que aprender

É o comando que você mais vai usar. Todas as flags que veremos a seguir são variações dele. Dominar o run é dominar 90% da ferramenta.

Conceitos-chave

• run "Empresa" = pipeline completo
• Nome entre aspas vira pasta output/slug
• Sempre ative o venv antes de rodar

O que é

Adicione --context "B2B payments, fintech" para dar contexto à pesquisa. Isso orienta a Perplexity e melhora a qualidade dos 15 documentos.

Por que aprender

Para empresas pouco conhecidas ou com nome ambíguo, o contexto faz toda a diferença — evita que a IA pesquise a empresa errada.

Conceitos-chave

• --context = setor, modelo, porte
• Texto livre entre aspas
• Opcional, mas recomendado

O que é

Use --mode quick (o padrão) para uma passada rápida e barata, ou --mode comprehensive para uma pesquisa mais profunda — e mais cara.

Por que aprender

É a flag que mais mexe no custo e no tempo. O Módulo 2.2 inteiro é dedicado a ela — aqui basta saber que ela existe e o que cada valor faz.

Conceitos-chave

• quick = padrão, ~9 buscas
• comprehensive = ~18 buscas, mais profundo
• Os 15 documentos são os mesmos nos dois

O que é

Com --dry-run, a ferramenta simula a execução e mostra o que seria gerado, sem fazer nenhuma chamada de IA — ou seja, sem custo.

Por que aprender

É a melhor forma de testar a instalação e as chaves antes de gastar de verdade. Se o dry-run roda sem erro, sua configuração está correta.

Conceitos-chave

• --dry-run = simulação, custo zero
• Mostra o plano de execução
• Ótimo para validar o setup

O que é

O comando status "Stripe" --detailed mostra o progresso e o custo de uma análise; list lista todas as empresas já analisadas.

Por que aprender

São seus comandos de inspeção: descobrir o que já foi feito, quanto custou e o que ainda falta — sem reabrir cada pasta na mão.

Conceitos-chave

• status "Empresa" --detailed = progresso + custo
• list = todas as análises feitas
• Não consomem API, são leitura local

O que é

resume "Stripe" retoma de onde parou; reset "Stripe" --yes limpa tudo; e as flags --skip-research, --skip-synthesis e --skip-generation reaproveitam resultados já salvos em cache.

Por que aprender

São seus comandos de recuperação e economia: nunca refaça (e pague de novo) uma etapa que já deu certo. Voltamos a eles no Módulo 2.3.

Conceitos-chave

• resume = continua o que parou
• reset --yes = recomeça do zero
• --skip-* = pula fases já em cache

O que é

A diferença está na profundidade da pesquisa: o modo Quick faz cerca de 9 buscas; o Comprehensive faz cerca de 18. Os 15 documentos gerados são exatamente os mesmos — muda a riqueza da matéria-prima.

Por que aprender

Saber que a saída é a mesma desfaz um mito comum: o Comprehensive não gera "mais documentos", ele gera documentos mais bem fundamentados.

Conceitos-chave

• Quick ≈ 9 buscas
• Comprehensive ≈ 18 buscas
• Mesmos 15 documentos nos dois

O que é

O modo padrão. Leva de 2 a 3 minutos e custa cerca de US$ 0,05 por empresa. É a passada rápida, ideal para uma primeira visão e para triagem de várias empresas.

Por que aprender

Por ser barato e veloz, é o ponto de partida natural. Você consegue avaliar muitas empresas com poucos centavos antes de aprofundar nas que importam.

Conceitos-chave

• É o padrão (sem precisar de flag)
• 2-3 min · ~US$ 0,05
• Use para triagem e primeira passada

O que é

A passada profunda. Leva de 5 a 10 minutos e custa cerca de US$ 0,50 por empresa. A pesquisa é mais ampla e detalhada — ideal para a empresa que você vai realmente apresentar.

Por que aprender

Quando o resultado vai para um cliente ou para a diretoria, vale pagar 10x mais (ainda assim centavos) para ter o melhor embasamento possível.

Conceitos-chave

• --mode comprehensive
• 5-10 min · ~US$ 0,50
• Use na empresa que vai apresentar

O que é

No Quick, a pesquisa usa só o modelo sonar (barato e rápido). No Comprehensive, ela combina sonar + sonar-pro + sonar-deep-research. A síntese, em ambos, sempre usa o Gemini gemini-2.5-flash.

Por que aprender

Entender quais modelos entram em cada modo explica por que o Comprehensive custa mais: ele usa modelos mais caros e potentes na pesquisa.

Conceitos-chave

• Quick = sonar
• Comprehensive = sonar + sonar-pro + deep-research
• Síntese sempre = gemini-2.5-flash

O que é

Na prática: o Quick fica entre ~US$ 0,02 e US$ 0,15; o Comprehensive entre ~US$ 0,31 e US$ 0,90. A fase de geração (local) é sempre gratuita.

Por que aprender

Mesmo o modo mais caro custa menos de um dólar. Ver os números lado a lado mostra que o "caro" aqui ainda é baratíssimo perto de uma consultoria.

Conceitos-chave

• Quick ~US$ 0,02-0,15
• Comprehensive ~US$ 0,31-0,90
• Geração local = grátis

O que é

A estratégia campeã: triar várias empresas no Quick e, depois, rodar a escolhida no Comprehensive. Se já tiver a pesquisa básica, use --skip-research para não pagar de novo.

Por que aprender

É o fluxo que equilibra custo e qualidade: você só gasta o caro onde vale a pena, depois de filtrar com o barato.

Conceitos-chave

• Triar no Quick, aprofundar no Comprehensive
• Árvore de decisão simples: vai apresentar? → comprehensive
• --skip-research evita pesquisa repetida

O que é

Na primeira fase, a Perplexity faz de 9 a 18 buscas sobre a empresa: visão geral, stack de tecnologia, concorrentes, dores e regulação. Tudo é coletado e salvo para as fases seguintes.

Por que aprender

É a matéria-prima de tudo. Sem uma boa pesquisa, os documentos saem fracos — por isso o contexto e o modo importam tanto.

Conceitos-chave

• 9-18 buscas conforme o modo
• Cobre empresa, setor, concorrentes e regulação
• Resultado salvo para reuso

O que é

Na segunda fase, o Gemini gera os 15 documentos em ordem de dependência — alguns só são escritos depois que outros ficam prontos. Há uma pausa de ~5s entre as chamadas para respeitar os limites da API.

Por que aprender

Entender a ordem explica por que a fase demora um pouco e por que não dá para gerar tudo de uma vez: um documento usa o anterior como insumo.

Conceitos-chave

• 15 documentos em ordem de dependência
• Pausa de ~5s entre chamadas
• Respeita o limite de requisições do Gemini

O que é

A terceira fase roda no seu computador, sem custo: monta os 2 PPTX (com a biblioteca python-pptx), os 2 DOCX e renderiza os diagramas Mermaid em PNG (usando Chrome/Puppeteer por baixo).

Por que aprender

É por isso que o custo total é tão baixo: a parte que vira "arquivos bonitos" não consome nenhuma API — é tudo local.

Conceitos-chave

• PPTX via python-pptx
• DOCX e diagramas PNG
• Mermaid renderizado com Chrome/Puppeteer

O que é

O state.json é o checkpoint da análise: guarda a fase atual, quais entregáveis já ficaram prontos, o custo gasto e os erros encontrados.

Por que aprender

É exatamente esse arquivo que permite o comando resume: sem ele, a ferramenta não saberia de onde continuar.

Conceitos-chave

• Guarda fase, entregáveis prontos, custo e erros
• É o que viabiliza o resume
• Fica na pasta da empresa

O que é

O research_cache.json guarda a pesquisa bruta da Perplexity. Com ele, você pode regerar os documentos sem repesquisar, usando --skip-research.

Por que aprender

É o seu maior aliado de economia: a pesquisa é a parte que custa. Reaproveitá-la significa ajustar e regerar documentos quase de graça.

Conceitos-chave

• Guarda a pesquisa bruta da Perplexity
• --skip-research reusa esse cache
• Regerar documentos sem pagar a pesquisa de novo

O que é

Se você interromper com Ctrl+C ou cair a internet, basta rodar resume "Empresa" para continuar de onde parou. Em erro 429 (limite de requisições), espere alguns minutos e retome.

Por que aprender

Falhas acontecem. Saber recuperar sem perder o trabalho (nem o dinheiro já gasto) é o que torna o uso tranquilo no dia a dia.

Conceitos-chave

• resume continua de onde parou
• Erro 429 = limite atingido → esperar e retomar
• O state.json preserva o progresso

O que é

Cada empresa vira uma pasta output/{slug}/ com subpastas: markdown/ (15 .md), presentations/ (2 .pptx), documents/ (2 .docx), mermaid_images/ (5 .png), além de state.json e research_cache.json.

Por que aprender

Saber a estrutura te deixa achar qualquer arquivo na hora — e entender o que cada um é. A Trilha 3 abre o conteúdo de cada entregável.

Conceitos-chave

• output/{slug}/ por empresa
• markdown, presentations, documents, mermaid_images
• + state.json e research_cache.json