email_cleaner.class.php

Go to the documentation of this file.

<?php
/* Copyright (C) 2026  Braito                  <braito4@hotmail.com>
 * Copyright (C) 2026   MDW           <mdeweerd@users.noreply.github.com>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see <https://www.gnu.org/licenses/>.
 */
 
class ToolEmailCleaner extends McpTool
{
  private const TABLE_AI_REQUEST_LOG = 'ai_request_log';
  private const TOOL_NAME = 'email_cleaner';
 
  private $tableExistsCache = array();
 
  public function getDefinitions(): array
  {
    if (!isModEnabled('emailcollector') || !getDolGlobalInt('AI_EMAILCLEANER_ENABLED', 0)) {
      return [];
    }
 
    return [
      [
        'name' => 'list_email_cleaner_runs',
        'description' => 'List EmailCollector AI cleaner runs logged in the shared AI request log. Technical metadata only, no business interpretation.',
        'inputSchema' => [
          'type' => 'object',
          'properties' => [
            'actioncomm_id' => ['type' => 'integer', 'description' => 'Optional agenda event id filter.'],
            'collector_id' => ['type' => 'integer', 'description' => 'Optional collector id filter.'],
            'message_id' => ['type' => 'string', 'description' => 'Optional message-id filter.'],
            'context_profile_code' => ['type' => 'string', 'description' => 'Optional context profile filter.'],
            'min_confidence' => ['type' => 'number', 'description' => 'Optional minimum cleaning confidence (0..1).'],
            'max_confidence' => ['type' => 'number', 'description' => 'Optional maximum cleaning confidence (0..1).'],
            'limit' => ['type' => 'integer', 'default' => 20],
            'offset' => ['type' => 'integer', 'default' => 0],
          ],
        ],
      ],
      [
        'name' => 'get_email_cleaner_run',
        'description' => 'Get one EmailCollector AI cleaner run from the shared AI request log.',
        'inputSchema' => [
          'type' => 'object',
          'properties' => [
            'ai_request_log_id' => ['type' => 'integer', 'description' => 'AI request log rowid.'],
            'cleaning_id' => ['type' => 'integer', 'description' => 'Backward-compatible alias for ai_request_log_id.'],
            'message_id' => ['type' => 'string', 'description' => 'Message-id fallback selector.'],
            'collector_id' => ['type' => 'integer', 'description' => 'Optional collector filter when using message_id.'],
          ],
          'anyOf' => [
            ['required' => ['ai_request_log_id']],
            ['required' => ['cleaning_id']],
            ['required' => ['message_id']],
          ],
        ],
      ],
      [
        'name' => 'get_email_thread_context',
        'description' => 'Get only the technical email thread context extracted by EmailCleaner. No business interpretation.',
        'inputSchema' => [
          'type' => 'object',
          'properties' => [
            'ai_request_log_id' => ['type' => 'integer', 'description' => 'AI request log rowid.'],
            'cleaning_id' => ['type' => 'integer', 'description' => 'Backward-compatible alias for ai_request_log_id.'],
            'message_id' => ['type' => 'string', 'description' => 'Message-id fallback selector.'],
            'collector_id' => ['type' => 'integer', 'description' => 'Optional collector filter when using message_id.'],
          ],
          'anyOf' => [
            ['required' => ['ai_request_log_id']],
            ['required' => ['cleaning_id']],
            ['required' => ['message_id']],
          ],
        ],
      ],
      [
        'name' => 'get_email_handoff_payload',
        'description' => 'Get handoff payload generated by EmailCleaner from the shared AI request log. Evidence only, no decision.',
        'inputSchema' => [
          'type' => 'object',
          'properties' => [
            'ai_request_log_id' => ['type' => 'integer', 'description' => 'AI request log rowid.'],
            'handoff_id' => ['type' => 'integer', 'description' => 'Backward-compatible alias for ai_request_log_id.'],
            'cleaning_id' => ['type' => 'integer', 'description' => 'Backward-compatible alias for ai_request_log_id.'],
          ],
          'anyOf' => [
            ['required' => ['ai_request_log_id']],
            ['required' => ['handoff_id']],
            ['required' => ['cleaning_id']],
          ],
        ],
      ],
    ];
  }
 
  public function getCategories(): array
  {
    return ['global'];
  }
 
  public function execute(string $name, array $args)
  {
    if (!$this->canReadEmailData()) {
      return $this->appendComplianceMetadata(['error' => "Permission Denied: You don't have rights to read email cleaner data."]);
    }
 
    $result = array();
    switch ($name) {
      case 'list_email_cleaner_runs':
        $result = $this->listEmailCleanerRuns($args);
        break;
 
      case 'get_email_cleaner_run':
        $result = $this->getEmailCleanerRun($args);
        break;
 
      case 'get_email_thread_context':
        $result = $this->getEmailThreadContext($args);
        break;
 
      case 'get_email_handoff_payload':
        $result = $this->getEmailHandoffPayload($args);
        break;
 
      default:
        $result = ['error' => "Tool function '$name' not found."];
        break;
    }
 
    return $this->appendComplianceMetadata($result);
  }
 
  private function canReadEmailData(): bool
  {
    if (empty($this->user->id)) {
      return false;
    }
    if (!is_object($this->conf) || !isModEnabled('ai')) {
      return false;
    }
    if (!isModEnabled('emailcollector')) {
      return false;
    }
    if (!getDolGlobalInt('AI_EMAILCLEANER_ENABLED', 0)) {
      return false;
    }
    if (!empty($this->user->admin)) {
      return true;
    }
    if (method_exists($this->user, 'hasRight') && $this->user->hasRight('emailcollector', 'read')) {
      return true;
    }
    return false;
  }
 
  private function listEmailCleanerRuns(array $args): array
  {
    if (!$this->isTableAvailable(self::TABLE_AI_REQUEST_LOG)) {
      return ['error' => 'AI request log table is not available.'];
    }
 
    $entity = (int) (!empty($this->conf->entity) ? $this->conf->entity : 1);
    $limit = $this->sanitizeLimit($args['limit'] ?? 20);
    $offset = max(0, (int) ($args['offset'] ?? 0));
    $actioncommId = (int) ($args['actioncomm_id'] ?? 0);
    $collectorId = (int) ($args['collector_id'] ?? 0);
    $messageId = trim((string) ($args['message_id'] ?? ''));
    $contextProfileCode = trim((string) ($args['context_profile_code'] ?? ''));
    $minConfidence = $this->sanitizeConfidenceOrNull($args['min_confidence'] ?? null);
    $maxConfidence = $this->sanitizeConfidenceOrNull($args['max_confidence'] ?? null);
 
    $sql = "SELECT rowid, fk_actioncomm, provider, confidence, status, raw_request_payload, date_request";
    $sql .= " FROM ".MAIN_DB_PREFIX.self::TABLE_AI_REQUEST_LOG;
    $sql .= " WHERE entity = ".((int) $entity);
    $sql .= " AND tool_name = '".$this->db->escape(self::TOOL_NAME)."'";
 
    if ($actioncommId > 0) {
      $sql .= " AND fk_actioncomm = ".((int) $actioncommId);
    }
    if ($collectorId > 0) {
      $sql .= " AND raw_request_payload LIKE '%\"collector_id\":".((int) $collectorId)."%'";
    }
    if ($messageId !== '') {
      $sql .= " AND raw_request_payload LIKE '%".$this->db->escape($messageId)."%'";
    }
    if ($contextProfileCode !== '') {
      $sql .= " AND raw_request_payload LIKE '%".$this->db->escape($contextProfileCode)."%'";
    }
    if ($minConfidence !== null) {
      $sql .= " AND confidence >= ".((float) $minConfidence);
    }
    if ($maxConfidence !== null) {
      $sql .= " AND confidence <= ".((float) $maxConfidence);
    }
 
    $sql .= " ORDER BY rowid DESC";
    $sql .= $this->db->plimit($limit, $offset);
 
    $resql = $this->db->query($sql);
    if (!$resql) {
      return ['error' => 'Database error while listing email cleaner runs: '.$this->db->lasterror()];
    }
 
    $items = array();
    while ($obj = $this->db->fetch_object($resql)) {
      $inputMetadata = $this->decodeJsonOrRaw((string) $obj->raw_request_payload);
      $items[] = array(
        'ai_request_log_id' => (int) $obj->rowid,
        'cleaning_id' => (int) $obj->rowid,
        'actioncomm_id' => (int) $obj->fk_actioncomm,
        'collector_id' => (!empty($inputMetadata['collector_id']) ? (int) $inputMetadata['collector_id'] : null),
        'message_id' => (!empty($inputMetadata['message_id']) ? (string) $inputMetadata['message_id'] : null),
        'cleaning_confidence' => (float) $obj->confidence,
        'cleaning_model' => null,
        'prompt_code' => (!empty($inputMetadata['prompt_code']) ? (string) $inputMetadata['prompt_code'] : null),
        'prompt_version' => (!empty($inputMetadata['prompt_version']) ? (string) $inputMetadata['prompt_version'] : null),
        'context_profile_code' => (!empty($inputMetadata['context_profile_code']) ? (string) $inputMetadata['context_profile_code'] : null),
        'context_profile_version' => (!empty($inputMetadata['context_profile_version']) ? (string) $inputMetadata['context_profile_version'] : null),
        'status' => (!empty($obj->status) ? (string) $obj->status : null),
        'date_creation' => (!empty($obj->date_request) ? (string) $obj->date_request : null),
      );
    }
    $this->db->free($resql);
 
    return array(
      'items' => $items,
      'count' => count($items),
      'filters' => array(
        'entity' => $entity,
        'actioncomm_id' => ($actioncommId > 0 ? $actioncommId : null),
        'collector_id' => ($collectorId > 0 ? $collectorId : null),
        'message_id' => ($messageId !== '' ? $messageId : null),
        'context_profile_code' => ($contextProfileCode !== '' ? $contextProfileCode : null),
        'min_confidence' => $minConfidence,
        'max_confidence' => $maxConfidence,
        'limit' => $limit,
        'offset' => $offset,
      ),
    );
  }
 
  private function getEmailCleanerRun(array $args): array
  {
    if (!$this->isTableAvailable(self::TABLE_AI_REQUEST_LOG)) {
      return ['error' => 'AI request log table is not available.'];
    }
 
    $entity = (int) (!empty($this->conf->entity) ? $this->conf->entity : 1);
    $aiRequestLogId = (int) ($args['ai_request_log_id'] ?? ($args['cleaning_id'] ?? 0));
    $messageId = trim((string) ($args['message_id'] ?? ''));
    $collectorId = (int) ($args['collector_id'] ?? 0);
 
    $sql = "SELECT rowid, entity, fk_actioncomm, provider, input_hash, output_hash, security_hash, confidence, status, raw_request_payload, raw_response_payload, date_request";
    $sql .= " FROM ".MAIN_DB_PREFIX.self::TABLE_AI_REQUEST_LOG;
    $sql .= " WHERE entity = ".((int) $entity);
    $sql .= " AND tool_name = '".$this->db->escape(self::TOOL_NAME)."'";
 
    if ($aiRequestLogId > 0) {
      $sql .= " AND rowid = ".((int) $aiRequestLogId);
    } elseif ($messageId !== '') {
      $sql .= " AND raw_request_payload LIKE '%".$this->db->escape($messageId)."%'";
      if ($collectorId > 0) {
        $sql .= " AND raw_request_payload LIKE '%\"collector_id\":".((int) $collectorId)."%'";
      }
      $sql .= " ORDER BY rowid DESC";
    } else {
      return ['error' => "Missing selector: use 'ai_request_log_id', 'cleaning_id' or 'message_id'."];
    }
 
    $sql .= $this->db->plimit(1);
 
    $resql = $this->db->query($sql);
    if (!$resql) {
      return ['error' => 'Database error while reading cleaner run: '.$this->db->lasterror()];
    }
    $obj = $this->db->fetch_object($resql);
    $this->db->free($resql);
    if (!$obj) {
      return ['error' => 'Email cleaner run not found.'];
    }
 
    $inputMetadata = $this->decodeJsonOrRaw((string) $obj->raw_request_payload);
    $outputJson = $this->decodeJsonOrRaw((string) $obj->raw_response_payload);
    $handoffJson = (!empty($outputJson['handoff_payload_json']) && is_array($outputJson['handoff_payload_json'])) ? $outputJson['handoff_payload_json'] : array();
 
    return array(
      'ai_request_log_id' => (int) $obj->rowid,
      'cleaning_id' => (int) $obj->rowid,
      'entity' => (int) $obj->entity,
      'actioncomm_id' => (int) $obj->fk_actioncomm,
      'collector_id' => (!empty($inputMetadata['collector_id']) ? (int) $inputMetadata['collector_id'] : 0),
      'message_id' => (!empty($inputMetadata['message_id']) ? (string) $inputMetadata['message_id'] : ''),
      'raw_hash' => (!empty($inputMetadata['raw_hash']) ? (string) $inputMetadata['raw_hash'] : null),
      'clean_hash' => (!empty($inputMetadata['clean_hash']) ? (string) $inputMetadata['clean_hash'] : null),
      'clean_body' => (!empty($outputJson['clean_body']) ? (string) $outputJson['clean_body'] : ''),
      'cleaning_confidence' => (float) $obj->confidence,
      'cleaning_model' => (!empty($outputJson['cleaning_model']) ? (string) $outputJson['cleaning_model'] : null),
      'prompt_code' => (!empty($inputMetadata['prompt_code']) ? (string) $inputMetadata['prompt_code'] : null),
      'prompt_version' => (!empty($inputMetadata['prompt_version']) ? (string) $inputMetadata['prompt_version'] : null),
      'context_profile_code' => (!empty($inputMetadata['context_profile_code']) ? (string) $inputMetadata['context_profile_code'] : null),
      'context_profile_version' => (!empty($inputMetadata['context_profile_version']) ? (string) $inputMetadata['context_profile_version'] : null),
      'input_hash' => (!empty($obj->input_hash) ? (string) $obj->input_hash : null),
      'output_hash' => (!empty($obj->output_hash) ? (string) $obj->output_hash : null),
      'security_hash' => (!empty($obj->security_hash) ? (string) $obj->security_hash : null),
      'status' => (!empty($obj->status) ? (string) $obj->status : null),
      'raw_request_payload' => $inputMetadata,
      'cleaning_json' => $outputJson,
      'handoff_payload_json' => $handoffJson,
      'date_creation' => (!empty($obj->date_request) ? (string) $obj->date_request : null),
    );
  }
 
  private function getEmailThreadContext(array $args): array
  {
    $run = $this->getEmailCleanerRun($args);
    if (!empty($run['error'])) {
      return $run;
    }
 
    $cleaningJson = (!empty($run['cleaning_json']) && is_array($run['cleaning_json'])) ? $run['cleaning_json'] : array();
    $handoffJson = (!empty($run['handoff_payload_json']) && is_array($run['handoff_payload_json'])) ? $run['handoff_payload_json'] : array();
    $emailContext = array();
 
    if (!empty($cleaningJson['email_context']) && is_array($cleaningJson['email_context'])) {
      $emailContext = $cleaningJson['email_context'];
    } elseif (!empty($handoffJson['conversation_context']) && is_array($handoffJson['conversation_context'])) {
      $emailContext = $handoffJson['conversation_context'];
    }
 
    return array(
      'ai_request_log_id' => (int) $run['ai_request_log_id'],
      'cleaning_id' => (int) $run['cleaning_id'],
      'actioncomm_id' => (int) $run['actioncomm_id'],
      'collector_id' => (int) $run['collector_id'],
      'message_id' => (string) $run['message_id'],
      'email_context' => $emailContext,
      'cleaning_confidence' => (float) $run['cleaning_confidence'],
      'context_profile_code' => (!empty($run['context_profile_code']) ? (string) $run['context_profile_code'] : null),
      'context_profile_version' => (!empty($run['context_profile_version']) ? (string) $run['context_profile_version'] : null),
    );
  }
 
  private function getEmailHandoffPayload(array $args): array
  {
    $aiRequestLogId = (int) ($args['ai_request_log_id'] ?? ($args['handoff_id'] ?? ($args['cleaning_id'] ?? 0)));
    if ($aiRequestLogId <= 0) {
      return ['error' => "Missing selector: use 'ai_request_log_id', 'handoff_id' or 'cleaning_id'."];
    }
 
    $run = $this->getEmailCleanerRun(array('ai_request_log_id' => $aiRequestLogId));
    if (!empty($run['error'])) {
      return $run;
    }
 
    return array(
      'ai_request_log_id' => (int) $run['ai_request_log_id'],
      'handoff_id' => (int) $run['ai_request_log_id'],
      'cleaning_id' => (int) $run['cleaning_id'],
      'actioncomm_id' => (int) $run['actioncomm_id'],
      'handoff_version' => (!empty($run['handoff_payload_json']['handoff_version']) ? (string) $run['handoff_payload_json']['handoff_version'] : null),
      'consumer_code' => 'generic',
      'payload_json' => $run['handoff_payload_json'],
      'payload_hash' => (!empty($run['output_hash']) ? (string) $run['output_hash'] : null),
      'quality_status' => (!empty($run['status']) ? (string) $run['status'] : null),
      'date_creation' => (!empty($run['date_creation']) ? (string) $run['date_creation'] : null),
    );
  }
 
  private function isTableAvailable(string $tableWithoutPrefix): bool
  {
    if (isset($this->tableExistsCache[$tableWithoutPrefix])) {
      return $this->tableExistsCache[$tableWithoutPrefix];
    }
 
    $full = MAIN_DB_PREFIX.$tableWithoutPrefix;
    $ok = (bool) count($this->db->DDLInfoTable($full));
    $this->tableExistsCache[$tableWithoutPrefix] = $ok;
 
    return $ok;
  }
 
  private function decodeJsonOrRaw(string $raw)
  {
    $raw = trim($raw);
    if ($raw === '') {
      return array();
    }
    $dec = json_decode($raw, true);
    if (json_last_error() === JSON_ERROR_NONE && is_array($dec)) {
      return $dec;
    }
    return $raw;
  }
 
  private function sanitizeLimit($raw): int
  {
    $limit = (int) $raw;
    if ($limit <= 0) {
      $limit = 20;
    }
    if ($limit > 200) {
      $limit = 200;
    }
    return $limit;
  }
 
  private function sanitizeConfidenceOrNull($raw): ?float
  {
    if ($raw === null || $raw === '') {
      return null;
    }
    $val = (float) $raw;
    if ($val < 0) {
      $val = 0;
    }
    if ($val > 1) {
      $val = 1;
    }
    return $val;
  }
 
  private function appendComplianceMetadata(array $result): array
  {
    $result['compliance'] = array(
      'ai_transparency_label' => 'AI-derived technical evidence',
      'human_review_required' => 1,
      'autonomous_business_action_allowed' => 0,
      'policy_scope' => 'diagnostic_only_no_business_decision',
    );
 
    return $result;
  }
}