Braintrust.Project (Braintrust v0.3.0)

View Source

Manage Braintrust projects.

Projects are the foundational organizational unit in Braintrust - containers for experiments, datasets, and logs.

Examples

# List all projects
{:ok, projects} = Braintrust.Project.list()

# Create a project
{:ok, project} = Braintrust.Project.create(%{name: "my-project"})

# Get a project by ID
{:ok, project} = Braintrust.Project.get("proj_123")

# Update a project
{:ok, project} = Braintrust.Project.update("proj_123", %{name: "new-name"})

# Delete a project
{:ok, project} = Braintrust.Project.delete("proj_123")

Pagination

The list/1 function supports cursor-based pagination:

# Get all projects as a list
{:ok, projects} = Braintrust.Project.list()

# Stream through projects lazily
Braintrust.Project.stream()
|> Stream.take(100)
|> Enum.to_list()

Summary

Types

t()

Functions

create(params, opts \\ [])

Creates a new project.

delete(project_id, opts \\ [])

Deletes a project.

get(project_id, opts \\ [])

Gets a project by ID.

list(opts \\ [])

Lists all projects.

stream(opts \\ [])

Returns a Stream that lazily paginates through all projects.

update(project_id, params, opts \\ [])

Updates a project.

Types

t()

@type t() :: %Braintrust.Project{
  created_at: DateTime.t() | nil,
  deleted_at: DateTime.t() | nil,
  id: String.t(),
  name: String.t(),
  org_id: String.t(),
  settings: map() | nil,
  user_id: String.t() | nil
}

Functions

create(params, opts \\ [])

@spec create(
  map(),
  keyword()
) :: {:ok, t()} | {:error, Braintrust.Error.t()}

Creates a new project.

If a project with the same name already exists, returns the existing project unmodified (idempotent behavior).

Parameters

  • :name - Project name (required)
  • :settings - Project settings map (optional)

Options

  • :api_key - Override API key for this request
  • :base_url - Override base URL for this request

Examples

iex> {:ok, project} = Braintrust.Project.create(%{name: "my-project"})
iex> project.name
"my-project"

# With settings
iex> {:ok, project} = Braintrust.Project.create(%{
...>   name: "my-project",
...>   settings: %{comparison_key: "input"}
...> })

delete(project_id, opts \\ [])

@spec delete(
  String.t(),
  keyword()
) :: {:ok, t()} | {:error, Braintrust.Error.t()}

Deletes a project.

This is a soft delete - the project's deleted_at field will be set.

Options

  • :api_key - Override API key for this request
  • :base_url - Override base URL for this request

Examples

iex> {:ok, project} = Braintrust.Project.delete("proj_123")
iex> project.deleted_at != nil
true

get(project_id, opts \\ [])

@spec get(
  String.t(),
  keyword()
) :: {:ok, t()} | {:error, Braintrust.Error.t()}

Gets a project by ID.

Options

  • :api_key - Override API key for this request
  • :base_url - Override base URL for this request

Examples

iex> {:ok, project} = Braintrust.Project.get("proj_123")
iex> project.name
"my-project"

list(opts \\ [])

@spec list(keyword()) :: {:ok, [t()]} | {:error, Braintrust.Error.t()}

Lists all projects.

Returns all projects as a list. For large result sets, consider using stream/1 for memory-efficient lazy loading.

Options

  • :limit - Number of results per page (default: 100)
  • :starting_after - Cursor for pagination
  • :project_name - Filter by project name
  • :org_name - Filter by organization name
  • :ids - Filter by specific project IDs (list of strings)
  • :api_key - Override API key for this request
  • :base_url - Override base URL for this request

Examples

iex> {:ok, projects} = Braintrust.Project.list(limit: 10)
iex> is_list(projects)
true

stream(opts \\ [])

@spec stream(keyword()) :: Enumerable.t()

Returns a Stream that lazily paginates through all projects.

This is memory-efficient for large result sets as it only fetches pages as items are consumed.

Options

Same as list/1.

Examples

# Take first 50 projects
Braintrust.Project.stream(limit: 25)
|> Stream.take(50)
|> Enum.to_list()

# Process all projects without loading all into memory
Braintrust.Project.stream()
|> Stream.each(&process_project/1)
|> Stream.run()

update(project_id, params, opts \\ [])

@spec update(String.t(), map(), keyword()) ::
  {:ok, t()} | {:error, Braintrust.Error.t()}

Updates a project.

Uses PATCH semantics - only provided fields are updated. Object fields like settings support deep merge.

Parameters

  • :name - New project name
  • :settings - Settings to merge (deep merge for nested objects)

Options

  • :api_key - Override API key for this request
  • :base_url - Override base URL for this request

Examples

iex> {:ok, project} = Braintrust.Project.update("proj_123", %{name: "new-name"})
iex> project.name
"new-name"

# Update settings (deep merge)
iex> {:ok, project} = Braintrust.Project.update("proj_123", %{
...>   settings: %{comparison_key: "output"}
...> })