FunctionHelper

A classe FunctionHelper é usada para definir funções que podem ser chamadas pelos LLMs durante a execução. Ela fornece uma interface fluente para criar definições de funções com vários parâmetros e comportamentos.

Criando Funções

Você pode criar funções usando o método estático create:

use LabsLLM\Helpers\FunctionHelper;

// Criar uma função simples
$simpleFunction = FunctionHelper::create(
    'functionName',            // O nome da função
    'Descrição da função'      // Descrição que ajuda o modelo a entender quando usá-la
);

Definindo Parâmetros

Funções podem ter parâmetros para os quais o modelo fornecerá valores:

$withParams = FunctionHelper::create('previsaoTempo', 'Obter previsão do tempo para um local')
    ->withParameter([
        new StringParameter('location', 'A cidade e estado, ex: São Paulo, SP'),
        new StringParameter('unit', 'A unidade de temperatura', ['celsius', 'fahrenheit'])
    ], ['location']); // 'location' é obrigatório, 'unit' é opcional

O método withParameter recebe dois argumentos:

1. Um array de definições de parâmetros
2. Um array de nomes de parâmetros obrigatórios

Adicionando Comportamento

Para tornar sua função executável, adicione um callable que implementa o comportamento da função:

$function = FunctionHelper::create('multiplicar', 'Multiplicar dois números')
    ->withParameter([
        new StringParameter('num1', 'Primeiro número'),
        new StringParameter('num2', 'Segundo número')
    ], ['num1', 'num2'])
    ->callable(function($num1, $num2) {
        $num1 = floatval($num1);
        $num2 = floatval($num2);
        return "O resultado é: " . ($num1 * $num2);
    });

A função callable recebe os valores dos parâmetros diretamente como argumentos individuais da função, na mesma ordem em que foram definidos em withParameter().

Processo de Execução da Função

Quando o LLM decide chamar uma função, o seguinte acontece:

1. O modelo envia o nome da função e os argumentos
2. LabsLLM encontra o function helper correspondente
3. O callable é executado com os argumentos fornecidos passados diretamente como parâmetros da função
4. O valor de retorno do callable é enviado de volta ao modelo
5. Se maxSteps > 1, o modelo pode usar esse resultado para gerar uma resposta ou chamar outra função

Usando Funções com LabsLLM

Para disponibilizar sua função para o modelo:

$execute = LabsLLM::text()
    ->addTool($function)              // Adiciona o function helper
    ->withMaxSteps(2)                 // Permite chamada de função + resposta
    ->using(new OpenAI('chave', 'modelo'))
    ->executePrompt('Calcule 25 multiplicado por 4');

$response = $execute->getResponseData();

Melhores Práticas

1. Descrições claras: Forneça descrições claras de funções e parâmetros para que o modelo saiba quando e como usá-las
2. Valide entrada: Sempre valide os argumentos recebidos do modelo
3. Retorne respostas informativas: Retorne respostas que o modelo possa entender e incorporar em sua resposta
4. Trate erros com elegância: Retorne mensagens de erro claras quando os argumentos forem inválidos
5. Mantenha funções focadas: Crie funções que façam uma coisa bem em vez de funções complexas com múltiplos propósitos

Formatação de Função

Internamente, o FunctionHelper converte sua definição de função para o formato esperado pelo provedor LLM:

$functionAsArray = $function->toArray();
// Estrutura do resultado:
// [
//   'type' => 'function',
//   'function' => [
//     'name' => 'functionName',
//     'description' => 'Descrição da função',
//     'parameters' => [
//       'type' => 'object',
//       'properties' => [ ... ],
//       'required' => [ ... ]
//     ]
//   ]
// ]

Para mais informações sobre tipos de parâmetros, consulte a seção Parâmetros.