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") |
exigirusacande tai-api, la misma regla querequires_permissions.reglasusarls_for, las mismas reglas de fila que el CRUD generado, las deowner()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:
- llama a
exigircon la acción y la tabla, antes de tocarla; - 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 derbac/chatbot.pyque 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:
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:
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 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-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:
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¶
"""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:
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.
@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, sinaveria-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 concreated_bydel 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:
Si la herramienta devuelve algo que ese curl no devuelve, le falta rls= en alguna consulta.