Módulo 3.3 — Integrações Avançadas

1

🌐 Arquitetura de Integração

Integrações avançadas transformam o segundo cérebro em um sistema de captura automática. Em vez de você anotar manualmente, scripts coletam dados de APIs e os depositam em raw/.

🌐 Hub de Integrações

2

🐙 Integração com GitHub

O GitHub é uma fonte rica de contexto técnico: PRs, issues, commits e releases. Coletar automaticamente esse contexto elimina a necessidade de documentar decisões técnicas manualmente.

Script: github_collector.py

"""Coleta atividade GitHub e grava em raw/"""
import requests
from datetime import date
from pathlib import Path

def collect_github_activity(token: str, org: str, vault_path: str):
    headers = {"Authorization": f"token {token}"}
    today = date.today().isoformat()

    # Coleta PRs merged hoje
    prs = requests.get(
        f"https://api.github.com/search/issues",
        params={"q": f"org:{org} is:pr merged:{today}"},
        headers=headers
    ).json()["items"]

    # Formata como nota raw/
    content = f"""# GitHub Activity — {today}

## PRs Merged
"""
    for pr in prs:
        content += f"""
### [{pr['title']}]({pr['html_url']})
- Repo: {pr['repository_url'].split('/')[-1]}
- Autor: @{pr['user']['login']}
- Body: {pr['body'][:200] if pr['body'] else 'sem descrição'}
"""

    # Salva em raw/
    raw_path = Path(vault_path) / "raw" / "github"
    raw_path.mkdir(exist_ok=True)
    (raw_path / f"github-{today}.md").write_text(content)
    print(f"✅ {len(prs)} PRs coletados")

O que coletar

→ PRs merged com descrição e reviewers
→ Issues criadas e fechadas
→ Releases com changelog
→ Review comments em PRs importantes

Evite coletar

→ Todos os commits (muito ruído)
→ Build logs (não agrega contexto)
→ Dependabot PRs (automatizados)
→ Draft PRs (incompletos)

3

💬 Integração com Slack

Decisões importantes frequentemente acontecem no Slack e se perdem. O coletor de Slack filtra por canais e palavras-chave específicas para capturar apenas o que importa.

Script: slack_collector.py

"""Coleta mensagens relevantes do Slack"""
from slack_sdk import WebClient
from pathlib import Path
import re

# Canais e keywords de interesse
CANAIS_IMPORTANTES = ["#decisoes-tecnicas", "#arquitetura", "#produto"]
KEYWORDS = ["decidimos", "aprovado", "mudança", "importante", "atenção"]

def collect_slack_digest(token: str, vault_path: str):
    client = WebClient(token=token)
    digest = []

    for channel_name in CANAIS_IMPORTANTES:
        # Busca mensagens das últimas 24h
        history = client.conversations_history(
            channel=channel_name,
            oldest=str(time.time() - 86400)
        )
        for msg in history["messages"]:
            text = msg.get("text", "")
            # Filtra por keywords relevantes
            if any(kw in text.lower() for kw in KEYWORDS):
                digest.append({
                    "canal": channel_name,
                    "texto": text[:500],
                    "user": msg.get("user")
                })

    # Grava digest em raw/
    if digest:
        today = date.today().isoformat()
        content = format_digest(digest)
        (Path(vault_path) / f"raw/slack/slack-digest-{today}.md").write_text(content)

4

📅 Integração com Calendário

O calendário sabe quais reuniões você teve. Com a API do Google Calendar, o agente cria automaticamente uma nota de reunião em raw/ com os participantes e a agenda antes de cada meeting.

Script: calendar_collector.py

"""Cria notas de reunião automaticamente antes dos meetings"""
from google.oauth2.credentials import Credentials
from googleapiclient.discovery import build

def create_meeting_notes(creds_path: str, vault_path: str):
    creds = Credentials.from_authorized_user_file(creds_path)
    service = build("calendar", "v3", credentials=creds)

    # Busca eventos de amanhã
    tomorrow_start = get_tomorrow_iso_start()
    tomorrow_end = get_tomorrow_iso_end()

    events = service.events().list(
        calendarId="primary",
        timeMin=tomorrow_start,
        timeMax=tomorrow_end,
        singleEvents=True
    ).execute().get("items", [])

    for event in events:
        attendees = [a["email"] for a in event.get("attendees", [])]
        # Cria template de nota em raw/
        note = f"""# Meeting: {event['summary']}
Data: {event['start']['dateTime']}
Participantes: {', '.join(attendees)}
Agenda: {event.get('description', 'sem agenda')}

## Notas (preencher durante a reunião)

## Decisões

## Ação Items
- [ ]
"""
        filename = slugify(event["summary"]) + ".md"
        (Path(vault_path) / "raw/reunioes" / filename).write_text(note)

5

🔒 Segurança e Dados Sensíveis

Integrações com APIs externas envolvem tokens, senhas e dados pessoais. Nunca armazene credenciais no vault — use variáveis de ambiente e seja cuidadoso com PII.

✅ Práticas Seguras

# Nunca isso:
GITHUB_TOKEN = "ghp_abc123..."

# Use variáveis de ambiente:
import os
token = os.environ["GITHUB_TOKEN"]

# .env (nunca commitar)
GITHUB_TOKEN=ghp_abc123
SLACK_TOKEN=xoxb-abc123

# .gitignore
.env
*.credentials.json
vault/raw/emails/  # PII

⚠ Cuidados com PII

→Emails de clientes: nunca armazene no vault
→Dados de usuários: anonimize antes de ingerir
→Senhas/tokens: jamais apareçam em notas
→Se sync via Git: todo vault é semi-público

6

🎛️ Orquestração: Integration Hub

Com múltiplos coletores, você precisa de um orquestrador que coordena execução, trata erros e monitora saúde de todas as integrações.

integration_hub.py — Orquestrador

import schedule, time, logging
from collectors import github_collector, slack_collector, calendar_collector

logging.basicConfig(level=logging.INFO)
log = logging.getLogger("hub")

def run_collector(name: str, func):
    try:
        func()
        log.info(f"✅ {name} concluído")
    except Exception as e:
        log.error(f"❌ {name} falhou: {e}")
        # Alerta — sem quebrar os outros coletores

# Agenda
schedule.every(15).minutes.do(run_collector, "GitHub", github_collector.collect)
schedule.every(30).minutes.do(run_collector, "Slack", slack_collector.collect)
schedule.every().day.at("08:00").do(run_collector, "Calendar", calendar_collector.create_notes)
schedule.every().day.at("22:00").do(ingest_all_raw)  # LLM ingere tudo

log.info("🚀 Integration Hub iniciado")
while True:
    schedule.run_pending()
    time.sleep(60)

✅ Conceitos-chave do módulo

✓APIs externas → raw/ → LLM compila → wiki/

✓GitHub: PRs, issues, releases por API

✓Slack: filtrar por canal e keyword

✓Calendar: pré-criar templates de reunião

✓Credenciais: sempre em variáveis de ambiente

✓Hub: orquestra todos os coletores com retry