13. Guia: Usar dados NovaOps (adaptive-rag) no ingest-rag

Este documento explica como integrar os dados sintéticos gerados em adaptive-rag/ no sistema de retrieval ingest-rag/.

---

1. Configuração inicial

1.1 Gerar e carregar dados

cd ../adaptive-rag
./build.sh

Isto gera todos os dados e sobe Postgres + Neo4j com seed. Após correr:

• Postgres: localhost:5432 (novaops/novaops/novaops)
• Neo4j: http://localhost:7474 (neo4j/novaops)
• Docs: adaptive-rag/data/generated/docs/*.md
• Eval: adaptive-rag/data/processed/eval/eval_questions.jsonl

1.2 Ligar dados ao ingest-rag

Opção A — symlink (recomendado):

cd ingest-rag
rm -rf data/generated  # se existir
ln -s ../adaptive-rag/data/generated data/generated

Opção B — copiar:

cp -r ../adaptive-rag/data/generated ingest-rag/data/

O ingest-rag passa a ter:

• data/generated/docs/ — documentos Markdown
• data/generated/sql/ — CSVs + schema (úteis para referência)
• data/generated/graph/ — nodes.json, edges.json
• data/generated/metadata/ — document_manifest, source_registry

---

2. Mapeamento estratégia ↔ fontes

---

3. Por estratégia: como usar os dados

3.1 Direct Answer (Resposta direta)

Não usa dados. Resposta baseada apenas no conhecimento do LLM.

---

3.2 Simple RAG

Pipeline: Query → retrieval (vector) → rerank → generate

Passos de implementação:

1. Chunking — usar data/processed/retrieval_views/chunk_plan.json (ou data/generated/metadata/ se copiados) para regras por documento.

2. Indexar docs — carregar chunks em vector store (Chroma, FAISS, pgvector):

   • Pasta: data/generated/docs/
   • 11 documentos: employee_handbook, security_policy, expense_policy, etc.

3. Exemplo de ingestão (pseudo-código):

   from pathlib import Path
   from langchain_community.document_loaders import DirectoryLoader, TextLoader
   from langchain.text_splitter import RecursiveCharacterTextSplitter
   
   docs_dir = Path("data/generated/docs")
   loader = DirectoryLoader(str(docs_dir), glob="*.md", loader_cls=TextLoader)
   documents = loader.load()
   
   splitter = RecursiveCharacterTextSplitter(chunk_size=512, chunk_overlap=50)
   chunks = splitter.split_documents(documents)
   
   # Adicionar a Chroma/pgvector
   vector_store.add_documents(chunks)
   

4. Retrieval — em simple_rag, após o analyzer escolher strategy=simple_rag, chamar o retriever com a query.

---

3.3 Enriched RAG

Pipeline: Query → decomposition / multi-query → retrieval (várias queries) → rerank → synthesis

Dados: Os mesmos docs do Simple RAG. A diferença está na lógica (decomposição, multi-query, hybrid search).

Metadata filters — usar document_manifest.json para filtrar por document_type, related_entities:

• Ex.: query sobre "expenses" → filtrar docs com related_entities que incluam team_finance ou pol_expense.

---

3.4 Multi-Backend Agent

Fontes: docs + SQL (Postgres) + graph (Neo4j)

Postgres — conexão:

import psycopg2
conn = psycopg2.connect(
    host="localhost", port=5432,
    user="novaops", password="novaops",
    dbname="novaops"
)

Tabelas: teams, employees, services, projects, incidents, tickets, budgets, expenses, service_kpis, policies, document_references, etc.

Neo4j — conexão:

from neo4j import GraphDatabase
driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "novaops"))

Relações úteis: EMPLOYEE_BELONGS_TO_TEAM, TEAM_OWNS_SERVICE, PROJECT_IMPACTS_SERVICE, INCIDENT_AFFECTED_SERVICE, SERVICE_DEPENDS_ON_SERVICE, TICKET_RELATES_TO_SERVICE, etc.

Tools sugeridas para LangGraph:

• query_docs — retriever vetorial sobre docs
• query_sql — executar SQL no Postgres (com validação)
• query_graph — Cypher no Neo4j

---

4. Configuração no ingest-rag

Adicionar a config/ ou .env:

# Paths (relativo ao projeto ingest-rag)
DATA_DOCS_PATH=data/generated/docs
DATA_SQL_SCHEMA_PATH=data/generated/sql/schema.sql
DATA_GRAPH_PATH=data/generated/graph

# Postgres (quando Docker do adaptive-rag está a correr)
PG_HOST=localhost
PG_PORT=5432
PG_USER=novaops
PG_PASSWORD=novaops
PG_DATABASE=novaops

# Neo4j
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=novaops

# Vector store (Chroma, etc.)
VECTOR_STORE_PATH=./data/chroma_db

---

5. Dataset de avaliação

O ficheiro adaptive-rag/data/processed/eval/eval_questions.jsonl tem 55 perguntas com:

• expected_strategy — direct_answer, simple_rag, enriched_rag, multi_backend
• expected_sources — documentos ou tabelas esperadas
• gold_answer — resposta de referência
• related_entities — entidades do universo NovaOps

Uso:

1. Rodar cada query pelo pipeline do ingest-rag
2. Comparar strategy_used com expected_strategy (router accuracy)
3. Comparar resposta com gold_answer (qualidade)
4. Verificar se as fontes usadas cobrem expected_sources

import json
with open("../adaptive-rag/data/processed/eval/eval_questions.jsonl") as f:
    eval_data = [json.loads(line) for line in f]

for item in eval_data:
    # POST /query com item["question"]
    # Validar strategy_used vs expected_strategy
    # Opcional: validar answer vs gold_answer

---

6. Ordem sugerida de implementação

---

7. Exemplo de fluxo completo

User: "Qual foi o orçamento da equipa de Engineering no Q1 2023?"
    ↓
Query Analyzer → requires_structured_data=true, sources=["sql"], strategy=multi_backend_agent
    ↓
Strategy Router → multi_backend_agent
    ↓
Multi-Backend Agent:
  1. Planner decide: precisa de SQL
  2. Tool query_sql: SELECT amount_usd FROM budgets WHERE team_id='team_eng' AND quarter='Q1' AND year=2023
  3. Result: 450000
  4. Synthesis: "O orçamento da equipa Engineering no Q1 2023 foi de $450,000."

---

8. Ficheiros de referência