Parâmetros

O LabsLLM suporta diferentes tipos de parâmetros para definições de funções. Os parâmetros permitem que os LLMs passem dados estruturados para suas funções quando elas são chamadas.

Tipos de Parâmetros Disponíveis

Atualmente, o LabsLLM suporta os seguintes tipos de parâmetros:

StringParameter

O StringParameter é usado para valores de texto e é o tipo de parâmetro mais comumente usado:

use LabsLLM\Parameters\StringParameter;

// Parâmetro de string básico
$nameParam = new StringParameter(
    'name',                // Nome do parâmetro
    'Nome de uma pessoa'   // Descrição do parâmetro
);

// Parâmetro de string com opções enumeradas
$colorParam = new StringParameter(
    'color', 
    'Escolha uma cor', 
    ['red', 'blue', 'green']  // Valores permitidos (enum)
);

Quando você define um parâmetro de string com um enum, o modelo será orientado a escolher apenas entre essas opções, melhorando a confiabilidade das chamadas de função.

NumberParameter

O NumberParameter é usado para valores numéricos (inteiros e decimais):

use LabsLLM\Parameters\NumberParameter;

// Parâmetro numérico básico
$ageParam = new NumberParameter(
    'age',               // Nome do parâmetro
    'Idade da pessoa'    // Descrição do parâmetro
);

BooleanParameter

O BooleanParameter é usado para valores booleanos (verdadeiro/falso):

use LabsLLM\Parameters\BooleanParameter;

// Parâmetro booleano básico
$isPaidParam = new BooleanParameter(
    'isPaid',               // Nome do parâmetro
    'Se o pagamento foi realizado'  // Descrição do parâmetro
);

ArrayParameter

O ArrayParameter é usado para listas de valores:

use LabsLLM\Parameters\ArrayParameter;
use LabsLLM\Parameters\StringParameter;

// Array de strings
$namesParam = new ArrayParameter(
    'names',             // Nome do parâmetro
    'Nomes das pessoas', // Descrição do parâmetro
    items: new StringParameter('name', 'Nome da pessoa')
);

O ArrayParameter é mais complexo que outros tipos porque requer a definição do tipo de itens que o array conterá. No exemplo acima, definimos um array de strings, mas você pode criar arrays de qualquer outro tipo de parâmetro, incluindo arrays de números, booleanos ou até mesmo arrays aninhados.

ObjectParameter

O ObjectParameter é usado para objetos complexos com múltiplas propriedades:

use LabsLLM\Parameters\ObjectParameter;
use LabsLLM\Parameters\StringParameter;
use LabsLLM\Parameters\NumberParameter;
use LabsLLM\Parameters\ArrayParameter;

// Parâmetro de objeto com múltiplas propriedades
$userParam = new ObjectParameter(
    'user',              // Nome do parâmetro
    'Dados do usuário',  // Descrição do parâmetro
    [
        new StringParameter('name', 'O nome do usuário'),
        new NumberParameter('age', 'A idade do usuário'),
        new ArrayParameter('skills', 'As habilidades do usuário', 
            new StringParameter('skill', 'Uma habilidade do usuário'))
    ],
    ['name', 'age']      // name e age são campos obrigatórios
);

O ObjectParameter permite criar estruturas de dados complexas combinando múltiplos tipos de parâmetros. Você pode especificar quais propriedades são obrigatórias passando seus nomes no quarto argumento.

Importante: Alguns modelos de LLM podem ter dificuldade em respeitar corretamente os campos marcados como obrigatórios, especialmente em estruturas de objetos aninhados. Se você notar que o modelo está ignorando os campos obrigatórios, considere especificar essas restrições diretamente na descrição da função ou do parâmetro para aumentar a probabilidade do modelo seguir corretamente a estrutura esperada.

Usando Parâmetros com o FunctionHelper

Os parâmetros são usados dentro do FunctionHelper para definir as entradas para suas funções chamáveis:

$weatherFunction = FunctionHelper::create('getWeather', 'Obter informações meteorológicas')
    ->withParameter([
        new StringParameter('location', 'Nome da cidade', ['Nova York', 'Londres', 'Tóquio']),
        new StringParameter('format', 'Formato da resposta', ['simples', 'detalhado'])
    ], ['location']) // Apenas location é obrigatório
    ->callable(function($location, $format = 'simples') {
        // Implementação para obter dados meteorológicos
        return "O clima em $location está ensolarado. Formato: $format";
    });

Observe que os parâmetros são passados diretamente para a função chamável na mesma ordem em que foram definidos. Para parâmetros opcionais, você pode fornecer valores padrão na assinatura da função.

Parâmetros Obrigatórios vs Opcionais

Ao definir parâmetros com withParameter(), você especifica quais parâmetros são obrigatórios:

->withParameter([
    new StringParameter('param1', 'Primeiro parâmetro'),
    new StringParameter('param2', 'Segundo parâmetro'),
    new StringParameter('param3', 'Terceiro parâmetro')
], ['param1', 'param2']) // param1 e param2 são obrigatórios, param3 é opcional

Parâmetros obrigatórios devem ser fornecidos pelo modelo ao chamar a função, enquanto parâmetros opcionais podem ser omitidos. Para parâmetros opcionais, é uma boa prática definir valores padrão em sua função chamável:

->callable(function($param1, $param2, $param3 = 'valor padrão') {
    // Implementação da função
});

Futuros Tipos de Parâmetros

Mais tipos de parâmetros serão adicionados em versões futuras.

Melhores Práticas para Parâmetros

1. Use nomes descritivos: Escolha nomes de parâmetros claros que indiquem seu propósito
2. Adicione descrições úteis: Forneça descrições detalhadas para orientar o modelo sobre o que inserir
3. Use enums quando possível: Forneça uma lista de opções válidas para restringir as escolhas do modelo
4. Valide entradas: Sempre valide os valores dos parâmetros em sua função chamável
5. Forneça padrões para parâmetros opcionais: Lide com casos em que parâmetros opcionais não são fornecidos usando valores de parâmetros padrão na assinatura da função

Para mais informações sobre o uso de parâmetros com funções, consulte a seção FunctionHelper.