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#

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)

events: list[EventSpec]#: The events to create. May be empty if the agent found no intervals matching the declared event types.

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)

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.

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)

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.

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)

description: str | None = None#: Optional longer explanation of what the event captures.

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.

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

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.

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.

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.

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)

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.

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

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.

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).