8. Contratos e Modelos de Dados

QueryAnalysis (Saída do Bloco 1)

Objeto produzido pelo Query Analyzer.

# Exemplo
needs_grounding: true
task_type: comparative          # factual | procedural | comparative | analytical | exploratory | structured_numeric
complexity: medium              # low | medium | high
requires_structured_data: false
requires_multi_source: false
sources: ["docs"]               # docs | sql | api | graph
latency_tier: normal            # rápido | normal | qualidade
risk_level: medium              # low | medium | high
strategy: enriched_rag          # recomendação do analyzer
confidence: 0.81                # [0, 1]

Schema (JSON Schema)

{
  "type": "object",
  "properties": {
    "needs_grounding": { "type": "boolean" },
    "task_type": {
      "type": "string",
      "enum": ["factual", "procedural", "comparative", "analytical", "exploratory", "structured_numeric"]
    },
    "complexity": {
      "type": "string",
      "enum": ["low", "medium", "high"]
    },
    "requires_structured_data": { "type": "boolean" },
    "requires_multi_source": { "type": "boolean" },
    "sources": {
      "type": "array",
      "items": { "type": "string", "enum": ["docs", "sql", "api", "graph"] }
    },
    "latency_tier": {
      "type": "string",
      "enum": ["fast", "normal", "quality"]
    },
    "risk_level": {
      "type": "string",
      "enum": ["low", "medium", "high"]
    },
    "strategy": {
      "type": "string",
      "enum": ["direct_answer", "simple_rag", "enriched_rag", "multi_backend_agent", "clarify_first", "safe_decline"]
    },
    "confidence": { "type": "number", "minimum": 0, "maximum": 1 }
  },
  "required": ["needs_grounding", "task_type", "complexity", "strategy", "confidence"]
}

---

ExecutionResult (Saída do Bloco 4)

Objeto produzido após cada execução, para logs e métricas.

# Exemplo
strategy_used: simple_rag
sources_used: ["docs"]
documents_retrieved: 6
reranked_top_k: 4
citations_count: 3
confidence: 0.77
latency_ms: 1320
cost_usd: 0.014
fallback_triggered: false

Schema

{
  "type": "object",
  "properties": {
    "strategy_used": { "type": "string" },
    "sources_used": { "type": "array", "items": { "type": "string" } },
    "documents_retrieved": { "type": "integer" },
    "reranked_top_k": { "type": "integer" },
    "citations_count": { "type": "integer" },
    "confidence": { "type": "number" },
    "latency_ms": { "type": "number" },
    "cost_usd": { "type": "number" },
    "fallback_triggered": { "type": "boolean" }
  }
}

---

QueryRequest (Entrada da API)

{
  "query": "O que diz a policy de despesas sobre reembolso?",
  "conversation_id": "optional-uuid",
  "context": "contexto opcional de voltas anteriores",
  "latency_preference": "rápido | normal | qualidade",
  "user_profile": {}
}

---

QueryResponse (Saída da API)

{
  "answer": "A policy de despesas indica que...",
  "citations": [
    { "doc_id": "expense_policy", "passage": "...", "score": 0.92 }
  ],
  "strategy_used": "simple_rag",
  "confidence": 0.85,
  "sources_used": ["docs"],
  "metadata": {
    "latency_ms": 1200,
    "fallback_triggered": false
  }
}

---

Interfaces por Bloco

Bloco 1 — Query Analyzer

Entrada: QueryRequest (mínimo: query)
Saída: QueryAnalysis
Efeitos secundários: nenhum (stateless)

Bloco 2 — Strategy Router

Entrada: QueryAnalysis
Saída: strategy: string (ex: "simple_rag") + reasoning: string (opcional, para auditoria)
Efeitos secundários: nenhum (determinístico ou quase)

Bloco 3 — Execution Layer

Entrada:

• query: string
• strategy: string
• QueryAnalysis (contexto)

Saída:

• answer: string
• citations: Citation[]
• confidence: number
• ExecutionResult (para observabilidade)

Bloco 4 — Avaliação / Observabilidade

Entrada: ExecutionResult + QueryRequest + resposta final
Saída: logs estruturados, traces, métricas
Efeitos secundários: logging, métricas, armazém de feedback opcional