onetool

The last LLM tool you'll need.

The Problem

LLM agents typically get dozens of specialized tools:

A calculator for arithmetic
A date formatter for timestamps
A string manipulator for text operations
A JSON parser, a base64 encoder, a hash generator...

Each tool requires API design, documentation, and testing. Tools don't compose well. And you're always limited by what tools you thought to create.

The Solution

onetool provides one universal computation tool powered by a sandboxed Lua runtime.

Instead of hunting for the right tool, your LLM can solve problems programmatically. State persists between calls for multi-step reasoning. It's safe by design with comprehensive sandboxing. And it integrates seamlessly with major LLM libraries.

Quick Start: LLM Integration

use onetool::Repl;
use genai::chat::{ChatRequest, ChatMessage, ToolResponse};
use serde_json::json;

// 1. Create the REPL
let repl = Repl::new()?;

// 2. Get the tool definition (compatible with OpenAI, Google, etc.)
let tool = onetool::tool_definition::genai_tool();

// 3. Add to your chat request
let chat_req = ChatRequest::new(vec![
    ChatMessage::user("What's the sum of the 10 first prime numbers?")
]).with_tools(vec![tool]);

// 4. Get LLM response with tool calls
let chat_res = client.exec_chat(MODEL, chat_req.clone(), None).await?;
let tool_calls = chat_res.into_tool_calls();

// 5. Execute the code
let source_code = &tool_calls[0].fn_arguments["source_code"];
let response = repl.eval(source_code).await?;

// 6. Send results back to LLM
let tool_response = ToolResponse::new(
    tool_calls[0].call_id.clone(),
    json!({
        "output": response.output.join("\n"),
        "result": match response.result {
            Ok(result) => result.join("\n"),
            Err(err) => format!("error: {}", err),
        }
    }).to_string()
);

// 7. Get final answer
let chat_req = chat_req
    .append_message(tool_calls)
    .append_message(tool_response);
let final_response = client.exec_chat(MODEL, chat_req, None).await?;

Real Example: What Can It Do?

Here's an actual interaction from the included example:

User: "What's the sum of the 10 first prime numbers?"

LLM calls lua_repl with:
{
  "source_code": "
    local primes = {}
    local num = 2
    while #primes < 10 do
      local is_prime = true
      for i = 2, math.sqrt(num) do
        if num % i == 0 then
          is_prime = false
          break
        end
      end
      if is_prime then
        table.insert(primes, num)
      end
      num = num + 1
    end

    local sum = 0
    for _, p in ipairs(primes) do
      sum = sum + p
    end
    return sum
  "
}

Response: {
  "result": "129",
  "output": ""
}

LLM: "The sum of the first 10 prime numbers is 129."

The LLM wrote a complete algorithm, executed it safely, and got the answer - all without needing a specialized "prime number calculator" tool.

Tool Definition System

onetool includes a complete tool definition system for LLM integration:

use onetool::tool_definition;

// Tool metadata
tool_definition::NAME              // "lua_repl"
tool_definition::DESCRIPTION       // Full description for LLM context
tool_definition::PARAM_SOURCE_CODE // "source_code"

// JSON Schema (for OpenAI, Google, Anthropic)
let schema = tool_definition::json_schema();

// genai integration (requires "genai" feature)
let tool = tool_definition::genai_tool();

Compatible with:

OpenAI function calling
Google Gemini function calling
Anthropic tool use
Any JSON Schema-based tool system

Security Model

Safe by Design

Sandboxed Lua 5.4 runtime - Dangerous operations blocked at the language level

What's Available

String manipulation (string.*)
Table operations (table.*)
Math functions (math.*)
UTF-8 support (utf8.*)
Safe OS functions (os.time, os.date)
All Lua control flow and data structures

What's Blocked

File I/O (io, file)
Network access
Code loading (require, dofile, load*)
OS commands (os.execute, os.getenv, etc.)
Metatable manipulation
Coroutines
Garbage collection control

Key Features

For LLM Integration:

Universal computation tool (replaces dozens of specialized tools)
Built-in tool definitions (OpenAI, Google, Anthropic compatible)
JSON Schema generation
Comprehensive documentation in tool description

For Developers:

Drop-in integration with genai library
Async/await support
Separate print() output from return values
Clear error messages
Type-safe Rust API via mlua

For LLM Agents:

Persistent state between calls (variables, functions, tables)
Runtime introspection via docs global
Can solve multi-step problems programmatically
Self-documenting environment

Installation

Basic setup:

[dependencies]
onetool = "0.0.1-alpha.1"
tokio = { version = "1", features = ["full"] }

With genai integration:

[dependencies]
onetool = { version = "0.0.1-alpha.1", features = ["genai"] }
genai = "0.5"

With JSON Schema only:

[dependencies]
onetool = { version = "0.0.1-alpha.1", features = ["json_schema"] }

Note: Currently in alpha - API may change.

Complete Example

Run the full LLM integration example:

# Set your API key (OpenAI, Google, etc.)
export OPENAI_API_KEY=your_key_here

# Run the example
cargo run --features genai --example genai-basic

This demonstrates:

Creating the sandboxed REPL
Registering the tool with an LLM client
LLM generating Lua code to solve a problem
Executing the code safely
Returning results to the LLM
LLM synthesizing the final answer

See it in action:

The example asks the LLM to calculate the sum of the first 10 prime numbers. The LLM:

Writes Lua code to find primes
Writes code to sum them
Executes via onetool
Receives the answer (129)
Responds to the user

See the full example source: examples/genai-basic.rs

Other Examples

Interactive REPL (for testing):

cargo run --example lua-repl

This lets you interact with the sandboxed environment directly to test Lua code and understand what the LLM sees.

API Overview

Full API documentation available at docs.rs/onetool.

Why Lua?

Lightweight: Small runtime, fast startup
Embeddable: Designed from the ground up to be embedded in host applications
Simple: Easy for LLMs to generate correct code
Powerful: Full programming language, not a domain-specific language
Safe: Straightforward to sandbox effectively

Use Cases

Perfect for:

LLM agents that need computation capabilities
AI assistants with multi-step reasoning
Applications requiring safe user-generated code execution

Project Status

Version: 0.0.1-alpha.1
Stability: Alpha - API may change, but core concept is stable
Production Ready: Not yet - use at your own risk

Development

Building:

cargo build
cargo test
cargo doc --open

Nix Support:

nix develop  # Dev shell with Rust, cargo-watch, rust-analyzer

Running Examples:

cargo run --features genai --example genai-basic  # Full LLM integration
cargo run --example lua-repl     # Interactive testing

Architecture

For implementation details, see:

src/runtime/mod.rs - Lua runtime definition
src/runtime/docs.rs - Runtime documentation implementation
src/runtime/sandbox.rs - Sandboxing implementation
src/tool_definition.rs - Tool integration system

Key patterns:

Nil-based sandboxing (simple, effective)
Output capture via mpsc channels
Persistent Lua state across invocations
Runtime documentation system

License & Contributing

Contributing:

Early stage project - feedback welcome!
See CLAUDE.md for architecture details
Issues and PRs appreciated

Built with mlua and genai.

onetool 0.0.1-alpha.1