dolibarr 25.0.0-alpha
llmadapter.class.php
Go to the documentation of this file.
1<?php
2/* Copyright (C) 2026 Laurent Destailleur <eldy@users.sourceforge.net>
3 * Copyright (C) 2026 Nick Fragoulis
4 * Copyright (C) 2026 Jose Martinez <jose.martinez@pichinov.com>
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 3 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY, without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program. If not, see <https://www.gnu.org/licenses/>.
18 * or see https://www.gnu.org/
19 */
20
28{
30 public $lastRequest = "";
31
33 public $lastResponse = "";
34
36 public $lastUsage = array();
37
39 private $type;
40
42 private $key;
43
45 private $baseUrl;
46
48 private $model;
49
51 private $timeout;
52
54 private $maxTokens = 0;
55
65 public function __construct(string $type, string $key, string $baseUrl, string $model, int $timeout)
66 {
67 $this->type = strtolower($type);
68 $this->key = $key;
69 $this->baseUrl = rtrim($baseUrl, '/');
70 $this->model = $model;
71 $this->timeout = $timeout;
72 }
73
81 public function setMaxTokens(int $maxTokens): bool
82 {
83 $this->maxTokens = max(0, $maxTokens);
84
85 return true;
86 }
87
102 public function generate(string $system, string $userMsg, string $mode = 'text', array $attachments = array(), array $history = array()): ?string
103 {
104 switch ($this->type) {
105 case 'anthropic':
106 return $this->callAnthropic($system, $userMsg, $mode, $attachments, $history);
107 case 'google':
108 return $this->callGoogle($system, $userMsg, $mode, $attachments, $history);
109 default:
110 return $this->callOpenAI($system, $userMsg, $mode, $attachments, $history);
111 }
112 }
113
124 private function callOpenAI(string $sys, string $msg, string $mode = 'text', array $attachments = array(), array $history = array()): ?string
125 {
126 $url = $this->baseUrl;
127 if (strpos($url, '/chat/completions') === false && strpos($url, '/generate') === false) {
128 $url .= '/chat/completions';
129 }
130
131 // With attachments, the user content becomes an array of typed parts
132 // (vision input); without, it stays a plain string (widest compatibility).
133 $userContent = $msg;
134 if (!empty($attachments)) {
135 $userContent = array(array("type" => "text", "text" => $msg));
136 foreach ($attachments as $att) {
137 if ($att['mime'] === 'application/pdf') {
138 // OpenAI compatible APIs reject non-image MIME inside image_url;
139 // PDFs use the dedicated 'file' content part.
140 $userContent[] = array(
141 "type" => "file",
142 "file" => array(
143 "filename" => "document.pdf",
144 "file_data" => "data:application/pdf;base64,".$att['data']
145 )
146 );
147 } else {
148 $userContent[] = array(
149 "type" => "image_url",
150 "image_url" => array("url" => "data:".$att['mime'].";base64,".$att['data'])
151 );
152 }
153 }
154 }
155
156 $messages = array(array("role" => "system", "content" => $sys));
157 foreach ($history as $turn) {
158 $messages[] = array("role" => (($turn['role'] ?? '') === 'assistant' ? 'assistant' : 'user'), "content" => (string) $turn['text']);
159 }
160 $messages[] = array("role" => "user", "content" => $userContent);
161
162 $data = array(
163 "model" => $this->model,
164 "messages" => $messages,
165 "temperature" => 0.1
166 );
167 if ($this->maxTokens > 0) {
168 $data["max_tokens"] = $this->maxTokens;
169 } elseif (!empty($attachments)) {
170 $data["max_tokens"] = 8192; // a multi-line document (e.g. a delivery note) serializes to an intent JSON far beyond 4096 tokens
171 }
172
173 // Only force JSON mode if explicitly requested
174 // This allows Email/Webpage generation to return raw HTML
175 if ($mode === 'json') {
176 // Apply to specific providers known to support this parameter safely
177 if (strpos($url, 'openai') !== false || strpos($url, 'deepseek') !== false || strpos($url, 'perplexity') !== false || strpos($url, 'mistral') !== false || strpos($url, 'zai') !== false) {
178 $data["response_format"] = array("type" => "json_object");
179 }
180 }
181
182 $this->lastRequest = $this->encodeRequestForLog($data);
183
184 if (getDolGlobalString("AI_DEBUG")) {
185 dol_syslog('callOpenAI url='.$url, LOG_DEBUG, 0, '_ai');
186 }
187
188 $answer = $this->curl($url, $data, array("Content-Type: application/json", "Authorization: Bearer " . $this->key));
189
190 return $answer;
191 }
192
204 private function callAnthropic(string $sys, string $msg, string $mode = 'text', array $attachments = array(), array $history = array())
205 {
206
207 $url = $this->baseUrl . (strpos($this->baseUrl, '/messages') === false ? '/messages' : '');
208
209 // With attachments, content becomes an array of typed blocks: PDFs go as
210 // 'document' blocks, images as 'image' blocks (Anthropic native formats).
211 $userContent = $msg;
212 $maxTokens = 1024;
213 if (!empty($attachments)) {
214 $userContent = array();
215 foreach ($attachments as $att) {
216 $userContent[] = array(
217 "type" => ($att['mime'] === 'application/pdf' ? "document" : "image"),
218 // Only application/pdf and image/* reach this point (see
219 // ai_validate_attachments()); anything else would 400.
220 "source" => array("type" => "base64", "media_type" => $att['mime'], "data" => $att['data'])
221 );
222 }
223 $userContent[] = array("type" => "text", "text" => $msg);
224 $maxTokens = 8192; // a multi-line document (e.g. a delivery note) serializes to an intent JSON far beyond 4096 tokens
225 }
226
227 $messages = array();
228 foreach ($history as $turn) {
229 $messages[] = array("role" => (($turn['role'] ?? '') === 'assistant' ? 'assistant' : 'user'), "content" => (string) $turn['text']);
230 }
231 $messages[] = array("role" => "user", "content" => $userContent);
232
233 $data = array(
234 "model" => $this->model,
235 "system" => $sys,
236 "messages" => $messages,
237 "max_tokens" => ($this->maxTokens > 0 ? $this->maxTokens : $maxTokens)
238 );
239
240 $this->lastRequest = $this->encodeRequestForLog($data);
241
242 return $this->curl($url, $data, array("content-type: application/json", "x-api-key: " . $this->key, "anthropic-version: 2023-06-01"), true);
243 }
244
256 private function callGoogle(string $sys, string $msg, string $mode = 'text', array $attachments = array(), array $history = array())
257 {
258 $url = $this->baseUrl;
259
260 // Strict type check for string position
261 if (strpos($url, ':generateContent') === false) {
262 if (strpos($url, '/models/') === false) {
263 $url .= "/models/" . $this->model;
264 }
265 $url .= ":generateContent";
266 }
267
268 $url .= "?key=" . $this->key;
269
270 // With attachments, prepend native inline_data parts (Gemini vision /
271 // document understanding) before the text part.
272 $parts = array();
273 foreach ($attachments as $att) {
274 $parts[] = array("inline_data" => array("mime_type" => $att['mime'], "data" => $att['data']));
275 }
276 $parts[] = array("text" => $sys . "\nUser: " . $msg);
277
278 // Single-turn payload stays exactly as before (no 'role' key) so the
279 // historical behavior is untouched; only a non-empty history switches
280 // to Gemini's multi-turn format, where every content needs its role
281 // ('model' is Gemini's name for the assistant role).
282 $contents = array();
283 if (!empty($history)) {
284 foreach ($history as $turn) {
285 $contents[] = array(
286 "role" => (($turn['role'] ?? '') === 'assistant' ? 'model' : 'user'),
287 "parts" => array(array("text" => (string) $turn['text']))
288 );
289 }
290 $contents[] = array("role" => "user", "parts" => $parts);
291 } else {
292 $contents[] = array("parts" => $parts);
293 }
294
295 $data = array(
296 "contents" => $contents,
297 "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
298 );
299 if ($this->maxTokens > 0) {
300 $data["generationConfig"]["maxOutputTokens"] = $this->maxTokens;
301 }
302
303 $this->lastRequest = $this->encodeRequestForLog($data);
304
305 return $this->curl($url, $data, array("Content-Type: application/json"), false, true);
306 }
307
313 private function clearModelFailure()
314 {
315 global $db, $conf;
316
317 if (!is_object($db) || !is_object($conf)) {
318 return;
319 }
320 $raw = getDolGlobalString('AI_MODEL_RUNTIME_FAILURE');
321 if ($raw === '') {
322 return;
323 }
324 $rec = json_decode($raw, true);
325 if (!is_array($rec) || (string) ($rec['model'] ?? '') !== (string) $this->model) {
326 return; // a different model failed: leave that warning standing
327 }
328 include_once DOL_DOCUMENT_ROOT.'/core/lib/admin.lib.php';
329 dolibarr_del_const($db, 'AI_MODEL_RUNTIME_FAILURE', -1);
330 }
331
339 public static function isModelUnavailableError(string $msg): bool
340 {
341 // Only errors that talk about the model itself, not quota/auth/network ones.
342 if (!preg_match('/model/i', $msg)) {
343 return false;
344 }
345 return (bool) preg_match('/not.?found|does not exist|not exist|unsupported|not supported|not available|unavailable|deprecated|no longer|retired|invalid/i', $msg);
346 }
347
359 private function recordModelFailure(int $httpCode, string $msg)
360 {
361 global $db, $conf;
362
363 if (!is_object($db) || !is_object($conf)) {
364 return; // no Dolibarr runtime (defensive: adapter may be unit-tested standalone)
365 }
366 if (!self::isModelUnavailableError($msg)) {
367 return;
368 }
369 include_once DOL_DOCUMENT_ROOT.'/core/lib/admin.lib.php';
370 dolibarr_set_const($db, 'AI_MODEL_RUNTIME_FAILURE', json_encode(array(
371 // The provider is recorded too: without it the banner survives a
372 // change of provider and blames a model nobody is using any more.
373 'service' => getDolGlobalString('AI_API_SERVICE'),
374 'model' => $this->model,
375 'ts' => dol_now(),
376 'http_code' => $httpCode,
377 'message' => dol_trunc($msg, 300)
378 )), 'chaine', 0, '', $conf->entity);
379 }
380
390 private function encodeRequestForLog(array $data)
391 {
392 $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
393
394 // Unanchored: base64 appears both as bare JSON string values (Anthropic,
395 // Google) and embedded inside data: URLs (OpenAI file/image_url parts).
396 $out = preg_replace_callback(
397 '~((?:[A-Za-z0-9+=]++|\\\\/)+)~',
402 static function (array $m) {
403 if (strlen($m[1]) < 512) {
404 return $m[1]; // short runs (words, urls) stay as they are
405 }
406
407 return '[base64 elided, '.strlen($m[1]).' chars]';
408 },
409 $json
410 );
411
412 return ($out === null) ? $json : $out;
413 }
414
425 private function curl(string $url, array $data, array $headers, bool $isClaude = false, bool $isGemini = false): ?string
426 {
427 include_once DOL_DOCUMENT_ROOT.'/core/lib/geturl.lib.php';
428
429 // By default, we accept only external endpoints ($dolibarr_ai_allow_local_endpoints is not set).
430 // To allow local endpoints, we must set $dolibarr_ai_allow_local_endpoints to 1 or 2 in conf.php.
431 global $dolibarr_ai_allow_local_endpoints;
432
433 $localurl = empty($dolibarr_ai_allow_local_endpoints) ? 0 : 2;
434
435 // Pass $this->timeout as the response timeout so the LLM-specific value configured
436 // at construction time is honored (getURLContent's $timeoutresponse is the 10th arg;
437 // preceding args $ssl_verifypeer=-1 and $timeoutconnect=0 keep their defaults).
438 $this->lastUsage = array(); // never carry over the previous call's usage
439
440 $result = getURLContent($url, 'POST', json_encode($data), 1, $headers, array('http', 'https'), $localurl, -1, 0, $this->timeout);
441
442 $body = (string) ($result['content'] ?? '');
443 $httpCode = (int) ($result['http_code'] ?? 0);
444 $effectiveUrl = (string) ($result['url'] ?? $url);
445 // The Gemini key travels as a ?key= query parameter: mask it before the
446 // URL lands in lastResponse, which is persisted into llx_ai_request_log
447 // and shown by the admin Log Viewer - a secret must never sit in a log.
448 $effectiveUrl = preg_replace('/([?&]key=)[^&\s]+/', '$1***', $effectiveUrl);
449 // Store an enriched payload so the admin Log Viewer ("VIEW LOGS" in the AI Server
450 // MCP setup page) shows something actionable when something goes wrong, not just
451 // a bare "Invalid JSON response from API." with an empty body.
452 $this->lastResponse = "HTTP " . $httpCode . " from " . $effectiveUrl . "\n--- body (" . strlen($body) . " bytes) ---\n" . $body;
453
454 if (getDolGlobalString("AI_DEBUG")) {
455 dol_syslog('curl answer received, HTTP = '.$httpCode.', size of response string = '.strlen($body), LOG_DEBUG, 0, '_ai');
456 }
457
458 if (!empty($result['curl_error_no'])) {
459 if (getDolGlobalString("AI_DEBUG")) {
460 dol_syslog("Error: cURL #" . $result['curl_error_no'] . " " . $result['curl_error_msg'] . " (url=" . $effectiveUrl . ")", LOG_DEBUG, 0, '_ai');
461 }
462 return "Error: cURL #" . $result['curl_error_no'] . " " . $result['curl_error_msg'] . " (url=" . $effectiveUrl . ")";
463 }
464
465 $json = json_decode($body, true);
466
467 if (getDolGlobalString("AI_DEBUG")) {
468 dol_syslog("curl answer body=" . var_export($body, true), LOG_DEBUG, 0, '_ai');
469 dol_syslog("curl answer json_decoded=" . var_export($json, true), LOG_DEBUG, 0, '_ai');
470 }
471
472 if ($json === null && json_last_error() !== JSON_ERROR_NONE) {
473 // Common real-world causes: HTTP 4xx/5xx with empty body, HTML error page
474 // from a proxy, gateway timeout, etc. Surface the HTTP code and a short
475 // body snippet so the admin can diagnose without re-running with curl.
476 $snippet = substr($body, 0, 500);
477 if (getDolGlobalString("AI_DEBUG")) {
478 dol_syslog("Error: Invalid JSON response from API (HTTP " . $httpCode . ", " . strlen($body) . " bytes). Body snippet: " . ($snippet !== '' ? $snippet : '<empty>'), LOG_DEBUG, 0, '_ai');
479 }
480 return "Error: Invalid JSON response from API (HTTP " . $httpCode . ", " . strlen($body) . " bytes). Body snippet: " . ($snippet !== '' ? $snippet : '<empty>');
481 }
482
483 // Error formats: {"error":{"message":...}} (OpenAI, Anthropic, Gemini) or
484 // {"object":"error","message":...} (Mistral), with no 'error' key.
485 if (isset($json['error']) || (is_array($json) && ($json['object'] ?? '') === 'error')) {
486 if (isset($json['error'])) {
487 $msg = $json['error']['message'] ?? json_encode($json['error']);
488 } else {
489 $msg = $json['message'] ?? json_encode($json);
490 }
491 if (!is_string($msg)) {
492 $msg = json_encode($msg);
493 }
494 $this->recordModelFailure($httpCode, (string) $msg);
495 if (getDolGlobalString("AI_DEBUG")) {
496 dol_syslog("Error: API " . $msg, LOG_DEBUG, 0, '_ai');
497 }
498 return "Error: API " . $msg;
499 }
500
501 // Token usage as reported by the provider, for the cost columns of the
502 // request log: every provider returns it inside the response body under
503 // its own name. Thinking tokens are billed as output, so Gemini's
504 // thoughtsTokenCount is counted with the visible candidates tokens.
505 // The call succeeded: a warning recorded for this same model is now stale.
506 $this->clearModelFailure();
507
508 $this->lastUsage = array('model' => $this->model);
509 if ($isGemini) {
510 $this->lastUsage['input'] = (int) ($json['usageMetadata']['promptTokenCount'] ?? 0);
511 $this->lastUsage['output'] = (int) ($json['usageMetadata']['candidatesTokenCount'] ?? 0) + (int) ($json['usageMetadata']['thoughtsTokenCount'] ?? 0);
512 } elseif ($isClaude) {
513 $this->lastUsage['input'] = (int) ($json['usage']['input_tokens'] ?? 0);
514 $this->lastUsage['output'] = (int) ($json['usage']['output_tokens'] ?? 0);
515 } else {
516 $this->lastUsage['input'] = (int) ($json['usage']['prompt_tokens'] ?? 0);
517 $this->lastUsage['output'] = (int) ($json['usage']['completion_tokens'] ?? 0);
518 }
519
520 // Extraction Logic
521 $answer = null;
522 if ($isClaude) {
523 // The list of blocks, not only the first one: with thinking (on by default
524 // on recent models), a 'thinking' block comes before the 'text' one.
525 $answer = $json['content'] ?? null;
526 } elseif ($isGemini) {
527 $answer = $json['candidates'][0]['content']['parts'][0]['text'] ?? null;
528 }
529
530 if ($answer === null) {
531 // Default (OpenAI compatible)
532 $answer = $json['choices'][0]['message']['content'] ?? null;
533 }
534
535 // A reasoning model (e.g. Claude, or through GLM) may send the content as a list
536 // of chunks, a 'thinking' one before the 'text' one: keep only the text.
537 if (is_array($answer)) {
538 $text = '';
539 foreach ($answer as $chunk) {
540 if (is_array($chunk) && ($chunk['type'] ?? '') === 'text' && is_string($chunk['text'] ?? null)) {
541 $text .= $chunk['text'];
542 }
543 }
544 $answer = ($text !== '') ? $text : null;
545 }
546
547 // When answer was into the tool_calls instead of message
548 if (empty($answer) && !empty($json['choices'][0]['message']['tool_calls'])) {
549 $answer = json_encode($json['choices'][0]['message']['tool_calls']);
550 }
551
552 return $answer;
553 }
554}
$propal type
'integer', 'integer:ObjectClass:PathToClass[:AddCreateButtonOrNot[:Filter[:Sortfield]]]',...
Definition propal.php:281
dolibarr_set_const($db, $name, $value, $type='chaine', $visible=0, $note='', $entity=1)
Insert a parameter (key,value) into database (delete old key then insert it again).
dolibarr_del_const($db, $name, $entity=1)
Delete a constant.
if(!isModEnabled('ai')||!getDolGlobalString('AI_ASSISTANT_ENABLED')) global $conf
The main.inc.php has been included so the following variable are now defined:
clearModelFailure()
Drop a recorded model failure once that model answers again.
curl(string $url, array $data, array $headers, bool $isClaude=false, bool $isGemini=false)
Execute HTTP Request via cURL.
__construct(string $type, string $key, string $baseUrl, string $model, int $timeout)
Constructor.
generate(string $system, string $userMsg, string $mode='text', array $attachments=array(), array $history=array())
Generate a response using the configured LLM provider.
recordModelFailure(int $httpCode, string $msg)
Record a "model not found / retired" type provider failure into the constant AI_MODEL_RUNTIME_FAILURE...
callGoogle(string $sys, string $msg, string $mode='text', array $attachments=array(), array $history=array())
Call Google Gemini API.
setMaxTokens(int $maxTokens)
Set the maximum number of tokens of the answer, for callers that expect long answers (with thinking m...
encodeRequestForLog(array $data)
JSON-encode a request for the log with base64 payloads removed, so the 60k truncation in ai_log_reque...
static isModelUnavailableError(string $msg)
Tell if a provider error message says the requested model is unknown, retired or not available (not a...
callAnthropic(string $sys, string $msg, string $mode='text', array $attachments=array(), array $history=array())
Call Anthropic API (Claude)
callOpenAI(string $sys, string $msg, string $mode='text', array $attachments=array(), array $history=array())
Call OpenAI-compatible API.
dol_now($mode='gmt')
Return date for now.
dol_trunc($string, $size=40, $trunc='right', $stringencoding='UTF-8', $nodot=0, $display=0)
Truncate a string to a particular length adding '...' if string larger than length.
getDolGlobalString($key, $default='')
Return a Dolibarr global constant string value.
dol_syslog($message, $level=LOG_INFO, $ident=0, $suffixinfilename='', $restricttologhandler='', $logcontext=null)
Write log message into outputs.
getURLContent($url, $postorget='GET', $param='', $followlocation=1, $addheaders=array(), $allowedschemes=array('http', 'https'), $localurl=0, $ssl_verifypeer=-1, $timeoutconnect=0, $timeoutresponse=0, $otherCurlOptions=array(), $morelogsuffix='')
Function to get a content from an URL (use proxy if proxy defined).