Trajectory Client

The Trajectory dataclass and functions for creating, projecting, and resuming durable agent trajectories.

Overview

The Python client isn't a fluent class, it's a plain Trajectory dataclass paired with a handful of module-level functions in trajectory_ir.runtime. You get a Trajectory instance back from open_trajectory() or resume(), then pass it into everything else.

The Trajectory dataclass

@dataclass
class Trajectory:
    trajectory_id: str
    tenant_id: str
    db_path: str
    mode: str

Fields

Field	Type	Description
`trajectory_id`	`str`	UUID identifying this trajectory.
`tenant_id`	`str`	Identifier for the tenant/user that owns the trajectory.
`db_path`	`str`	Path to the metadata store backing this trajectory.
`mode`	`str`	Execution mode the trajectory was opened with.

There's no constructor to call directly. Instances come from open_trajectory() or resume() below.

`open_trajectory()`

Creates a new trajectory and its backing metadata store.

def open_trajectory(
    tenant_id: str,
    db_path: str,
    mode: str = "durable",
    trajectory_id: Optional[str] = None,
) -> Trajectory:

Parameters

Parameter	Type	Default	Description
`tenant_id`	`str`	required	Identifier for the tenant/user owning the trajectory.
`db_path`	`str`	required	Path to the metadata store to create or attach to.
`mode`	`str`	`"durable"`	Execution mode for the trajectory.
`trajectory_id`	`str \| None`	`None`	Optional UUID. Auto-generated if omitted.

Returns: a Trajectory instance.

Example:

from trajectory_ir.runtime import open_trajectory

traj = open_trajectory(tenant_id="demo-user", db_path="~/.trajectory-ir/local.db")
print(traj.trajectory_id)

`project()`

Replays a trajectory's node log and returns its current semantic state. Useful for checking what's already happened before deciding on the next step.

def project(trajectory: Trajectory) -> dict:

Returns: a dict snapshot of the nodes recorded for the trajectory so far.

Example:

from trajectory_ir.runtime import project

state = project(traj)
print(state["nodes"])

`resume()`

Reattaches to an existing trajectory after a process restart or crash, picking up wherever the metadata log left off.

def resume(trajectory_id: str, db_path: str) -> Trajectory:

Parameters

Parameter	Type	Default	Description
`trajectory_id`	`str`	required	ID of the trajectory to resume.
`db_path`	`str`	required	Path to the metadata store the trajectory was originally opened against.

Returns: the reattached Trajectory instance. If the log has a dangling DECISION_SEAL for a NON_IDEMPOTENT_WRITE tool, the trajectory comes back in a BLOCKED_NEEDS_GATE state instead of re-running it.

On this page