# DevPulseAI - Inteligência de Sinal Multi-Agente

> Filosofia de Design: Os agentes são utilizados apenas onde é necessário raciocínio. Operações determinísticas (coleta, normalização, deduplicação) são implementadas como utilitários simples - não como agentes.

- Fonte: https://doutorai.pt/apps/devpulse-ai
- Categoria: Equipas de Agentes
- Dificuldade: Avançado
- Modelos: OpenAI, Claude, Gemini, Llama
- Frameworks: Agno
- Corre local?: Precisa de APIs cloud
- Chaves necessárias: OPENAI_API_KEY
- Licença: Apache-2.0
- Site: Doutor AI (https://doutorai.pt) - ferramentas de IA para pequenos negócios em português

## Tutorial completo

# 🧠 DevPulseAI - Inteligência de Sinais Multi-Agente

Uma implementação de referência que demonstra como construir um **pipeline multi-agente** que agrega sinais técnicos de múltiplas fontes, classifica-os em termos de relevância, avalia riscos e sintetiza um resumo de inteligência acionável.

> **Filosofia de Design:** Os agentes são utilizados **apenas onde é necessário raciocínio.** Operações determinísticas (coleta, normalização, deduplicação) são implementadas como utilitários simples - não como agentes.

---

## Arquitetura

```
┌─────────────────────────────────────────────────────────┐
│                    DATA SOURCES                         │
│  GitHub · ArXiv · HackerNews · Medium · HuggingFace     │
└──────────────────────┬──────────────────────────────────┘
                       │ raw signals
                       ▼
┌──────────────────────────────────────────────────────────┐
│  SignalCollector (UTILITY - no LLM)                      │
│  • Normalizes to unified schema                          │
│  • Deduplicates via source:id composite key              │
│  • Filters incomplete signals                            │
└──────────────────────┬───────────────────────────────────┘
                       │ normalized signals
                       ▼
┌──────────────────────────────────────────────────────────┐
│  RelevanceAgent (AGENT - gpt-4.1-mini)                   │
│  • Scores each signal 0–100 for developer relevance      │
│  • Considers: novelty, impact, actionability, timeliness  │
│  • Falls back to heuristics if no API key                 │
└──────────────────────┬───────────────────────────────────┘
                       │ scored signals
                       ▼
┌──────────────────────────────────────────────────────────┐
│  RiskAgent (AGENT - gpt-4.1-mini)                        │
│  • Assesses security vulnerabilities                      │
│  • Flags breaking changes and deprecations                │
│  • Rates risk: LOW / MEDIUM / HIGH / CRITICAL             │
└──────────────────────┬───────────────────────────────────┘
                       │ risk-assessed signals
                       ▼
┌──────────────────────────────────────────────────────────┐
│  SynthesisAgent (AGENT - gpt-4.1)                        │
│  • Cross-references relevance + risk data                 │
│  • Produces executive summary                             │
│  • Generates actionable recommendations                   │
└──────────────────────┬───────────────────────────────────┘
                       │
                       ▼
              📄 Intelligence Digest
```

## Porque a Coleta de Sinais Não É um Agente

Esta é uma **escolha de design intencional e opinativa** - não é um atalho.

A coleta de sinais envolve:

- Obter dados de APIs HTTP (determinístico)
- Normalizar campos para um esquema unificado (transformação mecânica)
- Deduplicar por chave composta (comparação de hash)

**Nenhuma destas tarefas requer raciocínio, julgamento ou compreensão da linguagem.**

Encapsular a coleta numa classe `Agent` seria _decorativo_ - teria uma importação de LLM que nunca seria chamada. Isto engana os leitores a pensar que um LLM é necessário, quando a lógica real é um laço `for` com um `set()`.

> **Regra prática:** Se consegues escrever a lógica como uma função pura sem ambiguidade, é uma utilidade. Se a saída depende da compreensão do contexto, de fazer julgamentos ou de gerar linguagem natural, é um agente.

---

## Funções dos Agentes & Seleção de Modelos

| Componente | Tipo | Modelo | Porque Este Modelo |
|---|---|---|---|
| `SignalCollector` | **Utilidade** | _nenhum_ | Determinístico - sem raciocínio necessário |
| `RelevanceAgent` | **Agente** | `gpt-4.1-mini` | Tarefa de classificação - rápida, barata, de alto volume |
| `RiskAgent` | **Agente** | `gpt-4.1-mini` | Análise estruturada - cuidadosa mas não cara |
| `SynthesisAgent` | **Agente** | `gpt-4.1` | Cruzamento de referências & sumarização - necessita do raciocínio mais forte |

**Fornecedor único por defeito (OpenAI)** para reduzir a fricção de integração. Substitui por agente através de variáveis de ambiente:

```bash
export MODEL_RELEVANCE=gpt-4.1-nano    # cheaper, faster
export MODEL_RISK=o4-mini               # deeper reasoning for risk
export MODEL_SYNTHESIS=gpt-4.1          # default, strongest
```

## Como Executar

### Verificação Rápida (Sem Chave de API Necessária)

```bash
cd advanced_ai_agents/multi_agent_apps/devpulse_ai
python verify.py
```

```markdown
# Pipeline Completo

Este executa o pipeline completo com dados simulados em **<1 segundo**. Sem chamadas de rede, sem chaves de API.

## Instalação

Para instalar as dependências, executa o seguinte comando:

```bash
pip install -r requirements.txt
```

## Execução

Para executar o pipeline, utiliza o seguinte comando:

```bash
python main.py
```

## Estrutura do Projeto

A estrutura do projeto é a seguinte:

```
/projeto
│
├── main.py
├── requirements.txt
└── src
    ├── __init__.py
    ├── module1.py
    └── module2.py
```

## Contribuição

Se quiseres contribuir, por favor, segue estas etapas:

1. Faz um fork do repositório.
2. Cria uma nova branch (`git checkout -b feature/nome-da-feature`).
3. Faz as tuas alterações e commit (`git commit -m 'Adiciona nova feature'`).
4. Faz push para a branch (`git push origin feature/nome-da-feature`).
5. Abre um Pull Request.

## Licença

Este projeto está licenciado sob a Licença MIT. Vê o ficheiro [LICENSE](LICENSE) para mais detalhes.
```

```
[OK] DevPulseAI reference pipeline executed successfully
```

### Pipeline Completo (Com Chave de API)

```bash
# Instalação das dependências
pip install -r requirements.txt
```

1. **Configuração da Chave de API**
   - Cria um ficheiro `.env` na raiz do projeto.
   - Adiciona a tua chave de API no formato:
     ```
     API_KEY=your_api_key_here
     ```

2. **Execução do Pipeline**
   - Para executar o pipeline, utiliza o seguinte comando:
     ```bash
     python main.py
     ```

3. **Estrutura do Projeto**
   ```
   ├── main.py
   ├── requirements.txt
   ├── .env
   └── src/
       ├── module1.py
       └── module2.py
   ```

4. **Descrição dos Módulos**
   - `module1.py`: Contém funções para a pré-processamento dos dados.
   - `module2.py`: Contém funções para a análise dos dados.

5. **Exemplo de Uso**
   - Após a execução do pipeline, os resultados serão armazenados na pasta `results/`.

6. **Notas Finais**
   - Certifica-te de que a chave de API é válida e que tens as permissões necessárias para aceder aos recursos.

```bash
pip install -r requirements.txt
export OPENAI_API_KEY=sk-...
python main.py
```

Sem uma chave de API, os agentes recorrem automaticamente à pontuação heurística.

### Painel Streamlit

```bash
streamlit run streamlit_app.py
```

## Estrutura do Projeto

```
devpulse_ai/
├── agents/
│   ├── __init__.py              # Package exports + design docs
│   ├── signal_collector.py      # UTILITY - normalize & dedup
│   ├── relevance_agent.py       # AGENT  - score relevance (gpt-4.1-mini)
│   ├── risk_agent.py            # AGENT  - assess risks (gpt-4.1-mini)
│   └── synthesis_agent.py       # AGENT  - produce digest (gpt-4.1)
├── adapters/
│   ├── github.py                # GitHub trending repos
│   ├── arxiv.py                 # ArXiv recent papers
│   ├── hackernews.py            # HackerNews top stories
│   ├── medium.py                # Medium AI/ML blogs
│   └── huggingface.py           # HuggingFace trending models
├── workflows/
│   └── signal-intelligence-pipeline.json
├── main.py                      # Full pipeline runner
├── verify.py                    # Mock-data verification (<1s)
├── streamlit_app.py             # Interactive dashboard
└── requirements.txt             # Minimal deps (single provider)
```

## Extensões Opcionais (Utilizadores Avançados)

Estas **não são necessárias** para a implementação de referência, mas mostram como a arquitetura se estende:

1. **Modelos multi-fornecedor** - Troca `RelevanceAgent` para usar Anthropic Claude ou Google Gemini atualizando a configuração do modelo. O framework `agno` suporta múltiplos fornecedores.

2. **Pesquisa vetorial** - Adiciona um adaptador Pinecone ou Qdrant para armazenar e recuperar sinais semanticamente para deteção de padrões a longo prazo.

3. **Resumos em streaming** - Usa streaming WebSocket a partir de `SynthesisAgent` para feeds de inteligência em tempo real.

4. **Adaptadores personalizados** - Adiciona novas fontes de sinal implementando uma função `fetch_*` que retorna `List[Dict]` com o esquema padrão (`id`, `source`, `title`, `description`, `url`, `metadata`).

5. **Ciclo de feedback** - Armazena feedback dos utilizadores (👍/👎) no Supabase e usa-o para ajustar a pontuação de relevância ao longo do tempo.

---

## Dependências

```
agno              # Agent framework
openai            # LLM provider (single default)
httpx             # HTTP client for adapters
feedparser        # RSS/Atom parsing for Medium
streamlit>=1.30   # Interactive dashboard
```

## Compromissos de Design

| Decisão | Compromisso | Porquê |
|---|---|---|
| Provedor único por defeito | Menos flexibilidade | Reduz a integração de 2+ chaves para 1 |
| Coleta de sinais como utilidade | Menos demonstração "agente" | Arquitetura honesta - agentes onde existe raciocínio |
| Alternativas heurísticas | Qualidade inferior sem chave de API | O pipeline funciona sempre, mesmo para avaliação |
| 5 sinais por fonte por defeito | Menos dados | Mantém a demonstração rápida (<10s com API, <1s simulação) |
| Sem async em agentes | Menos capacidade de processamento | Código mais simples, valor educativo mais claro |

---

_Construído como uma implementação de referência para [awesome-llm-apps](https://github.com/Shubhamsaboo/awesome-llm-apps)._

## Poupe horas todas as semanas com IA, sem complicações

O **Doutor AI** dá-lhe 1859 prompts de IA prontos a copiar, por indústria e em português simples - mais uma biblioteca técnica completa para quem quer ir mais longe. [Ver planos →](https://doutorai.pt/precos)

---
Conteúdo de Doutor AI (https://doutorai.pt). Ao citar, indique a fonte: https://doutorai.pt/apps/devpulse-ai