API Reference
Decorators
Function decorators provided by the Trajectory-IR SDK.
@Trajectory.tool()
Registers a Python function as a durable tool within the Trajectory-IR runtime. The decorated function is automatically wrapped inside a DBOS durable step.
@Trajectory.tool(
effect_class: EffectClass = EffectClass.PURE,
idempotency_key: Optional[str] = None,
timeout_seconds: int = 300,
)
def my_tool(...) -> Any:
...Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
effect_class | EffectClass | PURE | Safety classification. See EffectClass. |
idempotency_key | str | None | None | Required for IDEMPOTENT_WRITE. Auto-generated UUID if omitted. |
timeout_seconds | int | 300 | Maximum execution time before the tool is forcefully terminated. |
Behavior
- Before execution, the tool payload is canonicalized (RFC 8785 JCS) and hashed (SHA256).
- A
DECISION_SEALis written to the metadata log. - The function body executes inside a DBOS durable step.
- On completion, an
Observationnode is automatically appended.
Example
from trajectory_ir.runtime import Trajectory
from trajectory_ir.effects import EffectClass
@Trajectory.tool(
effect_class=EffectClass.IDEMPOTENT_WRITE,
timeout_seconds=60,
)
def update_config(key: str, value: str) -> dict:
"""Updates a configuration value with idempotent PUT semantics."""
return api.put(f"/config/{key}", json={"value": value})