Arquitectura de Referencia: Agentes de IA Empresariales

from google.cloud import bigquery
from vertexai.generative_models import GenerativeModel
import looker_sdk

class GroundedBIAgent:
    """
    Agente de IA fundamentado en capa semántica LookML
    """
    def __init__(self):
        self.model = GenerativeModel("gemini-1.5-pro")
        self.looker = looker_sdk.init40()
        self.bq_client = bigquery.Client()

    def process_query(self, user_question: str) -> dict:
        """
        Procesa consulta de lenguaje natural con grounding semántico
        """
        # Paso 1: Obtener contexto semántico disponible de Looker
        explores = self.looker.all_lookml_models()
        context = self._build_semantic_context(explores)

        # Paso 2: Usar Gemini para interpretar consulta con grounding semántico
        grounded_prompt = f"""
        Eres un asistente analista de BI. Responde SOLO usando las
        definiciones semánticas proporcionadas. Si te preguntan sobre métricas no
        definidas aquí, di que no puedes responder.

        DEFINICIONES SEMÁNTICAS DISPONIBLES:
        {context}

        PREGUNTA DEL USUARIO: {user_question}

        Genera una especificación de consulta de API de Looker (NO SQL directo).
        Incluye: model, view, fields, filters, sorts.
        """

        response = self.model.generate_content(grounded_prompt)
        query_spec = self._parse_query_spec(response.text)

        # Paso 3: Ejecutar vía Looker (hereda toda la gobernanza)
        result = self.looker.run_inline_query(
            result_format="json",
            body=query_spec
        )

        # Paso 4: Generar explicación en lenguaje natural
        explanation = self._generate_explanation(
            question=user_question,
            data=result,
            query_spec=query_spec
        )

        return {
            "answer": explanation,
            "data": result,
            "query_used": query_spec,
            "governance": {
                "grounded": True,
                "semantic_model": query_spec.get("model"),
                "access_validated": True
            }
        }

    def _build_semantic_context(self, explores):
        """
        Construye contexto semántico desde definiciones LookML
        """
        context = []
        for explore in explores:
            context.append(f"""
            Explore: {explore.name}
            Descripción: {explore.description}
            Dimensiones Disponibles: {[d.name for d in explore.dimensions]}
            Medidas Disponibles: {[m.name for m in explore.measures]}
            """)
        return "\n".join(context)

# Archivo de modelo con documentación amigable para agentes
explore: orders {
  label: "Órdenes de Clientes"
  description: "Todas las órdenes de clientes incluyendo estado, ingresos y fulfillment.
                Usa este explore para responder preguntas sobre ventas, ingresos,
                volumen de órdenes y patrones de compra de clientes."

  # Define joins válidos para el agente
  join: customers {
    type: left_outer
    sql_on: ${orders.customer_id} = ${customers.id} ;;
    relationship: many_to_one
  }

  join: products {
    type: left_outer
    sql_on: ${order_items.product_id} = ${products.id} ;;
    relationship: many_to_one
  }
}

view: orders {
  sql_table_name: analytics.fct_orders ;;

  # El agente necesita descripciones claras para cada campo
  dimension: order_id {
    primary_key: yes
    type: number
    sql: ${TABLE}.order_id ;;
    description: "Identificador único para cada orden"
  }

  dimension_group: order {
    type: time
    timeframes: [raw, date, week, month, quarter, year]
    sql: ${TABLE}.order_timestamp ;;
    description: "Cuándo se realizó la orden. Usar para análisis basado en tiempo."
  }

  dimension: order_status {
    type: string
    sql: ${TABLE}.status ;;
    description: "Estado actual: pending, processing, shipped, delivered, cancelled"
    suggestions: ["pending", "processing", "shipped", "delivered", "cancelled"]
  }

  # Medidas con contexto de negocio
  measure: total_revenue {
    type: sum
    sql: ${TABLE}.order_total ;;
    value_format_name: usd
    description: "Valor total de orden en USD. Excluye órdenes canceladas y devueltas."
    filters: [order_status: "-cancelled, -returned"]

    # Tags ayudan a los agentes a entender cuándo usar esta métrica
    tags: ["revenue", "sales", "financial", "primary_metric"]
  }

  measure: order_count {
    type: count_distinct
    sql: ${TABLE}.order_id ;;
    description: "Número de órdenes únicas realizadas"
    filters: [order_status: "-cancelled"]
    tags: ["volume", "count", "orders"]
  }

  measure: average_order_value {
    type: number
    sql: ${total_revenue} / NULLIF(${order_count}, 0) ;;
    value_format_name: usd
    description: "Ingreso promedio por orden (AOV). Métrica clave de e-commerce."
    tags: ["aov", "average", "efficiency"]
  }
}