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

On this page