Transform system

Overview

The transform system bridges rigid API specifications and LLM-friendly interfaces. You define schemas that match the API documentation exactly, and the LLM gets semantic, human-readable types.

Core principle: LLMs should interact with data like humans, not like computers dealing with wire formats.

Transforms compose with the mode system, which controls which fields the LLM sees; transforms control what type those fields have.

The pipeline

APIs speak in rigid formats — base64, RFC822, protobuf JSON.
You annotate schema fields with Format markers matching the API docs.
Charter generates the LLM-facing view, where those fields carry semantic types.
The LLM provides natural input (to/subject/body, not raw MIME).
The transform engine converts semantic input to the exact wire format.
The API receives the payload it expects. No glue code.

Components

1. Transform registry

One place where every transformation is declared, via TransformRegistry:

rfc822_transform.py

from charter import EmailContent, TransformRegistry

@TransformRegistry.register("rfc822_base64", EmailContent, "Email message content")
def transform_email_to_rfc822_base64(email: EmailContent) -> str:
    """Convert EmailContent -> RFC822 -> base64url."""

Declarative registration
Semantic type recorded alongside the function, so schema generation knows what to show the LLM
LLM-friendly description attached to the field

2. Format markers

Annotate the fields that need conversion with Format:

format_marker.py

from typing import Annotated
from pydantic import BaseModel, Field
from charter import Format

class SendEmailRequest(BaseModel):
    raw: Annotated[
        str,
        Field(description="RFC-822, base64url encoded"),
        Format("rfc822_base64"),
    ]

The schema still says exactly what the API says. The marker records where the bridge goes.

3. LLM schema generation

send_email_request.py

# You write:
class SendEmailRequest(BaseModel):
    raw: Annotated[str, Format("rfc822_base64")]

# The LLM sees:
class SendEmailRequest_LLM(BaseModel):
    raw: EmailContent  # semantic type

The generator:

detects Format markers,
replaces the wire type with the registered semantic type,
swaps in the transform’s LLM-facing description,
preserves the Path/Query/Body/Case/Mode markers.

Built-in transforms

Name	Semantic type	Wire format
`rfc822_base64`	`EmailContent`	base64url RFC822 message, unpadded
`mime_base64`	`EmailContent`	standard base64 RFC822 message, padded (Graph)
`email_json`	`EmailContent`	JSON object with wire aliases
`base64`	`str`	standard base64, padded
`base64url`	`str`	URL-safe base64, unpadded
`bytes`	`str`	URL-safe base64 (Google “bytes” fields)
`json_base64`	`dict`	compact JSON, base64
`file_base64`	`FileContent`	standard base64 of the file body
`document_json`	`DocumentContent`	JSON object
`field_mask`	`FieldMask`	comma-joined path string
`proto_json`	protobuf models	plain JSON primitives

bytes and base64url encode identically. The separate name exists for fidelity with Google API specs that annotate a field as bytes.

Nesting

Transforms apply at any depth. The runtime walks nested models and lists, applying every Format marker it finds, then routes the transformed value to the HTTP location its Path/Query/Body marker names.

Registering your own

Call register_transform with the semantic type, the conversion, and the description the LLM will see:

custom_transform.py

from pydantic import BaseModel
from charter import register_transform

class Coordinates(BaseModel):
    lat: float
    lon: float

register_transform(
    "latlon_string",
    Coordinates,
    lambda c: f"{c.lat},{c.lon}",
    "Geographic coordinates",
)

Then Annotated[str, Query(), Format("latlon_string")] shows the LLM a Coordinates object and sends "48.8584,2.2945". The last argument replaces the description of every field the transform is applied to. Give one when the field’s own description is about the wire value the transform hides, as a vendor’s “a base64url encoded string” is: a model told that encodes the value itself, and the API receives it encoded twice. Leave it out and each field keeps its own description, which is what a transform reused across fields wants:

postgrest_filter.py

from typing import Annotated

from pydantic import BaseModel, Field

from charter import Format, Query, register_transform

register_transform("eq", str, lambda v: f"eq.{v}")  # PostgREST: ?topic=eq.ai-safety

class GetFeed(BaseModel):
    topic: Annotated[str, Query(), Format("eq")] = Field(description="A topic id.")

The model reads “A topic id.” and writes ai-safety; the request carries topic=eq.ai-safety.

Failure

An unknown transform name, a payload that will not validate as the semantic type, or a transform function that raises all produce a TransformError naming the transform and the field. Transform failures are never swallowed — a silently untransformed value reaches the API as a confusing 400.

TransformSpec, TransformRegistry, register_transform — the registry API in full
Format — the marker that names a transform
Semantic types — EmailContent, CalendarEvent, DocumentContent, FileContent
TransformError — what a failed conversion raises

Get started

Declaring a tool

The boundary

Authentication

Using your tools

Optimization

Running it

Guarantees

Overview

The pipeline

Components

1. Transform registry

2. Format markers

3. LLM schema generation

Built-in transforms

Nesting

Registering your own

Failure

​Overview

​The pipeline

​Components

​1. Transform registry

​2. Format markers

​3. LLM schema generation

​Built-in transforms

​Nesting

​Registering your own

​Failure

​Related

Overview

The pipeline

Components

1. Transform registry

2. Format markers

3. LLM schema generation

Built-in transforms

Nesting

Registering your own

Failure

Related