Skip to main content
You are reading the docs of Galtea 5.17. Read this page in the latest version.

What are Content Parts?

A trace input, a trace output and a test case input can be an object with a content list. Each element of that list is a content part: a text, an image, a file or an audio clip. A part names its kind in its type field.
Galtea decides for each element of the list on its own whether it is a Galtea file, and checks and stores each element on its own.

Galtea Files

A Galtea file is a file you uploaded to Galtea, or one that Galtea stored from inline media in a trace. Galtea knows it by its key, the storage name that the upload or the copy gives it. The key has this shape: files/<organization id>/<32 lowercase hex characters>.<extension>. A file part is a Galtea file when the path of its uri is that key. The path can also start with one extra segment, the storage bucket or container. Galtea reads the key on any host, and also in a signed URL. The URI that galtea.storage.upload() returns with the default file_type is a Galtea file. So is any URL that Galtea returns for a Galtea file, even when its path has more segments before the key. In the example above, the second part is a Galtea file and the third part is not. See Audio Parts for audio, which follows its own rules. To get a key, upload the file with the SDK or attach it in the dashboard. The SDK input_file_paths and output_file_paths parameters upload a local file for you. See Upload File. When you attach a Galtea file part of your organization, Galtea does these things:
  • It stores the uri without its upload signature, so the reference you read back never expires.
  • It fills mimeType from the stored file when you leave it out, and filename too where the storage keeps the name. It always reads sizeBytes from the stored file.
  • It checks the file type. A type that is not accepted fails with the message "<name>" is not an accepted file type. The accepted types are listed in File inputs.
  • It checks the limits: at most 20 files and 20 MB in total for one input or one output.

Your Own Parts

Every element that is not a Galtea file is yours. Galtea stores it exactly as you sent it. This includes:
  • A text part.
  • An image_url part.
  • A file part that names an OpenAI file_id.
  • An element with no type.
  • A file URL on your own host, such as https://cdn.example.com/files/acme/report.pdf.
Galtea does not fetch a URL on your own host when it stores one of these elements. A run sends only Galtea files to your endpoint, through input_files. Your own file parts are left out of input_files, and the turn runs without them. A file that an endpoint connection returns in its response follows other rules: see Files in the Response. The SDK lists every file part that has a uri in .input_files and .actual_output_files, your own included. Only a Galtea file can be fetched with galtea.storage.download() or galtea.storage.read(). For any other URL the platform answers that the file is not found, so fetch it with your own client.

What Happens to Each Element

The trace columns also hold for the input and output of a span. In a batch of spans, a span with a Galtea file of another organization is refused on its own and the other spans are stored. On a deployment that sets the API variable INLINE_MEDIA_COPY_ENABLED to true, Galtea replaces inline media in a trace input or output with a Galtea file token, and stores the file. Inline media is a binary data: URI, or the byte field of a provider object: an Anthropic base64 source, a Gemini inline_data, a Vertex media part, a Bedrock source.bytes, an OpenTelemetry blob, a Vercel AI SDK file or image part, or an MCP image, audio or resource blob. A byte field may hold base64, a data: URI or a Python bytes literal (b'...'), but a Python bytes literal inside JSON held in a string stays as sent. Text, files under about 768 bytes (1,024 base64 characters), files of a type Galtea does not detect, and files over 20 MB stay as sent. The copy applies to every trace write: traces sent with or without a turn id, span writes, and a trace file import. It does not apply to a test case input. The copy is off by default. The dashboard shows each token in a trace or span input or output as the file it names, with the same preview and download controls as an uploaded file. The Raw view shows the token as stored. When a run sends an earlier turn to your endpoint again, for example in past_turns, Galtea puts the stored file back, even after the copy is turned off. A data: URI comes back as a data: URI. A byte field comes back as base64, also when you sent a data: URI or a bytes literal in it. When the stored file is missing or over 20 MB, your endpoint receives the @@@galtea-file:...@@@ token text in its place. The restored text of one request to your endpoint, past turns included, is at most 50 MB. Past that, the session fails and your endpoint does not receive the turn. Past turns reach your agent with their inline media restored from SDK 5.17.0; an earlier SDK passes the stored file token. The same 50 MB limit holds for each turn the SDK rebuilds: past it, the API answers 400 and the run fails, where an earlier SDK went on with the token. A read through the API or the SDK returns the stored token text, unless it asks for restoreFiles (restore_files in the SDK). An evaluation judge reads [File N] in place of the token, with N the file’s number in the session, and a stored image or PDF counts as a Galtea file: see Files and Evaluation. An edit that keeps a Galtea file unchanged does not read storage again. So the edit succeeds even when someone deleted the file after you attached it.

Audio Parts

Galtea does not apply the file checks above to an audio part. It does not check its type, its size or the file count. On a test case input, an audio part needs a transcript.

Files and Evaluation

Only a Galtea file is sent to the judge, the model that scores a metric. A file that Galtea stored from inline media counts as a Galtea file when it is an image or a PDF. A stored audio or other file reads as [File N] text and never makes the evaluator skip a metric. The judge reads each element of a content list in its place: a Galtea file as [File N], a text part as its text, an audio part as its transcript, and any other element, a file on your own host included, as its JSON text. A file on your own host is never sent as a file, so it never makes the evaluator skip a metric. Galtea numbers the files of a session in one sequence: turn files first, in turn order, input before output, then the files of every span. A file that sits in several places of a session, as a file part or as a token, takes one number, and the judge receives it once. The session page shows the same File N beside each turn file. The API check that a metric has text to read is separate: it counts every file part as a file, yours included. Most deployments do not send files to the judge yet: see File inputs for which metrics Galtea skips when a turn carries a Galtea file.

SDK Checks

In the SDK, each entry of input_file_paths and output_file_paths is a local path or a Galtea file reference, such as the uri of a Galtea file in trace.input_files. A URL whose path does not end in a Galtea key, such as https://cdn.example.com/files/acme/report.pdf, raises a ValueError before the SDK uploads anything. To keep a file on your own host, put its URL in a file part of input or output yourself.