{"id":"back\/lightdata_ai\/01-arquitectura.md#arquitectura-del-agente-logistico","path":"back\/lightdata_ai\/01-arquitectura.md","titulo":"Arquitectura del agente logistico","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","arquitectura","agente","logistico"],"line_start":1,"line_end":2,"contenido":"# Arquitectura del agente logistico"}
{"id":"back\/lightdata_ai\/01-arquitectura.md#objetivo","path":"back\/lightdata_ai\/01-arquitectura.md","titulo":"Arquitectura del agente logistico > Objetivo","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","arquitectura","agente","logistico","objetivo"],"line_start":3,"line_end":23,"contenido":"## Objetivo\n\nLightDatai debe ser un agente logistico para operadores, administradores, clientes y choferes. Tiene que entender los circuitos del sistema y consultar datos vivos antes de responder.\n\nNo se conecta directo desde el navegador a Ollama\/Gemma. El flujo correcto es:\n\n```text\nAppChat \/ modulo UI\n  -> AppApi.iaLogisticaPreguntar()\n  -> POST \/controlador.php { accion:\"ia.logistica.preguntar\", pregunta, contextoUi }\n  -> ControladorIa\n      -> valida sesion\/perfil\n      -> planifica desde la pregunta (global por defecto)\n      -> busca docs relevantes via RAG\n      -> arma Context Pack operativo\n      -> llama Ollama local\n      -> devuelve respuesta + fuentes + acciones sugeridas\n```\n\nRegla de razonamiento: la pregunta del usuario manda. La ventana activa no limita la consulta; solo aporta contexto cuando el usuario dice \"estos\", \"esta pantalla\", \"lo que estoy viendo\", \"filtrados\" o \"seleccionados\". Para datos operativos, el backend planifica y consulta DB antes de pedir redaccion al modelo."}
{"id":"back\/lightdata_ai\/01-arquitectura.md#1-ui","path":"back\/lightdata_ai\/01-arquitectura.md","titulo":"Arquitectura del agente logistico > Capas > 1. UI","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","arquitectura","agente","logistico","capas"],"line_start":26,"line_end":33,"contenido":"### 1. UI\n\n- `base_php\/js\/core\/AppChat.js`: conversacion con Asistente IA.\n- `base_php\/js\/core\/AppApi.js`: metodo `iaLogisticaPreguntar`.\n- Modulos abiertos pueden aportar `estado()` y seleccion actual.\n\nLa UI no decide permisos ni consulta DB directa. Solo manda pregunta y contexto visual opcional."}
{"id":"back\/lightdata_ai\/01-arquitectura.md#2-puerta-unica","path":"back\/lightdata_ai\/01-arquitectura.md","titulo":"Arquitectura del agente logistico > Capas > 2. Puerta unica","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","arquitectura","agente","logistico","capas","puerta","unica"],"line_start":34,"line_end":49,"contenido":"### 2. Puerta unica\n\nTodo entra por:\n\n```text\nPOST \/controlador.php\n```\n\nAccion propuesta:\n\n```text\nia.logistica.preguntar\n```\n\nEsto mantiene la auditoria, sesion PHP, hash de sesion y multi-tenant."}
{"id":"back\/lightdata_ai\/01-arquitectura.md#3-backend-ia","path":"back\/lightdata_ai\/01-arquitectura.md","titulo":"Arquitectura del agente logistico > Capas > 3. Backend IA","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","arquitectura","agente","logistico","capas","backend"],"line_start":50,"line_end":69,"contenido":"### 3. Backend IA\n\nArchivo runtime propuesto:\n\n```text\nback\/sistema\/controlador_ia.php\n```\n\nEsta carpeta `back\/lightdata_ai\/` documenta la arquitectura; el controlador ejecutable vive en `back\/sistema\/` para respetar el patron actual de controladores.\n\nResponsabilidades:\n\n- validar pregunta;\n- conocer usuario, perfil y alcance;\n- recuperar documentos relevantes;\n- armar contexto operativo;\n- llamar al modelo local;\n- normalizar la respuesta;\n- devolver acciones sugeridas, no ejecutarlas."}
{"id":"back\/lightdata_ai\/01-arquitectura.md#4-rag-documental","path":"back\/lightdata_ai\/01-arquitectura.md","titulo":"Arquitectura del agente logistico > Capas > 4. RAG documental","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","arquitectura","agente","logistico","capas","documental"],"line_start":70,"line_end":81,"contenido":"### 4. RAG documental\n\nEl agente no tiene que memorizar todos los docs. Debe buscar fragmentos relevantes en:\n\n- `manuales_y_circuitos\/`\n- `docs\/`\n- `docs\/modulos\/`\n- `docs\/DICCIONARIO-DATOS.md`\n- `docs\/CIRCUITOS-MS.md`\n- `docs\/MODELO-DATOS.md`\n- esta carpeta `back\/lightdata_ai\/`"}
{"id":"back\/lightdata_ai\/01-arquitectura.md#5-datos-vivos","path":"back\/lightdata_ai\/01-arquitectura.md","titulo":"Arquitectura del agente logistico > Capas > 5. Datos vivos","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","arquitectura","agente","logistico","capas","datos","vivos"],"line_start":82,"line_end":93,"contenido":"### 5. Datos vivos\n\nEl agente usa MySQL\/Redis\/MS segun intencion:\n\n- envio puntual: `ControladorEnvios::obtener`;\n- listado\/riesgo: `ControladorEnvios::listar`;\n- dashboard: `ControladorInformes::dashboard`;\n- zonas\/clientes\/choferes: catalogos;\n- GPS\/presencia: Redis\/WS;\n- health: `ControladorHealth`;\n- costos\/liquidaciones: controladores\/procesos existentes."}
{"id":"back\/lightdata_ai\/01-arquitectura.md#6-capacidades-operativas","path":"back\/lightdata_ai\/01-arquitectura.md","titulo":"Arquitectura del agente logistico > Capas > 6. Capacidades operativas","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","arquitectura","agente","logistico","capas","capacidades","operativas"],"line_start":94,"line_end":111,"contenido":"### 6. Capacidades operativas\n\nEl agente no debe razonar con un diccionario de frases. Debe elegir entre capacidades validadas del OS:\n\n- ruta UI (`envios.listado`, `informes.porzonas`, `informes.porcliente`);\n- herramienta disponible (`consultarEnvios`, `consultarInforme`);\n- controlador backend real (`ControladorEnvios`, `ControladorInformes`);\n- tablas fuente (`envios`, `envios_zonas`, `estados_envios`, etc.);\n- dimensiones y metricas que puede agrupar.\n\nEl catalogo runtime vive en:\n\n```text\nback\/lightdata_ai\/capacidades.php\n```\n\nEjemplo: si el usuario pregunta \"pendientes por zonas\", el agente debe elegir `informes.porzonas`, no tratar \"zona\" como texto libre ni inventar una zona. La respuesta se arma con `ControladorInformes::envios(['por' => 'zona'])` y estados reales de `estados_envios`."}
{"id":"back\/lightdata_ai\/01-arquitectura.md#7-conocimiento-operativo","path":"back\/lightdata_ai\/01-arquitectura.md","titulo":"Arquitectura del agente logistico > Capas > 7. Conocimiento operativo","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","arquitectura","agente","logistico","capas","conocimiento","operativo"],"line_start":112,"line_end":139,"contenido":"### 7. Conocimiento operativo\n\nAntes de elegir una capacidad, el agente necesita entender el circuito y el modelo de datos:\n\n- `envios.estado` es el estado actual;\n- `estados_envios` traduce el DID de estado;\n- `envios_historial` explica cambios y fecha de estado;\n- `envios_direcciones_destino.didEnvioZona` relaciona un envio con `envios_zonas`;\n- `clientes.nombre_fantasia` es el nombre operacional del cliente;\n- `pendientes` no es un texto: es una regla sobre estados no cerrados.\n\nEl conocimiento runtime vive en:\n\n```text\nback\/lightdata_ai\/conocimiento.php\n```\n\nFlujo correcto:\n\n```text\nlenguaje natural\n  -> conocimiento operativo: tablas, campos, relaciones, estados, circuitos\n  -> capacidad\/herramienta validada\n  -> controlador backend real\n  -> respuesta con datos vivos\n  -> accion UI opcional\n```"}
{"id":"back\/lightdata_ai\/01-arquitectura.md#principios","path":"back\/lightdata_ai\/01-arquitectura.md","titulo":"Arquitectura del agente logistico > Principios","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","arquitectura","agente","logistico","principios"],"line_start":140,"line_end":148,"contenido":"## Principios\n\n- El agente responde solo con fuentes recuperadas o datos consultados.\n- Si falta informacion, debe decirlo.\n- Las consultas respetan permisos del perfil.\n- Las respuestas deben ser breves, operativas y accionables.\n- Las acciones reales requieren confirmacion y backend server-side.\n- El contexto enviado al modelo debe ser chico y explicable."}
{"id":"back\/lightdata_ai\/01-arquitectura.md#flujo-de-una-pregunta","path":"back\/lightdata_ai\/01-arquitectura.md","titulo":"Arquitectura del agente logistico > Flujo de una pregunta","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","arquitectura","agente","logistico","flujo","pregunta"],"line_start":149,"line_end":164,"contenido":"## Flujo de una pregunta\n\nEjemplo:\n\n```text\n\"por que no se liquido el envio SEED-CABA-015?\"\n```\n\n1. Detectar intencion: `explicar_liquidacion` + tracking.\n2. Buscar envio por tracking.\n3. Traer cabecera, historial, costos, liquidaciones y cliente.\n4. Recuperar docs de liquidaciones, costos y estados pagables.\n5. Armar contexto.\n6. Llamar modelo.\n7. Responder con causa probable, evidencia y accion sugerida."}
{"id":"back\/lightdata_ai\/01-arquitectura.md#salida-esperada","path":"back\/lightdata_ai\/01-arquitectura.md","titulo":"Arquitectura del agente logistico > Salida esperada","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","arquitectura","agente","logistico","salida","esperada"],"line_start":165,"line_end":183,"contenido":"## Salida esperada\n\n```json\n{\n  \"respuesta\": \"El envio no se liquido porque el movimiento del chofer todavia figura con precioProcesado=0...\",\n  \"intencion\": \"explicar_liquidacion\",\n  \"fuentes\": [\n    { \"tipo\": \"db\", \"nombre\": \"envios\", \"did\": 123 },\n    { \"tipo\": \"doc\", \"path\": \"docs\/DICCIONARIO-DATOS.md\" }\n  ],\n  \"acciones\": [\n    {\n      \"tipo\": \"abrir_modulo\",\n      \"label\": \"Abrir ficha del envio\",\n      \"payload\": { \"ruta\": \"envios.ficha\", \"opts\": { \"did\": 123 } }\n    }\n  ]\n}\n```"}
{"id":"back\/lightdata_ai\/02-rag-documental.md#que-es-rag","path":"back\/lightdata_ai\/02-rag-documental.md","titulo":"RAG documental > Que es RAG","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","documental"],"line_start":3,"line_end":17,"contenido":"## Que es RAG\n\nRAG significa `Retrieval-Augmented Generation`: generacion aumentada con busqueda.\n\nEn Lightdata:\n\n```text\nUsuario pregunta\n  -> el backend busca docs\/circuitos\/tablas relevantes\n  -> arma contexto corto\n  -> el modelo responde con ese contexto\n```\n\nEl modelo no debe tener todos los manuales pegados en cada prompt. Debe recibir solo los fragmentos necesarios."}
{"id":"back\/lightdata_ai\/02-rag-documental.md#por-que-lo-necesitamos","path":"back\/lightdata_ai\/02-rag-documental.md","titulo":"RAG documental > Por que lo necesitamos","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","documental","necesitamos"],"line_start":18,"line_end":32,"contenido":"## Por que lo necesitamos\n\nEl agente tiene que entender:\n\n- circuitos end-to-end;\n- significado de estados;\n- tablas y relaciones;\n- permisos por perfil;\n- procesos batch;\n- microservicios;\n- reglas de costos y liquidaciones;\n- que modulo abrir para cada tarea.\n\nEse conocimiento es estable, cambia con el codigo y debe venir de documentos versionados."}
{"id":"back\/lightdata_ai\/02-rag-documental.md#corpus-inicial","path":"back\/lightdata_ai\/02-rag-documental.md","titulo":"RAG documental > Corpus inicial","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","documental","corpus","inicial"],"line_start":33,"line_end":57,"contenido":"## Corpus inicial\n\nIndexar estos archivos:\n\n```text\nmanuales_y_circuitos\/*.md\ndocs\/*.md\ndocs\/modulos\/*.md\nprocesos\/*.md\nMS\/README.md\nback\/lightdata_ai\/*.md\n```\n\nPrioridad alta:\n\n- `manuales_y_circuitos\/02-circuitos-end-to-end.md`\n- `manuales_y_circuitos\/03-manual-tecnico-desarrollo.md`\n- `manuales_y_circuitos\/04-estado-modulos.md`\n- `manuales_y_circuitos\/06-microservicios-y-procesos.md`\n- `manuales_y_circuitos\/07-agente-logistico-ia.md`\n- `manuales_y_circuitos\/08-redis-cache-operativo.md`\n- `docs\/DICCIONARIO-DATOS.md`\n- `docs\/CIRCUITOS-MS.md`\n- `docs\/MODELO-DATOS.md`"}
{"id":"back\/lightdata_ai\/02-rag-documental.md#chunking","path":"back\/lightdata_ai\/02-rag-documental.md","titulo":"RAG documental > Chunking","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","documental","chunking"],"line_start":58,"line_end":77,"contenido":"## Chunking\n\nPartir documentos por seccion Markdown:\n\n```text\ntitulo h1\nsubtitulo h2\/h3\ncontenido\npath\nline_start\nline_end\ntags\n```\n\nTamanio recomendado:\n\n- 400 a 900 tokens por chunk;\n- solapamiento bajo, 50 a 100 tokens;\n- conservar encabezados para contexto."}
{"id":"back\/lightdata_ai\/02-rag-documental.md#metadata","path":"back\/lightdata_ai\/02-rag-documental.md","titulo":"RAG documental > Metadata","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","documental","metadata"],"line_start":78,"line_end":94,"contenido":"## Metadata\n\nCada chunk debe tener:\n\n```json\n{\n  \"id\": \"docs\/DICCIONARIO-DATOS.md#envios_historial\",\n  \"path\": \"docs\/DICCIONARIO-DATOS.md\",\n  \"titulo\": \"envios_historial\",\n  \"dominio\": \"envios\",\n  \"tipo\": \"diccionario\",\n  \"tags\": [\"envios\", \"historial\", \"estado\", \"precioProcesado\"],\n  \"line_start\": 120,\n  \"line_end\": 155\n}\n```"}
{"id":"back\/lightdata_ai\/02-rag-documental.md#busqueda","path":"back\/lightdata_ai\/02-rag-documental.md","titulo":"RAG documental > Busqueda","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","documental","busqueda"],"line_start":95,"line_end":110,"contenido":"## Busqueda\n\nPrimera version simple:\n\n- busqueda textual BM25\/LIKE sobre indice local;\n- tags manuales por path\/seccion;\n- ranking por coincidencias de dominio.\n\nVersion mejor:\n\n- embeddings locales;\n- vector store en Redis\/SQLite\/Postgres;\n- reranking con reglas por modulo\/intencion.\n\nComo ya existe Gemma\/Ollama local, una alternativa practica es usar embeddings locales con Ollama si el modelo de embeddings esta disponible. Si no, arrancar con busqueda textual."}
{"id":"back\/lightdata_ai\/02-rag-documental.md#pipeline-recomendado","path":"back\/lightdata_ai\/02-rag-documental.md","titulo":"RAG documental > Pipeline recomendado","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","documental","pipeline","recomendado"],"line_start":111,"line_end":122,"contenido":"## Pipeline recomendado\n\n```text\npregunta\n  -> detectar dominio\/intencion\n  -> buscar 5-12 chunks relevantes\n  -> filtrar por score y dominio\n  -> compactar a \"contexto_documental\"\n  -> combinar con \"contexto_operativo\"\n  -> llamar modelo\n```"}
{"id":"back\/lightdata_ai\/02-rag-documental.md#ejemplos","path":"back\/lightdata_ai\/02-rag-documental.md","titulo":"RAG documental > Ejemplos","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","documental","ejemplos"],"line_start":123,"line_end":151,"contenido":"## Ejemplos\n\nPregunta:\n\n```text\n\"por que no se calculo el costo del chofer?\"\n```\n\nDocs a recuperar:\n\n- proceso chofer lista de precios;\n- `envios_historial.precioProcesado`;\n- `costos_envios`;\n- `sistema_usuarios.lista_de_precios`;\n- `sistema_usuarios_accesos.estados_precio`.\n\nPregunta:\n\n```text\n\"como se actualiza el informe por zona?\"\n```\n\nDocs a recuperar:\n\n- `docs\/CIRCUITOS-MS.md`;\n- `MS\/README.md`;\n- `ControladorInformes`;\n- Redis\/cache operativo si pregunta por performance."}
{"id":"back\/lightdata_ai\/02-rag-documental.md#prompt-documental","path":"back\/lightdata_ai\/02-rag-documental.md","titulo":"RAG documental > Prompt documental","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","documental","prompt"],"line_start":152,"line_end":166,"contenido":"## Prompt documental\n\nEl backend debe pasar algo asi:\n\n```text\nCONTEXTO_DOCUMENTAL:\n[1] docs\/DICCIONARIO-DATOS.md#envios_historial\nenvios_historial guarda un movimiento por cambio de estado...\n\n[2] procesos\/README.md#proceso_chofer_listaprecios\nEl proceso usa precioProcesado=0...\n```\n\nEl modelo debe citar o nombrar las fuentes si la respuesta depende de ellas."}
{"id":"back\/lightdata_ai\/02-rag-documental.md#ingestion","path":"back\/lightdata_ai\/02-rag-documental.md","titulo":"RAG documental > Ingestion","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","documental","ingestion"],"line_start":167,"line_end":182,"contenido":"## Ingestion\n\nComando futuro sugerido:\n\n```text\nphp back\/lightdata_ai\/scripts\/index_docs.php\n```\n\nSalida:\n\n```text\nback\/lightdata_ai\/index\/docs_index.jsonl\n```\n\nNo hace falta resolver embeddings en la primera version. Lo importante es tener el contrato y los chunks."}
{"id":"back\/lightdata_ai\/03-contexto-operativo.md#contexto-operativo","path":"back\/lightdata_ai\/03-contexto-operativo.md","titulo":"Contexto operativo","dominio":"general","tipo":"arquitectura_ia","tags":["general","contexto","operativo"],"line_start":1,"line_end":2,"contenido":"# Contexto operativo"}
{"id":"back\/lightdata_ai\/03-contexto-operativo.md#objetivo","path":"back\/lightdata_ai\/03-contexto-operativo.md","titulo":"Contexto operativo > Objetivo","dominio":"general","tipo":"arquitectura_ia","tags":["general","contexto","operativo","objetivo"],"line_start":3,"line_end":6,"contenido":"## Objetivo\n\nEl contexto operativo es el JSON vivo que se arma para cada pregunta. Debe incluir solo los datos necesarios, respetando permisos y evitando mandar tablas completas al modelo."}
{"id":"back\/lightdata_ai\/03-contexto-operativo.md#estructura-base","path":"back\/lightdata_ai\/03-contexto-operativo.md","titulo":"Contexto operativo > Estructura base","dominio":"general","tipo":"arquitectura_ia","tags":["general","contexto","operativo","estructura","base"],"line_start":7,"line_end":35,"contenido":"## Estructura base\n\n```json\n{\n  \"tenant\": {\n    \"did\": 1,\n    \"nombre\": \"Demo Lightdata\",\n    \"fechaSistema\": \"2026-06-08\",\n    \"timezone\": \"America\/Buenos_Aires\"\n  },\n  \"usuario\": {\n    \"did\": 22,\n    \"perfil\": \"adm\",\n    \"tipo\": \"adm\",\n    \"alcance\": \"tenant\"\n  },\n  \"ui\": {\n    \"modulo\": \"envios.listado\",\n    \"filtros\": {},\n    \"seleccion\": [],\n    \"vista\": {}\n  },\n  \"intencion\": \"analisis_envios\",\n  \"catalogos\": {},\n  \"operacion\": {},\n  \"documentos\": []\n}\n```"}
{"id":"back\/lightdata_ai\/03-contexto-operativo.md#contexto-ui","path":"back\/lightdata_ai\/03-contexto-operativo.md","titulo":"Contexto operativo > Contexto UI","dominio":"general","tipo":"arquitectura_ia","tags":["general","contexto","operativo"],"line_start":36,"line_end":59,"contenido":"## Contexto UI\n\nEl front puede mandar:\n\n```json\n{\n  \"modulo\": \"envios.listado\",\n  \"filtros\": {\n    \"tipoFecha\": \"estado\",\n    \"desde\": \"2026-06-08\",\n    \"hasta\": \"2026-06-08\",\n    \"estados\": [3,4]\n  },\n  \"seleccion\": [123,124],\n  \"vista\": {\n    \"page\": 1,\n    \"perPage\": 50,\n    \"sort\": { \"col\": \"fechaEstado\", \"dir\": \"desc\" }\n  }\n}\n```\n\nEl backend debe tratar esto como sugerencia, no como permiso."}
{"id":"back\/lightdata_ai\/03-contexto-operativo.md#intenciones-y-datos","path":"back\/lightdata_ai\/03-contexto-operativo.md","titulo":"Contexto operativo > Intenciones y datos","dominio":"general","tipo":"arquitectura_ia","tags":["general","contexto","operativo","intenciones","datos"],"line_start":60,"line_end":71,"contenido":"## Intenciones y datos\n\n| Intencion | Datos vivos |\n|---|---|\n| `tracking` | envio exacto, historial, observaciones, asignaciones |\n| `analisis_envios` | resumen, muestra filtrada, riesgos |\n| `ruteo` | choferes, zonas, envios asignables, GPS si aplica |\n| `cobranzas` | envios cobrables, liquidaciones, costos |\n| `dashboard` | agregados por estado\/zona\/chofer, health |\n| `ayuda_sistema` | documentos RAG, modulo activo |\n| `explicar_liquidacion` | envio, historial, costos, estados pagables, liquidaciones |"}
{"id":"back\/lightdata_ai\/03-contexto-operativo.md#datos-minimos-por-envio","path":"back\/lightdata_ai\/03-contexto-operativo.md","titulo":"Contexto operativo > Datos minimos por envio","dominio":"envios","tipo":"arquitectura_ia","tags":["envios","contexto","operativo","datos","minimos","envio"],"line_start":72,"line_end":100,"contenido":"## Datos minimos por envio\n\n```json\n{\n  \"did\": 123,\n  \"tracking\": \"SEED-CABA-015\",\n  \"cliente\": \"Deco Hogar\",\n  \"origen\": \"Directo\",\n  \"estado\": 3,\n  \"estadoNombre\": \"En planta de procesamiento\",\n  \"fechaVenta\": \"2026-06-06\",\n  \"fechaEstado\": \"2026-06-06 10:17\",\n  \"destino\": {\n    \"nombre\": \"Lucia Ruiz\",\n    \"cp\": \"1431\",\n    \"localidad\": \"CABA\",\n    \"zona\": \"CABA\"\n  },\n  \"chofer\": \"\",\n  \"flags\": {\n    \"sinChofer\": true,\n    \"sinZona\": false,\n    \"demorado\": true,\n    \"cobranza\": false,\n    \"logisticaInversa\": false\n  }\n}\n```"}
{"id":"back\/lightdata_ai\/03-contexto-operativo.md#resumen-operativo","path":"back\/lightdata_ai\/03-contexto-operativo.md","titulo":"Contexto operativo > Resumen operativo","dominio":"general","tipo":"arquitectura_ia","tags":["general","contexto","operativo","resumen"],"line_start":101,"line_end":121,"contenido":"## Resumen operativo\n\n```json\n{\n  \"totalEnvios\": 82,\n  \"porEstado\": {\n    \"2\": 9,\n    \"3\": 14,\n    \"5\": 21\n  },\n  \"riesgos\": {\n    \"sinChofer\": 8,\n    \"sinZona\": 3,\n    \"demorados\": 12,\n    \"conCobranza\": 5\n  },\n  \"porZona\": [],\n  \"porChofer\": []\n}\n```"}
{"id":"back\/lightdata_ai\/03-contexto-operativo.md#permisos","path":"back\/lightdata_ai\/03-contexto-operativo.md","titulo":"Contexto operativo > Permisos","dominio":"general","tipo":"arquitectura_ia","tags":["general","contexto","operativo","permisos"],"line_start":122,"line_end":132,"contenido":"## Permisos\n\nRespetar los controladores existentes:\n\n- perfil chofer\/logistica externa: solo envios asignados;\n- perfil cliente: solo clientes vinculados;\n- admin\/coordinador: segun permisos del sistema;\n- nunca mandar datos de otros tenants.\n\nLa seguridad real vive en backend. La UI no filtra como garantia."}
{"id":"back\/lightdata_ai\/03-contexto-operativo.md#limites","path":"back\/lightdata_ai\/03-contexto-operativo.md","titulo":"Contexto operativo > Limites","dominio":"general","tipo":"arquitectura_ia","tags":["general","contexto","operativo","limites"],"line_start":133,"line_end":140,"contenido":"## Limites\n\n- muestra de envios: 25 a 60 maximo;\n- historial por envio: ultimos 20 movimientos;\n- docs RAG: 5 a 12 chunks;\n- contexto IA cacheable: 60 a 180 segundos;\n- no mandar payloads de integraciones salvo intencion especifica."}
{"id":"back\/lightdata_ai\/03-contexto-operativo.md#datos-sensibles","path":"back\/lightdata_ai\/03-contexto-operativo.md","titulo":"Contexto operativo > Datos sensibles","dominio":"general","tipo":"arquitectura_ia","tags":["general","contexto","operativo","datos","sensibles"],"line_start":141,"line_end":154,"contenido":"## Datos sensibles\n\nPor defecto excluir:\n\n- telefonos;\n- emails;\n- tokens;\n- direcciones completas;\n- payloads `dataCuenta`;\n- valores de credenciales;\n- logs crudos.\n\nIncluirlos solo si la pregunta lo requiere y el perfil puede verlos."}
{"id":"back\/lightdata_ai\/03-contexto-operativo.md#fuentes","path":"back\/lightdata_ai\/03-contexto-operativo.md","titulo":"Contexto operativo > Fuentes","dominio":"general","tipo":"arquitectura_ia","tags":["general","contexto","operativo","fuentes"],"line_start":155,"line_end":166,"contenido":"## Fuentes\n\nToda respuesta deberia poder explicar de donde salio:\n\n```json\n[\n  { \"tipo\": \"db\", \"tabla\": \"envios\", \"did\": 123 },\n  { \"tipo\": \"redis\", \"clave\": \"ops:1:envios:resumen\" },\n  { \"tipo\": \"doc\", \"path\": \"docs\/DICCIONARIO-DATOS.md\", \"titulo\": \"envios_historial\" }\n]\n```"}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#herramientas-del-agente","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","herramientas","agente"],"line_start":1,"line_end":2,"contenido":"# Herramientas del agente"}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#objetivo","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Objetivo","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","herramientas","agente","objetivo"],"line_start":3,"line_end":6,"contenido":"## Objetivo\n\nEl agente no debe depender solo de texto. Debe poder pedir herramientas controladas al backend para consultar datos y preparar acciones."}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#tipos-de-herramienta","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Tipos de herramienta","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","herramientas","agente","tipos","herramienta"],"line_start":7,"line_end":8,"contenido":"## Tipos de herramienta"}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#lectura","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Tipos de herramienta > Lectura","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","herramientas","agente","tipos","herramienta","lectura"],"line_start":9,"line_end":25,"contenido":"### Lectura\n\nEstas herramientas consultan y devuelven datos.\n\n```text\nbuscar_envio\nobtener_envio\nlistar_envios_riesgo\nresumen_operacion\nbuscar_cliente\nbuscar_chofer\nconsultar_cobranzas\nconsultar_liquidacion\nconsultar_health\nbuscar_docs\n```"}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#navegacion-ui","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Tipos de herramienta > Navegacion UI","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","herramientas","agente","tipos","herramienta","navegacion"],"line_start":26,"line_end":37,"contenido":"### Navegacion UI\n\nEstas herramientas no cambian datos; preparan botones para la UI.\n\n```text\nabrir_modulo\nabrir_envio\nabrir_cliente\nabrir_informe\naplicar_filtros\n```"}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#preparacion-de-acciones","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Tipos de herramienta > Preparacion de acciones","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","herramientas","agente","tipos","herramienta","preparacion","acciones"],"line_start":38,"line_end":49,"contenido":"### Preparacion de acciones\n\nEstas herramientas preparan payloads. Siempre requieren confirmacion.\n\n```text\npreparar_cambio_estado\npreparar_asignacion_chofer\npreparar_observacion\npreparar_reimpresion\npreparar_reprocesar_preenvio\n```"}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#contrato-general","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Contrato general","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","herramientas","agente","contrato","general"],"line_start":50,"line_end":70,"contenido":"## Contrato general\n\n```json\n{\n  \"tool\": \"buscar_envio\",\n  \"args\": {\n    \"tracking\": \"SEED-CABA-015\"\n  }\n}\n```\n\nRespuesta:\n\n```json\n{\n  \"ok\": true,\n  \"data\": {},\n  \"fuentes\": []\n}\n```"}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#herramientas-iniciales","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Herramientas iniciales","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","herramientas","agente","iniciales"],"line_start":71,"line_end":72,"contenido":"## Herramientas iniciales"}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#catalogo-de-capacidades","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Herramientas iniciales > Catalogo de capacidades","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","herramientas","agente","iniciales","catalogo","capacidades"],"line_start":73,"line_end":89,"contenido":"### Catalogo de capacidades\n\nAntes de llamar una herramienta, el agente debe elegir una capacidad validada de:\n\n```text\nback\/lightdata_ai\/capacidades.php\n```\n\nEsto evita diccionarios por frase. Ejemplos:\n\n| Pregunta | Capacidad | Herramienta | Backend |\n|---|---|---|---|\n| pendientes por zonas | `informes.porzonas` | `consultarInforme({tipo:\"zonas\"})` | `ControladorInformes::envios(['por'=>'zona'])` |\n| pendientes por cliente | `informes.porcliente` | `consultarInforme({tipo:\"clientes\"})` | `ControladorInformes::envios(['por'=>'cliente'])` |\n| envios cancelados desde una fecha | `envios.listado` | `consultarEnvios` | `ControladorEnvios::listar\/resumen` |\n| crear ruta por zona para chofer | `ruteate.preparar_asignacion_zona_chofer` | `prepararAsignacionRuta` | `ControladorEnvios` + `sistema_usuarios` + `ruteate.asignacionProcesar` |"}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#conocimiento-operativo-previo","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Herramientas iniciales > Conocimiento operativo previo","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","herramientas","agente","iniciales","conocimiento","operativo","previo"],"line_start":90,"line_end":106,"contenido":"### Conocimiento operativo previo\n\nLas capacidades no alcanzan solas. El agente debe tener contexto de tablas\/campos\/circuitos desde:\n\n```text\nback\/lightdata_ai\/conocimiento.php\n```\n\nEse contexto le dice, por ejemplo:\n\n- estado actual: `envios.estado -> estados_envios.did`;\n- fecha de estado: `MAX(envios_historial.fecha)`;\n- zona de entrega: `envios_direcciones_destino.didEnvioZona -> envios_zonas.did`;\n- informe por zonas: agrupacion de `ControladorInformes::envios(['por'=>'zona'])`;\n- pendientes: estados que no son cerrados segun `estados_envios`.\n- ruta\/asignacion: seleccionar envios ruteables por zona de entrega, resolver chofer operativo y preparar confirmacion; no reasignar envios de otros choferes sin pedido explicito."}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#buscar-envio","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Herramientas iniciales > `buscar_envio`","dominio":"envios","tipo":"arquitectura_ia","tags":["envios","herramientas","agente","iniciales","buscar","envio"],"line_start":107,"line_end":124,"contenido":"### `buscar_envio`\n\nEntrada:\n\n```json\n{ \"tracking\": \"SEED-CABA-015\", \"idVenta\": \"\", \"idPack\": \"\" }\n```\n\nSalida:\n\n```json\n{\n  \"envios\": [\n    { \"did\": 123, \"tracking\": \"SEED-CABA-015\", \"estado\": 3, \"cliente\": \"Deco Hogar\" }\n  ]\n}\n```"}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#obtener-envio","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Herramientas iniciales > `obtener_envio`","dominio":"envios","tipo":"arquitectura_ia","tags":["envios","herramientas","agente","iniciales","obtener","envio"],"line_start":125,"line_end":134,"contenido":"### `obtener_envio`\n\nEntrada:\n\n```json\n{ \"did\": 123 }\n```\n\nUsa `ControladorEnvios::obtener`."}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#resumen-operacion","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Herramientas iniciales > `resumen_operacion`","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","herramientas","agente","iniciales","resumen","operacion"],"line_start":135,"line_end":153,"contenido":"### `resumen_operacion`\n\nEntrada:\n\n```json\n{ \"fecha\": \"2026-06-08\", \"filtros\": {} }\n```\n\nPrimero intenta Redis:\n\n```text\nops:{tenant}:envios:resumen\nops:{tenant}:envios:por_estado\nops:{tenant}:envios:por_zona\nops:{tenant}:envios:por_chofer\n```\n\nSi no hay cache, consulta DB y guarda TTL corto."}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#buscar-docs","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Herramientas iniciales > `buscar_docs`","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","herramientas","agente","iniciales","buscar","docs"],"line_start":154,"line_end":175,"contenido":"### `buscar_docs`\n\nEntrada:\n\n```json\n{ \"query\": \"como se liquida el costo del chofer\", \"tags\": [\"liquidaciones\", \"costos\"] }\n```\n\nSalida:\n\n```json\n{\n  \"chunks\": [\n    {\n      \"path\": \"procesos\/README.md\",\n      \"titulo\": \"proceso_chofer_listaprecios\",\n      \"texto\": \"...\"\n    }\n  ]\n}\n```"}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#acciones-sugeridas-para-ui","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Acciones sugeridas para UI","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","herramientas","agente","acciones","sugeridas","para"],"line_start":176,"line_end":205,"contenido":"## Acciones sugeridas para UI\n\nEl endpoint puede devolver:\n\n```json\n{\n  \"acciones\": [\n    {\n      \"tipo\": \"abrir_modulo\",\n      \"label\": \"Ver envios demorados\",\n      \"payload\": {\n        \"ruta\": \"envios.listado\",\n        \"estado\": {\n          \"filtros\": { \"estados\": [3], \"asignado\": \"0\" }\n        }\n      }\n    },\n    {\n      \"tipo\": \"preparar_cambio_estado\",\n      \"label\": \"Pasar seleccionados a En camino\",\n      \"payload\": {\n        \"dids\": [123,124],\n        \"estado\": 4\n      },\n      \"requiereConfirmacion\": true\n    }\n  ]\n}\n```"}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#reglas-de-seguridad","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Reglas de seguridad","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","herramientas","agente","reglas","seguridad"],"line_start":206,"line_end":213,"contenido":"## Reglas de seguridad\n\n- Ninguna herramienta escribe sin endpoint especifico y confirmacion UI.\n- El backend revalida permisos.\n- No se ejecutan SQL libres generados por el modelo.\n- No se aceptan nombres de tabla\/columna arbitrarios desde el modelo.\n- Las herramientas exponen funciones de dominio, no acceso crudo a DB."}
{"id":"back\/lightdata_ai\/04-herramientas-agente.md#roadmap-de-herramientas","path":"back\/lightdata_ai\/04-herramientas-agente.md","titulo":"Herramientas del agente > Roadmap de herramientas","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","herramientas","agente","roadmap"],"line_start":214,"line_end":234,"contenido":"## Roadmap de herramientas\n\nFase 1:\n\n- `buscar_docs`\n- `buscar_envio`\n- `obtener_envio`\n- `resumen_operacion`\n\nFase 2:\n\n- `listar_envios_riesgo`\n- `buscar_cliente`\n- `buscar_chofer`\n- `consultar_cobranzas`\n\nFase 3:\n\n- acciones preparadas con confirmacion;\n- apertura de modulos con filtros;\n- explicaciones de liquidacion\/costos."}
{"id":"back\/lightdata_ai\/05-redis-y-cache.md#redis-y-cache-para-el-agente","path":"back\/lightdata_ai\/05-redis-y-cache.md","titulo":"Redis y cache para el agente","dominio":"ms","tipo":"arquitectura_ia","tags":["ms","redis","cache","para","agente"],"line_start":1,"line_end":2,"contenido":"# Redis y cache para el agente"}
{"id":"back\/lightdata_ai\/05-redis-y-cache.md#rol-de-redis","path":"back\/lightdata_ai\/05-redis-y-cache.md","titulo":"Redis y cache para el agente > Rol de Redis","dominio":"ms","tipo":"arquitectura_ia","tags":["ms","redis","cache","para","agente"],"line_start":3,"line_end":15,"contenido":"## Rol de Redis\n\nRedis alimenta al agente con estado caliente y evita consultas repetidas cuando el usuario pregunta varias cosas seguidas.\n\nNo reemplaza a MySQL.\n\n```text\nMySQL = verdad\nRedis = cache, estado reciente, locks, sesiones\nRAG = conocimiento estable\nModelo = razonamiento\n```"}
{"id":"back\/lightdata_ai\/05-redis-y-cache.md#claves-que-usa-el-agente","path":"back\/lightdata_ai\/05-redis-y-cache.md","titulo":"Redis y cache para el agente > Claves que usa el agente","dominio":"ms","tipo":"arquitectura_ia","tags":["ms","redis","cache","para","agente","claves"],"line_start":16,"line_end":17,"contenido":"## Claves que usa el agente"}
{"id":"back\/lightdata_ai\/05-redis-y-cache.md#sesion-y-presencia","path":"back\/lightdata_ai\/05-redis-y-cache.md","titulo":"Redis y cache para el agente > Claves que usa el agente > Sesion y presencia","dominio":"ms","tipo":"arquitectura_ia","tags":["ms","redis","cache","para","agente","claves","sesion","presencia"],"line_start":18,"line_end":30,"contenido":"### Sesion y presencia\n\n```text\nrt:session:{tenant}:{uid}:{hash}\nrt:presence:{tenant}\n```\n\nUso:\n\n- validar WS;\n- saber usuarios conectados;\n- responder preguntas como \"que choferes estan online?\"."}
{"id":"back\/lightdata_ai\/05-redis-y-cache.md#gps","path":"back\/lightdata_ai\/05-redis-y-cache.md","titulo":"Redis y cache para el agente > Claves que usa el agente > GPS","dominio":"ruteate","tipo":"arquitectura_ia","tags":["ruteate","redis","cache","para","agente","claves"],"line_start":31,"line_end":42,"contenido":"### GPS\n\n```text\ngeo:last:{tenant}:{chofer}\n```\n\nUso:\n\n- ultimo punto conocido;\n- preguntas de ubicacion;\n- contexto de En Mano\/GeoChoferes."}
{"id":"back\/lightdata_ai\/05-redis-y-cache.md#catalogos","path":"back\/lightdata_ai\/05-redis-y-cache.md","titulo":"Redis y cache para el agente > Claves que usa el agente > Catalogos","dominio":"ms","tipo":"arquitectura_ia","tags":["ms","redis","cache","para","agente","claves","catalogos"],"line_start":43,"line_end":62,"contenido":"### Catalogos\n\n```text\ncat:{tenant}:estados_envios\ncat:{tenant}:clientes\ncat:{tenant}:choferes\ncat:{tenant}:zonas\ncat:{tenant}:depositos\ncat:{tenant}:servicios\ncat:{tenant}:listas\ncat:{tenant}:listaschofer\n```\n\nUso:\n\n- traducir DIDs a nombres;\n- interpretar estados;\n- resolver filtros;\n- armar contexto compacto."}
{"id":"back\/lightdata_ai\/05-redis-y-cache.md#operacion","path":"back\/lightdata_ai\/05-redis-y-cache.md","titulo":"Redis y cache para el agente > Claves que usa el agente > Operacion","dominio":"ms","tipo":"arquitectura_ia","tags":["ms","redis","cache","para","agente","claves","operacion"],"line_start":63,"line_end":79,"contenido":"### Operacion\n\n```text\nops:{tenant}:envios:resumen\nops:{tenant}:envios:por_estado\nops:{tenant}:envios:por_zona\nops:{tenant}:envios:por_chofer\nops:{tenant}:enmano:{fecha}\n```\n\nUso:\n\n- dashboard IA;\n- preguntas generales;\n- alertas de riesgo;\n- contexto rapido."}
{"id":"back\/lightdata_ai\/05-redis-y-cache.md#contexto-ia","path":"back\/lightdata_ai\/05-redis-y-cache.md","titulo":"Redis y cache para el agente > Claves que usa el agente > Contexto IA","dominio":"ms","tipo":"arquitectura_ia","tags":["ms","redis","cache","para","agente","claves","contexto"],"line_start":80,"line_end":93,"contenido":"### Contexto IA\n\n```text\nia:{tenant}:context:logistica:{uid}:{hashCorto}\n```\n\nTTL: 60 a 180 segundos.\n\nUso:\n\n- reutilizar contexto entre preguntas de la misma conversacion;\n- evitar reconstruir catalogos\/resumen constantemente;\n- invalidar cuando cambia filtro, seleccion o evento operativo."}
{"id":"back\/lightdata_ai\/05-redis-y-cache.md#invalidacion","path":"back\/lightdata_ai\/05-redis-y-cache.md","titulo":"Redis y cache para el agente > Invalidacion","dominio":"ms","tipo":"arquitectura_ia","tags":["ms","redis","cache","para","agente","invalidacion"],"line_start":94,"line_end":108,"contenido":"## Invalidacion\n\n| Evento | Claves |\n|---|---|\n| cambio de estado | `ops:{tenant}:envios:*`, `ia:{tenant}:context:logistica:*` |\n| asignacion | `ops:{tenant}:envios:por_chofer`, `ops:{tenant}:enmano:*`, `ia:{tenant}:context:logistica:*` |\n| zona asignada | `ops:{tenant}:envios:por_zona`, `ia:{tenant}:context:logistica:*` |\n| guardar cliente | `cat:{tenant}:clientes` |\n| guardar usuario\/chofer | `cat:{tenant}:choferes`, `rt:presence:{tenant}` |\n| guardar zona | `cat:{tenant}:zonas`, `route:{tenant}:zonas_resolver` |\n| guardar listas | `cat:{tenant}:listas`, `price:{tenant}:cliente:*` |\n| guardar listas chofer | `cat:{tenant}:listaschofer`, `price:{tenant}:chofer:*` |\n\nUsar `SCAN`, no `KEYS`, para borrar patrones en produccion."}
{"id":"back\/lightdata_ai\/05-redis-y-cache.md#cache-aside","path":"back\/lightdata_ai\/05-redis-y-cache.md","titulo":"Redis y cache para el agente > Cache-aside","dominio":"ms","tipo":"arquitectura_ia","tags":["ms","redis","cache","para","agente","aside"],"line_start":109,"line_end":123,"contenido":"## Cache-aside\n\nPatron recomendado:\n\n```text\nleer:\n  GET redis\n  si existe -> usar\n  si no -> DB -> SETEX -> usar\n\nguardar:\n  DB\n  DEL\/SCAN claves afectadas\n```"}
{"id":"back\/lightdata_ai\/05-redis-y-cache.md#no-cachear","path":"back\/lightdata_ai\/05-redis-y-cache.md","titulo":"Redis y cache para el agente > No cachear","dominio":"ms","tipo":"arquitectura_ia","tags":["ms","redis","cache","para","agente","cachear"],"line_start":124,"line_end":133,"contenido":"## No cachear\n\n- listados completos de envios;\n- historial completo;\n- auditoria;\n- liquidaciones finales;\n- costos definitivos;\n- payloads de integraciones;\n- datos sensibles sin TTL corto."}
{"id":"back\/lightdata_ai\/05-redis-y-cache.md#relacion-con-documento-central","path":"back\/lightdata_ai\/05-redis-y-cache.md","titulo":"Redis y cache para el agente > Relacion con documento central","dominio":"ms","tipo":"arquitectura_ia","tags":["ms","redis","cache","para","agente","relacion","documento","central"],"line_start":134,"line_end":143,"contenido":"## Relacion con documento central\n\nVer tambien:\n\n```text\nmanuales_y_circuitos\/08-redis-cache-operativo.md\n```\n\nEse documento define la estrategia global de Redis para todo Lightdata OS. Este archivo baja el uso especifico para el agente."}
{"id":"back\/lightdata_ai\/06-endpoints-contratos.md#endpoints-y-contratos","path":"back\/lightdata_ai\/06-endpoints-contratos.md","titulo":"Endpoints y contratos","dominio":"general","tipo":"arquitectura_ia","tags":["general","endpoints","contratos"],"line_start":1,"line_end":2,"contenido":"# Endpoints y contratos"}
{"id":"back\/lightdata_ai\/06-endpoints-contratos.md#endpoint-principal","path":"back\/lightdata_ai\/06-endpoints-contratos.md","titulo":"Endpoints y contratos > Endpoint principal","dominio":"general","tipo":"arquitectura_ia","tags":["general","endpoints","contratos","endpoint","principal"],"line_start":3,"line_end":76,"contenido":"## Endpoint principal\n\n```http\nPOST \/controlador.php\nContent-Type: application\/json\n```\n\nRequest:\n\n```json\n{\n  \"accion\": \"ia.logistica.preguntar\",\n  \"pregunta\": \"que envios estan demorados hoy?\",\n  \"contextoUi\": {\n    \"modulo\": \"envios.listado\",\n    \"filtros\": {},\n    \"seleccion\": []\n  }\n}\n```\n\n`contextoUi` es opcional para el razonamiento. El agente consulta globalmente por defecto y solo usa la vista activa cuando la pregunta contiene referencias como \"estos\", \"esta pantalla\", \"lo que estoy viendo\", \"filtrados\" o \"seleccionados\".\n\nResponse:\n\n```json\n{\n  \"ok\": true,\n  \"respuesta\": \"Tenes 12 envios con riesgo operativo...\",\n  \"intencion\": \"analisis_envios\",\n  \"fuentes\": [\n    { \"tipo\": \"planner\", \"nombre\": \"global\" },\n    { \"tipo\": \"db\", \"nombre\": \"envios\" }\n  ],\n  \"acciones\": [],\n  \"debug\": {\n    \"modelo\": \"qwen2.5:7b-instruct\",\n    \"plan\": {\n      \"dominio\": \"envios\",\n      \"intencion\": \"conteo_envios\",\n      \"base\": \"global\",\n      \"estado\": { \"did\": 7, \"nombre\": \"A retirar\" }\n    }\n  }\n}\n```\n\nEjemplos esperados:\n\n```text\nUsuario: cuantos envios a retirar tengo?\nRespuesta: Tenes 15 envios en estado A retirar.\n\nUsuario: de 1 semana para atras cuanto tengo a retirar?\nRespuesta: Tenes 15 envios en estado A retirar entre 2026-06-01 y 2026-06-08.\n\nUsuario: cuantos envios tuve?\nRespuesta: Para verlo bien, decime el rango de fechas y si queres contar por fecha de estado, venta o carga.\n\nUsuario: abrime envios filtrado por el cliente mongocho\nRespuesta: Tenes 0 envios.\nAccion: abrir `envios.listado` con `{ \"filtros\": { \"nombre\": \"mongocho\" }, \"page\": 1 }`.\n\nUsuario: decime cuantos pendientes tengo por zonas?\nRespuesta: Tenes 82 envios pendientes por zona: Sin zona: 73, Sur: 7, Norte: 2.\nCapacidad: `informes.porzonas`.\nAccion: abrir `informes.porzonas`.\n\nUsuario: podes crear una ruta para envios de zona sur, para el chofer teta? si no los tiene asignacelos.\nRespuesta: Zona Sur: encontre 7 envios. 0 ya estan asignados a Chofer Teta. 7 estan sin asignar y puedo prepararlos para asignar a Chofer Teta con confirmacion.\nCapacidad: `ruteate.preparar_asignacion_zona_chofer`.\nAcciones: previsualizar `ruteate.rutear` y confirmar `ruteate.asignacionProcesar`.\n```"}
{"id":"back\/lightdata_ai\/06-endpoints-contratos.md#appapi","path":"back\/lightdata_ai\/06-endpoints-contratos.md","titulo":"Endpoints y contratos > AppApi","dominio":"general","tipo":"arquitectura_ia","tags":["general","endpoints","contratos","appapi"],"line_start":77,"line_end":93,"contenido":"## AppApi\n\nMetodo propuesto:\n\n```js\nasync iaLogisticaPreguntar({ pregunta, contextoUi = {} }) {\n  const d = await this._post('ia.logistica.preguntar', { pregunta, contextoUi });\n  return {\n    respuesta: d.respuesta || '',\n    intencion: d.intencion || '',\n    fuentes: d.fuentes || [],\n    acciones: d.acciones || [],\n    debug: d.debug || {},\n  };\n}\n```"}
{"id":"back\/lightdata_ai\/06-endpoints-contratos.md#dispatch-php","path":"back\/lightdata_ai\/06-endpoints-contratos.md","titulo":"Endpoints y contratos > Dispatch PHP","dominio":"general","tipo":"arquitectura_ia","tags":["general","endpoints","contratos","dispatch"],"line_start":94,"line_end":107,"contenido":"## Dispatch PHP\n\nEn `empresa_demo\/controlador.php`:\n\n```php\nif ($modulo === 'ia') {\n    $c = new ControladorIa(db(), (int)$_SESSION['uid']);\n    switch ($metodo) {\n        case 'logistica.preguntar':\n            salir(['ok' => true] + $c->preguntarLogistica($in));\n    }\n}\n```"}
{"id":"back\/lightdata_ai\/06-endpoints-contratos.md#controlador","path":"back\/lightdata_ai\/06-endpoints-contratos.md","titulo":"Endpoints y contratos > Controlador","dominio":"general","tipo":"arquitectura_ia","tags":["general","endpoints","contratos","controlador"],"line_start":108,"line_end":127,"contenido":"## Controlador\n\nArchivo runtime:\n\n```text\nback\/sistema\/controlador_ia.php\n```\n\nMetodos esperados:\n\n```php\nclass ControladorIa\n{\n    public function preguntarLogistica(array $in): array;\n    private function detectarIntencion(string $pregunta, array $ui): string;\n    private function armarContexto(string $intencion, array $ui): array;\n    private function llamarModelo(array $messages): string;\n}\n```"}
{"id":"back\/lightdata_ai\/06-endpoints-contratos.md#ollama","path":"back\/lightdata_ai\/06-endpoints-contratos.md","titulo":"Endpoints y contratos > Ollama","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","endpoints","contratos","ollama"],"line_start":128,"line_end":155,"contenido":"## Ollama\n\nVariables:\n\n```text\nLD_IA_OLLAMA_URL=http:\/\/127.0.0.1:11434\nLD_IA_LOGISTICA_MODELO=qwen2.5:7b-instruct\nLD_IA_TIMEOUT=150\nLD_IA_MAX_ENVIOS=60\n```\n\nRequest a Ollama:\n\n```json\n{\n  \"model\": \"qwen2.5:7b-instruct\",\n  \"stream\": false,\n  \"messages\": [\n    { \"role\": \"system\", \"content\": \"...\" },\n    { \"role\": \"user\", \"content\": \"...\" }\n  ],\n  \"options\": {\n    \"temperature\": 0.2,\n    \"num_ctx\": 8192\n  }\n}\n```"}
{"id":"back\/lightdata_ai\/06-endpoints-contratos.md#prompt-base","path":"back\/lightdata_ai\/06-endpoints-contratos.md","titulo":"Endpoints y contratos > Prompt base","dominio":"general","tipo":"arquitectura_ia","tags":["general","endpoints","contratos","prompt","base"],"line_start":156,"line_end":166,"contenido":"## Prompt base\n\n```text\nSos LightDatai, un agente logistico para operadores de un TMS.\nResponde en espanol claro, breve y accionable.\nUsa solo CONTEXTO_DOCUMENTAL y CONTEXTO_OPERATIVO.\nSi falta un dato, decilo.\nNo inventes tracking, estados, choferes, zonas ni cantidades.\nNo ejecutes cambios. Solo propone acciones para confirmar en UI.\n```"}
{"id":"back\/lightdata_ai\/06-endpoints-contratos.md#errores","path":"back\/lightdata_ai\/06-endpoints-contratos.md","titulo":"Endpoints y contratos > Errores","dominio":"general","tipo":"arquitectura_ia","tags":["general","endpoints","contratos","errores"],"line_start":167,"line_end":199,"contenido":"## Errores\n\nModelo caido:\n\n```json\n{\n  \"ok\": false,\n  \"error\": \"No pude consultar el modelo local\",\n  \"codigo\": \"IA_MODELO_NO_DISPONIBLE\"\n}\n```\n\nPregunta vacia:\n\n```json\n{\n  \"ok\": false,\n  \"error\": \"Falta pregunta\",\n  \"codigo\": \"IA_PREGUNTA_VACIA\"\n}\n```\n\nSin datos:\n\n```json\n{\n  \"ok\": true,\n  \"respuesta\": \"No encontre datos suficientes con los filtros actuales.\",\n  \"intencion\": \"analisis_envios\",\n  \"fuentes\": [],\n  \"acciones\": []\n}\n```"}
{"id":"back\/lightdata_ai\/07-roadmap-implementacion.md#roadmap-de-implementacion","path":"back\/lightdata_ai\/07-roadmap-implementacion.md","titulo":"Roadmap de implementacion","dominio":"general","tipo":"arquitectura_ia","tags":["general","roadmap","implementacion"],"line_start":1,"line_end":2,"contenido":"# Roadmap de implementacion"}
{"id":"back\/lightdata_ai\/07-roadmap-implementacion.md#fase-0-documentacion","path":"back\/lightdata_ai\/07-roadmap-implementacion.md","titulo":"Roadmap de implementacion > Fase 0 - Documentacion","dominio":"general","tipo":"arquitectura_ia","tags":["general","roadmap","implementacion","fase","documentacion"],"line_start":3,"line_end":10,"contenido":"## Fase 0 - Documentacion\n\nEstado: en curso.\n\n- Crear `back\/lightdata_ai\/`.\n- Documentar arquitectura, RAG, contexto, Redis y endpoints.\n- Conectar con manuales existentes."}
{"id":"back\/lightdata_ai\/07-roadmap-implementacion.md#fase-1-endpoint-ia-minimo","path":"back\/lightdata_ai\/07-roadmap-implementacion.md","titulo":"Roadmap de implementacion > Fase 1 - Endpoint IA minimo","dominio":"general","tipo":"arquitectura_ia","tags":["general","roadmap","implementacion","fase","endpoint","minimo"],"line_start":11,"line_end":31,"contenido":"## Fase 1 - Endpoint IA minimo\n\nEstado: implementado base.\n\nObjetivo: que el chat responda usando endpoint propio y modelo local.\n\nTareas:\n\n- [x] Crear `back\/sistema\/controlador_ia.php`.\n- [x] Agregar dispatch `ia.logistica.preguntar`.\n- [x] Agregar `AppApi.iaLogisticaPreguntar`.\n- [x] Modificar `AppChat` para reemplazar respuesta mock de IA.\n- [x] Armar contexto basico: usuario, tenant, modulo activo, filtros.\n- [x] Llamar Ollama `qwen2.5:7b-instruct`.\n\nAceptacion:\n\n- [x] el navegador no llama a `localhost:11434`;\n- [x] la auditoria registra `ia.logistica.preguntar`;\n- [x] si Ollama esta caido, la UI responde con error amable."}
{"id":"back\/lightdata_ai\/07-roadmap-implementacion.md#fase-2-rag-documental-textual","path":"back\/lightdata_ai\/07-roadmap-implementacion.md","titulo":"Roadmap de implementacion > Fase 2 - RAG documental textual","dominio":"ia","tipo":"arquitectura_ia","tags":["ia","roadmap","implementacion","fase","documental","textual"],"line_start":32,"line_end":49,"contenido":"## Fase 2 - RAG documental textual\n\nObjetivo: que el agente entienda circuitos y DB.\n\nTareas:\n\n- Crear index JSONL de documentos.\n- Chunkear Markdown por secciones.\n- Buscar por texto\/tags.\n- Incluir 5-12 chunks por pregunta.\n- Agregar fuentes documentales en respuesta.\n\nAceptacion:\n\n- pregunta sobre costos recupera procesos\/listas\/diccionario;\n- pregunta sobre realtime recupera `CIRCUITOS-MS` y `MS\/README`;\n- respuesta no inventa tablas."}
{"id":"back\/lightdata_ai\/07-roadmap-implementacion.md#fase-3-contexto-operativo-real","path":"back\/lightdata_ai\/07-roadmap-implementacion.md","titulo":"Roadmap de implementacion > Fase 3 - Contexto operativo real","dominio":"general","tipo":"arquitectura_ia","tags":["general","roadmap","implementacion","fase","contexto","operativo","real"],"line_start":50,"line_end":84,"contenido":"## Fase 3 - Contexto operativo real\n\nEstado: iniciado con planner global para envios.\n\nObjetivo: responder sobre datos vivos sin depender de la ventana activa ni de que el modelo llame herramientas.\n\nAvance:\n\n- [x] Planner global para conteos\/listados de envios.\n- [x] Acciones ejecutables desde chat (`abrir_modulo` + `estado`).\n- [x] Abrir `envios.listado` con filtros derivados de lenguaje natural, por ejemplo cliente -> `filtros.nombre`.\n- [x] Catalogo de capacidades operativas para elegir rutas\/herramientas\/controladores sin diccionarios de frases.\n\nTareas:\n\n- [x] Reusar `ControladorEnvios` para conteos\/listas globales de envios.\n- [x] Detectar estado real desde `estados_envios` (`A retirar`, `Retirado`, etc.).\n- [x] Interpretar fechas basicas: hoy, ayer, semana pasada, ultimos N dias\/semanas.\n- [x] Usar la ventana activa solo ante frases como \"estos\", \"esta pantalla\", \"lo que estoy viendo\".\n- [x] Reusar `ControladorInformes` para agregados como `informes.porzonas` e `informes.porcliente`.\n- [ ] Reusar `ControladorUsuarios`, `ControladorHealth`.\n- [ ] Detectar tracking\/ID\/cliente\/chofer con mas cobertura.\n- [ ] Armar resumen operativo multi-dominio.\n- Traer envio puntual con historial si aplica.\n- Respetar permisos de perfil.\n\nAceptacion:\n\n- [ ] \"que paso con X\" trae ficha real;\n- [ ] \"como estamos hoy\" trae dashboard\/resumen;\n- [x] \"cuantos envios a retirar tengo\" consulta DB global y responde total vigente;\n- [x] \"de 1 semana para atras cuanto tengo a retirar\" interpreta rango y consulta DB;\n- [x] \"cuantos pendientes tengo por zonas\" elige `informes.porzonas` y no inventa zonas;\n- [x] cliente\/chofer no ve datos fuera de alcance porque se reutiliza `ControladorEnvios`."}
{"id":"back\/lightdata_ai\/07-roadmap-implementacion.md#fase-4-redis-operativo","path":"back\/lightdata_ai\/07-roadmap-implementacion.md","titulo":"Roadmap de implementacion > Fase 4 - Redis operativo","dominio":"ms","tipo":"arquitectura_ia","tags":["ms","roadmap","implementacion","fase","redis","operativo"],"line_start":85,"line_end":103,"contenido":"## Fase 4 - Redis operativo\n\nObjetivo: reducir DB y alimentar IA con estado caliente.\n\nTareas:\n\n- Helper PHP de Redis\/cache.\n- Cache de catalogos.\n- Cache de resumen operativo con TTL corto.\n- `rt:presence:{tenant}`.\n- `ia:{tenant}:context:logistica:{uid}:{hashCorto}`.\n- Invalidaciones por CRUD y eventos MS.\n\nAceptacion:\n\n- preguntas seguidas no reconstruyen todo;\n- cambios de estado invalidan contexto;\n- Redis caido degrada a DB."}
{"id":"back\/lightdata_ai\/07-roadmap-implementacion.md#fase-5-acciones-sugeridas","path":"back\/lightdata_ai\/07-roadmap-implementacion.md","titulo":"Roadmap de implementacion > Fase 5 - Acciones sugeridas","dominio":"general","tipo":"arquitectura_ia","tags":["general","roadmap","implementacion","fase","acciones","sugeridas"],"line_start":104,"line_end":121,"contenido":"## Fase 5 - Acciones sugeridas\n\nObjetivo: que el agente ayude a operar sin ejecutar sin permiso.\n\nTareas:\n\n- Devolver `acciones[]`.\n- UI pinta botones.\n- Acciones de navegacion: abrir modulo\/ficha\/informe.\n- Acciones preparadas: cambio estado\/asignacion\/observacion.\n- Confirmacion obligatoria.\n\nAceptacion:\n\n- el agente puede abrir envios filtrados;\n- no ejecuta cambios sin modal;\n- backend revalida permisos."}
{"id":"back\/lightdata_ai\/07-roadmap-implementacion.md#fase-6-embeddings-vector-search","path":"back\/lightdata_ai\/07-roadmap-implementacion.md","titulo":"Roadmap de implementacion > Fase 6 - Embeddings\/vector search","dominio":"general","tipo":"arquitectura_ia","tags":["general","roadmap","implementacion","fase","embeddings","vector","search"],"line_start":122,"line_end":134,"contenido":"## Fase 6 - Embeddings\/vector search\n\nObjetivo: mejorar RAG.\n\nOpciones:\n\n- embeddings locales con Ollama;\n- SQLite\/JSONL al inicio;\n- Redis vector si se habilita modulo compatible;\n- otro vector store si conviene.\n\nNo bloquear Fase 1-5 por embeddings. La busqueda textual bien etiquetada alcanza para arrancar."}
{"id":"back\/lightdata_ai\/07-roadmap-implementacion.md#fase-7-memoria-conversacional","path":"back\/lightdata_ai\/07-roadmap-implementacion.md","titulo":"Roadmap de implementacion > Fase 7 - Memoria conversacional","dominio":"general","tipo":"arquitectura_ia","tags":["general","roadmap","implementacion","fase","memoria","conversacional"],"line_start":135,"line_end":150,"contenido":"## Fase 7 - Memoria conversacional\n\nObjetivo: continuidad entre preguntas.\n\nTareas:\n\n- Tabla `ia_conversaciones` o Redis TTL.\n- Guardar resumen del hilo, no prompt completo.\n- Feedback util\/no util.\n- Historial visible por usuario si se decide.\n\nAceptacion:\n\n- el agente entiende \"y de esos cuales estan sin chofer\";\n- no guarda datos sensibles innecesarios;\n- el usuario puede reiniciar contexto."}
{"id":"back\/lightdata_ai\/README.md#lightdata-ai","path":"back\/lightdata_ai\/README.md","titulo":"Lightdata AI","dominio":"general","tipo":"arquitectura_ia","tags":["general","lightdata"],"line_start":1,"line_end":10,"contenido":"# Lightdata AI\n\nCarpeta de arquitectura y documentacion del agente logistico de Lightdata OS.\n\nEl objetivo es que el agente pueda responder y asistir sobre la operacion sin depender de memoria inventada del modelo. Para eso combina:\n\n- RAG documental: manuales, circuitos, diccionario de datos y documentacion de modulos.\n- Contexto operativo vivo: MySQL tenant, Redis operativo, WebSocket\/GPS e informes.\n- Herramientas controladas: buscar envios, leer historiales, resumir operacion, sugerir acciones y abrir modulos."}
{"id":"back\/lightdata_ai\/README.md#indice","path":"back\/lightdata_ai\/README.md","titulo":"Lightdata AI > Indice","dominio":"general","tipo":"arquitectura_ia","tags":["general","lightdata","indice"],"line_start":11,"line_end":33,"contenido":"## Indice\n\n1. [01-arquitectura.md](01-arquitectura.md)\n   - Vision general del agente, flujo front -> endpoint -> contexto -> modelo.\n\n2. [02-rag-documental.md](02-rag-documental.md)\n   - Que es RAG, que documentos indexar y como recuperar conocimiento de circuitos\/DB.\n\n3. [03-contexto-operativo.md](03-contexto-operativo.md)\n   - JSON de contexto vivo que se arma por pregunta, permisos y modulo activo.\n\n4. [04-herramientas-agente.md](04-herramientas-agente.md)\n   - Herramientas\/acciones controladas que el agente puede pedir o sugerir.\n\n5. [05-redis-y-cache.md](05-redis-y-cache.md)\n   - Que informacion conviene mantener caliente en Redis para IA y operacion.\n\n6. [06-endpoints-contratos.md](06-endpoints-contratos.md)\n   - Contratos de `ia.logistica.preguntar`, RAG search y respuestas.\n\n7. [07-roadmap-implementacion.md](07-roadmap-implementacion.md)\n   - Fases para construirlo sin romper el OS actual."}
{"id":"back\/lightdata_ai\/README.md#regla-de-oro","path":"back\/lightdata_ai\/README.md","titulo":"Lightdata AI > Regla de oro","dominio":"general","tipo":"arquitectura_ia","tags":["general","lightdata","regla"],"line_start":34,"line_end":45,"contenido":"## Regla de oro\n\n```text\nEl modelo razona.\nEl backend busca, filtra y valida.\nMySQL conserva la verdad.\nRedis mantiene estado caliente.\nLa UI confirma cualquier accion operativa.\n```\n\nEl agente no debe ejecutar cambios destructivos ni masivos por texto libre. Puede preparar una accion, explicar el impacto y pedir confirmacion mediante UI."}