v0.48.0

0.48.0

Breaking Changes

• RobotoStatementTimeoutException is renamed to RobotoOperationTimeoutException in roboto.exceptions. The new name reflects that it signals any operation aborted by Roboto's bounded timeout. Behavior is unchanged, and it still carries HTTP status 504. No alias is kept for the old name, so update imports to from roboto.exceptions import RobotoOperationTimeoutException.

Features Added

• Topic.get_data and Topic.get_data_as_df now decode topics recorded from DDS, those whose schema is OMG IDL (omgidl) or its ROS 2 dialect (ros2idl) with CDR payloads, as produced by stacks such as RTI Connext. Plain CDR, XCDR1 parameter-list (@mutable) framing, and the XCDR2 family all decode, alongside the existing ROS 1 and ROS 2 message formats. When a message carries a field whose CDR encoding is undefined (a wstring or wchar in a non-recoverable position), the reader skips that message and continues reading the file.
• QuerySpecification accepts a new optional max_results field that caps the total number of results returned across all pages of a query.
  • Defaults to None, which returns the full result set.
  • Distinct from limit, which is the per-page size.
  • max_results is only honored by RobotoSearch's find_* methods. The per-domain .query() methods that also accept a QuerySpecification — such as Dataset.query() — ignore it.
• Custom fields in search (experimental): custom fields can now be used in search, both as query filters and sort keys. Filter by a custom field with <entity>.custom.<name> (the entity prefix is optional) — e.g. dataset.custom.drone_id or custom.severity — and sort by custom.<name> (no entity prefix). Works both with structured QuerySpecification objects and RoboQL queries, across Dataset, Event, Collection, and Session searches. Each custom field type allows the comparators that make sense for it — ranges on Number and Timestamp, substring matching on String, equality and null checks everywhere.
• Event.delete_many(event_ids) deletes multiple events in one call. As with Event.delete(), you can delete any event you're able to manage; if the list includes an event you can't delete, the request is rejected and nothing is deleted. IDs that don't exist are ignored, so the call is idempotent and safe to retry. You can pass any number of IDs — large lists are batched automatically. Deletion cannot be undone.
• AgentThread.goals (experimental): new property returning the goals declared across a thread's turns, oldest first, as AgentThreadGoalView wrappers. Each wrapper exposes the goal's status (an AgentGoalStatus: PENDING, ACHIEVED, or FAILED), reconstructs the original declaration via to_agent_goal(), and resolves the achieve-tool invocation the agent submitted for the goal: achieve_tool_use, achieve_tool_result, and a typed result. result is a GoalResult, one of DatasetSummaryGoalResult, DatasetTriageGoalResult, or CreateEventsGoalResult, exposing the agent's submitted payload as typed fields (e.g. result.summary, result.label_decisions / result.applied_labels, result.events) instead of a raw dict. The property returns an empty list when the thread declared no goals or when the record was fetched without loading them; call refresh() if you expect goals to be present. Import the result and input models from roboto.ai.goals: GoalResult, the three *GoalResult models, the matching DatasetSummaryAchieveInput / DatasetTriageAchieveInput / CreateEventsAchieveInput models, EventSpec, LabelDecision, and AgentGoalStatus.
• AgentThreadGoalRecord gains an achieve_tool_use_id field pointing at the achieve-tool invocation associated with the goal, so callers can locate the exact tool_use / tool_result pair in the thread's message stream without scanning by tool name.
• S3BucketIntegrationRecord now surfaces bring-your-own-bucket health-check results: a new last_health_check field holding a new S3BucketHealthCheck model (reason_code, aws_error_code, message, and a per-probe probes map), plus a status_last_updated timestamp for when the most recent check ran. status may now also be unverified (registered, never checked) or unknown (a check that reached no verdict), alongside healthy and unhealthy. Both new fields are None until the first check.
• Agent.launch() accepts an optional analysis_scope that pins the analysis window for the launched thread, backed by a new analysis_scope field on LaunchAgentRequest. The scope is a roboto.ai.core.AnalysisScope with start_time/end_time bounds in nanoseconds since the Unix epoch. A supplied scope overrides the one in the agent's authored request_template; omitting it leaves the template's scope unchanged. Because of this, launch() cannot clear a window the author pinned in the template.
• roboto.http now exports InvalidPaginationTokenError, which PaginationToken.from_token raises when a pagination token is malformed or uses an unsupported scheme (previously a bare ValueError). The new error subclasses ValueError, so existing except ValueError handling still works; callers that need to detect an invalid token can catch it directly.

Bugs Fixed

• Dataset.upload_file and Dataset.upload_files could intermittently fail with a server error when the same destination path was uploaded concurrently (e.g. retrying an upload, or parallel uploads of the same path); these concurrent same-path uploads are now serialized and succeed.
• A large include_patterns/exclude_patterns list passed to Dataset.list_files, Dataset.download_files, or Dataset.delete_files previously failed with a server error; lists of hundreds of patterns now succeed.
• roboto.time.to_epoch_nanoseconds now converts datetime and ISO-8601 string inputs exactly, preserving their full microsecond resolution. Previously a floating-point seconds multiply rounded away the low-order nanosecond digits of sub-second values (for example, a microsecond-precision timestamp could land on ...001024 instead of ...001000). Integer inputs were unaffected.

Internals

• Message-content primitives (AgentTextContent, AgentToolUseContent, AgentToolResultContent, AgentErrorContent, AgentContentType, and the AgentContent union) now live in a new roboto.ai.core.content module and are re-exported from roboto.ai.core.record, so existing import paths keep working. This breaks a circular dependency and supports the typed goal-result models.