Scriptling Scriptling

scriptling.ai.tools

Builds OpenAI-compatible tool schemas from Scriptling functions, so an AI agent can discover and call them. The library exposes the Registry class: construct one with tools.Registry() (or ai.ToolRegistry(), the re-export most scripts use, see scriptling.ai), then register tools and build schemas to pass to a completion request or an Agent.

Availability

The standalone scriptling.ai.tools import is conditionally registered and is not added by normal CLI setup. When scriptling.ai is available, prefer its ai.ToolRegistry() re-export, which provides the same class without requiring the standalone namespace. Embedders that need import scriptling.ai.tools must register that library explicitly.

Available Functions

Function Description
Registry() Create a tool registry for building schemas

Registry Methods

Method Description
add(name, description, params, handler) Register a tool.
add_schema(name, description, schema, handler) Register a tool with a full JSON Schema.
build() Build OpenAI-compatible tool schemas from the registered tools.
get_handler(name) Get the handler function for a registered tool.

Functions

Registry()

Creates a new, empty Registry instance.

Returns: Registry: a new registry instance.

import scriptling.ai.tools as tools

registry = tools.Registry()

# Same class, re-exported by scriptling.ai:
import scriptling.ai as ai
registry = ai.ToolRegistry()

registry.add(name, description, params, handler)

Registers a tool with the registry. Parameter types are validated immediately, so an unknown type raises an error at add() time rather than at build() time.

Parameters:

  • name (str): Tool name.
  • description (str): Tool description, shown to the model.
  • params (dict): Parameter definitions, mapping each parameter name to a type string. Accepted types: string, integer, number, boolean, array, object. Aliases: int for integer, float for number, str for string, bool for boolean, dict for object, list for array. Append ? to mark a parameter optional (e.g. "string?").
  • handler (callable): Function executed when the tool is called. It receives the decoded arguments as a dict.

Returns: None.

Raises: Error: if a parameter type is not one of the accepted types or aliases.

import scriptling.ai.tools as tools

registry = tools.Registry()

registry.add("read_file", "Read a file", {"path": "string", "limit": "int?"}, read_file)
registry.add("search", "Search files", {"query": "string", "max_results": "int?"}, search_files)

registry.add_schema(name, description, schema, handler)

Registers a tool whose parameters are given as a complete JSON Schema dict, emitted verbatim in the built tool definition. Use this when the parameter shape is richer than the flat name-to-type map add() accepts: nested objects, enums, per-parameter descriptions. The common source is a remote MCP server’s inputSchema, which is what Agent(mcp_servers=[...]) uses internally. Unlike add(), registering a duplicate name raises an error instead of silently overwriting the previous handler.

Parameters:

  • name (str): Tool name.
  • description (str): Tool description, shown to the model.
  • schema (dict): JSON Schema for the tool’s parameters. Should describe an object ("type": "object" with "properties").
  • handler (callable): Function executed when the tool is called. It receives the decoded arguments as a dict.

Returns: None.

Raises: Error: if a tool with the same name is already registered, or the schema is not a dict.

import scriptling.ai as ai

registry = ai.ToolRegistry()

registry.add_schema("shop__search", "Search products", {
    "type": "object",
    "properties": {
        "query": {"type": "string", "description": "Search terms"},
        "filters": {
            "type": "object",
            "properties": {"tag": {"type": "string", "enum": ["new", "sale"]}},
        },
    },
    "required": ["query"],
}, search_products)

registry.build()

Builds OpenAI-compatible tool schemas from the tools registered via add() and add_schema(). The result is suitable to pass directly to a client completion request’s tools argument, or to an Agent via its tools= argument.

Returns: list: a list of tool schema dict values, each with type, function.name, function.description, and a JSON-Schema function.parameters object (with required derived from which parameters were marked optional).

import scriptling.ai as ai

registry = ai.ToolRegistry()
registry.add("get_time", "Get current time", {}, lambda args: "12:00 PM")

schemas = registry.build()

# Pass to a completion request
client = ai.Client("http://127.0.0.1:1234/v1")
response = client.completion("gpt-4", "What time is it?", tools=schemas)

registry.get_handler(name)

Returns the handler function registered for a tool. This is how Agent and ai.execute_tool_calls look up the function to run for a model-emitted tool call.

Parameters:

  • name (str): Tool name.

Returns: callable: the handler function.

Raises: Error: if no tool with that name is registered.

handler = registry.get_handler("read_file")
result = handler({"path": "/etc/hostname"})

See Also

  • scriptling.ai: re-exports the class as ai.ToolRegistry, plus completion helpers and execute_tool_calls.
  • scriptling.ai.agent: the Agent class consumes a Registry via its tools= argument.
  • scriptling.mcp.tool: building tools for the MCP protocol instead of direct LLM APIs.