Roboto

https://docs.roboto.ai/
Admin
Roboto is a platform for managing robotics data at scale, enabling teams to automate analysis of...
Tokens:321,012
Snippets:2,582
Trust Score:7.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Starting and Interacting with a Chat Session

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Demonstrates how to start a new chat session, wait for the AI's response, and send subsequent messages. This is useful for synchronous interaction patterns where sequential steps are required.

```python
from roboto.ai.chat import Chat

# Start a new chat session with an initial prompt
chat = Chat.start("Analyze my latest dataset")

# Wait for the AI assistant to finish generating its response and be ready for user input
# The timeout parameter specifies the maximum time to wait in seconds.
chat.await_user_turn(timeout=30.0)

# Send a follow-up text message to the AI assistant
chat.send_text("What were the key findings?")

# Chain method calls for a more concise interaction pattern
# This starts a chat, waits for the user turn, and then sends a text message, followed by waiting for the next user turn.
(Chat.start("Summarize the performance metrics")
 .await_user_turn()
 .send_text("Provide a detailed breakdown.")
 .await_user_turn())
```

--------------------------------

### DownloadSession Example - Python

Source: https://docs.roboto.ai/reference/python-sdk/roboto/fs/download_session/index.html

Demonstrates how to use the DownloadSession to manage a batch of file downloads. It shows initializing the session, obtaining an object store with appropriate credentials, and iterating through files to register download futures. The example highlights the use of context managers and the `await_downloads` method.

```python
session = DownloadSession(
    items=[
        {"bucket_name": "bucket", "source_uri": "s3://bucket/key", "destination_path": Path("/tmp/file")}
    ],
    association=Association.dataset("ds_123"),
)
object_store = registry.get_store_for_uri(uri, session.credential_provider)
with object_store:
    for file in session:
        future = object_store.get(file["source_uri"], file["destination_path"])
        session.register_download(file, future)
```

--------------------------------

### Upload Configuration File Example (JSON)

Source: https://docs.roboto.ai/learn/upload_agent.html

An example of the `.roboto_upload.json` file, which signals the agent to create a new dataset and configures its properties. It includes settings for file deletion, exclusion patterns, and dataset metadata like organization ID, description, tags, and collections.

```json
{
  "version": "v1",
  "upload": {
    "delete_uploaded_files": false,
    "exclude_patterns": ["**/.DS_Store"]
  },
  "dataset": {
    "org_id": "og_123456789012",
    "description": "This dataset contains logs from the Roboto team driving an RC car in the park",
    "tags": ["upload_agent_example", "crash", "4wd"],
    "add_to_collections": ["cl_12345"],
    "metadata": {
      "operator": "benji@roboto.ai",
      "location": "Gas Works Park",
      "avg_temp_f": "77",
      "visibility": "clear"
    }
  }
}

```

--------------------------------

### Agent Configuration File Example (JSON)

Source: https://docs.roboto.ai/learn/upload_agent.html

An example of the `upload_agent.json` file used to configure the Roboto upload agent. It specifies version, file deletion behavior, directories to search for uploads, and the name of the upload config file.

```json
{
  "version": "v1",
  "delete_uploaded_files": true,
  "search_paths": [
    "/Users/roboto/datasets/autoupload"
  ],
  "upload_config_filename": ".roboto_upload.json"
}

```

--------------------------------

### Query Actions with Tags

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

This example shows how to query actions that have specific tags. It utilizes QuerySpecification to filter actions based on tag content.

```python
>>> from roboto.query import QuerySpecification
>>> spec = QuerySpecification().where("tags").contains("ml")
>>> for action in Action.query(spec):
...     print(f"ML Action: {action.name}")
```

--------------------------------

### Start Chat API

Source: https://docs.roboto.ai/reference/python-sdk/roboto/ai/chat/index.html

Initiates a new chat session with optional initial messages, context, and configuration.

```APIDOC
## POST /chat/start

### Description
Starts a new chat session. This endpoint allows for the initialization of a conversation with optional system prompts, model profiles, and initial messages.

### Method
POST

### Endpoint
/chat/start

### Parameters
#### Request Body
- **messages** (list[AgentMessage]) - Required - Initial messages to start the conversation with.
- **client_tools** (list[ClientToolSpec] | None) - Optional - Client-side tools available for this invocation.
- **context** (RobotoLLMContext | None) - Optional - Context to include with the message.
- **model_profile** (str | None) - Optional - Model profile ID for the session (e.g., ‘standard’, ‘advanced’).
- **system_prompt** (str | None) - Optional - System prompt to customize AI assistant behavior.

### Request Example
```json
{
  "messages": [
    {
      "role": "USER",
      "content": "Hello, Roboto!"
    }
  ],
  "model_profile": "standard"
}
```

### Response
#### Success Response (200)
- **chat_id** (str) - The unique identifier for the new chat session.
- **messages** (list[AgentMessage]) - The initial messages in the chat session.

#### Response Example
```json
{
  "chat_id": "chat-12345",
  "messages": [
    {
      "role": "ASSISTANT",
      "content": "Hello! How can I help you today?"
    }
  ]
}
```
```

--------------------------------

### Get Data as DataFrame with Time Range and Cache

Source: https://docs.roboto.ai/reference/python-sdk/roboto/domain/topics/message_path/index.html

This function retrieves message path data and converts it into a pandas DataFrame. It allows specifying start and end times for the data retrieval and a cache directory for downloaded data. Requires pandas installation via `roboto[analytics]`.

```python
>>> topic = Topic.from_name_and_file("/imu/data", "file_abc123")
>>> angular_velocity_x = topic.get_message_path("angular_velocity.x")
>>> df = angular_velocity_x.get_data_as_df()
>>> print(df.head())
                        angular_velocity.x
log_time
1722870127699468923                  0.1
1722870127699468924                  0.15
>>> print(f"Mean: {df[angular_velocity_x.path].mean()}")
Mean: 0.125
```

--------------------------------

### Set file description with Python

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Demonstrates how to assign a human-readable description to a file using the set_description method.

```python
from roboto import InvocationContext
context = InvocationContext.from_env()
file_changeset_manager = context.file_changeset_manager

file_changeset_manager.set_description("images/front0_raw_000734.jpg", "This image was over-exposed")
```

--------------------------------

### Create Triggers with Python

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Demonstrates how to instantiate various types of triggers, including simple file-based triggers, conditional triggers with custom parameters, and triggers with specific compute resource overrides.

```python
from roboto.domain.actions import Trigger, TriggerForEachPrimitive

# Create a simple trigger for ROS bag files
trigger = Trigger.create(
    name="auto_process_bags",
    action_name="ros_ingestion",
    required_inputs=["**/*.bag"],
    for_each=TriggerForEachPrimitive.Dataset,
)

# Create a conditional trigger with parameters
from roboto.query import Condition
condition = Condition("metadata.sensor_type").equals("lidar")
trigger = Trigger.create(
    name="lidar_processing",
    action_name="lidar_processor",
    required_inputs=["**/*.pcd"],
    for_each=TriggerForEachPrimitive.Dataset,
    condition=condition,
    parameter_values={"resolution": "high", "filter": "statistical"},
)

# Create a trigger with compute overrides
from roboto.domain.actions import ComputeRequirements
trigger = Trigger.create(
    name="heavy_processing",
    action_name="ml_inference",
    required_inputs=["**/*.jpg", "**/*.png"],
    for_each=TriggerForEachPrimitive.DatasetFile,
    compute_requirement_overrides=ComputeRequirements(vCPU=8192, memory=16384),
)
```

--------------------------------

### Find Events by Name and Start Time

Source: https://docs.roboto.ai/roboql/example_queries.html

Retrieves events containing the word `spike` that started after September 09, 2024, 4:38 PM PDT. This query filters events based on their name and start time.

```text
name CONTAINS "spike" AND start_time > "2024-09-09T16:38:26.941-07:00"

```

--------------------------------

### Configure Roboto AI Client (Python)

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Demonstrates how to instantiate and configure the RobotoConfig class, which holds the API key and endpoint necessary for interacting with the Roboto AI service. It shows basic instantiation and how to potentially load from environment variables or profiles.

```python
from roboto import RobotoConfig

# Basic instantiation with API key and endpoint
config = RobotoConfig(api_key="YOUR_API_KEY", endpoint="https://api.roboto.ai")

# Example of loading from environment (assuming defaults or profile overrides)
# config = RobotoConfig.from_env(profile_override="production")

print(f"API Key: {config.api_key}")
print(f"Endpoint: {config.endpoint}")
print(f"Cache Directory: {config.get_cache_dir()}")
```

--------------------------------

### Get Data within a Time Range

Source: https://docs.roboto.ai/reference/python-sdk/roboto/domain/topics/message_path/index.html

This example demonstrates how to fetch data for a specific message path within a defined time range. It iterates through the records in the specified interval and prints each record.

```python
>>> for record in angular_velocity_x.get_data(start_time=1722870127699468923, end_time=1722870127799468923):
...     print(record)
```

--------------------------------

### Get Events by Message Path (Python)

Source: https://docs.roboto.ai/reference/python-sdk/roboto/domain/events/index.html

Retrieves all events associated with a specific message path ID. This method can be used to list all events or to filter them based on certain criteria like start time. It returns a generator that can be converted to a list.

```python
>>> events = list(Event.get_by_message_path("mp_abc123"))
>>> for event in events:
...     print(f"Message path event: {event.name}")

>>> events = Event.get_by_message_path("mp_abc123")
>>> filtered_events = [event for event in events if event.start_time >= 1722870127699468923]
```

--------------------------------

### Update Action Configuration

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

This example demonstrates updating an action's configuration. It shows how to modify parameters like description, timeout, and container settings.

```python
>>> action = Action.from_name("my_action")
>>> action.update(
...     description="Updated description",
...     timeout=60,
...     short_description="New short description"
... )
```

--------------------------------

### Query Actions with Pagination

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

This example illustrates how to query actions with pagination and ordering. It limits the results to 10 and orders them by creation date in descending order.

```python
>>> spec = QuerySpecification().limit(10).order_by("created", ascending=False)
>>> recent_actions = list(Action.query(spec))
>>> print(f"Found {len(recent_actions)} recent actions")
```

--------------------------------

### Collect Data into a Pandas DataFrame

Source: https://docs.roboto.ai/reference/python-sdk/roboto/domain/topics/message_path/index.html

This snippet illustrates how to convert message path data into a pandas DataFrame for further analysis. It requires the `roboto[analytics]` extra to be installed. The example also includes an assertion to verify the mean calculation.

```python
>>> df = angular_velocity_x.get_data_as_df()
>>> import math
>>> assert math.isclose(angular_velocity_x.mean, df[angular_velocity_x.path].mean())
```

--------------------------------

### Retrieve Action Parameters

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Demonstrates how to fetch configuration parameters provided to the action, including optional parameters with default values.

```python
import roboto
context = roboto.InvocationContext.from_env()
# Get optional parameter with default
value = context.get_optional_parameter("model_version", "latest")
```

--------------------------------

### Get Corresponding Images for an Event (Python)

Source: https://docs.roboto.ai/user-guides/create-events-on-data.html

Retrieves images from a dataset file corresponding to an event's start and end times. It uses `Dataset.from_id`, `get_file_by_path`, and `get_topic` to access camera data and then displays the images using `IPython.display.Image`. Requires 'roboto' and 'IPython' libraries.

```python
from IPython.display import display, Image

ds = Dataset.from_id("ds_aap1q0v1z4xa")
file = ds.get_file_by_path("nuscenes-tiny-multi.bag")

# Get camera topic with image data
camera_topic = file.get_topic("/camera/front/image")

# Fetch image data corresponding to the event start and end time
camera_data = camera_topic.get_data(
    start_time=event.start_time,
    end_time=event.end_time
)

# Show the images
for i, datum in enumerate(camera_data):
    display(Image(data=datum["data"], width=500))
```

--------------------------------

### GET /comments/entity_type

Source: https://docs.roboto.ai/reference/python-sdk/roboto/domain/comments/index.html

Retrieve all comments for a specific entity type. Fetches all comments attached to entities of a particular type within an organization. For example, retrieve all comments on datasets or all comments on files. Results are paginated and returned in chronological order.

```APIDOC
## GET /comments/entity_type

### Description
Retrieve all comments for a specific entity type. Fetches all comments attached to entities of a particular type within an organization. For example, retrieve all comments on datasets or all comments on files. Results are paginated and returned in chronological order.

### Method
GET

### Endpoint
/comments/entity_type

### Parameters
#### Query Parameters
- **entity_type** (CommentEntityType) - Required - Type of entities to retrieve comments for.
- **owner_org_id** (str) - Optional - Optional organization ID to scope the search to. If not provided, uses the organization from the client context.
- **page_token** (str) - Optional - Optional pagination token to retrieve the next page of results. Use None to start from the beginning.

### Request Example
```python
{
  "entity_type": "Dataset"
}
```

### Response
#### Success Response (200)
- **comments_list** (list[Comment]) - A sequence of Comment instances for the entity type.
- **next_token** (str) - An optional pagination token for the next page, or None if no more pages are available.

#### Response Example
```json
{
  "comments_list": [
    {
      "comment_id": "cmt_abcdef1234567890",
      "entity_type": "Dataset",
      "entity_id": "ds_1234567890abcdef",
      "user_id": "usr_0987654321fedcba",
      "text": "Another comment.",
      "created_at": "2023-10-27T10:05:00Z"
    }
  ],
  "next_token": "page_token_abc123"
}
```

#### Error Response
- **RobotoUnauthorizedException**: If the user lacks permission to access comments for the specified entity type.
```

--------------------------------

### Manage datasets and test files

Source: https://docs.roboto.ai/user-guides/creating-your-own-action.html

Commands to generate a sample log file, create a dataset, and upload files for testing purposes.

```bash
# Generate log.txt
( for i in {1..10}; do echo "$(date '+%Y-%m-%d %H:%M:%S') - INFO - Log message $i"; done; echo "$(date '+%Y-%m-%d %H:%M:%S') - ERROR - An error occurred"; echo "$(date '+%Y-%m-%d %H:%M:%S') - WARNING - A warning occurred"; for i in {11..20}; do echo "$(date '+%Y-%m-%d %H:%M:%S') - INFO - Log message $i"; done; ) > log.txt

# Create dataset
$ roboto datasets create

# Upload file
$ roboto datasets upload-files -d <dataset_id> -p ./log.txt
```

--------------------------------

### Get Event Data as Pandas DataFrame

Source: https://docs.roboto.ai/reference/python-sdk/roboto/domain/events/index.html

Collects all data from `get_data()` and returns it as a pandas DataFrame with the log time as the index. Requires installing the `roboto[analytics]` extra. Handles optional inclusion/exclusion of specific message paths and provides options for topic data services and caching.

```python
from roboto.domain.events import Event

# Example: Get all event data as a DataFrame
event = Event.from_id("ev_abc123")
df = event.get_data_as_df()
print(f"Data shape: {df.shape}")
print(df.head())

# Example: Get specific message paths as DataFrame
df_specific = event.get_data_as_df(message_paths_include=["velocity.x", "velocity.y"])
print(df_specific.columns.tolist())

# Example: Analyze event data
df_analysis = event.get_data_as_df()
print(f"Event duration: {df_analysis.index.max() - df_analysis.index.min()} ns")
print(f"Data points: {len(df_analysis)}")
```

--------------------------------

### Get Topic Data as Pandas DataFrame (Python)

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

This function retrieves topic data and converts it into a pandas DataFrame. The DataFrame is indexed by log time and includes columns for each message path. This is ideal for data analysis and visualization. It requires the `pandas` library, which can be installed via the `roboto[analytics]` extra.

```python
get_data_as_df(_message_paths_include =None_, _message_paths_exclude =None_, _start_time =None_, _end_time =None_, _cache_dir =None_)#
    
Return this topic’s underlying data as a pandas DataFrame.
Retrieves topic data and converts it to a pandas DataFrame for analysis and visualization. The DataFrame is indexed by log time and contains columns for each message path in the topic data. 

Parameters:
    
  * **message_paths_include** (_Optional_ _[__collections.abc.Iterable_ _[__str_ _]__]_) – Dot notation paths that match attributes of individual data records to include. If None, all paths are included.
  * **message_paths_exclude** (_Optional_ _[__collections.abc.Iterable_ _[__str_ _]__]_) – Dot notation paths that match attributes of individual data records to exclude. If None, no paths are excluded.
  * **start_time** (_Optional_ _[__roboto.time.Time_ _]_) – Start time (inclusive) as nanoseconds since UNIX epoch or convertible to such by `to_epoch_nanoseconds()`.
  * **end_time** (_Optional_ _[__roboto.time.Time_ _]_) – End time (exclusive) as nanoseconds since UNIX epoch or convertible to such by `to_epoch_nanoseconds()`.
  * **cache_dir** (_Union_ _[__str_ _,__pathlib.Path_ _,__None_ _]_) – Directory where topic data will be downloaded if necessary. Defaults to `DEFAULT_CACHE_DIR`.


Returns:
    
pandas DataFrame containing the topic data, indexed by log time. 

Raises:
    
**ImportError** – pandas is not installed. Install with `roboto[analytics]` extra. 

Return type:
    
pandas.DataFrame
Notes
Requires installing this package using the `roboto[analytics]` extra. 
Examples
```
>>> topic = Topic.from_name_and_file("/imu/data", "file_abc123")
>>> df = topic.get_data_as_df()
>>> print(df.head())
                        angular_velocity.x  angular_velocity.y  ...
log_time
1722870127699468923                  0.1                 0.2  ...

```

--------------------------------

### GET /api/resource

Source: https://docs.roboto.ai/reference/python-sdk/roboto/http/index.html

Performs a GET request to the specified path to retrieve resources from the Roboto platform.

```APIDOC
## GET [path]

### Description
Retrieves data from the specified path using the Roboto HTTP client.

### Method
GET

### Endpoint
[path]

### Parameters
#### Path Parameters
- **path** (ApiRelativePath) - Required - The relative path for the API request.

#### Query Parameters
- **caller_org_id** (str) - Optional - Organization ID of the caller.
- **owner_org_id** (str) - Optional - Organization ID of the owner.
- **query** (dict) - Optional - Key-value pairs for query string parameters.
- **headers** (dict) - Optional - Custom HTTP headers.
- **idempotent** (bool) - Optional - Whether the request is idempotent (default: True).
- **timeout** (Timeout) - Optional - Request timeout settings.

### Response
#### Success Response (200)
- **response** (HttpResponse) - The HTTP response object containing the requested data.
```

--------------------------------

### Create Directories with Roboto AI

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Demonstrates how to create directories within a dataset, including options for recursive directory creation. It returns a DirectoryRecord object and handles various authorization and existence exceptions.

```python
from roboto.domain import datasets
dataset = datasets.Dataset.from_id(...)
directory = dataset.create_directory("foo")
print(directory.relative_path)

directory = dataset.create_directory(
    name="final",
    parent_path=pathlib.Path("path/to/deep"),
    create_intermediate_dirs=True,
)
print(directory.relative_path)
```

--------------------------------

### Example: Create Organization - Python

Source: https://docs.roboto.ai/reference/python-sdk/roboto/domain/orgs/index.html

Shows a basic example of creating a new organization named 'my-company' using the `create` class method.

```python
>>> from roboto.domain.orgs import Org
>>> org = Org.create("my-company")
```

--------------------------------

### RobotoClient Initialization and Class Methods (Python)

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Provides methods for initializing and configuring the RobotoClient, which is used for making HTTP requests to the Roboto service. This includes class methods for creating clients from default settings, profiles, or configuration objects, as well as a method for creating a client from environment variables.

```python
class RobotoClient:
    def __init__(self, endpoint: str, auth_decorator: Optional[roboto.http.request.HttpRequestDecorator] = None, http_client_kwargs: Optional[dict[str, Any]] = None):
        # ... initialization logic ...
        pass

    @classmethod
    def defaulted(cls, client: Optional[RobotoClient] = None) -> RobotoClient:
        # ... implementation ...
        pass

    @classmethod
    def for_profile(cls, profile: str) -> RobotoClient:
        # ... implementation ...
        pass

    @classmethod
    def from_config(cls, config: roboto.config.RobotoConfig) -> RobotoClient:
        # ... implementation ...
        pass

    @classmethod
    def from_env() -> RobotoClient:
        # ... implementation ...
        pass

```

--------------------------------

### Create Basic Topic with Python

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Creates a basic topic for storing data, such as camera images. Requires file ID, topic name, schema name, and optionally start/end times and message count. Returns a Topic instance.

```python
>>> topic = Topic.create(
...     file_id="file_abc123",
...     topic_name="/camera/image",
...     schema_name="sensor_msgs/Image",
...     start_time=1722870127699468923,
...     end_time=1722870127799468923,
...     message_count=100,
... )
>>> print(topic.topic_id)
topic_xyz789
```

--------------------------------

### HttpClient Initialization

Source: https://docs.roboto.ai/reference/python-sdk/roboto/http/http_client/index.html

Configuration and instantiation of the HttpClient.

```APIDOC
## Constructor: HttpClient

### Description
Initializes the HTTP client with base configuration, authentication, and request providers.

### Parameters
- **base_headers** (dict[str, str]) - Optional - Default headers to include in every request.
- **default_endpoint** (str) - Optional - Base URL for all requests.
- **default_auth** (HttpRequestDecorator) - Optional - Authentication decorator.
- **requester** (RobotoRequester) - Optional - Custom requester implementation.
- **extra_headers_provider** (Callable) - Optional - Function to provide dynamic headers.
- **default_timeout** (float) - Optional - Default timeout in seconds.
```

--------------------------------

### Query Specification Example: Multiple Conditions (Python)

Source: https://docs.roboto.ai/reference/python-sdk/roboto/query/index.html

Example showing how to construct a QuerySpecification with multiple conditions combined using a logical operator (AND in this case). This allows for more complex filtering criteria.

```python
>>> from roboto import query
>>> query_spec = query.QuerySpecification(
...     condition=query.ConditionGroup(
...         operator=query.ConditionOperator.And,
...         conditions=[
...             query.Condition(field="name", comparator=query.Comparator.Equals, value="Roboto"),
...             query.Condition(field="age", comparator=query.Comparator.GreaterThan, value=18),
...         ],
...     )
... )
```

--------------------------------

### Create Actions using Roboto API

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Demonstrates how to create basic actions, actions with complex compute requirements and parameters, and actions that inherit from existing base actions.

```python
# Create a simple action
action = Action.create(
    name="hello_world", uri="ubuntu:latest", description="A simple hello world action"
)

# Create an action with parameters and compute requirements
from roboto.domain.actions import ComputeRequirements, ActionParameter
action = Action.create(
    name="data_processor",
    uri="my-registry.com/processor:v1.0",
    description="Processes sensor data with configurable parameters",
    compute_requirements=ComputeRequirements(vCPU=4096, memory=8192),
    parameters=[
        ActionParameter(name="threshold", required=True, description="Processing threshold"),
        ActionParameter(name="output_format", default="json", description="Output format"),
    ],
    tags=["data-processing", "sensors"],
    timeout=60,
)

# Create an action that inherits from another
base_action = Action.from_name("base_processor", owner_org_id="roboto-public")
derived_action = Action.create(
    name="custom_processor",
    inherits=base_action.record.reference,
    description="Custom processor based on base_processor",
    metadata={"version": "2.0", "team": "data-science"},
)
```

--------------------------------

### Query Specification Example: Single Condition (Python)

Source: https://docs.roboto.ai/reference/python-sdk/roboto/query/index.html

Example demonstrating how to create a QuerySpecification with a single condition using the Roboto library. This involves specifying the field, comparator, and value for the condition.

```python
>>> from roboto import query
>>> query_spec = query.QuerySpecification(
...     condition=query.Condition(field="name", comparator=query.Comparator.Equals, value="Roboto")
... )
```

--------------------------------

### Initialize RobotoSearch from Environment

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Demonstrates how to initialize a RobotoSearch instance using environment variables and perform a search for datasets. This is the primary entry point for interacting with the Roboto platform.

```python
import roboto

# Initialize the client from environment variables
roboto_search = roboto.RobotoSearch.from_env()

# Iterate through found datasets and print their names
for dataset in roboto_search.find_datasets():
    print(dataset.name)
```

--------------------------------

### Query Specification Example: Nested Conditions (Python)

Source: https://docs.roboto.ai/reference/python-sdk/roboto/query/index.html

Example illustrating the creation of a QuerySpecification with arbitrarily nested condition groups. This enables complex logical structures, combining AND and OR operators at different levels.

```python
>>> from roboto import query
>>> query_spec = query.QuerySpecification(
...     condition=query.ConditionGroup(
...         operator=query.ConditionOperator.And,
...         conditions=[
...             query.Condition(field="name", comparator=query.Comparator.Equals, value="Roboto"),
...             query.ConditionGroup(
...                 operator=query.ConditionOperator.Or,
...                 conditions=[
...                     query.Condition(field="age", comparator=query.Comparator.GreaterThan, value=18),
...                     query.Condition(field="age", comparator=query.Comparator.LessThan, value=30),
...                 ],
...             ),
...         ],
...     )
... )
```

--------------------------------

### Execute Roboto Actions

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Demonstrates how to trigger an action using the Roboto SDK. Includes examples for dataset-based ingestion and custom compute requirement overrides.

```python
from roboto import Action, InvocationSource, InvocationDataSourceType, InvocationUploadDestination, ComputeRequirements

# Basic invocation with a dataset
action = Action.from_name("ros_ingestion", owner_org_id="roboto-public")
iv = action.invoke(
    invocation_source=InvocationSource.Manual,
    data_source_id="ds_12345",
    data_source_type=InvocationDataSourceType.Dataset,
    input_data=["**/*.bag"],
    upload_destination=InvocationUploadDestination.dataset("ds_12345"),
)
iv.wait_for_terminal_status()

# Invocation with compute requirement overrides
action = Action.from_name("image_processing", owner_org_id="roboto-public")
compute_reqs = ComputeRequirements(vCPU=4096, memory=8192)
iv = action.invoke(
    invocation_source=InvocationSource.Manual,
    compute_requirement_overrides=compute_reqs,
    parameter_values={"threshold": 0.75},
)
status = iv.wait_for_terminal_status()
print(status)
```

--------------------------------

### Create Instantaneous Event (Python)

Source: https://docs.roboto.ai/reference/python-sdk/roboto/domain/events/event/index.html

Creates an event that occurs at a specific point in time. It requires a name and start time, and can optionally include file IDs and tags. The start time can be provided as a string or a numerical timestamp.

```python
>>> event = Event.create(
...     name="System Boot",
...     start_time="1722870127.699468923",  # String format also supported
...     file_ids=["fl_xyz789"],
...     tags=["system", "boot"],
... )

```

--------------------------------

### Get Filtered Topics from Dataset

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Retrieves topics associated with files in a dataset, with options to include or exclude specific topics by name. This method is efficient for getting topic names without message paths. It requires the dataset object and optional include/exclude lists.

```python
>>> dataset = Dataset.from_id("ds_abc123")
>>> # Get all topics
>>> for topic in dataset.get_topics():
...     print(topic.name)

>>> # Get only 'sensor_data' topics
>>> for topic in dataset.get_topics(include=['sensor_data']):
...     print(topic.name)

>>> # Exclude 'metadata' topics
>>> for topic in dataset.get_topics(exclude=['metadata']):
...     print(topic.name)
```

--------------------------------

### Create a new dataset in Roboto

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Demonstrates how to instantiate a new dataset using the Dataset.create class method. It supports optional parameters like name, description, tags, and metadata to organize data effectively.

```python
dataset = Dataset.create(
    name="Highway Test Session",
    description="Autonomous vehicle highway driving test data",
    tags=["highway", "autonomous", "test"],
    metadata={"vehicle_id": "vehicle_001", "test_type": "highway"},
)
print(dataset.dataset_id)

# Create minimal dataset
dataset = Dataset.create()
print(f"Created dataset: {dataset.dataset_id}")
```

--------------------------------

### Register a new device with Roboto

Source: https://docs.roboto.ai/reference/python-sdk/roboto/domain/devices/index.html

Demonstrates how to register a new device entity using the Device.create method. This allows the device to authenticate and interact with the platform using a unique identifier.

```python
from roboto.domain.devices import Device

# Register a robot device
device = Device.create(device_id="robot_001", caller_org_id="og_abc123")
print(f"Registered device: {device.device_id}")

# Register an upload station
device = Device.create(device_id="upload_station_alpha")
print(f"Device org: {device.org_id}")
```

--------------------------------

### InvocationContext Initialization

Source: https://docs.roboto.ai/reference/python-sdk/roboto/action_runtime/invocation_context/index.html

Demonstrates two primary ways to initialize the InvocationContext: from environment variables (recommended for runtime) and directly with specified parameters (useful for testing).

```APIDOC
## InvocationContext Initialization

### Description
Provides methods to initialize the `InvocationContext` for Roboto Actions. The `from_env` class method is recommended for runtime environments, while direct initialization is useful for testing.

### Methods

#### `from_env()`

##### Description
Initializes an `InvocationContext` from environment variables. This method is suitable for runtime execution within the Roboto environment.

##### Example
```python
from roboto import InvocationContext

context = InvocationContext.from_env()
```

#### Direct Initialization

##### Description
Initializes an `InvocationContext` directly by providing all required parameters. This is useful for local testing or unit tests where environment variables are not set.

##### Parameters
*   **dataset_id** (str) - The ID of the dataset.
*   **input_dir** (pathlib.Path) - The path to the input directory.
*   **invocation_id** (str) - The ID of the invocation.
*   **org_id** (str) - The ID of the organization.
*   **output_dir** (pathlib.Path) - The path to the output directory.
*   **input_data_manifest_file** (Optional[pathlib.Path]) - Path to the input data manifest file.
*   **parameters_file** (Optional[pathlib.Path]) - Path to the parameters file.
*   **secrets_file** (Optional[pathlib.Path]) - Path to the secrets file.
*   **roboto_client** (Optional[roboto.http.RobotoClient]) - An instance of the Roboto client.
*   **dry_run** (bool) - Flag for dry run mode.
*   **log_level** (Optional[str]) - The logging level.

##### Example
```python
import pathlib
from roboto import InvocationContext

context = InvocationContext(
    dataset_id="ds_XXXXXXXXXXXX",
    input_dir=pathlib.Path("/path/to/tmp/input/dir"),
    invocation_id="iv_XXXXXXXXXXXX",
    org_id="og_XXXXXXXXXXXX",
    output_dir=pathlib.Path("/path/to/tmp/output/dir")
)
```
```

--------------------------------

### GET /actions

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Queries available actions with optional filtering and pagination.

```APIDOC
## GET /actions

### Description
Searches for actions based on the provided query specification. Can search within an organization or across the public Action Hub.

### Method
GET

### Endpoint
/actions

### Parameters
#### Query Parameters
- **spec** (QuerySpecification) - Optional - Filters, sorting, and pagination settings.
- **accessibility** (Accessibility) - Optional - Search scope (Organization or Public).

### Response
#### Success Response (200)
- **actions** (list) - A list of action objects containing metadata, name, and parameters.

#### Response Example
{
  "actions": [
    {
      "name": "image_processing",
      "org_id": "roboto-public",
      "modified": "2023-10-27T10:00:00Z"
    }
  ]
}
```

--------------------------------

### Create Authentication Tokens for Roboto Devices

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Demonstrates how to generate new authentication tokens for a device. Supports custom expiry, naming, and scope configuration.

```python
device = Device.from_id("robot_001", org_id="og_abc123")
token, secret = device.create_token()
print(f"Token created: {token.token_id}")
print(f"Secret (save this!): {secret}")

token, secret = device.create_token(
    expiry_days=30, name="Monthly Upload Token", description="Token for automated monthly data uploads"
)
```

--------------------------------

### Chat Session Management

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

APIs for starting, retrieving, and managing chat sessions.

```APIDOC
## Chat Session Management

### Start a New Chat Session

#### Description
Initiates a new chat session with a starting message.

#### Method
`Chat.start(message: str)`

#### Parameters
- **message** (str) - Required - The initial message to start the conversation.

#### Request Example
```python
chat = Chat.start("Hello, Roboto!")
```

### Retrieve an Existing Chat Session

#### Description
Retrieves a previously created chat session by its unique identifier.

#### Method
`Chat.from_id(chat_id: str, roboto_client=None, load_messages=True)`

#### Parameters
- **chat_id** (str) - Required - Unique identifier for the chat session.
- **roboto_client** (Optional[RobotoClient]) - Optional - HTTP client for API communication. Uses default if None.
- **load_messages** (bool) - Optional - Whether to load the chat's messages. Defaults to True.

#### Request Example
```python
chat = Chat.from_id("chat_abc123")
```

#### Raises
- **RobotoNotFoundException** – If the chat session does not exist.
- **RobotoUnauthorizedException** – If the caller lacks permission to access the chat.

### Refresh Chat Session

#### Description
Updates the chat session with the latest messages and status from the server.

#### Method
`chat.refresh()`

#### Returns
- **Chat** - Self for method chaining.

#### Request Example
```python
chat.refresh()
```
```

--------------------------------

### GET /topics/{topic_id}

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Retrieves a specific topic record by its unique identifier.

```APIDOC
## GET /topics/{topic_id}

### Description
Fetches a topic record from the Roboto platform using its unique topic ID.

### Method
GET

### Endpoint
/topics/{topic_id}

### Parameters
#### Path Parameters
- **topic_id** (str) - Required - Unique identifier for the topic.

### Response
#### Success Response (200)
- **name** (str) - The name of the topic (e.g., '/camera/image')
- **message_count** (int) - Total number of messages in the topic
- **file_id** (str) - ID of the file containing the topic

#### Response Example
{
  "topic_id": "topic_xyz789",
  "name": "/camera/image",
  "message_count": 100
}
```

--------------------------------

### Search Files with RoboQL

Source: https://docs.roboto.ai/learn/sdk.html

Illustrates how to use the RobotoSearch client to execute RoboQL queries for filtering datasets based on tags and message path statistics.

```python
from roboto import query, RobotoSearch
roboto_search = RobotoSearch(query.client.QueryClient())

query = '''
dataset.tags CONTAINS 'boston' AND
topics[0].msgpaths[/vehicle_monitor/vehicle_speed.data].max > 20
'''

results = roboto_search.find_files(query)
```

--------------------------------

### GET /roboto/version

Source: https://docs.roboto.ai/reference/python-sdk/roboto/version/index.html

Retrieves the current version string of the Roboto AI package.

```APIDOC
## GET /roboto/version

### Description
Returns the current version of the Roboto AI package as a string.

### Method
GET

### Endpoint
/roboto/version

### Parameters
None

### Request Example
GET /roboto/version

### Response
#### Success Response (200)
- **version** (string) - The current version identifier of the package.

#### Response Example
"1.0.0"
```

--------------------------------

### GET /AISummary/text_stream

Source: https://docs.roboto.ai/reference/python-sdk/roboto/ai/summary/index.html

Streams the generated summary text as it is produced by the AI engine.

```APIDOC
## GET /AISummary/text_stream

### Description
Retrieves a generator that yields the text of the summary as it is generated by the AI service.

### Method
GET

### Endpoint
/AISummary/text_stream

### Parameters
#### Query Parameters
- **poll_interval_s** (float) - Optional - Polling interval, in seconds, to use when waiting for the summary.

### Request Example
GET /AISummary/text_stream?poll_interval_s=1.5

### Response
#### Success Response (200)
- **stream** (Generator[str, None, None]) - A stream of text segments representing the summary.

#### Error Handling
- **RobotoFailedToGenerateException** (500) - If the summary fails to generate.
- **TimeoutError** (408) - If the timeout is reached before the summary completes.
```

--------------------------------

### Update Device Properties (Python)

Source: https://docs.roboto.ai/reference/python-sdk/roboto/domain/devices/index.html

This example shows how to update a device's properties using the `update` method and an `UpdateDeviceRequest`. It demonstrates modifying metadata (like version) and tags (adding and removing). This function allows for granular control over device attributes.

```python
>>> from roboto.updates import MetadataChangeset
>>> device = Device.from_id("robot_001")
>>> updated_device = device.update(
...     UpdateDeviceRequest(
...         metadata_changeset=MetadataChangeset(
...             put_fields={"version": "2.0"}, put_tags=["updated"], remove_tags=["old"]
...         )
...     )
... )
```

--------------------------------

### Manage device tags

Source: https://docs.roboto.ai/reference/python-sdk/roboto/domain/devices/index.html

Demonstrates adding and removing tags associated with a device instance.

```python
device = Device.from_id("robot_001")
updated_device = device.put_tags(["production", "warehouse-c"])
print("production" in updated_device.tags)

updated_device = device.remove_tags(["old_tag", "deprecated"])
```

--------------------------------

### POST /uploads/begin

Source: https://docs.roboto.ai/reference/python-sdk/roboto/fs/api_operations/index.html

Initiates a batch file upload transaction for multiple files.

```APIDOC
## POST /uploads/begin

### Description
Used to initiate a multi-file upload transaction for any association type. Returns a transaction ID and upload mappings.

### Method
POST

### Endpoint
/uploads/begin

### Request Body
- **association** (object) - Required - The entity these files will be associated with.
- **resource_manifest** (dict[str, int]) - Required - Mapping of destination file paths to file sizes.
- **device_id** (str) - Optional - Identifier of the device.
- **origination** (str) - Required - Description of the upload source.

### Response
#### Success Response (200)
- **transaction_id** (str) - Unique identifier for this upload transaction.
- **upload_mappings** (dict[str, str]) - Mapping of file paths to S3 upload URIs.

### Response Example
{
  "transaction_id": "tx-999",
  "upload_mappings": {"data.csv": "s3://bucket/data.csv"}
}
```

--------------------------------

### GET /events/{event_id}

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Retrieves detailed information about a specific event by its unique identifier.

```APIDOC
## GET /events/{event_id}

### Description
Fetches the record and metadata for a specific event.

### Method
GET

### Endpoint
/events/{event_id}

### Parameters
#### Path Parameters
- **event_id** (string) - Required - The unique ID of the event.

### Response
#### Success Response (200)
- **event_id** (string) - The event ID.
- **name** (string) - The name of the event.
- **start_time** (timestamp) - Start time of the event.

#### Response Example
{
  "event_id": "evt_001",
  "name": "Sensor Trigger",
  "start_time": "2023-10-01T12:00:00Z"
}
```

--------------------------------

### Manage Datasets and Files via CLI

Source: https://docs.roboto.ai/learn/sdk.html

Demonstrates how to create a new dataset with a specific tag and upload a file to that dataset using the roboto CLI commands.

```bash
$ roboto datasets create --tag boston
$ roboto datasets upload-files -d ds_9ggdi910gntp -p scene57.bag
```

--------------------------------

### GET /orgs/{id}/users

Source: https://docs.roboto.ai/reference/python-sdk/roboto/domain/orgs/org/index.html

Retrieves all members of the organization.

```APIDOC
## GET /orgs/{id}/users

### Description
Retrieve all users who are members of this organization.

### Method
GET

### Endpoint
/orgs/{id}/users

### Response
#### Success Response (200)
- **users** (Collection) - A collection of OrgUserRecord instances.

#### Error Handling
- **RobotoUnauthorizedException**: Caller lacks permission to view members.
```

--------------------------------

### POST /devices/create

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Registers a new device within the organization.

```APIDOC
## POST /devices/create

### Description
Creates a new device record and returns the device configuration.

### Method
POST

### Endpoint
/devices/create

### Request Body
- **name** (string) - Required - Name of the device.
- **org_id** (string) - Required - Organization identifier.

### Request Example
{
  "name": "Robot_Alpha",
  "org_id": "org_99"
}

### Response
#### Success Response (200)
- **device_id** (string) - The generated device ID.

#### Response Example
{
  "device_id": "dev_abc123"
}
```

--------------------------------

### GET /devices/{device_id}/tokens

Source: https://docs.roboto.ai/reference/python-sdk/roboto/domain/devices/index.html

Retrieves all authentication tokens associated with a specific device.

```APIDOC
## GET /devices/{device_id}/tokens

### Description
Retrieve all authentication tokens associated with this device, including both active and expired tokens. Token secrets are not included.

### Method
GET

### Endpoint
/devices/{device_id}/tokens

### Response
#### Success Response (200)
- **tokens** (Sequence[Token]) - A list of token objects associated with the device.

### Errors
- **RobotoUnauthorizedException**: Caller lacks permission to list tokens.
```

--------------------------------

### Initialize and Create Datasets

Source: https://docs.roboto.ai/reference/python-sdk/roboto/domain/datasets/index.html

Demonstrates the Dataset class interface for interacting with platform data and the class method for instantiating new datasets.

```python
class Dataset:
    def __init__(self, record, roboto_client=None, file_service=None, content_mode=None):
        self.record = record

    @classmethod
    def create(cls, description=None, metadata=None, name=None, tags=None, device_id=None, caller_org_id=None, roboto_client=None, create_device_if_missing=False):
        # Implementation logic for creating a new dataset instance
        pass
```

--------------------------------

### Start and Interact with a Chat Session (Python)

Source: https://docs.roboto.ai/reference/python-sdk/roboto/ai/chat/index.html

Initiates a new chat session with Roboto's AI assistant and demonstrates basic interaction patterns, including sending text and awaiting user turns. This is useful for starting new conversations and handling synchronous interaction flows.

```python
>>> chat = Chat.start("Analyze my latest dataset")
>>> chat.await_user_turn(timeout=30.0)
>>> chat.send_text("What were the key findings?")

>>> chat = Chat.start("Analyze my latest dataset").await_user_turn()
>>> chat.send_text("What were the key findings?").await_user_turn()

>>> chat = Chat.start("Hello")
>>> while True:
...     chat.await_user_turn()
...     user_input = input("You: ")
...     if user_input.lower() == "quit":
...         break
...     chat.send_text(user_input)
```

--------------------------------

### Build and Deploy Action

Source: https://docs.roboto.ai/user-guides/creating-your-own-action.html

Details the process of building a Docker image for your action and deploying it to your Roboto account, making it available for hosted invocation and triggers. Covers handling multi-organization environments.

```APIDOC
## Build and Deploy Action

### Description
Build a Docker image for your action and deploy it to your Roboto account. This makes the action runnable on hosted compute and usable in triggers. Multi-organization users can specify the target organization.

### Method
`POST` (implied by `./scripts/deploy.sh` executing deployment actions)

### Endpoint
`/scripts/deploy.sh`

### Parameters
#### Path Parameters
None

#### Query Parameters
- `ROBOTO_ORG_ID` (string) - Environment variable to specify the target organization.
- `your-org-id` (string) - Command-line argument to specify the target organization.

### Request Example
```bash
$ ./scripts/deploy.sh
# For multi-organization users:
$ ROBOTO_ORG_ID=your-org-id ./scripts/deploy.sh
$ ./scripts/deploy.sh your-org-id
```

### Response
#### Success Response (200)
Confirmation of the Docker image build and push, and action creation or update in the Roboto account.

#### Response Example
(No specific example provided in the source text for deployment response structure.)
```

--------------------------------

### Annotate Datasets and Files with Metadata

Source: https://docs.roboto.ai/reference/python-sdk/roboto/index.html

Demonstrates how to apply tags and metadata to datasets and files. This includes tagging existing dataset files and associating metadata with new output files during an action invocation.

```python
context.dataset.put_tags(["tagged_by_action"])
context.dataset.put_metadata({"voltage_spikes_seen": 693})

# Tagging new output files
context.file_changeset_manager.put_tags(my_output_file.name, ["tagged_by_action"])
context.file_changeset_manager.put_fields(my_output_file.name, {"roboto_proficiency": "extreme"})

# Tagging existing files
existing_file = context.dataset.get_file_by_path("some_file.txt")
existing_file.put_tags(["tagged_by_action"])
existing_file.put_metadata({"roboto_proficiency": "extreme"})
```
Tokens:
Raw