roboto.ai.goals.types

Module Contents

roboto.ai.goals.types.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 (AgentSessionStatus.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.types.AgentGoalBase(/, **data)

Bases: pydantic.BaseModel

Shared base for every AgentGoal subclass.

Subclasses must declare a literal-typed discriminator field, e.g. goal_type: Literal[GoalType.MY_GOAL] = GoalType.MY_GOAL. Two machineries enforce that contract:

• __pydantic_init_subclass__() raises TypeError at class-body parse if a subclass forgets goal_type — converts a silent dispatch footgun into a loud failure.

• _force_discriminator_into_fields_set() marks goal_type as explicitly set after construction so it survives the SDK’s model_dump_json(exclude_unset=True) serialization and reaches the server’s discriminated-union parser. Without it, default-valued goal_type would be stripped on the wire and the server would 400 with “Request body malformed”.

Parameters:

data (Any)

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

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.