roboto.ai.goals

Submodules

• roboto.ai.goals.types

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

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.