3. Tools e Fontes de Dados

O retrieval acede a três fontes: documentos (vector store), SQL (Postgres), graph (Neo4j).

---

2.1 DocStore — Documentos

Responsabilidade

• Ler chunks do Chroma
• Embeddar queries com sentence-transformers
• Devolver [(doc_id, passage, score), ...]

API

store = DocStore()
chunks = store.retrieve(query="policy de despesas", top_k=5)
# [(doc_id, passage, score), ...]
count = store.count()

Dados

• Fonte: data/generated/docs/*.md (ou symlink para adaptive-rag)
• Indexação: python scripts/ingest_docs.py
• Coleção Chroma: "docs", espaço cosseno

---

2.2 SQLTool — Dados Estruturados

Responsabilidade

• Executar apenas queries SELECT
• Validar que não há INSERT/UPDATE/DELETE
• Devolver List[dict] (rows como dicts)

API

tool = SQLTool()
rows = tool.query("SELECT team_id, amount_usd FROM budgets WHERE quarter='Q1'")
# [{"team_id": "team_eng", "amount_usd": 450000}, ...]
available = tool.available()  # Postgres acessível?

Validação

• Começa por SELECT
• Proibido: INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE

Schema para Text-to-SQL

O LLM recebe schema resumido (até 3000 chars) de schema.sql para gerar queries.

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

Configuração

---

2.3 Neo4jTool — Graph

Responsabilidade

• Executar apenas Cypher read-only (MATCH, OPTIONAL MATCH, RETURN)
• Validar que não há CREATE/MERGE/DELETE
• Devolver List[dict] (records)

API

tool = Neo4jTool()
rows = tool.query("MATCH (t:Team)-[:OWNS_SERVICE]->(s:Service) RETURN t.name, s.name")
# [{"t.name": "Engineering", "s.name": "Billing API"}, ...]
available = tool.available()

Validação

• Deve conter MATCH ou OPTIONAL MATCH
• Proibido: CREATE, MERGE, DELETE, DETACH, REMOVE, SET, DROP, LOAD CSV, CALL apoc, etc.

Schema para Text-to-Cypher

Labels e relações NovaOps descritas em prompt: Team, Employee, Service, Incident, OWNS_SERVICE, BELONGS_TO, etc.

Configuração

---

2.4 Quando Cada Tool é Usada

O planner (LLM) decide use_docs, use_sql, use_graph por query.

---

2.5 Integração no Multi-Backend

Planner → {"use_docs": true, "use_sql": true, "use_graph": false}
    |
    v
Tools (paralelo conceptual):
    • use_docs → DocStore.retrieve(query, top_k)
    • use_sql → LLM text-to-SQL → SQLTool.query(sql)
    • use_graph → LLM text-to-Cypher → Neo4jTool.query(cypher)
    |
    v
Format context: docs_context, sql_context, graph_context
    |
    v
Synthesis LLM combina os três contextos

---

2.6 Teoria: Novas Fontes

Para adicionar APIs externas ou outras bases:

1. Criar tool com query(url, params) ou equivalente
2. Validar entradas (evitar SSRF, injection)
3. Adicionar ao planner prompt: "use_api": bool
4. Incluir schema/descrição da API no prompt
5. Formatar saída para synthesis