Imported from huannvictor/PricePulseAI (AGENTS.md). Install upstream with npx skills add huannvictor/PricePulseAI. Copyright stays with the author.

PricePulse AI: Orquestrador Autônomo de Inteligência de Preços e Automação RPA

Visão Geral do Projeto

O PricePulse AI é um ecossistema de automação inteligente e coleta de dados orientado por agentes autônomos no Google Antigravity. O sistema monitora variações de preços de produtos ou ativos no mercado, aplica regras avançadas de validação de negócios em tempo real, registra o histórico detalhado em um banco de dados relacional (PostgreSQL) e automatiza a tomada de decisão para oportunidades comerciais.

Este projeto foi desenhado para demonstrar arquitetura moderna de agentes baseados em arquivos de configuração locais, integração via Model Context Protocol (MCP), execução em modo autônomo (YOLO Mode) e engenharia de software orientada a dados.

Arquitetura de Pastas e Componentes

A estrutura do workspace é organizada de forma modular para desacoplar as responsabilidades de coleta, análise e notificação:

PricePulseAI/
├── AGENTS.md                          # Diretriz global e contexto do ecossistema de agentes
├── .agents/
│   ├── mcp_config.json                # Configuração do servidor MCP do PostgreSQL
│   └── skills/
│       ├── analyst-agent/SKILL.md     # Skill de lógica de negócios, cálculo de margem e delta de preços
│       ├── interface-agent/SKILL.md   # Skill de UX/UI, ergonomia de terminal, assets e build .exe
│       ├── notifier-agent/SKILL.md    # Skill de persistência estruturada e disparo de alertas
│       ├── scraper-agent/SKILL.md     # Skill de coleta e varredura web / APIs
│       ├── security-agent/SKILL.md    # Skill de segurança, gestão de segredos e sanitização
│       └── version-manager-agent/SKILL.md # Skill de versionamento semântico e governança Git
├── database/
│   └── schema.sql                     # Definição das tabelas relacionais e índices de histórico
└── src/
    ├── main.py                        # Orquestrador central da execução automatizada
    └── scraper.py                     # Motor de extração de dados

Definição dos Agentes e Skills

1. scraper-agent

• Escopo: Coleta de dados web e extração estruturada 100% real.
• Regras Operacionais:
  • Extrai dados reais e específicos de produtos diretamente em grandes varejistas (KaBuM!, Amazon Brasil, Kalunga).
  • Proíbe estritamente fallbacks simulados, preços fictícios ou links genéricos de busca (/busca/, /s?k=).
  • Retorna exclusivamente o link direto do produto e o preço real mais barato encontrado por loja.
  • Aplica filtros estritos de relevância para descartar acessórios (suportes, cabos) em buscas de produtos centrais.

2. analyst-agent

• Escopo: Validação de regras de negócio e cálculo de variação.
• Regras Operacionais:
  • Compara o preço coletado atualmente com a média histórica armazenada no banco de dados via MCP.
  • Identifica "Oportunidades Críticas" com base em limiares de desconto configurados (ex: queda superior a 15%).
  • Valida a consistência e integridade dos dados antes de autorizar a persistência.

3. notifier-agent

• Escopo: Persistência relacional e disparo de alertas automatizados.
• Regras Operacionais:
  • Registra o histórico completo de coletas no PostgreSQL mantendo rastreabilidade temporal.
  • Aciona logs detalhados e formata mensagens de alerta para canais externos (como webhooks).
  • Proíbe operações destrutivas no banco (como DROP ou TRUNCATE) sem validação explícita de segurança.

4. version-manager-agent

• Escopo: Versionamento semântico, auditoria da working tree, governança do repositório Git e documentação.
• Regras Operacionais:
  • Audita arquivos modificados, pendentes e não rastreados a cada alteração significativa.
  • Agrupa modificações de forma atômica por domínio/responsabilidade.
  • Formata mensagens de commit seguindo rigidamente o padrão Conventional Commits (<tipo>(<escopo>): <descrição>).
  • Cria e mantém o arquivo README.md sincronizado com novas capacidades, comandos e infraestrutura do ecossistema.
  • Assegura que credenciais e arquivos de ambiente (.env) nunca sejam rastreados.

5. security-agent

• Escopo: Segurança da informação, proteção de dados, gestão de segredos e sanitização.
• Regras Operacionais:
  • Aplica política de segredo zero em arquivos de código e configuração (proíbe senhas padrão em fallbacks).
  • Exige validação estrita de variáveis de ambiente (.env) e falha segura imediata em caso de ausência.
  • Garante o mascaramento de dados sensíveis e credenciais em logs e saídas de console.
  • Assegura consultas 100% parametrizadas no PostgreSQL para neutralizar riscos de SQL Injection.

6. interface-agent

• Escopo: Governança da interface gráfica desktop (GUI com janelas, botões, cards e tabelas visuais), ergonomia de interação, identidade visual, gestão de assets/ícones (.ico/.png) e empacotamento executável (.exe clicável) para distribuição desktop no Windows.
• Regras Operacionais:
  • Projeta e mantém a interface gráfica desktop moderna (src/gui.py) com CustomTkinter, oferecendo janelas, botões de ação rápida, cards e tabelas interativas.
  • Garante execução não-bloqueante de coletas web e banco de dados através de background threads (threading.Thread).
  • Adiciona botões clicáveis de ação direta ("Abrir no Navegador", "Atualizar Cotações", "Excluir com Confirmação").
  • Mantém o padrão visual de assets na pasta assets/ (icon.png 512x512 e icon.ico multi-resolução para Windows).
  • Automatiza a geração do executável standalone (PricePulseAI.exe) via PyInstaller com ícone oficial embutido e carregamento dinâmico de .env.
  • Fornece launcher de duplo clique (PricePulseAI.bat) para inicialização com zero atrito no Windows.

Schema do Banco de Dados (database/schema.sql)

-- 1. Sessões de Pesquisas de Mercado
CREATE TABLE IF NOT EXISTS pesquisas (
    id SERIAL PRIMARY KEY,
    titulo VARCHAR(255) NOT NULL,
    criado_em TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    atualizado_em TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 2. Itens Solicitados na Pesquisa
CREATE TABLE IF NOT EXISTS itens_pesquisa (
    id SERIAL PRIMARY KEY,
    pesquisa_id INT REFERENCES pesquisas(id) ON DELETE CASCADE,
    termo_busca VARCHAR(255) NOT NULL,
    criado_em TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 3. Ofertas e Resultados Coletados por Loja
CREATE TABLE IF NOT EXISTS ofertas_pesquisa (
    id SERIAL PRIMARY KEY,
    item_pesquisa_id INT REFERENCES itens_pesquisa(id) ON DELETE CASCADE,
    loja VARCHAR(100) NOT NULL,
    nome_produto VARCHAR(255) NOT NULL,
    preco_atual NUMERIC(10, 2) NOT NULL,
    url_origem TEXT NOT NULL,
    disponivel BOOLEAN DEFAULT TRUE,
    coletado_em TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- 4. Histórico Temporal de Preços das Ofertas
CREATE TABLE IF NOT EXISTS historico_ofertas (
    id SERIAL PRIMARY KEY,
    oferta_id INT REFERENCES ofertas_pesquisa(id) ON DELETE CASCADE,
    preco NUMERIC(10, 2) NOT NULL,
    variacao_percentual NUMERIC(5, 2),
    status_alerta VARCHAR(50),
    coletado_em TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX IF NOT EXISTS idx_itens_pesquisa_id ON itens_pesquisa(pesquisa_id);
CREATE INDEX IF NOT EXISTS idx_ofertas_item_id ON ofertas_pesquisa(item_pesquisa_id);
CREATE INDEX IF NOT EXISTS idx_hist_oferta_id ON historico_ofertas(oferta_id, coletado_em DESC);

Guia de Execução Rápida

1. Subir o ambiente de banco de dados: Certifique-se de que o container PostgreSQL está ativo e exposto na porta padrão:

   docker ps

2. Inicializar o ecossistema de agentes no Antigravity: Abra o terminal na raiz do projeto e inicie o CLI em modo autônomo:

    agy --dangerously-skip-permissions

3. Comandos sugeridos para os agentes:

   • "Analise o schema do banco e valide se a estrutura está pronta para receber novas coletas."
   • "Execute o fluxo do scraper-agent simulando a varredura de um produto monitorado e grave o histórico no banco de dados."