Saltar a contenido

Herramientas que leen datos

El asistente responde en nombre de un usuario, y no tiene permisos propios. Lo que una herramienta lee tiene que quedar acotado como si ese usuario lo pidiera a la API: con su permiso sobre la tabla y con sus reglas de fila. Si una herramienta leyera sin ellas, cualquiera podría preguntarle al asistente por lo que la API no le deja ver.

No hace falta reimplementar nada: tai-api ya sabe qué puede ver cada usuario, porque está declarado en rbac/chatbot.py. La herramienta solo tiene que pedírselo, y para eso está el contexto.

El contexto

Cada respuesta se ejecuta con un Contexto (agente/contexto.py): quién pregunta, y con qué modelo se responde. Una herramienta lo recibe declarando un argumento runtime:

from langchain.tools import ToolRuntime
from ..contexto import Contexto


@tool
async def mi_herramienta(..., runtime: ToolRuntime[Contexto]) -> ...:
    runtime.context          # el Contexto de esta respuesta

runtime lo pone LangChain al ejecutar la herramienta: el modelo no lo ve ni puede darle valor.

Qué es
runtime.context.username El usuario que pregunta
runtime.context.token Su AccessToken, el mismo que validó la API: sus roles y sus permisos
runtime.context.exigir(accion, tabla) Comprueba que tiene el permiso de API de esa tabla (read, create, update, delete). Si no, lanza SinPermiso
runtime.context.reglas(schema) Sus reglas de fila en ese schema, para pasarlas como rls= a cada consulta

Las dos últimas son exactamente lo que haría un endpoint generado por tai-api:

El permiso de la tabla Las filas
Un endpoint generado (GET /mantenimiento/averia) requires_permissions: averia-read Las reglas de fila del usuario: owner() y las de sus roles
Una herramienta runtime.context.exigir("read", "averia") rls=runtime.context.reglas("mantenimiento")
  • exigir usa can de tai-api, la misma regla que requires_permissions.
  • reglas usa rls_for, las mismas reglas de fila que el CRUD generado, las de owner() incluidas. Falla en cerrado: si una regla no se puede aplicar, lanza un error, nunca devuelve una consulta sin filtro.

La regla

Toda herramienta que lea o escriba una tabla:

  1. llama a exigir con la acción y la tabla, antes de tocarla;
  2. pasa rls=runtime.context.reglas(<schema>) a cada consulta del DAO.

Las dos cosas, siempre. exigir no acota las filas, y reglas no comprueba el permiso de la tabla.

Y lo que nunca:

  • leer con un DAO sin rls=: lee lo de todos;
  • filtrar por el dueño a mano (find_many(responsable=runtime.context.username)): es una segunda copia de la regla de rbac/chatbot.py que dejará de coincidir con ella el día que cambie;
  • tomar el usuario de un argumento que rellena el modelo: el modelo escribe lo que le pidan.

Leer el schema del chatbot

La plantilla trae una herramienta de ejemplo que lee las conversaciones del usuario:

agente/herramientas/toolfuncs.py
from api.database.chatbot import ChatAsyncDAO


@tool
async def contar_mis_conversaciones(runtime: ToolRuntime[Contexto]) -> str:
    """Cuántas conversaciones tiene el usuario que pregunta"""
    runtime.context.exigir("read", "chat")
    total = await ChatAsyncDAO.count(visible=True, rls=runtime.context.reglas("chatbot"))
    return f"{runtime.context.username} tiene {total} conversaciones"

owner("chatbot", "chat", "usuario_id", compare_to="user_id") hace que las reglas cuenten solo las suyas, también si pregunta el Administrador.

Leer los datos de la empresa

Lo normal es que el asistente responda sobre otros datos: los de un schema de tai-sql que ya existe en el repositorio, o uno nuevo. El ejemplo de esta página es un schema mantenimiento con máquinas y averías, en el que cada técnico ve las averías de las que es responsable.

1. El schema

En database/schemas/, como cualquier schema de tai-sql:

database/schemas/mantenimiento.py
from __future__ import annotations
from tai_sql import *
from tai_sql.generators import *

datasource(
    provider=env('MAIN_DATABASE_URL'),
    schema='mantenimiento',
    syntax='v2',
    operative_fields=True,
)

generate(PythonClientGenerator(output_dir=['database/database']))


class Maquina(Table):
    """Una máquina de la planta"""
    __tablename__ = "maquina"

    id: col[bigint] = column(primary_key=True, autoincrement=True)
    nombre: col[str] = column(description='Nombre de la máquina')
    linea: col[str] = column(index=True, description='Línea de producción, por ejemplo L2')

    averias: onetomany[Averia]


class Averia(Table):
    """Una avería de una máquina, y quién es responsable de resolverla"""
    __tablename__ = "averia"

    id: col[bigint] = column(primary_key=True, autoincrement=True)
    descripcion: col[str] = column(description='Qué le pasa')
    estado: col[str] = column(default='abierta', index=True, description='abierta, en_curso o cerrada')
    prioridad: col[int] = column(default=3, description='De 1 (urgente) a 5')
    responsable: col[str] = column(index=True, description='El usuario que la atiende')
    coste_eur: col[float | None] = column(description='Lo que costó repararla')
    abierta_en: col[datetime] = column(default=datetime.now)

    maquina_id: col[bigint] = column(description='La máquina averiada')
    maquina: manytoone[Maquina] = relation(fields=['maquina_id'], references=['id'], backref='averias')
tai-chat sql push -s mantenimiento

tai-chat db push solo lleva los schemas del chatbot (auth, chatbot y context): los demás son del repositorio y se llevan con tai-chat sql push.

2. Su cliente en la API

tai-chat api generate -s mantenimiento

tai-api genera el cliente de datos (api.database.mantenimiento: los DAOs y los DTOs), su CRUD (/mantenimiento/...) y sus tipos en el cliente TypeScript, y apunta el schema en el proyecto: los siguientes generate lo regeneran sin pedirlo.

3. Quién puede qué

En api/rbac/chatbot.py: el schema entra en el realm, la avería es de su responsable, y un rol puede leer y abrir averías:

api/rbac/chatbot.py
from rbac.tables.chatbot import (
    ...,
    Maquina, Averia,
)

source(realm_name="chatbot", dbschemas=["chatbot", "mantenimiento"])

owner("chatbot", "chat", "usuario_id", compare_to="user_id")
owner("chatbot", "tokens_mensaje", "usuario_id", compare_to="user_id")
# cada técnico ve las averías de las que es responsable
owner("mantenimiento", "averia", "responsable")

role(
    name="Tecnico",
    description="Chatea, y consulta y abre averías",
    api_permissions=[
        Chat.READ, Mensaje.READ, TokensMensaje.READ,
        Maquina.READ, Averia.READ, Averia.CREATE,
    ],
)
tai-chat api generate               # las constantes Maquina y Averia, en rbac/tables/chatbot
tai-chat api rbac push -r chatbot   # los permisos y el rol, a la base de datos

Ahora un Técnico ve sus averías por el CRUD generado. Lo que sigue es que las vea igual a través del asistente.

4. Las herramientas

agente/herramientas/averias.py
"""Las averías de la planta, leídas como el usuario que pregunta."""
from datetime import date, datetime, time
from typing import Optional

from langchain.tools import ToolRuntime
from langchain_core.tools import ToolException, tool

from api.database.mantenimiento import AveriaAsyncDAO, AveriaCreate, MaquinaAsyncDAO, username_context

from ..contexto import Contexto
from .schemas import BuscarAveriasParams


def _resumen(averia) -> dict:
    """Lo que el modelo necesita de una avería, sin los campos de auditoría."""
    return {
        "id": averia.id,
        "maquina_id": averia.maquina_id,
        "descripcion": averia.descripcion,
        "estado": averia.estado,
        "prioridad": averia.prioridad,
        "abierta_en": averia.abierta_en.date().isoformat(),
    }


@tool(args_schema=BuscarAveriasParams)
async def buscar_averias(
    runtime: ToolRuntime[Contexto],
    estado: str = "abierta",
    linea: Optional[str] = None,
    desde: Optional[date] = None,
    limite: int = 20,
) -> dict:
    """Busca averías por estado, línea y fecha. Devuelve un resumen de cada una: para el
    detalle completo de una avería, usa detalle_averia con su id."""
    contexto = runtime.context
    contexto.exigir("read", "averia")

    filtros = {"estado": estado}
    if desde:
        filtros["min_abierta_en"] = datetime.combine(desde, time.min)
    if linea:
        # la línea es de la máquina: primero las máquinas de esa línea, con sus propias reglas
        contexto.exigir("read", "maquina")
        maquinas = await MaquinaAsyncDAO.find_many(linea=linea, rls=contexto.reglas("mantenimiento"))
        filtros["in_maquina_id"] = [m.id for m in maquinas] or [-1]

    reglas = contexto.reglas("mantenimiento")
    total = await AveriaAsyncDAO.count(**filtros, rls=reglas)
    averias = await AveriaAsyncDAO.find_many(
        **filtros, rls=reglas, limit=limite, order_by=["abierta_en"], order="DESC",
    )
    return {"total": total, "devueltas": len(averias), "averias": [_resumen(a) for a in averias]}


@tool
async def detalle_averia(averia_id: int, runtime: ToolRuntime[Contexto]) -> dict:
    """El detalle completo de una avería: la máquina, su línea, la prioridad y el coste."""
    contexto = runtime.context
    contexto.exigir("read", "averia")
    averia = await AveriaAsyncDAO.find(
        averia_id, includes=["maquina"], rls=contexto.reglas("mantenimiento"),
    )
    if averia is None:
        # la de otro tampoco existe: el mismo mensaje, para no confirmar que existe
        raise ToolException(f"No hay ninguna avería con el id {averia_id}")
    return {
        **_resumen(averia),
        "maquina": averia.maquina.nombre,
        "linea": averia.maquina.linea,
        "responsable": averia.responsable,
        "coste_eur": averia.coste_eur,
    }

detalle_averia.handle_tool_error = True


@tool
async def historial_maquina(maquina_id: int, runtime: ToolRuntime[Contexto]) -> dict:
    """Las averías cerradas de una máquina, con su coste: para ver si falla siempre de lo mismo."""
    contexto = runtime.context
    contexto.exigir("read", "averia")
    averias = await AveriaAsyncDAO.find_many(
        maquina_id=maquina_id, estado="cerrada", rls=contexto.reglas("mantenimiento"),
        limit=50, order_by=["abierta_en"], order="DESC",
    )
    return {
        "maquina_id": maquina_id,
        "cerradas": len(averias),
        "coste_total_eur": round(sum(a.coste_eur or 0 for a in averias), 2),
        "averias": [_resumen(a) for a in averias],
    }

BuscarAveriasParams es el modelo de Pydantic de Herramientas. Y en la lista:

agente/herramientas/__init__.py
from .toolfuncs import *
from .averias import buscar_averias, detalle_averia, historial_maquina

tools = [
    contar_mis_conversaciones,
    buscar_averias,
    detalle_averia,
    historial_maquina,
]

Lo que pasa

Con dos averías abiertas de Ana y dos de Luis, cuando cada uno pregunta «¿qué averías tengo abiertas?»:

Quién Qué pide el modelo Qué devuelve la herramienta
Ana (Técnico) buscar_averias(linea="L1") {"total": 1, ...}: la suya de la L1, no la de Luis en la misma máquina
Luis buscar_averias() {"total": 2, ...}: las dos suyas
Ana detalle_averia(averia_id=3), que es de Luis «No hay ninguna avería con el id 3», como si no existiera
Un usuario sin averia-read buscar_averias() «No tienes permiso para read en averia», y el modelo se lo explica

Y si un jefe de planta tiene que verlas todas, se declara en el owner() — owner("mantenimiento", "averia", "responsable", exempt=["averia-admin"]) y su rol con Averia.ADMIN— sin cambiar una línea de las herramientas. Las herramientas no saben quién ve qué: se lo preguntan a tai-api.

Varias tablas, varias reglas

Cada tabla tiene sus permisos y sus reglas. En buscar_averias, filtrar por línea obliga a leer maquina: por eso pide su permiso y pasa las reglas también a esa consulta. Una herramienta que lee tres tablas exige tres permisos y pasa las reglas a las tres consultas.

reglas(schema) devuelve las reglas de todas las tablas del schema, y el DAO aplica las de la suya: se puede pedir una vez y pasarla a varias consultas del mismo schema.

Escribir

Una herramienta también puede escribir. Con más cuidado: el modelo puede pedirla por error, o porque alguien se lo pida con malas intenciones.

agente/herramientas/averias.py
@tool(parse_docstring=True)
async def abrir_averia(maquina_id: int, descripcion: str, prioridad: int, runtime: ToolRuntime[Contexto]) -> dict:
    """Abre una avería en una máquina, con el usuario como responsable. Antes de usarla,
    confirma con el usuario la máquina, la descripción y la prioridad.

    Args:
        maquina_id: La máquina averiada.
        descripcion: Qué le pasa, en una frase.
        prioridad: De 1 (urgente) a 5.
    """
    contexto = runtime.context
    contexto.exigir("create", "averia")
    # la máquina, si el usuario la puede ver: no se abre una avería en una que no existe para él
    contexto.exigir("read", "maquina")
    if await MaquinaAsyncDAO.find(maquina_id, rls=contexto.reglas("mantenimiento")) is None:
        raise ToolException(f"No hay ninguna máquina con el id {maquina_id}")

    # username_context: created_by y updated_by de la fila, como si la escribiera él por la API
    with username_context(contexto.username):
        averia = await AveriaAsyncDAO.create(AveriaCreate(
            maquina_id=maquina_id,
            descripcion=descripcion,
            prioridad=prioridad,
            responsable=contexto.username,
        ))
    return _resumen(averia)

abrir_averia.handle_tool_error = True
  • El permiso de la acción: exigir("create", "averia"). Un Usuario, sin averia-create, recibe «No tienes permiso para create en averia».
  • Lo que referencia, también acotado: no se abre una avería en una máquina que el usuario no ve.
  • El dueño, del token: responsable=contexto.username, nunca de un argumento.
  • La auditoría: dentro de username_context, la fila queda con created_by del usuario.
  • Confirmar antes: la descripción le pide al modelo que confirme con el usuario. Es una instrucción, no una garantía: lo que de verdad limita qué puede escribir el asistente son los permisos del usuario.

Para modificar, update(..., rls=reglas): las reglas acotan la escritura igual que la lectura, y una fila que no es del usuario no se toca.

Probar el aislamiento

La forma de saber que una herramienta lee como el usuario es preguntar con dos usuarios distintos y comparar con lo que ve cada uno por la API:

curl -s localhost:8000/mantenimiento/averia -H "Authorization: Bearer $TOKEN_ANA"

Si la herramienta devuelve algo que ese curl no devuelve, le falta rls= en alguna consulta.