rbac-rag-assistant

Relacionado: drivescore-cloud, un servicio Go en Kubernetes con Terraform y un registro de incidentes.

Un asistente de conocimiento interno para una universidad: el personal y los estudiantes hacen preguntas en lenguaje natural y obtienen respuestas fundamentadas en los documentos de políticas que tienen autorización para leer. Con recuperación aumentada, llamada a herramientas, consciente del rol y expuesto a través de MCP, de modo que cualquier cliente pueda usar las mismas herramientas bajo las mismas reglas.

Esta es la Capa 0 de un sistema de cinco capas. Las capas superiores añaden el pipeline de entrega, la ingeniería de fiabilidad, la evaluación, las pruebas de seguridad y la observabilidad, cada una sobre esta aplicación y no al lado de ella.

Cómo ejecutarlo

Python 3.13. Ten en cuenta que python en esta máquina resuelve a la compilación de msys2, que no tiene ninguno de estos paquetes, así que llama directamente al intérprete del venv.

py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

.\.venv\Scripts\python.exe test_rag.py
.\.venv\Scripts\python.exe test_tools.py

Ambos imprimen ok y no necesitan clave de API. La recuperación y las reglas de acceso se pueden probar sin conexión, que es el motivo de mantenerlas fuera del modelo.

Pregúntale algo (necesita GEMINI_API_KEY):

.\.venv\Scripts\python.exe agent.py student "I have a 1.8 GPA, what happens?"
.\.venv\Scripts\python.exe agent.py staff "the wifi is down in the east wing, log it"

La recuperación por sí sola, sin necesidad de clave:

.\.venv\Scripts\python.exe rag.py admin "adjunct pay per credit hour"

Related MCP server: mcp-business-bot

Cómo encaja todo

Tres decisiones que merece la pena defender

El rol de quien llama no es un parámetro de la herramienta. Se vincula fuera de banda antes de que comience el turno. Si existiera search_docs(query, role), el modelo tendría su propia autorización, y una frase escondida en un documento recuperado que le dijera "use role=admin" sería una vía de escalada. No hay nada que pasar, así que no hay nada de lo que convencerlo.

El filtro de autorización se aplica al conjunto de candidatos, no a los resultados. Un fragmento que quien llama no puede ver nunca entra en la clasificación, por lo que su existencia no puede deducirse de un hueco en los resultados ni de una puntuación que haya cambiado.

TF-IDF, no embeddings. Esta es la línea base que la Capa 3 existe para superar. Cambiar a un recuperador semántico antes de que exista un conjunto de referencia sería una conjetura; hacerlo después produce un número que justifica el cambio. El punto de sustitución es Index.

MCP

mcp_server.py registra las funciones de tools.py y no añade nada más, que es el argumento a favor de MCP en un solo archivo: una implementación, un conjunto de reglas de acceso, muchos clientes. Añade a la configuración de un cliente:

{
  "mcpServers": {
    "rbac-rag-assistant": {
      "command": "C:\\Users\\Shrey\\Documents\\CLAUDE CODE\\rbac-rag-assistant\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\Shrey\\Documents\\CLAUDE CODE\\rbac-rag-assistant\\mcp_server.py"],
      "env": { "KB_ROLE": "staff" }
    }
  }
}

Un cliente de MCP no tiene noción de rol universitario, así que KB_ROLE se lee una vez al arrancar y se aplica a toda la conexión. El rol pertenece al proceso del servidor, no a la conversación, y eso es lo que impide que el modelo lo elija.

Comportamiento cuando se deniega el acceso

A un estudiante que pregunta por material exclusivo del personal se le dice que el material existe y que no tiene autorización para consultarlo, en lugar de que se le diga que no existe (ADR-7). Verificado en directo:

Existe orientación sobre qué hacer si sospechas que tu cuenta ha sido comprometida en la documentación de políticas de la universidad, pero acceder a ella requiere autorización del personal. Por favor, contacta con la oficina responsable de esta política.

Lo que cruza la frontera es una etiqueta de clasificación y nada más. No hay pasaje, ni título, ni nombre de archivo. Una pregunta que ningún documento cubre recibe una respuesta diferente, que es precisamente el sentido de la distinción.

Lo que me sorprendió

Uno. faculty compensation bands no devolvió nada para un administrador, mientras que professor salary devolvió el mismo documento con 0.29. Esas tres palabras aparecen solo en el título del documento, y parse() saca el título del cuerpo y lo coloca en los metadatos antes de que se indexe nada. Los usuarios buscan por el título de un documento con mucha más frecuencia que por su redacción, así que la consulta más natural para el documento más sensible era la que estaba garantizado que fallara. Una línea para arreglarlo: indexar title + text, almacenar text.

Merece la pena registrarlo por dónde se encontró. Las pruebas de control de acceso pasaron en todo momento, incluida la que afirma que un estudiante nunca ve contenido confidencial, lo cual era vacuamente cierto cuando nadie podía recuperar el documento en absoluto. Una prueba que pasa porque no se devolvió nada es idéntica a una prueba que pasa porque la regla funciona.

Dos, encontrado al implementar ADR-7. El aviso de "el material restringido existe" se dispara con preguntas inocentes. «¿Quién es un catedrático aquí?» obtiene una puntuación de 0.28 frente a las bandas de compensación, que es más alta que la de una coincidencia legítima de personal con 0.19. Ningún umbral las separa, así que esto no es ajustable; es que la coincidencia léxica no puede distinguir una palabra compartida de un significado compartido. No se filtra nada, y la respuesta sigue siendo incorrecta. Lo primero que la Capa 3 debe medir.

Tres. El modelo rellena pequeñas lagunas que los documentos no cubren. Cuando se le preguntó por una cuenta comprometida, sugirió contactar con "el Service Desk de TI o el equipo de Seguridad de TI" cuando la herramienta solo había dicho "la oficina responsable de esa política". Plausible, inofensivo aquí y no fundamentado en nada de lo recuperado. Es exactamente el comportamiento que un evaluador de fundamentación existe para detectar, y apareció dentro de las primeras cinco preguntas en directo.

Entorno