docs: implement Perry Webhook Addon documentation

custom_addons/docs/perry-webhook.md

@@ -0,0 +1,54 @@
+The **Perry Webhook Addon** is a custom Odoo module that listens to internal messages and triggers the AI processing pipeline. It ensures that Perry can "hear" and "respond" within Odoo’s native Discuss (chatter) interface without blocking the user experience.
+
+The addon inherits from Odoo’s core messaging system (`mail.message`) to intercept communications. Its primary goal is to identify relevant messages in private chats and dispatch them to the **Perry Ingest API** for intelligent processing.
+
+### Key responsibilities:
+*   **Message Interception**: Real-time monitoring of new messages created in the system.
+*   **Intelligent Filtering**: Ensuring Perry only responds to private chats where he is an active participant and ignoring his own automated replies.
+*   **Asynchronous Dispatch**: Utilizing background threading to call the AI engine, ensuring the Odoo UI remains responsive and the message input bar clears instantly.
+*   **Response Integration**: Receiving the AI's output and posting it back into the Odoo channel as a formal comment.
+
+## Technical implementation
+
+### 1. Message hook (`mail.message`)
+The module overrides the `create` method of the `mail.message` model. This is the entry point for every message sent in Odoo.
+
+*   **Identity check**: It searches for the internal "Perry" user via a hardcoded email (`perry@perry.com`).
+*   **Constraint engine**:
+    *   **Type**: Only processes messages of type `comment`.
+    *   **Channel**: Only triggers for `discuss.channel` models of type `chat` (Direct Messages).
+    *   **Participation**: Only triggers if the "Perry" partner is a member of the specific channel.
+    *   **Anti-Recursion**: Immediately ignores messages authored by Perry to avoid infinite loop conversations.
+
+### 2. Non-blocking execution (Threading)
+Odoo typically operates in a synchronous request-response cycle. To prevent the user from waiting for the AI to "think," the addon spawns a **Background Thread** (`send_webhook_threaded`).
+
+*   **Independent cursor**: Because Odoo's database cursor is not thread-safe, the background process opens its own independent registry and cursor to interact with the database.
+*   **Daemon threading**: Uses `threading.Thread(daemon=True)` to ensure the process doesn't hang the main server process on shutdown.
+
+### 3. Webhook logic
+The background function performs a `POST` request to the AI Ingest API.
+
+*   **Endpoint**: `http://ingest-api-api-1:8000/clean/odoo`
+*   **Payload**: Includes the `session_id` (Odoo Channel ID) and the message body/metadata.
+*   **Persistence**: Upon receiving a successful (200 OK) response, it uses `Markup` to ensure safe HTML rendering and calls `channel.message_post()` followed by a manual `env.cr.commit()` to persist the AI's response.
+
+## Operational Flow
+
+1.  **User sends message**: The user types a message in an Odoo chat with Perry.
+2.  **Hook triggered**: `MailMessage.create()` intercepts the data.
+3.  **Validation**: The module confirms Perry is a participant and it's a private chat.
+4.  **Thread spawning**: A background thread is kicked off with a 120s timeout.
+5.  **UI feedback**: The user sees their message posted instantly; the input box clears.
+6.  **AI processing**: The thread calls the FastAPI engine.
+7.  **Injection**: The thread receives Perry's response and injects it back into the Odoo channel.
+
+## Observability (Logfire)
+
+The addon is instrumented with **Logfire** to track the lifecycle of a message from the Odoo side:
+*   **Spans**: Captures the initial hook (`mail.message create hook`) and the background API call (`Send Odoo webhook to FastAPI`).
+*   **Detailed Logging**:
+    *   `Odoo mail messages created`: Tracks volume.
+    *   `Private chat message detected`: Logs intent identification.
+    *   `FastAPI webhook response received`: Tracks status codes and latency.
+    *   `Odoo channel response committed`: Confirms the final delivery of Perry's reply.