Assistant Commands

This is the complete set of commands available to AI Assistants (both Chat and Workers) in your Dystr Workspaces. When you interact with an Assistant or create a Worker, these are the actions they can perform in your Workspace or the outside world - from reading files and running computations to sending emails and querying databases.

Each command executes a specific action and provides its results back to the Assistant, allowing them to make decisions and take next steps. This reference lets you understand exactly what your AI Assistants can (and cannot) do within your Workspace.

Available Commands

‍

‍

Command Reference

dystr/compute/edit

Modifies an existing compute task in your Workspace. This allows updating the name, code, or runtime of a previously created computation.

Input Required

‍

‍

What Happens

1. Locates the specified compute task in your Workspace
2. Updates the task with the new name, code, and runtime settings
3. Preserves the task's relationships and history in the Workspace

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

‍

dystr/compute/list

Lists compute tasks from your Workspace, ordered by last updated date. Returns details about each task including its execution history.

Input Required

‍

‍

What Happens

1. Queries your Workspace for compute tasks
2. Retrieves task details and their most recent executions
3. Returns up to 25 tasks, ordered by last modified date

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

‍

‍

Structure of each task in the results array:

‍

‍

dystr/compute/run

‍

Executes code in your Workspace's compute environment and creates a permanent record of the computation.

Input Required

‍

‍

What Happens

1. Creates a new compute task in your Workspace
2. Executes the provided code in your Workspace's compute environment (see Compute for details)
3. Captures all output (including console output, errors, and display data like plots)

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

‍

‍

dystr/files/exists

Checks if a file exists in your Workspace by its filename and returns its details if found.

Input Required

‍

‍

What Happens

1. Searches your Workspace for the specified file (case-insensitive)
2. If found, retrieves the file's metadata and location information
3. Returns whether the file exists and its details if found

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

‍

‍

‍

dystr/files/tts

Converts text from a Workspace file into speech. The text is extracted from the file, converted to audio using the specified voice, and saved as a new audio file in your Workspace.

Input Required

‍

‍

What Happens

1. Locates and reads the specified portion of text from the source file
2. Converts the text to speech using the chosen voice
3. Saves the audio file to the specified location in your Workspace

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

‍

‍

dystr/files/read

Reads content from a file in your Workspace. Can read either by page numbers or byte ranges, depending on the file type.

Supported File Types

• Text files (text/*)
• PDFs (application/pdf)
• JSON files (application/json)

Input Required

‍

‍

What Happens

1. Locates the specified file in your Workspace
2. Reads the requested portion of the file
3. For text files: Returns the raw text content
4. For PDFs: Returns text extracted from the specified pages

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

‍

‍

Structure of each content object in the array:

‍

‍

dystr/files/search

Searches within a specific file in your Workspace for content semantically similar to given prompts. Returns ranked excerpts ordered by similarity.

Input Required

‍

‍

‍

What Happens

1. Converts search prompts into semantic vectors
2. Searches the file for content similar to the combined prompts
3. Returns up to 25 most relevant excerpts, ranked by similarity
4. Each result includes the location and context of the match

See the Files documentation for more details on how files are stored and indexed.

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

‍

‍

Structure of each result in the array:

‍

dystr/files/write

Creates a new file in your Workspace. Cannot overwrite or append to existing files.

Input Required

‍

‍

What Happens

1. Validates the file size (must be under 100KB)
2. Creates a new file with the specified name in the given folder
3. Writes the contents to the file with the specified MIME type
4. Returns the file's ID and status

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

‍

‍

dystr/notes/create

Creates a new rich text note in your Workspace. Notes support markdown formatting and are stored with version history.

Input Required

‍

‍

ArgumentDescriptiontitleTitle for the new notecontentsNote contents in markdown format

What Happens

1. Converts the markdown content into a rich text format
2. Creates a new note with the specified title
3. Stores the content as the first revision of the note
4. Associates the note with your Workspace

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

‍

dystr/notes/list

Lists rich text notes from your Workspace, ordered by last modified date.

Input Required

‍

‍

What Happens

1. Queries your Workspace for non-removed notes
2. Orders them by last modification date
3. Returns up to 25 most recent notes

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

FieldTypeDescriptionstatusstringResult status ("okay" or "error")resultsarrayArray of note objects (see structure below)

Structure of each note in the results array:

FieldTypeDescriptionidstring | nullNote identifiertitlestring | nullTitle of the notelastModifiedstring | nullLast modification timestamp

dystr/notes/overwrite

Updates an existing rich text note in your Workspace by creating a new revision. The previous version is preserved in the note's history.

Input Required

ArgumentDescriptionidID of the note to updatecontentsNew note contents in markdown format

What Happens

1. Converts the new markdown content into rich text format
2. Creates a new revision of the note
3. Updates the note to point to the new revision
4. Preserves the previous version in the note's history

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

FieldTypeDescriptionstatusstringResult status ("okay" or "error")statusMessagestring | nullError message if status is "error"idstring | nullID of the updated notetitlestring | nullTitle of the notecontentsobjectThe processed rich text contents

See the Notes documentation for more details on the content structure of rich text notes.

dystr/notes/read

Reads the contents of a rich text note from your Workspace. Returns the most recent version of the note.

Input Required

ArgumentDescriptionidID of the note to read

What Happens

1. Locates the specified note in your Workspace
2. Retrieves the most recent revision
3. Converts the rich text content to markdown format
4. Returns the note's title and contents

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

FieldTypeDescriptionstatusstringResult status ("okay" or "error")statusMessagestringSuccess confirmation or "Note not found" erroridstring | nullID of the note that was readtitlestring | nullTitle of the note (defaults to "Untitled" if not set)contentsstring | nullThe note contents in markdown format

dystr/sqlite/query

Executes a SQL query on a SQLite database file in your Workspace. Can create new databases or modify existing ones.

Input Required

ArgumentDescriptionfileIdID of existing SQLite file (required except for CREATE)fileNameName of the SQLite file (with .sqlite extension)folderFolder to store the file in (default: "/files")querySQL query to execute (max: 1,000,000 chars)queryTypeType of query: CREATE, ALTER, SELECT, INSERT, UPDATE, DROP, DELETE, or PRAGMA

What Happens

1. For existing files: Downloads the SQLite database from your Workspace
2. For new files: Creates a new SQLite database
3. Executes the provided SQL query
4. Saves any changes back to your Workspace
5. For SELECT queries: Returns up to 25,000 bytes of results

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

FieldTypeDescriptionstatusstringResult status ("okay" or "error")statusMessagestringSuccess confirmation or error detailsidstring | nullID of the database filepathstring | nullPath to the file in Workspaceresultsarray | objectQuery results (for SELECT/PRAGMA) or execution info (for other queries)resultsTruncatedbooleanWhether results were truncated due to sizetotalResultsRowsnumberTotal number of rows in the resultresultsRowsReturnednumberNumber of rows actually returned

dystr/workspace/search

Searches across all files in your Workspace for both content and filenames that are semantically similar to your search prompts. Also returns Workspace statistics.

Input Required

ArgumentDescriptionqueryArray of search prompts (each up to 256 characters)topkNumber of results to return (max: 25)costSearch accuracy (0.0 = faster but less accurate, 1.0 = slower but more accurate)

What Happens

1. Converts search prompts into semantic vectors and combines them
2. Performs two parallel searches:
   • Content search: Finds similar text within files
   • Name search: Finds files with similar names
3. Removes duplicates and ranks results by similarity
4. Collects Workspace statistics (file count, storage used, MIME types)

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

FieldTypeDescriptionstatusstringResult status ("okay" or "error")statusMessagestring | nullError message if status is "error"querystring[]The search prompts that were usedsimilarContentResultsarrayContent matches (see structure below)similarNameResultsarrayFilename matches (see structure below)workspaceobjectWorkspace statistics (see structure below)

Structure of each content result:

FieldTypeDescriptionidstringResult identifierfileNamestringName of the filemimeTypestringMIME type of the filescorenumberSimilarity score (higher = more similar)ranknumberPosition in results (0 = most similar)textstringThe matching text excerptpagenumberPage number where match was foundcharIndexInPagenumberCharacter offset within the pagecharIndexInFilenumberCharacter offset within the entire file

Structure of each filename result:

FieldTypeDescriptionidstringResult identifierfileNamestringName of the filefilesystemPathstringFull path to the filemimeTypestringMIME type of the filemimeDescriptionstringHuman-readable description of the file typesizenumberFile size in bytesscorenumberSimilarity score (higher = more similar)ranknumberPosition in results (0 = most similar)

Structure of workspace statistics:

FieldTypeDescriptionidstringWorkspace identifiernumFilesnumberTotal number of filesstorageUsedMBnumberTotal storage used in megabytesmimeTypeCountarrayCount of files by MIME type

system/util/email

Sends an email to specified recipients within your Dystr Organization. Can only send emails to verified organization members.

Input Required

ArgumentDescriptiontoArray of recipient email addressesccArray of CC recipient email addresses (optional)bccArray of BCC recipient email addresses (optional)subjectSubject line of the emailbodyEmail content in markdown format

What Happens

1. Validates that all recipients are verified members of your organization
2. Filters out any invalid email addresses
3. Formats the email with a clear footer and sender information
4. Queues the email for delivery
5. Returns delivery status

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

FieldTypeDescriptionstatusstringResult status ("okay" or "error")statusMessagestringSuccess confirmation or error detailsresultstringDelivery status message

Important Notes

• The model will only use this command when explicitly requested by the user in the prompt
• All recipients must be verified members of your Dystr Organization
• Invalid email addresses will be filtered out
• The email will appear to come from your the Worker's email address
• Email content supports markdown formatting

system/util/fetch

Fetches and extracts text content from a webpage. Removes styling, scripts, and navigation elements to return clean, readable text.

Input Required

ArgumentDescriptionurlURL of the webpage to fetch

What Happens

1. Fetches the webpage through a proxy service
2. Removes non-content elements (styles, scripts, iframes, nav)
3. Extracts and cleans the text content:
   • Normalizes whitespace
   • Removes duplicate punctuation
   • Strips special characters
4. Returns up to 10,000 characters of the cleaned text

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

FieldTypeDescriptionstatusstringResult status ("okay" or "error")statusMessagestring | nullError message if fetch failsresultstringThe cleaned webpage textlengthnumberTotal length of the cleaned textfirstnumberNumber of characters returned (max: 10,000)skipnumberNumber of characters skipped (for pagination)

Important Notes

• Some websites may block automated fetching
• Content is limited to 10,000 characters per request
• JavaScript-rendered content may not be captured
• Returns plain text only (no HTML or formatting)

system/util/math

Evaluates simple mathematical expressions and returns the result. For more complex computations or programming logic, use compute/run instead.

Input Required

ArgumentDescriptioncalcMathematical expression to evaluate

What Happens

1. Parses the mathematical expression
2. Evaluates the result
3. Returns the computed value or error message

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

FieldTypeDescriptionstatusstringResult status ("okay" or "error")resultstringCalculated result or error message

Supported Operations

• Basic arithmetic (+, -, *, /, ^)
• Parentheses for grouping
• Common functions:
  • Trigonometric (sin, cos, tan)
  • Logarithmic (log, ln)
  • Exponential (exp, sqrt)
• Constants (pi, e)
• Unit conversions (e.g., "2 inch to cm")

Limitations

• No support for calculus operations
• No symbolic algebra
• No complex numbers
• No matrices or vectors
• No programming constructs (use dystr/compute/run instead)

Note

For more complex calculations requiring programming logic, loops, or advanced mathematical operations, use the dystr/compute/run command instead of this simple calculator.

system/util/stt

Converts speech from an audio file to text, with optional translation to English. Creates a new text file in your Workspace with the results.

Input Required

ArgumentDescriptionfileIdID of the audio file to converttranslateWhether to translate the speech to English (optional)outputFileNameName for the output file (with extension: .json, .txt, .srt, or .vtt)outputFileTypeFormat of output: json, text, srt, verbose_json, or vttoutputFolderFolder to save the output file (default: "/files")

What Happens

1. Loads the source audio file from your Workspace
2. Processes the speech using AI transcription
3. Translates to English if requested
4. Creates a new file with the transcribed text
5. Returns both the text and file information

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

FieldTypeDescriptionstatusstringResult status ("okay" or "error")statusMessagestringSuccess confirmation or error detailstextstring | nullThe transcribed textfileIdstring | nullID of the created output filefileUrlstring | nullURL to access the output filefileNamestring | nullName of the output filefileTypestring | nullFormat of the output filefolderstring | nullLocation of the output file

Output Formats

• text: Plain text transcription
• json: Basic JSON with text content
• verbose_json: JSON with timestamps and metadata
• srt: Subtitle format with timings
• vtt: Web Video Text Tracks format

system/util/tts

Converts text to speech and saves it as an audio file in your Workspace. Supports multiple voices and audio formats.

Input Required

ArgumentDescriptiontextText to convert to speech (max: 4,096 characters)voiceVoice to use: alloy, echo, fable, onyx, nova, or shimmeroutputFileNameName for the output file (with extension: .mp3, .opus, .aac, or .flac)outputFileTypeFormat of output: mp3, opus, aac, or flacoutputFolderFolder to save the output file (default: "/files")

What Happens

1. Validates the input text length
2. Processes the text using the selected voice
3. Converts to the requested audio format
4. Creates a new audio file in your Workspace
5. Returns the file information

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

FieldTypeDescriptionstatusstringResult status ("okay" or "error")statusMessagestringSuccess confirmation or error detailstextstring | nullThe input text that was convertedvoicestring | nullThe voice that was usedfileIdstring | nullID of the created audio filefileUrlstring | nullURL to access the audio filefileNamestring | nullName of the output filefileTypestring | nullFormat of the output filefolderstring | nullLocation of the output file

Important Notes

• Text must be under 4,096 characters per request
• Only use this for direct text-to-speech conversion
• For file conversion, use appropriate file conversion commands instead
• All voices are AI-generated and support English text

vendor/google/search

Performs a Google search and returns relevant web results. Supports pagination and configurable result count.

Input Required

ArgumentDescriptionquerySearch query stringresultOffsetStarting position in search results (for pagination)resultCountNumber of results to return (default: 5)

What Happens

1. Sends the search query to Google
2. Retrieves web search results
3. Extracts relevant information from each result
4. Returns formatted results with titles, URLs, and snippets

Results Provided to Assistant

After execution, these fields are injected into the Assistant's context:

FieldTypeDescriptionstatusstringResult status ("okay" or "error")querystringThe search query that was usedresultsarrayArray of search results (see structure below)

Structure of each search result:

FieldTypeDescriptiontitlestringTitle of the webpageurlstringURL of the webpagesnippetstringBrief excerpt from the page content

Important Notes

• Results are from Google's Custom Search API
• Each result includes a title, URL, and relevant text snippet
• Use pagination to access more results beyond the first set
• Results are ordered by relevance to the query
• Maximum of 10 results per request

‍

‍

‍