Class: Braintrust::API::Functions

Inherits:
Object
  • Object
show all
Defined in:
lib/braintrust/api/functions.rb

Overview

Functions API namespace Provides methods for creating, invoking, and managing remote functions (prompts)

Constant Summary collapse

TYPE_LLM = 
"llm"
TYPE_PROMPT = 
"prompt"
TYPE_SCORER = 
"scorer"
TYPE_TASK = 
"task"
TYPE_TOOL = 
"tool"

Instance Method Summary collapse

Constructor Details

#initialize(api) ⇒ Functions

Returns a new instance of Functions.



20
21
22
23
 
# File 'lib/braintrust/api/functions.rb', line 20

def initialize(api)
  @api = api
  @state = api.state
end

Instance Method Details

#create(project_name:, slug:, function_data:, prompt_data: nil, name: nil, description: nil, function_type: nil, function_schema: nil) ⇒ Hash

Create or register a function (idempotent) POST /v1/function This method is idempotent - if a function with the same slug already exists in the project, it will return the existing function unmodified. Unlike datasets, the response does not include a “found_existing” field.

Parameters:

  • project_name (String) —

    Project name

  • slug (String) —

    Function slug (URL-friendly identifier)

  • function_data (Hash) —

    Function configuration (usually “prompt”)

  • prompt_data (Hash, nil) (defaults to: nil) —

    Prompt configuration (prompt, options, etc.)

  • name (String, nil) (defaults to: nil) —

    Optional display name (defaults to slug)

  • description (String, nil) (defaults to: nil) —

    Optional description

  • function_type (String, nil) (defaults to: nil) —

    Function type (“llm”, “scorer”, “task”, “tool”, or nil)

  • function_schema (Hash, nil) (defaults to: nil) —

    JSON schema for function parameters and return type @option function_schema [Hash] :parameters JSON schema for input parameters @option function_schema [Hash] :returns JSON schema for return value

Returns:

  • (Hash) —

    Function metadata

Raises:



60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/braintrust/api/functions.rb', line 60

def create(project_name:, slug:, function_data:, prompt_data: nil, name: nil, description: nil, function_type: nil, function_schema: nil)
  # Look up project ID
  projects_result = http_get("/v1/project", {"project_name" => project_name})
  project = projects_result["objects"]&.first
  raise Error, "Project '#{project_name}' not found" unless project
  project_id = project["id"]

  payload = {
    project_id: project_id,
    slug: slug,
    name: name || slug,  # Name is required, default to slug
    function_data: function_data
  }
  payload[:prompt_data] = prompt_data if prompt_data
  payload[:description] = description if description
  payload[:function_type] = function_type if function_type
  payload[:function_schema] = function_schema if function_schema

  http_post_json("/v1/function", payload)
end

#create_llm(project_name:, slug:, prompt_data:, name: nil, description: nil, function_schema: nil) ⇒ Hash

Create an LLM function LLM functions are prompt-based functions categorized as LLM type.

Parameters:

  • project_name (String) —

    Project name

  • slug (String) —

    Function slug (URL-friendly identifier)

  • prompt_data (Hash) —

    Prompt configuration (prompt, options, etc.)

  • name (String, nil) (defaults to: nil) —

    Optional display name (defaults to slug)

  • description (String, nil) (defaults to: nil) —

    Optional description

  • function_schema (Hash, nil) (defaults to: nil) —

    JSON schema for parameters and return type

Returns:

  • (Hash) —

    Function metadata



188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/braintrust/api/functions.rb', line 188

def create_llm(project_name:, slug:, prompt_data:, name: nil, description: nil, function_schema: nil)
  validate_prompt_data!(prompt_data)
  create(
    project_name: project_name,
    slug: slug,
    function_data: {type: TYPE_PROMPT},
    prompt_data: prompt_data,
    name: name,
    description: description,
    function_type: TYPE_LLM,
    function_schema: function_schema
  )
end

#create_scorer(project_name:, slug:, prompt_data:, name: nil, description: nil, function_schema: nil) ⇒ Hash

Create a scorer function Scorers evaluate task outputs and return scores (typically 0-1).

Parameters:

  • project_name (String) —

    Project name

  • slug (String) —

    Function slug (URL-friendly identifier)

  • prompt_data (Hash) —

    Prompt configuration for the scoring logic

  • name (String, nil) (defaults to: nil) —

    Optional display name (defaults to slug)

  • description (String, nil) (defaults to: nil) —

    Optional description

  • function_schema (Hash, nil) (defaults to: nil) —

    JSON schema for parameters and return type

Returns:

  • (Hash) —

    Function metadata



142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/braintrust/api/functions.rb', line 142

def create_scorer(project_name:, slug:, prompt_data:, name: nil, description: nil, function_schema: nil)
  validate_prompt_data!(prompt_data)
  create(
    project_name: project_name,
    slug: slug,
    function_data: {type: TYPE_PROMPT},
    prompt_data: prompt_data,
    name: name,
    description: description,
    function_type: TYPE_SCORER,
    function_schema: function_schema
  )
end

#create_task(project_name:, slug:, prompt_data:, name: nil, description: nil, function_schema: nil) ⇒ Hash

Create a task function Tasks are general-purpose prompt functions.

Parameters:

  • project_name (String) —

    Project name

  • slug (String) —

    Function slug (URL-friendly identifier)

  • prompt_data (Hash) —

    Prompt configuration (prompt, options, etc.)

  • name (String, nil) (defaults to: nil) —

    Optional display name (defaults to slug)

  • description (String, nil) (defaults to: nil) —

    Optional description

  • function_schema (Hash, nil) (defaults to: nil) —

    JSON schema for parameters and return type

Returns:

  • (Hash) —

    Function metadata



165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/braintrust/api/functions.rb', line 165

def create_task(project_name:, slug:, prompt_data:, name: nil, description: nil, function_schema: nil)
  validate_prompt_data!(prompt_data)
  create(
    project_name: project_name,
    slug: slug,
    function_data: {type: TYPE_PROMPT},
    prompt_data: prompt_data,
    name: name,
    description: description,
    function_type: TYPE_TASK,
    function_schema: function_schema
  )
end

#create_tool(project_name:, slug:, prompt_data:, name: nil, description: nil, function_schema: nil) ⇒ Hash

Create a tool function Tools are functions that LLMs can call during execution.

Parameters:

  • project_name (String) —

    Project name

  • slug (String) —

    Function slug (URL-friendly identifier)

  • prompt_data (Hash) —

    Prompt configuration (prompt, options, etc.)

  • name (String, nil) (defaults to: nil) —

    Optional display name (defaults to slug)

  • description (String, nil) (defaults to: nil) —

    Description of what the tool does (recommended for LLM understanding)

  • function_schema (Hash, nil) (defaults to: nil) —

    JSON schema defining the tool’s parameters and return type

Returns:

  • (Hash) —

    Function metadata



119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/braintrust/api/functions.rb', line 119

def create_tool(project_name:, slug:, prompt_data:, name: nil, description: nil, function_schema: nil)
  validate_prompt_data!(prompt_data)
  create(
    project_name: project_name,
    slug: slug,
    function_data: {type: TYPE_PROMPT},
    prompt_data: prompt_data,
    name: name,
    description: description,
    function_type: TYPE_TOOL,
    function_schema: function_schema
  )
end

#delete(id:) ⇒ Hash

Delete a function by ID DELETE /v1/function/id

Parameters:

  • id (String) —

    Function UUID

Returns:

  • (Hash) —

    Delete response



106
107
108
 
# File 'lib/braintrust/api/functions.rb', line 106

def delete(id:)
  http_delete("/v1/function/#{id}")
end

#get(id:, version: nil) ⇒ Hash

Get a function by ID (includes full prompt_data) GET /v1/function/id

Parameters:

  • id (String) —

    Function UUID

  • version (String, nil) (defaults to: nil) —

    Retrieve prompt at a specific version (transaction ID or version identifier)

Returns:

  • (Hash) —

    Full function data including prompt_data



96
97
98
99
100
 
# File 'lib/braintrust/api/functions.rb', line 96

def get(id:, version: nil)
  params = {}
  params["version"] = version if version
  http_get("/v1/function/#{id}", params)
end

#invoke(id:, input:) ⇒ Object

Invoke a function by ID with input POST /v1/function/id/invoke

Parameters:

  • id (String) —

    Function UUID

  • input (Object) —

    Input data to pass to the function

Returns:

  • (Object) —

    The function output (String, Hash, Array, etc.) as returned by the HTTP API



86
87
88
89
 
# File 'lib/braintrust/api/functions.rb', line 86

def invoke(id:, input:)
  payload = {input: input}
  http_post_json("/v1/function/#{id}/invoke", payload)
end

#list(project_name: nil, project_id: nil, function_name: nil, slug: nil, limit: nil) ⇒ Hash

List functions with optional filters GET /v1/function?project_name=X&…

Parameters:

  • project_name (String, nil) (defaults to: nil) —

    Filter by project name

  • project_id (String, nil) (defaults to: nil) —

    Filter by project ID (UUID)

  • function_name (String, nil) (defaults to: nil) —

    Filter by function name

  • slug (String, nil) (defaults to: nil) —

    Filter by slug

  • limit (Integer, nil) (defaults to: nil) —

    Limit number of results

Returns:

  • (Hash) —

    Response with “objects” array



33
34
35
36
37
38
39
40
41
42
 
# File 'lib/braintrust/api/functions.rb', line 33

def list(project_name: nil, project_id: nil, function_name: nil, slug: nil, limit: nil)
  params = {}
  params["project_name"] = project_name if project_name
  params["project_id"] = project_id if project_id
  params["function_name"] = function_name if function_name
  params["slug"] = slug if slug
  params["limit"] = limit if limit

  http_get("/v1/function", params)
end