What is a Version?
A version in Galtea represents a specific iteration of a product. Versions allow you to track changes to your product over time and compare different implementations against the same datasets. You can create, view and manage your versions on the Galtea dashboard or programmatically using the Galtea SDK.How a Version is Identified
A version carries four separate things. Each one has its own job.
The number is local to the product, so every product has its own version 1. Galtea allocates it when the version is created and never changes it. A number is never given to a second version, so a deleted version leaves a permanent gap. Gaps are normal and mean nothing.
Galtea writes the number as
v followed by the number: v1, v7, v42. This is the version’s label.
The name is your own label, for example “support release”. Through the SDK and the API you can leave it out. Galtea then stores the label as the name, so the version reads as v7. The dashboard form still asks you for a name.
Galtea combines the two into one label. The label is v7 when the name is the version’s own label, and v7: support release when you gave the version a name. Galtea never repeats the label, so a version never reads as v7: v7.
A version created before numbers existed keeps whatever name it had, even a name such as
v5. That version and the product’s fifth version can therefore both answer to v5. So a name does not always identify one version. Use the ID whenever you need an exact match.Version Facts
The facts are the agent state a version represents. They are a flat map of text to text. One entry is one piece of that state, for examplemodel: gpt-4o or temperature: 0.7. The facts are optional, so a version with no facts is normal.
You set the facts with the REST API (POST /versions, PATCH /versions/{id} and POST /versions/get-or-create), with the CLI (galtea versions create, galtea versions update and galtea versions get-or-create), with the Galtea SDK (versions.get_or_create and versions.update), or in the dashboard. In the dashboard, use the Facts field on the version create and edit forms, below the description. The version’s details page shows the stored facts in a Facts card.
POST /versions/get-or-create asks for the version of one state instead of creating a row. You send a product and a facts map. Galtea answers the live version of that product whose facts are the ones you sent, and creates that version when no version holds them. So two jobs that run at the same time on one state receive the same version, and neither has to list the versions first and guess. The answer is 200 in both cases, and the key order you send does not change the match.
The SDK can also record the commit the job runs on, under the commit_hash fact. See Get or Create Version.
Read each fact from the same setting your agent runs with, such as an environment variable or a configuration file. Do not type the value a second time. Then a change to the agent’s settings gives a new version with no other edit, and the facts always describe the state that was tested. The GitHub Actions guide shows this.
Galtea normalizes the facts on every write:
- It removes the spaces at the start and the end of every key and every value.
- It drops an entry whose key or value is empty after that.
- It keeps the remaining text exactly. So
0.7and0.70are two different facts. - It stores a map that leaves no entry as no facts.
\u0000), and half of a surrogate pair. Galtea refuses the whole map when a key or a value holds one of them.
Galtea refuses two keys that become equal after the spaces around them are removed, for example model and model . It never keeps one of the two silently. Two keys that both become empty are the one exception: a blank key names no fact, so Galtea drops both instead of refusing the map. A key repeated with the exact same spelling is a different case: JSON parsing keeps only the last value of such a key, so the request reaches Galtea with one entry and this rule never sees it.
The facts are separate from the name and the number. Only the facts say which state a version represents. The name is a label for people, and the number is Galtea’s own sequence.
Comparing Versions
One of the key benefits of tracking versions in Galtea is the ability to compare different implementations of your product. This allows you to:- Measure improvements between versions
- Identify regressions in newer versions
- Compare different model providers or approaches
- Make data-driven decisions about which version to deploy
Run Evaluations
Learn how to run evaluations for your versions
Version Lineage
A version can have a parent version. The parent is the version you started from when you made a new iteration. The new version is called a version revision, and it keeps a link back to its parent. This link lets you trace where each version came from. When you improve a version (for example, you change its system prompt or its model), you create a revision from it instead of starting from scratch. Over time this builds a parent-child chain, so you can follow the full history of how a version evolved. A version with no parent is a root version. Its parent is empty.Lineage is provenance only. The parent link records history. It does not change how the version behaves, how it is evaluated, or how it is compared. A revision is a normal, independent version.
parent_version_id to versions.create to set the parent.
Endpoint Connections
An Endpoint Connection tells Galtea how to call your AI system’s API — the URL, authentication, request format, and how to extract the response. Three roles are available:- Conversation: Handles each interaction turn. Required once you link a connection, and it is the role used when the Conversation Target is HTTP Endpoint
- Initialization (optional): Runs before the conversation to set up a session
- Finalization (optional): Runs after the conversation to release resources
Configure Endpoint Connections
Full reference for URLs, auth types, Jinja2 input templates, JSONPath output mapping, session state management, and retry configuration.
SDK Integration
The Galtea SDK allows you to create, view, and manage versions programmatically. This is particularly useful for organizations that want to automate their versioning process or integrate it into their CI/CD pipeline.Version Service SDK
Manage product versions using the Python SDK
GitHub Actions
Learn how to set up GitHub Actions to automatically create new versions and evaluate them
Version Properties
Integer
required
The number Galtea gives the version. It starts at 1 for each product, never changes, and is never reused. See How a Version is Identified.
Text
Your own label for the version. Example: “v1.2.0” or “GPT-4 Implementation”. The dashboard asks you for one. Through the SDK and the API you can leave it out, and Galtea then stores the version’s label,
v followed by its number. A name of v followed by digits is reserved: see How a Version is Identified.Text
A description of the version, typically highlighting what makes it different from other versions. Example: “Improved summarization algorithm with better fact retention”
Version
The version this one was iterated from. See Version Lineage. Empty for a root version.
Model
required
The AI Model used by this version. Galtea uses this to track costs, calculate per-evaluation inference spend, and associate the version with the model’s pricing and tokenization characteristics.
Text
The system prompt used for this version. Example: “You are an expert legal document summarizer. Provide concise summaries that capture all key legal points.”
EndpointConnection
The primary Endpoint Connection used for the main conversational interactions with your AI product. Connections are optional on a version: in the Dashboard they only appear once you turn on the Link Connection toggle, and when it is on, the required connection is the one matching the selected Conversation Target (HTTP Endpoint, Phone, or WebRTC).Used for:
- Sending user messages
- Receiving AI responses
- (Often) creating and maintaining the external session state
EndpointConnection
An optional Endpoint Connection executed before the conversation begins. Used to initialize a session with your AI product.Used for:
- Creating a session on the external API
- Obtaining a session ID that will be used in subsequent conversation calls
- Setting up initial context or configuration
The initialization endpoint must return a
session_id in its response. Configure the outputMapping with a session_id key pointing to the session identifier in the response. This value is stored in Galtea and made available in subsequent calls via {{ session_id }}.EndpointConnection
An optional Endpoint Connection executed after the conversation ends (including after errors). Used to clean up resources on your AI product.Used for:
- Closing sessions on the external API
- Releasing resources
- Triggering post-conversation processing
The finalization step runs in a
finally block, meaning it executes even if the conversation encounters an error. Errors in the finalization step are logged but do not fail the overall evaluation.Related
Concepts overview
How Galtea’s concepts connect — diagram + per-entity quick reference.
Session
A group of traces that make up a full conversation.
Endpoint Connection
Configure how Galtea calls your AI system’s API.
Evaluation
Run evaluations to assess the performance of your versions.