# Chatboo (pns_ai_chatboo)

**IA para todos tus clientes, sin salir de Odoo.** Chatboo abre un chat de IA encima de la pantalla que tu cliente ya está usando. Sabe qué hay en esa pantalla, responde con los permisos del propio usuario y se quita con un clic. Funciona sobre el Motor de IA ([`pns_ai_mcp`](https://www.patanegra.com/es/ai-engine.html)). Odoo **14.0** y **19.0**.

## El dolor

**Para usar IA hay que salir de Odoo.**
Se exportan Excels a otra aplicación, o se le da la contraseña de Odoo a un
servicio de fuera. La respuesta llega a otro sitio y el trabajo se para
mientras se copia de vuelta. Chatboo se abre encima de la pantalla en la que
ya estás.

| | |
| :--- | :--- |
| **01 — ¿Esperar mirando cómo piensa la IA?** | Es una capa de quita y pon. La cierras, sigues trabajando y el elefante te avisa cuando la respuesta está lista. |
| **02 — ¿Cada pregunta cuesta dinero?** | Lo que repites lo conviertes en un skill. Casi siempre se ejecuta sin llamar a la IA: coste cero y la misma respuesta cada vez. |
| **03 — ¿Explicarle cada vez de qué registro hablas?** | Sabe qué hay en pantalla. Si varios encajan, pinchas la fila y listo. |

## Qué te llevas

**En la pantalla que ya usan**
- El elefante de la barra superior abre el chat encima de la pantalla actual. Nadie sale del registro en el que estaba.
- Sabe qué registro o qué lista hay en pantalla.
- Si varios registros encajan, los enseña. Pinchas una fila y la siguiente pregunta va sobre esa.
- Las conversaciones se guardan y se pueden reabrir. Cada usuario ve solo las suyas.

**Trabaja mientras piensa**
- Cierras el chat y sigues. La respuesta sigue llegando.
- Cuando está lista, el elefante enseña una campanita y Odoo muestra un aviso.
- Una respuesta larga se puede parar desde el chat.

**Respuestas que sirven**
- Tablas cuyas celdas abren el registro, y gráficos dibujados en el chat.
- Exportar una respuesta a PDF, Excel o Word, o copiarla.
- Adjuntar un Excel, un Word, un PDF, una imagen o un texto, y preguntar sobre él.
- Las respuestas se pueden leer en voz alta.

**Skills que no cuestan nada**
- Escribes `/` y eliges un skill: un procedimiento escrito una vez, para las rutinas del cliente.
- Las tablas y gráficos de un skill salen del código, no de la IA. Mismos datos, misma respuesta.
- Una buena respuesta se puede guardar como skill nuevo desde el propio chat.
- Ese conocimiento es un servicio que vendes y mantienes en cada cliente.

**Seguro para tu cliente**
- Lee como la persona que pregunta: sus permisos, sus reglas de registro y sus compañías.
- Un cambio es un plan con un botón Confirmar. Solo confirman los usuarios que tú permitas.

**Se pone y se quita**
- Un módulo de Odoo normal: sin servidor externo, sin herramientas de compilación.
- Apache 2.0. Sin cuota por usuario, por base de datos ni por año.
- Se desinstala desde Aplicaciones como cualquier otro.

## Qué trae el módulo

Leído de los propios ficheros del módulo, versión 2.1.553. Las descripciones van en inglés, como en el módulo.

### Skills de ejemplo

Vienen con el módulo para enseñar cómo es un skill. Los de cada cliente los escribe su consultor. Escribe `/` en el chat y elige uno.

| Orden | Nombre | Qué hace | Argumento |
| :--- | :--- | :--- | :--- |
| `/annual-billing` | Annual billing by week | Customer invoicing (posted out_invoice) by ISO week for a year or date range; pastel bar chart by month. | `year=2024` |
| `/billing` | Billing by period | Posted customer invoice totals for a period (last N months, year, YTD or range); chart-ready table without business-area coupling. | `ytd` |
| `/cash-forecast` | Cash forecast | Week-by-week cash forecast page from open customer and supplier items by due date: inflows, outflows, running balance, lowest point and the biggest receipts and payments ahead. | `weeks=12` |
| `/credit-facility` | Credit facilities | Month-end drawn (creditor balance) on facility journals; configurable period; PDF-safe month blocks. | `ytd \| 12 \| 2025 \| 2024-2025 \| 2025-03 \| ?` |
| `/customer-360` | Customer 360 | One-page customer view across apps: profile, health score, revenue by month, open and overdue invoices, CRM opportunities, meetings, planned activities and the latest messages. | `customer name, VAT or email` |
| `/customer-risk-analysis` | Customer risk analysis | Customer collection-risk score from six criteria: payment ratio, DSO, temporal spread, monetary volume, recency and due-date compliance. | `meses=24 min_deuda=0 top=30` |
| `/dashboard` | Business dashboard | Nine chart cards — team (or journal), top customers and trend for month, quarter and YTD from posted customer invoices. |  |
| `/financial-health` | Financial health | Narrative financial situation report: KPIs, liquidity, debts, collections, ratios, facilities; configurable period. | `ytd \| 12 \| 2025 \| 2024-2025 \| 2025-03 \| ?` |
| `/forecast` | Weather forecast | Company-city forecast for the next 7 days by default; optional other cities; sky column uses weather emojis. | `company city · 7 days` |
| `/pipeline` | Sales pipeline | Live CRM pipeline page: funnel by stage, weighted forecast by close month, salesperson leaderboard, win rate and stalled deals. | `team=… salesperson=… stalled_days=21` |
| `/sys-info` | System information | Odoo version, series, server time, current user and company, user/company/module counts, and base URL. |  |
| `/users-all` | All users | All system users (including archived) with login, name, email, type (internal/portal), active flag and last access. |  |
| `/users-logged` | Logged-in users | Users currently connected (bus online/away). If the bus is unavailable, last logins by date. |  |

### Contextos

| Código | Tipo | Descripción |
| :--- | :--- | :--- |
| `page_tab` | domain | Answer as a page in its own browser tab (page_url), not as a chat table |
| `presentation_grids` | domain | Chatboo table presentation — soft pastels, pijama, quartiles/terciles, readable text colours |
| `self_chatboo` | domain | Chatboo identity — role, tone and scope |
| `ui_focus` | domain | Chatboo screen focus — implicit reference to the Odoo view underneath the overlay |

Al instalar Chatboo entra también PNS AI Engine, con sus 28 contextos: [verlos](https://www.patanegra.com/es/ai-engine.html#contextos).


## Qué no hace

- **No trae IA propia.** Los proveedores, los agentes y las aprobaciones viven en el Motor de IA. Sin un proveedor con el rol **Conversación**, el chat no tiene a quién preguntar.
- **No es para todos los usuarios de entrada.** Solo lo usan quienes tienen **IA Conversacional** y una clave API generada.
- **No cambia nada sin una persona.** La IA propone; un usuario con **IA Escritor** pulsa Confirmar.
- **Dos versiones probadas.** 14.0 y 19.0. De la 15.0 a la 18.0 construyes tú los módulos y los pruebas antes; la 13.0 y anteriores no funcionan (ver *Versiones de Odoo*).

## Preguntas

**¿Adónde van las preguntas?** A los proveedores configurados en el Motor de IA, en el orden de la lista del agente. Un skill que se ejecuta sin la IA no envía nada fuera.

**¿La voz es un servicio de fuera?** No. Leer una respuesta en voz alta usa la voz del propio navegador.

**¿Chatboo es un servidor MCP?** No. El servidor MCP está en el Motor de IA (`/mcp`). Chatboo es el chat dentro de Odoo y habla con el motor por PAAP, dentro del mismo Odoo.

**¿Puedo usar el motor sin Chatboo?** Sí. El Motor de IA solo ya sirve a Cursor y a otros clientes MCP.

## Puesta en marcha

1. **Instala.** Desde la tienda de Odoo, descarga Chatboo: la tienda trae PNS AI Engine y PNS Base. Desde git, clona los tres en la misma serie (`19.0` o `14.0`):

   ```bash
   mkdir -p ~/odoo/pns && cd ~/odoo/pns
   for r in pns_base pns_ai_mcp pns_ai_chatboo; do
     git clone -b 19.0 --depth 1 https://github.com/patanegra-soft/$r
   done
   ```

   Cada clon es una entrada más del `addons_path` (`~/odoo/pns/pns_base,~/odoo/pns/pns_ai_mcp,~/odoo/pns/pns_ai_chatboo`). En Odoo 14, antes, `pip install "openpyxl>=3.1.2"`. Reinicia Odoo, *Aplicaciones → Actualizar lista de aplicaciones* e instala **Chatboo**; los otros dos entran con él.
2. **Configura el Motor de IA.** Chatboo habla con la IA a través de `pns_ai_mcp`. Sigue su [puesta en marcha](https://www.patanegra.com/es/ai-engine.html#puesta-en-marcha): administrador de IA, tu acceso y un proveedor.

**Listo.** Pulsa el elefante de la barra superior.

## Para el equipo de IT

### Cómo encaja

```
pns_ai_chatboo  ──PAAP──▶  pns_ai_mcp  ──▶  proveedores de IA
  (conversación)             (motor)
```

Chatboo lleva la conversación: las sesiones, el turno del chat (en
streaming), la pantalla desde la que se abre y la interfaz (la aplicación y
la capa que sale de la barra superior). Los proveedores, los agentes, las
herramientas y el bucle de la IA son del motor; Chatboo le habla por PAAP
(Patanegra Application Agent Protocol). Depende de `web`, `bus`, `mail`,
`pns_base` y `pns_ai_mcp`.

Una fila pinchada viaja con el siguiente mensaje como `{model, id, label}`,
así el motor la toma como el asunto en vez de volver a buscar el nombre. Ese
mensaje la gasta.

### Estructura del repositorio

`main` es un solo árbol para todas las versiones. Una rama plana (`14.0`, `19.0`) es ese árbol construido para una versión, listo para el addons path.

| Ruta | Contenido |
| :--- | :--- |
| `common/` | Código común a todas las versiones, skills, contextos, datos, ficha de Apps |
| `stacks/owl1/pns_ai_chatboo/` | Odoo 14 |
| `stacks/owl2/pns_ai_chatboo/` | Odoo 15 y siguientes |

El instalador copia `common/` y encima la pila; si un fichero está en los dos,
gana el de la pila. Lo común se edita solo en `common/`. El módulo plano de
una versión se construye con `./install_flat.sh 19.0 /ruta/a/addons`.

Python: en la 14, usa un `openpyxl` reciente (los antiguos fallan con NumPy
moderno). En la 19 no hace falta nada más.

### Versiones de Odoo

| Versión | Estado |
| :--- | :--- |
| 14.0, 19.0 | Probadas. Rama plana publicada. |
| 15.0 – 18.0 | Sin probar, ni por personas ni por el CI. Sin rama publicada. |
| 13.0 y anteriores | No soportadas. |

**De la 15.0 a la 18.0.** No hay rama que clonar. Construye tú los módulos
planos desde `main`, que tiene el código de todas las versiones (`owl2` para
la 15.0 y siguientes): `pns_base`, `pns_ai_mcp` y Chatboo.

```bash
git clone https://github.com/patanegra-soft/pns_base.git
git clone https://github.com/patanegra-soft/pns_ai_mcp.git
git clone https://github.com/patanegra-soft/pns_ai_chatboo.git
cd pns_base       && ./install_flat.sh 17.0 /ruta/a/addons && cd ..
cd pns_ai_mcp     && ./install_flat.sh 17.0 /ruta/a/addons && cd ..
cd pns_ai_chatboo && ./install_flat.sh 17.0 /ruta/a/addons
```

El script avisa de que esa versión no está probada. Nadie ha usado Chatboo
en estas versiones: pruébalo antes en una base de pruebas y pasa ahí los
tests de Odoo (ver *Tests*). Si funciona, o si no, cuéntanoslo
([CONTRIBUTING.md](https://github.com/patanegra-soft/pns_ai_chatboo/blob/main/CONTRIBUTING.md)).

Odoo 13 no tiene OWL, sobre el que está hecho el chat. De Odoo 8 a 12 usan un
Python anterior al 3.7, que es el que necesita el motor. La suite mantiene dos
pilas (`owl1` para la 14.0 y `owl2` para la 15.0 y siguientes).

### Tests

| Dónde estás | Qué se ejecuta |
| :--- | :--- |
| `main` | `python -m pytest unit_tests`, sin Odoo. Después los tests de Odoo, tras `./install_flat.sh 19.0 <dir>`. |
| Una rama plana (`14.0`, `19.0`) | Los tests de Odoo en `tests/`. Los unitarios viven en `main`. |

```bash
odoo-bin -d <db> -i pns_ai_chatboo --test-enable --stop-after-init --test-tags /pns_ai_chatboo
```

## Licencia, marcas, entrenamiento

Apache-2.0: ver [LICENSE](https://github.com/patanegra-soft/pns_ai_chatboo/blob/main/LICENSE) y [NOTICE](https://github.com/patanegra-soft/pns_ai_chatboo/blob/main/NOTICE).
Chatboo™, el dibujo del elefante con el bocadillo, PATANEGRA Soft™ y PAAP™
son marcas de PATANEGRA Soft SL; la licencia no las concede. Se permite la
minería de textos y el entrenamiento de IA (TDMRep `tdm-reservation = 0`).

Seguridad: [SECURITY.md](https://github.com/patanegra-soft/pns_ai_chatboo/blob/main/SECURITY.md). Errores, ideas y preguntas: [CONTRIBUTING.md](https://github.com/patanegra-soft/pns_ai_chatboo/blob/main/CONTRIBUTING.md).