traxgen 0.1.4

Trajectory ground truth generator for agentic frameworks

Traxgen

Traxgen is a Python package for generating synthetic multi-agent trajectories for simulation, research, and evaluation purposes. It provides a modular framework to configure agent behaviors, environments, and export formats, making it suitable for academia and industry alike.

Table of Contents

• Introduction
• Features
• Installation
• Usage
• Trajectory Types Support
  • Traxgen Style
  • Tool Only
  • Google Style
  • LangChain Tool Style
• Main Functions
  • generate_trajectories
  • get_required_fields
  • generate_field_template
  • generate_user_profiles
• Example Inputs
  • customer_data
  • routine_data
• Routine JSON Files Explained
  • Agent
  • Steps
  • Soft Ordering
  • Conditionals
  • Operators
  • Actions
  • Example of a Full Routine
• License

---

Introduction

Traxgen simplifies the creation of realistic agent-based trajectories by allowing users to define detailed workflows and behaviors. Whether you are simulating customer support interactions, logistics flows, or other multi-agent scenarios, Traxgen ensures reproducibility and flexibility.

This page contains all information needed to install, configure, and use Traxgen effectively, with examples to help you get started quickly.

---

Features

• Modular framework for trajectory generation that can be extended or customized.
• Multi-agent support, enabling complex interactions among agents.
• Configurable simulation parameters to model real-world scenarios.
• Export options include standard formats like JSON for interoperability with other tools.
• Flexible trajectory styles, accommodating different evaluation ecosystems.

---

Installation

Install Traxgen via pip:

pip install traxgen

---

Usage

Below is a minimal example to generate and save trajectories:

from traxgen import generate_trajectories

# Sample input data
customer_data = [
    {"customer_id": 12345, "name": "Alice", "payment_method": "Card"},
    {"customer_id": 67890, "name": "Bob", "payment_method": "Cash"}
]

# Routine definitions (example JSON loaded into Python objects)
import json
routine_data = {
    "book_train": json.load(open("routine_data/book_train.json")),
    "submit_time_off": json.load(open("routine_data/submit_time_off.json"))
}

# Generate trajectories in 'traxgen' style and save to file
trajectories = generate_trajectories(
    customer_data=customer_data,
    routine_data=routine_data,
    id_field="customer_id",
    trajectory_format="traxgen",
    output_path="output/trajectories.json",
    output_mode="trajectory_only"
)

print("Generated trajectories:", trajectories)

---

Trajectory Types Support

Traxgen supports multiple trajectory output styles. Choose the one that best fits your evaluation pipeline.

Trajectory Type	Description
Traxgen Style	Captures agent name and tool calls with arguments in a nested list format.
Tool Only	Minimalistic, listing only the sequence of tool call names.
Google Style	Compatible with Google's Vertex AI evaluation service, using dictionaries for tool calls.
LangChain Tool Style	Format designed for the LangChain tool evaluation ecosystem.

---

Traxgen Style

[["agent: orchestrator",
    "tool: ask_for_order_id()",
    "tool: get_order_status(order_id=63920)",
    "tool: return_order_status(order_status=Delivered)",
    "tool: close_case(order_id=63920)"]]

---

Tool Only

['ask_for_order_id', 'get_order_status', 'return_order_status', 'close_case']

---

Google Style

[[{'tool_name': 'ask_for_order_id', 'tool_input': {}},
  {'tool_name': 'get_order_status', 'tool_input': {'order_id': 63920}},
  {'tool_name': 'return_order_status', 'tool_input': {'order_status': 'Delivered'}},
  {'tool_name': 'close_case', 'tool_input': {'order_id': 63920}}]]

---

LangChain Tool Style

[
  { "role": "assistant", "tool_calls": [{ "name": "ask_for_order_id", "arguments": {} }]},
  { "role": "assistant", "tool_calls": [{ "name": "get_order_status", "arguments": { "order_id": 63920 }}]},
  { "role": "assistant", "tool_calls": [{ "name": "return_order_status", "arguments": { "order_status": "Delivered" }}]},
  { "role": "assistant", "tool_calls": [{ "name": "close_case", "arguments": { "order_id": 63920 }}]}
]

---

Main Functions

generate_trajectories(...)

Generates user-specific trajectories based on an input sequence of agents and a defined routine.

Arguments:

• customer_data (list of dict): Customer records to generate trajectories for.
• routine_data (dict): Maps routine names to JSON objects defining workflows.
• id_field (str): Key to identify each customer (default: 'customer_id').
• trajectory_format (str or list): Output style(s) (one of "traxgen", "tool_only", "google", "langchain").
• output_path (str, optional): File path to save generated trajectories.
• output_mode (str): "trajectory_only" (default) or "data_and_trajectory".
• external_data (dict, optional): Additional data sources in JSON format.
• enable_visualization (bool): If True, visualize trajectories (default: False).

Returns:

• If output_mode='trajectory_only': List of generated trajectories.
• If output_mode='data_and_trajectory': customer_data with ground truth trajectory field.

Example (if output_mode='trajectory_only' and trajectory_format = traxgen):

[
  [
    "agent: assistant",
    "tool: ask_for_order_id()",
    "tool: get_order_status(order_id=63920)",
    "tool: return_order_status(order_status=Delivered)",
    "tool: close_case(order_id=63920)"
  ],
  ...
]

---

get_required_fields(routine_data)

Extracts a list of required fields from the provided routines, ensuring correct data alignment before trajectory generation.

Arguments:

• routine_data (dict): Maps routine names to JSON objects defining workflows.

Returns:
A list of required field names such as:

['agent_sequence', 'field1', 'field2', ...]

---

generate_field_template(required_fields)

Creates a template dictionary defining distributions or generators for each required field. Useful for setting up synthetic data sampling workflows.

Arguments:

• required_fields (list): List of required fields names.

Returns: A dictionary mapping fields to sampling instructions. Example:

{
  "customer_id": { "random_int(1000, 9999)": 1.0 },
  "payment_method": { "Card": 0.7, "Cash": 0.3 }
}

---

generate_user_profiles(...)

Generates synthetic customer profiles by sampling from field distributions.

Arguments:

• fields (list): List of required field names.
• field_distributions (dict): Value distributions or generators for each field.
• num_samples (int): Number of synthetic profiles to generate.
• write_to_file (bool): If True, save profiles to disk.
• output_path (str, optional): File path to save generated profiles.

Returns: A list of customer profile dictionaries. Example:

[
  {
    "customer_id": 1234,
    "payment_method": "Card",
    ...
  },
  {
    "customer_id": 5678,
    "payment_method": "Cash",
    ...
  }
]

Example Inputs

customer_data

customer_data should be a JSON array (list) of customer dictionaries, for example:

[
  {
    "customer_id": 12345,
    "name": "Alice",
    "address": "123 Main St",
    "payment_method": "Card"
  },
  {
    "customer_id": 67890,
    "name": "Bob",
    "address": "456 Oak Ave",
    "payment_method": "Cash"
  }
]

routine_data

routine_data is a dictionary mapping routine names to JSON objects defining agent workflows. Example:

import json

routine_data = {
    "book_train": json.load(open("routine_data/book_train.json")),
    "submit_time_off": json.load(open("routine_data/submit_time_off.json"))
}

Routine JSON Files Explained

The routine JSON files define the behavior and workflow of your agents. Each routine JSON consists of four main components:

agent

The agent field defines the unique identifier or name of the routine.

steps

• This is an ordered list of all possible tool calls the routine might execute.
• Each step includes the tool call syntax with parameters and expected output variables.
• We list all potential steps, even if some won't be used in every individual trajectory.
• Parameters are mapped to data locations (e.g., customer data or extra inputs).

Example snippet:

"steps": [
  "ask_for_basic_flight_details()",
  "get_customer_preferences(customer_id = customer_id)",
  "search_regular_flights(origin = user_provided_info['origin'], destination = user_provided_info['destination'], ...)",
  "create_booking(flight_number = user_provided_info['flight_number'])"
]

soft_ordering

• A list of lists where each inner list contains tool call names (without parameters).
• Tool calls inside each inner list can execute in any order, enabling multiple valid trajectories by permuting calls.
• For example, two tools means 2! = 2 possible orders; combining groups multiplies permutations.

Example snippet:

"soft_ordering": [
  ["add_special_services", "notify_airport_ground_team"],
  ["search_regular_flights", "search_priority_flights"]
]

This means:

• add_special_services and notify_airport_ground_team can happen in any order.
• search_regular_flights and search_priority_flights can also happen in any order.
• Combining these yields 4 possible valid orderings.

conditionals

Controls which steps execute based on customer data or previous tool outputs.

Each entry follows this structure:

{
  "if": [
    { "field": ..., "operator": ..., "value": ... }
  ],
  "then": [
    { "action": ..., "target": ... }
  ],
  "else": [
    { "action": ..., "target": ... }
  ]
}

• The if block contains one or more condition objects using a field, an operator, and a value. The field references a key in the client data or an external data source provided to the routine (such as API output) whose value is evaluated at runtime.
• The then block defines what to do when the condition is met. The target can be one individual tool call or a list of tool calls.
• The else block (optional) defines what to do when the condition is not met. The target can be one individual tool call or a list of tool calls.
• Each then or else contains one or more {action, target} pairs.

You can also nest conditions using all_of or any_of as follows:

{
  "conditionals": [
    {
      "if": [{ "all_of": [
        { "field": ..., "operator": ..., "value": ... },
        { "field": ..., "operator": ..., "value": ... }
      ]}],
      "then": [{ "action": ..., "target": ... }],
      "else": [{ "action": ..., "target": ... }]
    }
  ]
}

Supported Operators

Each condition in the if block must specify an operator. The following operators are supported:

Operator	Description
==	Equal to
!=	Not equal to
>	Greater than (for numbers only)
<	Less than (for numbers only)
>=	Greater than or equal to (for numbers only)
<=	Less than or equal to (for numbers only)
in	Check if field is in value (e.g., list or set)
not in	Check if field is not in value
contains	Check if value is a substring/item in field
not contains	Check if value is not a substring/item in field
not	Synonym for !=

Common Actions in Conditionals

Within the conditionals section, you control the workflow by specifying actions to take when conditions are met or not met. Supported actions are:

Action	Description
skip	Ignore (skip) the specified tool call(s) for this case if the condition is met.
end_after	End the workflow immediately after executing the specified tool call.
override_trajectory	Ignore all other logic and conditionals for this case; use the specified trajectory exactly.
override_params	Change the parameters passed to a tool call for this case. All parameters must be explicitly provided.

Example of a Full Routine

{
  "agent": "account_suspension_request",
  "steps": [
    "ask_suspension_type() -> [suspension_type]",
    "ask_suspension_reason() -> [reason]",
    "get_user_status(employee_id = employee_id) -> [status]",
    "notify_already_suspended(employee_id = employee_id)",
    "ask_reactivation_date() -> [reactivation_date]",
    "suspend_account(employee_id = employee_id, type = user_provided_info['suspension_type'], reason = user_provided_info['suspension_reason'])",
    "send_suspension_confirmation(employee_id = employee_id)",
    "close_case(suspension_id = suspension['suspension_id'])"
  ],
  "soft_ordering": [
    ["ask_suspension_type", "ask_suspension_reason"]
  ],
  "conditionals": [
    {
      "if": [
        {
          "field": "suspension['suspension_status']",
          "operator": "==",
          "value": "suspended"
        }
      ],
      "then": [
        {
          "action": "end_after",
          "target": "notify_already_suspended"
        }
      ],
      "else": [
        {
          "action": "skip",
          "target": "notify_already_suspended"
        }
      ]
    },
    {
      "if": [
        {
          "field": "user_provided_info['suspension_type']",
          "operator": "!=",
          "value": "temporary"
        }
      ],
      "then": [
        {
          "action": "skip",
          "target": "ask_reactivation_date"
        }],
      "else": [
        {
          "action": "override_params",
          "target": "suspend_account",
          "params": {
            "employee_id": "employee_id",
            "type": "user_provided_info['suspension_type']",
            "reason": "user_provided_info['suspension_reason']",
            "reactivation_date": "user_provided_info['reactivation_date']"
          }
        }
      ]
    }
  ]
}

---

License

This project is licensed under the MIT License.