Skip to content

System Architecture

🏗️ Technical Overview

Now that you understand what AI Complete Suite does, let's dive into how it's built. The system uses a layered architecture that makes it flexible, secure, and easy to extend.

🧠 Core Foundation (ai_base_gt)

The foundation module is the heart of the system. It provides all the essential services that other modules depend on.

Data Models

AI Assistant (ai.assistant)

  • Manages AI assistants with different roles and permissions
  • Links to Odoo partners and users
  • Controls access to data sources and tools
  • Handles super assistant mode for administrative access

Data Source (ai.data.source)

  • Manages three types of data sources: Model, URL, and Text
  • Handles data indexing and vector embeddings
  • Controls which assistants can access which data
  • Manages domain filters for model data

AI Context (ai.context)

  • Defines behavior and personality for AI assistants
  • Provides system prompts and instructions
  • Controls response style and tone
  • Manages assistant-specific knowledge

AI Thread (ai.thread)

  • Manages conversation sessions
  • Handles message history and context
  • Provides AI tools and function calling
  • Controls access to Odoo data and operations

Key Features

Vector Embeddings

  • Uses FastEmbed for semantic search
  • Supports multiple languages
  • Optimized for similarity search
  • Real-time indexing of new data

Tool Integration

  • AI can call tools to access and modify Odoo data
  • Tools respect Odoo permissions and domain restrictions
  • Read Tools: Search, read, and analyze records
  • Write Tools: Create, update, and delete records
  • Custom tools can be added
  • Function calling with parameters

Access Control

  • Permission-based data access
  • Data source restrictions
  • Group-based access control
  • Audit trail for all operations

AI Tools

The system provides a comprehensive set of tools for AI to interact with Odoo data:

Read Tools:

  • _semantic_search: Search across data sources using semantic similarity
  • _model_search: Search Odoo records with domain filters
  • _model_read: Read specific record details
  • _model_read_group: Perform grouped data analysis
  • _get_model_fields_spec: Get all accessible fields specifications of models

Write Tools:

  • _model_create: Create new records in Odoo models
  • _model_write: Update existing record fields
  • _model_unlink: Delete records from Odoo models

Method Tools:

  • _get_model_methods_spec: Discover what methods are available on a model
  • _call_model_method: Execute custom business logic methods on records

Translation Tools:

  • _model_get_field_translations: Get current translations of a translatable field
  • _model_update_field_translations: Update translations of a translatable field

Security Features:

  • All tools respect user permissions
  • Domain access control for write and method operations
  • Field-level access control ensures only allowed fields can be changed
  • Automatic validation for invalid operations

🏠 Integration Modules

Discuss Integration (ai_mail_gt)

Purpose: Integrates AI into Odoo's Discuss system for team collaboration.

Key Components:

  • Mail AI: Processes messages and triggers AI responses
  • AI Thread: Manages conversation threads in Discuss
  • Record Tagging: Automatic linking to Odoo records
  • UI Components: Ask AI button and assistant selection

How It Works:

  1. User sends message in Discuss
  2. System detects AI mentions or private chats
  3. Creates or finds AI thread for conversation
  4. AI processes message with context and tools
  5. Response is posted back to Discuss channel

Features:

  • Private AI conversations
  • AI mentions in team channels
  • Record reference parsing ($model/id)
  • Attachment handling (images, documents)
  • AI can read conversation history of any Odoo thread
  • AI can send messages to any Odoo thread
  • Error handling and recovery

AI Tools:

  • _read_thread_conversation: Read conversation history of any accessible Odoo thread
  • _post_message_to_thread: Send messages to any Odoo thread (tasks, leads, orders, etc.)

Livechat Integration (ai_livechat_gt)

Purpose: Provides AI-powered customer support through website livechat.

Key Components:

  • AI Operator: AI assistant as livechat operator
  • Human Handover: Seamless transition to human agents
  • Context Management: Livechat-specific AI contexts
  • Channel Management: AI-enabled livechat channels

How It Works:

  1. Customer starts chat on website
  2. System assigns AI operator if no humans available
  3. AI handles customer questions using business data
  4. If AI can't help, transfers to human agent
  5. Conversation context is preserved during handover

Features:

  • 24/7 automated support
  • Multi-language support
  • FAQ automation
  • Smart escalation to humans
  • Performance monitoring

AI Tools:

  • _forward_to_human_operator: Transfer conversation to a human operator when AI cannot help

Automation Integration (ai_automation_gt)

Purpose: Integrates AI assistants with Odoo's Automation Rules and Scheduled Actions, allowing AI actions to be triggered automatically when events occur or on a fixed schedule.

Key Components:

  • AI Action Type: New action type in automation rules and scheduled actions
  • AI Thread Creation: Automatic thread creation for each automation execution
  • Record Tagging: Automatic inclusion of triggered records in AI context (Automation Rules)
  • Non-Interactive Mode: AI runs autonomously without asking questions

How It Works:

  1. Create automation rule or scheduled action with "AI Action" type
  2. Configure AI assistant and write prompt describing the task
  3. When rule/action triggers, system creates AI thread with your prompt
  4. AI executes task autonomously using available tools
  5. Results are applied automatically (create records, update data, send messages)

Features:

  • Event-Based Triggers: Automation Rules execute when conditions are met (record created, updated, etc.)
  • Time-Based Triggers: Scheduled Actions run on fixed intervals (daily, weekly, monthly)
  • Triggered records automatically included in AI context (Automation Rules only)
  • Non-interactive mode for autonomous operation
  • Asynchronous processing after transaction commit
  • Full tool access (search, read, create, update, delete, execute methods)
  • Optional super assistant mode for administrative tasks

🌐 AI Provider Connectors

ChatGPT Connector (ai_chatgpt_connector_gt)

Purpose: Connects to OpenAI's ChatGPT API.

Configuration:

  • Add 'chatgpt' type to AI configurations
  • Default model: gpt-4.1-mini
  • Requires OpenAI API key

Features:

  • Image support (base64 encoding)
  • Web search

Claude Connector (ai_claude_connector_gt)

Purpose: Connects to Anthropic's Claude API.

Configuration:

  • Add 'claude' type to AI configurations
  • Default model: claude-3-5-haiku-latest
  • Requires Anthropic API key

Features:

  • Image and PDF support
  • Web search

Gemini Connector (ai_gemini_connector_gt)

Purpose: Connects to Google's Gemini API.

Configuration:

  • Add 'gemini' type to AI configurations
  • Default model: gemini-2.5-flash
  • Requires Google API key

Features:

  • Image support (inline data)

🔄 Data Flow Architecture

Request Processing Flow

User Input → AI Thread → Context Building → Tool Selection → 
AI Provider → Response Generation → Tool Execution → 
Final Response → User Interface

Detailed Flow

  1. Input Processing

    • User sends message in Discuss or Livechat
    • System detects AI involvement
    • Creates or finds existing AI thread

  2. Context Building

    • Loads conversation history
    • Applies assistant context and instructions
    • Includes relevant business data

  3. Tool Selection

    • AI decides which tools to use
    • Checks permissions and access rights
    • Prepares tool specifications

  4. AI Provider Call

    • Formats message for specific AI provider
    • Sends request with context and tools
    • Handles provider-specific formatting

  5. Response Processing

    • Parses AI response
    • Executes any tool calls
    • Formats final response

  6. Output Delivery

    • Posts response to user interface
    • Updates conversation history
    • Logs interaction for audit

Error Handling

Network Issues:

  • Automatic retry with exponential backoff
  • Fallback to human operators
  • Error messages to users

API Limits:

  • Rate limiting and quota management
  • Graceful degradation
  • Alternative provider switching

Data Access:

  • Permission checking before operations
  • Safe fallbacks for missing data
  • Audit logging for security

🔧 Technical Implementation

Database Schema

Core Tables:

  • ai.assistant: AI assistant configurations
  • ai.data.source: Data source definitions
  • ai.data.item: Indexed data with embeddings
  • ai.thread: Conversation sessions
  • ai.message: Individual messages
  • ai.context: Assistant contexts and instructions

Relationships:

  • Assistants can access multiple data sources
  • Threads belong to assistants
  • Messages belong to threads
  • Data items belong to data sources

Vector Embeddings

Technology Stack:

  • FastEmbed for embedding generation
  • PostgreSQL with pgvector extension
  • Sentence transformers for multilingual support

Indexing Process:

  1. Data is extracted from sources
  2. Text is processed and cleaned
  3. Embeddings are generated
  4. Vectors are stored in database
  5. Index is created for fast search

Search Process:

  1. Query is converted to embedding
  2. Similarity search is performed
  3. Top results are retrieved
  4. Context is added to AI prompt

Security Model

Access Control:

  • User-based permissions
  • Data source restrictions
  • Tool access limitations
  • Audit trail logging

Data Protection:

  • API key encryption
  • Secure data transmission
  • Privacy-compliant logging
  • Data retention policies

Monitoring:

  • Request/response logging
  • Performance metrics
  • Error tracking
  • Usage analytics

🔮 Extension Points

Custom AI Tools

You can extend the system with custom tools for your specific business needs. The system provides a framework for creating custom tools that AI can use to access your data and perform operations.

New AI Providers

Adding new AI providers involves:

  1. Create Connector Module

    • Extend ai.config with new type
    • Implement provider-specific methods
    • Handle message formatting

  2. Add Provider Logic

    • API client integration
    • Error handling
    • Response parsing

  3. Update Configuration

    • Add provider to selection
    • Configure default models
    • Set up API key management

Custom Data Sources

Extend data source types:

  1. Define Source Type

    • Add to selection field
    • Implement indexing logic
    • Handle data extraction

  2. Add Processing Logic

    • Data cleaning and formatting
    • Embedding generation
    • Search optimization

Ready to install? Check out the Installation Guide or jump to Quick Start.