Metadata-Version: 2.4
Name: agents-upstream
Version: 1.3.0
Summary: AI-powered research analysis system for product discovery
Home-page: https://github.com/marcelusfernandes/agents-upstream
Author: Agents Upstream Contributors
License: MIT
Project-URL: Homepage, https://github.com/marcelusfernandes/agents-upstream
Project-URL: Repository, https://github.com/marcelusfernandes/agents-upstream
Project-URL: Issues, https://github.com/marcelusfernandes/agents-upstream/issues
Keywords: ai,agents,product-discovery,research-analysis,workflow,cursor-ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Agents Upstream (Python)

[![PyPI version](https://img.shields.io/pypi/v/agents-upstream.svg)](https://pypi.org/project/agents-upstream/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/pypi/pyversions/agents-upstream.svg)](https://pypi.org/project/agents-upstream/)

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](https://www.npmjs.com/package/agents-upstream).

## 🚀 Instalação Rápida

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

```bash
pipx run agents-upstream
```

### Via pip (instalação global)

```bash
pip install agents-upstream
agents-upstream
```

### Via pip (instalação em ambiente virtual)

```bash
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

```bash
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

```bash
# 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!

```bash
# 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

```bash
# 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](https://github.com/marcelusfernandes/agents-upstream/issues)
- **Discussões:** [GitHub Discussions](https://github.com/marcelusfernandes/agents-upstream/discussions)

---

**Permite que equipes de produto pensem estrategicamente sem sacrificar velocidade.**

