roboto.ai.goals.types

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.

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

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

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.

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.

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.

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.