Funcionalidade: Pipeline de IA — RAG (Retrieval-Augmented Generation) + Minilayers
Visão Geral
Expansão significativa da infraestrutura de inteligência artificial do plugin, dividida em dois pilares principais:
- Minilayers API: Sistema de geração de camadas simplificadas via IA, permitindo criar representações visuais resumid
de dados geoespaciais.
- Layers RAG Pipeline: Pipeline de Recuperação Aumentada (RAG) especializado para camadas de mapa, que enriquece o co
xto enviado aos modelos de IA com metadados, estilos e descrições de cores das camadas.
Ambos os sistemas são auto-contidos, registram suas próprias rotas REST e se integram ao painel administrativo de IA e
xistente.
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arquitetura
Camada Arquivo Função
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Minilayer Agent src/includes/ai/class-minilayer-agent.php Orquestra a geração de minilayers via IA
Minilayer Handler src/includes/ai/class-minilayer-handler.php Processamento, cache e entrega das minilayers
geradas
RAG Worker src/includes/ai/class-rag-worker.php Motor de processamento do pipeline RAG
RAG Agent src/includes/ai/class-rag-agent.php Interface entre o RAG e os modelos de IA
RAG Backup src/includes/ai/class-rag-backup.php Persistência e recuperação de estado do pipeli
ne
RAG Config src/includes/ai/class-rag-pipeline-config.php Configuração dinâmica do pipeline
Color Describer src/includes/ai/class-color-describer.php Análise e descrição de paletas de cores de cam
adas
Layer Data Loader src/includes/ai/class-layer-data-loader.php Carregamento e normalização de dados de camada
s para contexto
AI Handler src/includes/class-ai-handler.php Integração geral com o sistema de IA do plugin
CLI src/includes/cli/class-ai-cli.php Comandos WP-CLI para execução manual do pipeli
ne
Settings UI src/includes/ai/settings/tab-knowledge.php Nova aba "Knowledge" no painel de configuraçõe
s de IA
Docs .architecture/ai/README.md, .architecture/minil Documentação arquitetural
ayer/README.md
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Minilayers API
class-minilayer-agent.php (164 linhas)
• Orquestra o agente de IA responsável por gerar descrições/versões simplificadas de camadas complexas
• Comunica-se com o adapter NeuronAI para processamento assíncrono
• Gerencia o ciclo de vida da geração: prompt → processamento → resposta → cache
class-minilayer-handler.php (245 linhas)
• Recebe requisições REST e retorna minilayers processadas
• Implementa lógica de preferência por camadas estilizáveis: prioriza tiles que aceitem customização visual (hue, satu
ção, contraste)
• Gerencia cache das minilayers geradas para evitar reprocessamento desnecessário
• Valida permissões e quotas de uso
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Layers RAG Pipeline
class-rag-worker.php (326 linhas — expandido significativamente)
• Núcleo do pipeline de processamento em background
• Executa as etapas do RAG:
1. Ingestão: coleta metadados da camada (tipo, fonte, estilo, zoom, bounds)
2. Enriquecimento: adiciona descrições de cores e dados contextuais
3. Chunking: divide informações em segmentos processáveis
4. Embedding: envia para o modelo de IA gerar vetores de busca
5. Indexação: armazena no banco para recuperação rápida
• Suporta processamento em lote (bulk) via fila do WordPress
class-rag-agent.php (atualizado)
• Interface entre o worker e os modelos de linguagem
• Gerencia o contexto enviado aos prompts, incluindo agora informações enriquecidas de camadas
• Tratamento de fallback quando o pipeline RAG não retorna resultados
class-rag-backup.php (atualizado)
• Persiste o estado intermediário do pipeline para recuperação em caso de falha
• Armazena checkpoints a cada etapa crítica do processamento
class-rag-pipeline-config.php (114 linhas — novo)
• Configuração centralizada do pipeline:
• Modelo de embedding utilizado
• Tamanho dos chunks
• Overlap entre segmentos
• Filtros de camadas elegíveis ao RAG
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Color Describer
class-color-describer.php (277 linhas — novo)
• Analisa paletas de cores de camadas vetoriais e raster
• Gera descrições textuais das cores dominantes, tons e contrastes
• Utiliza algoritmos de quantização de cor + modelo de linguagem para descrição semântica
• Correção aplicada: remove fallback para nome de matiz (hue) nulo, garantindo que a descrição de cor sempre retorne u
valor válido
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Layer Data Loader
class-layer-data-loader.php (359 linhas — novo)
• Carrega e normaliza dados técnicos de camadas para alimentar o contexto do RAG
• Extrai informações de:
• Metadados do post da camada
• Configurações de estilo (JSON de estilo Mapbox/MapLibre)
• Propriedades de fonte de dados (URL, tipo, tilejson, etc.)
• Estatísticas de uso e cobertura geográfica
• Converte formatos heterogêneos em estrutura padronizada para o pipeline
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
CLI e Interface Administrativa
class-ai-cli.php (atualizado — +124/-40 linhas)
• Novos comandos WP-CLI:
• wp jeo ai rag:process — executa o pipeline RAG manualmente para uma ou mais camadas
• wp jeo ai rag:status — verifica o status do processamento em background
• wp jeo ai minilayer:generate — gera minilayer para uma camada específica
• wp jeo ai minilayer:clear-cache — limpa o cache de minilayers
tab-knowledge.php (112 linhas — nova aba no admin)
• Interface visual no painel de configurações de IA
• Permite:
• Visualizar o status do índice RAG
• Reprocessar camadas manualmente
• Configurar parâmetros do pipeline (modelo, chunk size, etc.)
• Ver estatísticas de minilayers geradas
settings-page.js (atualizado)
• Componentes React para a nova aba "Knowledge"
• Integração com endpoints REST de status do pipeline
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Fluxo de Dados (RAG + Minilayers)
[Camada do Mapa]
↓
[Layer Data Loader] → Normalização de metadados e estilo
↓
[Color Describer] → Descrição textual da paleta de cores
↓
[RAG Worker] → Chunking + Embedding + Indexação
↓
[RAG Backup] → Persistência de checkpoint
↓
[AI Handler / NeuronAI] → Recuperação aumentada em consultas
↓
[Minilayer Agent] → Geração de camada simplificada (quando solicitado)
↓
[Minilayer Handler] → Cache e entrega via REST
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Correções Pós-Lançamento
Commit Correção
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
09dc06a O Minimap (consumidor das Minilayers) passa a preferir camadas estilizáveis. Atualização na lógica de sel
eção de class-minilayer-agent.php e class-minilayer-handler.php
7c8fd55 Hue name should never be null: removido fallback que permitia nome de matiz nulo no class-color-describer
.php, garantindo descrições de cor sempre válidas
4df23aa Correções de PHPCS: ajustes de lint em class-bulk-processor.php, class-rag-backup.php, class-rag-worker.p
hp e class-ai-handler.php para conformidade com WPCS
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arquivos Criados / Modificados
Arquivos novos:
• src/includes/ai/class-minilayer-agent.php (164 linhas)
• src/includes/ai/class-minilayer-handler.php (245 linhas)
• src/includes/ai/class-color-describer.php (277 linhas)
• src/includes/ai/class-layer-data-loader.php (359 linhas)
• src/includes/ai/class-rag-pipeline-config.php (114 linhas)
• src/includes/ai/settings/tab-knowledge.php (112 linhas)
• .architecture/minilayer/README.md (70+ linhas)
Arquivos modificados:
• src/includes/ai/class-rag-agent.php — integração com layer data loader
• src/includes/ai/class-rag-backup.php — melhorias na persistência de estado
• src/includes/ai/class-rag-worker.php — expansão massiva do pipeline (+326/-81 linhas)
• src/includes/class-ai-handler.php — integração geral com minilayers e RAG
• src/includes/cli/class-ai-cli.php — novos comandos WP-CLI
• src/includes/settings/settings-page.js — nova aba Knowledge na UI
• .architecture/ai/README.md — documentação atualizada (+72 linhas)
• .architecture/README.md — índice atualizado
• .architecture/rest-api/README.md — documentação dos novos endpoints
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Notas de Compatibilidade
• Requer PHP 8.2+ (conforme padrão do projeto)
• Requer extensões MySQL com suporte a JSON (para armazenamento de embeddings e checkpoints)
• Dependência NeuronAI: O pipeline RAG e a geração de minilayers dependem do adapter NeuronAI configurado e funcionand
• Processamento em background: O RAG utiliza a fila de eventos do WordPress (WP Cron ou system cron recomendado para v
umes grandes)
• Cache: Minilayers são cacheadas em transientes do WordPress; limpar o cache requer uso do CLI ou da interface admin
• Modelos de IA: A nova aba "Knowledge" na administração permite configurar qual modelo de embedding será utilizado pe
pipeline RAG
• Rollback: O class-rag-backup.php mantém checkpoints que permitem retomar o pipeline do ponto de falha, sem reprocess
ento completo
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Funcionalidade: Pipeline de IA — RAG (Retrieval-Augmented Generation) + Minilayers
Visão Geral
Expansão significativa da infraestrutura de inteligência artificial do plugin, dividida em dois pilares principais:
de dados geoespaciais.
xto enviado aos modelos de IA com metadados, estilos e descrições de cores das camadas.
Ambos os sistemas são auto-contidos, registram suas próprias rotas REST e se integram ao painel administrativo de IA e
xistente.
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arquitetura
Camada Arquivo Função
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Minilayer Agent src/includes/ai/class-minilayer-agent.php Orquestra a geração de minilayers via IA
Minilayer Handler src/includes/ai/class-minilayer-handler.php Processamento, cache e entrega das minilayers
geradas
RAG Worker src/includes/ai/class-rag-worker.php Motor de processamento do pipeline RAG
RAG Agent src/includes/ai/class-rag-agent.php Interface entre o RAG e os modelos de IA
RAG Backup src/includes/ai/class-rag-backup.php Persistência e recuperação de estado do pipeli
ne
RAG Config src/includes/ai/class-rag-pipeline-config.php Configuração dinâmica do pipeline
Color Describer src/includes/ai/class-color-describer.php Análise e descrição de paletas de cores de cam
adas
Layer Data Loader src/includes/ai/class-layer-data-loader.php Carregamento e normalização de dados de camada
s para contexto
AI Handler src/includes/class-ai-handler.php Integração geral com o sistema de IA do plugin
CLI src/includes/cli/class-ai-cli.php Comandos WP-CLI para execução manual do pipeli
ne
Settings UI src/includes/ai/settings/tab-knowledge.php Nova aba "Knowledge" no painel de configuraçõe
s de IA
Docs .architecture/ai/README.md, .architecture/minil Documentação arquitetural
ayer/README.md
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Minilayers API
class-minilayer-agent.php (164 linhas)
• Orquestra o agente de IA responsável por gerar descrições/versões simplificadas de camadas complexas
• Comunica-se com o adapter NeuronAI para processamento assíncrono
• Gerencia o ciclo de vida da geração: prompt → processamento → resposta → cache
class-minilayer-handler.php (245 linhas)
• Recebe requisições REST e retorna minilayers processadas
• Implementa lógica de preferência por camadas estilizáveis: prioriza tiles que aceitem customização visual (hue, satu
ção, contraste)
• Gerencia cache das minilayers geradas para evitar reprocessamento desnecessário
• Valida permissões e quotas de uso
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Layers RAG Pipeline
class-rag-worker.php (326 linhas — expandido significativamente)
• Núcleo do pipeline de processamento em background
• Executa as etapas do RAG:
1. Ingestão: coleta metadados da camada (tipo, fonte, estilo, zoom, bounds)
2. Enriquecimento: adiciona descrições de cores e dados contextuais
3. Chunking: divide informações em segmentos processáveis
4. Embedding: envia para o modelo de IA gerar vetores de busca
5. Indexação: armazena no banco para recuperação rápida
• Suporta processamento em lote (bulk) via fila do WordPress
class-rag-agent.php (atualizado)
• Interface entre o worker e os modelos de linguagem
• Gerencia o contexto enviado aos prompts, incluindo agora informações enriquecidas de camadas
• Tratamento de fallback quando o pipeline RAG não retorna resultados
class-rag-backup.php (atualizado)
• Persiste o estado intermediário do pipeline para recuperação em caso de falha
• Armazena checkpoints a cada etapa crítica do processamento
class-rag-pipeline-config.php (114 linhas — novo)
• Configuração centralizada do pipeline:
• Modelo de embedding utilizado
• Tamanho dos chunks
• Overlap entre segmentos
• Filtros de camadas elegíveis ao RAG
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Color Describer
class-color-describer.php (277 linhas — novo)
• Analisa paletas de cores de camadas vetoriais e raster
• Gera descrições textuais das cores dominantes, tons e contrastes
• Utiliza algoritmos de quantização de cor + modelo de linguagem para descrição semântica
• Correção aplicada: remove fallback para nome de matiz (hue) nulo, garantindo que a descrição de cor sempre retorne u
valor válido
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Layer Data Loader
class-layer-data-loader.php (359 linhas — novo)
• Carrega e normaliza dados técnicos de camadas para alimentar o contexto do RAG
• Extrai informações de:
• Metadados do post da camada
• Configurações de estilo (JSON de estilo Mapbox/MapLibre)
• Propriedades de fonte de dados (URL, tipo, tilejson, etc.)
• Estatísticas de uso e cobertura geográfica
• Converte formatos heterogêneos em estrutura padronizada para o pipeline
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
CLI e Interface Administrativa
class-ai-cli.php (atualizado — +124/-40 linhas)
• Novos comandos WP-CLI:
• wp jeo ai rag:process — executa o pipeline RAG manualmente para uma ou mais camadas
• wp jeo ai rag:status — verifica o status do processamento em background
• wp jeo ai minilayer:generate — gera minilayer para uma camada específica
• wp jeo ai minilayer:clear-cache — limpa o cache de minilayers
tab-knowledge.php (112 linhas — nova aba no admin)
• Interface visual no painel de configurações de IA
• Permite:
• Visualizar o status do índice RAG
• Reprocessar camadas manualmente
• Configurar parâmetros do pipeline (modelo, chunk size, etc.)
• Ver estatísticas de minilayers geradas
settings-page.js (atualizado)
• Componentes React para a nova aba "Knowledge"
• Integração com endpoints REST de status do pipeline
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Fluxo de Dados (RAG + Minilayers)
[Camada do Mapa]
↓
[Layer Data Loader] → Normalização de metadados e estilo
↓
[Color Describer] → Descrição textual da paleta de cores
↓
[RAG Worker] → Chunking + Embedding + Indexação
↓
[RAG Backup] → Persistência de checkpoint
↓
[AI Handler / NeuronAI] → Recuperação aumentada em consultas
↓
[Minilayer Agent] → Geração de camada simplificada (quando solicitado)
↓
[Minilayer Handler] → Cache e entrega via REST
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Correções Pós-Lançamento
Commit Correção
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
09dc06a O Minimap (consumidor das Minilayers) passa a preferir camadas estilizáveis. Atualização na lógica de sel
eção de class-minilayer-agent.php e class-minilayer-handler.php
7c8fd55 Hue name should never be null: removido fallback que permitia nome de matiz nulo no class-color-describer
.php, garantindo descrições de cor sempre válidas
4df23aa Correções de PHPCS: ajustes de lint em class-bulk-processor.php, class-rag-backup.php, class-rag-worker.p
hp e class-ai-handler.php para conformidade com WPCS
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Arquivos Criados / Modificados
Arquivos novos:
• src/includes/ai/class-minilayer-agent.php (164 linhas)
• src/includes/ai/class-minilayer-handler.php (245 linhas)
• src/includes/ai/class-color-describer.php (277 linhas)
• src/includes/ai/class-layer-data-loader.php (359 linhas)
• src/includes/ai/class-rag-pipeline-config.php (114 linhas)
• src/includes/ai/settings/tab-knowledge.php (112 linhas)
• .architecture/minilayer/README.md (70+ linhas)
Arquivos modificados:
• src/includes/ai/class-rag-agent.php — integração com layer data loader
• src/includes/ai/class-rag-backup.php — melhorias na persistência de estado
• src/includes/ai/class-rag-worker.php — expansão massiva do pipeline (+326/-81 linhas)
• src/includes/class-ai-handler.php — integração geral com minilayers e RAG
• src/includes/cli/class-ai-cli.php — novos comandos WP-CLI
• src/includes/settings/settings-page.js — nova aba Knowledge na UI
• .architecture/ai/README.md — documentação atualizada (+72 linhas)
• .architecture/README.md — índice atualizado
• .architecture/rest-api/README.md — documentação dos novos endpoints
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Notas de Compatibilidade
• Requer PHP 8.2+ (conforme padrão do projeto)
• Requer extensões MySQL com suporte a JSON (para armazenamento de embeddings e checkpoints)
• Dependência NeuronAI: O pipeline RAG e a geração de minilayers dependem do adapter NeuronAI configurado e funcionand
• Processamento em background: O RAG utiliza a fila de eventos do WordPress (WP Cron ou system cron recomendado para v
umes grandes)
• Cache: Minilayers são cacheadas em transientes do WordPress; limpar o cache requer uso do CLI ou da interface admin
• Modelos de IA: A nova aba "Knowledge" na administração permite configurar qual modelo de embedding será utilizado pe
pipeline RAG
• Rollback: O class-rag-backup.php mantém checkpoints que permitem retomar o pipeline do ponto de falha, sem reprocess
ento completo
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────