roboto.ai.core#

Core AI abstractions usable by any other submodule within module roboto.ai.

Submodules#

Package Contents#

type roboto.ai.core.AgentContent = AgentTextContent | AgentToolUseContent | AgentToolResultContent | AgentErrorContent#: Type alias for all possible content types within agent messages.

class roboto.ai.core.AgentContentType#

Bases: roboto.compat.StrEnum

Enumeration of different types of content within agent messages.

Defines the various content types that can be included in agent messages.

ERROR = 'error'#: Error information when message generation fails.

TEXT = 'text'#: Plain text content from users or AI responses.

TOOL_RESULT = 'tool_result'#: Results returned from tool executions.

TOOL_USE = 'tool_use'#: Tool invocation requests from the AI assistant.

class roboto.ai.core.AgentErrorContent(/, **data)#

Bases: pydantic.BaseModel

Error content within an agent message.

Used when message generation fails due to an error or is cancelled by the user.

Parameters:: data (Any)

content_type: Literal[AgentContentType]#

error_code: str | None = None#: Optional error code for programmatic handling.

error_message: str#: User-friendly error message describing what went wrong.

class roboto.ai.core.AgentErrorEvent(/, **data)#

Bases: pydantic.BaseModel

Signals that message generation failed or was cancelled.

Parameters:: data (Any)

error_code: str | None = None#: Optional error code for programmatic handling.

error_message: str#: User-friendly error message describing what went wrong.

type roboto.ai.core.AgentEvent = Union[AgentStartTextEvent, AgentTextDeltaEvent, AgentTextEndEvent, AgentToolUseEvent, AgentToolResultEvent, AgentErrorEvent]#

class roboto.ai.core.AgentMessage(/, **data)#

Bases: pydantic.BaseModel

A single message within an agent session.

Represents one message in the conversation, containing the sender role, content blocks, and generation status. Messages can contain multiple content blocks of different types (text, tool use, tool results).

Parameters:: data (Any)

content: list[AgentContent]#: List of content blocks that make up this message.

created: datetime.datetime = None#: Timestamp when this message was created.

is_complete()#

Check if message generation is complete.

Returns:: True if the message status is COMPLETED, False otherwise.
Return type:: bool

is_unsuccessful()#

Check if message generation failed or was cancelled.

Returns:: True if the message status is FAILED or CANCELLED, False otherwise.
Return type:: bool

role: AgentRole#: The role of the message sender (user, assistant, or roboto).

status: AgentMessageStatus#: Current generation status of this message.

classmethod text(text, role=AgentRole.USER)#

Create a simple text message.

Convenience method for creating a message containing only text content.

Parameters:

text (str) – The text content for the message.
role (AgentRole) – The role of the message sender. Defaults to USER.

Returns:

AgentMessage instance containing the text content.

Return type:

AgentMessage

class roboto.ai.core.AgentMessageStatus#

Bases: roboto.compat.StrEnum

Enumeration of possible message generation states.

Tracks the lifecycle of message generation from initiation to completion.

CANCELLED = 'cancelled'#: Message generation was cancelled by the user.

COMPLETED = 'completed'#: Message generation has finished and content is complete.

FAILED = 'failed'#: Message generation failed due to an error.

GENERATING = 'generating'#: Message content is currently being generated.

NOT_STARTED = 'not_started'#: Message has been queued but generation has not begun.

is_terminal()#

Check if the message generation is in a terminal state.

Returns:: True if the message is in a terminal state, False otherwise.
Return type:: bool

class roboto.ai.core.AgentRole#

Bases: roboto.compat.StrEnum

Enumeration of possible roles in an agent session.

Defines the different participants that can send messages in a session.

ASSISTANT = 'assistant'#: AI agent responding to user queries and requests.

ROBOTO = 'roboto'#: Roboto system providing tool results and system information.

USER = 'user'#: Human user sending messages to the agent.

class roboto.ai.core.AgentSessionDelta(/, **data)#

Bases: pydantic.BaseModel

Incremental update to an agent session.

Contains only the changes since the last synchronization, used for efficient real-time updates without transferring the entire session history.

Parameters:: data (Any)

continuation_token: str#: Updated token for the next incremental synchronization.

goals: list[AgentSessionGoalRecord] | None = None#: Latest snapshot of every goal declared in the session, ordered by allocation. None means there has been no change since the previous delta — clients should retain the snapshot they already hold. An empty list means the session has no declared goals. A non-empty list is the authoritative current snapshot and replaces any prior value.

messages_by_idx: dict[int, AgentMessage]#: New or updated messages indexed by their position in the conversation.

status: AgentSessionStatus | None = None#: Updated status of the agent session.

title: str | None = None#: Updated title of the agent session.

class roboto.ai.core.AgentSessionRecord(/, **data)#

Bases: pydantic.BaseModel

Complete record of an agent session.

Contains all the persistent data for a session including metadata, message history, and synchronization state.

Parameters:: data (Any)

property chat_id: str#

Backwards-compatible alias — serialized as chat_id in API responses.

Return type:: str

continuation_token: str#: Token used for incremental updates and synchronization.

created: datetime.datetime#: Timestamp when this agent session was created.

created_by: str#: User ID of the person who created this agent session.

forked_from_message_sequence_num: int | None = None#

Message sequence number in the source session that this fork was taken from.

Populated in tandem with forked_from_session_id; both are None for sessions that were not created as a fork.

forked_from_session_id: str | None = None#: If this session was forked, the id of the source session. None otherwise.

goals: list[AgentSessionGoalRecord] | None = None#: Goals declared across this session’s turns, ordered by allocation (i.e. by goal_index). None means goals were not loaded for this record (full-session reads populate the field; lightweight or legacy reads may omit it). An empty list means goals were loaded but the session never declared any.

messages: list[AgentMessage] = None#: Complete list of messages in the conversation.

model_profile: str | None = None#: Model profile used for this agent session (e.g., ‘standard’, ‘advanced’).

org_id: str#: Organization ID that owns this agent session.

session_id: str = None#: Unique identifier for this agent session.

status: AgentSessionStatus#: Current status of this agent session.

title: str | None = None#: Title of this agent session.

class roboto.ai.core.AgentSessionStatus#

Bases: roboto.compat.StrEnum

Enumeration of possible agent session states.

Tracks the overall status of an agent session from creation to termination.

CLIENT_TOOL_TURN = 'client_tool_turn'#: Client must execute pending tool uses and submit results.

GOALS_FAILED = 'goals_failed'#: The agent runner exhausted its corrective re-prompt budget without achieving every declared goal for the most-recent turn. Signals to clients that the session needs human intervention before it can continue.

NOT_STARTED = 'not_started'#: Session has been created but no messages have been sent.

ROBOTO_TURN = 'roboto_turn'#: Roboto is generating a message.

USER_TURN = 'user_turn'#: User has the turn to send a message.

class roboto.ai.core.AgentStartTextEvent(/, **data)#

Bases: pydantic.BaseModel

Signals the beginning of text generation in a chat response.

Parameters:: data (Any)

class roboto.ai.core.AgentTextContent(/, **data)#

Bases: pydantic.BaseModel

Text content within an agent message.

Parameters:: data (Any)

text: str#: The actual text content of the message.

class roboto.ai.core.AgentTextDeltaEvent(/, **data)#

Bases: pydantic.BaseModel

Contains incremental text content as the AI generates its response.

Parameters:: data (Any)

text: str#: Text fragment from the streaming response.

class roboto.ai.core.AgentTextEndEvent(/, **data)#

Bases: pydantic.BaseModel

Signals the completion of text generation in a chat response.

Parameters:: data (Any)

class roboto.ai.core.AgentToolResultContent(/, **data)#

Bases: pydantic.BaseModel

Tool execution result content within an agent message.

Parameters:: data (Any)

content_type: Literal[AgentContentType]#

raw_response: dict[str, Any] | None = None#: Raw, unparsed response payload from tool execution.

runtime_ms: int#: Wall-clock execution time of the tool in milliseconds.

status: str#: Outcome of the tool execution (e.g. ‘success’, ‘error’).

tool_name: str#: Name of the tool that was executed.

tool_use_id: str#: Identifier of the tool invocation this result corresponds to.

class roboto.ai.core.AgentToolResultEvent(/, **data)#

Bases: pydantic.BaseModel

Contains the result of a tool invocation.

Parameters:: data (Any)

name: str#: Name of the tool that was invoked.

output: dict[str, Any] | None = None#: Raw tool output payload (from the underlying tool_result’s raw_response). May be None for errored invocations or for tools that return no data.

runtime_ms: int | None = None#: Wall-clock execution time of the tool in milliseconds, as reported by the tool-result content. None only if the underlying content omits it.

success: bool#: Whether the tool invocation succeeded.

tool_use_id: str#: Unique identifier for this tool invocation.

class roboto.ai.core.AgentToolUseContent(/, **data)#

Bases: pydantic.BaseModel

Tool usage request content within an agent message.

Parameters:: data (Any)

content_type: Literal[AgentContentType]#

input: dict[str, Any] | None = None#: Parsed tool input parameters chosen by the LLM (provider-agnostic).

raw_request: dict[str, Any] | None = None#: Raw, unparsed request payload for this tool invocation.

tool_name: str#: Name of the tool the LLM is requesting to invoke.

tool_use_id: str#: Unique identifier for this tool invocation, used to correlate with its result.

class roboto.ai.core.AgentToolUseEvent(/, **data)#

Bases: pydantic.BaseModel

Signals that the AI is invoking a tool to gather information.

Parameters:: data (Any)

input: dict[str, Any] | None = None#: Parsed tool input parameters chosen by the LLM.

name: str#: Name of the tool being invoked.

tool_use_id: str#: Unique identifier for this tool invocation.

class roboto.ai.core.AnalysisScope(/, **data)#

Bases: pydantic.BaseModel

The slice of data an agent is expected to analyze.

An AnalysisScope is delivered to every AgentTool invocation on the server side. Individual tools opt in to honoring the scope as they are adopted; this SDK type carries the configuration, it does not itself enforce anything. Fields set to None are unconstrained on that dimension; an AnalysisScope with every field None is equivalent to no scope at all.

Parameters:: data (Any)

end_time: int | None = None#: Upper bound (inclusive) of the analysis window, expressed as nanoseconds since the Unix epoch.

start_time: int | None = None#: Lower bound (inclusive) of the analysis window, expressed as nanoseconds since the Unix epoch.

class roboto.ai.core.ClientToolSpec(/, **data)#

Bases: pydantic.BaseModel

Declarative specification for a client-side tool.

Unlike AgentTool (which is an ABC with a __call__ method for server-side execution), ClientToolSpec is a plain data model. The backend includes it in the LLM’s tool list but never executes it — the client is responsible for execution and submitting the result.

Parameters:: data (Any)

description: str#

input_schema: dict[str, Any]#

name: str#

class roboto.ai.core.ClientViewingContext(/, **data)#

Bases: pydantic.BaseModel

What the Roboto client (e.g. the Web UI) is currently viewing when the user composed a message.

Passed to the agent as implicit context for resolving deictic references — “this dataset”, “those files”, “the visualizer state I’m looking at” — that the user would otherwise have to spell out. This type is purely informational; it is not enforced and never gates tool authorization.

Distinct from:

AnalysisScope, which is a hard analysis window honored by individual tools on the server side.
AgentGoal, which declares typed outcomes the agent runner must drive the turn to satisfy.

The corresponding wire-format field is client_context (with a one-release context alias for migration).

Parameters:: data (Any)

dataset_ids: list[str] = None#: IDs of datasets the user is currently viewing or has selected.

file_ids: list[str] = None#: IDs of files the user is currently viewing or has selected.

misc_context: dict[str, Any] | None = None#: Miscellaneous client-supplied context that doesn’t fit the typed fields above. Use sparingly; prefer adding a typed field when a recurring shape emerges.

visualizer_state: dict[str, Any] | None = None#: State of the visualizer, when the user composed the message from the visualizer view. A relatively opaque JSON blob.

class roboto.ai.core.ModelProfileResponse(/, **data)#

Bases: pydantic.BaseModel

Metadata about an available model profile, returned by the API.

Parameters:: data (Any)

description: str#: Short description of the profile’s characteristics.

id: str#: Profile identifier, e.g. ‘standard’ or ‘advanced’.

is_default: bool = False#: Whether this profile is selected by default for new sessions.

label: str#: Human-readable display label.