roboto.ai.goals.achieve_inputs

Pydantic models for the inputs an achieve-tool receives from the LLM.

Each model captures the exact JSON shape the LLM submits when invoking the achieve-tool for a goal of the corresponding GoalType. The models are shared between the server-side handlers (which validate the LLM’s tool_use input against them) and the SDK-side roboto.ai.goals.results GoalResult discriminated union (which re-hydrates the same shape from the persisted message stream).

Vocabulary-aware constraints (e.g. “label must be one of the goal’s declared labels”, “event name must be in the goal’s event vocabulary”) are not expressible at the static-model level because they depend on the goal instance; the server-side handler enforces them as a second pass after this structural validation. The SDK does not enforce them at all — historical tool_use inputs have already passed both Bedrock’s schema check and the handler’s vocab check at the time they were persisted.

Module Contents

CreateEventsAchieveInput

class roboto.ai.goals.achieve_inputs.CreateEventsAchieveInput(/, **data)#

Bases: pydantic.BaseModel

Input the LLM submits to achieve a GoalType.CREATE_EVENTS goal.

Parameters

data Any

Attributes

CreateEventsAchieveInput.events

events list[EventSpec] #

The events to create. May be empty if the agent found no intervals matching the declared event types.

DatasetSummaryAchieveInput

class roboto.ai.goals.achieve_inputs.DatasetSummaryAchieveInput(/, **data)#

Bases: pydantic.BaseModel

Input the LLM submits to achieve a GoalType.DATASET_SUMMARY goal.

Parameters

data Any

Attributes

DatasetSummaryAchieveInput.summary

summary str = None #

The full natural-language summary to persist for the dataset.

Must contain non-whitespace characters; the achieve-tool rejects pure whitespace as equivalent to empty.

DatasetTriageAchieveInput

class roboto.ai.goals.achieve_inputs.DatasetTriageAchieveInput(/, **data)#

Bases: pydantic.BaseModel

Input the LLM submits to achieve a GoalType.DATASET_TRIAGE goal.

Parameters

data Any

Attributes

DatasetTriageAchieveInput.label_decisions

label_decisions list[LabelDecision] = None #

One LabelDecision per entry in the goal’s label_vocabulary.

Vocabulary completeness — every label declared on the goal appears exactly once, with no duplicates — is enforced by the server-side handler. This model only validates the structural shape of each decision.

EventSpec

class roboto.ai.goals.achieve_inputs.EventSpec(/, **data)#

Bases: pydantic.BaseModel

One event the LLM proposes inside a CreateEventsAchieveInput.

The name must come from the parent goal’s event_vocabulary and every tags entry from the goal’s tag_vocabulary; both checks live in the server-side handler because they depend on the goal instance.

Parameters

data Any

Attributes

EventSpec.description

description str | None = None #

Optional longer explanation of what the event captures.

EventSpec.end_time

end_time pydantic.StrictInt #

Event end, in nanoseconds since the Unix epoch. Must be greater than or equal to start_time.

Strictly typed for the same reason as start_time.

EventSpec.name

name str #

The kind of event. Must be one of the goal’s declared event vocabulary names (enforced by the handler).

EventSpec.start_time

start_time pydantic.StrictInt #

Event start, in nanoseconds since the Unix epoch.

Strictly typed: pydantic would otherwise coerce stringified integers and (notably) booleans — True would silently parse as timestamp 1. The historical achieve-tool contract required a JSON integer.

EventSpec.tags

tags list[str] = None #

Tags attached to this event. Each must be one of the goal’s declared tag vocabulary keys (enforced by the handler). Empty by default.

EventSpec.target_id

target_id str | None = None #

Identifier of the Roboto entity this event is attached to. The server-side handler infers the entity type from the id prefix (ds_ / fl_ / tp_ / mp_) and enforces that the target descends from the goal’s dataset.

Optional rather than required so the SDK can re-hydrate CreateEventsGoalResult from persisted tool-use records written before per-event target scoping was added — those carry no target_id on each spec. Current-day records always carry a non-empty value; the handler rejects None on new invocations via a corrective tool-failure response.

LabelDecision

class roboto.ai.goals.achieve_inputs.LabelDecision(/, **data)#

Bases: pydantic.BaseModel

One per-label deliberation entry inside a DatasetTriageAchieveInput.

Every label in the goal’s label_vocabulary must appear exactly once across the parent label_decisions list — that constraint is enforced by the server-side handler after structural validation, since the vocabulary is goal-instance-specific.

Parameters

data Any

Attributes

LabelDecision.applies

applies pydantic.StrictBool #

Whether the label applies to the dataset. True decisions become tags on the dataset; False decisions are recorded in the tool-use log but not persisted on the dataset itself.

Strictly typed to reject pydantic’s default truthy-string coercion — the historical achieve-tool contract required a JSON boolean, not a boolean-coerced string or integer.

LabelDecision.confidence

confidence float = None #

Subjective confidence in the decision, from 0.0 (no confidence) to 1.0 (certain). Recorded but not used to gate persistence.

LabelDecision.justification

justification str = None #

Brief reasoning for the decision, citing concrete observations from the dataset. Required even when applies is False so the deliberation is captured.

LabelDecision.label

label str #

The vocabulary label this decision concerns. Must match one of the goal’s label_vocabulary keys (enforced by the handler against the declaring goal).