Quase todo problema tem solução simples — e quase todo bom resultado vem de alguns hábitos certos. Este módulo final reúne os erros mais comuns com a correção de cada um, mais as boas práticas, o custo e a ética de usar a ferramenta.
Diagrama ilustrativo — do erro à solução em quatro passos.
O erro 401 significa "não autorizado": a chave está errada ou ausente. É o problema número um de quem começa — e quase sempre é um detalhe bobo.
# Certo — sem espaços, chave completa
PERPLEXITY_API_KEY=pplx-xxxxxxxxxxxxxxxx
GEMINI_API_KEY=AIzaSyxxxxxxxxxxxxxxxx
# Errado — espaço ou chave pela metade
PERPLEXITY_API_KEY = pplx-xxx ← espaços!
GEMINI_API_KEY=AIzaSy ← incompleta!Depois de corrigir, reinicie o app para ele reler o arquivo.
O app só lê o .env quando inicia. Corrigiu a chave? Pare e suba o app de novo — senão ele continua usando a versão antiga e o 401 persiste.
Esse erro quase sempre quer dizer uma coisa: o ambiente virtual (venv) não está ativo. Sem ele, o Python não enxerga as bibliotecas instaladas.
# 1) Ative o ambiente virtual
source venv/bin/activate # Mac / Linux
.\venv\Scripts\activate # Windows
# 2) (Re)instale as dependências
pip install -r requirements.txt
# 3) Rode de novo o que deu erroNo Windows, confira também se o Python está no PATH (marcado na instalação).
Cada novo terminal abre "limpo". É fácil esquecer de ativar o venv ao abrir uma janela nova — e aí o Python procura as bibliotecas no lugar errado. Ative sempre antes de rodar.
Bom saber: este "problema" quase nunca trava você. Se a porta 8888 já estiver em uso, o app encontra outra porta livre automaticamente.
# Deixar o app escolher (padrão)
python -m strategy_factory.webapp
# Forçar uma porta específica
python -m strategy_factory.webapp --port 9000Se o endereço no navegador aparecer com outro número, é só o app tendo achado uma porta livre — tudo normal.
Diferente do 401 e do "module not found", a porta ocupada é só um aviso. Se ver uma porta diferente de 8888, abra esse endereço e siga em frente.
O erro 429 significa "muitas requisições" — você bateu no limite de taxa da API. A boa notícia: você não perde o trabalho já feito.
1. Pare e espere — de 5 a 10 minutos
2. Continue de onde parou — use o comando resume
3. Pronto — ele aproveita o que já foi gerado
# Continuar de onde parou, sem refazer tudo
python -m strategy_factory.main resume "Stripe"Já existe um delay de cerca de 5s embutido entre as chamadas do Gemini, justamente para evitar o 429.
As APIs limitam quantas requisições você faz por minuto. Esperar um pouco quase sempre resolve — e o resume garante que você não comece do zero.
Se os diagramas saem como PNG em branco, geralmente falta o Chrome — usado pelo Puppeteer, que "tira a foto" do diagrama Mermaid.
Os documentos podem sair perfeitos e só as imagens falharem — é um problema só da fase de Geração. Saber a causa evita achar que "tudo deu errado": basta instalar o Chrome e regerar.
A diferença entre um rascunho mediano e um ótimo costuma estar em quatro hábitos simples. Eles economizam dinheiro e melhoram muito a qualidade.
# Bom contexto = pesquisa mais precisa
python -m strategy_factory.main run "Acme" \
--mode quick \
--context "fintech B2B, 200 funcionários, Brasil"Um contexto específico faz diferença enorme em empresas pouco conhecidas ou de nome ambíguo.
Rode dez empresas no modo rápido (centavos cada) e só gaste o aprofundado naquela que realmente importa. É o melhor custo-benefício da ferramenta.
Usar a ferramenta com responsabilidade protege você e a empresa. Três princípios e uma forma simples de acompanhar o gasto.
A pesquisa se baseia em informação pública — não em dados sigilosos da empresa. Não cole segredos internos no contexto.
O resultado precisa de revisão humana. Trate como ponto de partida de qualidade — não como palavra final.
As recomendações não substituem um especialista. Para decisões legais ou financeiras sérias, valide com um profissional.
# Ver o estado de uma análise, em detalhe
python -m strategy_factory.main status "Empresa" --detailed
# Listar todas as análises já feitas
python -m strategy_factory.main listLembre: quick ~US$ 0,05 · comprehensive ~US$ 0,50 por empresa · a geração local é grátis.
Dados públicos, rascunho com revisão humana, sem caráter de conselho definitivo, e gasto acompanhado de perto. Com isso, você usa a ferramenta de forma responsável e sustentável.
Da instalação aos entregáveis: agora você sabe gerar o pacote, entender cada documento, apresentar à diretoria e resolver os problemas mais comuns. É só colocar em prática.