Agents Upstream (Python)

Sistema de análise de pesquisa com agentes especializados de IA para Product Discovery.

Nota: Este é o pacote Python. Também disponível como pacote Node.js/npm.

🚀 Instalação Rápida

📖 Para instalação detalhada, consulte: QUICK_INSTALL.md

🎯 Método Recomendado - Instalador Inteligente

Sempre instala no PATH do usuário (sem precisar de admin):

# Download e instalação em um comando
curl -sSL https://raw.githubusercontent.com/marcelusfernandes/agents-upstream/main/python-package/install.py | python3

# Ou baixe primeiro:
wget https://raw.githubusercontent.com/marcelusfernandes/agents-upstream/main/python-package/install.py
python3 install.py          # Instala no usuário (padrão)
python3 install.py --pipx   # Usa pipx (ainda melhor)
python3 install.py -g       # Instala globalmente (se precisar)

Via pipx (alternativa recomendada)

pipx run agents-upstream
# ou
pipx install agents-upstream

Via pip manual

# Recomendado: Sempre use --user para evitar problemas de PATH
pip install --user agents-upstream
agents-upstream

# Ou instalação global (pode precisar de sudo/admin)
pip install agents-upstream
agents-upstream

✨ Configuração Automática de PATH

Se você instalar sem privilégios de administrador (usando pip install --user), o pacote detecta automaticamente se o PATH precisa ser configurado e oferece configurar para você:

⚠️  ATENÇÃO: Configuração de PATH necessária

Opções:
  1. Configurar automaticamente (recomendado) ✨
  2. Pular e usar 'pipx run agents-upstream'
  3. Configurar manualmente depois

Configurar PATH depois:

# Se você pulou a configuração, pode configurar depois com:
agents-upstream --setup-path

# Ou use python diretamente:
python -m agents_upstream.cli --setup-path

O pacote configura automaticamente para:

• Linux/Mac: Adiciona ~/.local/bin ao seu .bashrc ou .zshrc
• Windows: Adiciona Scripts ao PATH do usuário (sem precisar de admin)

Via pip (instalação em ambiente virtual)

python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate  # Windows

pip install agents-upstream
agents-upstream

Isso criará toda a estrutura de pastas, templates e agentes de IA no diretório atual.

📦 O que está incluído?

• 9 Agentes Especializados de IA para análise de problema e solução
• 17+ Templates profissionais para análise estratégica
• Sistema de workflow automatizado com validação de qualidade
• Documentação completa com exemplos e melhores práticas

🎯 O que o sistema faz?

Transforma semanas de análise estratégica em horas, mantendo supervisão e validação humana:

• Analisa entrevistas e dados de pesquisa de usuários
• Identifica automaticamente problemas-chave, oportunidades e insights estratégicos
• Gera análises completas de pain points até recomendações de solução
• Produz relatórios prontos para executivos e roadmaps de implementação

📋 Requisitos

• Python 3.8 ou superior
• Cursor AI ou editor compatível com Cursor Rules

🔧 Como usar

1. Instalar

pipx run agents-upstream

2. Preparar materiais

• Coloque arquivos de entrevista em 0-documentation/0b-Interviews/
• Atualize 0-documentation/0a-projectdocs/context.md com objetivos do negócio

3. Iniciar workflow

No Cursor AI, digite:

start workflow

O sistema progride automaticamente pelos Agentes 0-5 (análise de problema) e depois Agentes 6-8 (desenvolvimento de solução).

📂 Estrutura criada

├── 0-documentation/          # Contexto do projeto e materiais fonte
│   ├── 0a-projectdocs/       # Documentação de contexto
│   └── 0b-Interviews/        # Arquivos de entrevista
├── _output-structure/        # Templates e guias de formatação
│   ├── problem-space/        # Templates de análise de problema
│   └── solution-space/       # Templates de desenvolvimento de solução
└── .cursor/                  # Agentes de IA e regras de workflow
    └── rules/
        ├── problem-space/    # Agentes 0-5
        └── solution-space/   # Agentes 6-8

🤖 Agentes Incluídos

Problem Space (Agentes 0-5)

• Agent 0: Product & Service Design Specialist
• Agent 1: Qualitative Research Specialist
• Agent 2: Pain Point Analysis Specialist
• Agent 3: As-Is Journey Mapper
• Agent 4: Journey Consolidation Specialist
• Agent 5: Strategic Report Generator

Solution Space (Agentes 6-8)

• Agent 6: Strategic Analysis Specialist
• Agent 7: Process Optimization Specialist
• Agent 8: Communication Specialist

📊 Entregáveis

Pacote de Análise de Problema

• Declaração estratégica de problema
• Análise de pain points
• Mapeamento de jornada do estado atual
• Relatório abrangente de problema

Pacote de Ideação de Solução

• Oportunidades estratégicas com ROI
• Roadmap de implementação
• Avaliação de automação
• Apresentação executiva
• Plano de gestão de mudança

🛠️ Desenvolvimento

Instalação local para desenvolvimento

# Clone o repositório
git clone https://github.com/marcelusfernandes/agents-upstream.git
cd agents-upstream/python-package

# Crie um ambiente virtual (recomendado)
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

# IMPORTANTE: Instale dependências de build/publicação
pip install build twine

# Instale em modo editável
pip install -e .

# Teste
agents-upstream

Build Automatizado

O pacote Python sincroniza automaticamente com o repositório principal durante o build!

# Build completo (sincroniza templates + build)
python build_package.py

# Ou use o Makefile (recomendado)
make build

# Outros comandos úteis
make help          # Ver todos os comandos
make clean         # Limpar artefatos
make sync          # Apenas sincronizar templates
make test          # Testar instalação
make dev           # Instalar modo desenvolvimento

⚡ Vantagens do Build Automatizado

• ✅ Uma única fonte de verdade: Templates sempre sincronizados com ../template/
• ✅ Zero manutenção duplicada: Não precisa copiar manualmente
• ✅ Sempre atualizado: Build garante templates mais recentes
• ✅ Simples: Um comando faz tudo

Publicação

# Publicar no TestPyPI (teste)
make publish-test

# Publicar no PyPI (produção)
make publish

# Ou manualmente:
python build_package.py
python -m twine upload --repository testpypi dist/*  # TestPyPI
python -m twine upload dist/*                        # PyPI

🆚 Python vs Node.js

Ambas as versões oferecem a mesma funcionalidade. Escolha baseado no seu ambiente:

Característica	Python (pipx)	Node.js (npx)
Execução sem instalação	✅ pipx run	✅ npx
Templates incluídos	✅ Idênticos	✅ Idênticos
Agentes de IA	✅ Idênticos	✅ Idênticos
Telemetria	❌ Não	✅ Opcional
Dependências	Nenhuma	posthog-node, chalk, etc

Recomendação:

• Use Python se você trabalha principalmente com Python
• Use Node.js se você trabalha com desenvolvimento web/frontend

📝 Licença

MIT

🤝 Contribuindo

Contribuições são bem-vindas! Este é um sistema em evolução projetado para melhoria contínua.

Como Contribuir

1. Faça um fork do projeto
2. Crie uma branch para sua feature (git checkout -b feature/MinhaFeature)
3. Commit suas mudanças (git commit -m 'Adiciona MinhaFeature')
4. Push para a branch (git push origin feature/MinhaFeature)
5. Abra um Pull Request

🐛 Troubleshooting

Problema: Comando não encontrado após instalação?

Solução Automática (Recomendado):

# Configure PATH automaticamente em um comando
agents-upstream --setup-path

# Ou se isso não funcionar, use Python diretamente:
python -m agents_upstream.cli --setup-path

Alternativas:

• Use pipx run agents-upstream (não requer configuração de PATH)
• Consulte o Guia de Troubleshooting PATH para configuração manual detalhada

📧 Suporte

• Documentação: Consulte a documentação completa incluída após a instalação
• Troubleshooting PATH: PATH_TROUBLESHOOTING.md
• Issues: GitHub Issues
• Discussões: GitHub Discussions

---

Permite que equipes de produto pensem estrategicamente sem sacrificar velocidade.