Casi todos los problemas tienen una solución sencilla, y casi todos los buenos resultados se obtienen con algunos hábitos adecuados. Este módulo final reúne los errores más comunes con la corrección de cada uno, además de las buenas prácticas, el costo y la ética de usar la herramienta.
Diagrama ilustrativo — del error a la solución en cuatro pasos.
El error 401 significa "no autorizado": la clave es incorrecta o falta. Es el problema número uno de quienes empiezan, y casi siempre se debe a un detalle tonto.
# 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!Después de corregirlo, reinicia la app para que vuelva a leer el archivo.
La app solo lee el .env al iniciarse. ¿Corregiste la clave? Detén y vuelve a iniciar la app; de lo contrario, seguirá usando la versión anterior y el 401 persistirá.
Este error casi siempre quiere decir una cosa: el el entorno virtual (venv) no está activo. Sin él, Python no reconoce las 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 erroEn Windows, comprueba también que Python esté en el PATH (marcado durante la instalación).
Cada terminal nuevo se abre "limpio". Es fácil olvidar activar el venv al abrir una ventana nueva y entonces Python busca las bibliotecas en el lugar equivocado. Actívalo siempre antes de ejecutar.
Es bueno saberlo: este "problema" casi nunca te detiene. Si el puerto 8888 ya está en uso, la app encuentra automáticamente otro puerto libre.
# Deixar o app escolher (padrão)
python -m strategy_factory.webapp
# Forçar uma porta específica
python -m strategy_factory.webapp --port 9000Si la dirección del navegador aparece con otro número, es que la app encontró un puerto disponible — todo normal.
A diferencia del 401 y de "module not found", que el puerto esté ocupado es solo un aviso. Si ves un puerto distinto de 8888, abre esa dirección y continúa.
El error 429 significa "muchas solicitudes": alcanzaste el límite de tasa de la API. La buena noticia: no pierdes el trabajo ya realizado.
1. Detente y espera — de 5 a 10 minutos
2. Continúa desde donde lo dejaste — usa el comando resume
3. Listo — aprovecha lo que ya se generó
# Continuar de onde parou, sem refazer tudo
python -m strategy_factory.main resume "Stripe"Ya hay un retraso de unos 5s incorporado entre las llamadas a Gemini, precisamente para evitar el 429.
Las API limitan cuántas solicitudes haces por minuto. Esperar un poco casi siempre lo resuelve, y la resume garantiza que no empieces desde cero.
Si los diagramas se generan como PNG en blanco, generalmente falta Chrome — que usa Puppeteer para "tomar la foto" del diagrama Mermaid.
Los documentos pueden salir perfectos y solo fallar las imágenes: es un problema de la fase de Generación. Saber la causa evita pensar que "todo salió mal": basta con instalar Chrome y volver a generarlos.
La diferencia entre un borrador mediocre y uno excelente suele estar en cuatro hábitos sencillos. Estos ahorran dinero y mejoran mucho la calidad.
# Bom contexto = pesquisa mais precisa
python -m strategy_factory.main run "Acme" \
--mode quick \
--context "fintech B2B, 200 funcionários, Brasil"Un contexto específico marca una gran diferencia en empresas poco conocidas o con nombres ambiguos.
Ejecuta diez empresas en el modo rápido (unos centavos cada una) y reserva el análisis en profundidad solo para la que realmente importa. Es la mejor relación costo-beneficio de la herramienta.
Usar la herramienta con responsabilidad te protege a ti y a la empresa. Tres principios y una forma sencilla de controlar el gasto.
La investigación se basa en información pública, no en datos confidenciales de la empresa. No pegues secretos internos en el contexto.
El resultado necesita revisión humana. Tómalo como un punto de partida de calidad, no como la última palabra.
Las recomendaciones no sustituyen a un especialista. Para decisiones legales o financieras importantes, consulta con un profesional.
# 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 listRecuerda: quick ~US$ 0,05 · comprehensive ~US$ 0,50 por empresa · la generación local es gratis.
Datos públicos, borrador con revisión humana, sin carácter de asesoramiento definitivo y gastos monitoreados de cerca. Así, usas la herramienta de forma responsable y sostenible.
Desde la instalación hasta los entregables: ahora sabes cómo generar el paquete, entender cada documento, presentarlo a la dirección y resolver los problemas más comunes. Solo tienes que ponerlo en práctica.