roboto.ai.goals

Goal’s corresponding achieve-tool was invoked successfully.

Goal could not be achieved within the turn’s retry budget.

Goal has been registered but not yet completed.

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

Identifier of the collection every created event is added to. None (the default) means created events are not filed into any collection. When set, the achieve-tool enforces it as an invariant and the target must be an event collection.

Identifier of the dataset to investigate. Every created event is associated with this dataset. The achieve-tool enforces this as an invariant.

Caller-provided natural-language guidance layered on top of the vocabularies (e.g. “only flag intervals longer than five seconds”). None means the vocabulary descriptions alone steer the agent. When set, must be 1-_MAX_EVENT_FOCUS_PROMPT_CHARS characters; an empty string is rejected so callers don’t accidentally suppress the guidance with whitespace-stripped input.

Fixed set of event types the agent may create, mapped to descriptions. Keys are the event names the LLM may choose between — each becomes the name of a created event — and values describe what each event type signifies so the LLM can decide which intervals qualify. Must contain at least one entry and at most _MAX_EVENT_VOCABULARY.

Discriminator. Always GoalType.CREATE_EVENTS.

Fixed set of tags the agent may attach to created events, mapped to descriptions of when each tag applies. For every event it creates the agent picks a subset (possibly empty) of these tags. Empty (the default) means created events carry no tags. At most _MAX_TAG_VOCABULARY entries.

Discriminator. Always GoalType.CREATE_EVENTS.

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.

Identifier of the dataset to summarize. The achieve-tool enforces this as an invariant.

Discriminator. Always GoalType.DATASET_SUMMARY.

Caller-provided natural-language guidance about the desired summary structure. None means use the handler’s opinionated default. When set, must be 1-4000 characters; an empty string is rejected so callers don’t accidentally suppress the default with whitespace-stripped input.

Discriminator. Always GoalType.DATASET_SUMMARY.

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.

Identifier of the dataset to triage. The achieve-tool enforces this as an invariant.

Discriminator. Always GoalType.DATASET_TRIAGE.

Allowable labels for this triage action, mapped to descriptions. Keys are the labels the LLM may choose between; values describe what each label signifies so the LLM can pick correctly. Must contain at least one entry and at most _MAX_TRIAGE_LABELS. Each key must match _TRIAGE_LABEL_PATTERN (ASCII alphanumerics, underscore, hyphen). Each description must be 1-_MAX_TRIAGE_DESCRIPTION_CHARS characters.

Labels for which the LLM voted applies=True.

Matches the set of tags the achieve-tool persisted on the dataset. Returned in declaration order, not the (sorted) order in which the achieve-tool writes them to the dataset; for stable ordering use sorted(result.applied_labels).

Discriminator. Always GoalType.DATASET_TRIAGE.

Optional longer explanation of what the event captures.

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.

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

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 attached to this event. Each must be one of the goal’s declared tag vocabulary keys (enforced by the handler). Empty by default.

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.

The AgentToolResultContent the runner observed for the matching tool_use_id, if any. None when the runner persisted a tool_use but no corresponding tool_result reached the chunk log before the turn terminated.

The AgentToolUseContent the LLM submitted. input carries the raw arguments; the parsed typed fields on the subclass are derived from it.

Terminal status of the goal: ACHIEVED or FAILED.

Investigate a dataset and create events on it, drawn from a caller-supplied event vocabulary; optionally file each created event into a caller-supplied collection.

Produce and persist a dataset summary via SummaryService.set_dataset_summary.

Deliberate over a caller-supplied label vocabulary and apply the labels that fit (zero or more) as tags on the dataset, with a per-label justification recorded in the agent session log.

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.

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

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

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