trajectory

type Config ¶

type Config struct {
	RootProcessID agent.ProcessID
	Termination   agent.Termination
	Output        *agent.Output
	Usage         agent.Usage
	Duration      time.Duration
	Events        []agent.Event
	ModelCalls    []ModelCall
	ToolCalls     []ToolCall
}

Config supplies the complete facts owned by one Trajectory.

type Evaluator ¶

type Evaluator struct{}

Evaluator deterministically checks terminal success, exact Tool behavior, replay consistency, and configured resource regressions for one Sample. Its zero value is ready to use because all case-specific policy belongs to the typed Sample rather than mutable evaluator configuration.

func (Evaluator) Evaluate(ctx context.Context, sample Sample) (eval.Report, error)

type Expectation ¶

type Expectation struct {
	Status   agent.Status  `json:"status"`
	Output   *agent.Output `json:"output,omitempty"`
	Tools    *ToolSequence `json:"tools,omitempty"`
	Baseline *Trajectory   `json:"baseline,omitempty"`
	Limits   Limits        `json:"limits,omitzero"`
}

Expectation describes case-specific success without contaminating Metric identity. Baseline is optional and enables deterministic replay comparison.

func (e Expectation) Validate() error

type Limits ¶

type Limits struct {
	CommittedSteps  *uint64        `json:"committed_steps,omitempty"`
	PreparedEffects *uint64        `json:"prepared_effects,omitempty"`
	AcceptedSignals *uint64        `json:"accepted_signals,omitempty"`
	DroppedDeltas   *uint64        `json:"dropped_deltas,omitempty"`
	TotalTokens     *int64         `json:"total_tokens,omitempty"`
	Duration        *time.Duration `json:"duration,omitempty"`
}

Limits defines optional upper bounds. Pointers distinguish an asserted zero from a dimension the case does not evaluate.

func (l Limits) Validate() error

type ModelCall ¶

type ModelCall struct {
	ProcessID    agent.ProcessID `json:"process_id"`
	StepSequence uint64          `json:"step_sequence"`
	CallSequence uint32          `json:"call_sequence"`
	Response     *chat.Response  `json:"response"`
}

ModelCall is one settled model boundary attributed to an Agent Process Step.

func (m ModelCall) Clone() ModelCall

func (m ModelCall) Validate() error

type Recorder ¶

type Recorder struct {
	// contains filtered or unexported fields
}

Recorder joins the Agent mechanics and Interaction semantic observation boundaries into owned Trajectories. Take consumes one completed root tree so a long-lived Engine does not turn evaluation capture into an unbounded log.

func (r *Recorder) OnEvent(_ context.Context, event agent.Event)

func (r *Recorder) OnModelResponse(
	_ context.Context,
	invocation interaction.ModelInvocation,
	response *chat.Response,
)

func (r *Recorder) OnToolSettled(
	_ context.Context,
	invocation interaction.ToolInvocation,
	settlement interaction.ToolSettlement,
)

func (r *Recorder) OnToolStarted(_ context.Context, invocation interaction.ToolInvocation)

func (r *Recorder) Take(result agent.Result) (Trajectory, error)

type Sample ¶

type Sample struct {
	Actual   Trajectory  `json:"actual"`
	Expected Expectation `json:"expected"`
}

Sample is the typed subject consumed by Evaluator.

func (s Sample) Validate() error

type ToolArguments ¶

type ToolArguments string

ToolArguments is one exact semantic JSON argument assertion. Its empty value matches a Tool call that supplied no argument text.

func (t ToolArguments) Validate() error

type ToolCall ¶

type ToolCall struct {
	ProcessID    agent.ProcessID  `json:"process_id"`
	StepSequence uint64           `json:"step_sequence"`
	ModelCall    uint32           `json:"model_call"`
	Index        uint32           `json:"index"`
	Call         chat.ToolCall    `json:"call"`
	Outcome      ToolOutcome      `json:"outcome"`
	Result       *chat.ToolResult `json:"result,omitempty"`
	Failure      string           `json:"failure,omitempty"`
}

ToolCall is one settled Tool boundary attributed to an Agent Process Step.

func (t ToolCall) Clone() ToolCall

func (t ToolCall) Validate() error

type ToolExpectation ¶

type ToolExpectation struct {
	Name      string         `json:"name"`
	Arguments *ToolArguments `json:"arguments,omitempty"`
	Outcome   ToolOutcome    `json:"outcome,omitempty"`
}

func (t ToolExpectation) Validate() error

type ToolOutcome ¶

type ToolOutcome string

ToolOutcome is the complete host-boundary outcome of one started Tool call.

const (
	ToolOutcomeInvalid       ToolOutcome = ""
	ToolOutcomeSucceeded     ToolOutcome = "succeeded"
	ToolOutcomeError         ToolOutcome = "error"
	ToolOutcomeInputRequired ToolOutcome = "input_required"
	ToolOutcomeFailed        ToolOutcome = "failed"
	ToolOutcomeUnknown       ToolOutcome = "unknown"
)

func (t ToolOutcome) Valid() bool

type ToolSequence ¶

type ToolSequence struct {
	Calls []ToolExpectation `json:"calls"`
}

ToolSequence makes an exact ordered Tool-call assertion explicit. A nil *ToolSequence skips the assertion; a non-nil empty sequence asserts no calls.

type Trajectory ¶

type Trajectory struct {
	// contains filtered or unexported fields
}

Trajectory is an owned, portable record of one completed root Process tree. Absolute timing and provider responses remain available in the record, but BehaviorDigest deliberately excludes them from replay comparison.

func New(config Config) (Trajectory, error)

func (t Trajectory) BehaviorDigest() (string, error)

func (t Trajectory) Clone() (Trajectory, error)

func (t Trajectory) Duration() time.Duration

func (t Trajectory) Events() []agent.Event

func (t Trajectory) MarshalJSON() ([]byte, error)

func (t Trajectory) ModelCalls() []ModelCall

func (t Trajectory) Output() *agent.Output

func (t Trajectory) RootProcessID() agent.ProcessID

func (t Trajectory) Termination() agent.Termination

func (t Trajectory) ToolCalls() []ToolCall

func (t Trajectory) TotalTokens() (int64, error)

func (t *Trajectory) UnmarshalJSON(data []byte) error

func (t Trajectory) Usage() agent.Usage

func (t Trajectory) Validate() error