CHEFMANAGER 3.5.0 · PRIVATE AI
===============================

OBJETIVO
--------
Añadir una capa de IA privada y opcional sobre el motor analítico existente sin convertir el LLM en la fuente de verdad y sin obligar al restaurante a contratar una API comercial por consulta.

PRINCIPIO
---------
ChefManager calcula. La IA analiza. Tú decides.

La aplicación ERP/POS sigue funcionando con PHP + JavaScript y SQLite. AiInsights, SQL, reglas y estadísticas continúan siendo el respaldo determinista si el servidor de IA no está instalado, está apagado o falla.

ARQUITECTURA INCLUIDA
---------------------
1. ChefManager ERP/POS: PHP + JavaScript.
2. ChefManager AI Gateway: Python + FastAPI, en ai-gateway/.
3. Runtime local inicial: Ollama.
4. Model Router:
   - Agente: qwen3:8b (configurable).
   - Razonamiento: deepseek-r1:7b (configurable).
   - Visión: qwen3-vl:4b (configurable).
   - Embeddings: embeddinggemma (configurable; esquema actual espera 768 dimensiones).
5. RAG documental: PostgreSQL + pgvector.
6. Fallback: AiInsights + tools SQL seguros + búsqueda documental local en SQLite.
7. Control Center global de IA: métricas agregadas y salud, sin revelar credenciales.

IMPORTANTE: los modelos NO se incluyen dentro del ZIP. Son varios GB y deben descargarse en el servidor mediante Ollama. El sistema puede funcionar sin ellos gracias al fallback interno.

DATOS VIVOS VS. RAG
-------------------
NO se indexan ventas, caja o inventario completo en la base vectorial.

Datos vivos/estructurados:
- ventas
- costos/margen
- inventario
- lotes/vencimientos
- mermas
- Cocina
- proveedores
- RRHH
- mantenimiento
- reputación

se consultan mediante tools SQL previamente programados y filtrados por restaurant_id/branch_id.

RAG se reserva para conocimiento documental:
- Manual Digital
- recetas y fichas técnicas (sincronización automática desde Recetas)
- procedimientos
- políticas
- contratos
- documentos RRHH
- manuales de equipos
- capacitación

SEGURIDAD
---------
- El LLM no recibe credenciales de la base de datos.
- El LLM no genera ni ejecuta SQL libre.
- PHP ejecuta únicamente tools incluidos en allow-list.
- Cada consulta se filtra por restaurante, sucursal, usuario, rol y permisos.
- pgvector aplica además Row Level Security por restaurant_id. El Gateway conecta con un rol PostgreSQL no-superusuario (chefmanager_ai_app); el superusuario de la base no se entrega al Gateway.
- Ollama no se publica a Internet en docker-compose.ai.yml.
- AI Gateway se publica solo en 127.0.0.1:8090 del host.
- AI Gateway exige X-ChefManager-AI-Key cuando CM_AI_REQUIRE_SECRET=true.
- Los restaurantes no pueden seleccionar modelos arbitrarios instalados en el servidor salvo habilitación explícita del operador.
- El secreto se compara en tiempo constante.
- El Super Admin no ve el secreto en la interfaz.
- Toda tool queda registrada en ai_tool_executions y Audit.
- Las acciones sensibles se convierten en propuestas y requieren confirmación humana.

TOOLS DISPONIBLES EN 3.5.0
--------------------------
Lectura:
- get_manager_snapshot (reutiliza Gerente Inteligente 24/7)
- get_purchase_suggestions (reutiliza AI Inventory)
- get_sales_forecast (reutiliza el pronóstico interno)
- get_sales_summary
- get_waste_ranking
- get_inventory_risk
- get_expiring_batches
- get_kitchen_delays
- get_reputation_summary
- get_supplier_debt
- get_maintenance_risk
- get_hr_attendance
- search_knowledge

Propuestas con confirmación:
- propose_product_availability
- propose_high_demand_mode

Las propuestas caducan y pueden ser Confirmadas o Rechazadas desde ChefManager Private AI. El modelo nunca ejecuta el cambio directamente.

CHEFMANAGER VISION
------------------
Private AI incluye un flujo de lectura visual para factura/nota de entrega:
- el usuario sube JPG/PNG/WebP;
- el navegador reduce la imagen antes del envío;
- AI Gateway usa el modelo visual configurado;
- devuelve proveedor, documento, fecha, moneda, totales e ítems cuando sean legibles;
- devuelve confianza y advertencias;
- NO registra la compra, NO cambia inventario y NO crea cuentas por pagar automáticamente.

Siempre requiere revisión humana antes de pasar los datos a módulos transaccionales.

INSTALACIÓN RÁPIDA CON DOCKER
-----------------------------
Requisitos recomendados:
- Docker + Docker Compose
- espacio suficiente para los modelos
- RAM acorde con los modelos seleccionados
- GPU opcional, pero recomendable para menor latencia

Desde la carpeta ai-gateway/:

  bash scripts/install-local.sh

El script:
- genera CM_AI_SHARED_SECRET;
- genera contraseñas PostgreSQL separadas para administración y para el rol restringido del Gateway;
- levanta PostgreSQL/pgvector, Ollama y AI Gateway;
- descarga los modelos configurados.

Después copia el valor CM_AI_SHARED_SECRET generado en ai-gateway/.env a la variable de entorno PHP:

  CHEFMANAGER_AI_SECRET=<mismo secreto>

Por defecto PHP ya busca:

  CHEFMANAGER_AI_GATEWAY_URL=http://127.0.0.1:8090

No publiques 11434 (Ollama) ni 5432 (PostgreSQL) a Internet.

CONFIGURACIÓN DEL GATEWAY
-------------------------
Variables principales:
CM_AI_SHARED_SECRET
CM_AI_OLLAMA_URL
CM_AI_MODEL_AGENT
CM_AI_MODEL_REASONING
CM_AI_MODEL_VISION
CM_AI_MODEL_EMBEDDING
CM_AI_POSTGRES_DSN
CM_AI_RAG_ENABLED
CM_AI_ALLOW_TENANT_MODEL_OVERRIDE (false por defecto en SaaS)

El archivo ai-gateway/.env.example contiene un ejemplo. El endpoint /health también exige X-ChefManager-AI-Key cuando CM_AI_REQUIRE_SECRET=true; no es un endpoint público. El compose usa Ollama 0.32.5 por defecto y permite sobrescribir OLLAMA_IMAGE/PGVECTOR_IMAGE desde .env.

POSTGRESQL + PGVECTOR
---------------------
El PostgreSQL de 3.5.0 se usa para el índice vectorial del AI Gateway. NO es una migración automática de todo el ERP desde SQLite.

Esquema disponible:
  database/postgresql-private-ai.sql

Incluye:
- vector(768)
- índice HNSW/cosine
- filtro tenant
- Row Level Security forzada por restaurant_id

AI Gateway ejecuta set_config('app.restaurant_id', ...) dentro de cada transacción antes de leer/escribir vectores. El branch_id de fuentes de sucursal también se conserva en el índice y se filtra al recuperar. El esquema/EXTENSION se crea durante la inicialización del contenedor con el usuario administrador; el Gateway no tiene permisos DDL ni BYPASSRLS.

FALLBACK
--------
Si AI Gateway/Ollama no está disponible:
- ChefManager NO deja de operar;
- Gerente Inteligente 24/7 continúa con AiInsights;
- Private AI selecciona tools por reglas internas;
- las cifras siguen saliendo de SQL real;
- RAG puede usar búsqueda léxica local sobre los fragmentos almacenados en SQLite.


BOOTSTRAP SEGURO DE SUPER ADMIN
--------------------------------
El ZIP no incluye tokens ni hashes de recuperación pre-generados. Para una instalación nueva o una recuperación explícita usa desde la terminal:

  php cli/create-admin-recovery.php admin@tudominio.bo "Administrador"

El comando genera una contraseña temporal aleatoria y storage/admin-reset-once.json con permisos restringidos. ChefManager consume ese archivo una sola vez y lo elimina. El directorio cli/ está bloqueado desde .htaccess y el script rechaza ejecución web.

CONTROL CENTER
--------------
El Super Admin dispone de:
Sistema -> Inteligencia Artificial

Muestra:
- salud de AI Gateway/Ollama;
- modelos configurados;
- estado de RAG;
- consultas, tool calls y fallbacks;
- uso por restaurante de forma agregada;
- arquitectura activa.

Es de solo lectura. No muestra secretos ni permite entrar a datos operativos de los restaurantes.

BENCHMARK
---------
Después de instalar los modelos:

  CM_AI_SHARED_SECRET=<secreto> python3 scripts/benchmark-local.py

Valida selección de las 13 tools de lectura y las 2 tools de propuesta. Las dos acciones se quedan en fase de propuesta: el benchmark nunca confirma ni modifica datos del restaurante.

COSTOS
------
La arquitectura evita una tarifa obligatoria por consulta/tokens de un proveedor externo. Esto NO significa costo total cero: el servidor, RAM/GPU, almacenamiento, electricidad, monitoreo y mantenimiento siguen teniendo costo operativo.

LICENCIAS
---------
ChefManager no redistribuye pesos de modelos dentro de este ZIP. Antes de desplegar o redistribuir un modelo, verifica siempre la licencia de la versión exacta elegida. Los nombres de modelos incluidos en los ejemplos son defaults técnicos configurables, no una obligación.

LIMITACIONES / SIGUIENTE EVOLUCIÓN
----------------------------------
- vLLM está contemplado por la interfaz de arquitectura, pero 3.5.0 entrega Ollama como runtime listo para instalar.
- Edge/offline en la PC de caja con Phi/Gemma no se instala automáticamente en 3.5.0; se mantiene como futura modalidad, sin acoplar el ERP a un modelo específico.
- ChefManager Vision extrae y previsualiza; una siguiente versión puede convertir la previsualización aprobada en borrador de compra sin saltarse confirmaciones.
- La migración completa del ERP SaaS a PostgreSQL debe hacerse como proyecto separado y reversible; 3.5.0 no fuerza esa migración.
