llmadapter.class.php

Go to the documentation of this file.

<?php
/* Copyright (C) 2026   Laurent Destailleur   <eldy@users.sourceforge.net>
 * Copyright (C) 2026   Nick Fragoulis
 * Copyright (C) 2026   Jose Martinez     <jose.martinez@pichinov.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/>.
 * or see https://www.gnu.org/
 */
 
class UniversalLLMAdapter
{
  public $lastRequest = "";
 
  public $lastResponse = "";
 
  public $lastUsage = array();
 
  private $type;
 
  private $key;
 
  private $baseUrl;
 
  private $model;
 
  private $timeout;
 
  public function __construct(string $type, string $key, string $baseUrl, string $model, int $timeout)
  {
    $this->type = strtolower($type);
    $this->key = $key;
    $this->baseUrl = rtrim($baseUrl, '/');
    $this->model = $model;
    $this->timeout = $timeout;
  }
 
  public function generate(string $system, string $userMsg, string $mode = 'text', array $attachments = array(), array $history = array()): ?string
  {
    switch ($this->type) {
      case 'anthropic':
        return $this->callAnthropic($system, $userMsg, $mode, $attachments, $history);
      case 'google':
        return $this->callGoogle($system, $userMsg, $mode, $attachments, $history);
      default:
        return $this->callOpenAI($system, $userMsg, $mode, $attachments, $history);
    }
  }
 
  private function callOpenAI(string $sys, string $msg, string $mode = 'text', array $attachments = array(), array $history = array()): ?string
  {
    $url = $this->baseUrl;
    if (strpos($url, '/chat/completions') === false && strpos($url, '/generate') === false) {
      $url .= '/chat/completions';
    }
 
    // With attachments, the user content becomes an array of typed parts
    // (vision input); without, it stays a plain string (widest compatibility).
    $userContent = $msg;
    if (!empty($attachments)) {
      $userContent = array(array("type" => "text", "text" => $msg));
      foreach ($attachments as $att) {
        if ($att['mime'] === 'application/pdf') {
          // OpenAI compatible APIs reject non-image MIME inside image_url;
          // PDFs use the dedicated 'file' content part.
          $userContent[] = array(
            "type" => "file",
            "file" => array(
              "filename" => "document.pdf",
              "file_data" => "data:application/pdf;base64,".$att['data']
            )
          );
        } else {
          $userContent[] = array(
            "type" => "image_url",
            "image_url" => array("url" => "data:".$att['mime'].";base64,".$att['data'])
          );
        }
      }
    }
 
    $messages = array(array("role" => "system", "content" => $sys));
    foreach ($history as $turn) {
      $messages[] = array("role" => (($turn['role'] ?? '') === 'assistant' ? 'assistant' : 'user'), "content" => (string) $turn['text']);
    }
    $messages[] = array("role" => "user", "content" => $userContent);
 
    $data = array(
      "model" => $this->model,
      "messages" => $messages,
      "temperature" => 0.1
    );
    if (!empty($attachments)) {
      $data["max_tokens"] = 8192; // a multi-line document (e.g. a delivery note) serializes to an intent JSON far beyond 4096 tokens
    }
 
    // Only force JSON mode if explicitly requested
    // This allows Email/Webpage generation to return raw HTML
    if ($mode === 'json') {
      // Apply to specific providers known to support this parameter safely
      if (strpos($url, 'openai') !== false || strpos($url, 'deepseek') !== false || strpos($url, 'perplexity') !== false || strpos($url, 'mistral') !== false || strpos($url, 'zai') !== false) {
        $data["response_format"] = array("type" => "json_object");
      }
    }
 
    $this->lastRequest = $this->encodeRequestForLog($data);
 
    return $this->curl($url, $data, array("Content-Type: application/json", "Authorization: Bearer " . $this->key));
  }
 
  private function callAnthropic(string $sys, string $msg, string $mode = 'text', array $attachments = array(), array $history = array())
  {
 
    $url = $this->baseUrl . (strpos($this->baseUrl, '/messages') === false ? '/messages' : '');
 
    // With attachments, content becomes an array of typed blocks: PDFs go as
    // 'document' blocks, images as 'image' blocks (Anthropic native formats).
    $userContent = $msg;
    $maxTokens = 1024;
    if (!empty($attachments)) {
      $userContent = array();
      foreach ($attachments as $att) {
        $userContent[] = array(
          "type" => ($att['mime'] === 'application/pdf' ? "document" : "image"),
          // Only application/pdf and image/* reach this point (see
          // ai_validate_attachments()); anything else would 400.
          "source" => array("type" => "base64", "media_type" => $att['mime'], "data" => $att['data'])
        );
      }
      $userContent[] = array("type" => "text", "text" => $msg);
      $maxTokens = 8192;  // a multi-line document (e.g. a delivery note) serializes to an intent JSON far beyond 4096 tokens
    }
 
    $messages = array();
    foreach ($history as $turn) {
      $messages[] = array("role" => (($turn['role'] ?? '') === 'assistant' ? 'assistant' : 'user'), "content" => (string) $turn['text']);
    }
    $messages[] = array("role" => "user", "content" => $userContent);
 
    $data = array(
      "model" => $this->model,
      "system" => $sys,
      "messages" => $messages,
      "max_tokens" => $maxTokens
    );
 
    $this->lastRequest = $this->encodeRequestForLog($data);
 
    return $this->curl($url, $data, array("content-type: application/json", "x-api-key: " . $this->key, "anthropic-version: 2023-06-01"), true);
  }
 
  private function callGoogle(string $sys, string $msg, string $mode = 'text', array $attachments = array(), array $history = array())
  {
    $url = $this->baseUrl;
 
    // Strict type check for string position
    if (strpos($url, ':generateContent') === false) {
      if (strpos($url, '/models/') === false) {
        $url .= "/models/" . $this->model;
      }
      $url .= ":generateContent";
    }
 
    $url .= "?key=" . $this->key;
 
    // With attachments, prepend native inline_data parts (Gemini vision /
    // document understanding) before the text part.
    $parts = array();
    foreach ($attachments as $att) {
      $parts[] = array("inline_data" => array("mime_type" => $att['mime'], "data" => $att['data']));
    }
    $parts[] = array("text" => $sys . "\nUser: " . $msg);
 
    // Single-turn payload stays exactly as before (no 'role' key) so the
    // historical behavior is untouched; only a non-empty history switches
    // to Gemini's multi-turn format, where every content needs its role
    // ('model' is Gemini's name for the assistant role).
    $contents = array();
    if (!empty($history)) {
      foreach ($history as $turn) {
        $contents[] = array(
          "role" => (($turn['role'] ?? '') === 'assistant' ? 'model' : 'user'),
          "parts" => array(array("text" => (string) $turn['text']))
        );
      }
      $contents[] = array("role" => "user", "parts" => $parts);
    } else {
      $contents[] = array("parts" => $parts);
    }
 
    $data = array(
      "contents" => $contents,
      "generationConfig" => (empty($attachments) ? array("temperature" => 0.1) : array("temperature" => 0.1, "maxOutputTokens" => 16384)) // thinking models count their reasoning tokens INSIDE maxOutputTokens: at 4096 a multi-line reception intent came back finishReason=MAX_TOKENS, cut mid-JSON
    );
 
    $this->lastRequest = $this->encodeRequestForLog($data);
 
    return $this->curl($url, $data, array("Content-Type: application/json"), false, true);
  }
 
  private function clearModelFailure()
  {
    global $db, $conf;
 
    if (!is_object($db) || !is_object($conf)) {
      return;
    }
    $raw = getDolGlobalString('AI_MODEL_RUNTIME_FAILURE');
    if ($raw === '') {
      return;
    }
    $rec = json_decode($raw, true);
    if (!is_array($rec) || (string) ($rec['model'] ?? '') !== (string) $this->model) {
      return; // a different model failed: leave that warning standing
    }
    include_once DOL_DOCUMENT_ROOT.'/core/lib/admin.lib.php';
    dolibarr_del_const($db, 'AI_MODEL_RUNTIME_FAILURE', -1);
  }
 
  private function recordModelFailure(int $httpCode, string $msg)
  {
    global $db, $conf;
 
    if (!is_object($db) || !is_object($conf)) {
      return; // no Dolibarr runtime (defensive: adapter may be unit-tested standalone)
    }
    // Only errors that talk about the model itself, not quota/auth/network ones.
    if (!preg_match('/model/i', $msg)) {
      return;
    }
    if (!preg_match('/not.?found|does not exist|not exist|unsupported|not supported|not available|unavailable|deprecated|no longer|retired|invalid/i', $msg)) {
      return;
    }
    include_once DOL_DOCUMENT_ROOT.'/core/lib/admin.lib.php';
    dolibarr_set_const($db, 'AI_MODEL_RUNTIME_FAILURE', json_encode(array(
      // The provider is recorded too: without it the banner survives a
      // change of provider and blames a model nobody is using any more.
      'service' => getDolGlobalString('AI_API_SERVICE'),
      'model' => $this->model,
      'ts' => dol_now(),
      'http_code' => $httpCode,
      'message' => dol_trunc($msg, 300)
    )), 'chaine', 0, '', $conf->entity);
  }
 
  private function encodeRequestForLog(array $data)
  {
    $json = json_encode($data); // compact on purpose: the log budget is 60k chars, and core's json.lib.php polyfill makes 2-arg json_encode a phpstan error
 
    // Unanchored: base64 appears both as bare JSON string values (Anthropic,
    // Google) and embedded inside data: URLs (OpenAI file/image_url parts).
    $out = preg_replace_callback(
      '~((?:[A-Za-z0-9+=]++|\\\\/)+)~',
      static function (array $m) {
        if (strlen($m[1]) < 512) {
          return $m[1]; // short runs (words, urls) stay as they are
        }
 
        return '[base64 elided, '.strlen($m[1]).' chars]';
      },
      $json
    );
 
    return ($out === null) ? $json : $out;
  }
 
  private function curl(string $url, array $data, array $headers, bool $isClaude = false, bool $isGemini = false): ?string
  {
    include_once DOL_DOCUMENT_ROOT.'/core/lib/geturl.lib.php';
 
    // By default, we accept only external endpoints ($dolibarr_ai_allow_local_endpoints is not set).
    // To allow local endpoints, we must set $dolibarr_ai_allow_local_endpoints to 1 or 2 in conf.php.
    global $dolibarr_ai_allow_local_endpoints;
 
    $localurl = empty($dolibarr_ai_allow_local_endpoints) ? 0 : 2;
 
    // Pass $this->timeout as the response timeout so the LLM-specific value configured
    // at construction time is honored (getURLContent's $timeoutresponse is the 10th arg;
    // preceding args $ssl_verifypeer=-1 and $timeoutconnect=0 keep their defaults).
    $this->lastUsage = array(); // never carry over the previous call's usage
 
    $result = getURLContent($url, 'POST', json_encode($data), 1, $headers, array('http', 'https'), $localurl, -1, 0, $this->timeout);
 
    $body         = (string) ($result['content'] ?? '');
    $httpCode     = (int) ($result['http_code'] ?? 0);
    $effectiveUrl = (string) ($result['url'] ?? $url);
    // The Gemini key travels as a ?key= query parameter: mask it before the
    // URL lands in lastResponse, which is persisted into llx_ai_request_log
    // and shown by the admin Log Viewer - a secret must never sit in a log.
    $effectiveUrl = preg_replace('/([?&]key=)[^&\s]+/', '$1***', $effectiveUrl);
    // Store an enriched payload so the admin Log Viewer ("VIEW LOGS" in the AI Server
    // MCP setup page) shows something actionable when something goes wrong, not just
    // a bare "Invalid JSON response from API." with an empty body.
    $this->lastResponse = "HTTP " . $httpCode . " from " . $effectiveUrl . "\n--- body (" . strlen($body) . " bytes) ---\n" . $body;
 
    if (!empty($result['curl_error_no'])) {
      return "Error: cURL #" . $result['curl_error_no'] . " " . $result['curl_error_msg'] . " (url=" . $effectiveUrl . ")";
    }
 
    $json = json_decode($body, true);
 
    if ($json === null && json_last_error() !== JSON_ERROR_NONE) {
      // Common real-world causes: HTTP 4xx/5xx with empty body, HTML error page
      // from a proxy, gateway timeout, etc. Surface the HTTP code and a short
      // body snippet so the admin can diagnose without re-running with curl.
      $snippet = substr($body, 0, 500);
      return "Error: Invalid JSON response from API (HTTP " . $httpCode . ", " . strlen($body) . " bytes). Body snippet: " . ($snippet !== '' ? $snippet : '<empty>');
    }
 
    if (isset($json['error'])) {
      $msg = $json['error']['message'] ?? json_encode($json['error']);
      $this->recordModelFailure($httpCode, (string) $msg);
      return "Error: API " . $msg;
    }
 
    // Token usage as reported by the provider, for the cost columns of the
    // request log: every provider returns it inside the response body under
    // its own name. Thinking tokens are billed as output, so Gemini's
    // thoughtsTokenCount is counted with the visible candidates tokens.
    // The call succeeded: a warning recorded for this same model is now stale.
    $this->clearModelFailure();
 
    $this->lastUsage = array('model' => $this->model);
    if ($isGemini) {
      $this->lastUsage['input']  = (int) ($json['usageMetadata']['promptTokenCount'] ?? 0);
      $this->lastUsage['output'] = (int) ($json['usageMetadata']['candidatesTokenCount'] ?? 0) + (int) ($json['usageMetadata']['thoughtsTokenCount'] ?? 0);
    } elseif ($isClaude) {
      $this->lastUsage['input']  = (int) ($json['usage']['input_tokens'] ?? 0);
      $this->lastUsage['output'] = (int) ($json['usage']['output_tokens'] ?? 0);
    } else {
      $this->lastUsage['input']  = (int) ($json['usage']['prompt_tokens'] ?? 0);
      $this->lastUsage['output'] = (int) ($json['usage']['completion_tokens'] ?? 0);
    }
 
    // Extraction Logic
    if ($isClaude) {
      return $json['content'][0]['text'] ?? null;
    }
    if ($isGemini) {
      return $json['candidates'][0]['content']['parts'][0]['text'] ?? null;
    }
 
    // Default (OpenAI compatible)
    return $json['choices'][0]['message']['content'] ?? null;
  }
}