Almost every problem has a simple solution — and almost every good result comes from a few good habits. This final module brings together the most common errors with each one’s fix, plus best practices, the cost, and the ethics of using the tool.
Illustrative diagram — from error to solution in four steps.
The error 401 means "unauthorized": the key is incorrect or missing. It’s the number one issue for people getting started — and it’s almost always a small oversight.
# 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!After fixing it, restart the app so it rereads the file.
The app only reads .env when it starts. Fixed the key? Stop and restart the app — otherwise, it keeps using the old version and the 401 persists.
This error almost always means one thing: the virtual environment (venv) is not active. Without it, Python can’t see the installed libraries.
# 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 erroOn Windows, also check that Python is on the PATH (selected during installation).
Each new terminal opens "clean." It's easy to forget to activate the venv when you open a new window—and then Python looks for the libraries in the wrong place. Always activate it before running.
Good to know: this "problem" almost never stops you. If port 8888 is already in use, the app automatically finds another available port.
# Deixar o app escolher (padrão)
python -m strategy_factory.webapp
# Forçar uma porta específica
python -m strategy_factory.webapp --port 9000If the address in your browser shows a different number, the app simply found an available port — everything is working normally.
Unlike a 401 or “module not found,” a busy port is just a warning. If you see a port other than 8888, open that address and continue.
The error 429 means "too many requests" — you hit the API rate limit. The good news: you don’t lose the work already done.
1. Stop and wait — 5 to 10 minutes
2. Pick up where you left off — use the resume command
3. Ready — it reuses what’s already been generated
# Continuar de onde parou, sem refazer tudo
python -m strategy_factory.main resume "Stripe"There’s already a delay of about 5s built in between Gemini calls, specifically to avoid 429 errors.
APIs limit how many requests you can make per minute. Waiting a little usually solves the problem—and the resume ensures you don’t start from scratch.
If the diagrams are generated as Blank PNG, Chrome is usually missing—it’s used by Puppeteer, which "takes the picture" of the Mermaid diagram.
The documents may turn out perfectly while only the images fail — a problem limited to the Generation phase. Knowing the cause keeps you from thinking that "everything went wrong": just install Chrome and generate them again.
The difference between a mediocre draft and a great one usually comes down to four simple habits. They save money and greatly improve quality.
# Bom contexto = pesquisa mais precisa
python -m strategy_factory.main run "Acme" \
--mode quick \
--context "fintech B2B, 200 funcionários, Brasil"Specific context makes a huge difference for companies that aren’t well known or have ambiguous names.
Run ten companies in quick mode (pennies each) and spend on the in-depth analysis only for the one that really matters. It's the tool's best value.
Use the tool with responsibility protects you and the company. Three principles and a simple way to track spending.
The research is based on public information—not confidential company data. Don’t paste internal secrets into the context.
The result needs human review. Treat it as a quality starting point — not the final word.
The recommendations are no substitute for an expert. For serious legal or financial decisions, check with a professional.
# 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 listRemember: quick ~US$ 0,05 · comprehensive ~US$ 0,50 per company · local generation is free.
Public data, drafts with human review, no claim to be definitive advice, and closely monitored spending. This lets you use the tool responsibly and sustainably.
From installation to deliverables: you now know how to generate the package, understand each document, present it to leadership, and solve the most common problems. All that's left is to put it into practice.