Transformers

Overview

The Confident AI SDK exposes every Transformer method on the platform. This page documents how to call these methods in all supported languages. See the introduction to install the SDK and set your API key.

Methods

List Transformers

Lists the transformers in your Confident AI project one page at a time, ordered by name. Use the returned ids for an AI connection's or a metric collection's transformer fields; retrieve one by id to read its code.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.transformers.list(page=1, page_size=25)

For async mode, call a_list and await it as shown below:

result = await client.transformers.a_list(...)

Parameters

Parameter	Type	Description
`page`	`Optional[int]`	The page to return. Defaults to 1.
`page_size`	`Optional[int]`	The number of results per page, at most 100. Defaults to 25.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.transformers.list({ page: 1, pageSize: 25 });

Parameters

Parameter	Type	Description
`page`	`number`	The page to return. Defaults to 1.
`pageSize`	`number`	The number of results per page, at most 100. Defaults to 25.

Returns

This method returns an object of type TransformerList.

Create Transformer

Creates a transformer in your Confident AI project and returns its id. Test the code against a sample before attaching the transformer to anything.

from confident_ai import ConfidentAI
from confident_ai.transformers import TransformerCodeDefinition
from confident_ai.transformers import TransformerLanguage

client = ConfidentAI()

result = client.transformers.create(
    name="Extract nested answer",
    code_definition=TransformerCodeDefinition(
        code="def transformer(data):\n    return data[\"answer\"]",
        language=TransformerLanguage.PYTHON
    ),
    description="Pulls the answer out of a nested envelope.",
)

For async mode, call a_create and await it as shown below:

result = await client.transformers.a_create(...)

Parameters

Parameter	Type	Description
`name`	`str`	Required. The name of the transformer, unique within the project.
`code_definition`	`TransformerCodeDefinition`	Required. See TransformerCodeDefinition.
`description`	`Optional[str]`	What the transformer extracts. Send null to leave it unset.

import { ConfidentAI } from "confident-ai";
import { TransformerLanguage } from "confident-ai/transformers";

const client = new ConfidentAI();

const result = await client.transformers.create(
  "Extract nested answer",
  {
    code: "def transformer(data):\n    return data[\"answer\"]",
    language: TransformerLanguage.PYTHON
  },
  { description: "Pulls the answer out of a nested envelope." },
);

Parameters

Parameter	Type	Description
`name`	`string`	Required. The name of the transformer, unique within the project.
`codeDefinition`	`TransformerCodeDefinition`	Required. See TransformerCodeDefinition.
`description`	`string \| null`	What the transformer extracts. Send null to leave it unset.

Returns

This method returns an object of type TransformerRef.

Get Transformer

Retrieves a transformer by id, including the code it runs. A transformer saved without code returns codeDefinition as null.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.transformers.get(transformer_id="<TRANSFORMER-ID>")

For async mode, call a_get and await it as shown below:

result = await client.transformers.a_get(...)

Parameters

Parameter	Type	Description
`transformer_id`	`str`	Required. The id of the transformer.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.transformers.get("<TRANSFORMER-ID>");

Parameters

Parameter	Type	Description
`transformerId`	`string`	Required. The id of the transformer.

Returns

This method returns an object of type Transformer.

Update Transformer

Renames a transformer, changes its description, or replaces its code, and returns it. Sending codeDefinition overwrites the stored code, which every AI connection and metric collection already using this transformer picks up on its next run.

from confident_ai import ConfidentAI
from confident_ai.transformers import TransformerCodeDefinition
from confident_ai.transformers import TransformerLanguage

client = ConfidentAI()

result = client.transformers.update(
    transformer_id="<TRANSFORMER-ID>",
    name="Extract nested answer",
    description="Pulls the answer out of a nested envelope.",
    code_definition=TransformerCodeDefinition(
        code="def transformer(data):\n    return data[\"answer\"]",
        language=TransformerLanguage.PYTHON
    ),
)

For async mode, call a_update and await it as shown below:

result = await client.transformers.a_update(...)

Parameters

Parameter	Type	Description
`transformer_id`	`str`	Required. The id of the transformer.
`name`	`Optional[str]`	The name of the transformer, unique within the project.
`description`	`Optional[str]`	What the transformer extracts. Send null to clear it.
`code_definition`	`Optional[TransformerCodeDefinition]`	See TransformerCodeDefinition.

import { ConfidentAI } from "confident-ai";
import { TransformerLanguage } from "confident-ai/transformers";

const client = new ConfidentAI();

const result = await client.transformers.update(
  "<TRANSFORMER-ID>",
  {
    name: "Extract nested answer",
    description: "Pulls the answer out of a nested envelope.",
    codeDefinition: {
      code: "def transformer(data):\n    return data[\"answer\"]",
      language: TransformerLanguage.PYTHON
    }
  },
);

Parameters

Parameter	Type	Description
`transformerId`	`string`	Required. The id of the transformer.
`name`	`string`	The name of the transformer, unique within the project.
`description`	`string \| null`	What the transformer extracts. Send null to clear it.
`codeDefinition`	`TransformerCodeDefinition`	See TransformerCodeDefinition.

Returns

This method returns an object of type Transformer.

Delete Transformer

Permanently deletes a transformer and the code stored with it. Anything still pointing at it stops transforming.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.transformers.delete(transformer_id="<TRANSFORMER-ID>")

For async mode, call a_delete and await it as shown below:

result = await client.transformers.a_delete(...)

Parameters

Parameter	Type	Description
`transformer_id`	`str`	Required. The id of the transformer.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.transformers.delete("<TRANSFORMER-ID>");

Parameters

Parameter	Type	Description
`transformerId`	`string`	Required. The id of the transformer.

Returns

This method returns an object of type TransformerRef.

Test Code

Runs the transformer's stored code against a sample value and returns what it produced. Code that raises or times out is a completed test, so it comes back with a 200 and success: false carrying error and reason — branch on success rather than on the status. A 400 means the transformer has no code saved to run.

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.transformers.test_code(
    transformer_id="<TRANSFORMER-ID>",
    input_data={
        "data": {"answer": "Mount Everest is 8,849 metres tall."}
    },
)

For async mode, call a_test_code and await it as shown below:

result = await client.transformers.a_test_code(...)

Parameters

Parameter	Type	Description
`transformer_id`	`str`	Required. The id of the transformer.
`input_data`	`Optional[Any]`	The value to pass to the transformer's `transformer` function. Any JSON value is accepted; send the shape the transformer expects to see in production.

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.transformers.testCode(
  "<TRANSFORMER-ID>",
  {
    inputData: { data: { answer: "Mount Everest is 8,849 metres tall." } }
  },
);

Parameters

Parameter	Type	Description
`transformerId`	`string`	Required. The id of the transformer.
`inputData`	`unknown`	The value to pass to the transformer's `transformer` function. Any JSON value is accepted; send the shape the transformer expects to see in production.

Returns

This method returns an object of type TransformerCodeRunResult.

Types

Transformer

Code that reshapes a value on its way into or out of an evaluation, such as extracting the answer from your endpoint's response.

class Transformer:
    id: str
    name: str
    description: Optional[str]
    created_at: str = Field(alias="createdAt")
    updated_at: str = Field(alias="updatedAt")
    code_definition: Optional[TransformerCodeDefinition] = Field(alias="codeDefinition")

idstrRequired

The id of the transformer, generated by Confident AI.

Example: "<TRANSFORMER-ID>"

namestrRequired

The name of the transformer.

Example: "Extract nested answer"

descriptionOptional[str]Required

What the transformer extracts.

Example: "Pulls the answer out of a nested envelope."

created_atstrRequired

The timestamp when the transformer was created.

Example: "2025-01-15T10:30:00+00:00"

updated_atstrRequired

The timestamp when the transformer was last updated.

Example: "2025-01-20T08:15:00+00:00"

code_definitionOptional[TransformerCodeDefinition]Required

The code the transformer runs, or null when no code has been saved for it yet.

See TransformerCodeDefinition.

interface Transformer {
  id: string;
  name: string;
  description: string | null;
  createdAt: string;
  updatedAt: string;
  codeDefinition: TransformerCodeDefinition | null;
}

idstringRequired

The id of the transformer, generated by Confident AI.

Example: "<TRANSFORMER-ID>"

namestringRequired

The name of the transformer.

Example: "Extract nested answer"

descriptionstring | nullRequired

What the transformer extracts.

Example: "Pulls the answer out of a nested envelope."

createdAtstringRequired

The timestamp when the transformer was created.

Example: "2025-01-15T10:30:00+00:00"

updatedAtstringRequired

The timestamp when the transformer was last updated.

Example: "2025-01-20T08:15:00+00:00"

codeDefinitionTransformerCodeDefinition | nullRequired

The code the transformer runs, or null when no code has been saved for it yet.

See TransformerCodeDefinition.

TransformerCodeDefinition

The code a transformer runs, with the language it is written in.

class TransformerCodeDefinition:
    code: str
    language: TransformerLanguage

codestrRequired

The source of the transformer. It must define a top-level transformer function that takes the value being transformed and returns the value to use in its place.

Example: "def transformer(data):\n return data[\"answer\"]"

languageTransformerLanguageRequired

See TransformerLanguage.

interface TransformerCodeDefinition {
  code: string;
  language: TransformerLanguage;
}

codestringRequired

The source of the transformer. It must define a top-level transformer function that takes the value being transformed and returns the value to use in its place.

Example: "def transformer(data):\n return data[\"answer\"]"

languageTransformerLanguageRequired

See TransformerLanguage.

TransformerCodeRunResult

What running the transformer's code against your sample produced. Branch on success: the code raising is reported here, not as an error status.

TransformerCodeRunResult = Union[
    TransformerCodeRunSuccess,
    TransformerCodeRunFailure,
]

type TransformerCodeRunResult =
  | TransformerCodeRunSuccess
  | TransformerCodeRunFailure;

A TransformerCodeRunResult is one of the shapes below. Send the fields of one of them, never a mix of both.

A run of the transformer's code that returned a value.

class TransformerCodeRunSuccess:
    success: bool
    output: Optional[Any] = None
    verbose_logs: Optional[str] = Field(alias="verboseLogs")

successboolRequired

Marks the run as successful.

Example: true

outputOptional[Any]

The value the transformer returned. Any JSON value.

Example: "Mount Everest is 8,849 metres tall."

verbose_logsOptional[str]Required

Anything the code printed while it ran, or null when it printed nothing.

interface TransformerCodeRunSuccess {
  success: boolean;
  output?: unknown;
  verboseLogs: string | null;
}

successbooleanRequired

Marks the run as successful.

Example: true

outputunknown

The value the transformer returned. Any JSON value.

Example: "Mount Everest is 8,849 metres tall."

verboseLogsstring | nullRequired

Anything the code printed while it ran, or null when it printed nothing.

A run of the transformer's code that raised or timed out. Code that fails is still a completed test, so this is returned with a 200; branch on success.

class TransformerCodeRunFailure:
    success: bool
    error: Optional[str]
    reason: Optional[str]
    verbose_logs: Optional[str] = Field(alias="verboseLogs")

successboolRequired

Marks the run as failed.

Example: false

errorOptional[str]Required

What went wrong, as the code executor reported it, or null when it gave no message.

Example: "KeyError: 'answer'"

reasonOptional[str]Required

A fuller explanation of the failure, such as a traceback, or null when there is none.

Example: "Traceback (most recent call last):\n File \"transformer.py\", line 2, in transform"

verbose_logsOptional[str]Required

Anything the code printed while it ran, or null when it printed nothing.

interface TransformerCodeRunFailure {
  success: boolean;
  error: string | null;
  reason: string | null;
  verboseLogs: string | null;
}

successbooleanRequired

Marks the run as failed.

Example: false

errorstring | nullRequired

What went wrong, as the code executor reported it, or null when it gave no message.

Example: "KeyError: 'answer'"

reasonstring | nullRequired

A fuller explanation of the failure, such as a traceback, or null when there is none.

Example: "Traceback (most recent call last):\n File \"transformer.py\", line 2, in transform"

verboseLogsstring | nullRequired

Anything the code printed while it ran, or null when it printed nothing.

TransformerLanguage

The language a transformer's code is written in.

class TransformerLanguage(Enum):
    PYTHON = "PYTHON"

enum TransformerLanguage {
  PYTHON = "PYTHON",
}

PYTHON

TransformerList

One page of transformers, with the total across all pages.

class TransformerList:
    transformers: List[TransformerSummary]
    total_transformers: int = Field(alias="totalTransformers")
    page: int
    page_size: int = Field(alias="pageSize")

transformersList[TransformerSummary]Required

The transformers for the current page, ordered by name.

See TransformerSummary.

total_transformersintRequired

The total number of transformers in this project.

Example: 4

pageintRequired

The page this response covers.

Example: 1

page_sizeintRequired

The number of transformers per page.

Example: 25

interface TransformerList {
  transformers: TransformerSummary[];
  totalTransformers: number;
  page: number;
  pageSize: number;
}

transformersTransformerSummary[]Required

The transformers for the current page, ordered by name.

See TransformerSummary.

totalTransformersnumberRequired

The total number of transformers in this project.

Example: 4

pagenumberRequired

The page this response covers.

Example: 1

pageSizenumberRequired

The number of transformers per page.

Example: 25

TransformerRef

A reference to a transformer by its id.

class TransformerRef:
    id: str

idstrRequired

The id of the transformer, generated by Confident AI.

Example: "<TRANSFORMER-ID>"

interface TransformerRef {
  id: string;
}

idstringRequired

The id of the transformer, generated by Confident AI.

Example: "<TRANSFORMER-ID>"

TransformerSummary

A transformer as it appears in a list: what it is and when it changed, without its code. Retrieve one by id to read the code.

class TransformerSummary:
    id: str
    name: str
    description: Optional[str]
    created_at: str = Field(alias="createdAt")
    updated_at: str = Field(alias="updatedAt")

idstrRequired

The id of the transformer, generated by Confident AI.

Example: "<TRANSFORMER-ID>"

namestrRequired

The name of the transformer.

Example: "Extract nested answer"

descriptionOptional[str]Required

What the transformer extracts.

Example: "Pulls the answer out of a nested envelope."

created_atstrRequired

The timestamp when the transformer was created.

Example: "2025-01-15T10:30:00+00:00"

updated_atstrRequired

The timestamp when the transformer was last updated.

Example: "2025-01-20T08:15:00+00:00"

interface TransformerSummary {
  id: string;
  name: string;
  description: string | null;
  createdAt: string;
  updatedAt: string;
}

idstringRequired

The id of the transformer, generated by Confident AI.

Example: "<TRANSFORMER-ID>"

namestringRequired

The name of the transformer.

Example: "Extract nested answer"

descriptionstring | nullRequired

What the transformer extracts.

Example: "Pulls the answer out of a nested envelope."

createdAtstringRequired

The timestamp when the transformer was created.

Example: "2025-01-15T10:30:00+00:00"

updatedAtstringRequired

The timestamp when the transformer was last updated.

Example: "2025-01-20T08:15:00+00:00"

Building a production pipeline?Design a scalable API workflow for evals, datasets, traces, and promptsTalk to an engineer

Last updated on September 30, 2026

Built byConfident AI