agents-upstream 1.3.0

AI-powered research analysis system for product discovery

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

Via pipx (recomendado - não requer instalação)

pipx run agents-upstream

Via pip (instalação global)

pip install agents-upstream
agents-upstream

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

📧 Suporte

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

---

Permite que equipes de produto pensem estrategicamente sem sacrificar velocidade.