From ef20b9a506b56133c59ab6168f49154ca9311603 Mon Sep 17 00:00:00 2001 From: D3n3bX Date: Tue, 5 May 2026 20:32:29 +0200 Subject: [PATCH] Doc perry human in the loop --- .../docs/addons/perry-human-in-the-loop.md | 46 +++++++++++++++++++ .../docs/{ => addons}/perry-webhook.md | 0 2 files changed, 46 insertions(+) create mode 100644 custom_addons/docs/addons/perry-human-in-the-loop.md rename custom_addons/docs/{ => addons}/perry-webhook.md (100%) diff --git a/custom_addons/docs/addons/perry-human-in-the-loop.md b/custom_addons/docs/addons/perry-human-in-the-loop.md new file mode 100644 index 0000000..65359dd --- /dev/null +++ b/custom_addons/docs/addons/perry-human-in-the-loop.md @@ -0,0 +1,46 @@ +The **HITL** system is Perry's "safety catch." Instead of allowing the AI to write directly to sensitive models (like Payments or CRM Leads), Perry prepares a **Pending Action**. This action acts as a draft containing all the necessary metadata, which a human user must then review, confirm, or cancel. + +## Model overview: `perry.pending.action` + +This model serves as a temporary staging area for AI-generated intents. It stores the raw data in a JSON payload and provides a user-friendly interface for execution. + +### Core Fields: +* **Action title (`name`)**: A descriptive name for the task (e.g., "Schedule Meeting: Project Review"). +* **Action type (`action_type`)**: Defines the target Odoo module: + * `lead`: Creates a CRM Opportunity. + * `payment`: Registers an Accounting Payment. + * `calendar`: Creates a Calendar Event. +* **Payload (`payload`)**: A hidden text field containing the raw JSON data extracted by the AI agents. +* **Status (`state`)**: Manages the lifecycle: `draft` $\to$ `pending` $\to$ `done` or `cancelled`. + +## Key features + +### 1. Dynamic data summary +To avoid forcing users to read raw JSON, the module includes a computed **Summary HTML** field. +* **Logic**: It parses the `payload` and generates a clean, responsive HTML table. +* **User experience**: Users see a clear breakdown of "Recipient," "Amount," or "Date" directly on the Odoo form before clicking confirm. + +### 2. The execution engine (`action_confirm`) +When a user clicks **Confirm**, the module triggers specific Odoo logic based on the action type: + +* **CRM leads**: Creates a new `crm.lead` record using `sudo()` to ensure permissions don't block the AI's intent. +* **Accounting payments**: + * Performs an `ilike` search for the **Partner** and **Journal**. + * Creates an `account.payment` record. + * Automatically triggers `.action_post()` to move the payment out of draft state. +* **Calendar events**: + * Parses naive timestamps. + * Calculates durations and sets the UTC offset (defaulting to -2 hours for specific regional logic). + * Creates the `calendar.event`. + +### 3. Safety first (`action_cancel`) +If the AI extracted the wrong data or the user changes their mind, the `action_cancel` method simply marks the record as `cancelled`. This prevents the data from ever touching the core Odoo business models. + + +## Observability (Logfire) + +The HITL module is deeply instrumented with **Logfire** to provide a full audit trail of human decisions: +* **Computation Traces**: Logs every time a summary is rendered. +* **Lookup Logs**: In payments, it logs whether the Partner or Journal were successfully found. +* **Execution Spans**: Every confirmation is wrapped in a span that logs the final record ID created in Odoo. +* **Validation Errors**: If a journal isn't found or a payment fails to post, Logfire captures the exception before Odoo shows the user a friendly error message. \ No newline at end of file diff --git a/custom_addons/docs/perry-webhook.md b/custom_addons/docs/addons/perry-webhook.md similarity index 100% rename from custom_addons/docs/perry-webhook.md rename to custom_addons/docs/addons/perry-webhook.md