roboto.ai.goals#

Submodules#

Package Contents#

roboto.ai.goals.AgentGoal#

Closed, Roboto-controlled discriminated union of all declarable agent goals.

Validated via pydantic discriminator on goal_type. Add new goals by extending the Union and registering a corresponding GoalHandler.

A goal is the right primitive when the caller has an upfront, verifiable platform mutation the turn must complete — and is willing to fail the turn (AgentThreadStatus.GOALS_FAILED) if the action doesn’t happen. Goals power specialized agents with deterministic, directionally opinionated behavior. One-off LLM-discovered actions and pure reads belong as regular AgentTool registrations; actions that don’t need an LLM at all belong as direct REST endpoints. The registry is closed to keep this discipline visible at PR-review time.

class roboto.ai.goals.AgentGoalStatus#

Bases: roboto.compat.StrEnum

Lifecycle of a per-turn declared goal.

Goals begin PENDING when registered. They transition to ACHIEVED when the corresponding achieve-tool reports success, or to FAILED when the runner’s corrective re-prompt budget for the turn is exhausted (or when the worker cannot construct an achieve-tool for the goal).

ACHIEVED = 'achieved'#

Goal’s corresponding achieve-tool was invoked successfully.

FAILED = 'failed'#

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

PENDING = 'pending'#

Goal has been registered but not yet completed.

class roboto.ai.goals.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.CreateEventsGoal(/, **data)#

Bases: AgentGoalBase

Goal: investigate a dataset and create tagged events on it from fixed vocabularies.

The caller declares event_vocabulary — a fixed set of event types (name → description) the agent may create — and, optionally, tag_vocabulary — a fixed set of tags (tag → when-to-apply description) the agent may attach. The achieve-tool constrains every submitted event’s name to an event_vocabulary key and every tag to a tag_vocabulary key, so the agent can only file events of the declared kinds carrying the declared tags; the descriptions steer which intervals qualify and which tags fit. Every created event is associated with the dataset identified by dataset_id. When collection_id is set, each created event is also added to that (event) collection; when it is None, events are created but not filed into any collection. The dataset id — and the collection id when set — are constructor-injected into the achieve-tool so the LLM cannot redirect the work.

Parameters:

data (Any)

collection_id: str | None = None#

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.

dataset_id: str#

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

event_focus_prompt: str | None = None#

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.

event_vocabulary: dict[str, str] = None#

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.

goal_type: Literal[GoalType]#

Discriminator. Always GoalType.CREATE_EVENTS.

tag_vocabulary: dict[str, str] = None#

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.

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

Bases: GoalResultBase, roboto.ai.goals.achieve_inputs.CreateEventsAchieveInput

Result of a GoalType.CREATE_EVENTS achieve-tool invocation.

Exposes the list of EventSpec objects the LLM submitted. The SDK does not currently surface the resulting event ids directly from this result — callers wanting the created events should query the dataset’s events using the time bounds in events. (Surfacing event ids here would require an API-layer round-trip back to the achieve-tool’s response payload; YAGNI until a caller needs it.)

Parameters:

data (Any)

goal_type: Literal[roboto.ai.goals.types.GoalType.CREATE_EVENTS]#

Discriminator. Always GoalType.CREATE_EVENTS.

class roboto.ai.goals.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.DatasetSummaryAgentGoal(/, **data)#

Bases: AgentGoalBase

Goal: summarize a specific dataset and persist the result.

The achieve-tool wired to this goal must call SummaryService.set_dataset_summary against the dataset identified by dataset_id (no other dataset). The format spec is supplied to the LLM as part of the goal prompt block; the achieve-tool itself does not interpret it.

Parameters:

data (Any)

dataset_id: str#

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

goal_type: Literal[GoalType]#

Discriminator. Always GoalType.DATASET_SUMMARY.

summary_format_spec_prompt: str | None = None#

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.

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

Bases: GoalResultBase, roboto.ai.goals.achieve_inputs.DatasetSummaryAchieveInput

Result of a GoalType.DATASET_SUMMARY achieve-tool invocation.

Exposes the LLM-submitted summary directly alongside the raw achieve_tool_use / achieve_tool_result blocks.

Parameters:

data (Any)

goal_type: Literal[roboto.ai.goals.types.GoalType.DATASET_SUMMARY]#

Discriminator. Always GoalType.DATASET_SUMMARY.

class roboto.ai.goals.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.DatasetTriageGoal(/, **data)#

Bases: AgentGoalBase

Goal: deliberate over a caller-supplied label vocabulary and apply the labels that fit.

The achieve-tool requires one decision per vocabulary entry — each with applies: bool plus a justification and confidence. Labels with applies=true (zero or more) become tags on the dataset identified by dataset_id; per-label reasoning lives in the agent session log, not on the dataset itself.

Parameters:

data (Any)

dataset_id: str#

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

goal_type: Literal[GoalType]#

Discriminator. Always GoalType.DATASET_TRIAGE.

label_vocabulary: dict[str, str] = None#

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.

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

Bases: GoalResultBase, roboto.ai.goals.achieve_inputs.DatasetTriageAchieveInput

Result of a GoalType.DATASET_TRIAGE achieve-tool invocation.

Exposes the full per-label deliberation in label_decisions; use applied_labels for the convenience subset that actually became tags on the dataset.

Parameters:

data (Any)

property applied_labels: list[str]#

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

Return type:

list[str]

goal_type: Literal[roboto.ai.goals.types.GoalType.DATASET_TRIAGE]#

Discriminator. Always GoalType.DATASET_TRIAGE.

class roboto.ai.goals.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.

roboto.ai.goals.GoalResult#

Closed, Roboto-controlled discriminated union of every typed goal result.

Validated via pydantic discriminator on goal_type. Mirrors the shape of AgentGoal so adding a new goal type means:

  1. Add a new GoalType member.

  2. Add a new AgentGoal subclass in roboto.ai.goals.types.

  3. Add a matching achieve-input model in roboto.ai.goals.achieve_inputs.

  4. Add a new GoalResult subclass here that inherits from both GoalResultBase and the new achieve-input model.

No API or wire-schema change is needed because the SDK builds the result from the persisted message stream via achieve_tool_use_id.

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

Bases: pydantic.BaseModel

Shared base for every concrete GoalResult.

Subclasses must declare a literal-typed goal_type field so the discriminated union can dispatch — and must also inherit from the matching achieve-input model from roboto.ai.goals.achieve_inputs so the parsed typed fields land alongside the raw blocks.

Parameters:

data (Any)

achieve_tool_result: roboto.ai.core.content.AgentToolResultContent | None = None#

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.

achieve_tool_use: roboto.ai.core.content.AgentToolUseContent#

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

status: roboto.ai.goals.types.AgentGoalStatus#

ACHIEVED or FAILED.

Type:

Terminal status of the goal

class roboto.ai.goals.GoalType#

Bases: roboto.compat.StrEnum

Discriminator values for the AgentGoal union.

Each value pairs with exactly one pydantic.BaseModel subclass below and one server-side GoalHandler registration. The string value is the canonical identifier used in persistence (agent_session_goals.goal_type), in the Bedrock-facing achieve-tool name, and in the wire format.

CREATE_EVENTS = 'create_events'#

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.

DATASET_SUMMARY = 'dataset_summary'#

Produce and persist a dataset summary via SummaryService.set_dataset_summary.

DATASET_TRIAGE = 'dataset_triage'#

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.

class roboto.ai.goals.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).

On this page