[WIP][18.0] [ADD] ai_connection

[angelmoya]

Supersedes: #77

📝 Context & Rationale

This Pull Request supersedes #77 . The original implementation for
AI tool execution was functional but suffered from structural limitations when dealing
with more complex AI interactions such as real-time streaming, human-in-the-loop (HITL)
validations, and robust conversational persistence.

Specifically, if a tool raised an exception, the entire Odoo transaction would crash.
Furthermore, continuous execution flows lacked the ability to pause and resume
effectively, and file attachments were bloat-heavy when kept purely in memory or JSON
structures.

This PR introduces a refactoring of the ai.connection core to solve these issues by
unifying the LLM execution flow around a generator-based architecture and providing
dedicated database models for execution persistence.

🛠️ Key Architectural Changes

• Unified Generator Core: _run and _run_ai have been refactored to consume a single
iterator logic ( handle_message_stream ). This streamlines both synchronous and iterative
workflows into a single manageable loop.
• Robust Persistence Layer: Introduced ai.connection.execution to track the state (
draft , running , paused , pending_tool_approval , done , failed ) and the
conversational history.
• Fail-Safe Tool Execution: Tool calls ( _execute_tool ) are now wrapped in a try/except
block. Instead of crashing the Odoo thread, exceptions are captured and returned to the
LLM as a JSON error payload, allowing the AI to naturally correct its inputs or notify the
user.
• Optimized Attachments: Base64 files inside prompts are now dynamically extracted into
ir.attachment records and rehydrated back only when communicating with the LLM API,
significantly reducing DB payload overhead.
• Extensible Streaming Architecture: While the exact streaming transport is not rigidly
defined out of the box, this refactor introduces an isolated _on_stream_batch hook. This
acts as a highly extensible foundation allowing developers to implement custom streaming
logic (for instance, streaming chunks via temporary files or websockets) without modifying
the core execution loop.

✨ New Features

• Backend UI for Executions: Admins can inspect active, paused, or failed executions from
the backend, viewing the full message history and token usage.
• Step-by-Step Mode (HITL & Transaction Isolation): Executions can now run in a stepwise
mode, pausing after each tool call to allow for manual inspection or future confirmation
dialogs ( pending_tool_approval ). Crucially, this allows each iteration to be executed in
a separate database query/transaction, preventing massive long-running transactions from
holding locks.
• Deep Debugging: Added a debug flag that records every single iteration in a nested
model ( ai.connection.execution.iteration ), dumping the exact request/response JSONs
exchanged with the API. A cron job automatically vacuums these debug records after 15 days.

🧪 Testing

The test suite has been significantly expanded to cover:

• Standard and persistent executions.
• Paused states, stepwise increments, and interactive resumption.
• Stream chunk buffering logic.
• Automatic extraction and rehydration of file attachments from the JSON history.
• Tool error isolation and recovery.

[angelmoya]

I have also added a testing wizard ( ai.connection.run.wizard )!

You can now click the "Test Connection" button directly from the ai.connection form
view. It allows you to quickly test prompts, system prompts, and tools from the UI. You
can choose to run it in-memory to get a direct raw response, or store the execution in the
database to debug the step-by-step iterations. Test coverage is also included for it.