tools-llm

Biblioteca/Library minimalista para executar funções de texto com marcadores inline.

PT-BR

Sintaxe suportada

Modo padrão (substitui pelo retorno da função):

• [[funcao]]
• [[funcao:param1]]
• [[funcao:param1,param2,param3]]

Modo silencioso (executa e remove marcador):

• [[!funcao]]
• [[!funcao:param1]]
• [[!funcao:param1,param2,param3]]

Comportamento

• Executa a função apenas se ela existir em tools
• Suporta funções síncronas e assíncronas
• Resolve marcadores da esquerda para a direita
• Converte retorno automaticamente para string no modo padrão
• Modo silencioso (!) executa a função e ignora o retorno
• No modo silencioso, o marcador é removido do texto final
• Marcadores desconhecidos são preservados (inclusive silenciosos)
• Se a função lançar erro, o marcador é preservado
• Detecta automaticamente quando um parâmetro é JSON válido

Instalação

npm install tools-llm

Uso (PT-BR)

import { executarTools, executeMutedTools } from "tools-llm";
// ou: import executarTools from "tools-llm";

const tools = {
  data_agora() {
    return "24/06/2026";
  },
  async clima(cidade) {
    return cidade === "Recife" ? "32°C" : "N/A";
  },
  somar(a, b) {
    return Number(a) + Number(b);
  },
  processar(payload) {
    return payload.cidade;
  },
  async registrarLog(msg) {
    // side effect
    return "OK";
  }
};

const texto = `Hoje é [[data_agora]]
Clima: [[clima:Recife]]
Soma: [[somar:10,20]]
JSON: [[processar:{"cidade":"Recife","temp":32}]]

[[!registrarLog:usuario entrou]]

Favorito: [[Naruto]]`;

const resultado = await executarTools(texto, tools);

console.log(resultado);
/*
Hoje é 24/06/2026
Clima: 32°C
Soma: 30
JSON: Recife


Favorito: [[Naruto]]
*/

const resultadoLista = await executeMutedTools(texto, tools);
console.log(resultadoLista);
/*
[
  { tool: "data_agora", result: "24/06/2026" },
  { tool: "clima", result: "32°C" },
  { tool: "somar", result: 30 },
  { tool: "processar", result: "Recife" },
  { tool: "registrarLog", result: "OK" }
]
*/

API (PT-BR)

• await executarTools(texto, tools): Retorna uma String com o texto modificado (marcadores substituídos pelos retornos das funções).
• await executeMutedTools(texto, tools): Executa as funções e retorna uma lista de objetos (Array<{ tool: string, result: any }>) com os resultados. Não substitui o texto original e ignora a restrição de "silencioso" (!).

EN

Supported syntax

Default mode (replaces with function return):

• [[functionName]]
• [[functionName:param1]]
• [[functionName:param1,param2,param3]]

Silent mode (executes and removes marker):

• [[!functionName]]
• [[!functionName:param1]]
• [[!functionName:param1,param2,param3]]

Behavior

• Executes only if the function exists in tools
• Supports sync and async functions
• Resolves markers left to right
• Converts return values to string in default mode
• Silent mode (!) executes the function and ignores return value
• In silent mode, marker is removed from final text
• Unknown markers are preserved (including silent markers)
• If a function throws, the marker is preserved
• Automatically detects valid JSON parameters

Installation

npm install tools-llm

Usage (EN)

import { executeTools, executeMutedTools } from "tools-llm";
// or: import executarTools from "tools-llm";

const tools = {
  date_now() {
    return "24/06/2026";
  },
  async weather(city) {
    return city === "Recife" ? "32°C" : "N/A";
  },
  sum(a, b) {
    return Number(a) + Number(b);
  },
  process(payload) {
    return payload.city;
  },
  async saveMemory(key, value) {
    // side effect
    return "OK";
  }
};

const text = `Today is [[date_now]]
Weather: [[weather:Recife]]
Sum: [[sum:10,20]]
JSON: [[process:{"city":"Recife","temp":32}]]

[[!saveMemory:name,Caio]]

Favorite: [[Naruto]]`;

const result = await executeTools(text, tools);

console.log(result);
/*
Today is 24/06/2026
Weather: 32°C
Sum: 30
JSON: Recife


Favorite: [[Naruto]]
*/

const resultList = await executeMutedTools(text, tools);
console.log(resultList);
/*
[
  { tool: "date_now", result: "24/06/2026" },
  { tool: "weather", result: "32°C" },
  { tool: "sum", result: 30 },
  { tool: "process", result: "Recife" },
  { tool: "saveMemory", result: "OK" }
]
*/

API (EN)

• await executeTools(text, tools) (alias de executarTools): Returns a String with the text modified (markers replaced by the functions' return values).
• await executeMutedTools(text, tools): Executes the functions and returns an array of objects (Array<{ tool: string, result: any }>) with the results. It does not replace the original text and ignores the "silent" restriction (!).

Notas/Notes

• JSON válido vira objeto/array/valor nativo via JSON.parse
• Texto comum continua string
• Parâmetros com vírgulas internas em JSON são tratados corretamente
• Compatível com Node.js e navegador (ESM)
• Exports disponíveis:
  • executarTools
  • executeTools
  • executeMutedTools
  • default (executarTools)